Erlang App. Management with Rebar

Introduction

Rebar is a build and packaging tool for Erlang applications. It is implemented in Erlang and the only dependency is the Erlang Virtual Machine, so it can work as a stand-alone escript in your project. Rebar was created by Dave Smith from Basho, creators of Riak. In this tutorial I'll be creating a sample application, building it and generating a release for it, all of this with Rebar.

Application Requirements

Rebar expects that your applications follows the OTP Design Principles. The application directory must have the following sub-directories:

- *src* - Contains the Erlang source code.
- *ebin* - Contains the Erlang object code, the beam files. The .app file is also placed here.
- *priv* - Used for application specific files. For example, C executables are placed here. The function code:priv_dir/1 should be used to access this directory.
- *include* - Used for include files. 

Don't worry about this, Rebar can create applications with this kind of directory structure automatically.

Installation

To install Rebar is very easy, just download it at: http://hg.basho.com/rebar/downloads/rebar. After getting it just run a chmod u+x rebar. Rebar depends on Erlang R13B03 (or later), so I advise you to get Erlang OTP source code em build it. There is a tutorial here: http://wiki.github.com/erlang/otp/installation.

h2. Rebar's Features

To see what Rebar offers just execute ./rebar -c and you'll be able to see all of Rebar's commands.

$ ./rebar -c
analyze                              Analyze with Dialyzer
build_plt                            Build Dialyzer PLT
check_plt                            Check Dialyzer PLT

clean                                Clean
compile                              Compile sources

create      template= [var=foo,...]  Create skel based on template 
                                      and vars
create-app                           Create simple app skel
create-node                          Create simple node skel

check-deps                           Display to be fetched dependencies
get-deps                             Fetch dependencies
delete-deps                          Delete fetched dependencies

generate    [dump_spec=0/1]          Build release with reltool
install     [target=]                Install build into target

eunit       [suite=foo]              Run eunit [test/foo_tests.erl] 
                                      tests

int_test    [suite=] [case=]         Run ct suites in ./int_test
perf_test   [suite=] [case=]         Run ct suites in ./perf_test
test        [suite=] [case=]         Run ct suites in ./test

I won't be using all of the commands listed above for the sample application, so if you get more interested in it take a look at the source code.

Getting Started

To get started off I'll go step by step on creating a new project with rebar.

$ mkdir mysample
$ cd mysample
$ wget http://hg.basho.com/rebar/downloads/rebar
$ chmod u+x rebar
$ ./rebar create-app appid=mysample
==> mysample (create-app)
Writing ebin/mysample.app
Writing src/mysample_app.erl
Writing src/mysample_sup.erl

This was pretty easy to follow. Rebar creates this directory structure based on a previous created template. If you want to add new templates or change the ones that exists take a look at Rebar's source code: http://bitbucket.org/basho/rebar/src and navigate to priv/templates/simpleapp.template.

Well, for now we've had Rebar create our initial application directories and files. Let's take a look at the source code we've got so far:

ebin/mysample.app - Application descriptor

{application, mysample,
 [
  {description, ""},
  {vsn, "1"},
  {modules, [
             mysample_app,
             mysample_sup
            ]},
  {registered, []},
  {applications, [
                  kernel,
                  stdlib
                 ]},
  {mod, { mysample_app, []}},
  {env, []}
 ]}.

src/mysample_app.erl - Application callback module

-module(mysample_app).

-behaviour(application).

-export([start/2, stop/1]).

start(_StartType, _StartArgs) ->
    mysample_sup:start_link().

stop(_State) ->
    ok.

src/mysample_sup.erl - Supervisor callback module

-module(mysample_sup).

-behaviour(supervisor).

-export([start_link/0]).
-export([init/1]).

-define(CHILD(I, Type), {I, {I, start_link, []}, permanent, 5000, Type, 
[I]}).

start_link() ->
    supervisor:start_link({local, ?MODULE}, ?MODULE, []).

init([]) ->
    {ok, { {one_for_one, 5, 10}, []} }.

The generated code is almost a fully working simple application, but there is one thing missing, a Generic Server ! So the next step is to create one. I'll create a generic server called mysample_server.erl.

Place this code in src/mysample_server.erl:

-module(mysample_server).

-behaviour(gen_server).

-export([start_link/0, say_hello/0]).

-export([init/1, handle_call/3, handle_cast/2, handle_info/2,
         terminate/2, code_change/3]).

start_link() ->
    gen_server:start_link({local, ?MODULE}, ?MODULE, [], []).

init([]) ->
    {ok, []}.

say_hello() ->
    gen_server:call(?MODULE, hello).

%% callbacks
handle_call(hello, _From, State) ->
    io:format("Hello from server!~n", []),
    {reply, ok, State};

handle_call(_Request, _From, State) ->
    Reply = ok,
    {reply, Reply, State}.

handle_cast(_Msg, State) ->
    {noreply, State}.

handle_info(_Info, State) ->
    {noreply, State}.

terminate(_Reason, _State) ->
    ok.

code_change(_OldVsn, State, _Extra) ->
    {ok, State}.

