Doom Emacs - Elixir Wiki

A wiki for Doom Emacs

Doom is a configuration framework for GNU Emacs. It focuses on performance and customizability. It can be a foundation for your own config or a resource for Emacs enthusiasts to learn more about our favorite OS.

Doom Emacs is considered the fastest Emacs ‘distribution’ at the expense of being more ‘hardcore’ than some alternatives (for example: Spacemacs)

This wiki will provide guides and tips to get you up and running with Emacs for Elixir development.

https://github.com/hlissner/doom-emacs - Official Doom Emacs site
https://github.com/tonini/alchemist.el - Alchemist Elixir site
https://github.com/elixir-lsp/elixir-ls - Elixir LS site


Prelude

There is no such thing as a ‘Doom Emacs’ app. You just run regular Emacs which loads the configuration generated by Doom using doom sync.

Doom Emacs configures Emacs by default uses keybindings like Vim. If you are not familiar with Vim, it’s best to have some basic understanding about the keys, actions and motions.

For now, just remember that

  • you can save a file using :w (press colon, press w)
  • SPC means spacebar
  • You can search in a file with /
  • You can search in all files of a project with SPC /
  • You can search and start a lot of functionality using SPC : In the list you will also see which keys are bound to certain actions. For example type SPC : find.

Installation

1) Emacs and Doom Emacs installation

Instructions how to install Doom Emacs can be found at it’s own Getting Started Guide.


2) Enabling Elixir support

To enable the support for Elixir, you have to adapt the ~/.doom.d/init.yml. You can easily open this file in Emacs by pressing SPC f p and selecting it from the list.

Uncomment the Elixir recipe by removing the ;; from the beginning of the line:

elixir

tip: Search for elixir using SPC /, put the cursor on the ; press x to remove the character, then save with :w

Important
Every time you make changes to the init.el file or packages.el file, you have to run ~/.emacs.d/bin/doom sync in the terminal and restart Emacs. This synchronizes your config with Doom Emacs. It ensures that needed packages are installed, orphaned packages are removed and necessary metadata correctly generated.

tip: you can also press SPC h r r to initiate doom sync && emacs restart in the background.


3) Optional: Enabling Elixir Language Server support

The Elixir Language Server provides a server that runs in the background, providing Emacs information about Elixir Mix projects. This enables code completion and more.

3a. Install the LSP server

First we install Elixir LSP by cloning the repo, compiling the package and creating a release.

git clone https://github.com/elixir-lsp/elixir-ls.git ~/.elixir-ls
cd ~/.elixir-ls
mix deps.get
mix compile
mix elixir_ls.release -o release

Next we add elixir-ls to the PATH variable. This is usually done in ~/.bashrc or ~/.zshrc. Add this line:

export PATH=$PATH:$HOME/.elixir-ls/release

When you start Emacs from another environment (for example: the desktop GUI) the shell environment variables are not available. Doom can sync shell environment variables to Emacs environment variables in ~/.emacs.d/.local/env. Run:

~/.emacs.d/bin/doom env

3b. Enable LSP in Doom Emacs

To enable LSP mode when editing Elixir files, you have to do open init.el again using SPC f p and change the line of elixir to

(elixir +lsp)

Also uncomment lsp in the tools section. I recommend to also enable the LSP peak function so the line looks like:

(lsp +peek) ; M-x vscode

Now sync the configuration and restart Emacs (using SPC h r r) and it should be working as expected. That is: once you open an Elixir file the LSP server will be started and you get code completion etc. As the LSP server has to index your project code first, it might take up to 15 minutes before it kicks in.

WARNING: Using Credo with LSP
If you use Credo, you should add this snippet in config.el so it works together with LSP:

