rebar3/doc/guide.md

Why Rebar3?

Rebar was a great step forward for Erlang development but with time has proven to be fragile to change. Rebar3 builds on certain components of rebar which have benefited from years of community collaboration within a new core which is more extendable.

Creating a New Project

$ rebar3 new release myrelease
===> Writing apps/myrelease/src/myrelease_app.erl
===> Writing apps/myrelease/src/myrelease_sup.erl
===> Writing apps/myrelease/src/myrelease.app.src
===> Writing rebar.config
===> Writing relx.config
===> Writing config/sys.config
===> Writing config/vm.args
===> Writing .gitignore
===> Writing LICENSE
===> Writing README.md

Working on an Existing Rebar3 Project

First, checkout the project and change directories to the project root.

$ git clone git://github.com/tsloughter/minasan.git
$ cd minansan

Now we can use rebar3 to fetch all dependencies and build both the dependencies and the project app or apps.

$ rebar3 compile
===> Fetching gproc
===> Fetching ranch
===> Fetching cowboy
===> Fetching cowlib
===> Compiling gproc
/home/tristan/Devel/minasan/_deps/gproc/src/gproc_dist.erl:23: Warning: behaviour gen_leader undefined
===> Compiling cowlib
===> Compiling ranch
===> Compiling cowboy
===> Compiling minasan

Adding Dependencies

Dependencies are listed in rebar.config file under the deps key:

{deps, [
        {cowboy, ".*", {git, "git://github.com/ninenines/cowboy.git", {tag, "1.0.0"}}}
        ]}.

Now you can add the dep to one of your project's application's .app.src file under applications:

{application, <APPNAME>,
 [{description, ""},
  {vsn, "<APPVSN>"},
  {registered, []},
  {modules, []},
  {applications, [
                 kernel
                 ,stdlib
                 ,cowboy
                 ]},
  {mod, {<APPNAME>_app, []}},
  {env, []}
 ]}.

Rebar3 Conventions

Rebar3 is entirely based on building OTP applications and releases.

• Directories starting with underscores, e.g. _deps, are expected to not be checked in version control.
• Project apps you are working on exist under apps/ or lib/, or is a single app project with src/ in the root directory.
• rebar.lock and rebar.config go in the root of the project.
• Tests go in tests/.

rebar.config vs rebar.lock

rebar.lock contains the exact reference id to a commit that was used to build the project. Committing this file allows you to specify a branch in rebar.config for a dependency and still have reproducable builds because if the rebar.lock file exists when a rebar3 project is being built the contents of deps in rebar.config are ignored.

Checkout Dependencies

Often while developing you find yourself working on mulitple applications from separate repos together. To simplify this process rebar3 will look in the directory _checkouts for applications to override a dependency.

For example, you are working on project app1 which depends on app2. You want to have your modifications to app2 used by app1:

[app1] $ pwd
/home/user/code/app1
[app1] $ cat rebar.config
{deps, [
   {app2, "", {git, "git://github.com:user/app2.git", {branch, "master"}}}
]}.
[app1] $ ls -l _checkouts
lrwxrwxrwx app2 -> /home/user/code/app2

Since a symlink to app2 exists in _checkouts there will not be a fetch of app2 by rebar3 when the project is built.

Tests

Rebar3 has the concept of test dependencies. These dependencies will only be fetched when a rebar3 command that runs tests is run by the user.

{test_deps, [
             {meck, ".*", {git, "https://github.com/eproxus/meck.git", {tag, "0.8"}}}
             ]}.

$ rebar ct
===> Fetching meck
===> Compiling meck
===> Compiling minasan