Skip to content

Commit

Permalink
[docs] Scrub Getting Started section (clojure-emacs#3771)
Browse files Browse the repository at this point in the history
  • Loading branch information
@alexander-yakushev @dakra
alexander-yakushev authored and dakra committed Jan 20, 2025
1 parent 027ad3a commit a135714
Show file tree
Hide file tree
Showing 5 changed files with 77 additions and 246 deletions.
130 changes: 8 additions & 122 deletions doc/modules/ROOT/pages/about/compatibility.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -46,149 +48,33 @@ 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
| 0.25
| 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
| 0.41
| 8
| 1.8

| 1.12
| 26.1
| 1.0
| 0.44
| 8
| 1.9

| 1.13
| 26.1
| 1.0
| 0.44
| 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
Expand Down
9 changes: 3 additions & 6 deletions doc/modules/ROOT/pages/basics/installation.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
64 changes: 15 additions & 49 deletions doc/modules/ROOT/pages/basics/middleware_setup.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]
----
Expand All @@ -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
Expand All @@ -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]"]}
----
Expand Down Expand Up @@ -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].
Loading

0 comments on commit a135714

Please sign in to comment.