The next step is make the generic server part of the application, this is done by doing the following steps:

  • Add mysample_server into ebin/mysample.app under the modules tuple.
  • Make mysample_server a child of mysample supervisor.

So by making this changes we have the following new codes:

ebin/mysample.app:

{application, mysample,
 [
  {description, ""},
  {vsn, "1"},
  {modules, [
             mysample_app,
             mysample_sup,
             mysample_server
            ]},
  {registered, []},
  {applications, [
                  kernel,
                  stdlib
                 ]},
  {mod, { mysample_app, []}},
  {env, []}
 ]}.

src/mysample_sup.erl:

-module(mysample_sup).

-behaviour(supervisor).

-export([start_link/0]).
-export([init/1]).

-define(CHILD(I, Type), {I, {I, start_link, []}, permanent, 5000, Type, 
[I]}).

start_link() ->
    supervisor:start_link({local, ?MODULE}, ?MODULE, []).

init([]) ->
    MySampleServer = ?CHILD(mysample_server, worker),
    {ok, { {one_for_one, 5, 10}, [MySampleServer]} }.

Now that we've made every change, let's compile the project:

$ ./rebar compile
==> mysample (compile)
Compiled src/mysample_app.erl
Compiled src/mysample_sup.erl
Compiled src/mysample_server.erl

Now take a look at your ebin directory and check if each module has a beam file placed there.

What about now? We've got an application module, a supervisor, and a simple generic server, but what do we do with it? Well, wouldn't be great to make your application work as a service that you can start, stop, and restart whenever you want? You can create this using some Erlang tools, but with Rebar you can do this in a very very easy way. Summarizing what I've just said: Rebar can help you create an Erlang Release.

To create a release we have to create a new directory in the root of our project called rel and create a node in it. A node is kind of a standalone Erlang VM for our application to run on.

$ mkdir rel
$ cd rel
$ ../rebar create-node nodeid=mysample
==> rel (create-node)
Writing reltool.config
Writing overlay/erts-vsn/bin/erl
Writing overlay/erts-vsn/bin/nodetool
Writing overlay/bin/mysample
Writing overlay/etc/app.config
Writing overlay/etc/vm.args
$ cd -

We've just created a node for our application to run on, this node is created using a template just like the one used in the application creation. You can see it at Rebar's source code: http://bitbucket.org/basho/rebar/src/ and then head to priv/templates/simplenode.template.

Now we're almost done. We only need to make some changes to the rel/reltool.config, file that contains the release configuration, so it can be compatible with our application's modules.

Here is the changed version of the generated file, I will put * around the lines I changed, notice that they don't belong to the real code.

{sys, [
       *{lib_dirs, ["../../"]}*,
       {rel, "mysample", "1",
        [
         kernel,
         stdlib,
         sasl,
         *mysample*
        ]},
       {rel, "start_clean", "",
        [
         kernel,
         stdlib
        ]},
       {boot_rel, "mysample"},
       {profile, embedded},
       {excl_sys_filters, ["^bin/.*",
                           "^erts.*/bin/(dialyzer|typer)"]},
       *{app, mysample, [{incl_cond, include}]}*,
       {app, sasl, [{incl_cond, include}]}
      ]}.

{rebar, [
         {empty_dirs, [
                       "log/sasl"
                      ]},

         {overlay, "overlay"}
         ]}.

If you want to know the meaning of each of this tuple's options, look at Reltool Manual.

Now lets make this directory visible for rebar, for that we create rebar.config file in the root directory of our project.

rebar.config:

{sub_dirs, ["rel"]}.

Configuration is now over! Lets generate our release:

$ ./rebar generate

This command creates a release of your application. Take a look at yours rel/mysample folder and you'll be able to see something like this:

$ ls rel/mysample
bin  erts-5.7.4  etc  lib  log  releases

Now let's run our release service, see the step by step below:

$ chmod u+x rel/mysample/bin/mysample
$ ./rel/mysample/bin/mysample
Usage: mysample {start|stop|restart|reboot|ping|console|attach}

Seems that everything is alright. To make sure your application was packed in the release, run your service with console ./rel/mysample/bin/mysample console and execute application:which_applications().. Check if you got something like this:

(mysample@127.0.0.1)1> application:which_applications().
[{mysample,[],"1"},
 {sasl,"SASL  CXC 138 11","2.1.8"},
 {stdlib,"ERTS  CXC 138 10","1.16.4"},
 {kernel,"ERTS  CXC 138 10","2.13.4"}]
(mysample@127.0.0.1)2> mysample_server:say_hello().
Hello from server!

If yes, you've done it! If not, make sure you've followed everything correctly.

Conclusions

The purpose of this tutorial was to give an introduction to a tool that helps we manage our Erlang applications. I think Rebar has a long way to go from here, but it is on the right track. It's a great tool and if there were more documentation available there would have more people using it. I've talked about some of it's most important features here, but in the beggining I showed that there is a lot more to it than just than compile and generate functions. So get Rebar and start using it on your next project.

Feel free to put your comments below and thank you for reading this post.