Erlbox
The Erlang Toolbox
This is a set of Rake tasks and scripts for working with Erlang projects.
GETTING STARTED
Dave ‘DizzyD’ Smith has written a great article on getting started with Erlbox.
USAGE
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).
APP_ROOT
|-- 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
.
DEFAULT FUNCTIONALITY
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
orcompile
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
ortest
test:unit:prepare
test:unit:cover
test:int
orint_test
test:int:prepare
test:int:cover
test:perf
orperf_test
test:perf:prepare
test:perf:cover
Generating documentation
Edoc generation tasks are in the “edoc” namespace.
edoc:run
oredoc
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
ordialyzer
OPTIONAL FEATURES
Optional features are enabled by requiring an Erlbox extension module.
Compiling SNMP MIBs
Include support for compiling SNMP MIBs with ‘erlbox/snmp’:
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
Include support for compiling a C port driver with ‘erlbox/driver’:
require 'erlbox/driver'
The driver module extends the build:compile
task to also compile any C source files.
REFERENCE
Constants
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…
- PWD
- This constant contains the working directory when the Rakefile was invoked.
- ERL_SRC
- The list of Erlang sources to be compiled to beam files. This does not include test sources.
- ERL_BEAM
- The list of beam files that are produced from Erlang sources.
- APP_FILE
- The path to the app file for this application.
- ERL_INCLUDE
- The directory where Erlang include (hrl) files live.
- TEST_ROOT
- The root of the test directory hierarchy.
- TEST_LOG_DIR
- The directory where test results are placed.
- UNIT_TEST_DIR
- The directory where unit tests are located.
- INT_TEST_DIR
- The directory where integration tests are located.
- PERF_TEST_DIR
- The directory where performance tests are located.
Variables
These variables can be customized in your Rakefile to control the behavior of the erlbox tasks.
- ERL_PATH
- 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.
- ERLC_FLAGS
- 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.
- UNIT_TEST_FLAGS
- A list of flags to be passed to the command that runs the unit tests. Defaults to an empty list.
- INT_TEST_FLAGS
- A list of flags to be passed to the command that runs the integration tests. Defaults to an empty list.
- PERF_TEST_FLAGS
- A list of flags to be passed to the command that runs the performance tests. Defaults to an empty list.
- CLEAN and CLOBBER
- These variables have their standard meaning from Rake.
Functions
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.
- erl_app_version(app)
- Return the version of the Erlang application defined in the app file.
REQUIREMENTS
If you want to use the edoc
task and you are using Faxien, you must install the edoc
and syntax_tools
applications (faxien ia <appname>
).
You need the current version of Rake to use the tasks (obviously). Nothing else is required.
INSTALL
The gem can be installed directly from wax:
sudo gem install erlbox --source=http://wax.hive/gems
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.