spacemacs/layers/+lang/elixir/README.org

#+TITLE: Elixir layer

#+TAGS: general|layer|multi-paradigm|programming

[[file:img/elixir.png]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
  - [[#layer][Layer]]
  - [[#choosing-a-backend][Choosing a backend]]
    - [[#feature-comparison-in-backends][Feature comparison in backends]]
- [[#configuration][Configuration]]
  - [[#flycheck][Flycheck]]
    - [[#credo][Credo]]
    - [[#dogma][Dogma]]
    - [[#mix-compile][mix compile]]
  - [[#language-server-protocol][Language server protocol]]
  - [[#debugger][Debugger]]
- [[#key-bindings][Key bindings]]
  - [[#alchemist][Alchemist]]
    - [[#refcard][Refcard]]
    - [[#help][Help]]
    - [[#mix][Mix]]
    - [[#project][Project]]
    - [[#evaluation-in-place][Evaluation in place]]
    - [[#repl-interactions][REPL interactions]]
    - [[#tests][Tests]]
    - [[#compile][Compile]]
    - [[#execute][Execute]]
    - [[#code-definition-jump][Code Definition Jump]]
    - [[#hex-packages][Hex (packages)]]
    - [[#macro-expand][Macro expand]]
    - [[#formatting][Formatting]]
    - [[#debugging][Debugging]]
  - [[#lsp][LSP]]
    - [[#debugging-1][Debugging]]

* Description
This layer adds support for [[http://elixir-lang.org/][Elixir]].

[[https://github.com/tonini/alchemist.el][Alchemist]] brings the Elixir tooling to Emacs and comes with a bunch of features.
[[https://github.com/emacs-lsp/lsp-mode][Lsp-mode]] brings IDE like features following Language Server Protocol, through [[https://github.com/JakeBecker/elixir-ls][elixir-ls]]

As Alchemist is no longer maintained, elixir-ls is a preferred solution, even though it has less features at the moment.

** Features:
- Powerful IEx integration
- Mix integration
- Compile & Execution of Elixir code
- Inline code evaluation
- Documentation lookup
- Definition lookup
- Smart code completion
- Elixir project management
- Integration with [[http://company-mode.github.io/][company-mode]]
- Flycheck support for mix compile
- Flycheck support for [[https://github.com/rrrene/credo][credo]]
- Flycheck support for test results
- Interactive debugger using [[https://github.com/emacs-lsp/dap-mode][dap-mode]]

* Install
** Layer
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =elixir= to the existing =dotspacemacs-configuration-layers= list in this
file.

** Choosing a backend
To choose a default backend set the layer variable =elixir-backend=:

#+BEGIN_SRC elisp
  (elixir :variables elixir-backend 'alchemist)
#+END_SRC

Alternatively the =lsp= backend will be automatically chosen if the layer =lsp=
is used and you did not specify any value for =elixir-backend=.

Backend can be chosen on a per project basis using directory local variables
(files named =.dir-locals.el= at the root of a project), an example to use the
=lsp= backend:

#+BEGIN_SRC elisp
  ;;; Directory Local Variables
  ;;; For more information see (info "(emacs) Directory Variables")

  ((elixir-mode (elixir-backend . lsp)))
#+END_SRC

*Note:* you can easily add a directory local variable with ~SPC f v d~.

The available options are:

| symbol     | description       |
|------------+-------------------|
| 'alchemist | Default           |
| 'lsp       | elixir-ls package |

*** Feature comparison in backends

| features                           | Alchemist | Lsp |
|------------------------------------+-----------+-----|
| Powerful IEx integration           | yes       | no  |
| Mix integration                    | yes       | no  |
| Compile & Execution of Elixir code | yes       | no  |
| Inline code evaluation             | yes       | no  |
| Documentation lookup               | yes       | yes |
| Definition lookup                  | yes       | yes |
| Smart code completion              | yes       | yes |
| Elixir project management          | yes       | no  |
| Integration with =company-mode=    | yes       | yes |
| Flycheck support                   | yes       | yes |

* Configuration
** Flycheck
*Note:* since flycheck checkers are slow, the checks are enabled only at save
time.

*** Credo
You need to install [[https://github.com/rrrene/credo][credo]] into your project. For this, add the following snippet
to dependencies of your project (in file =mix.exs=):

#+BEGIN_SRC elixir
  {:credo, "~> 0.5", only: [:dev, :test]}
#+END_SRC

Then run in your shell:

#+BEGIN_SRC shell
  $ mix deps.get
#+END_SRC

For more info about mix [[http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html][see]].

You can tell flycheck-credo to call credo with the '--strict' argument.

#+BEGIN_SRC elisp
  (setq flycheck-elixir-credo-strict t)
#+END_SRC

*** Dogma
In order to lint your code, you also need to install [[https://github.com/lpil/dogma][dogma]] into your project.
For this, add the following snippet to the dependencies in your =mix.exs= file:

#+BEGIN_SRC elixir
  {:dogma, "~> 0.1", only: [:dev]}
#+END_SRC

Then run in your shell:

#+BEGIN_SRC shell
  $ mix deps.get
#+END_SRC

*** mix compile
*Important:*

Elixir compiler is based on macros and can execute arbitrary during compilation.
Therefore Spacemacs disable flycheck compilation checker by default.

To enable flycheck support for compilation errors *globally* the variable
=elixir-enable-compilation-checking= can be set explicitly to =t= in your
dotfile but it is not recommended to do so because of the limitation described
above.

Instead you should use directory local variables in order to enable the flycheck
checker only for certain projects. Directory local variables are stored in a
file named =.dir-locals.el= usually at the root of a project. To easily add a
directory local variable use the key binding ~SPC f v d~ then choose the
=elixir-mode= and the variable name =elixir-enable-compilation-checking= with a
value of t. The result is a new file =.dir-locals.el= with the following
contents:

#+BEGIN_SRC elisp
  ;;; Directory Local Variables
  ;;; For more information see (info "(emacs) Directory Variables")

  ((elixir-mode
    (elixir-enable-compilation-checking . t)))
#+END_SRC

Spacemacs marks the variable =elixir-enable-compilation-checking= as safe so
Emacs won't ask you if the variable is safe whenever an elixir file is opened.

Remember that you can verify the flycheck checkers status with ~SPC e v~.

** Language server protocol
The =lsp= backend uses [[https://github.com/JakeBecker/elixir-ls][elixir-ls]] as its language server implementation
Clone the project to your system and follow the building instructions [[https://github.com/JakeBecker/elixir-ls#building-and-running][here]]
Or the lsp-elixir [[https://github.com/elixir-lsp/elixir-ls][fork]], which is actively maintained as well

set the =elixir-ls-path= to the release folder of =elixir-ls= in .spacemacs =dotspacemacs/user-config=

#+BEGIN_SRC elisp
  (setq elixir-ls-path "*path to folder*/elixir-ls/release")
#+END_SRC

or in the layer definition

#+BEGIN_SRC elisp
  (elixir :variables elixir-backend 'lsp elixir-ls-path "*path to folder*/elixir-ls/release")
#+END_SRC

by default =elixir-ls-path= is equal to ="~/elixir-ls/release"=

** Debugger
For =lsp= backend only

=lsp= backend supports debugging of your elixir project through [[https://github.com/emacs-lsp/dap-mode][dap]]
simply follow [[https://github.com/syl20bnr/spacemacs/tree/develop/layers/%2Btools/dap#layer-installation][dap layer]] installation and configuration instructions
as well as make sure to read this elixir-ls [[https://github.com/elixir-lsp/elixir-ls#debugger-support][debugger support note]]

* Key bindings
** Alchemist
*** Refcard
You find and overview of all the key bindings on the [[https://github.com/tonini/alchemist.el/blob/master/doc/alchemist-refcard.pdf][Alchemist-Refcard]].

*** Help

| Key binding | Description                         |
|-------------+-------------------------------------|
| ~SPC m h :~ | Run custom search for help          |
| ~SPC m h h~ | Show help of the current expression |
| ~SPC m h H~ | Toggle through search history       |
| ~SPC m h r~ | Show help for current region        |

*** Mix

| Key binding | Description                                                |
|-------------+------------------------------------------------------------|
| ~SPC m m :~ | Prompt for a =mix= command                                 |
| ~SPC m m c~ | Compile the whole application                              |
| ~SPC m m h~ | Show help for a specific =mix= command                     |
| ~SPC m m x~ | Run the given expression in the Elixir application context |

*** Project

| Key binding | Description                                                |
|-------------+------------------------------------------------------------|
| ~SPC m g t~ | Toggle between a file and its tests in the current window. |
| ~SPC m g T~ | Toggle between a file and its tests in other window.       |

*** Evaluation in place

| Key binding | Description                             |
|-------------+-----------------------------------------|
| ~SPC m e b~ | Evaluate buffer                         |
| ~SPC m e B~ | Evaluate buffer and insert result       |
| ~SPC m e l~ | Evaluate current line                   |
| ~SPC m e L~ | Evaluate current line and insert result |
| ~SPC m e r~ | Evaluate region                         |
| ~SPC m e R~ | Evaluate region and insert result       |

*** REPL interactions

| Key binding | Description                                                     |
|-------------+-----------------------------------------------------------------|
| ~SPC m s c~ | Compiles the current buffer in the IEx process.                 |
| ~SPC m s i~ | Start an =iex= inferior process                                 |
| ~SPC m s I~ | Start an IEx process with mix (=iex -S mix=)                    |
| ~SPC m s l~ | Send current line to REPL buffer                                |
| ~SPC m s L~ | Send current line to REPL buffer and focus it in =insert state= |
| ~SPC m s m~ | Reloads the module in the current buffer in your IEx process    |
| ~SPC m s r~ | Send region to REPL buffer                                      |
| ~SPC m s R~ | Send region to REPL buffer and focus it in =insert state=       |

*** Tests

| Key binding | Description                                                                           |
|-------------+---------------------------------------------------------------------------------------|
| ~SPC m g t~ | Open the test file for current buffer                                                 |
| ~SPC m t a~ | Run all the tests                                                                     |
| ~SPC m t b~ | Run all the tests from current buffer                                                 |
| ~SPC m t B~ | Run all the tests from current file; if test file not found, after confirm, create it |
| ~SPC m t f~ | Choose test file to run                                                               |
| ~SPC m t t~ | Run test under point                                                                  |
| ~SPC m t r~ | Rerun the last test                                                                   |
| ~SPC m t n~ | Jump to next test                                                                     |
| ~SPC m t N~ | Jump to previous test                                                                 |
| ~SPC m t s~ | Run stale tests (~mix test --stale~)                                                  |
| ~SPC m t R~ | Toggle test report window                                                             |
| ~SPC m t F~ | Open project test directory and list all test files.                                  |

*** Compile

| Key binding | Description                                        |
|-------------+----------------------------------------------------|
| ~SPC m c :~ | Run a custom compile command with =elixirc=        |
| ~SPC m c b~ | Compile the current buffer with elixirc. =elixirc= |
| ~SPC m c f~ | Compile the given filename with =elixirc=          |

*** Execute

| Key binding | Description                                |
|-------------+--------------------------------------------|
| ~SPC m x :~ | Run a custom execute command with =elixir= |
| ~SPC m x b~ | Run the current buffer through =elixir=    |
| ~SPC m x f~ | Run =elixir= with the given filename       |

*** Code Definition Jump

| Key binding | Description                                        |
|-------------+----------------------------------------------------|
| ~SPC m g g~ | Jump to the elixir expression definition at point. |
| ~SPC m .~   | Jump to the elixir expression definition at point. |
| ~SPC m g b~ | Pop back to where ~SPC m g g~ was last invoked.    |
| ~SPC m ,~   | Pop back to where ~SPC m g g~ was last invoked.    |
| ~SPC m g n~ | Jump to next symbol definition                     |
| ~SPC m g N~ | Jump to previous symbol definition                 |
| ~SPC m g j~ | Choose which symbol definition to jump to          |

*** Hex (packages)
Hex is the package manager for Elixir & Erlang ecosystem. See [[https://hex.pm]].

| Key binding | Description                                              |
|-------------+----------------------------------------------------------|
| ~SPC m X i~ | Display Hex package information for the package at point |
| ~SPC m X r~ | Display Hex package releases for the package at point    |
| ~SPC m X R~ | Display Hex package releases for a certain package       |
| ~SPC m X I~ | Display Hex package info for a certain package           |
| ~SPC m X s~ | Search for Hex packages                                  |

*** Macro expand

| Key binding | Description                                                                       |
|-------------+-----------------------------------------------------------------------------------|
| ~SPC m o l~ | Macro expand once the Elixir code on the current line                             |
| ~SPC m o L~ | Macro expand once the Elixir code on the current line and insert the result       |
| ~SPC m o k~ | Macro expand completely the Elixir code on the current line                       |
| ~SPC m o K~ | Macro expand completely the Elixir code on the current line and insert the result |
| ~SPC m o i~ | Macro expand once the Elixir code on marked region                                |
| ~SPC m o I~ | Macro expand once the Elixir code on marked region once and insert the result     |
| ~SPC m o r~ | Macro expand completely the Elixir code on marked region                          |
| ~SPC m o R~ | Macro expand completely the Elixir code on marked region and insert the result    |

*** Formatting

| Key binding | Description               |
|-------------+---------------------------|
| ~SPC m =~   | Format the current buffer |

*** Debugging

| Key binding | Description               |
|-------------+---------------------------|
| ~SPC m d b~ | Toggle IEx.pry breakpoint |

** LSP
You find and overview of all the key bindings on the [[https://github.com/syl20bnr/spacemacs/tree/develop/layers/%2Btools/lsp#key-bindings][lsp layer description]].

*** Debugging
Using the =dap= layer you'll get access to all the DAP key bindings, see the
complete list of key bindings on the [[https://github.com/syl20bnr/spacemacs/tree/develop/layers/%2Btools/dap#key-bindings][dap layer description]].