From 463f04d2cfb806c858c786931cb905ac77629cfa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Sat, 29 Oct 2016 17:23:10 +0300 Subject: Update user guide --- guide/asciidoc.html | 10 ++++---- guide/ci.html | 2 +- guide/compat.html | 10 ++++---- guide/contributing.html | 16 ++++++------- guide/coverage.html | 2 +- guide/ct.html | 12 +++++----- guide/dialyzer.html | 8 +++---- guide/edoc.html | 8 +++---- guide/escript.html | 2 +- guide/eunit.html | 12 +++++----- guide/history.html | 6 ++--- guide/index.html | 2 +- guide/overview.html | 46 ++++++++++++++++++------------------- guide/plugins_list.html | 22 +++++++++--------- guide/plugins_usage.html | 8 +++---- guide/relx.html | 6 ++--- guide/sfx.html | 59 ++++++++++++++++++++++++++++++++++++++++++++++++ guide/shell.html | 6 ++--- guide/why.html | 14 ++++++------ guide/xref.html | 2 +- 20 files changed, 156 insertions(+), 97 deletions(-) create mode 100644 guide/sfx.html diff --git a/guide/asciidoc.html b/guide/asciidoc.html index c24810f..0fcb434 100644 --- a/guide/asciidoc.html +++ b/guide/asciidoc.html @@ -33,12 +33,12 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 12. AsciiDoc documentation

Erlang.mk provides rules for generating documentation from +

Prev   Next

Chapter 13. AsciiDoc documentation

Erlang.mk provides rules for generating documentation from AsciiDoc files. It can automatically build a user guide PDF, -chunked HTML documentation and Unix manual pages.

12.1. Requirements

It is necessary to have AsciiDoc, +chunked HTML documentation and Unix manual pages.

13.1. Requirements

It is necessary to have AsciiDoc, xsltproc and dblatex installed on your -system for Erlang.mk to generate documentation from AsciiDoc sources.

12.2. Writing AsciiDoc documentation

AsciiDoc is a text document format for +system for Erlang.mk to generate documentation from AsciiDoc sources.

13.2. Writing AsciiDoc documentation

AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page.

The AsciiDoc user guide @@ -48,8 +48,8 @@ file is doc/src/guide/ for the user guide, and doc/src/manual/ for the function reference. In the case of the user guide, the entry point is always doc/src/guide/book.asciidoc.

For manual pages, it is good practice to use section 3 for -modules, and section 7 for the application itself.

12.3. Configuration

All of the AsciiDoc related configuration can be done directly -inside the files themselves.

12.4. Usage

To build all documentation:

$ make docs

To build only the AsciiDoc documentation:

$ make asciidoc

To build only the user guide:

$ make asciidoc-guide

To build only the manual:

$ make asciidoc-manual

To install man pages on Unix:

$ make install-docs

Erlang.mk allows customizing the installation path and sections +modules, and section 7 for the application itself.

13.3. Configuration

All of the AsciiDoc related configuration can be done directly +inside the files themselves.

13.4. Usage

To build all documentation:

$ make docs

To build only the AsciiDoc documentation:

$ make asciidoc

To build only the user guide:

$ make asciidoc-guide

To build only the manual:

$ make asciidoc-manual

To install man pages on Unix:

$ make install-docs

Erlang.mk allows customizing the installation path and sections of the man pages to be installed. The MAN_INSTALL_PATH variable defines where man pages will be installed. It defaults to /usr/local/share/man. The MAN_SECTIONS variable defines diff --git a/guide/ci.html b/guide/ci.html index cf3ed50..73b786c 100644 --- a/guide/ci.html +++ b/guide/ci.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}

-
Prev   Next

Chapter 18. Continuous integration

Placeholder chapter.

Prev Up Next
 Home 
+
Prev   Next

Chapter 19. Continuous integration

Placeholder chapter.

Prev Up Next
 Home 
diff --git a/guide/compat.html b/guide/compat.html index 298caef..4c1c80d 100644 --- a/guide/compat.html +++ b/guide/compat.html @@ -33,25 +33,25 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 11. Compatibility with other build tools

