Elixir Tooling Integration Into Emacs
Alchemist comes with a bunch of features, which are:
- Mix integration
- Compile & Execution of Elixir code
- Inline code evaluation
- Documentation lookup
- Definition lookup
- Powerful IEx integration
- Smart code completion
- Elixir project management
- Integration with company-mode
- Installation
- Configuration
- Server
- Mix
- Compile & Execute
- Project
- Documentation lookup
- Definition lookup
- Auto-completion
- IEx
- Eval
- Testing
- Modeline
- Keymap
- Support
- Contributing
- License
package.el is the built-in package manager in Emacs.
Alchemist.el is available on the three major community maintained repositories - MELPA STABLE, MELPA and Marmalade.
You can install Alchemist with the following command:
M-x package-install [RET] alchemist [RET]
or by adding this bit of Emacs Lisp code to your Emacs initialization file
(.emacs or init.el):
(unless (package-installed-p 'alchemist)
(package-install 'alchemist))If the installation doesn't work try refreshing the package list:
M-x package-refresh-contents [RET]
Keep in mind that MELPA packages are built automatically from
the master branch, meaning bugs might creep in there from time to
time. Never-the-less, installing from MELPA is the recommended way of
obtaining Alchemist, as the master branch is normally quite stable and
"stable" (tagged) builds are released somewhat infrequently.
With the most recent builds of Emacs, you can pin Alchemist to always use MELPA Stable by adding this to your Emacs initialization:
(add-to-list 'package-pinned-packages '(alchemist . "melpa-stable") t)el-get is another popular package manager for Emacs. If you're an el-get user just do M-x el-get-install [RET] alchemist [RET].
You can install Alchemist manually by placing Alchemist on your load-path and
require ing it. Many people favour the folder ~/.emacs.d/vendor.
(add-to-list 'load-path "~/.emacs.d/vendor/alchemist.el/")
(require 'alchemist)There are some ways Alchemist can be adjusted that certain workflows operating differently.
- Use a different shell command for mix.
(setq alchemist-mix-command "/usr/local/bin/mix")- Use a different task for running tests.
(setq alchemist-mix-test-task "espec")- Use custom mix test task options.
(setq alchemist-mix-test-default-options '("--exclude pending:true")) ;; default- Use a different environment variable in which mix tasks will run.
Mix tasks could always be executed in a specific environment with the usage of C-u (universal-argument).
But if you like to change the run of Mix task permanently to a specific environment set it
through the variable.
(setq alchemist-mix-env "prod")- Use a different shell command for iex.
(setq alchemist-iex-program-name "/usr/local/bin/iex") ;; default: iex- Use a different shell command for elixir.
(setq alchemist-execute-command "/usr/local/bin/elixir") ;; default: elixir- Use a different shell command for elixirc.
(setq alchemist-compile-command "/usr/local/bin/elixirc") ;; default: elixirc- Disable the change of the modeline color with the last test run status.
(setq alchemist-test-status-modeline nil)- Use a different keybinding prefix than C-c a
(setq alchemist-key-command-prefix (kbd "C-c ,")) ;; default: (kbd "C-c a")- Disable the use of a more significant syntax highlighting on functions like
test,assert_*andrefute_*
(setq alchemist-test-mode-highlight-tests nil) ;; default t- Run the whole test suite with
alchemist-mix-testafter saving a buffer.
(setq alchemist-hooks-test-on-save t)Alchemist works as a server & client model, where the Alchemist server is written in Elixir and Emacs takes the part of the client.
For each Elixir mix project Alchemist starts an independent server in the background. If an Elixir file gets opened in a buffer, Alchemist checks if a server is running for the current project or not and starts a new one if needed. If there is no Elixir mix project found, Alchemist starts a general unique server.
An Alchemist server can be started/restarted by hand with the call of the function alchemist-server-start.
A prompt for the environment in which the server should run (default: dev) gets opened and the server will start/restart in the selected environment.
To get the server status for the current project, just call the function alchemist-server-status and a report will be displayed in the minibuffer:
Alchemist-Server-Status: [Project: /Users/tonini/Projects/ek/ Status: Connected]
| Keybinding | Description |
|---|---|
| C-c a x | Prompt for a mix command including a list of all available mix commands. alchemist-mix |
| C-c a t | Run the whole elixir test suite. alchemist-mix-test |
| C-c a r | Rerun the last test that was run by alchemist. alchemist-mix-rerun-last-test |
| C-c a m t f | Run alchemist-mix--test-file with the FILENAME. alchemist-mix-test-file |
| C-c a m t b | Run the current buffer through mix test. alchemist-mix-test-this-buffer |
| C-c a m t . | Run the test at point. alchemist-mix-test-at-point |
| C-c a m c | Compile the whole elixir project. alchemist-mix-compile |
| C-c a m r | Runs the given file or expression in the context of the application. alchemist-mix-run |
Mix tasks could also be executed in a specific environment with the usage of C-u (universal-argument).
Default environments are prod, dev and test. Mix environments
The Mix tasks running in a separate alchemist-mix-mode, in which the following keybindings are available:
| Keybinding | Description |
|---|---|
| q | Quit *mix* buffer window |
| i | Send an input to the current running mix task process. |
| Keybinding | Description |
|---|---|
| C-c a c c | Compile the current buffer with the elixirc command. alchemist-compile-this-buffer |
| C-c a c f | Compile the given FILENAME with the elixirc command. alchemist-compile-file |
| C-c a c b | Run a custom compile command with elixirc. alchemist-compile |
| Keybinding | Description |
|---|---|
| C-c a e e | Run the current buffer through elixir command. alchemist-execute-this-buffer |
| C-c a e f | Run elixir command with the given FILENAME. alchemist-execute-file |
| C-c a e b | Run a custom execute command with elixir. alchemist-execute |
| Keybinding | Description |
|---|---|
| C-c a p f | Open project test directory and list all test files. alchemist-project-find-test |
| C-c a p s | Toggle between a file and its tests in the current window. alchemist-project-toggle-file-and-tests |
| C-c a p o | Toggle between a file and its tests in other window. alchemist-project-toggle-file-and-tests-other-window |
| C-c a p t | Run the tests related to the current file.. alchemist-project-run-tests-for-current-file |
There is the alchemist-help-minor-mode for a complete fully functional
interface to the Elixir documentation. The alchemist-help-minor-mode uses the
same functions like Elixir's IEx.
What does that mean? It means no matter which Elixir version is currently
installed on the system, the documentation you get by alchemist is the same
IEx would deliver.
| Keybinding | Description |
|---|---|
| C-c a h h | Run a custom search. alchemist-help |
| C-c a h i | Look through search history. alchemist-help-history |
| C-c a h e | Run alchemist-help with the expression under the cursor. (example: is_binary or Code.eval_string). If there is a currently marked region this will be used as the search term alchemist-help-search-at-point |
| C-c a h r | Open a buffer with a refcard of alchemist bindings. alchemist-refcard |
Inside of the alchemist-help-minor-mode (*elixir help* buffer) the key ? will
open a keymap summary in the minibuffer with the following functionality:
You're always be able to continue to search inside the *elixir help* buffer.
| Keybinding | Description |
|---|---|
| q | Quit *elixir help* buffer window |
| e | alchemist-help-search-at-point |
| m | alchemist-help-search-marked-region |
| s | alchemist-help |
| h | alchemist-help-history |
| ? | alchemist-help-minor-mode-key-binding-summary |
With the function alchemist-goto-definition-at-point, which is bound to M-., you
can jump to module and function definitions. If you want to jump back, just use M-, which calls alchemist-goto-jump-back.
You also can jump to the current selected completion candidate with just hit the same key as normally, M-..
By default you're able to jump to definitions of your own mix project codebase and dependencies. But if you would like to also jump to Elixir and Erlang source code you need to tell Alchemist where it can find the source code of Elixir and Erlang.
For that purpose there're two variables you can set:
(setq alchemist-goto-erlang-source-dir "/path/to/erlang/source/")(setq alchemist-goto-elixir-source-dir "/path/to/elixir/source/")If you inside an Erlang file and the erlang-mode is enabled you can't use alchemist-goto-jump-back anymore.
But if you would like to use it also inside the erlang-mode just setup the following custom hook:
(defun custom-erlang-mode-hook ()
(define-key erlang-mode-map (kbd "M-,") 'alchemist-goto-jump-back))
(add-hook 'erlang-mode-hook 'custom-erlang-mode-hook)
There is the function alchemist-goto-list-symbol-definitions which lets you jump to a specific module, function or macro definitions in the current file.
Alchemist users are advised to use company-mode to enable auto-completion inside of Elixir source code.
Alchemist enables a company-mode elixir backend by default if company-mode is installed.
There are the same keybindings for documentation lookup and definition opening for the selected candidate available like company-mode provides.
C-h and <f1> for documentation lookup for the current selected candidate. C-w to jump to the definition of the current selected candidate.
Alchemist provides a REPL buffer, connected to an
Elixir IEx subprocess.
To start an IEx process just run M-x alchemist-iex-run
To start an IEx process in the context of an Elixir project (iex -S mix) just run M-x alchemist-iex-project-run
To start a custom IEx process with additional arguments (like: iex --sname custom) just use the
universal-argument C-u
before run M-x alchemist-iex-run
| Keybinding | Description |
|---|---|
| C-c a i i | Start an IEx process. alchemist-iex-run |
| C-c a i p | Start an IEx process with mix (iex -S mix). alchemist-iex-project-run |
| C-c a i l | Sends the current line to the IEx process. alchemist-iex-send-current-line |
| C-c a i c | Sends the current line to the IEx process and jump to the buffer.. alchemist-iex-send-current-line-and-go |
| C-c a i r | Sends the marked region to the IEx process. alchemist-iex-send-region |
| C-c a i m | Sends the marked region to the IEx process and jump to the buffer. alchemist-iex-send-region-and-go |
| C-c a i b | Compiles the current buffer in the IEx process. alchemist-iex-compile-this-buffer |
When Alchemist finds company-mode it enables if for completion inside the IEx process buffer.
Alchemist comes with the functionality to evaluate code inside the buffer.
| Keybinding | Description |
|---|---|
| C-c a v l | Evaluate the Elixir code on the current line. alchemist-eval-current-line. |
| C-c a v k | Evaluate the Elixir code on the current line and insert the result. alchemist-eval-print-current-line. |
| C-c a v j | Get the Elixir code representation of the expression on the current line. alchemist-eval-quoted-current-line. |
| C-c a v h | Get the Elixir code representation of the expression on the current line and insert the result. alchemist-eval-print-quoted-current-line. |
| C-c a v o | Evaluate the Elixir code on marked region. alchemist-eval-region. |
| C-c a v i | Evaluate the Elixir code on marked region and insert the result. alchemist-eval-print-region. |
| C-c a v u | Get the Elixir code representation of the expression on marked region. alchemist-eval-quoted-region. |
| C-c a v y | Get the Elixir code representation of the expression on marked region and insert the result. alchemist-eval-print-quoted-region. |
| C-c a v q | Evaluate the Elixir code in the current buffer. alchemist-eval-buffer. |
| C-c a v w | Evaluate the Elixir code in the current buffer and insert the result. alchemist-eval-print-buffer. |
| C-c a v e | Get the Elixir code representation of the expression in the current buffer. alchemist-eval-quoted-buffer. |
| C-c a v r | Get the Elixir code representation of the expression in the current buffer and insert result. alchemist-eval-print-quoted-buffer. |
Alchemist comes with an minor mode for testing which will be enabled by default inside *_test.exs files.
| Keybinding | Description |
|---|---|
| C-c , s | Run the test at point. alchemist-mix-test-at-point |
| C-c , v | Run all tests in the current file. alchemist-mix-test-this-buffer |
| C-c , a | Run the whole elixir test suite. alchemist-mix-test |
| C-c , f | Run all tests of a specific file alchemist-mix-test-file |
| C-c , n | Jump to the next test inside the current file. alchemist-test-mode-jump-to-next-test |
| C-c , p | Jump to the previous test inside the current file alchemist-test-mode-jump-to-previous-test |
The tests are reported in the alchemist-test-report-mode, which have the following keybindings:
| Keybinding | Description |
|---|---|
| M-n | Jump to the next error in the test report. alchemist-test-next-result |
| M-p | Jump to the previous error in the test report. alchemist-test-previous-result |
| M-N | Jump to the next stacktrace file in the test report. alchemist-test-next-stacktrace-file |
| M-P | Jump to the previous stacktrace file in the test report. alchemist-test-previous-stacktrace-file |
| C-c C-k | Interrupt the current running report process. alchemist-report-interrupt-current-process |
| q | Close the test report window |
By default the status of alchemist-mix-test, alchemist-compile etc will be
represented via the colorized mode-name. In our case that will be the elixir-mode.
If you don't like that just set the alchemist-test-status-modeline variable
via (setq alchemist-test-status-modeline nil) or M-x customize-group [RET] alchemist-test
Alchemist comes with a default keymap.
The the default prefix keybinding is C-c a
You find and overview of all the key-bindings on the Alchemist-Refcard.
There is also a refcard for usage inside Emacs, which gets dynamically generated with the current adjusted keybindings.
If you use the keybinding i on a specific row, it will call describe-function on that function.
Just M-x alchemist-refcard RET
If you hit any problems, please first ensure that you are using the latest version of this code, and that you have updated your packages to the most recent available versions. If you still experience problems, you can find me on IRC channels #elixir-lang and #emacs-elixir under the nickname tonini.
Contributions are very welcome!
- Fork alchemist.el
- Create a topic branch -
git checkout -b my_branch - Push to your branch -
git push origin my_branch - Send me a pull-request for your topic branch
- That's it!
Copyright © 2014-2015 Samuel Tonini and contributors.
Distributed under the GNU General Public License, version 3