Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 36 ยท Tools and Testing

rebar3: building Erlang projects

Use rebar3, the standard Erlang build tool: create apps and releases, rebar.config, dependencies from Hex, profiles, compile, shell, eunit, dialyzer and releases.

Compiling single modules with erlc is fine for experiments. Real projects need dependencies, tests, releases and a predictable layout. rebar3 is the de-facto build tool of the Erlang ecosystem. It follows OTP conventions, fetches libraries from Hex (the package registry shared with Elixir) and drives compilation, testing, static analysis and releases from one command.

Installing and creating a project

rebar3 is a single executable (an escript). Download it once, put it on your PATH, then:

TEXT
$ rebar3 new app greeter
$ rebar3 new release greeter     # same plus release configuration
$ rebar3 new lib mylib           # library application, no supervision tree
$ rebar3 new escript tool        # command-line program

rebar3 new app greeter creates:

TEXT
greeter/
  rebar.config
  src/
    greeter.app.src
    greeter_app.erl
    greeter_sup.erl
  test/                  (you add eunit or ct tests here)

The files match what you saw in applications and releases: a resource file template, an application callback and a top supervisor.

Everyday commands

TEXT
rebar3 compile       # compile src/ and dependencies into _build/
rebar3 shell         # start an Erlang shell with the project and deps loaded
rebar3 eunit         # run unit tests
rebar3 ct            # run Common Test suites
rebar3 dialyzer      # static analysis (slow first time: builds a PLT)
rebar3 xref          # find calls to missing functions
rebar3 clean
rebar3 release       # build a release (needs a relx section)
rebar3 tar           # release as a tarball
rebar3 upgrade       # refresh dependency versions
rebar3 tree          # show the dependency tree

Output goes to _build/, which you should add to .gitignore. Commands can be chained: rebar3 do compile, eunit, dialyzer, or rebar3 as test eunit to run under another profile. In rebar3 shell, code changes can be reloaded with r3:compile(). or r3:do(compile).

rebar.config

The configuration file is a list of Erlang terms, each ending with a period:

ERLANG
{erl_opts, [debug_info, warnings_as_errors]}.

{deps, [
    {jsx, "3.1.0"},                                   % from Hex
    {cowboy, "2.12.0"},
    {mylib, {git, "https://example.com/mylib.git", {tag, "1.2.0"}}}
]}.

{shell, [{apps, [greeter]}]}.

{profiles, [
    {test, [{deps, [meck]}]},
    {prod, [{relx, [{mode, prod}]}]}
]}.

{dialyzer, [{warnings, [unknown]}]}.
  • erl_opts are compiler options. debug_info is needed by tools such as Dialyzer and the debugger; warnings_as_errors keeps a codebase tidy.
  • deps lists dependencies: {Name, "Version"} for Hex, or git/branch/tag sources. rebar3 writes the exact resolved versions to rebar.lock, which you commit, so builds are reproducible.
  • Profiles add or override settings for a context: test, prod, or any name you pick. The test profile is active automatically for eunit and ct.

Dependencies must also appear in the applications list of your .app.src (jsx, cowboy and so on) so they start first in a release.

Hex and publishing

Hex hosts open source Erlang and Elixir packages. Search rebar3 hex search json and publish your own library with the rebar3_hex plugin (rebar3 hex publish). Plugins extend rebar3 and are listed under {plugins, [rebar3_hex, rebar3_format]}. Typical ones: rebar3_proper (property-based testing), rebar3_lint (style checks), rebar3_format (formatter).

A rebar3 workflow

rebar3 new Layout from a template
deps in rebar.config Hex, git, locked in rebar.lock
eunit, ct, dialyzer Test and analyse
release / tar Ship a self-contained system

One tool covers the whole loop.

1 / 2

escripts and single files

For small tools, an escript is an Erlang script that runs without a project:

ERLANG
#!/usr/bin/env escript
%%! -noshell
main([Name]) ->
    io:format("Hello, ~s!~n", [Name]);
main(_) ->
    io:format("usage: greet NAME~n"),
    halt(1).

Save it as greet, mark it executable, and run ./greet Ada. It is compiled on each start; rebar3 escriptize can package a project as one portable file.

Layout conventions that matter

  • Source in src/, headers in include/ (public) or src/ (private), tests in test/, configuration in config/.
  • One module per file, file name equal to module name, prefixed by the application name (greeter_sup) to avoid clashes, since Erlang modules share one flat namespace.
  • Keep application names unique; two libraries with a module util will collide.
  • Umbrella projects, with several apps under apps/, are supported when {project_app_dirs, ["apps/*"]} is set; use them when one release contains several tightly related applications.

Run it: a dependency resolver stand-in

This JavaScript stand-in is not rebar3. It reads a tiny rebar.config-like description and shows how a lock file picks one version for each dependency and detects a conflict.

JS Stand-in: resolving dependencies

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

No output.

Common mistakes

  • Not committing rebar.lock: teammates and CI may get different versions.
  • Forgetting a dependency in .app.src applications: works in rebar3 shell, fails in a release.
  • Running rebar3 dialyzer without debug_info.
  • Editing code in _build/; it is regenerated.
  • Mixing profile-only dependencies into the main deps, shipping test libraries to production.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file records the exact versions of dependencies that rebar3 resolved?

    rebar.lock pins versions so builds are reproducible; commit it.
  2. 2. What is Hex?

    Hex hosts packages that rebar3 downloads for deps declared by name and version.
  3. 3. Which command starts a shell with your project loaded?

    rebar3 shell compiles and loads the project and its dependencies in an Erlang shell.
  4. 4. What do profiles in rebar.config do?

    A profile merges extra settings (deps, relx, erl_opts) when selected with rebar3 as <profile>.

Summary

  • rebar3 new creates OTP-style projects; compile, shell, eunit, ct, dialyzer, release are the daily commands.
  • rebar.config holds compiler options, dependencies, profiles and release settings; rebar.lock pins versions.
  • Dependencies come from Hex or git and must also be listed in the app's applications.
  • Escripts cover small command-line tools.

Next: EUnit and Common Test