Erlang.mk User Guide

Extension	Location	Description	Output
.dtl	templates/	Django templates	ebin/*.beam
.proto	src/	Protocol buffers	ebin/*.beam

ERLC_OPTS can be used to pass some options to erlc, the Erlang compiler. Erlang.mk does not restrict any option. Please refer to diff --git a/guide/ci.html b/guide/ci.html index 5705b07..998c3cf 100644 --- a/guide/ci.html +++ b/guide/ci.html @@ -33,24 +33,21 @@ div.navfooter{margin-bottom:1em}

Prev		Next

Chapter 21. Continuous integration

Erlang.mk comes with some support for continuous integration, +

Prev		Next

Chapter 22. Continuous integration

Erlang.mk comes with some support for continuous integration, aimed at open source projects that need to support more than one specific Erlang/OTP release. (If you target one specific release, check the OTP version pinning -Section 12.2, “OTP version pinning” -section of the OTP version management -Chapter 12, OTP version management chapter.)

21.1. Configuring Erlang/OTP versions to test

To use the CI plugin you must first configure which versions +section of the OTP version management chapter.)

22.1. Configuring Erlang/OTP versions to test

To use the CI plugin you must first configure which versions of Erlang/OTP will be used. Erlang.mk provides three separate configuration variables depending on whether you need a normal OTP release, a HiPE-enabled release or an ErLLVM-enabled release.

At the time of writing, this is how you would test against all the most recent patch releases of Erlang/OTP 19 and above:

CI_OTP = OTP-19.0.7 OTP-19.1.6 OTP-19.2.3 OTP-19.3.6.2 OTP-20.0.4

If you want to test against HiPE and ErLLVM but only with the latest version of Erlang/OTP, the following could work:

CI_HIPE = $(lastword $(CI_OTP))
-CI_ERLLVM = $(CI_HIPE)

Consult the OTP version management -Chapter 12, OTP version management chapter for more +CI_ERLLVM = $(CI_HIPE)

Consult the OTP version management chapter for more information about Erlang/OTP versions and customization of the -Erlang/OTP builds.

21.2. Running tests across all configured versions

The recommended way to run the ci target is with the option +Erlang/OTP builds.

22.2. Running tests across all configured versions

The recommended way to run the ci target is with the option -k. It will ensure that tests are run for all configured -Erlang/OTP versions, even if there are errors:

$ make ci -k

21.3. Extending the CI targets

The ci target can be extended. For example to run Dialyzer +Erlang/OTP versions, even if there are errors:

$ make ci -k

22.3. Extending the CI targets

The ci target can be extended. For example to run Dialyzer at the end of CI:

ci:: dialyze

Additional setup can be done by extending the ci-setup target. This target is ran before testing each individual Erlang/OTP version.

For example, to ensure dependencies are re-fetched/built diff --git a/guide/compat.html b/guide/compat.html index aa03ab7..18377ee 100644 --- a/guide/compat.html +++ b/guide/compat.html @@ -45,8 +45,7 @@ use Rebar 2 to patch any Rebar project and make it compatible with Erlang.mk. This feature essentially patches Rebar out and adds a Makefile to the project that Erlang.mk can then use for building:

Autoload is documented in more details in the -Packages and dependencies -Chapter 7, Packages and dependencies chapter.

13.2. Erlang.mk projects as Rebar dependencies

Erlang.mk projects can be made compatible with the Rebar family +Packages and dependencies chapter.

13.2. Erlang.mk projects as Rebar dependencies

Erlang.mk projects can be made compatible with the Rebar family of build tools pretty easily, as Erlang.mk will generate all the files they require for building.

The Rebar family requires two files: a rebar.config file containing compilation options and the list of dependencies, diff --git a/guide/contributing.html b/guide/contributing.html index 3a4cb2a..9da6481 100644 --- a/guide/contributing.html +++ b/guide/contributing.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}

Prev

Chapter 28. Contributing

You are welcome and encouraged to contribute.

This is how.

28.1. Priorities

From the most important to the least important:

+
Prev
Chapter 29. Contributing
You are welcome and encouraged to contribute.
This is how.
29.1. Priorities
From the most important to the least important:
- Bugs
- Package issues/additions @@ -41,7 +41,7 @@ Package issues/additions Refactoring
- Features -
28.2. Bugs
If you have found a bug, you should open a ticket. Include +

29.2. Bugs

If you have found a bug, you should open a ticket. Include everything relevant including the command you used, output, a link to the code that triggers the issue, why you think this is a bug, etc.

If you think you have found a bug but you are not sure, you @@ -49,7 +49,7 @@ should open a ticket as previously explained.

If you have found a bug and NOW, open a ticket as previously explained.

Once you have opened a ticket, be patient, try to answer questions in a timely manner and confirm that the bug was indeed fixed when it is.

If you can’t be patient, either try to solve the bug and -contribute the fix back or become a paying customer.

28.3. Code

The code is located in the core/*.mk and plugins/*.mk files. +contribute the fix back or become a paying customer.

29.3. Code

The code is located in the core/*.mk and plugins/*.mk files. The tests are located in the test/Makefile and test/*.mk files.

If you have a fix or a hack for a bug, you should open a pull request. Any fix should include a test case that fails before the fix and is working after.

If you have a test case that reproduces a bug, but no fix for @@ -62,7 +62,7 @@ The value 4 is particular and shows expanded commands right before they are executed.

To run tests in parallel, use the -j option. It is generally a good idea to also use the -k option to run all tests even if one fails. For example: make check -j 32 -k.

Some changes should be tested against all packages. Continue -reading for more details on testing them.

28.4. Packages

You can search existing packages using the make search q=STRING +reading for more details on testing them.

29.4. Packages

You can search existing packages using the make search q=STRING command. This can be done both from an Erlang.mk project or directly from the Erlang.mk repository.

Packages can be added to the index using the pkg_add.sh script.

$ git clone https://github.com/$YOURUSERNAME/erlang.mk
 $ cd erlang.mk
@@ -75,12 +75,11 @@ where PACKAGE is the name of the package, for examp
 This can take a long time. Some packages will fail with certain
 versions of Erlang, or if a prerequisite is missing from your system.
 You can of course speed things up using the -j and -k flags.
After all packages have been tested, you can run the command
-make summary to know what changed since the previous run.

28.5. Documentation

The documentation is always right.

If you think you have found a mistake in the documentation, +make summary to know what changed since the previous run.

29.5. Documentation

The documentation is always right.

If you think you have found a mistake in the documentation, this is a bug. You can either open a ticket or send a pull request.

To make sure that the documentation changes work, install -the listed Requirements -Chapter 14, AsciiDoc documentation on your system and -run make docs.

28.6. Feature requests

If you have an awesome idea or need something that Erlang.mk +the listed Requirements on your system and +run make docs.

29.6. Feature requests

If you have an awesome idea or need something that Erlang.mk doesn’t provide yet, open a ticket. Provide as much detail as possible.

If you have code, great! Open a pull request as previously explained.

If not, you can still improve your feature request by writing diff --git a/guide/coverage.html b/guide/coverage.html index 6ee0436..d269e73 100644 --- a/guide/coverage.html +++ b/guide/coverage.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}

Prev		Next

Chapter 20. Code coverage

Placeholder chapter.

Prev	Up	Next
	Home

Prev		Next

Chapter 21. Code coverage

Placeholder chapter.

Prev	Up	Next
	Home

diff --git a/guide/ct.html b/guide/ct.html index e05a767..3c09784 100644 --- a/guide/ct.html +++ b/guide/ct.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}

Prev		Next

Chapter 19. Common Test

Common Test is Erlang’s functional testing framework. +

Prev		Next

Chapter 19. Common Test

Common Test is Erlang’s functional testing framework. Erlang.mk automates the discovery and running of Common Test suites.

19.1. Writing tests

The Common Test user guide is the best place to learn how to write tests. Erlang.mk @@ -56,9 +56,8 @@ using the variable t. Note that this only applies t suite-specific targets, like the ct-http example above.

To run all tests from the http_compress group in the http_SUITE test suite, write:

$ make ct-http t=http_compress

Similarly, to run a specific test case in that group:

$ make ct-http t=http_compress:headers_dupe

To do the same against a multi-application repository, you can use the -C option:

$ make -C apps/my_app ct-http t=my_group:my_case

Note that this also applies to dependencies. When using Cowboy -as a dependency, you can run the following directly:

$ make -C deps/cowboy ct-http t=http_compress

Finally, code coverage -Chapter 20, Code coverage is available, -but covered in its own chapter.

Prev	Up	Next
	Home

+as a dependency, you can run the following directly:

$ make -C deps/cowboy ct-http t=http_compress

Finally, code coverage is available, +but covered in its own chapter.

Prev	Up	Next
	Home

diff --git a/guide/deps.html b/guide/deps.html index 43d0170..6930352 100644 --- a/guide/deps.html +++ b/guide/deps.html @@ -60,7 +60,6 @@ dep_leveldb = git https://github.com/basho/leveldb 2.1.3

This dependency you could easily copy the resulting shared file into your priv/ directory as part of the build process. More information about that in the NIFs and port drivers -Chapter 8, NIFs and port drivers chapter.

Another variable, LOCAL_DEPS, allows specifying runtime dependencies which are part of Erlang/OTP itself, but also dependencies that are included in the repository. Since they diff --git a/guide/dialyzer.html b/guide/dialyzer.html index 08f7644..3626a75 100644 --- a/guide/dialyzer.html +++ b/guide/dialyzer.html @@ -33,18 +33,18 @@ div.navfooter{margin-bottom:1em}

Prev		Next

Chapter 22. Dialyzer

Dialyzer is a tool that will detect discrepancies in your +

Prev		Next

Chapter 23. Dialyzer

Dialyzer is a tool that will detect discrepancies in your program. It does so using a technique known as success typing analysis which has the advantage of providing no false positives. Dialyzer is able to detect type errors, -dead code and more.

Erlang.mk provides a wrapper around Dialyzer.

22.1. How it works

Dialyzer requires a PLT file to work. The PLT file contains +dead code and more.

Erlang.mk provides a wrapper around Dialyzer.

23.1. How it works

Dialyzer requires a PLT file to work. The PLT file contains the analysis information from all applications which are not expected to change, or rarely do. These would be all the dependencies of the application or applications you are currently working on, including standard applications in Erlang/OTP itself.

Dialyzer can generate this PLT file. Erlang.mk includes rules to automatically generate the PLT file when it is missing.

Once the PLT file is generated, Dialyzer can perform the -analysis in record time.

22.2. Configuration

In a typical usage scenario, no variable needs to be set. +analysis in record time.

23.2. Configuration

In a typical usage scenario, no variable needs to be set. The defaults should be enough. Do note however that the dependencies need to be set properly using the DEPS and LOCAL_DEPS variables.

The DIALYZER_PLT file indicates where the PLT file will @@ -59,7 +59,7 @@ The former one defines which directories should be part of the analysis. The latter defines what extra warnings Dialyzer should report.

Note that Erlang.mk enables the race condition warnings by default. As it can take considerably large resources -to run, you may want to disable it on larger projects.

22.3. Usage

To perform an analysis, run the following command:

$ make dialyze

This will create the PLT file if it doesn’t exist.

The analysis will also be performed when you run the +to run, you may want to disable it on larger projects.

23.3. Usage

To perform an analysis, run the following command:

$ make dialyze

This will create the PLT file if it doesn’t exist.

The analysis will also be performed when you run the following command, alongside tests:

$ make check

You can use the plt target to create the PLT file if it doesn’t exist. This is normally not necessary as Dialyzer creates it automatically.

The PLT file will be removed when you run make distclean.

Prev	Up	Next
	Home

diff --git a/guide/escript.html b/guide/escript.html index 77cffef..7ea67a2 100644 --- a/guide/escript.html +++ b/guide/escript.html @@ -34,11 +34,9 @@ div.navfooter{margin-bottom:1em}

Prev		Next

Chapter 11. Escripts

Escripts are an alternative to release. They are meant to be -used for small command line executables written in Erlang.

They are not self-contained, unlike releases -Chapter 9, Releases. +used for small command line executables written in Erlang.

They are not self-contained, unlike releases. Erlang must be installed for them to run. This however means -that they are fairly small compared to releases.

For self-contained executables, check self-extracting releases -Chapter 10, Self-extracting releases.

11.1. Requirements

Erlang.mk uses p7zip by default to generate the escript +that they are fairly small compared to releases.

For self-contained executables, check self-extracting releases.

11.1. Requirements

Erlang.mk uses p7zip by default to generate the escript archive. Make sure it is installed. On most systems the package is named p7zip; on Ubuntu you need p7zip-full.

If p7zip is unavailable, zip may be used by setting the ESCRIPT_ZIP variable. For example:

$ make escript ESCRIPT_ZIP=zip

11.2. Generating an escript

Run the following command to generate an escript:

$ make escript

This will by default create an escript with the same name as diff --git a/guide/eunit.html b/guide/eunit.html index 363b8fe..eedd8e7 100644 --- a/guide/eunit.html +++ b/guide/eunit.html @@ -70,8 +70,7 @@ the variable t.

For example, to run all tests module (instead of all tests from the entire project), one could write:

$ make eunit t=cow_http_hd

Similarly, to run a specific test case:

$ make eunit t=cow_http_hd:parse_accept_test_

To do the same against a multi-application repository, you can use the -C option:

$ make -C apps/my_app eunit t=my_module:hello_test

Note that this also applies to dependencies. From Cowboy, -you can run the following directly:

$ make -C deps/cowlib eunit t=cow_http_hd

Finally, code coverage -Chapter 20, Code coverage is available, +you can run the following directly:

$ make -C deps/cowlib eunit t=cow_http_hd

Finally, code coverage is available, but covered in its own chapter.

Prev	Up	Next
	Home

diff --git a/guide/getting_started.html b/guide/getting_started.html index 06b92cd..d779c71 100644 --- a/guide/getting_started.html +++ b/guide/getting_started.html @@ -62,8 +62,7 @@ cp .erlang.mk.build/erlang.mk ./erlang.mk rm -rf .erlang.mk.build

This is Erlang.mk bootstrapping itself. Indeed, the file you initially downloaded contains nothing more than the code needed to bootstrap. This operation is done only once. Consult the -Updating Erlang.mk -Chapter 4, Updating Erlang.mk chapter for more +Updating Erlang.mk chapter for more information.

Of course, the generated project can now be compiled:

$ make

Cheers!

2.4. Getting started with OTP libraries

An OTP library is an Erlang application that has no supervision tree. In other words, it is nothing but modules.

This kind of project can also be generated by Erlang.mk, using the bootstrap-lib target:

$ make -f erlang.mk bootstrap-lib

Erlang.mk will once again bootstrap itself and generate all @@ -76,7 +75,6 @@ create a project that will build a release:

$ mak
 commands useful during operations, and put the components
 of the system in separate applications that you will then
 depend on. Consult the Packages and dependencies
-Chapter 7, Packages and dependencies
 chapter for more information.
When you run make from now on, Erlang.mk will compile your
 project and build the release:
$ make
  APP    hello_joe.app.src
@@ -93,7 +91,6 @@ project and build the release:
$ make
 relx, the release building tool. So don’t worry if you see
 more output than above.
If building the release is slow, no need to upgrade your
 hardware just yet. Just consult the Releases
-Chapter 9, Releases
 chapter for various tips to speed up build time during
 development.
You can start the release using the ./_rel/hello_joe_release/bin/hello_joe_release
 script, or simply run make run. The latter will also compile
@@ -135,7 +132,7 @@ boilerplate. It is rarely an issue of course, except when
 creating new modules. That’s why Erlang.mk not only comes with
 templates for generating projects, but also individual modules!
You can list all available templates with the list-templates
 target:
$ make list-templates
-Available templates: cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server ranch_protocol supervisor
To generate a module, let’s say a gen_server, all you need to
+Available templates: cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server gen_statem ranch_protocol supervisor
To generate a module, let’s say a gen_server, all you need to
 do is to call make new with the appropriate arguments:
$ make new t=gen_server n=my_server
This will create a module located in src/my_server.erl
 using the gen_server template.
This module is automatically compiled the next time you run
 make:
$ make
diff --git a/guide/history.html b/guide/history.html
index 5037d3c..17e3741 100644
--- a/guide/history.html
+++ b/guide/history.html
@@ -33,8 +33,8 @@ div.navfooter{margin-bottom:1em}
 
 
 
-Prev     Next
Chapter 27. Short history
This chapter aims to be a brief record of the life of the
-Erlang.mk project.
27.1. Before Erlang.mk
Erlang.mk originates from the Cowboy project. Cowboy started
+
Prev     Next
Chapter 28. Short history
This chapter aims to be a brief record of the life of the
+Erlang.mk project.
28.1. Before Erlang.mk
Erlang.mk originates from the Cowboy project. Cowboy started
 as a Rebar project and I, Loïc Hoguin, was very happy with it
 for a couple years. Over time however I started getting annoyed
 and frustrated by a number of things, including bad defaults,
@@ -46,7 +46,7 @@ than a minute to complete.
Following this success I started removing a lit
 on the fateful day of January 5th, 2013, removed the dependency
 on Rebar entirely. Rebar, and in particular the concept of
 dependencies, was, and still is, a pretty strong influence.
Erlang.mk was conceived.
A few months passed and, on May 1st, 2013, the Erlang.mk
-repository was created. Erlang.mk was born.
Little did I know how much it would grow.
27.2. Lifetime of the project
Erlang.mk would eventually become a much larger file able to
+repository was created. Erlang.mk was born.
Little did I know how much it would grow.
28.2. Lifetime of the project
Erlang.mk would eventually become a much larger file able to
 deal with many more projects than just Cowboy. From the birth
 of the project, the biggest force for growth was user contributions,
 because Erlang.mk appealed to a variety of people with different
diff --git a/guide/index.html b/guide/index.html
index 4550a23..a1c85a0 100644
--- a/guide/index.html
+++ b/guide/index.html
@@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}
 
 

 
-     Next
Erlang.mk User Guide
Loïc Hoguin
<essen@ninenines.eu>
Table of Contents
1. Installation
1.1. On Unix
1.2. On Windows
2. Getting started
2.1. Creating a folder for your project
2.2. Downloading Erlang.mk
2.3. Getting started with OTP applications
2.4. Getting started with OTP libraries
2.5. Getting started with OTP releases
2.6. Getting started from scratch
2.7. Using spaces instead of tabs
2.8. Using templates
2.9. Hiding Erlang.mk from git
2.10. Getting help
3. Overview
3.1. Building your project
3.2. Exploring the package index
3.3. Generating documentation
3.4. Running tests
3.5. Need more?
4. Updating Erlang.mk
4.1. Initial bootstrap
4.2. Updating
4.3. Customizing the build
5. Limitations
5.1. Erlang must be available
5.2. Spaces in path
5.3. Dependency tracking and modification times
I. Code
6. Building
6.1. How to build
6.2. What to build
6.3. Application resource file
6.4. Automatic application resource file values
6.5. File formats
6.6. Compilation options
6.7. Cold and hot builds
6.8. Dependency tracking
6.9. Generating Erlang source
6.10. Cleaning
7. Packages and dependencies
7.1. Searching packages
7.2. Adding dependencies to your project
7.3. How deps are fetched and built
7.4. Fetching and listing dependencies only
7.5. Ignoring unwanted dependencies
7.6. Dependencies directory
7.7. Many applications in one repository
7.8. Repositories with no application at the root level
7.9. Autopatch
7.10. Skipping deps
8. NIFs and port drivers
8.1. C source code location and Erlang environment
8.2. Using a custom Makefile
8.3. Using Erlang.mk directly
8.4. Propagating compile and linker flags to sub-Makefiles
9. Releases
9.1. Setup
9.2. Configuration
9.3. Generating the release
9.4. Running the release
9.5. Upgrading a release
9.6. Getting Relx semver value
10. Self-extracting releases
10.1. Generating the self-extracting archive
10.2. Running the release
11. Escripts
11.1. Requirements
11.2. Generating an escript
11.3. Configuration
11.4. Extra files
11.5. Optimizing for size
12. OTP version management
12.1. Erlang versions
12.2. OTP version pinning
12.3. Continuous integration
12.4. Configuring Kerl
13. Compatibility with other build tools
13.1. Rebar projects as Erlang.mk dependencies
13.2. Erlang.mk projects as Rebar dependencies
II. Documentation
14. AsciiDoc documentation
14.1. Requirements
14.2. Writing AsciiDoc documentation
14.3. Configuration
14.4. Usage
15. EDoc comments
15.1. Writing EDoc comments
15.2. Configuration
15.3. Usage
16. Sphinx documentation
16.1. Writing Sphinx documentation
16.2. Basic setup
16.3. Erlang.mk configuration
16.4. Generating man pages
III. Tests
17. Erlang shell
17.1. Configuration
17.2. Usage
18. EUnit
18.1. Writing tests
18.2. Configuration
18.3. Usage
19. Common Test
19.1. Writing tests
19.2. Configuration
19.3. Usage
20. Code coverage
21. Continuous integration
21.1. Configuring Erlang/OTP versions to test
21.2. Running tests across all configured versions
21.3. Extending the CI targets
22. Dialyzer
22.1. How it works
22.2. Configuration
22.3. Usage
23. Xref
IV. Third-party plugins
24. External plugins
24.1. Loading all plugins from a dependency
24.2. Loading one plugin from a dependency
24.3. Writing external plugins
24.4. Early-stage plugins
24.5. Loading  plugins local to the application
25. List of plugins
25.1. efene.mk
25.2. elixir.mk
25.3. elvis.mk
25.4. geas
25.5. hexer.mk
25.6. hexpm.mk
25.7. jorel
25.8. lfe.mk
25.9. mix.mk
25.10. reload.mk
25.11. rust.mk
V. About Erlang.mk
26. Why Erlang.mk
26.1. Erlang.mk is fast
26.2. Erlang.mk gives you the full power of Unix
26.3. Erlang.mk is a text file
26.4. Erlang.mk can manage Erlang itself
26.5. Erlang.mk can do more than Erlang
26.6. Erlang.mk integrates nicely in Make and Automake projects
27. Short history
27.1. Before Erlang.mk
27.2. Lifetime of the project
28. Contributing
28.1. Priorities
28.2. Bugs
28.3. Code
28.4. Packages
28.5. Documentation
28.6. Feature requests
     Next
+     Next
Erlang.mk User Guide
Loïc Hoguin
<essen@ninenines.eu>
Table of Contents
1. Installation
1.1. On Unix
1.2. On Windows
2. Getting started
2.1. Creating a folder for your project
2.2. Downloading Erlang.mk
2.3. Getting started with OTP applications
2.4. Getting started with OTP libraries
2.5. Getting started with OTP releases
2.6. Getting started from scratch
2.7. Using spaces instead of tabs
2.8. Using templates
2.9. Hiding Erlang.mk from git
2.10. Getting help
3. Overview
3.1. Building your project
3.2. Exploring the package index
3.3. Generating documentation
3.4. Running tests
3.5. Need more?
4. Updating Erlang.mk
4.1. Initial bootstrap
4.2. Updating
4.3. Customizing the build
5. Limitations
5.1. Erlang must be available
5.2. Spaces in path
5.3. Dependency tracking and modification times
I. Code
6. Building
6.1. How to build
6.2. What to build
6.3. Application resource file
6.4. Automatic application resource file values
6.5. File formats
6.6. Compilation options
6.7. Cold and hot builds
6.8. Dependency tracking
6.9. Generating Erlang source
6.10. Cleaning
7. Packages and dependencies
7.1. Searching packages
7.2. Adding dependencies to your project
7.3. How deps are fetched and built
7.4. Fetching and listing dependencies only
7.5. Ignoring unwanted dependencies
7.6. Dependencies directory
7.7. Many applications in one repository
7.8. Repositories with no application at the root level
7.9. Autopatch
7.10. Skipping deps
8. NIFs and port drivers
8.1. C source code location and Erlang environment
8.2. Using a custom Makefile
8.3. Using Erlang.mk directly
8.4. Propagating compile and linker flags to sub-Makefiles
9. Releases
9.1. Setup
9.2. Configuration
9.3. Generating the release
9.4. Running the release
9.5. Upgrading a release
9.6. Getting Relx semver value
10. Self-extracting releases
10.1. Generating the self-extracting archive
10.2. Running the release
11. Escripts
11.1. Requirements
11.2. Generating an escript
11.3. Configuration
11.4. Extra files
11.5. Optimizing for size
12. OTP version management
12.1. Erlang versions
12.2. OTP version pinning
12.3. Continuous integration
12.4. Configuring Kerl
13. Compatibility with other build tools
13.1. Rebar projects as Erlang.mk dependencies
13.2. Erlang.mk projects as Rebar dependencies
II. Documentation
14. AsciiDoc documentation
14.1. Requirements
14.2. Writing AsciiDoc documentation
14.3. Configuration
14.4. Usage
15. EDoc comments
15.1. Writing EDoc comments
15.2. Configuration
15.3. Usage
16. Sphinx documentation
16.1. Writing Sphinx documentation
16.2. Basic setup
16.3. Erlang.mk configuration
16.4. Generating man pages
III. Tests
17. Erlang shell
17.1. Configuration
17.2. Usage
18. EUnit
18.1. Writing tests
18.2. Configuration
18.3. Usage
19. Common Test
19.1. Writing tests
19.2. Configuration
19.3. Usage
20. Triq
21. Code coverage
22. Continuous integration
22.1. Configuring Erlang/OTP versions to test
22.2. Running tests across all configured versions
22.3. Extending the CI targets
23. Dialyzer
23.1. How it works
23.2. Configuration
23.3. Usage
24. Xref
IV. Third-party plugins
25. External plugins
25.1. Loading all plugins from a dependency
25.2. Loading one plugin from a dependency
25.3. Writing external plugins
25.4. Early-stage plugins
25.5. Loading  plugins local to the application
26. List of plugins
26.1. efene.mk
26.2. elixir.mk
26.3. elvis.mk
26.4. geas
26.5. hexer.mk
26.6. hexpm.mk
26.7. jorel
26.8. lfe.mk
26.9. mix.mk
26.10. reload.mk
26.11. rust.mk
V. About Erlang.mk
27. Why Erlang.mk
27.1. Erlang.mk is fast
27.2. Erlang.mk gives you the full power of Unix
27.3. Erlang.mk is a text file
27.4. Erlang.mk can manage Erlang itself
27.5. Erlang.mk can do more than Erlang
27.6. Erlang.mk integrates nicely in Make and Automake projects
28. Short history
28.1. Before Erlang.mk
28.2. Lifetime of the project
29. Contributing
29.1. Priorities
29.2. Bugs
29.3. Code
29.4. Packages
29.5. Documentation
29.6. Feature requests
     Next
 
 
 
diff --git a/guide/kerl.html b/guide/kerl.html
index 35ec324..72a0aa5 100644
--- a/guide/kerl.html
+++ b/guide/kerl.html
@@ -62,8 +62,7 @@ use the version you configured.
Note that there has been reports that this
 is not compatible with the .ONESHELL feature from
 GNU Make.
12.3. Continuous integration
Erlang.mk can automatically test your project against
 many different Erlang/OTP versions. This functionality
-is documented in the Continuous integration
-Chapter 21, Continuous integration chapter.
12.4. Configuring Kerl
All of the Kerl variables can be configured directly in the
+is documented in the Continuous integration chapter.
12.4. Configuring Kerl
All of the Kerl variables can be configured directly in the
 Makefile. All you need to do is to export them. For example,
 to change the installation directory for the Erlang/OTP
 versions managed by Kerl, you could add the following to
diff --git a/guide/overview.html b/guide/overview.html
index 1c6f842..87768e4 100644
--- a/guide/overview.html
+++ b/guide/overview.html
@@ -37,51 +37,34 @@ div.navfooter{margin-bottom:1em}
 what Erlang.mk can do for you.
3.1. Building your project
Erlang.mk is first and foremost a build tool. It is especially
 tailored for Erlang developers and follows widely accepted
 practices in the Erlang community.
Erlang.mk will happily build all Erlang-specific files
-Chapter 6, Building
 you throw at it. Other kinds of files too, like C or C++ code
-when you are working on a NIF or a port driver
-Chapter 8, NIFs and port drivers.
Erlang.mk embraces the concept of source dependencies
-Chapter 7, Packages and dependencies.
+when you are working on a NIF or a port driver.
Erlang.mk embraces the concept of source dependencies.
 It can fetch dependency source code using a variety of mechanisms,
 including fetching from Git, Mercurial or SVN.
Erlang.mk will automatically generate releases
-Chapter 9, Releases
-when applicable. It can also generate escripts
-Chapter 11, Escripts.
3.2. Exploring the package index
Erlang.mk comes with a built-in package index
-Chapter 7, Packages and dependencies.
+when applicable. It can also generate escripts.
3.2. Exploring the package index
Erlang.mk comes with a built-in package index.
 It is built as an extension of the dependency system and is
 meant to be used for discovery purposes.
No package is ever installed, they are only used as dependencies
 and are always project-specific. They can be thought of as a
 shortcut over plain dependencies.
You can get a list of all packages known to Erlang.mk by using
 the search target:
$ make search
You can also use this target to search across all packages, for
-example to find all packages related to Cowboy:
$ make search q=cowboy
3.3. Generating documentation
Erlang.mk supports EDoc and Asciidoc.
EDoc
-Chapter 15, EDoc comments generates HTML documentation directly from
+example to find all packages related to Cowboy:
$ make search q=cowboy
3.3. Generating documentation
Erlang.mk supports EDoc and Asciidoc.
EDoc generates HTML documentation directly from
 your source code.
While it is convenient, ask yourself: if all the documentation is
 inside the source code, why not just open the source code directly?
-That’s where Asciidoc comes in.
The Asciidoc
-Chapter 14, AsciiDoc documentation plugin expects all documentation
+That’s where Asciidoc comes in.
The Asciidoc plugin expects all documentation
 to be separate from source. It will generate HTML, PDF, man pages and
 more from the documentation you write in the doc/src/ folder in
 your repository.
3.4. Running tests
Erlang.mk supports a lot of different testing and static
-analysis tools.
The make shell
-Chapter 17, Erlang shell command allows you
+analysis tools.
The make shell command allows you
 to test your project manually. You can automate these
-unit tests with EUnit
-Chapter 18, EUnit and test
-your entire system with Common Test
-Chapter 19, Common Test.
-Code coverage
-Chapter 20, Code coverage can of course
+unit tests with EUnit and test
+your entire system with Common Test.
+Code coverage can of course
 be enabled during tests.
Erlang.mk comes with features to make your life easier when
-setting up and using Continuous integration
-Chapter 21, Continuous integration.
On the static analysis side of things, Erlang.mk comes with
-support for Dialyzer
-Chapter 22, Dialyzer and Xref
-Chapter 23, Xref,
+setting up and using Continuous integration.
On the static analysis side of things, Erlang.mk comes with
+support for Dialyzer and Xref,
 to perform success typing analysis and cross referencing
-of the code.
3.5. Need more?
Not convinced yet? You can read about why you should use Erlang.mk
-Chapter 26, Why Erlang.mk
-and its history
-Chapter 27, Short history. And if you’re still not
+of the code.
3.5. Need more?
Not convinced yet? You can read about why you should use Erlang.mk
+and its history. And if you’re still not
 convinced after that, it’s OK! The world would be boring if
 everyone agreed on everything all the time.
Prev     Next
  Home  
 
diff --git a/guide/plugins_list.html b/guide/plugins_list.html
index cc17f63..2a4e5bc 100644
--- a/guide/plugins_list.html
+++ b/guide/plugins_list.html
@@ -33,21 +33,21 @@ div.navfooter{margin-bottom:1em}
 
 
 
-Prev     Next
Chapter 25. List of plugins
This is a non-exhaustive list of Erlang.mk plugins, sorted
-alphabetically.
25.1. efene.mk
An Efene plugin for Erlang.mk.
-Efene is an alternative language for the BEAM.
25.2. elixir.mk
An Elixir plugin for
+
Prev     Next
Chapter 26. List of plugins
This is a non-exhaustive list of Erlang.mk plugins, sorted
+alphabetically.
26.1. efene.mk
An Efene plugin for Erlang.mk.
+Efene is an alternative language for the BEAM.
26.2. elixir.mk
An Elixir plugin for
 Erlang.mk. Elixir is an alternative
-language for the BEAM.
25.3. elvis.mk
An Elvis plugin for Erlang.mk.
-Elvis is an Erlang style reviewer.
25.4. geas
Geas gives aggregated
+language for the BEAM.
26.3. elvis.mk
An Elvis plugin for Erlang.mk.
+Elvis is an Erlang style reviewer.
26.4. geas
Geas gives aggregated
 information on a project and its dependencies, and is available
-as an Erlang.mk plugin.
25.5. hexer.mk
An Hex plugin for Erlang.mk
-using the hexer tool.
25.6. hexpm.mk
Another Hex plugin for
-Erlang.mk, with support for Hex dependency operators.
25.7. jorel
Jorel is Just anOther RELease
-assembler for Erlang/OTP, and is available as an Erlang.mk plugin.
25.8. lfe.mk
An LFE plugin for Erlang.mk.
+as an Erlang.mk plugin.
26.5. hexer.mk
An Hex plugin for Erlang.mk
+using the hexer tool.
26.6. hexpm.mk
Another Hex plugin for
+Erlang.mk, with support for Hex dependency operators.
26.7. jorel
Jorel is Just anOther RELease
+assembler for Erlang/OTP, and is available as an Erlang.mk plugin.
26.8. lfe.mk
An LFE plugin for Erlang.mk.
 LFE, or Lisp Flavoured Erlang, is an alternative
-language for the BEAM.
25.9. mix.mk
A Mix plugin for Erlang.mk,
+language for the BEAM.
26.9. mix.mk
A Mix plugin for Erlang.mk,
 to generate a compatible configuration file for
-Mix.
25.10. reload.mk
A live reload plugin for Erlang.mk.
25.11. rust.mk
A plugin to build Rust crates and install binaries into priv/.
Prev  Up  Next
  Home  
+Mix.
26.10. reload.mk
A live reload plugin for Erlang.mk.
26.11. rust.mk
A plugin to build Rust crates and install binaries into priv/.
Prev  Up  Next
  Home  
 
 
 
diff --git a/guide/plugins_usage.html b/guide/plugins_usage.html
index aaf5af7..c78e48b 100644
--- a/guide/plugins_usage.html
+++ b/guide/plugins_usage.html
@@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}
 
 
 
-Prev     Next
Chapter 24. External plugins
It is often convenient to be able to keep the build files
+
Prev     Next
Chapter 25. External plugins
It is often convenient to be able to keep the build files
 used by all your projects in one place. Those files could
 be Makefiles, configuration files, templates and more.
Erlang.mk allows you to automatically load plugins from
 dependencies. Plugins can do anything, including defining
@@ -42,19 +42,19 @@ inside the normal Erlang.mk processing or even adding new
 rules.
You can load plugins using one of two methods. You can
 either load all plugins from a dependency, or just one.
 We will also cover conventions about writing external
-plugins.
24.1. Loading all plugins from a dependency
To load plugins from a dependency, all you need to do is add
+plugins.
25.1. Loading all plugins from a dependency
To load plugins from a dependency, all you need to do is add
 the dependency name to DEP_PLUGINS in addition to the list
 of dependencies.
For example, if you have cowboy in DEPS, add cowboy in
 DEP_PLUGINS also:
DEPS = cowboy
 DEP_PLUGINS = cowboy
This will load the file plugins.mk in the root folder of
-the Cowboy repository.
24.2. Loading one plugin from a dependency
Now that we know how to load all plugins, let’s take a look
+the Cowboy repository.
25.2. Loading one plugin from a dependency
Now that we know how to load all plugins, let’s take a look
 at how to load one specific plugin from a dependency.
To do this, instead of writing only the name of the dependency,
 we will write its name and the path to the plugin file. This
 means that writing DEP_PLUGINS = cowboy is equivalent to
 writing DEP_PLUGINS = cowboy/plugins.mk.
Knowing this, if we were to load the plugin mk/dist.mk
 from Cowboy and no other, we would write the following in
 our Makefile:
DEPS = cowboy
-DEP_PLUGINS = cowboy/mk/dist.mk
24.3. Writing external plugins
The plugins.mk file is a convention. It is meant to load
+DEP_PLUGINS = cowboy/mk/dist.mk

		Next

		Next

25.3. Writing external plugins

The plugins.mk file is a convention. It is meant to load all the plugins from the dependency. The code for the plugin can be written directly in plugins.mk or be separate.

If you are providing more than one plugin with your repository, the recommended way is to create one file per plugin in the @@ -65,7 +65,7 @@ file:

THIS := $(dir $(realpath $(lastword $(MAKEF
 include $(THIS)/mk/dist.mk
 include $(THIS)/mk/templates.mk

The THIS variable is required to relatively include files.

This allows users to not only be able to select individual plugins, but also select all plugins from the dependency -in one go if they wish to do so.

24.4. Early-stage plugins

Plugins declared in DEP_PLUGINS are loaded near the end of Erlang.mk. +in one go if they wish to do so.

25.4. Early-stage plugins

Plugins declared in DEP_PLUGINS are loaded near the end of Erlang.mk. That’s why you have access to all previously initialized variables. However, if you want your plugin to add common dependencies to your applications, a regular is loaded too late in the process. @@ -79,7 +79,7 @@ BUILD_DEPS = common_deps DEP_EARLY_PLUGINS = common_deps

# In the plugin's early-plugins.mk
 DEPS += cowboy
 TEST_DEPS = ct_helper
-dep_ct_helper = git https://github.com/ninenines/ct_helper master

24.5. Loading plugins local to the application

If the Erlang.mk plugin lives in the same directory or repository as your +dep_ct_helper = git https://github.com/ninenines/ct_helper master

25.5. Loading plugins local to the application

If the Erlang.mk plugin lives in the same directory or repository as your application or library, then you can load it exactly like an external plugin: the dependency name is simply the name of your application or library.

For example, the following Makefile loads a plugin in the mk diff --git a/guide/sfx.html b/guide/sfx.html index 6aff580..e31cb98 100644 --- a/guide/sfx.html +++ b/guide/sfx.html @@ -33,8 +33,7 @@ div.navfooter{margin-bottom:1em}

Prev		Next

Chapter 10. Self-extracting releases

Erlang.mk allows you to package Relx releases -Chapter 9, Releases as +

Prev		Next

Chapter 10. Self-extracting releases

Erlang.mk allows you to package Relx releases as self-extracting archives. These archives contain all the files in the release and come in the form of a script that will extract and run the release automatically.

This allows you to package the release as a single file diff --git a/guide/shell.html b/guide/shell.html index 791a2ee..0d389a5 100644 --- a/guide/shell.html +++ b/guide/shell.html @@ -42,7 +42,9 @@ To continue with our example, if you want to use kjel shell, you also need to change SHELL_ERL and point it to the kjell executable:

SHELL_ERL = $(DEPS_DIR)/kjell/bin/kjell

You can specify additional options to be used when starting the shell using the SHELL_OPTS variable:

SHELL_OPTS = -setcookie chocolate

Any of the usual erl options can be used, including -eval:

SHELL_OPTS = -eval 'my_app:run()'

17.2. Usage

To start the shell, all you need is the following command:

$ make shell

The shell can be stopped as usual with a double Ctrl+C or the -command q()..

Prev	Up	Next
	Home

+command q()..
Note that the shell target does not build the application. To do it, +use either the app target or, if you want to include also test +modules, the test-build target.

Prev	Up	Next
	Home

diff --git a/guide/triq.html b/guide/triq.html new file mode 100644 index 0000000..dde4b76 --- /dev/null +++ b/guide/triq.html @@ -0,0 +1,41 @@ + + + + +Erlang.mk User Guide + + + +
+
+ User guide + Tutorials +
+ +
+ 470+ packages + Issues? +
+
+
+ +
Prev Next
Chapter 20. Triq
Triq is a QuickCheck-like library for +property-based testing. Erlang.mk automates discovery and checking of +Triq properties.
To run all tests (including Triq):
$ make tests
To run all tests and static checks (including Triq):
$ make check
You can also run Triq separately:
$ make triq
To check properties from a single module:
$ make triq t=foo_tests
To check a single property:
$ make triq t=foo_tests:bar
Prev Up Next
Home
+
+ + diff --git a/guide/why.html b/guide/why.html index 919182d..f7a9bdb 100644 --- a/guide/why.html +++ b/guide/why.html @@ -33,15 +33,14 @@ div.navfooter{margin-bottom:1em}
-
Prev Next
Chapter 26. Why Erlang.mk
Why would you choose Erlang.mk, if not for its -many features -Chapter 3, Overview? This chapter will -attempt to answer that.
26.1. Erlang.mk is fast
Erlang.mk is as fast as it gets.
Erlang.mk will group the compilation of files so as to avoid +
Prev Next
Chapter 27. Why Erlang.mk
Why would you choose Erlang.mk, if not for its +many features? This chapter will +attempt to answer that.
27.1. Erlang.mk is fast
Erlang.mk is as fast as it gets.
Erlang.mk will group the compilation of files so as to avoid running the BEAM more than necessary. This saves many seconds compared to traditional Makefiles, even on small projects.
Erlang.mk will not try to be too smart. It provides a simple solution that works for most people, and gives additional options for projects that run into edge cases, often in the -form of extra variables or rules to be defined.
26.2. Erlang.mk gives you the full power of Unix
Erlang.mk is a Makefile.
You could use Erlang.mk directly without configuring anything +form of extra variables or rules to be defined.
27.2. Erlang.mk gives you the full power of Unix
Erlang.mk is a Makefile.
You could use Erlang.mk directly without configuring anything and it would just work. But you can also extend it greatly either through configuration or hooks, and you can of course add your own rules to the Makefile.
In all cases: for configuration, hooks or custom rules, you @@ -49,22 +48,22 @@ have all the power of Unix at your disposal, and can call any utility or even any language interpreter you want, every time you need to. Erlang.mk also allows you to write scripts in this small language called Erlang directly inside -your Makefile if you ever need to…
26.3. Erlang.mk is a text file
Erlang.mk is a Makefile.
Which means Erlang.mk is a simple text file. You can edit a +your Makefile if you ever need to…
27.3. Erlang.mk is a text file
Erlang.mk is a Makefile.
Which means Erlang.mk is a simple text file. You can edit a text file. Nothing stops you. If you run into any bug, or behavior that does not suit you, you can just open the erlang.mk file in your favorite editor, fix and/or comment -a few lines, save, and try again. It’s as simple as it gets.
Currently using a binary build tool? Good luck with that.
26.4. Erlang.mk can manage Erlang itself
Erlang.mk isn’t written in Erlang.
That’s not a good thing, you say? Well, here’s one thing +a few lines, save, and try again. It’s as simple as it gets.
Currently using a binary build tool? Good luck with that.
27.4. Erlang.mk can manage Erlang itself
Erlang.mk isn’t written in Erlang.
That’s not a good thing, you say? Well, here’s one thing that Erlang.mk and Makefiles can do for you that Erlang build tool can’t easily: choose what version of Erlang is to be used for compiling the project.
This really is a one-liner in Erlang.mk (a few more lines if you also let it download and build Erlang directly) and allows for even greater things, like testing your project across all supported Erlang versions in one small -command: make -k ci.
26.5. Erlang.mk can do more than Erlang
Erlang.mk doesn’t care what your dependencies are written in.
Erlang.mk will happily compile any dependency, as long as +command: make -k ci.
27.5. Erlang.mk can do more than Erlang
Erlang.mk doesn’t care what your dependencies are written in.
Erlang.mk will happily compile any dependency, as long as they come with a Makefile. The dependency can be written in C, C++ or even Javascript… Who cares, really? If you need Erlang.mk to fetch it, then Erlang.mk will fetch it -and compile it as needed.
26.6. Erlang.mk integrates nicely in Make and Automake projects
If you are planning to put your project in the middle of +and compile it as needed.
27.6. Erlang.mk integrates nicely in Make and Automake projects
If you are planning to put your project in the middle of a Make or Automake-based build environment, then the most logical thing to do is to use a Makefile.
Erlang.mk will happily sit in such an environment and behave as you expect it to.
Prev Up Next
Home
diff --git a/guide/xref.html b/guide/xref.html index 3440412..a4a9aff 100644 --- a/guide/xref.html +++ b/guide/xref.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}
-
Prev Next
Chapter 23. Xref
Placeholder chapter.
Prev Up Next
Home
+
Prev Next
Chapter 24. Xref
Placeholder chapter.
Prev Up Next
Home

-- cgit v1.2.3

Chapter 6. Building

6.1. How to build

6.1. How to build

6.2.2. Dependencies

6.2.3. Release

6.3. Application resource file

6.3.2. Legacy method

6.3.2. Application environment

6.3.3. Legacy method

6.6. Compilation options

6.6.1. ERLC_OPTS

Chapter 21. Continuous integration

Chapter 22. Continuous integration

21.1. Configuring Erlang/OTP versions to test

22.1. Configuring Erlang/OTP versions to test

21.2. Running tests across all configured versions

22.2. Running tests across all configured versions

21.3. Extending the CI targets

22.3. Extending the CI targets

13.2. Erlang.mk projects as Rebar dependencies

13.2. Erlang.mk projects as Rebar dependencies

Chapter 28. Contributing

28.1. Priorities

Chapter 29. Contributing

29.1. Priorities

28.2. Bugs

29.2. Bugs

28.3. Code

29.3. Code

28.4. Packages

29.4. Packages

28.5. Documentation

29.5. Documentation

28.6. Feature requests

29.6. Feature requests

Chapter 20. Code coverage

Chapter 21. Code coverage

Chapter 19. Common Test

Chapter 19. Common Test

19.1. Writing tests

Chapter 22. Dialyzer

Chapter 23. Dialyzer

22.1. How it works

23.1. How it works

22.2. Configuration

23.2. Configuration

22.3. Usage

23.3. Usage

Chapter 11. Escripts

11.1. Requirements

11.1. Requirements

11.2. Generating an escript

2.4. Getting started with OTP libraries

Chapter 27. Short history

27.1. Before Erlang.mk

Chapter 28. Short history

28.1. Before Erlang.mk

27.2. Lifetime of the project

28.2. Lifetime of the project

Erlang.mk User Guide

Loïc Hoguin

Erlang.mk User Guide

Loïc Hoguin

12.3. Continuous integration

12.4. Configuring Kerl

12.4. Configuring Kerl

3.1. Building your project

3.2. Exploring the package index

3.2. Exploring the package index

3.3. Generating documentation

3.3. Generating documentation

3.4. Running tests

3.5. Need more?

3.5. Need more?

Chapter 25. List of plugins

25.1. efene.mk

25.2. elixir.mk

Chapter 26. List of plugins

26.1. efene.mk

26.2. elixir.mk