From 6029c8d8f090cc98bb8f46986fc16262383796c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 24 Jan 2018 13:44:51 +0100 Subject: Update user guide --- guide/ci.html | 8 ++-- guide/contributing.html | 12 +++--- guide/coverage.html | 2 +- guide/ct.html | 12 +++--- guide/dialyzer.html | 8 ++-- guide/edoc.html | 4 +- guide/eunit.html | 12 +++--- guide/history.html | 6 +-- guide/index.html | 2 +- guide/kerl.html | 4 +- guide/overview.html | 34 +++++++-------- guide/plugins_list.html | 22 +++++----- guide/plugins_usage.html | 12 +++--- guide/shell.html | 6 +-- guide/sphinx.html | 108 +++++++++++++++++++++++++++++++++++++++++++++++ guide/tests.html | 2 +- guide/why.html | 14 +++--- guide/xref.html | 2 +- 18 files changed, 189 insertions(+), 81 deletions(-) create mode 100644 guide/sphinx.html diff --git a/guide/ci.html b/guide/ci.html index 8ccc12b..5705b07 100644 --- a/guide/ci.html +++ b/guide/ci.html @@ -33,13 +33,13 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 20. Continuous integration

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

Prev   Next

Chapter 21. 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.)

20.1. Configuring Erlang/OTP versions to test

To use the CI plugin you must first configure which versions +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 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 @@ -48,9 +48,9 @@ latest version of Erlang/OTP, the following could work:

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

20.2. Running tests across all configured versions

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

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

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

21.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/contributing.html b/guide/contributing.html index f490486..3a4cb2a 100644 --- a/guide/contributing.html +++ b/guide/contributing.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}

-
Prev   

Chapter 27. Contributing

You are welcome and encouraged to contribute.

This is how.

27.1. Priorities

From the most important to the least important:

  • +
    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:

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

    27.2. Bugs

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

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

27.3. Code

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

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

27.4. Packages

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

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

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

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

27.6. Feature requests

If you have an awesome idea or need something that Erlang.mk +run make docs.

28.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 e68dcd6..6ee0436 100644 --- a/guide/coverage.html +++ b/guide/coverage.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}

-
Prev   Next

Chapter 19. Code coverage

Placeholder chapter.

Prev Up Next
 Home 
+
Prev   Next

Chapter 20. Code coverage

Placeholder chapter.

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

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

18.1. Writing tests

The Common Test user guide +Test suites.

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

18.2. Configuration

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

19.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 @@ -48,7 +48,7 @@ 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

The CT_LOGS_DIR variable can be used to set where HTML -log files are to be written. This defaults to logs/.

CT_LOGS_DIR = ct_output_log_dir

18.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. +log files are to be written. This defaults to logs/.

CT_LOGS_DIR = ct_output_log_dir

19.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, @@ -56,8 +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 19, 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 20, 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 f474d0a..08f7644 100644 --- a/guide/dialyzer.html +++ b/guide/dialyzer.html @@ -33,18 +33,18 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 21. Dialyzer

Dialyzer is a tool that will detect discrepancies in your +

Prev   Next

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

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

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

21.2. Configuration

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

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

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

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 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 49f40c0..3ad87eb 100644 --- a/guide/edoc.html +++ b/guide/edoc.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 15. EDoc comments

Erlang.mk provides a thin wrapper on top of EDoc, an application +

Prev   Next

Chapter 15. EDoc comments

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

15.1. Writing EDoc comments

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

15.2. Configuration

The EDOC_OPTS variable allows you to specify additional EDoc options. Options are documented in the @@ -43,7 +43,7 @@ EDOC_OPTS = {doclet, edown_doclet}

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 -the following to your Makefile:

docs:: edoc
Prev Up Next
 Home 
+the following to your Makefile:

docs:: edoc
Prev Up Next
 Home 
diff --git a/guide/eunit.html b/guide/eunit.html index 71c5bbb..363b8fe 100644 --- a/guide/eunit.html +++ b/guide/eunit.html @@ -33,9 +33,9 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 17. EUnit

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

Prev   Next

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

17.1. Writing tests

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

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

17.2. Configuration

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

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

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

18.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 19, Code coverage is available, +you can run the following directly:

$ make -C deps/cowlib eunit t=cow_http_hd

Finally, code coverage +Chapter 20, 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 3c8083c..5037d3c 100644 --- a/guide/history.html +++ b/guide/history.html @@ -33,8 +33,8 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 26. Short history

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