Erlang.mk tries its best to be compatible with the other Erlang +

Prev   Next

Chapter 12. Compatibility with other build tools

Erlang.mk tries its best to be compatible with the other Erlang build tools. It can use dependencies written with other build tools in mind, and can also make your projects usable by those build tools as well. Erlang.mk is like the cool kid that gets along with everybody.

In this chapter I will use the term Rebar project to refer to a project built using Rebar 2, Rebar 3 or Mad. These three build tools are very similar and share the same configuration -file.

11.1. Rebar projects as Erlang.mk dependencies

Erlang.mk comes with a feature called Autoload which will +file.

12.1. Rebar projects as Erlang.mk dependencies

Erlang.mk comes with a feature called Autoload which will 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.

11.2. Erlang.mk projects as Rebar dependencies

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

12.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, and the application resource file, found either at -ebin/$(PROJECT).app or at src/$(PROJECT).app.src.

11.2.1. Rebar configuration

Erlang.mk comes with a target that generates a rebar.config +ebin/$(PROJECT).app or at src/$(PROJECT).app.src.

12.2.1. Rebar configuration

Erlang.mk comes with a target that generates a rebar.config file when invoked:

$ make rebar.config

Careful! This will build the file even if it already existed before.

To build this file, Erlang.mk uses information it finds in the DEPS and ERLC_OPTS variables, among others. This @@ -66,7 +66,7 @@ target:

app:: rebar.config

Don’t forget feature specific to Erlang.mk, like the cp fetch method. It could also be that we forgot to handle something! Sorry. We are of course interested to hear about any compatibility -problems you may have, just open a ticket!

11.2.2. Application resource file

Erlang.mk has two ways to generate an application resource +problems you may have, just open a ticket!

12.2.2. Application resource file

Erlang.mk has two ways to generate an application resource file: from the information found in the Makefile, or from the information found in the src/$(PROJECT).app.src file. Needless to say, if you have this file in your repository, diff --git a/guide/contributing.html b/guide/contributing.html index 0c49ce3..1bae5e9 100644 --- a/guide/contributing.html +++ b/guide/contributing.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}

-
Prev   

Chapter 25. Contributing

You are welcome and encouraged to contribute.

This is how.

25.1. Priorities

From the most important to the least important:

  • +
    Prev   

    Chapter 26. Contributing

    You are welcome and encouraged to contribute.

    This is how.

    26.1. Priorities

    From the most important to the least important:

    • Bugs
    • Package issues/additions @@ -41,7 +41,7 @@ Package issues/additions Refactoring
    • Features -

    25.2. Bugs

    If you have found a bug, you should open a ticket. Include +

26.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.

25.3. Code

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

26.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.

25.4. Packages

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

26.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,12 @@ 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.

25.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.

26.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 12, AsciiDoc documentation on your system and -run make docs.

25.6. Feature requests

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

26.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 46e1bba..b992588 100644 --- a/guide/coverage.html +++ b/guide/coverage.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}

-
Prev   Next

Chapter 17. Code coverage

Placeholder chapter.

Prev Up Next
 Home 
+
Prev   Next

Chapter 18. Code coverage

Placeholder chapter.

Prev Up Next
 Home 
diff --git a/guide/ct.html b/guide/ct.html index 2a0a592..ad63374 100644 --- a/guide/ct.html +++ b/guide/ct.html @@ -33,13 +33,13 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 16. Common Test

Common Test is Erlang’s functional testing framework. +

Prev   Next

Chapter 17. Common Test

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

16.1. Writing tests

The Common Test user guide +Test suites.

17.1. Writing tests

The Common Test user guide is the best place to learn how to write tests. Erlang.mk requires that file names for test suites end with _SUITE.erl and that the files be located in the $(TEST_DIR) directory. -This defaults to test/.

16.2. Configuration

The CT_OPTS variable allows you to set extra Common Test +This defaults to test/.

17.2. Configuration

The CT_OPTS variable allows you to set extra Common Test options. Options are documented in the Common Test user guide. You can use it to set Common Test hooks, for example:

CT_OPTS = -ct_hooks cowboy_ct_hook

