Emacs - Elixir Setup Configuration Wiki

Wikis & Polls Wikis
, , , ,
1

This post is a wiki (feel free to hit the edit button near the bottom right of this post to add your own changes!)

This post collects concrete information about configuring Emacs to be an Elixir editing environment.

Related posts/info:

Overview

  • Alchemist - Very full featured but development has stalled, not currently recommended
  • elixir-mode - Provides the basic font-locking, indentation and navigation support
    • Should be used as the baseline of support
  • elixir-ts-mode - Provides font-locking and other basic features based on the tree-sitter grammar for elixir
    • Built into Emacs as of 29.1
    • Either elixir-ts-mode or elixir-mode may be used, but not both.
  • Elixir Language Server backend
    • elixir-ls - Elixir LSP server implementation (previously this was a fork, but it has since been reconciled)
  • Language Server Emacs Frontend (choose 1)
    • lsp-mode - General LSP (Language Server Protocol) mode, use it together with a language server implementation
    • eglot - an Emacs LSP client that stays out of your way
  • exunit.el - Simple test runner for ex_unit tests

Configuration Examples/Instructions

Installing elixir language server

Note: Elixir 1.8.2 (compiled on otp 21) and Erlang 21.3.8 are recommended if you want to work on a wide range of projects. If you use asdf, then this will be taken care of for you with a cp .release-tool-versions .tool-versions && asdf install.

  • Clone the elixir-lsp elixir-ls repository locally
    • git clone https://github.com/elixir-lsp/elixir-ls.git
  • cd elixir-ls (that you just cloned)
  • mix deps.get
  • mix elixir_ls.release

This will create a release/language_server.sh (and .bat for windows) file that you will need for the Emacs integration, so note down this path (referred to later as path-to-elixir-ls/release).

eglot Configuration

With Spacemacs

Warning: I still face issues with evil-mode and eglot in Spacemacs. If anyone manages to make it work properly, feel free to edit this guide.

  1. The elixir layer in Spacemacs does not play well with Eglot: it calls lsp-mode from the Spacemacs lsp layer. Do NOT use it. Instead, add elixir-mode in dotspacemacs-additional-packages .
  2. Add eglot in dotspacemacs-additional-packages.
  3. Add in dotspacemacs/user-config :
