Nine Nines: Building

@@ -122,7 +122,7 @@ http://www.gnu.org/software/src-highlite -->

To build your application without touching dependencies at all, you can use the SKIP_DEPS variable:

@@ -138,7 +138,7 @@ is missing.

You can build all dependencies, and nothing else, by running the following command:

@@ -158,7 +158,7 @@ a normal Erlang.mk. A separate target is however available, and will take care of building the release, after building the application and all dependencies:

@@ -271,7 +271,7 @@ your situation.

There’s no need for quotes or anything. The relevant part of the Cowboy Makefile follows, if you need an example:

@@ -304,7 +304,7 @@ reason or another, worry not; Erlang.mk will support it. And if you need to create a new project that uses this method, you just have to say so when bootstrapping:

@@ -336,7 +336,7 @@ as it allows you to know which version they run exactly by asking them to look in the file, or by running a simple command on their production server:

@@ -464,7 +464,7 @@ the erlc Manual for the full list.

By default, Erlang.mk will set the following options:

@@ -475,7 +475,7 @@ obsolete guard functions.

You can redefine this variable in your Makefile to change it completely, either before or after including Erlang.mk:

@@ -484,7 +484,7 @@ http://www.gnu.org/software/src-highlite --> sets, by defining ERLC_OPTS after including Erlang.mk using the := operator.

@@ -509,7 +509,7 @@ not normally need it.

To exclude a module, simply list it in the variable, either before or after including Erlang.mk:

@@ -559,7 +559,7 @@ when you have behaviors used by other modules in your project.

the dependency tracking file every time you compile. You can do this by adding the following line to your Makefile:

@@ -571,7 +571,7 @@ this value when you do make substantial changes to your project and want to rebuild the dependency tracking file. You’ll be able to use the following command:

@@ -593,7 +593,7 @@ file is generated. To do this, you would add your hook before or after including the erlang.mk file.

The easiest way is after:

@@ -616,7 +616,7 @@ modified.

Erlang.mk, don’t forget to set the .DEFAULT_GOAL variable, otherwise nothing will get built:

@@ -648,14 +648,14 @@ putting your directory back to the state it was before you started working on it.

To clean:

$ make clean

Or distclean:

diff --git a/docs/en/erlang.mk/1/guide/asciidoc/index.html b/docs/en/erlang.mk/1/guide/asciidoc/index.html index 0a51ddeb..ad9c8406 100644 --- a/docs/en/erlang.mk/1/guide/asciidoc/index.html +++ b/docs/en/erlang.mk/1/guide/asciidoc/index.html @@ -7,7 +7,7 @@ - + Nine Nines: AsciiDoc documentation @@ -111,35 +111,35 @@ inside the files themselves.

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:

@@ -151,7 +151,7 @@ defines where man pages will be installed. It defaults to which manual sections are to be installed. It defaults to 3 7.

To install man pages to a custom location:

diff --git a/docs/en/erlang.mk/1/guide/ci/index.html b/docs/en/erlang.mk/1/guide/ci/index.html index 950eca18..3a325146 100644 --- a/docs/en/erlang.mk/1/guide/ci/index.html +++ b/docs/en/erlang.mk/1/guide/ci/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Continuous integration @@ -82,7 +82,7 @@ OTP release, a HiPE-enabled release or an ErLLVM-enabled release.

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

@@ -90,7 +90,7 @@ http://www.gnu.org/software/src-highlite -->

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

@@ -108,7 +108,7 @@ Erlang/OTP builds.

-k. It will ensure that tests are run for all configured Erlang/OTP versions, even if there are errors:

@@ -121,7 +121,7 @@ http://www.gnu.org/software/src-highlite -->

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

@@ -132,7 +132,7 @@ Erlang/OTP version.

For example, to ensure dependencies are re-fetched/built before testing individual Erlang/OTP releases:

diff --git a/docs/en/erlang.mk/1/guide/common_test/index.html b/docs/en/erlang.mk/1/guide/common_test/index.html index faf90773..25a0f2e5 100644 --- a/docs/en/erlang.mk/1/guide/common_test/index.html +++ b/docs/en/erlang.mk/1/guide/common_test/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Common Test @@ -88,7 +88,7 @@ options. Options are documented in the Common Test user guide. You can use it to set Common Test hooks, for example:

@@ -101,7 +101,7 @@ test suites automatically.

If the file is named http_SUITE.erl, the test suite is http:

@@ -109,7 +109,7 @@ http://www.gnu.org/software/src-highlite -->

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

@@ -121,21 +121,21 @@ http://www.gnu.org/software/src-highlite -->

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:

@@ -144,7 +144,7 @@ http://www.gnu.org/software/src-highlite --> If you have a file named test/http_SUITE.erl, then the target ct-http will run that specific test suite:

@@ -156,14 +156,14 @@ 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:

@@ -171,7 +171,7 @@ http://www.gnu.org/software/src-highlite -->

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

@@ -179,7 +179,7 @@ http://www.gnu.org/software/src-highlite -->

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

diff --git a/docs/en/erlang.mk/1/guide/compat/index.html b/docs/en/erlang.mk/1/guide/compat/index.html index 788e2fac..6e0e408b 100644 --- a/docs/en/erlang.mk/1/guide/compat/index.html +++ b/docs/en/erlang.mk/1/guide/compat/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Compatibility with other build tools @@ -103,7 +103,7 @@ and the application resource file, found either at

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

@@ -123,7 +123,7 @@ issues.

your application, by making it a dependency of the app target:

diff --git a/docs/en/erlang.mk/1/guide/contributing/index.html b/docs/en/erlang.mk/1/guide/contributing/index.html index 661ff55a..9d7bca3a 100644 --- a/docs/en/erlang.mk/1/guide/contributing/index.html +++ b/docs/en/erlang.mk/1/guide/contributing/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Contributing @@ -147,7 +147,7 @@ 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.

diff --git a/docs/en/erlang.mk/1/guide/coverage/index.html b/docs/en/erlang.mk/1/guide/coverage/index.html index 4c0aa76c..d033c604 100644 --- a/docs/en/erlang.mk/1/guide/coverage/index.html +++ b/docs/en/erlang.mk/1/guide/coverage/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Code coverage diff --git a/docs/en/erlang.mk/1/guide/deps/index.html b/docs/en/erlang.mk/1/guide/deps/index.html index f74a5842..98fe2cd5 100644 --- a/docs/en/erlang.mk/1/guide/deps/index.html +++ b/docs/en/erlang.mk/1/guide/deps/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Packages and dependencies @@ -84,7 +84,7 @@ in a single repository.

being added regularly.

To find a package, search for it:

@@ -94,7 +94,7 @@ pool and acceptor pool projects.

You can also list everything and use regular command line tools to find what you need, for example:

@@ -107,7 +107,7 @@ http://www.gnu.org/software/src-highlite -->

Once you find the package you need, adding it as a dependency to your project is a one-liner:

@@ -126,7 +126,7 @@ dependencies.

For example, you could add a parse transform project like this to make it available only at build time:

@@ -134,7 +134,7 @@ http://www.gnu.org/software/src-highlite -->

Or you could depend on a C project directly, if you are building a NIF:

@@ -153,7 +153,7 @@ Do note that there is no way to choose the version, the application used will be the one already on your system.

You could depend on the Crypto application, for example:

@@ -161,7 +161,7 @@ http://www.gnu.org/software/src-highlite -->

Erlang.mk comes with additional types of dependencies. It has TEST_DEPS for dependencies used only for testing:

@@ -169,7 +169,7 @@ http://www.gnu.org/software/src-highlite --> dep_ct_helper = git https://github.com/ninenines/ct_helper master

DOC_DEPS for dependencies used only when building documentation:

@@ -177,7 +177,7 @@ http://www.gnu.org/software/src-highlite -->

REL_DEPS for dependencies required to build the release, or to include extra applications in the release:

@@ -185,7 +185,7 @@ http://www.gnu.org/software/src-highlite -->

And SHELL_DEPS for dependencies to make available when running the make shell command:

@@ -198,7 +198,7 @@ chapters.

find the project you are looking for, if you only provide its name. This is this case:

@@ -210,7 +210,7 @@ for different reasons.

need to do is to define the dep_$(DEP_NAME)_commit variable. In the case of Cowboy, this would look like this:

@@ -223,7 +223,7 @@ too, for example because you want to use your own fork, or simply because the project is missing from the index, you can define the dep_$(DEP_NAME) variable with everything:

@@ -307,14 +307,14 @@ You can use any valid commit, tag or branch in that repository for the commit value.

For example, to fetch Cowboy with tag 2.0.0-pre.2 from Git:

dep_cowboy = git https://github.com/ninenines/cowboy 2.0.0-pre.2

Or to fetch Ehsa tag 4.0.3 from Mercurial:

@@ -323,7 +323,7 @@ http://www.gnu.org/software/src-highlite --> automatically initializes and updates submodules for dependencies, as long as they were added beforehand using git submodule add:

@@ -333,7 +333,7 @@ simply because the SVN repository URL can also contain the path and commit.

This would fetch an example project from the trunk:

@@ -341,7 +341,7 @@ http://www.gnu.org/software/src-highlite -->

And this would fetch a separate example project from a specific commit:

@@ -349,7 +349,7 @@ http://www.gnu.org/software/src-highlite -->

You can copy a directory from your machine using the cp method. It only takes the path to copy from:

@@ -357,7 +357,7 @@ http://www.gnu.org/software/src-highlite -->

Finally, you can use a package from the Hex repository:

@@ -374,7 +374,7 @@ Or in layman terms, if your dependency is Cowboy, this would become deps/cowboy.

To give an example, this is what the Git method does:

@@ -509,7 +509,7 @@ on your system.

To ignore a dependency, simply add it to the IGNORE_DEPS variable:

@@ -517,7 +517,7 @@ http://www.gnu.org/software/src-highlite -->

This will only ignore dependencies that are needed for building. It is therefore safe to write:

@@ -540,7 +540,7 @@ own dependencies.

if you know you will never use this project as a dependency, = will work. But to avoid it biting you later on, do this:

@@ -609,14 +609,14 @@ the application.

For example, to create a full fledged OTP application as a local dependency:

$ make new-app in=webchat

Or, the same as an OTP library:

@@ -625,7 +625,7 @@ http://www.gnu.org/software/src-highlite --> directory of the project. You do need however to tell Erlang.mk to create the files in the correct application:

@@ -724,7 +724,7 @@ Other projects with no Makefile are left untouched.

You can disable the replacing of the erlang.mk file by defining the NO_AUTOPATCH_ERLANG_MK variable:

@@ -732,7 +732,7 @@ http://www.gnu.org/software/src-highlite -->

You can also disable autopatch entirely for a few select projects using the NO_AUTOPATCH variable:

@@ -748,7 +748,7 @@ include being somewhere with no connection to download them, or perhaps a peculiar setup.

A typical usage would be:

diff --git a/docs/en/erlang.mk/1/guide/dialyzer/index.html b/docs/en/erlang.mk/1/guide/dialyzer/index.html index 4472dbe4..411b24ca 100644 --- a/docs/en/erlang.mk/1/guide/dialyzer/index.html +++ b/docs/en/erlang.mk/1/guide/dialyzer/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Dialyzer @@ -118,7 +118,7 @@ to run, you may want to disable it on larger projects.

To perform an analysis, run the following command:

@@ -127,7 +127,7 @@ http://www.gnu.org/software/src-highlite -->

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

diff --git a/docs/en/erlang.mk/1/guide/edoc/index.html b/docs/en/erlang.mk/1/guide/edoc/index.html index 4d73d7ff..7e787579 100644 --- a/docs/en/erlang.mk/1/guide/edoc/index.html +++ b/docs/en/erlang.mk/1/guide/edoc/index.html @@ -7,7 +7,7 @@ - + Nine Nines: EDoc comments @@ -85,7 +85,7 @@ EDoc options. Options are documented in the

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

@@ -98,7 +98,7 @@ http://www.gnu.org/software/src-highlite -->

To build all documentation, you would typically use:

@@ -109,7 +109,7 @@ do not want that file and still want to generate doc comments, two solutions are available.

You can generate EDoc documentation directly:

@@ -117,7 +117,7 @@ http://www.gnu.org/software/src-highlite -->

You can enable automatic generation on make docs by adding the following to your Makefile:

@@ -142,8 +142,8 @@ http://www.gnu.org/software/src-highlite --> - - Erlang shell + + Sphinx documentation diff --git a/docs/en/erlang.mk/1/guide/escripts/index.html b/docs/en/erlang.mk/1/guide/escripts/index.html index cccddf83..120c8e81 100644 --- a/docs/en/erlang.mk/1/guide/escripts/index.html +++ b/docs/en/erlang.mk/1/guide/escripts/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Escripts @@ -82,7 +82,7 @@ package is named p7zip; on Ubuntu you need p7zip-full.

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

@@ -94,7 +94,7 @@ http://www.gnu.org/software/src-highlite -->

Run the following command to generate an escript:

@@ -104,7 +104,7 @@ the project, in the project’s directory. If the project is called relx then the escript will be in ./relx.