The CT_SUITES variable can be used to override what @@ -47,7 +47,7 @@ Common Test suites Erlang.mk will be aware of. It does not normally need to be set as Erlang.mk will find the test suites automatically.

The name of the suite is the part before _SUITE.erl. If the file is named http_SUITE.erl, the test suite -is http:

CT_SUITES = http ws

16.3. Usage

To run all tests (including Common Test):

$ make tests

To run all tests and static checks (including Common Test):

$ make check

You can also run Common Test separately:

$ make ct

Erlang.mk will create targets for all test suites it finds. +is http:

CT_SUITES = http ws

17.3. Usage

To run all tests (including Common Test):

$ make tests

To run all tests and static checks (including Common Test):

$ make check

You can also run Common Test separately:

$ make ct

Erlang.mk will create targets for all test suites it finds. If you have a file named test/http_SUITE.erl, then the target ct-http will run that specific test suite:

$ make ct-http

Erlang.mk provides a convenient way to run a specific group or a specific test case within a specific group, @@ -55,8 +55,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 17, Code coverage is available, +as a dependency, you can run the following directly:

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

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

Prev Up Next
 Home 
diff --git a/guide/dialyzer.html b/guide/dialyzer.html index 7781b72..6d995bd 100644 --- a/guide/dialyzer.html +++ b/guide/dialyzer.html @@ -33,18 +33,18 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 19. Dialyzer

Dialyzer is a tool that will detect discrepancies in your +

Prev   Next

Chapter 20. 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.

19.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.

20.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.

19.2. Configuration

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

20.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.

19.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.

20.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/edoc.html b/guide/edoc.html index 40ebdde..bfb4425 100644 --- a/guide/edoc.html +++ b/guide/edoc.html @@ -33,13 +33,13 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 13. EDoc comments

Erlang.mk provides a thin wrapper on top of EDoc, an application -that generates documentation based on comments found in modules.

13.1. Writing EDoc comments

The EDoc user guide -explains everything you need to know about EDoc comments.

13.2. Configuration

The EDOC_OPTS variable allows you to specify additional +

Prev   Next

Chapter 14. EDoc comments

Erlang.mk provides a thin wrapper on top of EDoc, an application +that generates documentation based on comments found in modules.

14.1. Writing EDoc comments

The EDoc user guide +explains everything you need to know about EDoc comments.

14.2. Configuration

The EDOC_OPTS variable allows you to specify additional EDoc options. Options are documented in the EDoc manual.

A common use for this variable is to enable Markdown in doc comments, using the edown application:

DOC_DEPS = edown
-EDOC_OPTS = {doclet, edown_doclet}

13.3. Usage

To build all documentation, you would typically use:

$ make docs

Do note, however, that EDoc comments will only be generated +EDOC_OPTS = {doclet, edown_doclet}

14.3. Usage

To build all documentation, you would typically use:

$ make docs

Do note, however, that EDoc comments will only be generated automatically if the doc/overview.edoc file exists. If you do not want that file and still want to generate doc comments, two solutions are available.

You can generate EDoc documentation directly:

$ make edoc

You can enable automatic generation on make docs by adding diff --git a/guide/escript.html b/guide/escript.html index 8dc71a7..e874663 100644 --- a/guide/escript.html +++ b/guide/escript.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}

-
Prev   Next

Chapter 10. Escripts

Placeholder chapter.

Prev Up Next
 Home 
+
Prev   Next

Chapter 11. Escripts

Placeholder chapter.

Prev Up Next
 Home 
diff --git a/guide/eunit.html b/guide/eunit.html index 2bbeecd..1a5bb22 100644 --- a/guide/eunit.html +++ b/guide/eunit.html @@ -33,9 +33,9 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 15. EUnit

EUnit is the tool of choice for unit testing. Erlang.mk +

Prev   Next

Chapter 16. EUnit

EUnit is the tool of choice for unit testing. Erlang.mk automates a few things on top of EUnit, including the -discovery and running of unit tests.

15.1. Writing tests

The EUnit user guide +discovery and running of unit tests.

16.1. Writing tests