;; Workaround to enable running credo after lsp
(defvar-local my/flycheck-local-cache nil
(defun my/flycheck-checker-get (fn checker property)
  (or (alist-get property (alist-get checker my/flycheck-local-cache))
      (funcall fn checker property)))
(advice-add 'flycheck-checker-get :around 'my/flycheck-checker-get)
(add-hook 'lsp-managed-mode-hook
          (lambda ()
            (when (derived-mode-p 'elixir-mode)
              (setq my/flycheck-local-cache '((lsp . ((next-checkers . (elixir-credo)))))))
            ))

Optional: Configuration snippets

This snippet or parts of it can be placed in config.el without installing additional packages.

;; Configure elixir-lsp
;; replace t with nil to disable.
(setq lsp-elixir-fetch-deps nil)
(setq lsp-elixir-suggest-specs t)
(setq lsp-elixir-signature-after-complete t)
(setq lsp-elixir-enable-test-lenses t)

;; Compile and test on save
(setq alchemist-hooks-test-on-save t)
(setq alchemist-hooks-compile-on-save t)

;; Disable popup quitting for Elixir’s REPL
;; Default behaviour of doom’s treating of Alchemist’s REPL window is to quit the
;; REPL when ESC or q is pressed (in normal mode). It’s quite annoying so below
;; code disables this and set’s the size of REPL’s window to 30% of editor frame’s
;; height.
(set-popup-rule! "^\\*Alchemist-IEx" :quit nil :size 0.3)

;; Do not select exunit-compilation window 
(setq shackle-rules '(("*exunit-compilation*" :noselect t))
      shackle-default-rule '(:select t))

;; Set global LSP options
(after! lsp-mode (
setq lsp-lens-enable t
lsp-ui-peek-enable t
lsp-ui-doc-enable nil
lsp-ui-doc-position 'bottom
lsp-ui-doc-max-height 70
lsp-ui-doc-max-width 150
lsp-ui-sideline-show-diagnostics t
lsp-ui-sideline-show-hover nil
lsp-ui-sideline-show-code-actions t
lsp-ui-sideline-diagnostic-max-lines 20
lsp-ui-sideline-ignore-duplicate t
lsp-ui-sideline-enable t))

Installing packages
This is done differently than native Emacs and Spacemacs!

Package management Doom Emacs

9 Likes

I am just about done with Emacs but want to try Doom as my last stop. Curious what you will show us.

1 Like

curious, what turned you away from emacs?

1 Like

Thousand paper cuts, really. One distro is slow, another has severely different keybinds (why oh why don’t they all use Evil mode’s keys and stop trying to be so hopelessly individualistic?!), another has almost nothing to it (“hacker-oriented” :weary:).

And there’s ALWAYS something spitting warnings or errors, and every now and then it just hangs for 5 seconds…

I really give up. I am not in the “hacker culture” at the moment and haven’t been for the last 10 or so years so I seriously give up. I’ll have to muscle through a few detailed and long VIM tutorials but at least I’ll have transferable knowledge almost everywhere and will just go with NeoVim / LunarVim.

Emacs is just not for me. It keeps crapping the bed. And believe me when I tell you, I got very obsessive at one point and managed to mostly tame it. But it still has subtle failure modes (on macOS more, apparently, and I am there) and they burned me out.

3 Likes

Ah I see. Thanks for sharing your experience! I’ve been only solely been inside VSCode and did a bit of vim for terminal editing, and have been trying to get into emacs - but it’s been hard trying to leave the comforts of VSCode.

1 Like

If you’re emacs-curious I honestly think the best way to start with it is to consider it a tinkering project for a while. Stay with VSCode for your work/programming, and either play with Emacs on the side for fun, or use it as your terminal editor. I think you can’t truly get a good feel for what makes Emacs unique without writing some elisp, and trying to do that while adjusting to a tricked-out Emacs-as-IDE for serious programming work may be an exercise in frustration.

I personally would also start with either vanilla Emacs or a simple starter kit (eg. https://github.com/bbatsov/prelude) rather than having the foundation obscured by too many added layers. Move on to Doom or spacemacs once you’ve decided you want Emacs as your main workspace.

But that’s no more than my personal approach, and I don’t even use it these days (somewhat counter-culturally, I like GUIs).

2 Likes

I replied above before noticing this thread is tagged as a ‘wiki’. I’m wondering if the transient chatter needlessly dilutes @BartOtten’s thoughtful work above. I assume the intent of the wiki tag is to keep threads primarily as an editable reference.

1 Like

Wish somebody told me that 20 years ago. :frowning: I wouldn’t have even started using Emacs.

2 Likes

General tips/shortcuts:
SPC s o open the search options. You can highlight something and directly search many places for that. I use this a lot for searching errors.

Alt + x (or the Meta key on your keyboard) will allow you to search for any command.

Ctrl + b bring the list of buffers so you can pick and chose.

A lot of the Vim binds will work the same here, so if you’re familiar with them, your brain won’t freeze much.

Also, magit and org are really 2 wonderful tools.

If I think of more stuff I’ll update this.

2 Likes

My tinkering threshold has reduced by orders of magnitude. I did most of my emacs tinkering back when I ran FreeBSD f/t on a laptop …

That said, I now wonder if my advice to @mekusigjinn was a bit anachronistic. Depending on your personality re such things, you could probably just get started with a fully fledged Doom/spacemacs setup, and later cognise your way down the layers as much or little as you wish.

3 Likes

I’m definitely going to be back in the “hacker” / “tinkerer” camps but not soon. Too much crap to sort out in personal life AND work, it’s seriously a huge luxury to tinker.

Too many people providing tools never stop to consider that there are folks like myself who want to download the whole thing in one piece, go through a 5 to 30 minutes tutorial and be done with it.

3 Likes

The OP is a good intro to setting up emacs.

One other thing I would add is this. If you are getting some warning like “lsp is scanning 5000 files in current project…consider adding to ignore list”, try adding this to config.el:

(setq lsp-file-watch-ignored
      '(".idea" ".ensime_cache" ".eunit" "node_modules"
        ".git" ".hg" ".fslckout" "_FOSSIL_"
        ".bzr" "_darcs" ".tox" ".svn" ".stack-work"
        "build" "_build" "deps" "postgres-data")
      )

That’s just some files/directories that LSP will now ignore.

Note that in doom emacs you can easily get to config.el with key command SPC f P (doom/open-private config). You could have found this key command using ALT+X and typing, e.g. “doom config”.

Once you’re up and running, there are some really really nice things you can do.

For example, in an elixir file you should be in elixir-mode and you can use this key command: SPC m t b to run all tests in project (it runs mix test).

This is pretty cool - it will run the tests in a “compilation window” which you can browse like a normal buffer. Press enter on any file:line_number stacktrace to jump to that part of the code.

One final thing - the main reason I still love emacs so much. Press SPC u. This is a special command called universal-argument. It lets you add arbitrary arguments after any command.

For example, if you do SPC u SPC m t b then it will bring up a prompt where you can enter extra args, e.g. “–failed --max-failures=1”. This will then run mix test --failed --max-failures=1.

You can re-run the previous test command with SPC m t r.

This can all be done headlessly, because emacs can run in the shell.

4 Likes

I can relate to that. My resistance is almost the opposite - I have too much time available (out of work) and could easily let it all slip out of my hands with off-topic tinkering. Anyway VS Code sounds like a good fit for your situation. I’ve never before used a serious editor that ‘just worked’ to the extent it does.

Still for others reading - emacs is great, and fascinating, and rewards a bit of time spent.

1 Like

It’s not anachronistic at all, thank you for your replies. I know there’s going to be a point in my life where I don’t want to deal with VSCode (with its updates and fate being at the hands of a corporate giant, etc etc) - and deal with a product that I can use as a well-oiled tool to grow old with, and eventually I am hoping emacs would be that. Maybe not for full-blown Elixir development, but maybe I hope I can be emacs-literate enough so that my other tasks in the computer could be through emacs! :slight_smile:

2 Likes

As my girlfriend has just released son 3.0 and I want to finalize a lib for this young man I postpone further extension of the OP for a week. Just so you all know I don’t forget this topic, just have to limit my investments :slight_smile:

7 Likes

Congratulations :partying_face: :baby: :tada:

Well done on the Wiki, it’s looking great so far :023:

Congrats on release 3.0 :smiley:

1 Like

Thanks for writing this up!

I’d recommend changing (setq lsp-elixir-fetch-deps t) to (setq lsp-elixir-fetch-deps nil)

We’ve already made that change in the ElixirLS defaults and I plan to make a PR to change the default in lsp-mode as well (although anyone is free to beat me to it!)

The reason is that the auto fetch does has a race condition that can cause the dependency to get “stuck” and always appear downloading.

4 Likes

@BartOtten Looks like the alchemist elixir website has been taken over by domain squatters. You could use the github page instead… GitHub - tonini/alchemist.el: Elixir Tooling Integration Into Emacs

3 Likes

@BartOtten I suggest adding something to the OP, after you say it might take up to 15 minutes:

You can press SPC b B to bring up a list of “buffers”. Type “lsp” to filter for the lsp-log buffer. Pres enter to visit this buffer and you will see the output from the LSP compilation. Press G to go to the end of this buffer to see latest compilation logs.

3 Likes