path: root/README.md

erlang.mk
=========

A build tool for Erlang that just works.

[Check out our upcoming user guide!](doc/src/guide/book.asciidoc)

The README only contains legacy documentation that was not moved to
the guide yet. Check there if you don't find what you're looking for.

Requirements
------------

`erlang.mk` requires GNU Make and expects to be ran in a standard
unix environment with Erlang installed and in the `$PATH`.

Common workflow
---------------

A common workflow when editing a file would be to run `make` regularly
to see if it compiles (or less often `make clean app` if you want to
recompile everything), followed by `make dialyze` to see if there are
any type errors and then `make tests` to run the test suites. The
result of the test runs can be browsed from the `logs/index.html` file.

Compiling and dependencies
--------------------------

Gone! [Check out our upcoming user guide!](doc/src/guide/book.asciidoc)

Releases
--------

If a `relx.config` file is present, erlang.mk will download `relx`
automatically and build the release into the `_rel` folder. This
is the default command when the file exists.

No special configuration is required for this to work.

Extending Erlang.mk
-------------------

You may add additional operations to them by using the double
colons. Make will run all targets sharing the same name when
invoked.

``` Makefile
clean::
	@rm anotherfile
```

You can enable verbose mode by calling Make with the variable
`V` set to 1.

``` bash
$ make V=1
```

Parallel execution
------------------

*Parallel execution is currently disabled.*

Parallel execution can be enabled through the use of the
`-j` option. The following output showcases concurrent
downloading of dependencies.

``` bash
$ make -j32
Cloning into '/home/essen/ninenines/cowboy/deps/ranch'...
Cloning into '/home/essen/ninenines/cowboy/deps/cowlib'...
```

The `-O` option will ensure that output from different
targets is grouped, which is particularly useful when
running tests with different frameworks at the same time.
The disadvantage of this option however is that there is
no output until the target is completed.

