8 files changed, 223 insertions, 29 deletions
diff --git a/doc/src/guide/ci.asciidoc b/doc/src/guide/ci.asciidoc
index 2b69e28..2fa5feb 100644
--- a/doc/src/guide/ci.asciidoc
+++ b/doc/src/guide/ci.asciidoc
@@ -10,9 +10,7 @@ section of the xref:kerl[OTP version management] chapter.)
 === 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.
+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:
@@ -20,13 +18,6 @@ the most recent patch releases of Erlang/OTP 19 and above:
 [source,make]
 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:
-
-[source,make]
-CI_HIPE = $(lastword $(CI_OTP))
-CI_ERLLVM = $(CI_HIPE)
-
 Consult the xref:kerl[OTP version management] chapter for more
 information about Erlang/OTP versions and customization of the
 Erlang/OTP builds.
diff --git a/doc/src/guide/common_test.asciidoc b/doc/src/guide/common_test.asciidoc
index 993bb8c..05e43eb 100644
--- a/doc/src/guide/common_test.asciidoc
+++ b/doc/src/guide/common_test.asciidoc
@@ -99,5 +99,11 @@ the test suite does not group test cases:
 [source,bash]
 $ make ct-http c=headers_dupe
 
+A test within a specific subgroup can be run by providing a
+group path:
+
+[source,bash]
+$ make ct-http t=[top_level_group,second_level_group,third_level_group]:my_case
+
 Finally, xref:coverage[code coverage] is available,
 but covered in its own chapter.
diff --git a/doc/src/guide/coverage.asciidoc b/doc/src/guide/coverage.asciidoc
index 02f8b5b..af159d8 100644
--- a/doc/src/guide/coverage.asciidoc
+++ b/doc/src/guide/coverage.asciidoc
@@ -46,6 +46,17 @@ some applications by defining the `COVER_APPS` variable:
 [source,make]
 COVER_APPS = presence backend
 
+=== 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:
+
+[source,make]
+COVER_EXCLUDE_MODS = cowboy_app cowboy_sup
+
 === Configuring paths
 
 By default Erlang.mk will store 'coverdata' files and
diff --git a/doc/src/guide/deps.asciidoc b/doc/src/guide/deps.asciidoc
index 081f4f7..c46dce6 100644
--- a/doc/src/guide/deps.asciidoc
+++ b/doc/src/guide/deps.asciidoc
@@ -132,6 +132,18 @@ target `deps::` before including 'erlang.mk', for example:
 [source,make]
 deps:: $(CURDIR)/deps/triq
 
+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:
+
+[source,make]
+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.
+
 ==== Modifying the dependency source or version
 
 By default, Erlang.mk will look into its package index to
@@ -154,7 +166,7 @@ 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.
+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
@@ -559,10 +571,8 @@ performed:
 * 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.
+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.
diff --git a/doc/src/guide/installation.asciidoc b/doc/src/guide/installation.asciidoc
index 0c21fb0..1f7e178 100644
--- a/doc/src/guide/installation.asciidoc
+++ b/doc/src/guide/installation.asciidoc
@@ -134,7 +134,7 @@ C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -Syu"
 ==== 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:
 
 [source,bash]
diff --git a/doc/src/guide/ports.asciidoc b/doc/src/guide/ports.asciidoc
index 907ee36..3be5bf2 100644
--- a/doc/src/guide/ports.asciidoc
+++ b/doc/src/guide/ports.asciidoc
@@ -81,7 +81,7 @@ 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/doc/src/guide/releases.asciidoc b/doc/src/guide/releases.asciidoc
index 68174b3..a3bdb10 100644
--- a/doc/src/guide/releases.asciidoc
+++ b/doc/src/guide/releases.asciidoc
@@ -7,8 +7,15 @@ https://erlware.github.io/relx/[Relx website] for more information.
 
 === Setup
 
-Erlang.mk will create a release if it detects a Relx configuration
-file in the '$(RELX_CONFIG)' location. This defaults to
+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:
+
+[source,erlang]
+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:
 
@@ -29,14 +36,6 @@ 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.
-
-// @todo You can use a custom location by ???
-
 === Configuration
 
 You can specify additional Relx options using the `RELX_OPTS`
diff --git a/doc/src/guide/xref.asciidoc b/doc/src/guide/xref.asciidoc
index 44ed190..07bf05e 100644
--- a/doc/src/guide/xref.asciidoc
+++ b/doc/src/guide/xref.asciidoc
@@ -1,6 +1,183 @@
 [[xref]]
 == Xref
 
-// @todo Write it.
+Xref is a cross reference tool for analyzing dependencies
+between functions, modules, applications and releases.
+Erlang.mk provides an interface to analyzing all except
+the releases.
 