(require 'eglot)

;; This is optional. It automatically runs `M-x eglot` for you whenever you are in `elixir-mode`
(add-hook 'elixir-mode-hook 'eglot-ensure)

;; Make sure to edit the path appropriately, use the .bat script instead for Windows
(add-to-list 'eglot-server-programs '(elixir-mode "path-to-elixir-ls/release/language_server.sh"))
  1. If you didn’t add the optional hook, run M-x in any Elixir file to activate eglot.

Note:

  • The require instruction must come before the others.
  • If you fail to add the require instruction appropriately, eglot will randomly stop working on Emacs restart, and you will be prompted the error described in this GitHub issue.

With Vanilla Emacs

(package-install 'eglot)

;; This is optional. It automatically runs `M-x eglot` for you whenever you are in `elixir-mode`
(add-hook 'elixir-mode-hook 'eglot-ensure)

(add-to-list 'eglot-server-programs `(elixir-mode "path-to-elixir-ls/release/language_server.sh"))

Note: the package-install line must come before the add-to-list

And then, if you didn’t add the optional hook, type M-x eglot in any elixir file.

(You may also want to view this alternative configuration example which used to be recommended here)

lsp-mode Configuration

With Doom Emacs:

Elixir module documentation can be found at: https://github.com/hlissner/doom-emacs/blob/develop/modules/lang/elixir/README.org

  1. In your init.el ensure that the lsp Doom module is enabled
  2. In your init.el enable the Elixir layer with (elixir +lsp)
  3. Ensure that language_server.sh (generated from mix elixir_ls.release) is on your $PATH

With Spacemacs:

  1. Ensure that you are using the develop branch of spacemacs (your ~/.emacs.d should be on the develop branch)
    a. This is necessary as of 2019/03/03 but once 0.300 comes out it should be fine to use the stable release
  2. Set the elixir-backend variable inside your layer definitions i.e. (elixir :variables elixir-backend 'lsp)

NOTE: As of Add elixir-ls as a language backend for elixir by mpanarin · Pull Request #12668 · syl20bnr/spacemacs · GitHub alchemist is no longer included by default so excluding alchemist is no longer necessary

Add alchemist to your excluded package list dotspacemacs-excluded-packages '(alchemist) so that it is not loaded (since we’re using lsp-mode instead)

With Vanilla Emacs

  • Add lsp-mode via MELPA
    • M-x package-install [RET] lsp-mode [RET]

For both Spacemacs and Vanilla Emacs

  (use-package lsp-mode
    :commands lsp
    :ensure t
    :diminish lsp-mode
    :hook
    (elixir-mode . lsp)
    :init
    (add-to-list 'exec-path "path-to-elixir-ls/release"))

Verify that it is working by opening up a file in an elixir project (you should receive a prompt like mix.exs is not part of any project. Select action:. To which you probably want to respond Import project root. Then if there are no errors you can run M-x lsp-describe-session which will show you all of your lsp server sessions. On this screen you can press RET on the "diamond’ icon next to Capabilities to see the detected capabilities of the server.

Note: there is also GitHub - elixir-lsp/lsp-elixir.el: Emacs minor mode to interact with elixir buffers by using LSP that will manage the elixir-ls installation for you, but by installing it manually (as above) you can more easily contribute to elixir-ls.

Note: if you already have lsp-mode installed make sure it is up-to date (version 5.0 had many breaking changes)

Handy optional configuration: add '(lsp-ui-doc-enable nil t) to remove the auto-doc popups (instead you can run , h h when you want the docs). You can also run , T d to temporarilly enable/disable the popups.

ElixirLS Configuration

As mentioned in the elixir-ls README, as with VSCode you can configure the language server through entries in settings.json.

Configure emacs settings with lsp-mode

To configure through emacs (using lsp-mode), you can use code like the below.

  (defvar lsp-elixir--config-options (make-hash-table))

  (add-hook 'lsp-after-initialize-hook
            (lambda ()
              (lsp--set-configuration `(:elixirLS, lsp-elixir--config-options))))

You can use a .dir-locals.el file to set config options specific to the project. For example to disable dialyzer in one project, you’d run the above code in your init and the following in your .dir-locals.el:

  (puthash "dialyzerEnabled" :json-false lsp-elixir--config-options)

Configure emacs settings with eglot

You can use .dir-locals.el local to your project directory like so, without configuring any other explicitly configuration-related hooks for eglot:

((elixir-mode
  . ((eglot-workspace-configuration
      . ((:elixirLS . (:projectDir "subdir")))))))

DAP(Debug Adapter Protocol)
For integrated debugging, optionally enable DAP (Debug Adapter Protocol) (requires installing dap-mode from MELPA):

(require 'dap-elixir)
(dap-ui-mode)
(dap-mode)

exunit.el configuration

Note: this is recommended because the LSP protocol does not currently include running tests (so this is a good supplement to lsp-mode and eglot)

Note: Doom Emacs elixir module installs exunit.el by default

Install by cloning locally:

Add this to your emacs configuration:

  (add-to-list 'load-path "~/path_to_exunit.el")
  (require 'exunit)

Or Install via melpa:

M-x package-install [RET] exunit [RET]

Optional key binding examples with Spacemacs:

  (with-eval-after-load 'elixir-mode
    (spacemacs/declare-prefix-for-mode 'elixir-mode
      "mt" "tests" "testing related functionality")
    (spacemacs/set-leader-keys-for-major-mode 'elixir-mode
      "tb" 'exunit-verify-all
      "ta" 'exunit-verify
      "tk" 'exunit-rerun
      "tt" 'exunit-verify-single))

In Spacemacs (and I assume custom configs if you have popwin installed) you can add:

(push '("*exunit-compilation*"
        :dedicated t
        :position bottom
        :stick t
        :height 0.4
        :noselect t)
      popwin:special-display-config)

To make the exunit window always appear at the bottom and close when you press C-g

Tips and Tricks

64 Likes
2

exunit is available in melpa, so it could be installed via package-install

3 Likes
3

Thanks for putting this together! Is it recommended for Spacemacs users to add dotspacemacs-excluded-packages '(alchemist) ?

I know there was also an attempt to update Alchemist to use elixir-ls, maybe the alternative is to add an option to the spacemacs layer that would implement most of this.

2 Likes
4

Thanks! I’ve updated the instructions to include that.

1 Like
5

Your welcome! Yes it is (at least IMO), and I realized that I forgot that portion of the required configuration. Adding it to the wiki now.

There were actually two attempts by @trevoke:

But they ultimately became stale and were never merged into alchemist.el (hence not being recommended in this wiki).

It is a good idea to update the spacemacs +lang/elixir layer to switch from alchemist to a properly configured lsp-mode (which had completely slipped my mind until you mentioned it). I would assume it’s okay for +lang/elixir to depend on the lsp layer but we’ll have to see if that flies with the spacemacs team.

1 Like
6

I’m Eglot’s author. I stumbled upon this. Just wanted to say here that it is nonsense to call the section “Eglot configuration”, because Eglot is a completely different LSP client for Emacs. It’s setup is also much simpler, it’s probably just

(package-install 'eglot)
(add-to-list 'eglot-server-programs (elixir-mode "path-to-exilir-ls-executable"))

And then type M-x eglot in any elixir file.

4 Likes
7

Welcome to the forum and thanks for contributing :slight_smile:. I have restructured the sections to make it more obvious that you should use either Eglot or lsp-mode since they provide the same functionality. Looks like I initially missed eglot in the overview section as well (which I have now rectified).

Thanks! That is much simpler, so I’ve updated the instructions to that. Since I haven’t tried using eglot I just copied the configuration instructions from this other forum post which links to this gist (which it looks like you found already :smile:).

2 Likes
8

@axelson lsp-mode also have debugger support for Elixir via dap-mode. The configuration is simple as the configuration of lsp-mode:

Install dap-mode and then:

(require 'dap-elixir)
(dap-ui-mode)
(dap-mode)

9UPvMMz.png1061Ă—802 97 KB

3 Likes
9

Thanks! Added! And welcome to the forum as well :slight_smile:

1 Like
10

Hello, instructions regarding eglot half-worked for me. With OTP 21 elixir_ls server crashes, looks like it’s required OTP 20. I recompiled it and now eglot connected to the language_server (ran from release/language_server.sh (not dist folder)

EDIT: I also created the release with MIX_ENV=prod mix elixir_ls.release – not sure if that helps :slight_smile:

1 Like
11

Thanks! I committed an asdf .tool-versions file and added elixir and erlang versions to the readme. I’m using 1.6.6 with erlang 20.2.4. Updated the instructions (changed dist to release as well).

1 Like
12

Thanks to you! :wink:

13

Is this true? I am an Elixir LS user myself (in VSCode instead of Emacs, but this applies equally) and it is true that the Elixir LS repository has many open PRs waiting to be merged.
It would be great to know whether the original author has really abandoned the repository or whether he has temporally paused the work.

14

@JakeBecker is unresponsive here, at GitHub and on slack, so I think we can safely assume he has abondoned the project, if not elixir as a whole…

1 Like
15

Hi!

Sorry I’ve been unresponsive. I’ve been feeling burnt out on maintaining ElixirLS and have not been active in responding to people, but I plan to catch up on PRs soon. I’ll continue to try to fix breaking bugs quickly, but minor bugs and feature requests are going on the back-burner. I know that can be frustrating – apologies to anyone who’s tried to contribute and been unable to get ahold of me.

10 Likes
16

I’m glad to hear that! ElixirLS is an important and valued project :slight_smile:

1 Like
17

After things are moving now, would you mind getting in touch and join forces with the new elixir-lsp group on github? I’d prefer if we keep friction low and avoid a community split…

4 Likes
19

@axelson first thanks for taking the time to write this guide, I’m getting an error with eglot,

(Spacemacs) Error in dotspacemacs/user-config: Symbol’s value as variable is void: eglot-server-programs

I’m writting the configuration inside the user-config (not sure if it’s the best place for this)

  (add-to-list
   'eglot-server-programs
   '(elixir-mode  "/home/yo/Descargas/proj/elixir/elixir-ls/rel"))
  )

I’ve tried different ways

  (add-to-list
   'eglot-server-programs
   '(elixir-mode  "/home/yo/Descargas/proj/elixir/elixir-ls/rel/language_server.sh"))
  )

(add-to-list
 'eglot-server-programs
'(elixir-mode . ("sh"  "/home/yo/Descargas/proj/elixir/elixir-ls/rel/language_server.sh")))

but no one works for me…do you know which could be the issue here?..thank you

1 Like
20

hi guy, thanks to joao I can activate eglot and seems working fine

now I’m a bit stuck with the lsp-mode, I’m using spacemacs, so I add lsp to my configuration layers, after restart nothing happen, so I try the vanilla way, I add lsp-mode to my packages and the config, nothing happen again, when I open an elixir file I don’t get any alert…

I install lsp-elixir.el and now when I open an elixir file finally seems it runs…but I get an error: No LSP for elixir-mode

my lsp configuration is inside user-config and is


  (use-package lsp-mode
    :commands lsp
    :ensure t
    :diminish lsp-mode
    :hook
    (elixir-mode . lsp)
    :init
    (add-to-list 'exec-path "/home/yo/Descargas/proj/elixir/elixir-ls/rel/language_server.sh"))

is it correct?..thank you

by the way, the eglot error was that I was missing the line
(require 'eglot)

before the configuration…not sure if your guide must be update with this info

thank you

UPDATE
ok…seems that I was missing the line (choose 1) and I installed both, eglot seems run and working but I don’t get autocompletion with spacemacs, I think that autocompletion is the most required featured for me so if you guys use spacemacs and eglot, I’ll appreciate any help…thank ypu

21

I’m glad you were able to get eglot installed successfully! Also I just made the “(choose 1)” section bold so hopefully that’ll help next time :slight_smile:

My understanding of eglot is admittedly incomplete (as I use lsp-mode), but I think eglot tries to be less in your face by default and you may need to install company-mode to get auto-completion: GitHub - company-mode/company-mode: Modular in-buffer completion framework for Emacs