The EUnit user guide is the best place to learn how to write tests. Of note is that all functions ending with _test or _test_ will be picked up as EUnit test cases.

Erlang.mk will automatically pick up tests found in any of @@ -58,20 +58,20 @@ compiled.

-ifdef(TEST).
 %% Insert tests here.
 
 -endif.

Erlang.mk will automatically recompile your code when you -perform a normal build after running tests, and vice versa.

15.2. Configuration

The EUNIT_OPTS variable allows you to specify additional +perform a normal build after running tests, and vice versa.

16.2. Configuration

The EUNIT_OPTS variable allows you to specify additional EUnit options. Options are documented in the EUnit manual. At the time of writing, the only available option is verbose:

EUNIT_OPTS = verbose

The EUNIT_ERL_OPTS variable allows you to specify options to be passed to erl when running EUnit tests. For example, -you can load the vm.args and sys.config files:

EUNIT_ERL_OPTS = -args_file rel/vm.args -config rel/sys.config

15.3. Usage

To run all tests (including EUnit):

$ make tests

To run all tests and static checks (including EUnit):

$ make check

You can also run EUnit separately:

$ make eunit

EUnit will be quiet by default, only outputting errors. +you can load the vm.args and sys.config files:

EUNIT_ERL_OPTS = -args_file rel/vm.args -config rel/sys.config

16.3. Usage

To run all tests (including EUnit):

$ make tests

To run all tests and static checks (including EUnit):

$ make check

You can also run EUnit separately:

$ make eunit

EUnit will be quiet by default, only outputting errors. You can easily make it verbose for a single invocation:

$ make eunit EUNIT_OPTS=verbose

Erlang.mk allows you to run all tests from a specific module, or a specific test case from that module, using the variable t.

For example, to run all tests from the cow_http_hd 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 17, Code coverage is available, +you can run the following directly:

$ make -C deps/cowlib eunit t=cow_http_hd

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

Prev Up Next
 Home 
diff --git a/guide/history.html b/guide/history.html index 8ccb762..820aff3 100644 --- a/guide/history.html +++ b/guide/history.html @@ -33,8 +33,8 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 24. Short history

This chapter aims to be a brief record of the life of the -Erlang.mk project.

24.1. Before Erlang.mk

Erlang.mk originates from the Cowboy project. Cowboy started +

Prev   Next

Chapter 25. Short history

This chapter aims to be a brief record of the life of the +Erlang.mk project.

25.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.

24.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.

25.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 aa50a94..dbf92b2 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

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
9. Releases
9.1. Setup
9.2. Configuration
9.3. Generating the release
9.4. Running the release
9.5. Upgrading a release
10. Escripts
11. Compatibility with other build tools
11.1. Rebar projects as Erlang.mk dependencies
11.2. Erlang.mk projects as Rebar dependencies
II. Documentation
12. AsciiDoc documentation
12.1. Requirements
12.2. Writing AsciiDoc documentation
12.3. Configuration
12.4. Usage
13. EDoc comments
13.1. Writing EDoc comments
13.2. Configuration
13.3. Usage
III. Tests
14. Erlang shell
14.1. Configuration
14.2. Usage
15. EUnit
15.1. Writing tests
15.2. Configuration
15.3. Usage
16. Common Test
16.1. Writing tests
16.2. Configuration
16.3. Usage
17. Code coverage
18. Continuous integration
19. Dialyzer
19.1. How it works
19.2. Configuration
19.3. Usage
20. Xref
IV. Third-party plugins
21. External plugins
21.1. Loading all plugins from a dependency
21.2. Loading one plugin from a dependency
21.3. Writing external plugins
22. List of plugins
22.1. efene.mk
22.2. elixir.mk
22.3. elvis.mk
22.4. geas
22.5. hexer.mk
22.6. hexpm.mk
22.7. jorel
22.8. lfe.mk
22.9. mix.mk
22.10. reload.mk
22.11. rust.mk
V. About Erlang.mk
23. Why Erlang.mk
23.1. Erlang.mk is fast
23.2. Erlang.mk gives you the full power of Unix
23.3. Erlang.mk is a text file
23.4. Erlang.mk can manage Erlang itself
23.5. Erlang.mk can do more than Erlang
23.6. Erlang.mk integrates nicely in Make and Automake projects
24. Short history
24.1. Before Erlang.mk
24.2. Lifetime of the project
25. Contributing
25.1. Priorities
25.2. Bugs
25.3. Code
25.4. Packages
25.5. Documentation
25.6. Feature requests
   Next
