Using rebar3 to manage Erlang projects

Rebar3 is a tool for the Erlang programming language that allows you to easily and conveniently manage projects written in Erlang (sometimes Elixir).

People familiar with Erlang for a long time know the old rebar and maybe even still use it. Many (especially those who come from other languages with a much more developed ecosystem) do not like rebar, and from time to time they call it “shameful fake” there, which could be replaced with a Perl script. Fortunately, I didn’t have to work a lot with rebar (unlike the author of the above words), but rebar did quite well with basic things. But “not bad” is not “good.” Those who disagreed with this state of affairs (with “not bad”) turned out to be quite a few, and therefore they decided to give the valve a second life in the form of the rebar3 project, which is now actively developing. The project, among others, is the work of the notorious Sir Fred Hebert, who presented the world with the book "Learn Erlang in the name of good!".

My task in this article is to draw attention to rebar3 . Already familiar with rebar/rebar3 in the article will not find a lot of new rebar/rebar3 , but newcomers in the Erlang world may be interested. We will talk about how to start with rebar3 (installation, compilation, etc.).

Rebar3

As part of the installation, we have two ways:

Download the already copied rebar3 file.
Collect everything yourself from the source code.

In order not to offend anyone, I will show both ways, and which is better - you decide.

Method one:

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

Method two:

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

Now you need to add the path to the file in the $PATH environment variable.

This is done as follows:

 ➜ ./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=$PATH:~/.cache/rebar3/bin

After that, execute the command that you are asked to enter or add this line to your *rc file ( ~/.zshrc , ~/.bashrc ).

For example:

 ➜ ~ echo "export PATH=$PATH:~/.cache/rebar3/bin" >> ~/.zshrc

First application

Rebar3 (like most self-respecting project management tools) allows you to create application layouts from ready-made templates. Note that rebar3 creates a structure only for an OTP application. Below is a list of available templates, to translate the description of which I see no point.

 app: Complete OTP Application structure. cmake: Standalone Makefile for building C/C++ in c_src escript: Complete escriptized application structure plugin: Rebar3 plugin project structure release: OTP Release structure for executable programs lib: Complete OTP Library application (no processes) structure

We are only interested in the app and we will create our application based on this template:

 ➜ ~ rebar3 new app habrapp ===> Writing habrapp/src/habrapp_app.erl ===> Writing habrapp/src/habrapp_sup.erl ===> Writing habrapp/src/habrapp.app.src ===> Writing habrapp/rebar.config ===> Writing habrapp/.gitignore ===> Writing habrapp/LICENSE ===> Writing habrapp/README.md

Template created. Now let's look at the project structure:

 ➜ ~ cd habrapp ➜ ~/habrapp tree . ├── LICENSE ├── README.md ├── rebar.config └── src ├── habrapp_app.erl ├── habrapp.app.src └── habrapp_sup.erl

The usual structure of Erlang applications. What I would like to say, running ahead, is that rebar.config used to store metadata about the application (including dependency data)

If you are a lover of interactivity, then here rebar3 will not let you down. You can easily switch to shell-mode:

 ➜ ~/habrapp rebar3 shell ===> Fetching rebar3_hex ({pkg,<<"rebar3_hex">>,<<"3.0.0">>}) ===> Downloaded package, caching at /home/lk/.cache/rebar3/hex/default/packages/rebar3_hex-3.0.0.tar ===> Compiling rebar3_hex ===> Verifying dependencies... ===> Compiling habrapp Erlang/OTP 18 [erts-7.3] [source] [64-bit] [smp:4:4] [async-threads:0] [kernel-poll:false] Eshell V7.3 (abort with ^G) 1> application:start(habrapp). ok 2> application:stop(habrapp). =INFO REPORT==== 19-Jan-2017::14:03:38 === application: habrapp exited: stopped type: temporary ok

By the way, the whole article on Fred Hebert’s website is devoted to the shell topic.

Installing and removing packages

The first thing we need to do is install the plugin for rebar3 , which is called rebar3_hex . To do this, we need to edit the rebar.config file and add to the tuple next to the plugin tag the name of the plugin we need in the form of an atom: {plugins, [rebar3_hex]}.

After this we do the following:

 ➜ ~/habrapp rebar3 update ===> Fetching rebar3_hex ({pkg,<<"rebar3_hex">>,<<"3.1.0">>}) ===> Downloaded package, caching at /home/lk/.cache/rebar3/hex/default/packages/rebar3_hex-3.1.0.tar ===> Compiling rebar3_hex ===> Updating package registry... ===> Writing registry to /home/lk/.cache/rebar3/hex/default/registry ===> Generating package index... ===> Writing index to /home/lk/.cache/rebar3/hex/default/packages.idx

