Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 36 ยท Getting Started

Projects with rebar3

Use rebar3, the standard Erlang build tool: create an application, understand the project layout, compile, run the shell, add dependencies and build releases.

A single module is fine for practice. A real project has many modules, dependencies, tests and a release. Erlang's standard build tool for this is rebar3. It creates project skeletons, fetches libraries from Hex (the package registry shared with Elixir), compiles, tests and builds releases.

rebar3 and Erlang cannot run in the browser, so every command here is read-only. The stand-ins at the end only model how a project is organized.

Installing rebar3

rebar3 is a single executable script. Most package managers carry it:

Terminal
brew install rebar3          # macOS
sudo apt install rebar3      # Debian/Ubuntu (may be an older version)

Or download it from the rebar3 website, make it executable and put it on your PATH. Check with rebar3 version.

Creating an application

Terminal
rebar3 new app name=greeter
cd greeter

The generator produces this tree:

TEXT
greeter/
  rebar.config
  src/
    greeter.app.src
    greeter_app.erl
    greeter_sup.erl

The pieces:

File Purpose
rebar.config Build settings and dependencies
src/greeter.app.src Application resource file: name, version, dependencies on other apps
src/greeter_app.erl The application callback module: starts the supervisor
src/greeter_sup.erl The top supervisor (you meet supervisors in Fault Tolerance and OTP)

An application in Erlang is a component that can be started and stopped as a unit, with its own supervision tree. Do not confuse it with the everyday meaning of "app".

For a plain library with no processes, use rebar3 new lib name=greeter. For a runnable release, use rebar3 new release name=greeter.

The application resource file

src/greeter.app.src is plain Erlang data:

ERLANG
{application, greeter,
 [{description, "A small greeting service"},
  {vsn, "0.1.0"},
  {registered, []},
  {mod, {greeter_app, []}},
  {applications, [kernel, stdlib]},
  {env, []},
  {modules, []},
  {licenses, ["Apache-2.0"]},
  {links, []}]}.

mod names the callback that starts the application. applications lists applications that must be running first: kernel and stdlib are always required. If you add a dependency such as cowboy, list it here too, or it will not be started.

Building and running

From the project root:

Terminal
rebar3 compile     # compile src/ into _build/default/lib/greeter/ebin
rebar3 shell       # compile and open erl with the project on the code path
rebar3 clean       # remove build output

Inside rebar3 shell the application is already started, and you can call your modules directly. Edit a file and type r3:compile(). in the shell to recompile and reload changed modules without leaving it.

Adding a module

Add src/greeting.erl:

ERLANG
-module(greeting).
-export([make/1]).

make(Name) when is_binary(Name) ->
    <<"Hello, ", Name/binary, "!">>.

Then:

Terminal
rebar3 shell
ERLANG
1> greeting:make(<<"Ada">>).
<<"Hello, Ada!">>

Any .erl file inside src/ is compiled and added to the application automatically.

Dependencies

Dependencies go in rebar.config:

ERLANG
{erl_opts, [debug_info]}.
{deps, [
    {jsx, "3.1.0"},
    {cowboy, "2.12.0"}
]}.

Run rebar3 compile and rebar3 downloads them into _build/default/lib/. A rebar.lock file records exact versions, and you should commit it. {erl_opts, [debug_info]} keeps debugging data in the .beam files, which tools such as the debugger and Dialyzer need.

Other useful commands:

Terminal
rebar3 eunit        # run unit tests under test/
rebar3 dialyzer     # static type analysis
rebar3 xref         # find calls to undefined functions
rebar3 release      # build a self-contained release
rebar3 tree         # print the dependency tree

Project layout rules

OTP expects a fixed directory layout, and rebar3 follows it:

flowchart TD
    P["greeter/"] --> C["rebar.config"]
    P --> S["src/ (modules, .app.src)"]
    P --> T["test/ (EUnit and Common Test)"]
    P --> I["include/ (.hrl header files)"]
    P --> B["_build/ (generated)"]

Hand-written files live in src, test and include; _build is generated and not committed.

Add _build/ to .gitignore. Headers (.hrl) hold records and macros shared between modules; you load them with -include("file.hrl"). or -include_lib("app/include/file.hrl")..

Stand-ins

These JavaScript snippets are not Erlang. The first models a project tree and the second a dependency resolver that starts applications in order, like OTP does with the applications list.

JS Stand-in: a project tree (JavaScript, not Erlang)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Stand-in: starting applications in dependency order (JavaScript, not Erlang)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is rebar3?

    rebar3 creates projects, fetches dependencies, compiles, tests and builds releases.
  2. 2. Where do hand-written Erlang modules go in a rebar3 application?

    Source modules live in src/. The _build directory holds generated output.
  3. 3. Why must a dependency also be listed in the applications entry of the .app.src file?

    The applications list names the apps that must be running before yours starts.
  4. 4. Which command opens a shell with your project loaded?

    rebar3 shell compiles the project and starts erl with it on the code path.

Summary

  • rebar3 is the standard build tool: new, compile, shell, eunit, dialyzer, release.
  • An OTP application has src/, an .app.src resource file and rebar.config.
  • Dependencies go into rebar.config; commit rebar.lock, not _build/.
  • List dependencies in the applications entry so OTP starts them first.

Next: Numbers and Atoms