Elixir 1.11 and Erlang Docs

One of the nice new features in Elixir 1.11 is the ability to show the docs for Erlang functions. This helps you see things that you couldn’t see before. This is a short guide to help you get it working if you encountered any problems.

There are a couple prerequisites to make this work.

• Must use OTP 23+
• OTP 23+ must be compiled with docs

I use asdf for managing my Elixir and Erlang versions. This guide uses asdf to do this as well. If you need help getting started with asdf, check out this guide.

Let’s get it working!

Update asdf

First, make sure your asdf version is up-to-date.

asdf update

Update your asdf plugins

This uses the asdf-erlang plugin, lets make sure all the plugins are up-to-date as well.

asdf plugin-update --all

Enable compiling docs into Erlang

Following the instructions on the asdf-erlang plugin page, I did the following.

Updated my .bashrc file to include this:

export KERL_BUILD_DOCS=yes

Then, to be certain it would use this new ENV setting, I logged out of my desktop and logged back in. Then I tested it in a new console to verify it was set.

$ echo $KERL_BUILD_DOCS
yes

Install Erlang

To make sure I’m installing the latest version of Erlang, I run the following command.

asdf list-all erlang

I found “23.1.1” as the latest version for OTP 23. Install that version. This step takes some time.

$ asdf install erlang 23.1.1
asdf_23.1.1 is not a kerl-managed Erlang/OTP installation
No build named asdf_23.1.1
Downloading OTP-23.1.1.tar.gz to /home/mark/.asdf/plugins/erlang/kerl-home/archives
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   122  100   122    0     0    350      0 --:--:-- --:--:-- --:--:--   350
100 53.8M    0 53.8M    0     0  2143k      0 --:--:--  0:00:25 --:--:-- 3159k
Extracting source code
Building Erlang/OTP 23.1.1 (asdf_23.1.1), please wait...
APPLICATIONS DISABLED (See: /home/mark/.asdf/plugins/erlang/kerl-home/builds/asdf_23.1.1/otp_build_23.1.1.log)
 * jinterface     : No Java compiler found
 * odbc           : ODBC library - link check failed

Building docs...
Erlang/OTP 23.1.1 (asdf_23.1.1) has been successfully built
Installing Erlang/OTP 23.1.1 (asdf_23.1.1) in /home/mark/.asdf/installs/erlang/23.1.1...
You can activate this installation running the following command:
. /home/mark/.asdf/installs/erlang/23.1.1/activate
Later on, you can leave the installation typing:
kerl_deactivate
Cleaning up compilation products for 
Cleaned up compilation products for  under /home/mark/.asdf/plugins/erlang/kerl-home/builds
ln: failed to create symbolic link './erl_call': File exists

Erlang 23.1.1 has been installed. Activate globally with:

    asdf global erlang 23.1.1

Activate locally in the current folder with:

    asdf local erlang 23.1.1

Notice the folder where it builds? If I want or need to force a clean build, I can delete that folder. On my machine it is /home/mark/.asdf/plugins/erlang/kerl-home/builds/asdf_23.1.1.

Activate the new version either locally or globally.

asdf global erlang 23.1.1

Install Elixir

Now I can install Elixir 1.11. I need to make sure I’m installing the correct version that is intended for OTP 23. So this is the command I use.

asdf list-all elixir

Near the end of the list I find this entry: 1.11.0-otp-23. That’s the version I need.

asdf install elixir 1.11.0-otp-23

Make sure to activate this newly installed version!

asdf global elixir 1.11.0-otp-23

Now make sure you are using the correct Elixir version.

$ elixir -v
Erlang/OTP 23 [erts-11.1.1] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [hipe]

Elixir 1.11.0 (compiled with Erlang/OTP 23)

Test it out!

Let’s see if it worked! Run iex.

$ iex

In the terminal we can check for an Erlang function that we didn’t have docs for before.

iex(1)> h :erlang.binary_to_term/1

                                binary_to_term/1                                

  @spec binary_to_term(binary) :: term() when binary: ext_binary()

Returns an Erlang term that is the result of decoding binary object Binary,
which must be encoded according to the Erlang external term format
(erts:erlang#erts:erl_ext_dist).

    > Bin = term_to_binary(hello).
    <<131,100,0,5,104,101,108,108,111>>
    > hello = binary_to_term(Bin).
    hello

> WARNING
> 
> When decoding binaries from untrusted sources, consider using binary_to_term/2
> to prevent Denial of Service attacks.

See also term_to_binary/1 (erts:erlang#term_to_binary/1) and binary_to_term/2
(erts:erlang#binary_to_term/2).

iex(2)> 

It worked! We have the docs for the Erlang function in our Elixir IEx shell!

Hope this helps increase your Elixir enjoyment!