Building Your First Erlang App Using Rebar3

Erlang Central
Jun 20, 2016 · 4 min read

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:

curl -O

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/
===> Writing myapp/rebar.config
===> Writing myapp/.gitignore
===> Writing myapp/LICENSE
===> Writing myapp/

Code for your package is placed within the src directory.

$ cd myapp
$ tree
├── rebar.config
└── 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/ 
{application, 'myapp',
[{description, "An OTP application"},
{vsn, "0.1.0"},
{registered, []},
{mod, {'myapp_app', []}},
{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 
-export([start/2, stop/1]).
start(_StartType, _StartArgs) ->
stop(_State) ->

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).
2> application:stop(myapp).
=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


We need to install a plugin called rebar3_hex in order to use fetch and install Erlang packages from, 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">>,
===> 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:


Finding Erlang packages

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

$ rebar3 hex search 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

Erlang Central

Community-drive tutorials of #Erlang programming language. Content:

Erlang Central

Written by

The community website of #Erlang programming language. Content:

Erlang Central

Community-drive tutorials of #Erlang programming language. Content:

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade