toland edited this page Sep 11, 2010 · 6 revisions
Clone this wiki locally

Erlang Toolbox


This is a set of Rake tasks and scripts for working with Erlang projects.


The erlbox Rake tasks assume a certain directory structure. The tasks may or may not work correctly if you do not follow the prescribed structure (most likely not).

      |-- Rakefile
      |-- ebin
      |-- include
      |-- int_test
      |-- logs
      |-- mibs
      |-- priv
      |-- src
      `-- test

If you are on the golden path then all you need to do is put `require ‘erlbox’` at the top of an empty Rakefile. There are a few optional modules that you may take advantage of by requiring the appropriate file in your Rakefile. For example, if you are on the golden path and have SNMP mibs to compile then you can add `require ‘erlbox/snmp’`.

The behavior of erlbox can be customized by setting certain variables or by extending Rake tasks. For example, if you have other Erlang applications that need to be on the Erlang path when you compile and run tests then add them to the `ERL_PATH` variable:

    ERL_PATH.include %W( #{PWD}/../otherapp /usr/local/lib/erlang/alib )

The variables and constants (like `ERL_PATH` and `PWD`) are described in the Reference section.

You can see what tasks are available by issuing the command `rake -T`.


This section describes the features that are included by default. All of the tasks described here are available after requiring ‘erlbox’.

Compiling Erlang sources

The most basic Erlbox feature is compiling Erlang sources to beam files. The sources are found in the `src` directory (not subdirectories) and the beam files are placed in the `ebin` directory. After compilation is complete Erlbox will validate that all of the compiled modules are listed in the app file.

The flags passed to the `erlc` compiler can be controlled via the `ERLC_FLAGS` variable. `ERLC_FLAGS` will include `+debg_info` if you include `debug=1` on the command line.

All compilation tasks are in the “build” namespace.

  • `build:compile` or `compile`
  • `build:rebuild`
  • `build:validate_app`

The `build:compile` task is the default. It will be executed if you type `rake` with no task name.

Running tests

Test tasks are in the “test” namespace.

  • `test:prepare`
  • `test:unit` or `test`
  • `test:unit:prepare`
  • `test:unit:cover`
  • `test:int` or `int_test`
  • `test:int:prepare`
  • `test:int:cover`
  • `test:perf` or `perf_test`
  • `test:perf:prepare`
  • `test:perf:cover`

Generating documentation

Edoc generation tasks are in the “edoc” namespace.

  • `edoc:run` or `edoc`

Publishing Faxien packages

Faxien tasks are in the “faxien” namespace.

  • `faxien:prepare`
  • `faxien:package`
  • `faxien:publish`

The `faxien` task is equivalent to executing `faxien:package` followed by `faxien:publish`.

Running Dialyzer

To use Dialyzer with Erlbox, you must first ensure that you have a PLT file that has information on all of the appropriate libraries. First, in your project Rakefile, add any libraries that your code directly depends on to the `PLT_LIBS` variable:

    PLT_LIBS << 'crypto' << 'inets' << 'mochiweb'

Note that `PLT_LIBS` contains kernel and stdlib by default.

Next, run the `dialyzer:update_plt` task. This will create a PLT file at `~/.dialyzer_plt` if it does not already exist and it will add information for the libraries listed in `PLT_LIBS`. It will also add information for any applications listed in the `ERL_PATH` variable.

Finally, you can run Dialyzer using the `dialyzer` or `dialyzer:run` tasks.

The Dialyzer tasks are in the “dialyzer” namespace.

  • `dialyzer:update_plt`
  • `dialyzer:prepare`
  • `dialyzer:run` or `dialyzer`


Optional features are enabled by requiring an Erlbox extension module.

Compiling SNMP MIBs

    require 'erlbox/snmp'

The snmp module extends the `build:compile` task to also compile any SNMP MIBs.

If the default order for building the MIBs is wrong, override with a file line

    file 'priv/mibs/ENODE-MIB.bin' => 'priv/mibs/HCNUM-TC.bin'

Building a port driver

    require 'erlbox/driver'

The driver module extends the `build:compile` task to also compile any C source files.



These constants are available for reference in your Rakefile, but their values
should not be changed. Dark and evil things will happen if you change them…

This constant contains the working directory when the Rakefile was invoked.

The list of Erlang sources to be compiled to beam files. This does not include test sources.

The list of beam files that are produced from Erlang sources.

The path to the app file for this application.

The directory where Erlang include (hrl) files live.

The root of the test directory hierarchy.

The directory where test results are placed.

The directory where unit tests are located.

The directory where integration tests are located.

The directory where performance tests are located.


These variables can be customized in your Rakefile to control the behavior of
the erlbox tasks.

A FileList with other Erlang applications that will be added to the command line for “erl” and “erlc” with “-pa” switches. Defaults to an empty list.

An array of flags that will be passed to the “erlc” command. You may append flags to this list, but clearing it will cause the build to fail.

A list of flags to be passed to the command that runs the unit tests. Defaults to an empty list.

A list of flags to be passed to the command that runs the unit tests. Defaults to an empty list.

A list of flags to be passed to the command that runs the unit tests. Defaults to an empty list.

These variables have their standard meaning from Rake.


These functions can be called from your Rakefile. Any erlbox functions that are
not listed here are considered private and should not be called.

append_flags(flags, value)
Append value to the flags constant. Example: “append_flags ERLC_FLAGS, ‘+debug’”.

erl_run(script, args = "")
Run the Erlang code in script optionally passing args.

erl_where(lib, dir = ‘include’)
Return the physical location of the specified Erlang library.

Return the version of the Erlang application defined in the app file.


If you want to use the `edoc` task and you are using Faxien, you must install the
`edoc` and `syntax_tools` applications (`faxien ia `).

You need the current version of Rake to use the tasks (obviously). Nothing else
is required.


The gem can be installed with:

    sudo gem install erlbox

Alternatively, if you have checked out the Erlbox sources to a directory called ‘erlbox’,
all you need to do is:

    rake install

Be sure to enter your password when requested.