branch: elpa/cider
commit e95d2affbbdb1b37348202b07510f62e56281abf
Author: Oleksandr Yakushev <a...@bytopia.org>
Commit: GitHub <nore...@github.com>
[docs] Scrub Getting Started section (#3771)
---
doc/modules/ROOT/pages/about/compatibility.adoc | 130 ++-------------------
doc/modules/ROOT/pages/basics/installation.adoc | 9 +-
.../ROOT/pages/basics/middleware_setup.adoc | 64 +++-------
doc/modules/ROOT/pages/basics/up_and_running.adoc | 118 ++++++++-----------
doc/modules/ROOT/pages/index.adoc | 2 +-
5 files changed, 77 insertions(+), 246 deletions(-)
diff --git a/doc/modules/ROOT/pages/about/compatibility.adoc
b/doc/modules/ROOT/pages/about/compatibility.adoc
index f8ea78c5da..310360536b 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 182906cbb1..8e17b377fc 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 f80da72d7b..255eac6a5f 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 2f04324164..49d88233a1 100644
--- a/doc/modules/ROOT/pages/basics/up_and_running.adoc
+++ b/doc/modules/ROOT/pages/basics/up_and_running.adoc
@@ -3,13 +3,13 @@
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
+build tooling such as tools.deps, Leiningen, 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: 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 recent
+tools.deps. 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
+If your project uses `lein` 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 b1cb104b32..63234e4acc 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
