README.md: split off fallback server installation docs

These now go in doc/server-installation.md
OmniSharp · Jul 21, 2017 · ea1857a · ea1857a
1 parent ab4c6bb
commit ea1857a
Show file tree

Hide file tree

Showing 4 changed files with 106 additions and 91 deletions.
diff --git a/README.md b/README.md
@@ -10,95 +10,14 @@ works in the background.
 
 See [omnisharp-emacs Features](doc/features.md).
 
-## Installation of the omnisharp-roslyn server application
-This emacs package requires the [omnisharp-roslyn][] server program.
-
-You have three options here:
-  * You can use M-x `omnisharp-install-server` to install omnisharp-server binary automatically. 
-
-    * *NOTE: On Windows, this command requires PowerShell v5+ to be installed
-      – see [omnisharp-emacs#275](https://github.com/OmniSharp/omnisharp-emacs/issues/275).*
-
-    * *NOTE 2*: On macOS and Linux omnisharp server binary requires
-      [mono](http://www.mono-project.com/) to be installed on your system.
-
-  * Download and extract server binaries
-    manually and then point `omnisharp-server-executable-path` variable to the binary.
-
-  * Build the server yourself from the source. 
-    Building instructions are detailed in 
-    [omnisharp-roslyn building page](https://github.com/OmniSharp/omnisharp-roslyn#building).
-
-### Manual installation on macOS with brew
-<pre>
-brew install omnisharp/omnisharp-roslyn/omnisharp-mono
-</pre>
-
-Then you need to set the `omnisharp-server-executable-path`:
-
-```lisp
-(setq omnisharp-server-executable-path "/usr/local/bin/omnisharp")
-```
-
-### Manual installation on Linux
-Extract binary from [omnisharp-roslyn releases page](https://github.com/OmniSharp/omnisharp-roslyn/releases).
-
-Then you need to set the `omnisharp-server-executable-path`:
-
-```lisp
-(setq omnisharp-server-executable-path "<path-to-server-wrapper-script>")
-```
-
-### Manual installation on Windows (non-Cygwin)
-Use binary from [omnisharp-roslyn releases page](https://github.com/OmniSharp/omnisharp-roslyn/releases).
-
-*NOTE: For the moment you HAVE to use the `omnisharp-win-x86-net46.zip` bundle as -x64- one makes emacs
-to crash in `src/w32proc.c:w32_executable_type`.* See https://github.com/OmniSharp/omnisharp-emacs/issues/315
-
-Then you need to set the `omnisharp-server-executable-path` the path
-to where you have extracted server file, e.g.:
-
-```lisp
-(setq omnisharp-server-executable-path "C:\\Bin\\omnisharp-roslyn\\OmniSharp.exe")
-```
-
-### Manual installation on windows (with Cygwin)
-Use binary from [omnisharp-roslyn releases page](https://github.com/OmniSharp/omnisharp-roslyn/releases):
-
- - https://github.com/OmniSharp/omnisharp-roslyn/releases/download/v1.9-beta22/omnisharp-win-x64-net46.zip
-
-If I use omnisharp-roslyn net46 directly, omnisharp-emacs hangs when interacting via stdio.
-This seems to be a difference in how console IO is handled in newer versions of .Net.
-My workaround involves using a wrapper written in C#:
-
-https://gist.github.com/corngood/d982c3c21c016127a2f1600dc895c000
-
-You need to compile the wrapper against an older .net framework (3.5 seems to work). A simple way to use the wrapper is to create a shell script like:
-
-```shell
-#!/bin/sh
-set -e
-[path-to-wrapper-exe] "$(cygpath -w [path-to-omnisharp-exe])" "$@"
-```
-
-If you name this script OmniSharp, and put it in your path (e.g. /usr/local/bin/OmniSharp),
-`omnisharp-emacs` should find it and launch omnisharp correctly.
-Or you can point to it directly in your init.el
-
-```lisp
-(setq omnisharp-server-executable-path "/home/<username>/bin/OmniSharp")
-```
-
-## Package Installation and Configuration
+## Package Installation
 This package requires Emacs 24.3 and above. It has been tested on
 Ubuntu, Windows 7+ and on macOS.
 
 ### Installation on Spacemacs
 Add `csharp` layer to `dotspacemacs-configuration-layers` on
 your `.spacemacs` file. `csharp-mode` and `omnisharp` packages
-will get installed automatically on restart for you.
-
- * TODO: as of 2017-02-19 `csharp` layer installs non-roslyn version of omnisharp-emacs.
+will get installed automatically for you on restart.
 
 ### Installation on Regular Emacs
 To install, use [MELPA][].
@@ -120,16 +39,34 @@ something like this to `csharp-mode-hook` on your `init.el`:
 (add-hook 'csharp-mode-hook 'omnisharp-mode)
 ```
 
-## Configuration and commands available
-To start it, use `M-x omnisharp-start-omnisharp-server RET`.
-The command will ask you for a solution file or a directory 
-you want to code in.
+For autocompletion via company mode you will also need this in your `init.el`:
+
+```
+(eval-after-load
+ 'company
+ '(add-to-list 'company-backends 'company-omnisharp))
+```
 
+## Server Installation
+This emacs package requires the [omnisharp-roslyn][] server program.
 Emacs will manage connection to the server as a subprocess.
 
+The easiest way to install the server is to invoke 
+`M-x omnisharp-install-server` and follow instructions on minibufer.
+
+If that fails (or you feel adventurous) please see [installing omnisharp server](doc/server-installation.md) 
+on how to install the server manually.
+
+## Configuration
+To start using omnisharp-emacs, start the server with `M-x omnisharp-start-omnisharp-server RET`.
+The command will ask you for a project or solution file you want to code in.
+
 You will probably want to create a custom configuration for accessing
-omnisharp-emacs in your normal coding sessions. There is an example
-configuration for evil-mode included in the project.
+omnisharp-emacs in your normal coding sessions.
+Usually all this customization goes in your custom `csharp-mode-hook` in your `init.el`.
+
+There is also an example configuration for evil-mode included in the project,
+please see `doc/example-config-for-evil-mode.el`.
 
 * * * * *
 

diff --git a/doc/server-installation.md b/doc/server-installation.md
@@ -0,0 +1,78 @@
+# Installation of the omnisharp-roslyn server application
+This emacs package requires the [omnisharp-roslyn](https://github.com/OmniSharp/omnisharp-roslyn) server program.
+
+You have three options here:
+  * You can use M-x `omnisharp-install-server` to install omnisharp-server binary automatically. 
+
+    * *NOTE: On Windows, this command requires PowerShell v5+ to be installed
+      – see [omnisharp-emacs#275](https://github.com/OmniSharp/omnisharp-emacs/issues/275).*
+
+    * *NOTE 2*: On macOS and Linux omnisharp server binary requires
+      [mono](http://www.mono-project.com/) to be installed on your system.
+
+  * Download and extract server binaries
+    manually and then point `omnisharp-server-executable-path` variable to the binary.
+
+  * Build the server yourself from the source. 
+    Building instructions are detailed in 
+    [omnisharp-roslyn building page](https://github.com/OmniSharp/omnisharp-roslyn#building).
+
+## Manual installation on macOS with brew
+<pre>
+brew install omnisharp/omnisharp-roslyn/omnisharp-mono
+</pre>
+
+Then you need to set the `omnisharp-server-executable-path`:
+
+```lisp
+(setq omnisharp-server-executable-path "/usr/local/bin/omnisharp")
+```
+
+## Manual installation on Linux
+Extract binary from [omnisharp-roslyn releases page](https://github.com/OmniSharp/omnisharp-roslyn/releases).
+
+Then you need to set the `omnisharp-server-executable-path`:
+
+```lisp
+(setq omnisharp-server-executable-path "<path-to-server-wrapper-script>")
+```
+
+## Manual installation on Windows (non-Cygwin)
+Use binary from [omnisharp-roslyn releases page](https://github.com/OmniSharp/omnisharp-roslyn/releases).
+
+*NOTE: For the moment you HAVE to use the `omnisharp-win-x86-net46.zip` bundle as -x64- one makes emacs
+to crash in `src/w32proc.c:w32_executable_type`.* See https://github.com/OmniSharp/omnisharp-emacs/issues/315
+
+Then you need to set the `omnisharp-server-executable-path` the path
+to where you have extracted server file, e.g.:
+
+```lisp
+(setq omnisharp-server-executable-path "C:\\Bin\\omnisharp-roslyn\\OmniSharp.exe")
+```
+
+## Manual installation on windows (with Cygwin)
+Use binary from [omnisharp-roslyn releases page](https://github.com/OmniSharp/omnisharp-roslyn/releases):
+
+ - https://github.com/OmniSharp/omnisharp-roslyn/releases/download/v1.9-beta22/omnisharp-win-x64-net46.zip
+
+If I use omnisharp-roslyn net46 directly, omnisharp-emacs hangs when interacting via stdio.
+This seems to be a difference in how console IO is handled in newer versions of .Net.
+My workaround involves using a wrapper written in C#:
+
+https://gist.github.com/corngood/d982c3c21c016127a2f1600dc895c000
+
+You need to compile the wrapper against an older .net framework (3.5 seems to work). A simple way to use the wrapper is to create a shell script like:
+
+```shell
+#!/bin/sh
+set -e
+[path-to-wrapper-exe] "$(cygpath -w [path-to-omnisharp-exe])" "$@"
+```
+
+If you name this script OmniSharp, and put it in your path (e.g. /usr/local/bin/OmniSharp),
+`omnisharp-emacs` should find it and launch omnisharp correctly.
+Or you can point to it directly in your init.el
+
+```lisp
+(setq omnisharp-server-executable-path "/home/<username>/bin/OmniSharp")
+```
diff --git a/omnisharp-server-actions.el b/omnisharp-server-actions.el
@@ -20,7 +20,7 @@ to use server installed via `omnisharp-install-server`.
           (progn
             (message "omnisharp: No omnisharp server could be found.")
             (message (concat "omnisharp: Please use M-x 'omnisharp-install-server' or download server manually"
-                             " as detailed in https://github.com/OmniSharp/omnisharp-emacs/blob/master/README.md#installation-of-the-omnisharp-roslyn-server-application"))
+                             " as detailed in https://github.com/OmniSharp/omnisharp-emacs/blob/master/doc/server-installation.md"))
             nil)))))
 
 (defun omnisharp--do-server-start (path-to-project server-executable-path)

diff --git a/omnisharp-server-installation.el b/omnisharp-server-installation.el
@@ -107,7 +107,7 @@ See https://github.com/OmniSharp/omnisharp-emacs/issues/315"
                     (message (format "omnisharp: server was installed to \"%s\"; you can now do M-x 'omnisharp-start-omnisharp-server' "
                                      executable-path))
                   (message (concat "omnisharp: server could not be installed automatically. "
-                                   "Please check https://github.com/OmniSharp/omnisharp-emacs/blob/master/README.md#installation-of-the-omnisharp-roslyn-server-application for instructions."))))))
+                                   "Please check https://github.com/OmniSharp/omnisharp-emacs/blob/master/doc/server-installation.md for instructions."))))))
       (message (format "omnisharp: server is already installed (%s)"
                        expected-executable-path)))))