-Placeholder chapter.
+Both predefined checks and custom queries are supported
+in Erlang.mk.
+
+=== Usage
+
+To run Xref with the default predefined checks:
+
+[source,bash]
+$ make xref
+
+Erlang.mk will error out when warnings are found.
+
+The following predefined checks can be used:
+
+* `undefined_function_calls`
+* `undefined_functions` (similar to the previous)
+* `locals_not_used` (detected by the compiler)
+* `exports_not_used`
+* `deprecated_function_calls` (also detected by the compiler)
+* `deprecated_functions` (similar to the previous)
+* `{deprecated_function_calls, Flag}`
+* `{deprecated_functions, Flag}` (similar to the previous)
+
+Erlang.mk will only run the `undefined_function_calls`
+check by default.
+
+To change the check the `XREF_CHECKS` variable can be used:
+
+[source,bash]
+$ make xref XREF_CHECKS=exports_not_used
+
+Multiple checks can be run at once. The checks variable
+must be defined as an Erlang list:
+
+[source,bash]
+$ make xref XREF_CHECKS="[undefined_function_calls, exports_not_used]"
+
+Erlang.mk also supports informational analyses. Those will
+not error out when results are found, since they are not
+errors. To find all modules that call `cowboy_req` functions:
+
+[source,bash]
+$ make xref XREF_CHECKS="{module_use, cowboy_req}"
+
+The following informational checks are supported:
+
+* `{call, MFA}` - functions that MFA calls
+* `{use, MFA}` - functions that call MFA
+* `{module_call, Mod}` - modules that Mod calls (Mod depends on them)
+* `{module_use, Mod}` - modules that call Mod (they depend on Mod)
+* `{application_call, App}` - apps that App calls (App depends on them)
+* `{application_use, App}` - apps that call App (they depend on App)
+
+The scope might need to be increased in order to obtain
+the complete results of informational checks. This is
+especially true for module and applications, with
+application results being dependent on the applications
+being added to the scope to be found.
+
+=== Queries
+
+Erlang.mk provides an interface to the Xref query
+functions. To perform a query, the `q` variable
+must be used instead of `XREF_CHECKS`. For example,
+to obtain all unresolved calls:
+
+[source,bash]
+$ make xref q=UC
+
+The query language is documented at the top of the
+link:https://www.erlang.org/doc/man/xref.html[Xref manual page].
+
+=== Analysis scope
+
+Erlang.mk will set the scope of analysis to the current
+project by default. The scope can be automatically
+extended to the applications from multi-application
+repositories, to dependencies and to the built-in
+Erlang/OTP applications themselves.
+
+To change the scope, the `XREF_SCOPE` variable can be
+set. The variable can either be set in your Makefile
+or from the command line. The following values can
+be defined:
+
+* `app` - the current project
+* `apps` - applications from multi-application repositories
+* `deps` - dependencies
+* `otp` - Erlang/OTP applications
+
+To get the most complete analysis possible they should
+all be added to the variable:
+
+[source,bash]
+----
+$ make xref XREF_CHECKS="{application_use, ssl}" XREF_SCOPE="app apps deps otp"
+Application ssl is used by:
+- my_app
+- diameter
+- eldap
+- ftp
+- inets
+- ssl
+----
+
+Additional applications can be provided using the
+`XREF_EXTRA_APP_DIRS` variable. Note that these
+applications will need to be compiled before they
+can be found by Xref.
+
+Similarly, non-application directories can be
+added using `XREF_EXTRA_DIRS`. The directory
+to be provided must be the one that contains
+the beam files.
+
+=== Ignoring warnings
+
+Sometimes it is necessary to ignore warnings because
+they are expected. This is the case for example
+when multiple Erlang/OTP versions must be supported
+and modules or functions have been added or removed.
+
+Erlang.mk supports both project-wide configuration
+and Rebar-compatible inline ignores. To ignore
+warnings for a function in the current module the
+following line can be added to the source file:
+
+[source,erlang]
+----
+-ignore_xref({log, 1}).
+----
+
+The module name can be specified explicitly:
+
+[source,erlang]
+----
+-ignore_xref({my_mod, log, 1}).
+----
+
+As well as a full module can be ignored:
+
+[source,erlang]
+----
+-ignore_xref(my_mod).
+----
+
+The ignored functions can be provided as a list:
+
+[source,erlang]
+----
+-ignore_xref([{log, 1}, {pretty_print, 1}]).
+----
+
+The `XREF_IGNORE` variable can be used to define
+functions and modules to ignore project-wide. It
+accepts either MFAs or modules:
+
+[source,make]
+XREF_IGNORE = {my_mod, log, 1}
+
+Multiple ignores must be provided as an Erlang
+list:
+
+[source,make]
+XREF_IGNORE = [{my_mod, log, 1}, other_mod]
+
+By default Erlang.mk will ignore unused exports
+for behavior callbacks when the `exports_not_used`
+check is run. It is possible to override this
+behavior, or to ignore the callbacks for queries
+and other checks, by defining the `XREF_IGNORE_CALLBACKS`
+variable:
+
+[source,bash]
+$ make xref XREF_CHECKS=exports_not_used XREF_IGNORE_CALLBACKS=0