Update user guide

guide/ci.html

@@ -38,12 +38,8 @@
 one specific Erlang/OTP release. (If you target one specific
 release, check the <a class="link" href="kerl.html#otp_version_pinning" title="12.2. OTP version pinning">OTP version pinning</a>
 section of the <a class="link" href="kerl.html" title="Chapter 12. OTP version management">OTP version management</a> chapter.)</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_configuring_erlang_otp_versions_to_test"></a>24.1. Configuring Erlang/OTP versions to test</h2></div></div></div><p>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.</p><p>At the time of writing, this is how you would test against all
-the most recent patch releases of Erlang/OTP 19 and above:</p><pre class="programlisting">CI_OTP = OTP-19.0.7 OTP-19.1.6 OTP-19.2.3 OTP-19.3.6.2 OTP-20.0.4</pre><p>If you want to test against HiPE and ErLLVM but only with the
-latest version of Erlang/OTP, the following could work:</p><pre class="programlisting">CI_HIPE = $(lastword $(CI_OTP))
-CI_ERLLVM = $(CI_HIPE)</pre><p>Consult the <a class="link" href="kerl.html" title="Chapter 12. OTP version management">OTP version management</a> chapter for more
+of Erlang/OTP will be used.</p><p>At the time of writing, this is how you would test against all
+the most recent patch releases of Erlang/OTP 19 and above:</p><pre class="programlisting">CI_OTP = OTP-19.0.7 OTP-19.1.6 OTP-19.2.3 OTP-19.3.6.2 OTP-20.0.4</pre><p>Consult the <a class="link" href="kerl.html" title="Chapter 12. OTP version management">OTP version management</a> chapter for more
 information about Erlang/OTP versions and customization of the
 Erlang/OTP builds.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_running_tests_across_all_configured_versions"></a>24.2. Running tests across all configured versions</h2></div></div></div><p>The recommended way to run the <code class="literal">ci</code> target is with the option
 <code class="literal">-k</code>. It will ensure that tests are run for all configured

guide/coverage.html

@@ -48,10 +48,12 @@
 to all test frameworks and might be more useful.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_adding_applications_to_the_cover_report"></a>23.2. Adding applications to the cover report</h2></div></div></div><p>By default Erlang.mk will include all the applications
 in the code coverage report, except external dependencies.</p><p>To include some dependencies in the report, you can
 define the <code class="literal">COVER_DEPS</code> variable:</p><pre class="programlisting">COVER_DEPS = cowlib</pre><p>When using multi application repositories you can exclude
-some applications by defining the <code class="literal">COVER_APPS</code> variable:</p><pre class="programlisting">COVER_APPS = presence backend</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_configuring_paths"></a>23.3. Configuring paths</h2></div></div></div><p>By default Erlang.mk will store <span class="emphasis"><em>coverdata</em></span> files and
+some applications by defining the <code class="literal">COVER_APPS</code> variable:</p><pre class="programlisting">COVER_APPS = presence backend</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_removing_modules_from_the_cover_report"></a>23.3. Removing modules from the cover report</h2></div></div></div><p>By default Erlang.mk will include all modules in the
+cover report.</p><p>To exclude some modules from the report, you can
+define the <code class="literal">COVER_EXCLUDE_MODS</code> variable:</p><pre class="programlisting">COVER_EXCLUDE_MODS = cowboy_app cowboy_sup</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_configuring_paths"></a>23.4. Configuring paths</h2></div></div></div><p>By default Erlang.mk will store <span class="emphasis"><em>coverdata</em></span> files and
 code coverage reports under the <span class="emphasis"><em>cover/</em></span> directory. The
 variables <code class="literal">COVER_DATA_DIR</code> and <code class="literal">COVER_REPORT_DIR</code> can be
-set to use a different location.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_merging_coverdata_files"></a>23.4. Merging coverdata files</h2></div></div></div><p>The target <code class="literal">all.coverdata</code> will take all existing
+set to use a different location.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_merging_coverdata_files"></a>23.5. Merging coverdata files</h2></div></div></div><p>The target <code class="literal">all.coverdata</code> will take all existing
 <span class="emphasis"><em>coverdata</em></span> files and merge them into one:</p><pre class="programlisting">$ make all.coverdata</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="triq.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tests.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ci.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div>
 </main>
 </body>

guide/ct.html

@@ -57,7 +57,8 @@
 <code class="literal">http_SUITE</code> test suite, write:</p><pre class="programlisting">$ make ct-http t=http_compress</pre><p>Similarly, to run a specific test case in that group:</p><pre class="programlisting">$ make ct-http t=http_compress:headers_dupe</pre><p>To do the same against a multi-application repository,
 you can use the <code class="literal">-C</code> option:</p><pre class="programlisting">$ make -C apps/my_app ct-http t=my_group:my_case</pre><p>Note that this also applies to dependencies. When using Cowboy
 as a dependency, you can run the following directly:</p><pre class="programlisting">$ make -C deps/cowboy ct-http t=http_compress</pre><p>The variable <code class="literal">c</code> can be used to run a specific test when
-the test suite does not group test cases:</p><pre class="programlisting">$ make ct-http c=headers_dupe</pre><p>Finally, <a class="link" href="coverage.html" title="Chapter 23. Code coverage">code coverage</a> is available,
+the test suite does not group test cases:</p><pre class="programlisting">$ make ct-http c=headers_dupe</pre><p>A test within a specific subgroup can be run by providing a
+group path:</p><pre class="programlisting">$ make ct-http t=[top_level_group,second_level_group,third_level_group]:my_case</pre><p>Finally, <a class="link" href="coverage.html" title="Chapter 23. Code coverage">code coverage</a> is available,
 but covered in its own chapter.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eunit.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tests.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="proper.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div>
 </main>
 </body>

guide/deps.html

@@ -81,15 +81,20 @@
 deps
 </span></dt><dd>
 $(CURDIR)/deps/triq
-</dd></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_modifying_the_dependency_source_or_version"></a>7.2.1. Modifying the dependency source or version</h3></div></div></div><p>By default, Erlang.mk will look into its package index to
+</dd></dl></div><p>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
+<code class="literal">OPTIONAL_DEPS</code> may be used:</p><pre class="programlisting">OPTIONAL_DEPS = quicer</pre><p>The top-level project can then decide whether to include this
+application by adding it to its <code class="literal">BUILD_DEPS</code> and including
+it in the release dependencies.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_modifying_the_dependency_source_or_version"></a>7.2.1. Modifying the dependency source or version</h3></div></div></div><p>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:</p><pre class="programlisting">DEPS = cowboy</pre><p>If you need a different version, you need to define another
 variable. There are two ways to do this, each being useful
 for different reasons.</p><p>If you simply want to change the commit number, all you
 need to do is to define the <code class="literal">dep_$(DEP_NAME)_commit</code>
 variable. In the case of Cowboy, this would look like this:</p><pre class="programlisting">DEPS = cowboy
 dep_cowboy_commit = 2.0.0-pre.2</pre><p>Erlang.mk will use the package index to get all information
-about Cowboy, except the commit number which will be overriden.</p><p>If you need to set the fetch method or repository information
+about Cowboy, except the commit number which will be overridden.</p><p>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 <code class="literal">dep_$(DEP_NAME)</code> variable with everything:</p><pre class="programlisting">DEPS = cowboy
@@ -316,10 +321,8 @@
 </li><li class="listitem">
 Run autopatch on the project
 </li></ul></div><p>Autopatch first checks if there is any project-specific patch
-enabled. There are currently three: <code class="literal">RABBITMQ_CLIENT_PATCH</code> for
-the <code class="literal">amqp_client</code> dependency (before 3.6.0), <code class="literal">RABBITMQ_SERVER_PATCH</code>
-for the <code class="literal">rabbit</code> dependency (before 3.6.0) and <code class="literal">ELIXIR_PATCH</code>
-for the <code class="literal">elixir</code> dependency.</p><p>Otherwise, autopatch performs different operations depending
+enabled. There are currently two: <code class="literal">ELIXIR_PATCH</code> for the <code class="literal">elixir</code>
+dependency and <code class="literal">HUT_PATCH</code> for the <code class="literal">hut</code> dependency.</p><p>Otherwise, autopatch performs different operations depending
 on the kind of project it finds the dependency to be.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 Rebar projects are automatically converted to use Erlang.mk
 as their build tool. This essentially patches Rebar out, and