The``MAKEFLAGS` variable can be used to set it permanently
on your system. It can be set in your `.zshrc`, `.bashrc`
or equivalent file.

``` bash
MAKEFLAGS="-j32 -O"
```

C/C++ compiler plugin
---------------------

This plugin is available by default. It is meant to
simplify the management of projects that include C
and/or C++ source code, like NIFs for example.

If the file `$(C_SRC_DIR)/Makefile` exists, then the plugin
simply calls it when needed. Otherwise it tries to compile
it directly.

You can use a different directory than `./c_src` by setting
the `C_SRC_DIR` variable.

You can override the output file by setting the `C_SRC_OUTPUT`
variable.

You can override the temporary file containing information
about Erlang's environment by setting the `C_SRC_ENV` variable.
This file is automatically generated on first run.

The `CC`, `CXX`, `CFLAGS`, `CXXFLAGS`, `LDLIBS` and `LDFLAGS` variables
may be modified or replaced with any value of your choosing.
The defaults are system dependent.

Common_test plugin
------------------

This plugin is available by default. It adds the following
target:

`ct` runs all test suites for this application.

There is nothing to configure to use it, simply create your
test suites in the `./test/` directory and erlang.mk will
figure everything out automatically.

You can override the list of suites that will run when using
`make tests` by setting the `CT_SUITES` variable.

You can add extra `ct_run` options by defining the `CT_OPTS`
variable. For more information please see `erl -man ct_run`.

You can run an individual test suite by using the special `ct-*`
targets. For example if you have a common_test suite named `spdy`
and you want to run only this suite and not the others, you can
use the `make ct-spdy` command.

Dialyzer plugin
---------------

This plugin is available by default. It adds the following
targets:

`plt` builds the PLT file for this application.

`dialyze` runs Dialyzer.

The PLT file is built in `./$(PROJECT).plt` by default.
You can override this location by setting the `DIALYZER_PLT`
variable.

The `PLT_APPS` variable lists the applications that will be
included in the PLT file. There is no need to specify `erts`,
`kernel`, `stdlib` or the project's dependencies here, as they
are automatically added.

Dialyzer options can be modified by defining the `DIALYZER_OPTS`
variable. The directories to be analyzed can be overriden using
the `DIALYZER_DIRS` variable. It defaults to analyzing source
files recursively found in `src/`. For more information please
see `erl -man dialyzer`.

EDoc plugin
-----------

This plugin is available by default.

EDoc options can be specified in Erlang format by defining
the `EDOC_OPTS` variable. For more information please see
`erl -man edoc`.

Elvis plugin
------------

This plugin is available by default. It adds the following
target:

`elvis` runs Elvis style checker for this application.

The `ELVIS_CONFIG` variable specifies the location of the
configuration file which holds the rules to be applied.
If there's no `elvis.config` file the default one will be
downloaded. When the `ELVIS` variable points to a non-existing
file then the `elvis` executable will be downloaded as well.
Any other option should go in the `ELVIS_OPTS` variable.

ErlyDTL plugin
--------------

This plugin is available by default. It adds automatic
compilation of ErlyDTL templates found in `templates/*.dtl`
or any subdirectory. 

By default it ignores names of subdirectories and compiles 
`a/b/templatename.dtl` into `templatename_dtl.beam`. To include 
subdirectories names in the compiled module name add 
`DTL_FULL_PATH=1` into your Makefile - `a/b/templatename.dtl`
will be compiled into `a_b_templatename_dtl.beam`.

Escript plugin
--------------

This plugin is available by default. It adds the following
target:

`escript` which creates a shell-executable archive named
the same as your `$(PROJECT)`, containing the following files
from your application and its dependencies:

* `*.beam`
* contents of `priv/`
* `sys.config` for your application

There are a number of optional configuration parameters:

* `ESCRIPT_NAME` if a different output file is required
* `ESCRIPT_COMMENT` to alter the comment line in the escript header
* `ESCRIPT_BEAMS` for the paths searched for `*.beam` files to include
* `ESCRIPT_SYS_CONFIG` defaults to `rel/sys.config`
* `ESCRIPT_EMU_ARGS` for the parameters used to start the VM
* `ESCRIPT_SHEBANG` for the line used by your shell to start `escript`
* `ESCRIPT_STATIC` for non-beam directories to be included as well

Refer to http://www.erlang.org/doc/man/escript.html for
more information on `escript` functionality in general.

EUnit plugin
------------

This plugin is available by default. It adds the following
target:

`eunit` which runs all the EUnit tests found in `ebin` or
the test directory specified in `TEST_DIR`.

`EUNIT_OPTS` can be used to specify EUnit-specific options
(e.g. `verbose`) that will be used when calling
`eunit:test/2`. This configuration parameter is empty
by default.. Note that EUnit options are specified as
a comma-separated list of options.

Relx plugin
-----------

This plugin is available by default.

You can change the location of the `relx` executable
(downloaded automatically) by defining the `RELX` variable,
and the location of the configuration file by defining
the `RELX_CONFIG` variable.

The URL used to download `relx` can be overriden by setting
the `RELX_URL` variable.

You can change the generated releases location by setting
the `RELX_OUTPUT_DIR` variable. Any other option should go
in the `RELX_OPTS` variable.

If `RELX_OPTS` includes the `-o` option (instead of using
`RELX_OUTPUT_DIR`, then that option must be the first in
the list, otherwise erlang.mk will fail to find it and
will not be able to clean up the release directory.

Shell plugin
------------

This plugin is available by default.

`SHELL_DEPS` adds the specified modules only when `make shell`
or `make build-shell-deps` is run. For example, to include a module
reloader and TDD test runner, one might add `SHELL_DEPS = tddreloader`
to the Makefile.

You can add extra `erl` options by defining the `SHELL_OPTS` variable.
For more information please see `erl -man erl`.

`SHELL_PATH` adds paths to the shell's library search path. By default
this option sets the paths to `-pa ../$(PROJECT)/ebin $(DEPS_DIR)/*/ebin`.

Triq plugin
-----------

This plugin is available by default. It adds the following
target:

`triq` will check all the properties found in `ebin` or
the test directory specified in `TEST_DIR`.

You can use the `t` variable to give a specific module
or function to run, for example:

``` bash
$ make triq t=cow_http_hd
```

Or:

``` bash
$ make triq t=cow_http_hd:prop_parse_accept
```

Xref plugin
------------

This plugin is available by default. It adds the following
target:

`xref` Erlang Xref Runner (inspired in rebar's rebar_xref)

The `XREF_CONFIG` variable specifies the location of the
configuration file which holds the checks to be applied.
If there is no `xref.config` all `xref` checks will be
applied to the binaries located in the `/ebin` directory.

Contributing
------------

You can contribute by providing feedback, creating patches,
adding packages to the index or new features as plugins.

To add a package to the index, please use the `pkg_add.sh`
script. To use it, first fork the repository, then please
follow the example below:

``` bash
$ git clone https://github.com/$YOURUSERNAME/erlang.mk
$ cd erlang.mk
$ ./pkg_add.sh cowboy git https://github.com/ninenines/cowboy 1.0.0 http://ninenines.eu "Small, fast and modular HTTP server."
$ git push origin master
```

Then open a pull request. The arguments given to the script
are, in order, the project name, the download method used,
the repository URL, the commit/tag/branch/version to pull,
a link to the package's website and finally its description.
Make sure to put double quotes around the description.

You can submit as many packages as you want in one pull
request as long as you follow the instructions above.

For patches or plugins, you have to edit the `core/*.mk`
or `plugins/*.mk` files. If you submit a new plugin, you also
need to add it to the `build.config` file.

Make sure to keep the commit title short, to have a single
commit per package/feature/fix and you're good to submit
a pull request! And again, please don't forget to run make
and to commit the updated erlang.mk or index files along
with your other changes. Thanks!

Support
-------

 *  Official IRC Channel: #ninenines on irc.freenode.net
 *  [Mailing Lists](http://lists.ninenines.eu)