-
Notifications
You must be signed in to change notification settings - Fork 3
Home
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).
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`.
This section describes the features that are included by default. All of the tasks described here are available after requiring ‘erlbox’.
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.
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`
Edoc generation tasks are in the “edoc” namespace.
- `edoc:run` or `edoc`
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`.
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.
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'
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…
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.
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 unit tests. Defaults to an empty list.
PERF_TEST_FLAGS
A list of flags to be passed to the command that runs the unit tests. Defaults to an empty list.
CLEAN and CLOBBER
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.
erl_app_version(app)
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.