+
   Next

Erlang.mk User Guide

Loïc Hoguin

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
9. Releases
9.1. Setup
9.2. Configuration
9.3. Generating the release
9.4. Running the release
9.5. Upgrading a release
10. Self-extracting releases
10.1. Generating the self-extracting archive
10.2. Running the release
11. Escripts
12. Compatibility with other build tools
12.1. Rebar projects as Erlang.mk dependencies
12.2. Erlang.mk projects as Rebar dependencies
II. Documentation
13. AsciiDoc documentation
13.1. Requirements
13.2. Writing AsciiDoc documentation
13.3. Configuration
13.4. Usage
14. EDoc comments
14.1. Writing EDoc comments
14.2. Configuration
14.3. Usage
III. Tests
15. Erlang shell
15.1. Configuration
15.2. Usage
16. EUnit
16.1. Writing tests
16.2. Configuration
16.3. Usage
17. Common Test
17.1. Writing tests
17.2. Configuration
17.3. Usage
18. Code coverage
19. Continuous integration
20. Dialyzer
20.1. How it works
20.2. Configuration
20.3. Usage
21. Xref
IV. Third-party plugins
22. External plugins
22.1. Loading all plugins from a dependency
22.2. Loading one plugin from a dependency
22.3. Writing external plugins
23. List of plugins
23.1. efene.mk
23.2. elixir.mk
23.3. elvis.mk
23.4. geas
23.5. hexer.mk
23.6. hexpm.mk
23.7. jorel
23.8. lfe.mk
23.9. mix.mk
23.10. reload.mk
23.11. rust.mk
V. About Erlang.mk
24. Why Erlang.mk
24.1. Erlang.mk is fast
24.2. Erlang.mk gives you the full power of Unix
24.3. Erlang.mk is a text file
24.4. Erlang.mk can manage Erlang itself
24.5. Erlang.mk can do more than Erlang
24.6. Erlang.mk integrates nicely in Make and Automake projects
25. Short history
25.1. Before Erlang.mk
25.2. Lifetime of the project
26. Contributing
26.1. Priorities
26.2. Bugs
26.3. Code
26.4. Packages
26.5. Documentation
26.6. Feature requests
   Next
diff --git a/guide/overview.html b/guide/overview.html index c533e86..a449133 100644 --- a/guide/overview.html +++ b/guide/overview.html @@ -45,43 +45,43 @@ when you are working on generate releases Chapter 9, Releases -when applicable. It can also generate escripts -Chapter 10, Escripts.

3.2. Exploring the package index

Erlang.mk comes with a built-in package index +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. 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 13, 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 +Chapter 14, EDoc comments 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 12, AsciiDoc documentation plugin expects all documentation +That’s where Asciidoc comes in.

The Asciidoc +Chapter 13, AsciiDoc documentation 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 14, Erlang shell command allows you +analysis tools.

The make shell +Chapter 15, Erlang shell command allows you to test your project manually. You can automate these -unit tests with EUnit -Chapter 15, EUnit and test -your entire system with Common Test -Chapter 16, Common Test. -Code coverage -Chapter 17, Code coverage can of course +unit tests with EUnit +Chapter 16, EUnit and test +your entire system with Common Test +Chapter 17, Common Test. +Code coverage +Chapter 18, 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 18, Continuous integration.

On the static analysis side of things, Erlang.mk comes with -support for Dialyzer -Chapter 19, Dialyzer and Xref -Chapter 20, Xref, +setting up and using Continuous integration +Chapter 19, Continuous integration.