You can run the escript as you would any executable:

@@ -138,7 +138,7 @@ added to this file to create the escript.

the two steps. You can for example add extra files to the zip archive:

diff --git a/docs/en/erlang.mk/1/guide/eunit/index.html b/docs/en/erlang.mk/1/guide/eunit/index.html index 97c4ee49..ab93373a 100644 --- a/docs/en/erlang.mk/1/guide/eunit/index.html +++ b/docs/en/erlang.mk/1/guide/eunit/index.html @@ -7,7 +7,7 @@ - + Nine Nines: EUnit @@ -86,7 +86,7 @@ the code you ship to production. With Erlang.mk, you can do this thanks to the TEST macro. It is only defined when running tests:

@@ -100,7 +100,7 @@ as it also defines the TEST macro. Make sure to only include it inside an ifdef block, otherwise tests will always be compiled.

@@ -123,7 +123,7 @@ EUnit options. Options are documented in the EUnit manual. At the time of writing, the only available option is verbose:

@@ -132,7 +132,7 @@ http://www.gnu.org/software/src-highlite --> to be passed to erl when running EUnit tests. For example, you can load the vm.args and sys.config files:

@@ -144,21 +144,21 @@ http://www.gnu.org/software/src-highlite -->

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:

@@ -166,7 +166,7 @@ http://www.gnu.org/software/src-highlite -->

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

@@ -178,14 +178,14 @@ the variable t.

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:

@@ -193,7 +193,7 @@ http://www.gnu.org/software/src-highlite -->

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

@@ -201,7 +201,7 @@ http://www.gnu.org/software/src-highlite -->

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

diff --git a/docs/en/erlang.mk/1/guide/external_plugins/index.html b/docs/en/erlang.mk/1/guide/external_plugins/index.html index 3a8a1100..c1d61145 100644 --- a/docs/en/erlang.mk/1/guide/external_plugins/index.html +++ b/docs/en/erlang.mk/1/guide/external_plugins/index.html @@ -7,7 +7,7 @@ - + Nine Nines: External plugins @@ -88,7 +88,7 @@ of dependencies.

For example, if you have cowboy in DEPS, add cowboy in DEP_PLUGINS also:

@@ -111,7 +111,7 @@ writing DEP_PLUGINS = cowboy/plugins.mk.

from Cowboy and no other, we would write the following in our Makefile:

@@ -133,7 +133,7 @@ individual plugins in plugins.mk.

mk/templates.mk, you could write the following plugins.mk file:

@@ -161,7 +161,7 @@ the same.

early-plugins.mk. You can specify a filename exactly like you would have done it with regular plugins.

@@ -169,7 +169,7 @@ http://www.gnu.org/software/src-highlite --> BUILD_DEPS = common_deps DEP_EARLY_PLUGINS = common_deps

@@ -189,14 +189,14 @@ library.

For example, the following Makefile loads a plugin in the mk subdirectory:

DEP_PLUGINS = $(PROJECT)/mk/dist.mk

This also works with early-stage plugins:

@@ -205,7 +205,7 @@ http://www.gnu.org/software/src-highlite --> defaults to plugins.mk or early-plugins.mk, located at the root of your application:

diff --git a/docs/en/erlang.mk/1/guide/external_plugins_list/index.html b/docs/en/erlang.mk/1/guide/external_plugins_list/index.html index a72c4cfc..2c2564ea 100644 --- a/docs/en/erlang.mk/1/guide/external_plugins_list/index.html +++ b/docs/en/erlang.mk/1/guide/external_plugins_list/index.html @@ -7,7 +7,7 @@ - + Nine Nines: List of plugins diff --git a/docs/en/erlang.mk/1/guide/getting_started/index.html b/docs/en/erlang.mk/1/guide/getting_started/index.html index fe8532bf..ab67a6df 100644 --- a/docs/en/erlang.mk/1/guide/getting_started/index.html +++ b/docs/en/erlang.mk/1/guide/getting_started/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Getting started @@ -74,7 +74,7 @@

The first step is always to create a new folder that will contain your project.

@@ -95,14 +95,14 @@ the Cowboy project.

in your Erlang distribution, or even in your OS packages.

The next step is therefore to download it:

$ wget https://erlang.mk/erlang.mk

Or:

@@ -119,7 +119,7 @@ tree. In other words, it will always have processes running.

This kind of project can be automatically generated by Erlang.mk. All you need to do is use the bootstrap target:

@@ -127,7 +127,7 @@ http://www.gnu.org/software/src-highlite -->

Something similar to the following snippet will then appear on your screen:

@@ -154,7 +154,7 @@ to bootstrap. This operation is done only once. Consult the information.

Of course, the generated project can now be compiled:

@@ -170,7 +170,7 @@ tree. In other words, it is nothing but modules.

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

@@ -178,7 +178,7 @@ http://www.gnu.org/software/src-highlite -->

Erlang.mk will once again bootstrap itself and generate all the files for your project. You can now compile it:

@@ -196,7 +196,7 @@ to your production system and run without any extra setup.

Erlang.mk can of course bootstrap your project to generate releases. You can use the bootstrap-rel target for this purpose:

@@ -204,7 +204,7 @@ http://www.gnu.org/software/src-highlite -->

This target can be combined with bootstrap or bootstrap-lib to create a project that will build a release:

@@ -217,7 +217,7 @@ chapter for more information.

When you run make from now on, Erlang.mk will compile your project and build the release:

@@ -244,7 +244,7 @@ development.

script, or simply run make run. The latter will also compile your project and build the release if it wasn’t already:

@@ -280,14 +280,14 @@ manually.

create a folder, put Erlang.mk in it, and write a one line Makefile containing:

include erlang.mk

For a step by step:

@@ -311,7 +311,7 @@ opposite.

of spaces per indentation level you want.

For example, if you prefer two spaces per indentation level:

@@ -331,7 +331,7 @@ templates for generating projects, but also individual modules!

You can list all available templates with the list-templates target:

@@ -340,7 +340,7 @@ Available templates: cowboy_http cowboy_loop

To generate a module, let’s say a gen_server, all you need to do is to call make new with the appropriate arguments:

@@ -350,7 +350,7 @@ using the gen_server template.

This module is automatically compiled the next time you run make:

@@ -384,7 +384,7 @@ anymore.

During development, if you don’t remember the name of a target, you can always run make help:

diff --git a/docs/en/erlang.mk/1/guide/history/index.html b/docs/en/erlang.mk/1/guide/history/index.html index bdef70e6..82343e48 100644 --- a/docs/en/erlang.mk/1/guide/history/index.html +++ b/docs/en/erlang.mk/1/guide/history/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Short history diff --git a/docs/en/erlang.mk/1/guide/index.html b/docs/en/erlang.mk/1/guide/index.html index 6b7d7fd1..629691ae 100644 --- a/docs/en/erlang.mk/1/guide/index.html +++ b/docs/en/erlang.mk/1/guide/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Erlang.mk User Guide @@ -155,6 +155,11 @@ EDoc comments

+Sphinx documentation +

diff --git a/docs/en/erlang.mk/1/guide/installation.asciidoc b/docs/en/erlang.mk/1/guide/installation.asciidoc index bd191efe..3298db2d 100644 --- a/docs/en/erlang.mk/1/guide/installation.asciidoc +++ b/docs/en/erlang.mk/1/guide/installation.asciidoc @@ -24,6 +24,10 @@ The commands to install packages vary between distributions: [source,bash] $ pacman -S erlang git make +Alpine Linux and other distributions based on BusyBox come +with an incompatible `awk` program. Installing the GNU Awk +(`gawk` on Alpine) solves this issue. + ==== FreeBSD FreeBSD comes with binary and source packages: diff --git a/docs/en/erlang.mk/1/guide/installation/index.html b/docs/en/erlang.mk/1/guide/installation/index.html index fd886c96..27f76c1d 100644 --- a/docs/en/erlang.mk/1/guide/installation/index.html +++ b/docs/en/erlang.mk/1/guide/installation/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Installation @@ -84,18 +84,21 @@ have further requirements depending on your needs.

The commands to install packages vary between distributions:

Arch Linux

$ pacman -S erlang git make

Alpine Linux and other distributions based on BusyBox come +with an incompatible awk program. Installing the GNU Awk +(gawk on Alpine) solves this issue.

FreeBSD

FreeBSD comes with binary and source packages:

Install binary packages

@@ -110,7 +113,7 @@ to install a more recent version from either Homebrew or MacPorts:

Homebrew

@@ -119,7 +122,7 @@ http://www.gnu.org/software/src-highlite --> is the one provided by Apple.

MacPorts

@@ -198,7 +201,7 @@ C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -Syu" Git and any other required softwares. From an MSYS2 shell, you can call pacman directly:

@@ -206,7 +209,7 @@ http://www.gnu.org/software/src-highlite -->

You can use pacman -Ss to search packages. For example, to find all packages related to GCC:

@@ -215,7 +218,7 @@ http://www.gnu.org/software/src-highlite --> install this package, as Erlang.mk cannot use the normal "gcc" package:

diff --git a/docs/en/erlang.mk/1/guide/kerl/index.html b/docs/en/erlang.mk/1/guide/kerl/index.html index be6b2e46..124b08b5 100644 --- a/docs/en/erlang.mk/1/guide/kerl/index.html +++ b/docs/en/erlang.mk/1/guide/kerl/index.html @@ -7,7 +7,7 @@ - + Nine Nines: OTP version management @@ -104,7 +104,7 @@ ensure this version is used by everyone in your team.

ERLANG_OTP variable in your Makefile before including Erlang.mk. For example, to use OTP-20.0.4:

@@ -135,7 +135,7 @@ to change the installation directory for the Erlang/OTP versions managed by Kerl, you could add the following to your Makefile:

diff --git a/docs/en/erlang.mk/1/guide/limitations/index.html b/docs/en/erlang.mk/1/guide/limitations/index.html index 9620e115..d165d205 100644 --- a/docs/en/erlang.mk/1/guide/limitations/index.html +++ b/docs/en/erlang.mk/1/guide/limitations/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Limitations diff --git a/docs/en/erlang.mk/1/guide/overview/index.html b/docs/en/erlang.mk/1/guide/overview/index.html index cc2278e3..b416f77e 100644 --- a/docs/en/erlang.mk/1/guide/overview/index.html +++ b/docs/en/erlang.mk/1/guide/overview/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Overview @@ -97,7 +97,7 @@ shortcut over plain dependencies.

You can get a list of all packages known to Erlang.mk by using the search target:

@@ -105,7 +105,7 @@ http://www.gnu.org/software/src-highlite -->

You can also use this target to search across all packages, for example to find all packages related to Cowboy:

diff --git a/docs/en/erlang.mk/1/guide/ports/index.html b/docs/en/erlang.mk/1/guide/ports/index.html index 246f574d..71a55fb9 100644 --- a/docs/en/erlang.mk/1/guide/ports/index.html +++ b/docs/en/erlang.mk/1/guide/ports/index.html @@ -7,7 +7,7 @@ - + Nine Nines: NIFs and port drivers @@ -80,7 +80,7 @@ It defaults to c_src/. Should you need to modify it, all you need to do is to set the variable in your Makefile before including Erlang.mk:

@@ -89,7 +89,7 @@ http://www.gnu.org/software/src-highlite --> file named $(C_SRC_ENV). This file defaults to $(C_SRC_DIR)/env.mk. This can also be changed:

@@ -135,7 +135,7 @@ it.

You can include the env.mk file to benefit from the Erlang environment detection:

@@ -152,7 +152,7 @@ executables, using the source files it finds in $(C_SRC_DIR).

this and create an executable instead, put this in your Makefile before including Erlang.mk:

@@ -234,7 +234,7 @@ impacting other build steps.

By adding this to your Makefile all five variables will be made available to sub-Makefiles when building C code:

@@ -247,7 +247,7 @@ http://www.gnu.org/software/src-highlite --> because Makefiles expect an assignment for target-specific exports. Alternatively you can set a new value:

diff --git a/docs/en/erlang.mk/1/guide/releases/index.html b/docs/en/erlang.mk/1/guide/releases/index.html index 0ee51c52..494c27c3 100644 --- a/docs/en/erlang.mk/1/guide/releases/index.html +++ b/docs/en/erlang.mk/1/guide/releases/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Releases @@ -78,7 +78,7 @@ file in the $(RELX_CONFIG) location. This defaults to $(CURDIR)/relx.config. You can override it by defining the variable before including Erlang.mk:

@@ -95,7 +95,7 @@ location defaults to $(CURDIR)/relx and can be overriden.

You can specify additional Relx options using the RELX_OPTS variable. For example, to enable dev_mode:

@@ -105,7 +105,7 @@ in the Relx options directly, Erlang.mk provides a specific variable for it: RELX_OUTPUT_DIR. It defaults to the _rel directory. You can also override it:

@@ -120,7 +120,7 @@ release. As mentioned before, Erlang.mk will automatically generate it when it detects the $(RELX_CONFIG) file. This means the following command will also build the release:

@@ -128,7 +128,7 @@ http://www.gnu.org/software/src-highlite -->