guide/installation.html

@@ -84,7 +84,7 @@
 C:\&gt; 7z x msys2.tar &gt; NUL</pre><p>Then you can run the two commands needed to perform the
 post-installation setup:</p><pre class="screen">C:\&gt; C:\msys64\usr\bin\bash -lc "pacman --needed --noconfirm -Sy bash pacman pacman-mirrors msys2-runtime"
 C:\&gt; C:\msys64\usr\bin\bash -lc "pacman --noconfirm -Syu"</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_installing_the_required_msys2_packages"></a>1.2.3. Installing the required MSYS2 packages</h3></div></div></div><p>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 <code class="literal">pacman</code> directly:</p><pre class="programlisting">$ pacman -S git make</pre><p>You can use <code class="literal">pacman -Ss</code> to search packages. For example,
 to find all packages related to GCC:</p><pre class="programlisting">$ pacman -Ss gcc</pre><p>If you are going to compile C/C++ code, you will need to
 install this package, as Erlang.mk cannot use the normal

guide/ports.html

@@ -72,7 +72,7 @@
 default except for the extension: <code class="literal">.exe</code> on Windows, and otherwise
 nothing.</p><p>Erlang.mk sets appropriate compile and linker flags by default.
 These flags vary depending on the platform, and can of course
-be overriden.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+be overridden.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
 <code class="literal">CC</code>
 </span></dt><dd>
     The compiler to be used.

guide/relx.html

@@ -35,8 +35,10 @@
 
 <div class="navheader"><table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ports.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="sfx.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="relx"></a>Chapter 9. Releases</h2></div></div></div><p>Erlang.mk relies on <span class="emphasis"><em>Relx</em></span> for generating releases. This
 chapter covers the Erlang.mk-specific bits. Consult the
-<a class="ulink" href="https://erlware.github.io/relx/" target="_top">Relx website</a> for more information.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_setup"></a>9.1. Setup</h2></div></div></div><p>Erlang.mk will create a release if it detects a Relx configuration
-file in the <span class="emphasis"><em>$(RELX_CONFIG)</em></span> location. This defaults to
+<a class="ulink" href="https://erlware.github.io/relx/" target="_top">Relx website</a> for more information.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_setup"></a>9.1. Setup</h2></div></div></div><p>First, <code class="literal">relx</code> must be added in the dependencies of your
+project. You can add it to <code class="literal">REL_DEPS</code> so that it is fetched
+whenever you need to build the release:</p><pre class="programlisting">REL_DEPS = relx</pre><p>Then, you need to create a <span class="emphasis"><em>relx.config</em></span> file in the
+<span class="emphasis"><em>$(RELX_CONFIG)</em></span> location. This defaults to
 <span class="emphasis"><em>$(CURDIR)/relx.config</em></span>. You can override it by defining
 the variable before including Erlang.mk:</p><pre class="programlisting">RELX_CONFIG = $(CURDIR)/webchat.config</pre><p>It is also possible to have multiple <span class="emphasis"><em>relx.config</em></span> 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</pre><p>Relx does not need to be installed. Erlang.mk will download
-and build it automatically.</p><p>The Relx executable will be saved in the <span class="emphasis"><em>$(RELX)</em></span> file. This
-location defaults to <span class="emphasis"><em>$(CURDIR)/relx</em></span> and can be overriden.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_configuration"></a>9.2. Configuration</h2></div></div></div><p>You can specify additional Relx options using the <code class="literal">RELX_OPTS</code>
+endif</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_configuration"></a>9.2. Configuration</h2></div></div></div><p>You can specify additional Relx options using the <code class="literal">RELX_OPTS</code>
 variable. For example, to enable <code class="literal">dev_mode</code>:</p><pre class="programlisting">RELX_OPTS = -d true</pre><p>While you can specify the output directory for the release
 in the Relx options directly, Erlang.mk provides a specific
 variable for it: <code class="literal">RELX_OUTPUT_DIR</code>. It defaults to the <span class="emphasis"><em>_rel</em></span>