Rebar3

1. What is Rebar3?
2. Why Rebar3?
3. Should I Use Rebar3?
4. Getting Started
5. Documentation
6. Features
7. Migrating from rebar2
8. Additional Resources

What is Rebar3

Rebar3 is an Erlang tool that makes it easy to create, develop, and release Erlang libraries, applications, and systems in a repeatable manner.

Rebar3 will:

• respect and enforce standard Erlang/OTP conventions for project structure so they are easily reusable by the community;
• manage source dependencies and Erlang packages while ensuring repeatable builds;
• handle build artifacts, paths, and libraries such that standard development tools can be used without a headache;
• adapt to projects of all sizes on almost any platform;
• treat documentation as a feature, and errors or lack of documentation as a bug.

Rebar3 is also a self-contained Erlang script. It is easy to distribute or embed directly in a project. Tasks or behaviours can be modified or expanded with a plugin system flexible enough that even other languages on the Erlang VM will use it as a build tool.

Why Rebar3

Rebar3 is the spiritual successor to rebar 2.x, which was the first usable build tool for Erlang that ended up seeing widespread community adoption. It however had several shortcomings that made it difficult to use with larger projects or with teams with users new to Erlang.

Rebar3 was our attempt at improving over the legacy of Rebar 2.x, providing the features we felt it was missing, and to provide a better environment in which newcomers joining our teams could develop.

Should I use Rebar3?

If your main language for your system is Erlang, that you value repeatable builds and want your various tools to integrate together, we do believe Rebar3 is the best experience you can get.

Getting Started

Compatibility between Rebar3 and Erlang/OTP

This list presents the known working version combos between Rebar3 and Erlang/OTP. Always use the latest version your project can tolerate for latest security fixes.

A getting started guide is maintained on the official documentation website, but installing rebar3 can be done by any of the ways described below

Latest stable compiled version:

$ wget https://s3.amazonaws.com/rebar3/rebar3 && chmod +x rebar3

From Source (assuming you have a full Erlang install):

$ git clone https://github.com/erlang/rebar3.git
$ cd rebar3
$ ./bootstrap

Stable versions can also be obtained from the releases page.

The rebar3 escript can also extract itself with a run script under the user's home directory:

$ ./rebar3 local install
===> Extracting rebar3 libs to ~/.cache/rebar3/lib...
===> Writing rebar3 run script ~/.cache/rebar3/bin/rebar3...
===> Add to $PATH for use: export PATH=~/.cache/rebar3/bin:$PATH

To keep it up to date after you've installed rebar3 this way you can use rebar3 local upgrade which fetches the latest stable release and extracts to the same place as above. A nightly version can also be obtained if desired.

Rebar3 may also be available on various OS-specific package managers such as FreeBSD Ports. Those are maintained by the community and Rebar3 maintainers themselves are generally not involved in that process.

If you do not have a full Erlang install, we recommend using erln8 or kerl. For binary packages, use those provided by Erlang Solutions, but be sure to choose the "Standard" download option or you'll have issues building projects.

Do note that if you are planning to work with multiple Erlang versions on the same machine, you will want to build Rebar3 with the oldest one of them. The 3 newest major Erlang releases are supported at any given time: if the newest version is OTP-27, building with versions as old as OTP-25 will be supported, and produce an executable that will work with those that follow.

Documentation

Rebar3 documentation is maintained on https://rebar3.org/docs

Features

Rebar3 supports the following features or tools by default, and may provide many others via the plugin ecosystem:

Migrating From rebar2

The grievances we had with Rebar 2.x were not fixable without breaking compatibility in some very important ways.

A full guide titled From Rebar 2.x to Rebar3 is provided on the documentation website.

Notable modifications include mandating a more standard set of directory structures, changing the handling of dependencies, moving some compilers (such as C, Diameter, ErlyDTL, or ProtoBuffs) to plugins rather than maintaining them in core rebar, and moving release builds from reltool to relx.

Additional Resources

In the case of problems that cannot be solved through documentation or examples, you may want to try to contact members of the community for help. The community is also where you want to go for questions about how to extend rebar, fill in bug reports, and so on.

If you need quick feedback, you can try the #rebar channel on irc.freenode.net or the #rebar3 channel on erlanger.slack.com. Be sure to check the documentation first, just to be sure you're not asking about things with well-known answers.

For bug reports, roadmaps, and issues, visit the github issues page.

General rebar community resources and links can be found at rebar3.org/docs/about/about-us/#community

To contribute to rebar3, please refer to CONTRIBUTING.