If you need to generate the release, and only the release, the rel target can be used:

@@ -144,7 +144,7 @@ located at

$(RELX_OUTPUT_DIR)/<name>/<name>-<vsn>.tar.gz
 Erlang.mk provides a convenience function for running the
 release with one simple command:
 
-
@@ -174,7 +174,7 @@ release will be example.
 Once all this is done, you can build the tarball for the
 release upgrade:
 
-
@@ -184,7 +184,7 @@ 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:
 
-
@@ -192,14 +192,14 @@ http://www.gnu.org/software/src-highlite -->
 $ mv path/to/example-2.tar.gz releases/2/
 Finally, upgrade the release:
 
-
 $ bin/example_release upgrade "2/example_release"
 Or on Windows:
 
-
@@ -214,14 +214,14 @@ http://www.gnu.org/software/src-highlite -->
 generated by Relx based on VCS history.
 Create a file rel/version with only one line inside:
 
-
 {{ release_version }}
 Add/Update the overlay section of your relx.config:
 
-
@@ -231,7 +231,7 @@ http://www.gnu.org/software/src-highlite -->
 When you run make rel it creates the file $(RELX_OUTPUT_DIR)/example/version
 which contains the version value generated by Relx.
 
-
@@ -240,14 +240,14 @@ http://www.gnu.org/software/src-highlite -->
 In your Makefile you can use this simple snippet to get the version,
 but please keep in mind that this should depend on the rel target:
 