On the static analysis side of things, Erlang.mk comes with +support for Dialyzer +Chapter 20, Dialyzer and Xref +Chapter 21, 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 23, Why Erlang.mk -and its history -Chapter 24, 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 +Chapter 24, Why Erlang.mk +and its history +Chapter 25, Short 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 4a95994..50e963c 100644 --- a/guide/plugins_list.html +++ b/guide/plugins_list.html @@ -33,21 +33,21 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 22. List of plugins

This is a non-exhaustive list of Erlang.mk plugins, sorted -alphabetically.

22.1. efene.mk

An Efene plugin for Erlang.mk. -Efene is an alternative language for the BEAM.

22.2. elixir.mk

An Elixir plugin for +

Prev   Next

Chapter 23. List of plugins

This is a non-exhaustive list of Erlang.mk plugins, sorted +alphabetically.

23.1. efene.mk

An Efene plugin for Erlang.mk. +Efene is an alternative language for the BEAM.

23.2. elixir.mk

An Elixir plugin for Erlang.mk. Elixir is an alternative -language for the BEAM.

22.3. elvis.mk

An Elvis plugin for Erlang.mk. -Elvis is an Erlang style reviewer.

22.4. geas

Geas gives aggregated +language for the BEAM.

23.3. elvis.mk

An Elvis plugin for Erlang.mk. +Elvis is an Erlang style reviewer.

23.4. geas

Geas gives aggregated information on a project and its dependencies, and is available -as an Erlang.mk plugin.

22.5. hexer.mk

An Hex plugin for Erlang.mk -using the hexer tool.

22.6. hexpm.mk

Another Hex plugin for -Erlang.mk, with support for Hex dependency operators.

22.7. jorel

Jorel is Just anOther RELease -assembler for Erlang/OTP, and is available as an Erlang.mk plugin.

22.8. lfe.mk

An LFE plugin for Erlang.mk. +as an Erlang.mk plugin.

23.5. hexer.mk

An Hex plugin for Erlang.mk +using the hexer tool.

23.6. hexpm.mk

Another Hex plugin for +Erlang.mk, with support for Hex dependency operators.

23.7. jorel

Jorel is Just anOther RELease +assembler for Erlang/OTP, and is available as an Erlang.mk plugin.

23.8. lfe.mk

An LFE plugin for Erlang.mk. LFE, or Lisp Flavoured Erlang, is an alternative -language for the BEAM.

22.9. mix.mk

A Mix plugin for Erlang.mk, +language for the BEAM.

23.9. mix.mk

A Mix plugin for Erlang.mk, to generate a compatible configuration file for -Mix.

22.10. reload.mk

A live reload plugin for Erlang.mk.

22.11. rust.mk

A plugin to build Rust crates and install binaries into priv/.

Prev Up Next
 Home 
+Mix.

23.10. reload.mk

A live reload plugin for Erlang.mk.

23.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 ac3ee15..e45f59d 100644 --- a/guide/plugins_usage.html +++ b/guide/plugins_usage.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 21. External plugins

It is often convenient to be able to keep the build files +

Prev   Next

Chapter 22. 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.

21.1. Loading all plugins from a dependency

To load plugins from a dependency, all you need to do is add +plugins.

22.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.

21.2. Loading one plugin from a dependency

Now that we know how to load all plugins, let’s take a look +the Cowboy repository.

22.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

21.3. Writing external plugins

The plugins.mk file is a convention. It is meant to load +DEP_PLUGINS = cowboy/mk/dist.mk

22.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 diff --git a/guide/relx.html b/guide/relx.html index 3c07a4b..f210d5d 100644 --- a/guide/relx.html +++ b/guide/relx.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}

-
Prev   Next

Chapter 9. Releases

Erlang.mk relies on Relx for generating releases. This +

Prev   Next

Chapter 9. Releases

Erlang.mk relies on Relx for generating releases. This chapter covers the Erlang.mk-specific bits. Consult the Relx website for more information.

9.1. Setup

Erlang.mk will create a release if it detects a Relx configuration file in the $(RELX_CONFIG) location. This defaults to @@ -65,9 +65,9 @@ for more details.

For the purpose of this section, assume the initial rele version was 1, and the new version is 2. The name of the release will be example.

Once all this is done, you can build the tarball for the release upgrade:

$ make relup

This will create an archive at the root directory of the -release, $(RELX_OUTPUT_DIR)/example/example-2.tar.gz.

Move the archive to the correct location on the running +release, $RELX_OUTPUT_DIR/example/example-2.tar.gz.

Move the archive to the correct location on the running node. From the release’s root directory:

$ mkdir releases/2/
-$ mv path/to/example-2.tar.gz releases/2/

Finally, upgrade the release:

$ bin/example_release upgrade "2/example_release"

Or on Windows:

$ bin/example_release.cmd upgrade "2/example_release"

Your release was upgraded!

Prev Up Next
 Home 
+$ mv path/to/example-2.tar.gz releases/2/

Finally, upgrade the release:

$ bin/example_release upgrade "2/example_release"

Or on Windows:

$ bin/example_release.cmd upgrade "2/example_release"

Your release was upgraded!

Prev Up Next
 Home 
diff --git a/guide/sfx.html b/guide/sfx.html new file mode 100644 index 0000000..6aff580 --- /dev/null +++ b/guide/sfx.html @@ -0,0 +1,59 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 10. Self-extracting releases

Erlang.mk allows you to package Relx releases +Chapter 9, 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 +that can then be executed.

This feature is currently experimental. Feedback is much +appreciated.

10.1. Generating the self-extracting archive

To generate a self-extracting release, all you need to do +is pass the SFX=1 variable to Make when you build the +release:

$ make SFX=1

This will create a self-extracting archive in +$RELX_OUTPUT_DIR/<name>.run. For example if the release +is named hello_world and $RELX_OUTPUT_DIR is the default, +the file will be located at _rel/hello_world.run.

10.2. Running the release

Simply execute the script to get started:

$ ./_rel/hello_world.run
+Exec: /tmp/tmp.3eeEq7E1ta/erts-8.1/bin/erlexec ...
+Root: /tmp/tmp.3eeEq7E1ta
+/tmp/tmp.3eeEq7E1ta
+Erlang/OTP 19 [erts-8.1] [source] [64-bit] [smp:4:4] ...
+
+Eshell V8.1  (abort with ^G)
+(hello_world@localhost)1>

As you can see the archive is extracted to a temporary +directory before the release can be started.

The self-extracting script currently only supports starting +the release in console mode.

Prev Up Next
 Home 
+
+ + diff --git a/guide/shell.html b/guide/shell.html index 89e1d0c..60ccac5 100644 --- a/guide/shell.html +++ b/guide/shell.html @@ -33,15 +33,15 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 14. Erlang shell

Erlang.mk provides a convenient target for starting a shell -with all the paths set properly to experiment with your code.

14.1. Configuration

The SHELL_DEPS variable can be used to define dependencies +

Prev   Next

Chapter 15. Erlang shell

Erlang.mk provides a convenient target for starting a shell +with all the paths set properly to experiment with your code.

15.1. Configuration

The SHELL_DEPS variable can be used to define dependencies that are only to be used when the make shell command is called. For example, if you want to use kjell as your shell:

SHELL_DEPS = kjell

Dependencies are downloaded and compiled the first time you run the make shell command.

You can customize the executable used to start the Erlang shell. To continue with our example, if you want to use kjell as your 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()'

14.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 +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()'

15.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 
diff --git a/guide/why.html b/guide/why.html index 925063c..5dfa60e 100644 --- a/guide/why.html +++ b/guide/why.html @@ -33,15 +33,15 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 23. Why Erlang.mk

Why would you choose Erlang.mk, if not for its +

Prev   Next

Chapter 24. 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.

23.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 +attempt to answer that.

24.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.

23.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.

24.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 +49,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…

23.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…

24.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.

23.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.

24.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.

23.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.

24.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.

23.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.

24.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 acc4209..4d0bc06 100644 --- a/guide/xref.html +++ b/guide/xref.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 20. Xref

Placeholder chapter.

Prev Up Next
 Home 
+
Prev   Next

Chapter 21. Xref

Placeholder chapter.

Prev Up Next
 Home 
-- cgit v1.2.3