diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 123 |
1 files changed, 111 insertions, 12 deletions
@@ -13,6 +13,7 @@ an Erlang-based build tool, including but not limited to the following: * You want a very fast compilation and test cycle * You want the full power of Unix at your disposal when hooking into your build tool + * You want to be able to easily edit the damn build tool and fix it when it fails * You want to use the deps mechanism with non-Erlang Makefile-based projects * Your project will be part of a larger make or automake based environment @@ -115,6 +116,17 @@ dep_cowboy = git https://github.com/ninenines/cowboy 1.0.0 They will always be compiled using the command `make`. If the dependency does not feature a Makefile, then erlang.mk will be used for building. +For subversion dependencies, the url specifies trunk, branch or +tag. To specify a particular revision, use `@revision` at the end of +the url. No separate specification of branch, tag, or revision is +required or possible. + +``` erlang +DEPS = ex1 ex2 +dep_ex1 = svn https://example.com/svn/trunk/project/ex1 +dep_ex2 = svn svn://example.com/svn/branches/erlang-proj/ex2@264 +``` + You can also specify test-only dependencies. These dependencies will only be downloaded when running `make tests`. The format is the same as above, except the variable `TEST_DEPS` holds the list of test-only dependencies. @@ -127,6 +139,24 @@ dep_ct_helper = git https://github.com/extend/ct_helper.git master Please note that the test dependencies will only be compiled once when they are fetched, unlike the normal dependencies. +Autopatch +--------- + +The autopatch features allows you to automatically fix packages +that are not compatible with erlang.mk. It can also be used to +convert compatible packages to use erlang.mk itself for building +when used as dependency. + +The patching occurs only once, immediately after the package has +been fetched. + +erlang.mk defines a number of packages to be patched. You can add +more packages to the list by appending the `AUTOPATCH` variable. + +``` Makefile +AUTOPATCH += gproc +``` + Releases -------- @@ -194,6 +224,30 @@ You can enable verbose mode by calling Make with the variable $ V=1 make ``` +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" +``` + Core package functionality -------------------------- @@ -201,7 +255,7 @@ The following targets are specific to packages: `pkg-list` lists all packages in the index. -`pkg-search n=STRING` searches the index for STRING. +`pkg-search q=STRING` searches the index for STRING. Packages are downloaded into `DEPS_DIR` (`./deps/` by default). @@ -223,6 +277,9 @@ You can change compilation options by setting the `ERLC_OPTS` variable. It takes the arguments that will then be passed to `erlc`. For more information, please see `erl -man erlc`. +Test target compilation options can be specified in `TEST_ERLC_OPTS`. +It will override `ERLC_OPTS`. + You can specify a list of modules to be compiled first using the `COMPILE_FIRST` variable. @@ -296,7 +353,10 @@ The defaults are system dependent. Common_test plugin ------------------ -This plugin is available by default. +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 @@ -367,7 +427,14 @@ ErlyDTL plugin This plugin is available by default. It adds automatic compilation of ErlyDTL templates found in `templates/*.dtl` -or any subdirectory. +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 -------------- @@ -402,16 +469,14 @@ EUnit plugin This plugin is available by default. It adds the following target: -`eunit` which runs all the EUnit tests found in `ebin` and -any of the additional EUnit directories specified in -`EUNIT_DIR`. +`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 defaults to -`verbose`. Note -that EUnit options are specified as a comma-separated -list of options. +`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 ----------- @@ -451,6 +516,41 @@ 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 ------------ @@ -478,8 +578,7 @@ 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 and then run `make` to create an -updated `erlang.mk`. If you submit a new plugin, you also +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 |