diff options
Diffstat (limited to 'doc/up_and_running.md')
| -rw-r--r-- | doc/up_and_running.md | 157 |
1 files changed, 97 insertions, 60 deletions
diff --git a/doc/up_and_running.md b/doc/up_and_running.md index 8d7861e6..bf6bc8be 100644 --- a/doc/up_and_running.md +++ b/doc/up_and_running.md @@ -1,42 +1,38 @@ -The only requirement to use CIDER is to have an nREPL server to which it may -connect. Many Clojurians favour the use of tools like Leiningen, Boot or Gradle -to start an nREPL server, but the use of one of them is not a prerequisite to -use CIDER. - -## Setting up a Clojure project (optional) - -CIDER features a command called `cider-jack-in` that will start an nREPL server -for a particular Clojure project and connect to it automatically. Most -popular Clojure project management tools are supported by default - namely -Leiningen, Boot, `clj` (`tools.deps`) and Gradle. +To use CIDER, you'll need to connect it to a running nREPL server that +is associated with your program. Most Clojure developers use standard +build tooling such as Leiningen, Boot, or Gradle, and CIDER can +automatically work with those tools to get you up and running +quickly. But those tools are not required; CIDER can connect to an +nREPL server that is already started and is managed separately. !!! Note - This functionality depends on Leiningen 2.5.2+ or Boot + CIDER will automatically work with Leiningen 2.5.2+ or Boot 2.7.0+. Older versions are not supported. -Let's create a simple Clojure project using Leiningen now. Provided you've installed -it already, all you need to do is: +There are two ways to connect CIDER to an nREPL server: -``` -$ lein new demo -``` +1. CIDER can launch an nREPL server for your project from Emacs. +2. You can connect CIDER to an already-running nREPL server, managed separately. -The two main ways to obtain an nREPL connection are discussed in the following sections of the manual. +The following sections describe each of these methods. -## Launch an nREPL server and client from Emacs +## Launch an nREPL Server From Emacs -Simply open in Emacs a file belonging to your project (like `foo.clj`) and type -<kbd>M-x</kbd> `cider-jack-in` <kbd>RET</kbd>. This will start an nREPL server -and CIDER will automatically connect to it. +If you have a Clojure project in your file system and want CIDER to +launch an nREPL session for it, simply visit a file that belongs to +the project, and type <kbd>M-x</kbd> `cider-jack-in` +<kbd>RET</kbd>. CIDER will start an nREPL server and automatically +connect to it. !!! Note - If it is a `lein`, `boot` or `tools.deps (deps.edn)` project nREPL will be - started with all dependencies loaded. Dependency auto-injection is currently - not support for Gradle projects. + If your project uses `lein`, `boot` or `tools.deps (deps.edn)`, + CIDER will automatically inject all the necessary nREPL + dependencies when it starts the server. CIDER does not currently support + dependency auto-injection for Gradle projects. -Alternatively you can use <kbd>C-u M-x</kbd> `cider-jack-in` <kbd>RET</kbd> to +Alternatively, you can use <kbd>C-u M-x</kbd> `cider-jack-in` <kbd>RET</kbd> to specify the name of a `lein`, `boot` or `tools.deps` project, without having to visit any file in it. This option is also useful if your project contains some combination of `project.clj`, `build.boot` and `deps.edn` and you want to launch @@ -46,68 +42,109 @@ a REPL for one or the other. In Clojure(Script) buffers the command `cider-jack-in` is bound to <kbd>C-c C-x (C-)j (C-)j</kbd>. -For further customizing the command line used for `cider-jack-in`, you can -change the following (all string options): +You can further customize the command line CIDER uses for `cider-jack-in` by +modifying the following string options: - * `cider-lein-global-options`, `cider-boot-global-options`, - `cider-clojure-cli-global-options`, `cider-gradle-global-options`: - these are passed to the command directly, in first position - (e.g. `-o` to `lein` enables offline mode). - * `cider-lein-parameters`, `cider-boot-parameters`, - `cider-clojure-cli-parameters`, `cider-gradle-parameters`: these - are usually tasks names and their parameters (e.g.: `dev` for - launching boot's dev task instead of the standard `repl -s wait`). +* `cider-lein-global-options`, `cider-boot-global-options`, + `cider-clojure-cli-global-options`, `cider-gradle-global-options`: + these are passed to the command directly, in first position + (e.g., `-o` to `lein` enables offline mode). +* `cider-lein-parameters`, `cider-boot-parameters`, + `cider-clojure-cli-parameters`, `cider-gradle-parameters`: these are + usually task names and their parameters (e.g., `dev` for launching + boot's dev task instead of the standard `repl -s wait`). Note that if you try to run `cider-jack-in` outside a project -directory normally you'd get a warning to confirm you really want to -do this, as more often than not you'd probably do this -accidentally. If you decide to proceed, CIDER will invoke the command -configured in `cider-jack-in-default`. This used to be `lein` prior to -CIDER 0.17 and it was switched to Clojure's CLI (`clj`) afterwards. +directory, CIDER will warn you and ask you to confirm whether you +really want to do this; more often than not, this is an accident. If +you decide to proceed, CIDER will invoke the command configured in +`cider-jack-in-default`. Prior to CIDER 0.17, this defaulted to `lein` +but was subsequently switched to `clj`, Clojure's basic startup command. !!! Tip You can set `cider-allow-jack-in-without-project` to `t` if you'd like to disable the warning displayed when jacking-in outside a project. -## Connect to a running nREPL server +## Connect to a Running nREPL Server -Go to your project's directory in a terminal and type there: +If you have an nREPL server already running, CIDER can connect to +it. For instance, if you have a Leiningen-based project, go to your +project's directory in a terminal session and type: -``` -$ lein repl +```sh +$ lein repl :headless ``` -Or for `boot`: +This will start the project's nREPL server. -``` +If your project uses `boot`, do this instead: + +```sh $ boot repl -s wait (or whatever task launches a repl) ``` It is also possible for plain `clj`, although the command is somewhat longer: -``` -$ clj -Sdeps '{:deps {cider/cider-nrepl {:mvn/version "0.18.0-SNAPSHOT"} }}' -e '(require (quote cider-nrepl.main)) (cider-nrepl.main/init ["cider.nrepl/cider-middleware"])' +```sh +$ clj -Sdeps '{:deps {cider/cider-nrepl {:mvn/version "0.19.0"}}}' -m nrepl.cmdline --middleware "[cider.nrepl/cider-middleware]" ``` -Alternatively you can start nREPL either manually or by the facilities -provided by your project's build tool (Maven, etc). +Alternatively, you can start nREPL either manually or using the facilities +provided by your project's build tool (Gradle, Maven, etc). -After you get your nREPL server running, go back to Emacs. Type there -<kbd>M-x</kbd> `cider-connect` <kbd>RET</kbd> to connect to the -running nREPL server. +After you get your nREPL server running, go back to Emacs and connect +to it: <kbd>M-x</kbd> `cider-connect` <kbd>RET</kbd>. CIDER will +prompt you for the host and port information, which should have been +printed when the previous commands started the nREPL server in your +project. !!! Tip - In Clojure(Script) buffers the command `cider-connect` is bound to <kbd>C-c M-c</kbd>. + In Clojure(Script) buffers the command `cider-connect` is bound to <kbd>C-c C-x c s</kbd>. -You can configure known endpoints used by the `cider-connect` command offered -via a completing read. This is useful if you have a list of common host/ports -you want to establish remote nREPL connections to. Using an optional label is -helpful for identifying each host. +If you frequently connect to the same hosts and ports, you can tell +CIDER about them and it will use the information to do completing +reads for the host and port prompts when you invoke +`cider-connect`. You can identify each host with an optional label. -``` +```el (setq cider-known-endpoints '(("host-a" "10.10.10.1" "7888") ("host-b" "7888"))) ``` + +## Working with Remote Hosts + +While most of the time you'd be connecting to a locally running nREPL +server, that was started manually or via `cider-jack-in-*`, there's +also the option to connect to remote nREPL hosts. For the sake of security +CIDER has the ability to tunnel a connection over SSH in such cases. +This behavior is controlled by +`nrepl-use-ssh-fallback-for-remote-hosts`: when true, CIDER will attempt to +connect via ssh to remote hosts when unable to connect directly. It's +`nil` by default. + +There's also `nrepl-force-ssh-for-remote-hosts` which will force the use +of ssh for remote connection unconditionally. + +!!! Warning + + As nREPL connections are insecure by default you're encouraged to use only SSH + tunneling when connecting to servers running outside of your network. + +There's a another case in which CIDER may optionally leverage the `ssh` command - when +trying to figure out potential target hosts and ports when you're doing `cider-connect-*`. +If `cider-infer-remote-nrepl-ports` is true, CIDER will use ssh to try to infer +nREPL ports on remote hosts (for a direct connection). That option is also set to `nil` +by default. + +!!! Note + + Enabling either of these causes CIDER to use + [TRAMP](https://www.gnu.org/software/tramp/) for some SSH operations, which parses + config files such as `~/.ssh/config` and `~/.ssh/known_hosts`. This is known to + cause problems with complex or nonstandard ssh configs. + +You can safely run `cider-jack-in-*` while working with remote files over TRAMP. CIDER +will handle this use-case transparently for you. |