-
 $(shell cat $(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)
 For example:
 
-
@@ -258,7 +258,7 @@ http://www.gnu.org/software/src-highlite -->
         echo APP_VERSION = $(APP_VERSION)
 Would output:
 
-
diff --git a/docs/en/erlang.mk/1/guide/sfx/index.html b/docs/en/erlang.mk/1/guide/sfx/index.html
index 5ef06d47..2877244e 100644
--- a/docs/en/erlang.mk/1/guide/sfx/index.html
+++ b/docs/en/erlang.mk/1/guide/sfx/index.html
@@ -7,7 +7,7 @@
     
     
 
-    
+    
 
     Nine Nines: Self-extracting releases
 
@@ -82,7 +82,7 @@ appreciated.
 is pass the SFX=1 variable to Make when you build the
 release:
 
-
@@ -98,7 +98,7 @@ the file will be located at _rel/hello_world.run.
 
 Simply execute the script to get started:
 
-
diff --git a/docs/en/erlang.mk/1/guide/shell/index.html b/docs/en/erlang.mk/1/guide/shell/index.html
index 95cc3da1..1d87f835 100644
--- a/docs/en/erlang.mk/1/guide/shell/index.html
+++ b/docs/en/erlang.mk/1/guide/shell/index.html
@@ -7,7 +7,7 @@
     
     
 
-    
+    
 
     Nine Nines: Erlang shell
 
@@ -76,7 +76,7 @@ with all the paths set properly to experiment with your code.
 that are only to be used when the make shell command is called.
 For example, if you want to use kjell as your shell:
 
-
@@ -88,7 +88,7 @@ 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:
 
-
@@ -96,14 +96,14 @@ http://www.gnu.org/software/src-highlite -->
 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:
 
-
@@ -115,7 +115,7 @@ http://www.gnu.org/software/src-highlite -->
 
 To start the shell, all you need is the following command:
 
-
@@ -136,8 +136,8 @@ command q()..
 
 		
 			
-				
-					EDoc comments
+				
+					Sphinx documentation
 				
 			
 
diff --git a/docs/en/erlang.mk/1/guide/sphinx.asciidoc b/docs/en/erlang.mk/1/guide/sphinx.asciidoc
new file mode 100644
index 00000000..d4de20dd
--- /dev/null
+++ b/docs/en/erlang.mk/1/guide/sphinx.asciidoc
@@ -0,0 +1,129 @@
+[[sphinx]]
+== Sphinx documentation
+
+Erlang.mk includes targets for running the
+http://www.sphinx-doc.org/[Sphinx documentation generator], which can produce
+documentation in various formats, like HTML, man pages, Texinfo, LaTeX, and
+others.
+
+=== Writing Sphinx documentation
+
+Sphinx generates documentation from a set of
+http://www.sphinx-doc.org/en/stable/rest.html[reST] documents. There is
+a http://www.sphinx-doc.org/en/stable/tutorial.html[quick start guide] on
+Sphinx' website. For Erlang.mk, we'll set up a minimal environment instead.
+
+=== 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:
+
+[source,python]
+----
+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.
+
+[source,bash]
+$ make docs     # all the docs, including EDoc and AsciiDoc if applicable
+$ make sphinx   # Sphinx docs specifically
+
+=== Erlang.mk configuration
+
+Erlang.mk defaults to the following configuration:
+
+[source,make]
+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
+http://www.sphinx-doc.org/en/stable/invocation.html#cmdoption-sphinx-build-b[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.
+
+=== 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':
+
+[source,python]
+----
+man_pages = [
+    ('doc_name', 'page_name', 'Manpage Title', ['Page Author'], 1),
+]
+----
+
+As the
+http://www.sphinx-doc.org/en/stable/config.html#options-for-manual-page-output[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'.
diff --git a/docs/en/erlang.mk/1/guide/sphinx/index.html b/docs/en/erlang.mk/1/guide/sphinx/index.html
new file mode 100644
index 00000000..3d275b12
--- /dev/null
+++ b/docs/en/erlang.mk/1/guide/sphinx/index.html
@@ -0,0 +1,294 @@
+
+
+
+
+    
+    
+    
+    
+
+    
+
+    Nine Nines: Sphinx documentation
+
+    
+    
+
+    
+    
+    
+    
+
+    
+
+
+
+
+  
+    
+        
+          
+            99s
+          
+          
+            
+            
+              
+                
+                  Articles
+  				  Talks
+  				  Documentation
+  				  Consulting & Training
+                
+               
+              
+                
+                  
+                
+                    
+						
+					
+                    
+						
+					
+              
+            
+          
+        
+    
+
+
+
+
+
+
+
+
+
+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.
+
+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.
+
+
+
+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:
+
+
+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
+
+
+
+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.
+
+
+
+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:
+
+
+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.
+
+
+
+
+
+	
+		
+		
+		
+		
+		
+
+		
+			
+				
+					EDoc comments
+				
+			
+
+			
+				
+					Erlang shell
+				
+			
+		
+	
+
+
+
+
+
+
+
+
+
+	Erlang.mk
+	1
+	
+	User Guide
+
+
+
+	
+	
+	
+
+
+Navigation
+
+Version select
+
+	
+	
+	
+		1
+	
+
+
+
+
+
+
+
+      
+        
+          
+            
+              ↑ Scroll to top
+              
+                
+                  Contact us
Contribute to this site
+                
+              
+            
+            
+               
+               Copyright © Loïc Hoguin 2012-2016
+            
+          
+        
+      
+
+    
+    
+  
+
+
+
diff --git a/docs/en/erlang.mk/1/guide/updating/index.html b/docs/en/erlang.mk/1/guide/updating/index.html
index 06a96bfc..37c58d30 100644
--- a/docs/en/erlang.mk/1/guide/updating/index.html
+++ b/docs/en/erlang.mk/1/guide/updating/index.html
@@ -7,7 +7,7 @@
     
     
 
-    
+    
 
     Nine Nines: Updating Erlang.mk
 
@@ -87,7 +87,7 @@ from this.
 That’s why updating Erlang.mk is so simple. All you need
 to do is to call make erlang-mk:
 
-
@@ -124,7 +124,7 @@ and in what order.
 the build. For example, to exclude the package index and the EDoc
 plugin when bootstrapping your application:
 
-
@@ -133,7 +133,7 @@ http://www.gnu.org/software/src-highlite -->
 you update it, until you change your mind and use the WITHOUT
 variable again when you upgrade:
 
-
diff --git a/docs/en/erlang.mk/1/guide/why/index.html b/docs/en/erlang.mk/1/guide/why/index.html
index 7aed235e..c7e18c6d 100644
--- a/docs/en/erlang.mk/1/guide/why/index.html
+++ b/docs/en/erlang.mk/1/guide/why/index.html
@@ -7,7 +7,7 @@
     
     
 
-    
+    
 
     Nine Nines: Why Erlang.mk
 
diff --git a/docs/en/erlang.mk/1/guide/xref/index.html b/docs/en/erlang.mk/1/guide/xref/index.html
index 2dc4951c..4f0a27c6 100644
--- a/docs/en/erlang.mk/1/guide/xref/index.html
+++ b/docs/en/erlang.mk/1/guide/xref/index.html
@@ -7,7 +7,7 @@
     
     
 
-    
+    
 
     Nine Nines: Xref
 
-- 
cgit v1.2.3