From 62684cfaaff153700d61b8f94a745577751cbf4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 23 Jan 2024 13:55:08 +0100 Subject: [PATCH] Update user guide --- guide/ci.html | 8 ++------ guide/coverage.html | 6 ++++-- guide/ct.html | 3 ++- guide/deps.html | 15 +++++++++------ guide/index.html | 2 +- guide/installation.html | 2 +- guide/ports.html | 2 +- guide/relx.html | 10 +++++----- 8 files changed, 25 insertions(+), 23 deletions(-) diff --git a/guide/ci.html b/guide/ci.html index 81706a3a8..bd18f244d 100644 --- a/guide/ci.html +++ b/guide/ci.html @@ -38,12 +38,8 @@ one specific Erlang/OTP release. (If you target one specific release, check the OTP version pinning section of the OTP version management chapter.)

24.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 -the most recent patch releases of Erlang/OTP 19 and above:

CI_OTP = OTP-19.0.7 OTP-19.1.6 OTP-19.2.3 OTP-19.3.6.2 OTP-20.0.4

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

CI_HIPE = $(lastword $(CI_OTP))
-CI_ERLLVM = $(CI_HIPE)

Consult the OTP version management chapter for more +of Erlang/OTP will be used.

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

CI_OTP = OTP-19.0.7 OTP-19.1.6 OTP-19.2.3 OTP-19.3.6.2 OTP-20.0.4

Consult the OTP version management chapter for more information about Erlang/OTP versions and customization of the Erlang/OTP builds.

24.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 diff --git a/guide/coverage.html b/guide/coverage.html index 85d593519..dffab2da3 100644 --- a/guide/coverage.html +++ b/guide/coverage.html @@ -48,10 +48,12 @@ to all test frameworks and might be more useful.

23.2. Adding applications to the cover report

By default Erlang.mk will include all the applications in the code coverage report, except external dependencies.

To include some dependencies in the report, you can define the COVER_DEPS variable:

COVER_DEPS = cowlib

When using multi application repositories you can exclude -some applications by defining the COVER_APPS variable:

COVER_APPS = presence backend

23.3. Configuring paths

By default Erlang.mk will store coverdata files and +some applications by defining the COVER_APPS variable:

COVER_APPS = presence backend

23.3. Removing modules from the cover report

By default Erlang.mk will include all modules in the +cover report.

To exclude some modules from the report, you can +define the COVER_EXCLUDE_MODS variable:

COVER_EXCLUDE_MODS = cowboy_app cowboy_sup

23.4. Configuring paths

By default Erlang.mk will store coverdata files and code coverage reports under the cover/ directory. The variables COVER_DATA_DIR and COVER_REPORT_DIR can be -set to use a different location.

23.4. Merging coverdata files

The target all.coverdata will take all existing +set to use a different location.

23.5. Merging coverdata files

The target all.coverdata will take all existing coverdata files and merge them into one:

$ make all.coverdata
Prev Up Next
 Home 
diff --git a/guide/ct.html b/guide/ct.html index 023025931..9520c3792 100644 --- a/guide/ct.html +++ b/guide/ct.html @@ -57,7 +57,8 @@ 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

The variable c can be used to run a specific test when -the test suite does not group test cases:

$ make ct-http c=headers_dupe

Finally, code coverage is available, +the test suite does not group test cases:

$ make ct-http c=headers_dupe

A test within a specific subgroup can be run by providing a +group path:

$ make ct-http t=[top_level_group,second_level_group,third_level_group]:my_case

Finally, code coverage is available, but covered in its own chapter.

Prev Up Next
 Home 
diff --git a/guide/deps.html b/guide/deps.html index f2de86913..fe08502a4 100644 --- a/guide/deps.html +++ b/guide/deps.html @@ -81,7 +81,12 @@ deps
$(CURDIR)/deps/triq -

7.2.1. Modifying the dependency source or version

By default, Erlang.mk will look into its package index to +

Sometimes dependencies are allowed to be missing. However, your application +may depend on an optional application being started. To ensure that an +optional dependency is started before your application, the variable +OPTIONAL_DEPS may be used:

OPTIONAL_DEPS = quicer

The top-level project can then decide whether to include this +application by adding it to its BUILD_DEPS and including +it in the release dependencies.

7.2.1. Modifying the dependency source or version

By default, Erlang.mk will look into its package index to find the project you are looking for, if you only provide its name. This is this case:

DEPS = cowboy

If you need a different version, you need to define another variable. There are two ways to do this, each being useful @@ -89,7 +94,7 @@ need to do is to define the dep_$(DEP_NAME)_commit variable. In the case of Cowboy, this would look like this:

DEPS = cowboy
 dep_cowboy_commit = 2.0.0-pre.2

Erlang.mk will use the package index to get all information -about Cowboy, except the commit number which will be overriden.

If you need to set the fetch method or repository information +about Cowboy, except the commit number which will be overridden.

If you need to set the fetch method or repository information 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:

DEPS = cowboy
@@ -316,10 +321,8 @@
 
  • 
 Run autopatch on the project

    • Autopatch first checks if there is any project-specific patch -enabled. There are currently three: RABBITMQ_CLIENT_PATCH for -the amqp_client dependency (before 3.6.0), RABBITMQ_SERVER_PATCH -for the rabbit dependency (before 3.6.0) and ELIXIR_PATCH -for the elixir dependency.

    Otherwise, autopatch performs different operations depending +enabled. There are currently two: ELIXIR_PATCH for the elixir +dependency and HUT_PATCH for the hut dependency.

    Otherwise, autopatch performs different operations depending on the kind of project it finds the dependency to be.

    1.2.3. Installing the required MSYS2 packages

    After following these instructions, you can install GNU Make, -Git and any other required softwares. From an MSYS2 shell, +Git and any other required software. From an MSYS2 shell, you can call pacman directly:

    $ pacman -S git make

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

    $ pacman -Ss gcc

    If you are going to compile C/C++ code, you will need to install this package, as Erlang.mk cannot use the normal diff --git a/guide/ports.html b/guide/ports.html index a741cbabd..008b25635 100644 --- a/guide/ports.html +++ b/guide/ports.html @@ -72,7 +72,7 @@ default except for the extension: .exe on Windows, and otherwise nothing.

    Erlang.mk sets appropriate compile and linker flags by default. These flags vary depending on the platform, and can of course -be overriden.

    +be overridden.

    CC
    The compiler to be used. diff --git a/guide/relx.html b/guide/relx.html index 88fc61783..1b5f44b5b 100644 --- a/guide/relx.html +++ b/guide/relx.html @@ -35,8 +35,10 @@
    Prev   Next

    Chapter 9. Releases

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

    9.1. Setup

    Erlang.mk will create a release if it detects a Relx configuration -file in the $(RELX_CONFIG) location. This defaults to +Relx website for more information.

    9.1. Setup

    First, relx must be added in the dependencies of your +project. You can add it to REL_DEPS so that it is fetched +whenever you need to build the release:

    REL_DEPS = relx

    Then, you need to create a relx.config file in the +$(RELX_CONFIG) location. This defaults to $(CURDIR)/relx.config. You can override it by defining the variable before including Erlang.mk:

    RELX_CONFIG = $(CURDIR)/webchat.config

    It is also possible to have multiple relx.config files. For example you might have one for development and one for @@ -45,9 +47,7 @@ RELX_CONFIG = $(CURDIR)/relx.prod.config else RELX_CONFIG = $(CURDIR)/relx.dev.config -endif

    Relx does not need to be installed. Erlang.mk will download -and build it automatically.

    The Relx executable will be saved in the $(RELX) file. This -location defaults to $(CURDIR)/relx and can be overriden.

    9.2. Configuration

    You can specify additional Relx options using the RELX_OPTS +endif

    9.2. Configuration

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

    RELX_OPTS = -d true

    While you can specify the output directory for the release in the Relx options directly, Erlang.mk provides a specific variable for it: RELX_OUTPUT_DIR. It defaults to the _rel