12 files changed, 364 insertions, 40 deletions
diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index 7c4ee68..65c09b9 100644
--- a/doc/src/guide/book.asciidoc
+++ b/doc/src/guide/book.asciidoc
@@ -36,6 +36,8 @@ include::cross_compiling.asciidoc[Cross compiling]
 
 include::compat.asciidoc[Compatibility with other build tools]
 
+include::elixir.asciidoc[Elixir modules and dependencies]
+
 [[docs]]
 = Documentation
 
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..1ac2d8a 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
@@ -151,10 +163,10 @@ variable. In the case of Cowboy, this would look like this:
 
 [source,make]
 DEPS = cowboy
-dep_cowboy_commit = 2.0.0-pre.2
+dep_cowboy_commit = 2.12.0
 
 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
@@ -163,7 +175,7 @@ can define the `dep_$(DEP_NAME)` variable with everything:
 
 [source,make]
 DEPS = cowboy
-dep_cowboy = git https://github.com/essen/cowboy 2.0.0-pre.2
+dep_cowboy = git https://github.com/essen/cowboy 2.12.0
 
 This will fetch Cowboy from your fork at the given commit.
 
@@ -252,7 +264,7 @@ 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
-as you create a folder named '$(DEPS_DIR)/$(call dep_name,$1)'.
+as you create a folder named '$(DEPS_DIR)/$(call query_name,$1)'.
 Or in layman terms, if your dependency is Cowboy, this would
 become 'deps/cowboy'.
 
@@ -261,8 +273,8 @@ To give an example, this is what the Git method does:
 [source,make]
 ----
 define dep_fetch_git
-	git clone -q -n -- $(call dep_repo,$1) $(DEPS_DIR)/$(call dep_name,$1); \
-	cd $(DEPS_DIR)/$(call dep_name,$1) && git checkout -q $(call dep_commit,$1);
+	git clone -q -n -- $(call query_repo_git,$1) $(DEPS_DIR)/$(call query_name,$1); \
+	cd $(DEPS_DIR)/$(call query_name,$1) && git checkout -q $(call query_version_git,$1);
 endef
 ----
 
@@ -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/elixir.asciidoc b/doc/src/guide/elixir.asciidoc
new file mode 100644
index 0000000..b868825
--- /dev/null
+++ b/doc/src/guide/elixir.asciidoc
@@ -0,0 +1,86 @@
+[[elixir]]
+== Elixir modules and dependencies
+
+Erlang.mk has experimental support for building Elixir
+modules as well as dependencies. In this chapter we will
+cover the details and gotchas of the Elixir support.
+
+=== Selecting Elixir
+
+By default Elixir is disabled. This is to ensure that
+there's no negative impact to normal users of Erlang.mk.
+
+Erlang.mk can use either an Elixir installed in the
+system; or use Elixir as a dependency.
+
+Elixir will be automatically enabled when Elixir is
+used as a dependency. In that case all that is required
+is to depend on Elixir:
+
+[source,make]
+----
+DEPS = elixir
+dep_elixir_commit = v1.17.3
+----
+
+Alternatively, Erlang.mk will enable the system Elixir
+installation when Elixir files are found in the top-level
+project. In that case, Elixir is assumed to be in the path.
+
+In other cases, the system Elixir installation must be
+enabled manually in order to depend on Elixir applications.
+Note that this is only required for Elixir-only applications,
+not for applications that have both Erlang and Elixir code
+(as long as you only care about the Erlang side of things).
+The `ELIXIR` variable must be defined before including
+Erlang.mk:
+
+[source,make]
+ELIXIR = system
+
+Elixir can be explicitly disabled. In that case trying to
+depend on Elixir applications will result in failure
+during autopatch, unless the Elixir application has both
+Erlang and Elixir code.
+
+[source,make]
+ELIXIR = disable
+
+=== Elixir compilation
+
+There are currently no options.
+
+=== Elixir dependencies
+
+Erlang.mk will automatically autopatch Elixir dependencies
+by running Mix on the mix.exs file and producing a Makefile
+using the generated metadata.
+
+The following is an example of depending on Elixir
+applications from an Erlang-only application:
+
+[source,make]
+----
+DEPS = jose
+dep_jose = hex 1.11.10
+
+ELIXIR = system
+
+include erlang.mk
+----
+
+=== Dialyzer
+
+Dialyzer requires Elixir to be available in order to access
+the AST of the Elixir beam files. In most cases it will just
+work. When only enabling Elixir in a sub-application, Elixir
+will not always be available, so in that case we must tell
+Dialyzer where to find Elixir libraries. This can be done
+by adding the following rules to the relevant Makefiles,
+either as a plugin or after including Erlang.mk:
+
+[source,make]
+----
+dialyze: ELIXIR_LIBS = $(dir $(shell readlink -f `which elixir`))/../lib
+dialyze: ERL_LIBS = $(APPS_DIR):$(DEPS_DIR):$(ELIXIR_LIBS)
+----
diff --git a/doc/src/guide/external_plugins.asciidoc b/doc/src/guide/external_plugins.asciidoc
index 5f165f5..bb42f1a 100644
--- a/doc/src/guide/external_plugins.asciidoc
+++ b/doc/src/guide/external_plugins.asciidoc
@@ -90,7 +90,7 @@ help-plugins::
 Plugins declared in `DEP_PLUGINS` are loaded near the end of Erlang.mk.
 That's why you have access to all previously initialized variables.
 However, if you want your plugin to add common dependencies to