26.1. Before Erlang.mk

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

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

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

27.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 5c66c55..9650d74 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
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
III. Tests
16. Erlang shell
16.1. Configuration
16.2. Usage
17. EUnit
17.1. Writing tests
17.2. Configuration
17.3. Usage
18. Common Test
18.1. Writing tests
18.2. Configuration
18.3. Usage
19. Code coverage
20. Continuous integration
20.1. Configuring Erlang/OTP versions to test
20.2. Running tests across all configured versions
20.3. Extending the CI targets
21. Dialyzer
21.1. How it works
21.2. Configuration
21.3. Usage
22. Xref
IV. Third-party plugins
23. External plugins
23.1. Loading all plugins from a dependency
23.2. Loading one plugin from a dependency
23.3. Writing external plugins
23.4. Early-stage plugins
23.5. Loading plugins local to the application
24. List of plugins
24.1. efene.mk
24.2. elixir.mk
24.3. elvis.mk
24.4. geas
24.5. hexer.mk
24.6. hexpm.mk
24.7. jorel
24.8. lfe.mk
24.9. mix.mk
24.10. reload.mk
24.11. rust.mk
V. About Erlang.mk
25. Why Erlang.mk
25.1. Erlang.mk is fast
25.2. Erlang.mk gives you the full power of Unix
25.3. Erlang.mk is a text file
25.4. Erlang.mk can manage Erlang itself
25.5. Erlang.mk can do more than Erlang
25.6. Erlang.mk integrates nicely in Make and Automake projects
26. Short history
26.1. Before Erlang.mk
26.2. Lifetime of the project
27. Contributing
27.1. Priorities
27.2. Bugs
27.3. Code
27.4. Packages
27.5. Documentation
27.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
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
diff --git a/guide/kerl.html b/guide/kerl.html index f588e24..35ec324 100644 --- a/guide/kerl.html +++ b/guide/kerl.html @@ -62,8 +62,8 @@ 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 20, 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 21, 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 4e5743f..1c6f842 100644 --- a/guide/overview.html +++ b/guide/overview.html @@ -62,26 +62,26 @@ That’s where Asciidoc comes in.

T 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 16, Erlang shell command allows you +analysis tools.

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

Erlang.mk comes with features to make your life easier when -setting up and using Continuous integration -Chapter 20, Continuous integration.

On the static analysis side of things, Erlang.mk comes with -support for Dialyzer -Chapter 21, Dialyzer and Xref -Chapter 22, Xref, +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, 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 25, Why Erlang.mk -and its history -Chapter 26, 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 26, Why Erlang.mk +and its history +Chapter 27, 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 3b327ec..cc17f63 100644 --- a/guide/plugins_list.html +++ b/guide/plugins_list.html @@ -33,21 +33,21 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 24. List of plugins

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

24.1. efene.mk

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

24.2. elixir.mk

An Elixir plugin for +

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 Erlang.mk. Elixir is an alternative -language for the BEAM.

24.3. elvis.mk

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

24.4. geas

Geas gives aggregated +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 information on a project and its dependencies, and is available -as an Erlang.mk plugin.

24.5. hexer.mk

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

24.6. hexpm.mk

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

24.7. jorel

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

24.8. lfe.mk

An LFE plugin for Erlang.mk. +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. LFE, or Lisp Flavoured Erlang, is an alternative -language for the BEAM.

24.9. mix.mk

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

25.9. mix.mk

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

24.10. reload.mk

A live reload plugin for Erlang.mk.

24.11. rust.mk

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

Prev Up Next
 Home 
+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 
diff --git a/guide/plugins_usage.html b/guide/plugins_usage.html index 8fd3022..aaf5af7 100644 --- a/guide/plugins_usage.html +++ b/guide/plugins_usage.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 23. External plugins

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

Prev   Next

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

23.1. Loading all plugins from a dependency

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

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

23.2. Loading one plugin from a dependency

Now that we know how to load all plugins, let’s take a look +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 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

23.3. Writing external plugins

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

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

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

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

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

24.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/shell.html b/guide/shell.html index 642ae0f..791a2ee 100644 --- a/guide/shell.html +++ b/guide/shell.html @@ -33,15 +33,15 @@ div.navfooter{margin-bottom:1em}

-
Prev   Next

Chapter 16. Erlang shell

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

16.1. Configuration

The SHELL_DEPS variable can be used to define dependencies +

Prev   Next

Chapter 17. Erlang shell

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

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

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

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 
diff --git a/guide/sphinx.html b/guide/sphinx.html new file mode 100644 index 0000000..91be9b0 --- /dev/null +++ b/guide/sphinx.html @@ -0,0 +1,108 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 16. Sphinx documentation

Erlang.mk includes targets for running the +Sphinx documentation generator, which can produce +documentation in various formats, like HTML, man pages, Texinfo, LaTeX, and +others.

16.1. Writing Sphinx documentation

Sphinx generates documentation from a set of +reST documents. There is +a quick start guide on +Sphinx' website. For Erlang.mk, we’ll set up a minimal environment instead.

16.2. Basic setup

By default, Erlang.mk expects Sphinx documentation to be placed in the doc +directory, with doc/conf.py config file in particular. The file contains +information about the project, among the other things.

A minimal doc/conf.py will look similar to this:

project = 'My Project'
+version = '0.0'
+release = '0.0.1'
+master_doc = 'index'
+source_suffix = '.rst'

It points to a doc/index.rst document. A simple skeleton includes a table of +contents for all documentation, and links to generated index of terms and +a search page:

My Project
+==========
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   other_page
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

The skeleton above has a link to one other page, doc/other_page.rst. Simple +header with some text will do for now:

Other Page
+==========
+
+Lorem ipsum dolor sit amet...

The files above are enough to build HTML documentation to the html directory.

$ make docs     # all the docs, including EDoc and AsciiDoc if applicable
+$ make sphinx   # Sphinx docs specifically

16.3. Erlang.mk configuration

Erlang.mk defaults to the following configuration:

SPHINX_FORMATS = html
+SPHINX_SOURCE = doc

To change the location of Sphinx sources, you need to set the $(SPHINX_SOURCE) +variable. The conf.py file should also be placed in that directory, unless you +specify $(SPHINX_CONFDIR).

The variable $(SPHINX_OPTS) allows to provide options to sphinx-build, which +is particularly useful for -D name=value options. You can even forego +doc/conf.py file, using -D name=value in combination with the -C option, +though in this case you will need to manually call make sphinx or add the +sphinx target to dependencies of docs.

The $(SPHINX_FORMATS) variable lists formats to generate. By default only HTML +is generated, but it can also build man pages or LaTeX documents which can later +be converted to PDF. See the +description of the -b option +for sphinx-build for a list of known formats.

Formats are by default generated to a directory called after the format +(html for HTML, man for man pages, and so on). To change this behaviour +for a specific format, you can set the $(sphinx_$(format)_output) variable, e.g. +$(sphinx_html_output) for html or $(sphinx_man_output) for man. +There are also $(sphinx_$(format)_opts) variables for setting sphinx-build +options for a single format only.

16.4. Generating man pages

To generate man pages, you need to include man in $(SPHINX_FORMATS) in +your Makefile and define the man_pages option in doc/conf.py:

man_pages = [
+    ('doc_name', 'page_name', 'Manpage Title', ['Page Author'], 1),
+]

As the +Sphinx documentation +indicates, the structure is:

  • +doc_name is the path to the man page’s source (relative $(SPHINX_SOURCE)), + without the .rst suffix +
  • +page_name is the name of the resulting man page, which will be used as a base + for the output file name and will be included in the generated man page +
  • +Manpage Title is a short, one-line description, which will be included in + the generated man page on a position that’s used by the apropos command +
  • +Page Author (or more of them) will be included in the autogenerated AUTHOR + section. Leaving this field empty disables generating the AUTHOR section +
  • +1 is the man page section number +

With the above configuration (and Erlang.mk’s defaults), doc/doc_name.rst will +be used to generate man/page_name.1.

Prev Up Next
 Home 
+
+ + diff --git a/guide/tests.html b/guide/tests.html index 6076c2d..081321e 100644 --- a/guide/tests.html +++ b/guide/tests.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Part III. Tests

Prev   Next
 Home 
+
Prev   Next

Part III. Tests

Prev   Next
 Home 
diff --git a/guide/why.html b/guide/why.html index be77652..919182d 100644 --- a/guide/why.html +++ b/guide/why.html @@ -33,15 +33,15 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 25. Why Erlang.mk

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

Chapter 22. Xref

Placeholder chapter.

Prev Up Next
 Home 
+
Prev   Next

Chapter 23. Xref

Placeholder chapter.

Prev Up Next
 Home 
-- cgit v1.2.3