= Installation
:experimental:

The canonical way to install CIDER is via `package.el` (Emacs's built-in package
manager).

NOTE: You can install CIDER using other package managers as well, but this is
outside the scope of this guide.

== Prerequisites

You'll need to have Emacs installed, preferably the latest stable
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 28.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 your favorite build tool (Clojure CLI,
Leiningen, or Gradle) to be able to start CIDER via `cider-jack-in`. Generally
it's a good idea to use the latest stable versions.

== Installation via package.el

CIDER is available on all major `package.el` community
maintained repos -
https://elpa.nongnu.org[NonGNU ELPA],
http://stable.melpa.org[MELPA Stable]
and http://melpa.org[MELPA].

NOTE: NonGNU ELPA is one of Emacs's standard repositories and is enabled by
default on Emacs 28+. You'll have to setup MELPA and MELPA Stable yourselves if
you want to use them.

You can install CIDER with the following command:

kbd:[M-x package-install <RET> cider <RET>]

or by adding this bit of Emacs Lisp code to your Emacs initialization file
(`.emacs` or `init.el`):

[source,lisp]
----
(unless (package-installed-p 'cider)
  (package-install 'cider))
----

If the installation doesn't work try refreshing the package list:

kbd:[M-x package-refresh-contents <RET>]

It's important to note that MELPA packages are built automatically
from the `master` branch, and that means you'll be right on the
leading edge of development. This has upsides and downsides; you'll
see new features first, but you might experience some bugs from
time to time. Nevertheless, installing from MELPA is a reasonable way
to obtain CIDER. The `master` branch is normally quite stable
and serious regressions there are usually fixed quickly.

TIP: If you don't want to (or can't) wait for MELPA to rebuild CIDER,
you can easily build and install an up-to-date MELPA package locally yourself. Check out
http://emacsredux.com/blog/2015/05/10/building-melpa-packages-locally/[this article]
for details on the subject.

If you have concerns about living on the leading edge of CIDER
development, you can always pin CIDER to use NonGNU ELPA or MELPA Stable like this:

[source,lisp]
----
;; pin to NonGNU ELPA
(add-to-list 'package-pinned-packages '(cider . "nongnu") t)

;; pin to MELPA Stable
(add-to-list 'package-pinned-packages '(cider . "melpa-stable") t)
----

NOTE: CIDER has dependencies (e.g. `queue` & `seq`) that are only available in the
https://elpa.gnu.org/[GNU ELPA repository]. It's the only package repository
enabled by default in Emacs and you should not disable it!

== Installation via use-package

`use-package` can be used to install CIDER via the ``package.el``'s repositories
https://elpa.nongnu.org[NonGNU ELPA], http://stable.melpa.org[MELPA Stable] and http://melpa.org[MELPA].

If you wanted to install the version of CIDER which is what is to be found in
the `master` branch, declare the following in your Emacs initialization file
(`.emacs` or `init.el`):

[source,lisp]
----
(use-package cider
  :ensure t)
----

However, if you wanted to be a bit more conservative and only use the stable
releases of CIDER, you'd declare the following:

[source,lisp]
----
(use-package cider
  :ensure t
  :pin melpa-stable)
----

After placing one of the above s-expressions, evaluate it, for it to take effect
by entering: kbd:[C-x C-e].

For further configuration options with `use-package`, consult the
official https://github.com/jwiegley/use-package[use-package repository].

== Manual Installation

Installing CIDER manually is discouraged unless you plan to work with CIDER's
codebase. The manual installation is relatively involved as it requires manual
installation of the dependencies. Check out the section
xref:contributing/hacking.adoc[Hacking on CIDER] for more details.