-your applications, a regular is loaded too late in the process.
+your applications, a regular plugin is loaded too late in the process.
 You need to use "Early-stage plugins". They are declared using the
 `DEP_EARLY_PLUGINS` variable instead. Plugins listed in this variable
 are loaded near the beginning of Erlang.mk Otherwise, they work exactly
@@ -111,7 +111,7 @@ DEPS += cowboy
 TEST_DEPS = ct_helper
 dep_ct_helper = git https://github.com/ninenines/ct_helper master
 
-=== Loading  plugins local to the application
+=== Loading plugins local to the application
 
 If the Erlang.mk plugin lives in the same directory or repository as your
 application or library, then you can load it exactly like an external
@@ -138,3 +138,27 @@ your application:
 DEP_EARLY_PLUGINS = $(PROJECT)
 # Loads ./plugins.mk
 DEP_PLUGINS = $(PROJECT)
+
+=== Adding templates via plugins
+
+Plugins may add templates either from within their Makefile or from
+an external file. The recommended method is to use an external file;
+however do note it only works for Make 4 and above:
+
+[source,make]
+THIS := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
+tpl_test_mk = $(file < $(THIS)/templates/my_template.erl)
+
+With 'templates/my_template.erl' containing:
+
+[source,erlang]
+-module(template_name).
+
+Erlang.mk will do string substitution replacing the following
+strings with their equivalent:
+
+* `template_name`: the name provided by the user
+* `project_name`: either `$(PROJECT)` or the target application's name
+* `template_sp`: internal; propagates whitespace settings to Makefiles
+* `rel_deps_dir`: internal; path to deps/* from within an apps/* Makefile
+* `rel_root_dir`: internal; path to top-level directory from within an apps/* Makefile
diff --git a/doc/src/guide/getting_started.asciidoc b/doc/src/guide/getting_started.asciidoc
index be58e87..904cd7d 100644
--- a/doc/src/guide/getting_started.asciidoc
+++ b/doc/src/guide/getting_started.asciidoc
@@ -12,6 +12,11 @@ contain your project.
 $ mkdir hello_joe
 $ cd hello_joe
 
+Note that the project directory name must match the name of
+your application for some of the functionality to work (such
+as OTP releases). The name should only include letters, numbers
+or underscore as well for better compatibility.
+
 Most people tend to put all their projects side by side in
 a common folder. We recommend keeping an organization similar
 to your remote repositories. For example, for GitHub users,
@@ -266,8 +271,20 @@ You can list all available templates with the `list-templates`
 target:
 
 [source,bash]
+----
 $ make list-templates
-Available templates: cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server gen_statem ranch_protocol supervisor
+Available templates:
+    cowboy_http_h
+    cowboy_loop_h
+    cowboy_rest_h
+    cowboy_websocket_h
+    gen_fsm
+    gen_server
+    gen_statem
+    module
+    ranch_protocol
+    supervisor
+----
 
 To generate a module, let's say a `gen_server`, all you need to
 do is to call `make new` with the appropriate arguments:
@@ -345,7 +362,8 @@ Bootstrap targets:
 
 This guide should provide any other answer. If not, please
 open a ticket on https://github.com/ninenines/erlang.mk/issues[the official repository]
-and we will work on improving the guide.
+and we will work on improving the guide. For any other questions,
+please visit the https://discord.gg/x25nNq2fFE[Erlang OSS Discord server].
 
 Commercial support is available through Nine Nines. Please contact
 Loïc Hoguin by sending an email to mailto:[email protected][].
diff --git a/doc/src/guide/installation.asciidoc b/doc/src/guide/installation.asciidoc
index 0c21fb0..b3ab551 100644
--- a/doc/src/guide/installation.asciidoc
+++ b/doc/src/guide/installation.asciidoc
@@ -82,13 +82,13 @@ MSYS2 in order to use Erlang.mk.
 
 Erlang.mk requires Erlang/OTP to be installed. The OTP team
 provides binaries of Erlang/OTP for all major and minor releases,
-available from the http://www.erlang.org/download.html[official download page].
+available from the https://www.erlang.org/downloads[official download page].
 It is recommended that you use the 64-bit installer unless
 technically impossible. Please follow the instructions from
 the installer to complete the installation.
 
 The OTP team also provides a short guide to
-http://www.erlang.org/download.html[installing Erlang/OTP on Windows]
+https://www.erlang.org/downloads[installing Erlang/OTP on Windows]
 if you need additional references.
 
 You can install Erlang/OTP silently using the `/S` switch
@@ -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