From 320ba6533af24b918da615b65074f1d86f1bed00 Mon Sep 17 00:00:00 2001 From: Oleksandr Yakushev Date: Thu, 16 Jan 2025 21:25:09 +0200 Subject: [PATCH] [docs] Scrub Getting Started section --- .../ROOT/pages/about/compatibility.adoc | 130 ++---------------- .../ROOT/pages/basics/installation.adoc | 9 +- .../ROOT/pages/basics/middleware_setup.adoc | 64 ++------- .../ROOT/pages/basics/up_and_running.adoc | 114 +++++++-------- doc/modules/ROOT/pages/index.adoc | 2 +- 5 files changed, 75 insertions(+), 244 deletions(-) diff --git a/doc/modules/ROOT/pages/about/compatibility.adoc b/doc/modules/ROOT/pages/about/compatibility.adoc index f8ea78c5d..310360536 100644 --- a/doc/modules/ROOT/pages/about/compatibility.adoc +++ b/doc/modules/ROOT/pages/about/compatibility.adoc @@ -16,15 +16,17 @@ NOTE: We pay special attention to supporting whatever nREPL is bundled with the == Java -CIDER officially targets Java 8, Java 11, Java 17, Java 21 and the most recent rapid -release version (e.g. Java 22). Generally speaking, we aim -to support all Java releases that are currently officially supported -by Oracle.footnote:[You can find more information about the supported Java releases https://www.oracle.com/java/technologies/java-se-support-roadmap.html[here].] +CIDER officially targets Java 8, Java 11, Java 17, Java 21, and the most recent +non-LTS version. Generally speaking, we aim to support all Java releases that +are currently officially supported by Oracle.footnote:[You can find more +information about the supported Java releases +https://www.oracle.com/java/technologies/java-se-support-roadmap.html[here].] NOTE: The requirements for Java are pretty much ``cider-nrepl``'s requirements. -On Linux you are also required to make sure that JDK sources and javadocs are installed. -You can find example commands in xref:troubleshooting.adoc#navigation-to-jdk-sources-doesnt-work[Troubleshooting]. +While CIDER can work with +https://www.ibm.com/think/topics/jvm-vs-jre-vs-jdk[JRE], it is recommended to +use the full JDK distribution. == Clojure @@ -46,58 +48,12 @@ Currently we apply the same policy for Clojure and ClojureScript support. == Compatibility Matrix -NOTE: For a very long time CIDER and cider-nrepl were released in lock-step, but -this changed in CIDER 0.18. The actual releases diverged for the first time in -CIDER 0.23. - Below you can find the official compatibility matrix for CIDER. .Compatibility Matrix |=== | CIDER | Emacs | nREPL | cider-nrepl | Required JDK | Required Clojure -| 0.22 -| 25.1 -| 0.6 -| 0.22 -| 8 -| 1.8 - -| 0.23 -| 25.1 -| 0.6 -| 0.22 -| 8 -| 1.8 - -| 0.24 -| 25.1 -| 0.6 -| 0.24 -| 8 -| 1.8 - -| 0.25 -| 25.1 -| 0.6 -| 0.25 -| 8 -| 1.8 - -| 0.26 -| 25.1 -| 0.6 -| 0.25 -| 8 -| 1.8 - -| 1.0 -| 25.1 -| 0.6 -| 0.25 -| 8 -| 1.8 - | 1.1 | 25.1 | 0.6 @@ -105,55 +61,6 @@ Below you can find the official compatibility matrix for CIDER. | 8 | 1.8 -| 1.2 -| 26.1 -| 0.9 -| 0.27 -| 8 -| 1.8 - -| 1.3 -| 26.1 -| 0.9 -| 0.28 -| 8 -| 1.8 - -| 1.4 -| 26.1 -| 0.9 -| 0.28 -| 8 -| 1.8 - -| 1.5 -| 26.1 -| 0.9 -| 0.28 -| 8 -| 1.8 - -| 1.6 -| 26.1 -| 1.0 -| 0.29 -| 8 -| 1.8 - -| 1.7 -| 26.1 -| 1.0 -| 0.30 -| 8 -| 1.8 - -| 1.8 -| 26.1 -| 1.0 -| 0.40 -| 8 -| 1.8 - | 1.9 | 26.1 | 1.0 @@ -161,13 +68,6 @@ Below you can find the official compatibility matrix for CIDER. | 8 | 1.8 -| 1.12 -| 26.1 -| 1.0 -| 0.44 -| 8 -| 1.9 - | 1.13 | 26.1 | 1.0 @@ -175,20 +75,6 @@ Below you can find the official compatibility matrix for CIDER. | 8 | 1.9 -| 1.14 -| 26.1 -| 1.0 -| 0.47 -| 8 -| 1.10 - -| 1.15 -| 26.1 -| 1.0 -| 0.49 -| 8 -| 1.10 - | 1.16 | 26.1 | 1.0 diff --git a/doc/modules/ROOT/pages/basics/installation.adoc b/doc/modules/ROOT/pages/basics/installation.adoc index 182906cbb..8e17b377f 100644 --- a/doc/modules/ROOT/pages/basics/installation.adoc +++ b/doc/modules/ROOT/pages/basics/installation.adoc @@ -12,17 +12,14 @@ release. If you're new to Emacs you might want to go through https://www.gnu.org/software/emacs/tour/index.html[the guided tour of Emacs] and the built-in tutorial (just press kbd:[C-h t]). -CIDER officially supports Emacs 26.1+, Java 8+ and Clojure(Script) -1.8+. CIDER 0.17 (Andalucía) was the final release which supported -Java 7 and Clojure(Script) 1.7. +CIDER officially supports Emacs 26.1+, Java 8+, and Clojure(Script) 1.10+. If +you need to work with earlier versions, check +xref:about/compatibility.adoc#compatibility-matrix[compatibility matrix]. You'll also need a recent version of either the Clojure CLI tools or your favorite build tool (Leiningen, Boot, or Gradle) to be able to start CIDER via `cider-jack-in`. Generally it's a good idea to use the latest stable versions. -On Linux you are also required to make sure that JDK sources and javadocs are installed. -You can find example commands in xref:troubleshooting.adoc#navigation-to-jdk-sources-doesnt-work[Troubleshooting]. - == Installation via package.el CIDER is available on all major `package.el` community diff --git a/doc/modules/ROOT/pages/basics/middleware_setup.adoc b/doc/modules/ROOT/pages/basics/middleware_setup.adoc index f80da72d7..255eac6a5 100644 --- a/doc/modules/ROOT/pages/basics/middleware_setup.adoc +++ b/doc/modules/ROOT/pages/basics/middleware_setup.adoc @@ -4,31 +4,19 @@ NOTE: You can skip this section if you don't plan to use `cider-connect` or don't care about the advanced functionality that requires `cider-nrepl`. -Much of CIDER's functionality depends on its own https://github.com/clojure-emacs/cider-nrepl[nREPL -middleware]. Starting -with version 0.11, `cider-jack-in` (kbd:[C-c C-x (C-)j (C-)j]) -automatically injects this middleware and other dependencies as required. - -NOTE: In the past, if you were setting up CIDER, you might have had to -modify `profiles.clj` or `profile.boot`. CIDER now handles -everything automatically and you don't need to add anything -special to these files. The same is true of your `deps.edn` file and -your `build.gradle` (as of Clojurephant 0.7.0-alpha.6). - -If you prefer a standalone REPL, you will need to invoke -`cider-connect` instead of `cider-jack-in` and manually add the -dependencies to your Clojure project (explained in the following -sections). +Much of CIDER's functionality depends on its own +https://github.com/clojure-emacs/cider-nrepl[nREPL middleware]. `cider-jack-in` +(kbd:[C-c C-x (C-)j (C-)j]) automatically injects this middleware and other +dependencies as required. But if you prefer a standalone REPL, you will need to +invoke `cider-connect` instead of `cider-jack-in` and manually add the +dependencies to your Clojure project (explained in the following sections). == Setting Up a Standalone REPL === Using Leiningen -NOTE: Make sure you're using Leiningen 2.9.0 or newer, as 2.9.0 is the first -release to ship with nREPL 0.6. - Use the convenient plugin for defaults, either in your project's -`project.clj` file or in the :repl profile in `~/.lein/profiles.clj`. +`project.clj` file or in the `:repl` profile in `~/.lein/profiles.clj`. [source,clojure] ---- @@ -46,27 +34,6 @@ WARNING: Be careful not to place this in the `:user` profile, as this way CIDER' middleware will always get loaded, causing `lein` to start slower. You really need it just for `lein repl` and this is what the `:repl` profile is for. -=== Using Boot - -NOTE: Make sure you're using Boot 2.8.3 or newer, as 2.8.3 is the first -release to ship with nREPL 0.6. - -Boot users can configure the tool to include the middleware automatically in -all of their projects using a `~/.boot/profile.boot` file like so: - -[source,clojure] ----- -(require 'boot.repl) - -(swap! boot.repl/*default-dependencies* - concat '[[cider/cider-nrepl "0.52.0"]]) - -(swap! boot.repl/*default-middleware* - conj 'cider.nrepl/cider-middleware) ----- - -For more information visit https://github.com/boot-clj/boot/wiki/Cider-REPL[boot-clj wiki]. - === Using tools.deps You can add the following aliases to your deps.edn in order to launch @@ -81,7 +48,7 @@ run `cider-connect` or `cider-connect-cljs`. :cider-cljs {:extra-deps {org.clojure/clojurescript {:mvn/version "1.10.339"} cider/cider-nrepl {:mvn/version "0.52.0"} - cider/piggieback {:mvn/version "0.5.3"}} + cider/piggieback {:mvn/version "0.6.0"}} :main-opts ["-m" "nrepl.cmdline" "--middleware" "[cider.nrepl/cider-middleware,cider.piggieback/wrap-cljs-repl]"]} ---- @@ -133,11 +100,10 @@ server with CIDER's own nREPL handler. It goes without saying that your project should depend on `cider-nrepl`. -NOTE: Prior to CIDER 0.18, CIDER and cider-nrepl were always released together -and their versions had to match for things to work (e.g. CIDER 0.15 required -cider-nrepl 0.15). But as the prominence of cider-nrepl grew and many other -tools started using it, the two projects evolved separately and are no longer in -tight lock-step. Usually, any recent version of cider-nrepl should be (mostly) -compatible with a recent version of CIDER. You can check the required version of -cider-nrepl for your version of CIDER by looking at -`cider-required-middleware-version`. +NOTE: CIDER and cider-nrepl projects are co-developed, but are not released in a +lock-step — they have differing versions. Usually, any recent version of +cider-nrepl should be (mostly) compatible with a recent version of CIDER. You +can check the required version of cider-nrepl for your version of CIDER by +looking at `cider-required-middleware-version`. See also the +xref:about/compatibility.adoc#compatibility-matrix[compatibility +matrix]. diff --git a/doc/modules/ROOT/pages/basics/up_and_running.adoc b/doc/modules/ROOT/pages/basics/up_and_running.adoc index 2f0432416..e21588dd8 100644 --- a/doc/modules/ROOT/pages/basics/up_and_running.adoc +++ b/doc/modules/ROOT/pages/basics/up_and_running.adoc @@ -8,8 +8,8 @@ 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: CIDER will automatically work with Leiningen 2.9.0+ or Boot -2.8.3+. Older versions are not supported. +NOTE: CIDER will automatically work with Leiningen 2.9.0+ or a recentish +Clojure CLI. Older versions are not supported. There are two ways to connect CIDER to an nREPL server: @@ -56,20 +56,19 @@ NOTE: `cider-jack-in` is mainly designed for local development (with files on a local machine and the nREPL process running on the same machine). It does support various common remote/container scenarios, as documented later in this section. Due to the large variation of remote scenarios it cannot support all of them, so in -some cases a manual nREPL start and usage of `cider-connect` might be a better option. +some cases, a better option would be to start nREPL manually and connect to it with `cider-connect`. === Auto-Injecting Dependencies While CIDER's core functionality requires nothing more than an nREPL server, -there are many advanced features that depend on the presence of additional -nREPL middleware. In the early versions of CIDER (up to CIDER 0.11) users had -to add those dependencies themselves, which was a painful and error-prone process. -Fortunately today that's handled auto-magically when you're using `cider-jack-in`. +there are many advanced features that depend on the presence of additional nREPL +middleware. Fortunately, if you're using `cider-jack-in`, that's handled +auto-magically. If your project uses `lein`, `boot` or `tools.deps` (`deps.edn`), CIDER will automatically inject all the necessary nREPL dependencies (e.g. `cider-nrepl` or `piggieback`) when it starts the server. The injection process is extremely -simple - CIDER simply passes the extra dependencies and nREPL configuration to +simple - CIDER passes the extra dependencies and nREPL configuration to your build tool in the command it runs to start the nREPL server. Here's how this looks for `tools.deps`: @@ -77,8 +76,7 @@ this looks for `tools.deps`: TIP: If you don't want `cider-jack-in` to inject dependencies automatically, set `cider-inject-dependencies-at-jack-in` to `nil`. Note that you'll have to setup -the dependencies yourself (see xref:basics/middleware_setup.adoc[nREPL Middleware Setup]), -just as in CIDER 0.10 and older. +the dependencies yourself (see xref:basics/middleware_setup.adoc[nREPL Middleware Setup]). Normally `cider-jack-in` would inject only `cider-nrepl` and `cider-jack-in-cljs` would add `piggieback` as well. The injection mechanism is configurable and @@ -119,14 +117,43 @@ for example, if your project defaults to an older version of Clojure than that supported by the CIDER middleware. Set `cider-jack-in-auto-inject-clojure` appropriately to enable this. +=== Enabling nREPL JVMTI agent + +Since version 1.2.0, nREPL includes a native JVMTI agent which makes the eval +interrupts work properly on Java 21 and later. To enable the agent, the Java +process should be launched with `-Djdk.attach.allowAttachSelf`. CIDER will do it +automatically during jack-in if `cider-enable-nrepl-jvmti-agent` variable is set +to `t`. + +[IMPORTANT] +==== +`cider-enable-nrepl-jvmti-agent` has no effect if you start a REPL +process outside of Emacs and connect to it with `cider-connect`. In that +scenario, you have to add `-Djdk.attach.allowAttachSelf` Java property manually +through the means of the build tool. In Leiningen, add this to `project.clj`: + +[source,lisp] +---- +:jvm-opts ["-Djdk.attach.allowAttachSelf"] +---- + +In tools.deps, add this to one of the aliases that you enable with the REPL: + +[source,lisp] +---- +:aliases {:dev + {:jvm-opts ["-Djdk.attach.allowAttachSelf"] + ...}} +---- +==== + === Jacking-in without a Project If you try to run `cider-jack-in` outside a project 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. +`cider-jack-in-default` (defaults 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. @@ -185,17 +212,16 @@ with === Customizing the Jack-in Command Behavior -You can use kbd:[C-u M-x] `cider-jack-in` kbd:[RET] to -specify the exact command that `cider-jack-in` would run. -This option is very useful is you want to specify a something like a `lein` -or `deps.edn` profile. +You can use kbd:[C-u M-x] `cider-jack-in` kbd:[RET] to specify the exact command +that `cider-jack-in` would run. This option is very useful is you want to e.g. +specify extra Leiningen profiles or `deps.edn` aliases. Alternatively you can kbd:[C-u C-u M-x] `cider-jack-in` kbd:[RET], which is a variation of the previous command. This command will first prompt you for the project you want to launch `cider-jack-in` in, which is pretty handy if you're in some other directory currently. This option is also useful if your project -contains some combination of project.clj, build.boot and deps.edn and you want -to launch a REPL for one or the other. +contains some combination of `project.clj` and `deps.edn` and you want to launch +a REPL for one or the other. NOTE: The examples use only `cider-jack-in`, but this behavior is consistent for all `cider-jack-in-\*` commands. @@ -204,36 +230,6 @@ You can further customize the command line CIDER uses for `cider-jack-in` by modifying the some options. Those differ a bit between the various tools, so we'll examine them tool by tool. -==== Enabling nREPL JVMTI agent - -Since version 1.2.0, nREPL includes a native JVMTI agent which makes the eval -interrupts work properly on Java 21 and later. To enable the agent, the Java -process should be launched with `-Djdk.attach.allowAttachSelf`. CIDER will do it -automatically during jack-in if `cider-enable-nrepl-jvmti-agent` variable is set -to `t`. - -[IMPORTANT] -==== -`cider-enable-nrepl-jvmti-agent` has no effect if you start a REPL -process outside of Emacs and connect to it with `cider-connect`. In that -scenario, you have to add `-Djdk.attach.allowAttachSelf` Java property manually -through the means of the build tool. In Leiningen, add this to `project.clj`: - -[source,lisp] ----- -:jvm-opts ["-Djdk.attach.allowAttachSelf"] ----- - -In tools.deps, add this to one of the aliases that you enable with the REPL: - -[source,lisp] ----- -:aliases {:dev - {:jvm-opts ["-Djdk.attach.allowAttachSelf"] - ...}} ----- -==== - ==== Leiningen Options * `cider-lein-command` - the name of the Leiningen executable (`lein` by default) @@ -264,13 +260,6 @@ with the following alternatives NOTE: Alternatively you can use WSL (e.g. to run nREPL and Emacs there), which will likely result in a better overall development experience. -==== Boot Options - -* `cider-boot-command` - the name of the Boot executable (`boot` by default) -* `cider-boot-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`) - ==== Gradle Options * `cider-gradle-command` - the name of the Gradle executable (`./gradlew` by default) @@ -287,9 +276,9 @@ Which Jack-In Command is used is based on the project type. You can override the This allows for fine-grained control over how cider starts the nrepl-server. The precedence order for determining the Jack-In Command is: -1) :jack-in-cmd if provided as a parameter, -2) `cider-jack-in-command` if set as a directory local variable, and -3) inferred from the project type (the default). +1. `:jack-in-cmd` if provided as a parameter, +2. `cider-jack-in-command` if set as a directory local variable, and +3. Inferred from the project type (the default). ==== Setting a project-wide command @@ -339,13 +328,6 @@ $ lein repl :headless This will start the project's nREPL server. -If your project uses `boot`, do this instead: - -[source,sh] ----- -$ boot repl -s wait (or whatever task launches a repl) ----- - It is also possible for plain `clj`, although the command is somewhat longer: [source,sh] @@ -390,7 +372,7 @@ connect via ssh to remote hosts when unable to connect directly. It's 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 +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 diff --git a/doc/modules/ROOT/pages/index.adoc b/doc/modules/ROOT/pages/index.adoc index b1cb104b3..63234e4ac 100644 --- a/doc/modules/ROOT/pages/index.adoc +++ b/doc/modules/ROOT/pages/index.adoc @@ -73,7 +73,7 @@ CIDER packs plenty of features. Here are some of them (in no particular order): * `clojure.test` integration * `clojure.spec` integration * Interactive debugger -* Data Inspector +* Data inspector * Integration with Java logging frameworks * Profiling & tracing * ClojureScript support