Here, rebar3 takes information from our rebar.config file. And if you do not want to constantly add {plugins, [rebar3_hex]}. in your rebar.config files, add it to the global configuration file rebar3, which is located at ~/.config/rebar3/rebar.config and rebar3 will automatically take everything from the global configuration file.

If your project works on the basis of some other project, then you can get it (provided it is in hex.pm).

The search for projects is very simple:

 ➜ ~/habrapp rebar3 hex search smokkfiskur smokkfiskur: 0.1.1, 0.1.2, 0.1.3

Once we have verified that the project we are looking for exists we can get it. To do this, we need to edit the rebar.config file (not global) and next to the deps label indicate the name of the desired package (yes, in the form of an atom).

 {deps, [smokkfiskur, mochiweb]}.

If you wish, you can add a bit of specifics:

 {deps, [{smokkfiskur, "0.1.3"}, {mochiweb, "2.15.0"}]}.

Imagine that in our project we use smokkfiskur and mochiweb . All we need to get the dependencies is to perform rebar3 compile :

 ➜ ~/habrapp rebar3 compile ===> Verifying dependencies... ===> Fetching mochiweb ({pkg,<<"mochiweb">>,<<"2.15.0">>}) ===> Downloaded package, caching at /home/lk/.cache/rebar3/hex/default/packages/mochiweb-2.15.0.tar ===> Fetching smokkfiskur ({pkg,<<"smokkfiskur">>,<<"0.1.3">>}) ===> Downloaded package, caching at /home/lk/.cache/rebar3/hex/default/packages/smokkfiskur-0.1.3.tar ===> Compiling mochiweb ===> Compiling smokkfiskur ===> Compiling habrapp

Seeing dependencies is easier than typing pip freeze (well, almost ± 1 character):

 ➜ ~/habrapp rebar3 deps mochiweb* (package) smokkfiskur* (package)

Removing packages is also not difficult. You just need to remove the project name from the list {deps, [smokkfiskur]} and type the commands below:

 ➜ ~/habrapp rebar3 unlock ➜ ~/habrapp rebar3 deps smokkfiskur* (package)

To delete all compiled *.beam files from a project, use the clean command.

 ➜ rebar3 clean

Working with documents

Documentation is an important part of any project and convenient work with it is very important. What could be more convenient than the simple rebar3 edoc that generates documentation?

 ➜ ~/habrapp rebar3 edoc ===> Linking _build/default/plugins/rebar3_hex to _build/docs/plugins/rebar3_hex ===> Verifying dependencies... ===> Linking _build/default/lib/smokkfiskur to _build/docs/lib/smokkfiskur ===> Compiling habrapp ===> Running edoc for habrapp

Testing

Rebar3 allows you to run both Eunit tests and Common Tests. We did not write tests for our application, however we still see how to run them.

 ➜ ~/habrapp rebar3 ct ➜ ~/habrapp rebar3 eunti

You can see the code coverage with tests like this:

 ➜ rebar3 cover

Distribution

Distribution of packages is important and the rebar3_hex plugin, which we have already dealt with, will help us with this. We need to have a hex.pm account to post a package there. It is very easy to register it and you can do it right in the console.

 ➜ ~/habrapp rebar3 hex user register By registering an account on Hex.pm you accept all our policies and terms of service found at https://hex.pm/policies Username: ([])>

Once done with the registration, you can publish your project on hex.pm with the publish command.

 ➜ ~/habrapp rebar3 hex publish ===> Verifying dependencies... Publishing habrapp 0.1.0 Description: An OTP application Dependencies: smokkfiskur 0.1.3 Included files: /home/lk/habrapp/LICENSE /home/lk/habrapp/README.md /home/lk/habrapp/rebar.config /home/lk/habrapp/rebar.lock /home/lk/habrapp/src/habrapp.app.src /home/lk/habrapp/src/habrapp_app.erl /home/lk/habrapp/src/habrapp_sup.erl Maintainers: Licenses: Links: Build tools: rebar3 Before publishing, please read Hex CoC: https://hex.pm/policies/codeofconduct Proceed? ("Y")> n Goodbye...

You need to enter Y if you are publishing something more meaningful than the template. We will not publish our useless application and spoil the virgin cleanliness of this package repository.

Bun

For the lucky ones working in the *nix environment, there is additionally a nice bun in the form of automatic addition of the entered commands for zsh . You can find the plugin here .