Gradual Epiphany

Getting Started With Erlbox

erlbox is a set of Rake tasks that make it easy to build Erlang applications and embedded nodes. It’s a framework that Phil and I developed over the past few months and is now something I’d prefer not to live without. While it would be nice to have a “pure” Erlang solution for doing builds, Rake has turned out to be an excellent tool and a reasonable, pragmatic solution to the problem.

Please note that erlbox (and this blog entry) isn’t necessarily where you want to start when you’re first learning Erlang — see any of the excellent books for a good introduction to Erlang.

To get started with erlbox, you first need to install Ruby and RubyGems. One you have RubyGems installed, you can then do:

1
 $ gem install erlbox 

This should pull down erlbox as well as Rake and any other dependencies. Note that the Debian version of RubyGems is a little weird — my experience is that using RubyGems from source on Debian yields the best results.

Once you have erlbox installed, you’re ready to put together your an Erlang application. In keeping with OTP guidelines, we’ll start by creating a standard OTP directory structure:

1
 $ mkdir -p testapp/ebin testapp/src 

The next step is to create an application descriptor (ebin/testapp.app) so that Erlang/OTP knows how to start our application up. Drop the following text into testapp/ebin/testapp.app:

1
2
3
4
5
6
7
8
9
10
11
12
 {application, testapp,
 [{description, "Test Application"},
  {vsn, "1"},
  {modules, [ testapp,
              testapp_sup ]},
  {registered, []},
  {applications, [kernel, 
                  stdlib]},
  {mod, {testapp, []}},
  {env, [
        ]}
 ]}. 

The hows/whys of OTP .app files are beyond the scope of this entry — see the Erlang docs, specifically “Working with OTP/Design Principles” for more details.

With the .app file and the basic directory structure in place, we are now ready to create the Rakefile that will be used by Rake to kick off the erlbox tasks. For this simple build, it’s a one-liner:

1
 $ echo "require 'erlbox'" > testapp/Rakefile 

We can now use Rake to build our Erlang app:

1
2
3
4
5
6
7
8
9
10
 $ cd testapp; rake
(in /home/dizzyd/src/testapp)
validating testapp.app...
rake aborted!
One or more modules listed in testapp.app do not exist as .beam:
 * testapp
 * testapp_sup

(See full trace by running task with --trace)
 

As you can see, we still have some work to do. One of the important things that erlbox does is validate the application descriptor ebin/testapp.app and ensure that all the modules it lists are present in compiled form in the ebin/ directory. In this case, the .app file claimed that a module named “testapp” would be present as ebin/testapp.beam, and erlbox generated an error when the module was not found.

So, let’s create the source for the testapp module. Drop the following text into testapp/src/testapp.erl:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 -module(testapp).

-behaviour(application).

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

%% ===============================================================
%% Application callbacks
%% ===============================================================

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

stop(_State) ->
    ok.
 

We also need to define the application supervisor in testapp/src/testapp.erl:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 -module(testapp_sup).

-behaviour(supervisor).

%% API
-export([start_link/0]).

%% Supervisor callbacks
-export([init/1]).

%% ===================================================================
%% API functions
%% ===================================================================

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

%% ===================================================================
%% Supervisor callbacks
%% ===================================================================

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

The erlbox tasks know to look for all source files in testapp/src/.erl and compile them to testapp/ebin/.beam. With these files in place let’s try rake again:

1
2
3
4
5
6
 $ cd testapp; rake
(in /home/dizzyd/src/testapp)
compiling src/testapp.erl...
compiling src/testapp_sup.erl...
validating testapp.app...
$ 

The build completed cleanly. Congratulations, you’ve just built a basic Erlang/OTP application using erlbox.

There are a lot more features in erlbox other than what I’ve covered here. It also has the ability to build/compile OTP embedded nodes, SNMP MIBs, port drivers and other everyday components that make up the OTP platform.