Quick Guide to Rebar3

Rebar3 is the standard Erlang build tool

Common commands are:

• rebar3 help

• rebar3 get-deps

• rebar3 compile

• rebar3 eunit

• rebar3 ct

• rebar3 shell

• rebar3 release

Configuration

Rebar3 reads the rebar.config file to know what to do. This consists of one or more plain Erlang terms (tuples: {...}, lists: [...], symbols, numbers, and strings), each terminated by a full stop and newline, for example:

{erl_opts, [debug_info]}.

This sets compilation options and other details, lists dependencies (other Erlang apps to be fetched automatically) in the deps section:

{deps, [{gproc, "0.9.0"},
        ...]}.

defines how a Release is put together in the relx section:

{relx, [{release, { aeternity, ...},
        [ ... included-applications ... ]},
        ...
       ]}.

and specifies the different Rebar3 Profiles in the profiles section:

{profiles, [{prod, [... prod-specific-options ...
                   ]},
            {test, [... test-specific-options ...
                   ]},
           ]}.

In addition, the file rebar.config.script (an Erlang script) will be executed by Rebar3 if it exists, to perform dynamic configuration.

Generated files

Rebar3 does not write into the source directories, and instead outputs all generated files under a separate directory, by default _build/. It's always safe to delete the whole build directory and rebuild everything, if needed.

Source files

Rebar3 expects that applications follow the standard Erlang application structure with a src/ subdirectory etc. A Rebar3 project can be either a single application with a rebar.config file in the app directory, or it can consist of a collection of applications under a subdirectory named apps/ or lib/, with the main rebar.config in the root directory. Such a collection is called an "umbrella project".

An umbrella application is usually published as a Release - a complete Erlang system to run on some target machine. Often, only a top level rebar.config file is needed, but individual apps (apps/app1/, apps/app2/, ...) may have their own rebar.config files in order to use specific build options, pre-build or post-build hooks, etc., for that app only.

For a single application, it may also be published as a standalone library (that others can use as a dependency), or turned in to an escript (a standalone executable).

Releases

A release is a package that can be installed and run on a target machine, where the operator doesn't necessarily know anything about the implementation. When Rebar3 builds a release, typically rebar3 as prod release or rebar3 as prod tar, it puts the files under _build/$PROFILE/rel/$RELNAME (see Profiles below). A typical release specification looks something like this:

{relx, [{release, { RELNAME, DEFAULT_VERSION_STRING },
         [app1, app2, ...]},
        {sys_config, "./config/sys.config"},
        {vm_args, "./config/vm.args"},
        {overlay, [{copy, "LICENSE" , "LICENSE"},
                   {copy, "docs/README.md", "docs/REAME.md"}
                  ]}
       ]}.

A start script bin/$RELNAME will be generated automatically, providing standard commands like $RELNAME start. The listed Erlang apps will be included in the release package and will be started when the script runs, using the included sys_config and vm_args configuration files.

External Dependencies

Dependencies can be specified either just by name and version, as in {deps, [{gproc, "0.9.0"},...]}, in which case they are downloaded via the Hex package manager, or as a Git URL, as in {deps, [{cowboy, {git, "https://github.com/ninenines/cowboy.git", {tag,"2.11.0"}}},...]}, in which case they are checked out and built. See Profiles below for details about where the code ends up.

Note that listing an app as a dependency does not automatically include it in the final Release package - for that to happen, it must also be included in the relx specification (see above). For instance, libraries only used for building or testing may be listed as dependencies but should not be in the release spec. Vice versa, just listing an app in the release spec does not tell Rebar3 how to download that app.

The relx section does not however need to list every app that should be included in the Release. If an app a declares (in its *.app metadata file) that it has a runtime dependency on app b, then if Rebar3 includes a, it will automatically also include b, and so on, transitively, so that the Release package will contain all apps required for running.

Dependency pinning

When new dependencies have been fetched, Rebar3 updates the rebar.lock file with more exact information about the version, such as the Git hash, and not just the branch or tag name used in the deps declaration. This file should typically be kept under version control to ensure repeatable builds. See the Rebar3 documentation for details.

Checkout dependencies

You can also create a subdirectory or symbolic link named _checkouts, containing apps or links to apps that you have as local files, not yet published or committed, such as a library that you're currently making changes to. Apps found under _checkouts take precedence over any other apps with the same names, even if they already exist under _build.

Profiles

The default profile is just the basic rebar.config without any other profile applied. This is used if you e.g. just say rebar3 compile. To apply a profile to a command, say e.g. rebar3 as prod compile. You can use any profile names you like, but some names have special meaning to Rebar3:

• The prod profile will automatically apply the prod mode (see below).

• When running the commands rebar3 eunit or rebar3 ct, the profile named test will be automatically applied.

  • For example, if your tests require the meck library to run, you can add it as dependency to only the test profile, like this: {profiles, [{test, [{deps, [meck]}]}]}.

When Rebar3 builds things, it puts the generated files under _build/$PROFILE/. For example, Erlang apps compiled with rebar3 compile go under _build/default/lib, but when compiled with rebar3 as prod compile the files are placed under _build/prod/lib.

*Note that external dependencies, as specified in {deps, []}, are always built using their individual prod profiles, no matter what profile Rebar3 has been told to use currently. The files are however placed under _build/default/lib, not _build/prod/lib, because they should be available under the default profile.

Also note that when Rebar builds other profiles than the default, it does not rebuild the external dependencies. Instead it creates symbolic links from _build/$PROFILE/lib into _build/default/lib. The exception is dependencies specified as part of an individual profile, as in {profiles, [{test, [{deps, [meck]}]}]}, which get stored under that profile (in this case _build/test/lib) since they should not be available under the default profile.

These locations are typically not the final destination for the compiled files. Usually, they will later get copied into a Release package under _build/$PROFILE/rel for distribution as a tarball or similar.

Modes

Modes are shortcuts for some basic settings, for example {mode, prod} sets some typical options for production. The builtin modes are:

• prod: Include the Erlang Runtime System in the release package, don't include source code, and strip any debug information. Copy files into the release package instead of using symbolic links.

• minimal: Like prod but does not include the Erlang Runtime System.

• dev: The inverse of prod.

In particular, {mode, dev} implies the {dev_mode, true} option, which creates symbolic links instead of copying files when composing a release. This means that you don't need to rebuild the release when you make a small change during development; just recompiling is enough.