summaryrefslogtreecommitdiffstats
path: root/docs/en/erlang.mk/1/guide/app/index.html
diff options
context:
space:
mode:
Diffstat (limited to 'docs/en/erlang.mk/1/guide/app/index.html')
-rw-r--r--docs/en/erlang.mk/1/guide/app/index.html1147
1 files changed, 603 insertions, 544 deletions
diff --git a/docs/en/erlang.mk/1/guide/app/index.html b/docs/en/erlang.mk/1/guide/app/index.html
index 49f9c1f4..c4fa21f7 100644
--- a/docs/en/erlang.mk/1/guide/app/index.html
+++ b/docs/en/erlang.mk/1/guide/app/index.html
@@ -7,7 +7,7 @@
<meta name="description" content="">
<meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara">
- <meta name="generator" content="Hugo 0.17" />
+ <meta name="generator" content="Hugo 0.26" />
<title>Nine Nines: Building</title>
@@ -67,555 +67,614 @@
<h1 class="lined-header"><span>Building</span></h1>
-<div class="paragraph"><p>Erlang.mk can do a lot of things, but it is, first and
-foremost, a build tool. In this chapter we will cover
-the basics of building a project with Erlang.mk.</p></div>
-<div class="paragraph"><p>For most of this chapter, we will assume that you are
-using a project <a href="../getting_started">generated by Erlang.mk</a>.</p></div>
-<div class="sect1">
-<h2 id="_how_to_build">How to build</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To build a project, all you have to do is type <code>make</code>:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ make</tt></pre></div></div>
-<div class="paragraph"><p>It will work regardless of your project: OTP applications,
-library applications, NIFs, port drivers or even releases.
-Erlang.mk also automatically downloads and compiles the
-dependencies for your project.</p></div>
-<div class="paragraph"><p>All this is possible thanks to a combination of configuration
-and conventions. Most of the conventions come from Erlang/OTP
-itself so any seasoned Erlang developers should feel right at
-home.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_what_to_build">What to build</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk gives you control over three steps of the build
-process, allowing you to do a partial build if needed.</p></div>
-<div class="paragraph"><p>A build has three phases: first any dependency is fetched
-and built, then the project itself is built and finally a
-release may be generated when applicable. A release is only
-generated for projects specifically configured to do so.</p></div>
-<div class="paragraph"><p>Erlang.mk handles those three phases automatically when you
-type <code>make</code>. But sometimes you just want to repeat one or
-two of them.</p></div>
-<div class="paragraph"><p>The commands detailed in this section are most useful after
-you have a successful build as they allow you to quickly
-redo a step instead of going through everything. This is
-especially useful for large projects or projects that end
-up generating releases.</p></div>
-<div class="sect3">
-<h4 id="_application">Application</h4>
-<div class="paragraph"><p>You can build your application and dependencies without
-generating a release by running the following command:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ make app</tt></pre></div></div>
-<div class="paragraph"><p>To build your application without touching dependencies
-at all, you can use the <code>SKIP_DEPS</code> variable:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ make app <span style="color: #009900">SKIP_DEPS</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div>
-<div class="paragraph"><p>This command is very useful if you have a lot of dependencies
-and develop on a machine with slow file access, like the
-Raspberry Pi and many other embedded devices.</p></div>
-<div class="paragraph"><p>Note that this command may fail if a required dependency
-is missing.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_dependencies">Dependencies</h4>
-<div class="paragraph"><p>You can build all dependencies, and nothing else, by
-running the following command:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ make deps</tt></pre></div></div>
-<div class="paragraph"><p>This will fetch and compile all dependencies and their
-dependencies, recursively.</p></div>
-<div class="paragraph"><p><a href="../deps">Packages and dependencies</a> are covered
-in the next chapter.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_release">Release</h4>
-<div class="paragraph"><p>It is not possible to build the release without at least
-building the application itself, unless of course if there&#8217;s
-no application to begin with.</p></div>
-<div class="paragraph"><p>To generate the release, <code>make</code> will generally suffice with
-a normal Erlang.mk. A separate target is however available,
-and will take care of building the release, after building
-the application and all dependencies:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ make rel</tt></pre></div></div>
-<div class="paragraph"><p>Consult the <a href="../relx">Releases</a> chapter for more
-information about what releases are and how they are generated.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_application_resource_file">Application resource file</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>When building your application, Erlang.mk will generate the
-<a href="http://www.erlang.org/doc/man/app.html">application resource file</a>.
-This file is mandatory for all Erlang applications and is
-found in <em>ebin/$(PROJECT).app</em>.</p></div>
-<div class="paragraph"><p><code>PROJECT</code> is a variable defined in your Makefile and taken
-from the name of the directory when Erlang.mk bootstraps
-your project.</p></div>
-<div class="paragraph"><p>Erlang.mk can build the <em>ebin/$(PROJECT).app</em> in two different
-ways: from the configuration found in the Makefile, or from
-the <em>src/$(PROJECT).app.src</em> file.</p></div>
-<div class="sect3">
-<h4 id="_application_configuration">Application configuration</h4>
-<div class="paragraph"><p>Erlang.mk automatically fills the <code>PROJECT</code> variable when
-bootstrapping a new project, but everything else is up to
-you. None of the values are required to build your project,
-although it is recommended to fill everything relevant to
-your situation.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>PROJECT</code>
-</dt>
-<dd>
-<p>
- The name of the OTP application or library.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_DESCRIPTION</code>
-</dt>
-<dd>
-<p>
- Short description of the project.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_VERSION</code>
-</dt>
-<dd>
-<p>
- Current version of the project.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_MOD</code>
-</dt>
-<dd>
-<p>
- The application callback module.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_REGISTERED</code>
-</dt>
-<dd>
-<p>
- List of the names of all registered processes.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_ENV</code>
-</dt>
-<dd>
-<p>
- Configuration parameters used by the application.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_APP_EXTRA_KEYS</code>
-</dt>
-<dd>
-<p>
- Other keys you want to add to the application <code>.app</code> file.
- The variable content is written as-is to the <code>.app</code> file,
- so be sure to format valid Erlang terms. For example:
- <code>PROJECT_APP_EXTRA_KEYS = {maxT, 10000}, {start_phases, [...]}</code>.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>LOCAL_DEPS</code>
-</dt>
-<dd>
-<p>
- List of Erlang/OTP applications this project depends on,
- excluding <code>erts</code>, <code>kernel</code> and <code>stdlib</code>, or list of
- dependencies local to this repository (in <code>APPS_DIR</code>).
-</p>
-</dd>
-<dt class="hdlist1">
-<code>DEPS</code>
-</dt>
-<dd>
-<p>
- List of applications this project depends on that need
- to be fetched by Erlang.mk.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>There&#8217;s no need for quotes or anything. The relevant part of
-the Cowboy Makefile follows, if you need an example:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Any space before and after the value is dropped.</p></div>
-<div class="paragraph"><p><a href="../deps">Dependencies</a> are covered in details in
-the next chapter.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_legacy_method">Legacy method</h4>
-<div class="paragraph"><p>The <em>src/$(PROJECT).app.src</em> file is a legacy method of
-building Erlang applications. It was introduced by the original
-<code>rebar</code> build tool, of which Erlang.mk owes a great deal as it
-is its main inspiration.</p></div>
-<div class="paragraph"><p>The <em>.app.src</em> file serves as a template to generate the <em>.app</em>
-file. Erlang.mk will take it, fill in the <code>modules</code> value
-dynamically, and save the result in <em>ebin/$(PROJECT).app</em>.</p></div>
-<div class="paragraph"><p>When using this method, Erlang.mk cannot fill the <code>applications</code>
-key from dependencies automatically, which means you need to
-add them to Erlang.mk and to the <em>.app.src</em> at the same time,
-duplicating the work.</p></div>
-<div class="paragraph"><p>If you really can&#8217;t live without the legacy method, for one
-reason or another, worry not; Erlang.mk will support it. And
-if you need to create a new project that uses this method, you
-just have to say so when bootstrapping:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap-lib <span style="color: #009900">LEGACY</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_automatic_application_resource_file_values">Automatic application resource file values</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>When building the application resource file, Erlang.mk may
-automatically add an <code>id</code> key with information about the
-Git commit (if using Git), or an empty string otherwise.
-It will only do this under specific conditions:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-The application was built as a dependency of another, or
-</p>
-</li>
-<li>
-<p>
-The legacy method was used, and the <em>.app.src</em> file contained <code>{id, "git"}</code>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>This value is most useful when you need to help your users,
-as it allows you to know which version they run exactly by
-asking them to look in the file, or by running a simple
-command on their production server:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #993399">1</span><span style="color: #990000">&gt;</span> <span style="font-weight: bold"><span style="color: #000000">application:get_all_key</span></span>(<span style="color: #FF6600">cowboy</span>)<span style="color: #990000">.</span>
-{<span style="color: #FF6600">ok</span>,[{<span style="color: #FF6600">description</span>,<span style="color: #FF0000">"Small, fast, modular HTTP server."</span>},
- {<span style="color: #FF6600">id</span>,<span style="color: #FF0000">"2.0.0-pre.2-25-g0ffde50-dirty"</span>},</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_file_formats">File formats</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk supports a variety of different source file formats.
-The following formats are supported natively:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Extension </th>
-<th align="center" valign="top"> Location </th>
-<th align="center" valign="top"> Description </th>
-<th align="center" valign="top"> Output</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">.erl</p></td>
-<td align="center" valign="top"><p class="table">src/</p></td>
-<td align="center" valign="top"><p class="table">Erlang source</p></td>
-<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.core</p></td>
-<td align="center" valign="top"><p class="table">src/</p></td>
-<td align="center" valign="top"><p class="table">Core Erlang source</p></td>
-<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.xrl</p></td>
-<td align="center" valign="top"><p class="table">src/</p></td>
-<td align="center" valign="top"><p class="table">Leex source</p></td>
-<td align="center" valign="top"><p class="table">src/*.erl</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.yrl</p></td>
-<td align="center" valign="top"><p class="table">src/</p></td>
-<td align="center" valign="top"><p class="table">Yecc source</p></td>
-<td align="center" valign="top"><p class="table">src/*.erl</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.asn1</p></td>
-<td align="center" valign="top"><p class="table">asn1/</p></td>
-<td align="center" valign="top"><p class="table">ASN.1 files</p></td>
-<td align="center" valign="top"><p class="table">include/<strong>.hrl include/</strong>.asn1db src/*.erl</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.mib</p></td>
-<td align="center" valign="top"><p class="table">mibs/</p></td>
-<td align="center" valign="top"><p class="table">SNMP MIB files</p></td>
-<td align="center" valign="top"><p class="table">include/<strong>.hrl priv/mibs/</strong>.bin</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="paragraph"><p>Files are always searched recursively.</p></div>
-<div class="paragraph"><p>The build is ordered, so that files that generate Erlang source
-files are run before, and the resulting Erlang source files are
-then built normally.</p></div>
-<div class="paragraph"><p>In addition, Erlang.mk keeps track of header files (<code>.hrl</code>)
-as described at the end of this chapter. It can also compile
-C code, as described in the <a href="../ports">NIFs and port drivers</a>
-chapter.</p></div>
-<div class="paragraph"><p>Erlang.mk also comes with plugins for the following formats:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Extension </th>
-<th align="center" valign="top"> Location </th>
-<th align="center" valign="top"> Description </th>
-<th align="center" valign="top"> Output</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">.dtl</p></td>
-<td align="center" valign="top"><p class="table">templates/</p></td>
-<td align="center" valign="top"><p class="table">Django templates</p></td>
-<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.proto</p></td>
-<td align="center" valign="top"><p class="table">src/</p></td>
-<td align="center" valign="top"><p class="table">Protocol buffers</p></td>
-<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_compilation_options">Compilation options</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk provides a few variables that you can use to customize
-the build process and the resulting files.</p></div>
-<div class="sect3">
-<h4 id="_erlc_opts">ERLC_OPTS</h4>
-<div class="paragraph"><p><code>ERLC_OPTS</code> can be used to pass some options to <code>erlc</code>, the Erlang
-compiler. Erlang.mk does not restrict any option. Please refer to
-the <a href="http://www.erlang.org/doc/man/erlc.html">erlc Manual</a> for the
-full list.</p></div>
-<div class="paragraph"><p>By default, Erlang.mk will set the following options:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>In other words: warnings as errors, debug info (recommended) and
-enable warnings for exported variables, shadow variables and
-obsolete guard functions.</p></div>
-<div class="paragraph"><p>You can redefine this variable in your Makefile to change it
-completely, either before or after including Erlang.mk:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>You can also filter out some options from the defaults Erlang.mk
-sets, by defining ERLC_OPTS after including Erlang.mk using the
-<code>:=</code> operator.</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-<div class="sect3">
-<h4 id="_erlc_asn1_opts">ERLC_ASN1_OPTS</h4>
-<div class="paragraph"><p><code>ERLC_ASN1_OPTS</code> can be used to pass compiler options when compiling
-ASN.1 files. Please refer to the
-<a href="http://erlang.org/doc/man/asn1ct.html">asn1ct manual</a> for the full list.</p></div>
-<div class="paragraph"><p>By default, Erlang.mk will leave this empty.</p></div>
-<div class="paragraph"><p>You can redefine this variable in your Makefile.
-Please see the <code>ERLC_OPTS</code> section for instructions.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_erlc_exclude">ERLC_EXCLUDE</h4>
-<div class="paragraph"><p><code>ERLC_EXCLUDE</code> can be used to exclude some modules from the
-compilation. It&#8217;s there for handling special cases, you should
-not normally need it.</p></div>
-<div class="paragraph"><p>To exclude a module, simply list it in the variable, either
-before or after including Erlang.mk:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_cold_and_hot_builds">Cold and hot builds</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The first time you run <code>make</code>, Erlang.mk will build everything.</p></div>
-<div class="paragraph"><p>The second time you run <code>make</code>, and all subsequent times, Erlang.mk
-will only rebuild what changed. Erlang.mk has been optimized for
-this use case, as it is the most common during development.</p></div>
-<div class="paragraph"><p>Erlang.mk figures out what changed by using the dependency tracking
-feature of Make. Make automatically rebuilds a target if one of its
-dependency has changed (for example if a header file has changed,
-all the source files that include it will be rebuilt), and Erlang.mk
-leverages this feature to cut down on rebuild times.</p></div>
-<div class="paragraph"><p>Note that this applies only to building; some other features of
-Erlang.mk will run every time they are called regardless of files
-changed.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependency_tracking">Dependency tracking</h2>
-<div class="sectionbody">
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">This section is about the dependency tracking between files
-inside your project, not application dependencies.</td>
-</tr></table>
-</div>
-<div class="paragraph"><p>Erlang.mk keeps track of the dependencies between the different
-files in your project. This information is kept in the <em>$(PROJECT).d</em>
-file in your directory. It is generated if missing, and will be
-generated again after every file change, by default.</p></div>
-<div class="paragraph"><p>Dependency tracking is what allows Erlang.mk to know when to
-rebuild Erlang files when header files, behaviors or parse
-transforms have changed. Erlang.mk also automatically keeps
-track of which files should be compiled first, for example
-when you have behaviors used by other modules in your project.</p></div>
-<div class="paragraph"><p>If your project is stable, you may want to disable generating
-the dependency tracking file every time you compile. You can
-do this by adding the following line to your <em>Makefile</em>:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>As you can see, the snippet above uses <code>?=</code> instead of a
-simple equal sign. This is to allow you to temporarily override
-this value when you do make substantial changes to your project
-(including a new header file, new module with dependencies, etc.)
-and want to rebuild the dependency tracking file. You&#8217;ll be
-able to use the following command:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ <span style="color: #009900">NO_MAKEDEP</span><span style="color: #990000">=</span> make</tt></pre></div></div>
-<div class="paragraph"><p>Otherwise, <code>make clean app</code> will of course force the
-recompilation of your project.</p></div>
-<div class="paragraph"><p>Erlang.mk can also keep track of the source files generated
-by other means, for example if you generate code from a data
-file in your repository.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_generating_erlang_source">Generating Erlang source</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk provides hooks at different stages of the build process.
-When your goal is to generate Erlang source files, you can
-add your own rules before or after the dependency tracking
-file is generated. To do this, you would add your hook before
-or after including the <em>erlang.mk</em> file.</p></div>
-<div class="paragraph"><p>The easiest way is after:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>In this case we use <code>$(gen_verbose)</code> to hide the details of
-the build by default. Erlang.mk will simply say what file
-is it currently generating.</p></div>
-<div class="paragraph"><p>When using an external script to generate the Erlang source
-file, it is recommended to depend on that script, so that
-the source file gets generated again when the script gets
-modified.</p></div>
-<div class="paragraph"><p>If for whatever reason you prefer to hook before including
-Erlang.mk, don&#8217;t forget to set the <code>.DEFAULT_GOAL</code> variable,
-otherwise nothing will get built:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_cleaning">Cleaning</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Building typically involves creating a lot of new files. Some
-are reused in rebuilds, some are simply replaced. All can be
-removed safely.</p></div>
-<div class="paragraph"><p>Erlang.mk provides two commands to remove them: <code>clean</code> and
-<code>distclean</code>. <code>clean</code> removes all the intermediate files that
-were created as a result of building, including the BEAM files,
-the dependency tracking file and the generated documentation.
-<code>distclean</code> removes these and more, including the downloaded
-dependencies, Dialyzer&#8217;s PLT file and the generated release,
-putting your directory back to the state it was before you
-started working on it.</p></div>
-<div class="paragraph"><p>To clean:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ make clean</tt></pre></div></div>
-<div class="paragraph"><p>Or distclean:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ make distclean</tt></pre></div></div>
-<div class="paragraph"><p>That is the question.</p></div>
-<div class="paragraph"><p>Note that Erlang.mk will automatically clean some files as
-part of other targets, but it will never run <code>distclean</code> if
-you don&#8217;t explicitly use it.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk can do a lot of things, but it is, first and
+foremost, a build tool. In this chapter we will cover
+the basics of building a project with Erlang.mk.</p></div>
+<div class="paragraph"><p>For most of this chapter, we will assume that you are
+using a project <a href="../getting_started">generated by Erlang.mk</a>.</p></div>
+<div class="sect1">
+<h2 id="_how_to_build">How to build</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>To build a project, all you have to do is type <code>make</code>:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>$ make</tt></pre></div></div>
+<div class="paragraph"><p>It will work regardless of your project: OTP applications,
+library applications, NIFs, port drivers or even releases.
+Erlang.mk also automatically downloads and compiles the
+dependencies for your project.</p></div>
+<div class="paragraph"><p>All this is possible thanks to a combination of configuration
+and conventions. Most of the conventions come from Erlang/OTP
+itself so any seasoned Erlang developers should feel right at
+home.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_what_to_build">What to build</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Erlang.mk gives you control over three steps of the build
+process, allowing you to do a partial build if needed.</p></div>
+<div class="paragraph"><p>A build has three phases: first any dependency is fetched
+and built, then the project itself is built and finally a
+release may be generated when applicable. A release is only
+generated for projects specifically configured to do so.</p></div>
+<div class="paragraph"><p>Erlang.mk handles those three phases automatically when you
+type <code>make</code>. But sometimes you just want to repeat one or
+two of them.</p></div>
+<div class="paragraph"><p>The commands detailed in this section are most useful after
+you have a successful build as they allow you to quickly
+redo a step instead of going through everything. This is
+especially useful for large projects or projects that end
+up generating releases.</p></div>
+<div class="sect3">
+<h4 id="_application">Application</h4>
+<div class="paragraph"><p>You can build your application and dependencies without
+generating a release by running the following command:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>$ make app</tt></pre></div></div>
+<div class="paragraph"><p>To build your application without touching dependencies
+at all, you can use the <code>SKIP_DEPS</code> variable:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>$ make app <span style="color: #009900">SKIP_DEPS</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div>
+<div class="paragraph"><p>This command is very useful if you have a lot of dependencies
+and develop on a machine with slow file access, like the
+Raspberry Pi and many other embedded devices.</p></div>
+<div class="paragraph"><p>Note that this command may fail if a required dependency
+is missing.</p></div>
+</div>
+<div class="sect3">
+<h4 id="_dependencies">Dependencies</h4>
+<div class="paragraph"><p>You can build all dependencies, and nothing else, by
+running the following command:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>$ make deps</tt></pre></div></div>
+<div class="paragraph"><p>This will fetch and compile all dependencies and their
+dependencies, recursively.</p></div>
+<div class="paragraph"><p><a href="../deps">Packages and dependencies</a> are covered
+in the next chapter.</p></div>
+</div>
+<div class="sect3">
+<h4 id="_release">Release</h4>
+<div class="paragraph"><p>It is not possible to build the release without at least
+building the application itself, unless of course if there&#8217;s
+no application to begin with.</p></div>
+<div class="paragraph"><p>To generate the release, <code>make</code> will generally suffice with
+a normal Erlang.mk. A separate target is however available,
+and will take care of building the release, after building
+the application and all dependencies:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>$ make rel</tt></pre></div></div>
+<div class="paragraph"><p>Consult the <a href="../relx">Releases</a> chapter for more
+information about what releases are and how they are generated.</p></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_application_resource_file">Application resource file</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>When building your application, Erlang.mk will generate the
+<a href="http://www.erlang.org/doc/man/app.html">application resource file</a>.
+This file is mandatory for all Erlang applications and is
+found in <em>ebin/$(PROJECT).app</em>.</p></div>
+<div class="paragraph"><p><code>PROJECT</code> is a variable defined in your Makefile and taken
+from the name of the directory when Erlang.mk bootstraps
+your project.</p></div>
+<div class="paragraph"><p>Erlang.mk can build the <em>ebin/$(PROJECT).app</em> in two different
+ways: from the configuration found in the Makefile, or from
+the <em>src/$(PROJECT).app.src</em> file.</p></div>
+<div class="sect3">
+<h4 id="_application_configuration">Application configuration</h4>
+<div class="paragraph"><p>Erlang.mk automatically fills the <code>PROJECT</code> variable when
+bootstrapping a new project, but everything else is up to
+you. None of the values are required to build your project,
+although it is recommended to fill everything relevant to
+your situation.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>PROJECT</code>
+</dt>
+<dd>
+<p>
+ The name of the OTP application or library.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>PROJECT_DESCRIPTION</code>
+</dt>
+<dd>
+<p>
+ Short description of the project.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>PROJECT_VERSION</code>
+</dt>
+<dd>
+<p>
+ Current version of the project.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>PROJECT_MOD</code>
+</dt>
+<dd>
+<p>
+ The application callback module.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>PROJECT_REGISTERED</code>
+</dt>
+<dd>
+<p>
+ List of the names of all registered processes.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>PROJECT_ENV</code>
+</dt>
+<dd>
+<p>
+ Configuration parameters used by the application.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>PROJECT_APP_EXTRA_KEYS</code>
+</dt>
+<dd>
+<p>
+ Other keys you want to add to the application <code>.app</code> file.
+ The variable content is written as-is to the <code>.app</code> file,
+ so be sure to format valid Erlang terms. For example:
+ <code>PROJECT_APP_EXTRA_KEYS = {maxT, 10000}, {start_phases, [...]}</code>.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>LOCAL_DEPS</code>
+</dt>
+<dd>
+<p>
+ List of Erlang/OTP applications this project depends on,
+ excluding <code>erts</code>, <code>kernel</code> and <code>stdlib</code>, or list of
+ dependencies local to this repository (in <code>APPS_DIR</code>).
+</p>
+</dd>
+<dt class="hdlist1">
+<code>DEPS</code>
+</dt>
+<dd>
+<p>
+ List of applications this project depends on that need
+ to be fetched by Erlang.mk.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>There&#8217;s no need for quotes or anything. The relevant part of
+the Cowboy Makefile follows, if you need an example:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">PROJECT =</span> cowboy
+<span style="color: #009900">PROJECT_DESCRIPTION =</span> Small<span style="color: #990000">,</span> fast<span style="color: #990000">,</span> modular HTTP server<span style="color: #990000">.</span>
+<span style="color: #009900">PROJECT_VERSION =</span> 2.0.0-pre.2
+<span style="color: #009900">PROJECT_REGISTERED =</span> cowboy_clock
+
+<span style="color: #009900">LOCAL_DEPS =</span> crypto
+<span style="color: #009900">DEPS =</span> cowlib ranch</tt></pre></div></div>
+<div class="paragraph"><p>Any space before and after the value is dropped.</p></div>
+<div class="paragraph"><p><a href="../deps">Dependencies</a> are covered in details in
+the next chapter.</p></div>
+</div>
+<div class="sect3">
+<h4 id="_legacy_method">Legacy method</h4>
+<div class="paragraph"><p>The <em>src/$(PROJECT).app.src</em> file is a legacy method of
+building Erlang applications. It was introduced by the original
+<code>rebar</code> build tool, of which Erlang.mk owes a great deal as it
+is its main inspiration.</p></div>
+<div class="paragraph"><p>The <em>.app.src</em> file serves as a template to generate the <em>.app</em>
+file. Erlang.mk will take it, fill in the <code>modules</code> value
+dynamically, and save the result in <em>ebin/$(PROJECT).app</em>.</p></div>
+<div class="paragraph"><p>When using this method, Erlang.mk cannot fill the <code>applications</code>
+key from dependencies automatically, which means you need to
+add them to Erlang.mk and to the <em>.app.src</em> at the same time,
+duplicating the work.</p></div>
+<div class="paragraph"><p>If you really can&#8217;t live without the legacy method, for one
+reason or another, worry not; Erlang.mk will support it. And
+if you need to create a new project that uses this method, you
+just have to say so when bootstrapping:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap-lib <span style="color: #009900">LEGACY</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_automatic_application_resource_file_values">Automatic application resource file values</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>When building the application resource file, Erlang.mk may
+automatically add an <code>id</code> key with information about the
+Git commit (if using Git), or an empty string otherwise.
+It will only do this under specific conditions:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+The application was built as a dependency of another, or
+</p>
+</li>
+<li>
+<p>
+The legacy method was used, and the <em>.app.src</em> file contained <code>{id, "git"}</code>
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>This value is most useful when you need to help your users,
+as it allows you to know which version they run exactly by
+asking them to look in the file, or by running a simple
+command on their production server:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #993399">1</span><span style="color: #990000">&gt;</span> <span style="font-weight: bold"><span style="color: #000000">application:get_all_key</span></span>(<span style="color: #FF6600">cowboy</span>)<span style="color: #990000">.</span>
+{<span style="color: #FF6600">ok</span>,[{<span style="color: #FF6600">description</span>,<span style="color: #FF0000">"Small, fast, modular HTTP server."</span>},
+ {<span style="color: #FF6600">id</span>,<span style="color: #FF0000">"2.0.0-pre.2-25-g0ffde50-dirty"</span>},</tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_file_formats">File formats</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Erlang.mk supports a variety of different source file formats.
+The following formats are supported natively:</p></div>
+<div class="tableblock">
+<table rules="all"
+width="100%"
+frame="border"
+cellspacing="0" cellpadding="4">
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<thead>
+<tr>
+<th align="left" valign="top"> Extension </th>
+<th align="center" valign="top"> Location </th>
+<th align="center" valign="top"> Description </th>
+<th align="center" valign="top"> Output</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="left" valign="top"><p class="table">.erl</p></td>
+<td align="center" valign="top"><p class="table">src/</p></td>
+<td align="center" valign="top"><p class="table">Erlang source</p></td>
+<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">.core</p></td>
+<td align="center" valign="top"><p class="table">src/</p></td>
+<td align="center" valign="top"><p class="table">Core Erlang source</p></td>
+<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">.xrl</p></td>
+<td align="center" valign="top"><p class="table">src/</p></td>
+<td align="center" valign="top"><p class="table">Leex source</p></td>
+<td align="center" valign="top"><p class="table">src/*.erl</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">.yrl</p></td>
+<td align="center" valign="top"><p class="table">src/</p></td>
+<td align="center" valign="top"><p class="table">Yecc source</p></td>
+<td align="center" valign="top"><p class="table">src/*.erl</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">.asn1</p></td>
+<td align="center" valign="top"><p class="table">asn1/</p></td>
+<td align="center" valign="top"><p class="table">ASN.1 files</p></td>
+<td align="center" valign="top"><p class="table">include/<strong>.hrl include/</strong>.asn1db src/*.erl</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">.mib</p></td>
+<td align="center" valign="top"><p class="table">mibs/</p></td>
+<td align="center" valign="top"><p class="table">SNMP MIB files</p></td>
+<td align="center" valign="top"><p class="table">include/<strong>.hrl priv/mibs/</strong>.bin</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="paragraph"><p>Files are always searched recursively.</p></div>
+<div class="paragraph"><p>The build is ordered, so that files that generate Erlang source
+files are run before, and the resulting Erlang source files are
+then built normally.</p></div>
+<div class="paragraph"><p>In addition, Erlang.mk keeps track of header files (<code>.hrl</code>)
+as described at the end of this chapter. It can also compile
+C code, as described in the <a href="../ports">NIFs and port drivers</a>
+chapter.</p></div>
+<div class="paragraph"><p>Erlang.mk also comes with plugins for the following formats:</p></div>
+<div class="tableblock">
+<table rules="all"
+width="100%"
+frame="border"
+cellspacing="0" cellpadding="4">
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<thead>
+<tr>
+<th align="left" valign="top"> Extension </th>
+<th align="center" valign="top"> Location </th>
+<th align="center" valign="top"> Description </th>
+<th align="center" valign="top"> Output</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="left" valign="top"><p class="table">.dtl</p></td>
+<td align="center" valign="top"><p class="table">templates/</p></td>
+<td align="center" valign="top"><p class="table">Django templates</p></td>
+<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">.proto</p></td>
+<td align="center" valign="top"><p class="table">src/</p></td>
+<td align="center" valign="top"><p class="table">Protocol buffers</p></td>
+<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_compilation_options">Compilation options</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Erlang.mk provides a few variables that you can use to customize
+the build process and the resulting files.</p></div>
+<div class="sect3">
+<h4 id="_erlc_opts">ERLC_OPTS</h4>
+<div class="paragraph"><p><code>ERLC_OPTS</code> can be used to pass some options to <code>erlc</code>, the Erlang
+compiler. Erlang.mk does not restrict any option. Please refer to
+the <a href="http://www.erlang.org/doc/man/erlc.html">erlc Manual</a> for the
+full list.</p></div>
+<div class="paragraph"><p>By default, Erlang.mk will set the following options:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">ERLC_OPTS =</span> -Werror <span style="color: #990000">+</span>debug_info <span style="color: #990000">+</span>warn_export_vars <span style="color: #990000">+</span>warn_shadow_vars <span style="color: #990000">+</span>warn_obsolete_guard</tt></pre></div></div>
+<div class="paragraph"><p>In other words: warnings as errors, debug info (recommended) and
+enable warnings for exported variables, shadow variables and
+obsolete guard functions.</p></div>
+<div class="paragraph"><p>You can redefine this variable in your Makefile to change it
+completely, either before or after including Erlang.mk:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">ERLC_OPTS =</span> <span style="color: #990000">+</span>debug_info</tt></pre></div></div>
+<div class="paragraph"><p>You can also filter out some options from the defaults Erlang.mk
+sets, by defining ERLC_OPTS after including Erlang.mk using the
+<code>:=</code> operator.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>include erlang.mk
+
+<span style="color: #990000">ERLC_OPTS :=</span> <span style="color: #009900">$(</span>filter-out -Werror<span style="color: #990000">,</span><span style="color: #009900">$(ERLC_OPTS))</span></tt></pre></div></div>
+</div>
+<div class="sect3">
+<h4 id="_erlc_asn1_opts">ERLC_ASN1_OPTS</h4>
+<div class="paragraph"><p><code>ERLC_ASN1_OPTS</code> can be used to pass compiler options when compiling
+ASN.1 files. Please refer to the
+<a href="http://erlang.org/doc/man/asn1ct.html">asn1ct manual</a> for the full list.</p></div>
+<div class="paragraph"><p>By default, Erlang.mk will leave this empty.</p></div>
+<div class="paragraph"><p>You can redefine this variable in your Makefile.
+Please see the <code>ERLC_OPTS</code> section for instructions.</p></div>
+</div>
+<div class="sect3">
+<h4 id="_erlc_exclude">ERLC_EXCLUDE</h4>
+<div class="paragraph"><p><code>ERLC_EXCLUDE</code> can be used to exclude some modules from the
+compilation. It&#8217;s there for handling special cases, you should
+not normally need it.</p></div>
+<div class="paragraph"><p>To exclude a module, simply list it in the variable, either
+before or after including Erlang.mk:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">ERLC_EXCLUDE =</span> cowboy_http2</tt></pre></div></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_cold_and_hot_builds">Cold and hot builds</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The first time you run <code>make</code>, Erlang.mk will build everything.</p></div>
+<div class="paragraph"><p>The second time you run <code>make</code>, and all subsequent times, Erlang.mk
+will only rebuild what changed. Erlang.mk has been optimized for
+this use case, as it is the most common during development.</p></div>
+<div class="paragraph"><p>Erlang.mk figures out what changed by using the dependency tracking
+feature of Make. Make automatically rebuilds a target if one of its
+dependency has changed (for example if a header file has changed,
+all the source files that include it will be rebuilt), and Erlang.mk
+leverages this feature to cut down on rebuild times.</p></div>
+<div class="paragraph"><p>Note that this applies only to building; some other features of
+Erlang.mk will run every time they are called regardless of files
+changed.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_dependency_tracking">Dependency tracking</h2>
+<div class="sectionbody">
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">This section is about the dependency tracking between files
+inside your project, not application dependencies.</td>
+</tr></table>
+</div>
+<div class="paragraph"><p>Erlang.mk keeps track of the dependencies between the different
+files in your project. This information is kept in the <em>$(PROJECT).d</em>
+file in your directory. It is generated if missing, and will be
+generated again after every file change, by default.</p></div>
+<div class="paragraph"><p>Dependency tracking is what allows Erlang.mk to know when to
+rebuild Erlang files when header files, behaviors or parse
+transforms have changed. Erlang.mk also automatically keeps
+track of which files should be compiled first, for example
+when you have behaviors used by other modules in your project.</p></div>
+<div class="paragraph"><p>If your project is stable, you may want to disable generating
+the dependency tracking file every time you compile. You can
+do this by adding the following line to your <em>Makefile</em>:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>NO_MAKEDEP <span style="color: #990000">?=</span> <span style="color: #993399">1</span></tt></pre></div></div>
+<div class="paragraph"><p>As you can see, the snippet above uses <code>?=</code> instead of a
+simple equal sign. This is to allow you to temporarily override
+this value when you do make substantial changes to your project
+(including a new header file, new module with dependencies, etc.)
+and want to rebuild the dependency tracking file. You&#8217;ll be
+able to use the following command:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>$ <span style="color: #009900">NO_MAKEDEP</span><span style="color: #990000">=</span> make</tt></pre></div></div>
+<div class="paragraph"><p>Otherwise, <code>make clean app</code> will of course force the
+recompilation of your project.</p></div>
+<div class="paragraph"><p>Erlang.mk can also keep track of the source files generated
+by other means, for example if you generate code from a data
+file in your repository.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_generating_erlang_source">Generating Erlang source</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Erlang.mk provides hooks at different stages of the build process.
+When your goal is to generate Erlang source files, you can
+add your own rules before or after the dependency tracking
+file is generated. To do this, you would add your hook before
+or after including the <em>erlang.mk</em> file.</p></div>
+<div class="paragraph"><p>The easiest way is after:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">PROJECT =</span> example
+
+include erlang.mk
+
+<span style="color: #009900">$(PROJECT)</span>.d<span style="color: #990000">::</span> src/generated_mod.erl
+
+src/generated_mod.erl<span style="color: #990000">::</span> gen-mod.sh
+ <span style="color: #009900">$(gen_verbose)</span> <span style="color: #990000">.</span>/gen-mod.sh <span style="color: #009900">$@</span></tt></pre></div></div>
+<div class="paragraph"><p>In this case we use <code>$(gen_verbose)</code> to hide the details of
+the build by default. Erlang.mk will simply say what file
+is it currently generating.</p></div>
+<div class="paragraph"><p>When using an external script to generate the Erlang source
+file, it is recommended to depend on that script, so that
+the source file gets generated again when the script gets
+modified.</p></div>
+<div class="paragraph"><p>If for whatever reason you prefer to hook before including
+Erlang.mk, don&#8217;t forget to set the <code>.DEFAULT_GOAL</code> variable,
+otherwise nothing will get built:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">PROJECT =</span> example
+
+.DEFAULT_GOAL <span style="color: #990000">=</span> all
+
+<span style="color: #009900">$(PROJECT)</span>.d<span style="color: #990000">::</span> src/generated_mod.erl
+
+include erlang.mk
+
+src/generated_mod.erl<span style="color: #990000">::</span> gen-mod.sh
+ <span style="color: #009900">$(gen_verbose)</span> <span style="color: #990000">.</span>/gen-mod.sh <span style="color: #009900">$@</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_cleaning">Cleaning</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Building typically involves creating a lot of new files. Some
+are reused in rebuilds, some are simply replaced. All can be
+removed safely.</p></div>
+<div class="paragraph"><p>Erlang.mk provides two commands to remove them: <code>clean</code> and
+<code>distclean</code>. <code>clean</code> removes all the intermediate files that
+were created as a result of building, including the BEAM files,
+the dependency tracking file and the generated documentation.
+<code>distclean</code> removes these and more, including the downloaded
+dependencies, Dialyzer&#8217;s PLT file and the generated release,
+putting your directory back to the state it was before you
+started working on it.</p></div>
+<div class="paragraph"><p>To clean:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>$ make clean</tt></pre></div></div>
+<div class="paragraph"><p>Or distclean:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>$ make distclean</tt></pre></div></div>
+<div class="paragraph"><p>That is the question.</p></div>
+<div class="paragraph"><p>Note that Erlang.mk will automatically clean some files as
+part of other targets, but it will never run <code>distclean</code> if
+you don&#8217;t explicitly use it.</p></div>
+</div>
+</div>
+
+
+
<nav style="margin:1em 0">
generated by cgit v1.2.3 (git 2.25.1) at 2024-09-25 13:00:12 +0000