From 8cb709059c22eaba7fdf66dee1674c4cf790e87d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 25 Oct 2016 14:57:58 +0300 Subject: Update user guide --- guide/deps.html | 46 ++++++++++++++++++++++++++++++++++++++++------ guide/index.html | 2 +- guide/installation.html | 2 +- 3 files changed, 42 insertions(+), 8 deletions(-) diff --git a/guide/deps.html b/guide/deps.html index b10cfe6..d5b8f13 100644 --- a/guide/deps.html +++ b/guide/deps.html @@ -135,7 +135,41 @@ those from C.

Similarly, if project A depends on projects B, C and D, regardless of the order, and A, B and C depend on a different version of D, it will always be A’s version that wins, because we fetch all dependencies of A before -fetching those from B or C.

7.4. Ignoring unwanted dependencies

Sometimes, you may want to ignore dependencies entirely. +fetching those from B or C.

7.4. Fetching and listing dependencies only

You can fetch all dependencies recursively without building anything, +with the make fetch-deps command. It follows the same rules described +in the section above.

You can list all dependencies recursively, again without building +anything, with the make list-deps command. It will obviously need +to fetch all dependencies exactly like make fetch-deps. Once +everything is fetched, it prints a sorted list of absolute paths to the +dependencies.

By default, fetch-deps and list-deps work on the BUILD_DEPS +and DEPS lists only. To also fetch/list TEST_DEPS, DOC_DEPS, +REL_DEPS and/or SHELL_DEPS, you have two possibilities:

  • +You can use make fetch-test-deps, make fetch-doc-deps, make + fetch-rel-deps and make fetch-shell-deps commands respectively. + If you want to list them, you can use make list-test-deps, make + list-doc-deps, make list-rel-deps and make list-shell-deps + respectively. +
  • +You can use make fetch-deps or make list-deps with the Makefile + variable DEP_TYPES set to a list of dependency types you want. + The types are test, doc, rel and shell respectively. For + example, you can list test and doc dependencies with make list-deps + DEP_TYPES='test doc'. +

Note that only first level ‘TEST_DEPS, `DOC_DEPS, REL_DEPS and +SHELL_DEPS are included, not dependencies’ one. In other word, +make list-test-deps lists the TEST_DEPS of your project, but not +TEST_DEPS of the projects yours depend on.

No matter which method you use, BUILD_DEPS and DEPS are always +included.

Internally, the make fetch-* commands store the complete list of +dependencies in files named $(ERLANG_MK_RECURSIVE_DEPS_LIST), +$(ERLANG_MK_RECURSIVE_TEST_DEPS_LIST), +$(ERLANG_MK_RECURSIVE_DOC_DEPS_LIST), +$(ERLANG_MK_RECURSIVE_REL_DEPS_LIST) and +$(ERLANG_MK_RECURSIVE_SHELL_DEPS_LIST). Those files are simply printed +by the make list-* commands.

make list-* commands are made for human beings. If you need the list +of dependencies in a Makefile or a script, you should use the content +of those files directly instead. The reason is that make fetch-* and +make list-* may have unwanted content in their output, such as actual +fetching of dependencies.

7.5. Ignoring unwanted dependencies

Sometimes, you may want to ignore dependencies entirely. Not even fetch them. You may want to do this because a project you depend on depends on an application you do not need (like a dependency for building documentation @@ -145,7 +179,7 @@ variable:

IGNORE_DEPS += edown proper

Thi building. It is therefore safe to write:

IGNORE_DEPS += edown proper
 TEST_DEPS = proper

The PropEr application will be fetched as intended when running make tests or make check. It will however -not be fetched when running make or make deps.

7.5. Dependencies directory

Dependencies are fetched in $(DEPS_DIR). By default this is +not be fetched when running make or make deps.

7.6. Dependencies directory

Dependencies are fetched in $(DEPS_DIR). By default this is the deps directory. You can change this default, but you should only do so if it was not defined previously. Erlang.mk uses this variable to tell dependencies where to fetch their @@ -154,7 +188,7 @@ if you know you will never use this project as a dependency, = will work. But to avoid it biting you later on, do this:

DEPS_DIR ?= $(CURDIR)/libs

The $(CURDIR) part is important, otherwise dependencies of dependencies will be fetched in the wrong directory.

Erlang.mk will also export the REBAR_DEPS_DIR variable for compatibility with Rebar build tools, as long as they are -recent enough.

7.6. Many applications in one repository

In addition to the dependencies that are fetched, Erlang.mk +recent enough.

7.7. Many applications in one repository

In addition to the dependencies that are fetched, Erlang.mk also allows you to have dependencies local to your repository. This kind of layout is sometimes called multi-application repositories, or repositories with multiple applications.

They work exactly the same as remote dependencies, except:

  • @@ -178,7 +212,7 @@ command will create the necessary directories and bootstrap 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:

    $ make new-lib in=webchat

    Templates also work with local dependencies, from the root directory of the project. You do need however to tell -Erlang.mk to create the files in the correct application:

    $ make new t=gen_server n=my_server in=webchat

7.7. Repositories with no application at the root level

It’s possible to use Erlang.mk with only applications in +Erlang.mk to create the files in the correct application:

$ make new t=gen_server n=my_server in=webchat

7.8. Repositories with no application at the root level

It’s possible to use Erlang.mk with only applications in $(APPS_DIR), and nothing at the root of the repository. Just create a folder, put the erlang.mk file in it, write a Makefile that includes it, and start creating @@ -186,7 +220,7 @@ your applications.

Similarly, it’s possible to have a repository with on dependencies found in $(DEPS_DIR). You just need to create a Makefile and specify the dependencies you want. This allows you to create a repository for handling the -building of releases, for example.

7.8. Autopatch

Erlang.mk will automatically patch all the dependencies it +building of releases, for example.

7.9. Autopatch

Erlang.mk will automatically patch all the dependencies it fetches. It needs to do this to ensure that the dependencies become compatible with not only Erlang.mk, but also with the version of Erlang.mk that is currently used.

When fetching a dependency, the following operations are @@ -223,7 +257,7 @@ empty Makefile generated, for compatibility purposes. 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:

NO_AUTOPATCH_ERLANG_MK = 1

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

NO_AUTOPATCH = cowboy ranch cowlib

7.9. Skipping deps

It is possible to temporarily skip all dependency operations. +projects using the NO_AUTOPATCH variable:

NO_AUTOPATCH = cowboy ranch cowlib

7.10. Skipping deps

It is possible to temporarily skip all dependency operations. This is done by defining the SKIP_DEPS variable. Use cases include being somewhere with no connection to download them, or perhaps a peculiar setup.

A typical usage would be:

$ make SKIP_DEPS=1

When the variable is defined: