Building Your First Erlang App Using Rebar3

Image: http://www.rebar3.org/

Rebar3 is a build tool and package management tool for Erlang. Creating and publishing your Erlang packages is simple thanks to Rebar3 with its plugin to Hex. Let’s make a simple “hello world” package, and feel free to play along at home!

Download Rebar3

Download the latest version here: http://www.rebar3.org/.

curl -O https://s3.amazonaws.com/rebar3/rebar3

Use chmod to make it executable, then add it to your environment variable PATH.

chmod +x rebar3
export PATH=$PATH:your-current-directory

Your first Erlang app

Start with the command rebar3 new to generate a new project from the built-in template called app. In this example we are creating a project called myapp. Other available templates are: release, lib, plugin, escript, cmake.

$ rebar3 new app myapp
===> Writing myapp/src/myapp_app.erl
===> Writing myapp/src/myapp_sup.erl
===> Writing myapp/src/myapp.app.src
===> Writing myapp/rebar.config
===> Writing myapp/.gitignore
===> Writing myapp/LICENSE
===> Writing myapp/README.md

Code for your package is placed within the src directory.

$ cd myapp
$ tree
.
├── LICENSE
├── README.md
├── rebar.config
└── src
    ├── myapp.app.src
    ├── myapp_app.erl
    └── myapp_sup.erl

The convention is to have one .app.src file to define your app as an OTP application, since Rebar3 only handles OTP structured projects. Looks familiar? The file is also Erlang. Check out the full reference to see what it can contain.

$ cat src/myapp.app.src 
{application, 'myapp',
 [{description, "An OTP application"},
  {vsn, "0.1.0"},
  {registered, []},
  {mod, {'myapp_app', []}},
  {applications,
   [kernel,
    stdlib
   ]},
  {env,[]},
  {modules, []}
 ]}.

The code inside of src/myapp_app.erl is pretty bare bones. It just makes sure that you can start and stop your Erlang app:

$ cat src/myapp_app.erl 
-module('myapp_app').
-behaviour(application).
-export([start/2, stop/1]).
start(_StartType, _StartArgs) ->
    'myapp_sup':start_link().
stop(_State) ->
    ok.

Rebar3 uses a file called rebar.config to specify addition metadata, such as dependencies. There are lots of fields rebar.config can contain. To see them all check out the full sample.

$ cat rebar.config 
{erl_opts, [debug_info]}.
{deps, []}.

Now let’s use Rebar3 to start an Erlang shell with your app and the dependencies in the path. Run application:start(myapp). to verify that your app is correctly loaded.

$ rebar3 shell
===> Verifying dependencies...
===> Compiling myapp
Erlang R16B03-1 (erts-5.10.4) [source] [64-bit] [smp:8:8] [async-threads:0] [hipe] [kernel-poll:false]
Eshell V5.10.4  (abort with ^G)
1> application:start(myapp).
ok
2> application:stop(myapp). 
ok
3> 
=INFO REPORT==== 29-Jun-2015::16:14:10 ===
    application: myapp
    exited: stopped
    type: temporary

To learn about the command rebar3 shell, Fred Hebert (author of Learn You Some Erlang) wrote a nice post about it here.

Erlang Packages

Before you start

Image: https://hex.pm/

We need to install a plugin called rebar3_hex in order to use fetch and install Erlang packages from Hex.pm, the Erlang/Elixir package manager. Simply add the following line to your rebar.config file. (You need Erlang version OTP 17.4 and above)

{plugins, [rebar3_hex]}. 

Then run the commend: rebar3 update to enable the plugin.

$ rebar3 update
===> Fetching jsx ({pkg,<<"jsx">>,<<"2.6.1">>})
===> Fetching ssl_verify_hostname ({pkg,<<"ssl_verify_hostname">>,
                                           <<"1.0.5">>})
===> Fetching rebar3_hex ({pkg,<<"rebar3_hex">>,<<"0.6.0">>})
===> Compiling ssl_verify_hostname
===> Compiling jsx
===> Compiling rebar3_hex
===> Updating package index...

If you want to avoid this step every time you create a new Erlang app, add the entry to a global rebar.config and place it at:

~/.config/rebar3/rebar.config

Finding Erlang packages

The search command lets you find remote Erlang packages published on Hex.pm. You can use regular expression characters in your query:

$ rebar3 hex search cowboy
cloudi_service_http_cowboy
cowboy

Installing packages

Rebar3 can download and install the Erlang packages and any necessary dependencies. Add the application names to the deps entry in your rebar.config file, then run the command: rebar3 compile. In this example we are trying to use two Erlang packages called cowboy and meck.

{deps, [cowboy, meck]}.
$ rebar3 compile
===> Verifying dependencies...
===> Fetching ranch ({pkg,<<"ranch">>,<<"1.0.0">>})
===> Fetching meck ({pkg,<<"meck">>,<<"0.8.2">>})
===> Fetching cowlib ({pkg,<<"cowlib">>,<<"1.0.1">>})
===> Fetching cowboy ({pkg,<<"cowboy">>,<<"1.0.0">>})
===> Compiling cowlib
===> Compiling ranch
===> Compiling meck
===> Compiling cowboy
===> Compiling myapp

Want to install a specific version of an Erlang package? Write the application name and the version in a tuple. You can browse the available versions of a package at Hex home page.

{deps, [{cowboy, “1.0.2”}, {meck, "0.8.3"}]}.

Listing Installed packages

The rebar3 deps command shows your locally installed packages:

$ rebar3 deps
cowboy (locked package 1.0.0)
meck (locked package 0.8.2)

Uninstalling packages

To uninstall a package, you have to remove it from the rebar.config file first, then use the command: rebar3 unlock. Here we removed the package meck from our list.

$ rebar3 unlock
$ rebar3 deps
cowboy (locked package 1.0.0)

Further Reading

rebar3

(This story is also posted on https://medium.com/erlang-central/building-your-first-erlang-app-using-rebar3-25f40b109aad)