From 374933627a1de6d5a4a8ea68c65ec8624388ea8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 10 Mar 2020 10:45:19 +0100 Subject: Update user guide --- guide/deps.html | 66 ++++++++++++++++++++++++++++++++++++++++++++++++-------- guide/index.html | 2 +- 2 files changed, 58 insertions(+), 10 deletions(-) diff --git a/guide/deps.html b/guide/deps.html index 0853870..fa9287c 100644 --- a/guide/deps.html +++ b/guide/deps.html @@ -92,7 +92,7 @@ can define the dep_$(DEP_NAME) variable with everyt dep_cowboy = git https://github.com/essen/cowboy 2.0.0-pre.2

This will fetch Cowboy from your fork at the given commit.

7.2.2. Fetch methods

Erlang.mk comes with a number of different fetch methods. You can fetch from Git, Mercurial, SVN, to name a few. There are fetch methods that will work everywhere, and -fetch methods that will only work in a given environment.

The following table lists all existing methods:

Name Format Description

git

git repo commit

Clone the Git repository and checkout the given version

git-subfolder

git repo commit subfolder

Clone the Git repository, checkout the given version and use one of its subfolders as a dependency

git-submodule

git-submodule

Initialize and update the Git submodule

hg

hg repo commit

Clone the Mercurial repository and update to the given version

svn

svn repo

Checkout the given SVN repository

cp

cp path/to/repo

Recursively copy a local directory

ln

ln path/to/repo

Symbolically link a local directory

hex

hex version

Download the given project version from hex.pm

fail

N/A

Always fail, reserved for internal use

legacy

N/A

Legacy Erlang.mk fetcher, reserved for internal use

The git and hg methods both have a repository and commit. +fetch methods that will only work in a given environment.

The following table lists all existing methods:

Name Format Description

git

git repo commit

Clone the Git repository and checkout the given version

git-subfolder

git repo commit subfolder

Clone the Git repository, checkout the given version and use one of its subfolders as a dependency

git-submodule

git-submodule

Initialize and update the Git submodule

hg

hg repo commit

Clone the Mercurial repository and update to the given version

svn

svn repo

Checkout the given SVN repository

cp

cp path/to/repo

Recursively copy a local directory

ln

ln path/to/repo

Symbolically link a local directory

hex

hex version [pkg]

Download the given project version from hex.pm

fail

N/A

Always fail, reserved for internal use

legacy

N/A

Legacy Erlang.mk fetcher, reserved for internal use

default

N/A

Reserved

The git and hg methods both have a repository and commit. 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:

dep_ehsa = hg https://bitbucket.org/a12n/ehsa 4.0.3

Git also comes with a concept of submodules. Erlang.mk can automatically initializes and updates submodules for dependencies, @@ -101,7 +101,8 @@ simply because the SVN repository URL can also contain the path and commit.

This would fetch an example project from the trunk:

dep_ex1 = svn https://example.com/svn/trunk/project/ex1

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

dep_ex2 = svn svn://example.com/svn/branches/erlang-proj/ex2@264

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

dep_cowboy = cp $(HOME)/ninenines/cowboy

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

dep_cowboy = hex 1.0.3

7.2.3. Custom fetch methods

If none of the existing methods fit your use, you can simply +Hex repository:

dep_cowboy = hex 1.0.3

If the package on Hex has a different name than the application, +you can provide it after the version:

dep_uuid = hex 1.7.5 uuid_erl

7.2.3. Custom fetch methods

If none of the existing methods fit your use, you can simply define your own. Erlang.mk will consider all variables that are named as dep_fetch_$(METHOD) to be available fetch methods. You can do anything inside this variable, as long @@ -191,7 +192,54 @@ by the make list-* commands.

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. +fetching of dependencies.

7.5. Querying dependencies

You can obtain information about all dependencies with +the make query-deps family of commands:

  • +make query-deps will list dependencies found in BUILD_DEPS + and DEPS recursively. +
  • +make query-doc-deps will list documentation dependencies + of the current project. +
  • +make query-rel-deps will list release dependencies + of the current project. +
  • +make query-shell-deps will list shell dependencies + of the current project. +
  • +make query-test-deps will list test dependencies + of the current project. +

By default the information printed will be the dependency name, +fetch method, repository and version, prefixed by the current +project’s name. But this output can be customized via the +variable QUERY:

$ make query-deps QUERY="name fetch_method repo version extra absolute_path"

The following options are available:

+name +
+The dependency name. +
+fetch_method +
+The dependency’s fetch method. +
+repo +
+The dependency’s repository. +
+version +
+The dependency’s version, tag or commit. +
+extra +
+Any additional information specific to the fetch method used. +
+absolute_path +
+The dependency’s location after it has been fetched. +

Fields that have no value will print -. For example +not all fetch methods have a value for the version.

The value for extra, when available, will be formatted +with the name of the information printed prefixed. For +example the hex fetch method will add +package-name=uuid_erl for the uuid application.

7.6. 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 @@ -201,7 +249,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.6. Dependencies directory

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

7.7. 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 @@ -210,7 +258,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.7. Many applications in one repository

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

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

  • @@ -243,7 +291,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.8. 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.9. 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 @@ -251,7 +299,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.9. Autopatch

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

7.10. 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 @@ -296,7 +344,7 @@ It can also be used to add compiler options, for example:

The commands will run before autopatch when the target is
 defined before including erlang.mk, and after otherwise.
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.10. Dealing with duplicate modules

When there are duplicate modules found in both applications +projects using the NO_AUTOPATCH variable:

NO_AUTOPATCH = cowboy ranch cowlib

7.11. Dealing with duplicate modules

When there are duplicate modules found in both applications and their dependencies, some tasks may fail. Erlang expects modules to be unique in general.

When the duplicates are found in dependencies, you will need to remove one of the duplicates at fetch time. To do so, you @@ -305,7 +353,7 @@ can add a rule similar to this to your Makefile before including deps:: $(DEPS_DIR)/cowlib $(verbose) rm -f $(DEPS_DIR)/cowlib/src/cow_ws.erl

This must be done from the application that has this dependency. -Only define the DEPS_DIR variable if necessary.

7.11. Skipping deps

It is possible to temporarily skip all dependency operations. +Only define the DEPS_DIR variable if necessary.

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