diff options
Diffstat (limited to 'docs/en/erlang.mk/1')
32 files changed, 4461 insertions, 3565 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’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’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’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">></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’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’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’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’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’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’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’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’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">></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’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’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’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’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’t explicitly use it.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/asciidoc/index.html b/docs/en/erlang.mk/1/guide/asciidoc/index.html index f188ff6f..e0a10d20 100644 --- a/docs/en/erlang.mk/1/guide/asciidoc/index.html +++ b/docs/en/erlang.mk/1/guide/asciidoc/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: AsciiDoc documentation</title> @@ -67,106 +67,109 @@ <h1 class="lined-header"><span>AsciiDoc documentation</span></h1> -<div class="paragraph"><p>Erlang.mk provides rules for generating documentation from
-AsciiDoc files. It can automatically build a user guide PDF,
-chunked HTML documentation and Unix manual pages.</p></div>
-<div class="sect1">
-<h2 id="_requirements">Requirements</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It is necessary to have <a href="http://asciidoc.org/">AsciiDoc</a>,
-<a href="http://xmlsoft.org/XSLT/xsltproc2.html">xsltproc</a> and
-<a href="http://dblatex.sourceforge.net/">dblatex</a> installed on your
-system for Erlang.mk to generate documentation from AsciiDoc sources.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_writing_asciidoc_documentation">Writing AsciiDoc documentation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="http://asciidoc.org/">AsciiDoc</a> is a text document format for
-writing notes, documentation, articles, books, ebooks, slideshows,
-web pages, man pages and blogs. AsciiDoc files can be translated
-to many formats including HTML, PDF, EPUB, man page.</p></div>
-<div class="paragraph"><p>The <a href="http://asciidoc.org/userguide.html">AsciiDoc user guide</a>
-describes the AsciiDoc syntax.</p></div>
-<div class="paragraph"><p>The <a href="https://github.com/ninenines/erlang.mk/tree/master/doc/src/guide">Erlang.mk user guide</a>
-is written in AsciiDoc and can be used as an example. The entry
-file is <a href="https://github.com/ninenines/erlang.mk/blob/master/doc/src/guide/book.asciidoc">book.asciidoc</a>.</p></div>
-<div class="paragraph"><p>Erlang.mk expects you to put your documentation in a specific
-location. This is <em>doc/src/guide/</em> for the user guide, and
-<em>doc/src/manual/</em> for the function reference. In the case of
-the user guide, the entry point is always <em>doc/src/guide/book.asciidoc</em>.</p></div>
-<div class="paragraph"><p>For manual pages, it is good practice to use section 3 for
-modules, and section 7 for the application itself.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All of the AsciiDoc related configuration can be done directly
-inside the files themselves.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To build all documentation:</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 docs</tt></pre></div></div>
-<div class="paragraph"><p>To build only the AsciiDoc documentation:</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 asciidoc</tt></pre></div></div>
-<div class="paragraph"><p>To build only the user guide:</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 asciidoc-guide</tt></pre></div></div>
-<div class="paragraph"><p>To build only the manual:</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 asciidoc-manual</tt></pre></div></div>
-<div class="paragraph"><p>To install man pages on Unix:</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 install-docs</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk allows customizing the installation path and sections
-of the man pages to be installed. The <code>MAN_INSTALL_PATH</code> variable
-defines where man pages will be installed. It defaults to
-<em>/usr/local/share/man</em>. The <code>MAN_SECTIONS</code> variable defines
-which manual sections are to be installed. It defaults to <code>3 7</code>.</p></div>
-<div class="paragraph"><p>To install man pages to a custom location:</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 install-docs <span style="color: #009900">MAN_INSTALL_PATH</span><span style="color: #990000">=</span>/opt/share/man</tt></pre></div></div>
-<div class="paragraph"><p>Note that you may need to run the install commands using
-<code>sudo</code> or equivalent if the location is not writeable by
-your user.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk provides rules for generating documentation from +AsciiDoc files. It can automatically build a user guide PDF, +chunked HTML documentation and Unix manual pages.</p></div> +<div class="sect1"> +<h2 id="_requirements">Requirements</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is necessary to have <a href="http://asciidoc.org/">AsciiDoc</a>, +<a href="http://xmlsoft.org/XSLT/xsltproc2.html">xsltproc</a> and +<a href="http://dblatex.sourceforge.net/">dblatex</a> installed on your +system for Erlang.mk to generate documentation from AsciiDoc sources.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_writing_asciidoc_documentation">Writing AsciiDoc documentation</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="http://asciidoc.org/">AsciiDoc</a> is a text document format for +writing notes, documentation, articles, books, ebooks, slideshows, +web pages, man pages and blogs. AsciiDoc files can be translated +to many formats including HTML, PDF, EPUB, man page.</p></div> +<div class="paragraph"><p>The <a href="http://asciidoc.org/userguide.html">AsciiDoc user guide</a> +describes the AsciiDoc syntax.</p></div> +<div class="paragraph"><p>The <a href="https://github.com/ninenines/erlang.mk/tree/master/doc/src/guide">Erlang.mk user guide</a> +is written in AsciiDoc and can be used as an example. The entry +file is <a href="https://github.com/ninenines/erlang.mk/blob/master/doc/src/guide/book.asciidoc">book.asciidoc</a>.</p></div> +<div class="paragraph"><p>Erlang.mk expects you to put your documentation in a specific +location. This is <em>doc/src/guide/</em> for the user guide, and +<em>doc/src/manual/</em> for the function reference. In the case of +the user guide, the entry point is always <em>doc/src/guide/book.asciidoc</em>.</p></div> +<div class="paragraph"><p>For manual pages, it is good practice to use section 3 for +modules, and section 7 for the application itself.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All of the AsciiDoc related configuration can be done directly +inside the files themselves.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To build all documentation:</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 docs</tt></pre></div></div> +<div class="paragraph"><p>To build only the AsciiDoc documentation:</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 asciidoc</tt></pre></div></div> +<div class="paragraph"><p>To build only the user guide:</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 asciidoc-guide</tt></pre></div></div> +<div class="paragraph"><p>To build only the manual:</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 asciidoc-manual</tt></pre></div></div> +<div class="paragraph"><p>To install man pages on Unix:</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 install-docs</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk allows customizing the installation path and sections +of the man pages to be installed. The <code>MAN_INSTALL_PATH</code> variable +defines where man pages will be installed. It defaults to +<em>/usr/local/share/man</em>. The <code>MAN_SECTIONS</code> variable defines +which manual sections are to be installed. It defaults to <code>3 7</code>.</p></div> +<div class="paragraph"><p>To install man pages to a custom location:</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 install-docs <span style="color: #009900">MAN_INSTALL_PATH</span><span style="color: #990000">=</span>/opt/share/man</tt></pre></div></div> +<div class="paragraph"><p>Note that you may need to run the install commands using +<code>sudo</code> or equivalent if the location is not writeable by +your user.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/ci.asciidoc b/docs/en/erlang.mk/1/guide/ci.asciidoc index 24cfc053..2b69e282 100644 --- a/docs/en/erlang.mk/1/guide/ci.asciidoc +++ b/docs/en/erlang.mk/1/guide/ci.asciidoc @@ -1,6 +1,66 @@ [[ci]] == Continuous integration -// @todo Write it. +Erlang.mk comes with some support for continuous integration, +aimed at open source projects that need to support more than +one specific Erlang/OTP release. (If you target one specific +release, check the xref:otp_version_pinning[OTP version pinning] +section of the xref:kerl[OTP version management] chapter.) -Placeholder 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. + +At the time of writing, this is how you would test against all +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. + +=== Running tests across all configured versions + +The recommended way to run the `ci` target is with the option +`-k`. It will ensure that tests are run for all configured +Erlang/OTP versions, even if there are errors: + +[source,bash] +$ make ci -k + +=== Extending the CI targets + +The `ci` target can be extended. For example to run Dialyzer +at the end of CI: + +[source,make] +---- +ci:: dialyze +---- + +Additional setup can be done by extending the `ci-setup` +target. This target is ran before testing each individual +Erlang/OTP version. + +For example, to ensure dependencies are re-fetched/built +before testing individual Erlang/OTP releases: + +[source,make] +---- +ci-setup:: distclean +---- + +Similarly, the `ci-extra` target can be extended to run +extra commands after an Erlang/OTP version has been tested. diff --git a/docs/en/erlang.mk/1/guide/ci/index.html b/docs/en/erlang.mk/1/guide/ci/index.html index e4db9a8a..e73333f6 100644 --- a/docs/en/erlang.mk/1/guide/ci/index.html +++ b/docs/en/erlang.mk/1/guide/ci/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: Continuous integration</title> @@ -67,13 +67,89 @@ <h1 class="lined-header"><span>Continuous integration</span></h1> -<div class="paragraph"><p>Placeholder chapter.</p></div>
+<div class="paragraph"><p>Erlang.mk comes with some support for continuous integration, +aimed at open source projects that need to support more than +one specific Erlang/OTP release. (If you target one specific +release, check the <a href="../otp_version_pinning">OTP version pinning</a> +section of the <a href="../kerl">OTP version management</a> chapter.)</p></div> +<div class="sect1"> +<h2 id="_configuring_erlang_otp_versions_to_test">Configuring Erlang/OTP versions to test</h2> +<div class="sectionbody"> +<div class="paragraph"><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></div> +<div class="paragraph"><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></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">CI_OTP =</span> OTP-19.0.7 OTP-19.1.6 OTP-19.2.3 OTP-19.3.6.2 OTP-20.0.4</tt></pre></div></div> +<div class="paragraph"><p>If you want to test against HiPE and ErLLVM but only with the +latest version of Erlang/OTP, the following could work:</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">CI_HIPE =</span> <span style="color: #009900">$(</span>lastword <span style="color: #009900">$(CI_OTP))</span> +<span style="color: #009900">CI_ERLLVM =</span> <span style="color: #009900">$(CI_HIPE)</span></tt></pre></div></div> +<div class="paragraph"><p>Consult the <a href="../kerl">OTP version management</a> chapter for more +information about Erlang/OTP versions and customization of the +Erlang/OTP builds.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_running_tests_across_all_configured_versions">Running tests across all configured versions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The recommended way to run the <code>ci</code> target is with the option +<code>-k</code>. It will ensure that tests are run for all configured +Erlang/OTP versions, even if there are errors:</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 ci -k</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_extending_the_ci_targets">Extending the CI targets</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ci</code> target can be extended. For example to run Dialyzer +at the end of CI:</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: #990000">ci::</span> dialyze</tt></pre></div></div> +<div class="paragraph"><p>Additional setup can be done by extending the <code>ci-setup</code> +target. This target is ran before testing each individual +Erlang/OTP version.</p></div> +<div class="paragraph"><p>For example, to ensure dependencies are re-fetched/built +before testing individual Erlang/OTP releases:</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: #990000">ci-setup::</span> distclean</tt></pre></div></div> +<div class="paragraph"><p>Similarly, the <code>ci-extra</code> target can be extended to run +extra commands after an Erlang/OTP version has been tested.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/common_test/index.html b/docs/en/erlang.mk/1/guide/common_test/index.html index 74e9c912..7933d41a 100644 --- a/docs/en/erlang.mk/1/guide/common_test/index.html +++ b/docs/en/erlang.mk/1/guide/common_test/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: Common Test</title> @@ -67,121 +67,136 @@ <h1 class="lined-header"><span>Common Test</span></h1> -<div class="paragraph"><p>Common Test is Erlang’s functional testing framework.
-Erlang.mk automates the discovery and running of Common
-Test suites.</p></div>
-<div class="sect1">
-<h2 id="_writing_tests">Writing tests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/common_test/write_test_chapter.html">Common Test user guide</a>
-is the best place to learn how to write tests. Erlang.mk
-requires that file names for test suites end with <em>_SUITE.erl</em>
-and that the files be located in the <em>$(TEST_DIR)</em> directory.
-This defaults to <em>test/</em>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>CT_OPTS</code> variable allows you to set extra Common Test
-options. Options are documented in the
-<a href="http://www.erlang.org/doc/apps/common_test/run_test_chapter.html">Common Test user guide</a>.
-You can use it to set Common Test hooks, for example:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The <code>CT_SUITES</code> variable can be used to override what
-Common Test suites Erlang.mk will be aware of. It does
-not normally need to be set as Erlang.mk will find the
-test suites automatically.</p></div>
-<div class="paragraph"><p>The name of the suite is the part before <code>_SUITE.erl</code>.
-If the file is named <em>http_SUITE.erl</em>, the test suite
-is <code>http</code>:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The <code>CT_LOGS_DIR</code> variable can be used to set where HTML
-log files are to be written. This defaults to <em>logs/</em>.</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To run all tests (including Common Test):</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 tests</tt></pre></div></div>
-<div class="paragraph"><p>To run all tests and static checks (including Common Test):</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 check</tt></pre></div></div>
-<div class="paragraph"><p>You can also run Common Test separately:</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 ct</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk will create targets for all test suites it finds.
-If you have a file named <em>test/http_SUITE.erl</em>, then the
-target <code>ct-http</code> will run that specific test suite:</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 ct-http</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk provides a convenient way to run a specific
-group or a specific test case within a specific group,
-using the variable <code>t</code>. Note that this only applies to
-suite-specific targets, like the <code>ct-http</code> example above.</p></div>
-<div class="paragraph"><p>To run all tests from the <code>http_compress</code> group in the
-<code>http_SUITE</code> test suite, write:</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 ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress</tt></pre></div></div>
-<div class="paragraph"><p>Similarly, to run a specific test case in that group:</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 ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress<span style="color: #990000">:</span>headers_dupe</tt></pre></div></div>
-<div class="paragraph"><p>To do the same against a multi-application repository,
-you can use the <code>-C</code> option:</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 -C apps/my_app ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>my_group<span style="color: #990000">:</span>my_case</tt></pre></div></div>
-<div class="paragraph"><p>Note that this also applies to dependencies. When using Cowboy
-as a dependency, you can run the following directly:</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 -C deps/cowboy ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress</tt></pre></div></div>
-<div class="paragraph"><p>Finally, <a href="../coverage">code coverage</a> is available,
-but covered in its own chapter.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Common Test is Erlang’s functional testing framework. +Erlang.mk automates the discovery and running of Common +Test suites.</p></div> +<div class="sect1"> +<h2 id="_writing_tests">Writing tests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/common_test/write_test_chapter.html">Common Test user guide</a> +is the best place to learn how to write tests. Erlang.mk +requires that file names for test suites end with <em>_SUITE.erl</em> +and that the files be located in the <em>$(TEST_DIR)</em> directory. +This defaults to <em>test/</em>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>CT_OPTS</code> variable allows you to set extra Common Test +options. Options are documented in the +<a href="http://www.erlang.org/doc/apps/common_test/run_test_chapter.html">Common Test user guide</a>. +You can use it to set Common Test hooks, for 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">CT_OPTS =</span> -ct_hooks cowboy_ct_hook</tt></pre></div></div> +<div class="paragraph"><p>The <code>CT_SUITES</code> variable can be used to override what +Common Test suites Erlang.mk will be aware of. It does +not normally need to be set as Erlang.mk will find the +test suites automatically.</p></div> +<div class="paragraph"><p>The name of the suite is the part before <code>_SUITE.erl</code>. +If the file is named <em>http_SUITE.erl</em>, the test suite +is <code>http</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><span style="color: #009900">CT_SUITES =</span> http ws</tt></pre></div></div> +<div class="paragraph"><p>The <code>CT_LOGS_DIR</code> variable can be used to set where HTML +log files are to be written. This defaults to <em>logs/</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><span style="color: #009900">CT_LOGS_DIR =</span> ct_output_log_dir</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To run all tests (including Common Test):</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 tests</tt></pre></div></div> +<div class="paragraph"><p>To run all tests and static checks (including Common Test):</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 check</tt></pre></div></div> +<div class="paragraph"><p>You can also run Common Test separately:</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 ct</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk will create targets for all test suites it finds. +If you have a file named <em>test/http_SUITE.erl</em>, then the +target <code>ct-http</code> will run that specific test suite:</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 ct-http</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk provides a convenient way to run a specific +group or a specific test case within a specific group, +using the variable <code>t</code>. Note that this only applies to +suite-specific targets, like the <code>ct-http</code> example above.</p></div> +<div class="paragraph"><p>To run all tests from the <code>http_compress</code> group in the +<code>http_SUITE</code> test suite, write:</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 ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress</tt></pre></div></div> +<div class="paragraph"><p>Similarly, to run a specific test case in that group:</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 ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress<span style="color: #990000">:</span>headers_dupe</tt></pre></div></div> +<div class="paragraph"><p>To do the same against a multi-application repository, +you can use the <code>-C</code> option:</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 -C apps/my_app ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>my_group<span style="color: #990000">:</span>my_case</tt></pre></div></div> +<div class="paragraph"><p>Note that this also applies to dependencies. When using Cowboy +as a dependency, you can run the following directly:</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 -C deps/cowboy ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress</tt></pre></div></div> +<div class="paragraph"><p>Finally, <a href="../coverage">code coverage</a> is available, +but covered in its own chapter.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/compat/index.html b/docs/en/erlang.mk/1/guide/compat/index.html index da880762..d257d9ee 100644 --- a/docs/en/erlang.mk/1/guide/compat/index.html +++ b/docs/en/erlang.mk/1/guide/compat/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: Compatibility with other build tools</title> @@ -67,97 +67,104 @@ <h1 class="lined-header"><span>Compatibility with other build tools</span></h1> -<div class="paragraph"><p>Erlang.mk tries its best to be compatible with the other Erlang
-build tools. It can use dependencies written with other build
-tools in mind, and can also make your projects usable by those
-build tools as well. Erlang.mk is like the cool kid that gets
-along with everybody.</p></div>
-<div class="paragraph"><p>In this chapter I will use the term <em>Rebar project</em> to refer
-to a project built using Rebar 2, Rebar 3 or Mad. These three
-build tools are very similar and share the same configuration
-file.</p></div>
-<div class="sect1">
-<h2 id="_rebar_projects_as_erlang_mk_dependencies">Rebar projects as Erlang.mk dependencies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk comes with a feature called <em>Autoload</em> which will
-use Rebar 2 to patch any Rebar project and make it compatible
-with Erlang.mk. This feature essentially patches Rebar out
-and adds a Makefile to the project that Erlang.mk can then
-use for building:</p></div>
-<div class="paragraph"><p><em>Autoload</em> is documented in more details in the
-<a href="../deps">Packages and dependencies</a> chapter.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_projects_as_rebar_dependencies">Erlang.mk projects as Rebar dependencies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk projects can be made compatible with the Rebar family
-of build tools pretty easily, as Erlang.mk will generate
-all the files they require for building.</p></div>
-<div class="paragraph"><p>The Rebar family requires two files: a <em>rebar.config</em> file
-containing compilation options and the list of dependencies,
-and the application resource file, found either at
-<em>ebin/$(PROJECT).app</em> or at <em>src/$(PROJECT).app.src</em>.</p></div>
-<div class="sect3">
-<h4 id="_rebar_configuration">Rebar configuration</h4>
-<div class="paragraph"><p>Erlang.mk comes with a target that generates a <em>rebar.config</em>
-file when invoked:</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 rebar<span style="color: #990000">.</span>config</tt></pre></div></div>
-<div class="paragraph"><p>Careful! This will build the file even if it already existed
-before.</p></div>
-<div class="paragraph"><p>To build this file, Erlang.mk uses information it finds in
-the <code>DEPS</code> and <code>ERLC_OPTS</code> variables, among others. This
-means that the Rebar family builds your project much the
-same way as Erlang.mk.</p></div>
-<div class="paragraph"><p>Careful though! Different build tools have different fetching
-strategies. If some applications provide differing dependencies,
-they might be fetched differently by other build tools. Check
-the upcoming Sanity check chapter to find out how to detect such
-issues.</p></div>
-<div class="paragraph"><p>You can automatically generate this file when you build
-your application, by making it a dependency of the <code>app</code>
-target:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Don’t forget to commit the file when it changes!</p></div>
-<div class="paragraph"><p>If you run into other issues, it’s probably because you use a
-feature specific to Erlang.mk, like the <code>cp</code> fetch method.
-It could also be that we forgot to handle something! Sorry.
-We are of course interested to hear about any compatibility
-problems you may have, just open a ticket!</p></div>
-</div>
-<div class="sect3">
-<h4 id="_application_resource_file">Application resource file</h4>
-<div class="paragraph"><p>Erlang.mk has two ways to generate an application resource
-file: from the information found in the Makefile, or from
-the information found in the <em>src/$(PROJECT).app.src</em> file.
-Needless to say, if you have this file in your repository,
-then you don’t need to worry about compatibility with other
-build tools.</p></div>
-<div class="paragraph"><p>If you don’t, however, it’s not much harder. Every time
-Erlang.mk will compile your application, it will produce
-a new <em>ebin/$(PROJECT).app</em> file. Simply commit this file
-when it changes. It will only change when you modify the
-configuration, add or remove modules.</p></div>
-</div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk tries its best to be compatible with the other Erlang +build tools. It can use dependencies written with other build +tools in mind, and can also make your projects usable by those +build tools as well. Erlang.mk is like the cool kid that gets +along with everybody.</p></div> +<div class="paragraph"><p>In this chapter I will use the term <em>Rebar project</em> to refer +to a project built using Rebar 2, Rebar 3 or Mad. These three +build tools are very similar and share the same configuration +file.</p></div> +<div class="sect1"> +<h2 id="_rebar_projects_as_erlang_mk_dependencies">Rebar projects as Erlang.mk dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk comes with a feature called <em>Autoload</em> which will +use Rebar 2 to patch any Rebar project and make it compatible +with Erlang.mk. This feature essentially patches Rebar out +and adds a Makefile to the project that Erlang.mk can then +use for building:</p></div> +<div class="paragraph"><p><em>Autoload</em> is documented in more details in the +<a href="../deps">Packages and dependencies</a> chapter.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_projects_as_rebar_dependencies">Erlang.mk projects as Rebar dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk projects can be made compatible with the Rebar family +of build tools pretty easily, as Erlang.mk will generate +all the files they require for building.</p></div> +<div class="paragraph"><p>The Rebar family requires two files: a <em>rebar.config</em> file +containing compilation options and the list of dependencies, +and the application resource file, found either at +<em>ebin/$(PROJECT).app</em> or at <em>src/$(PROJECT).app.src</em>.</p></div> +<div class="sect3"> +<h4 id="_rebar_configuration">Rebar configuration</h4> +<div class="paragraph"><p>Erlang.mk comes with a target that generates a <em>rebar.config</em> +file when invoked:</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 rebar<span style="color: #990000">.</span>config</tt></pre></div></div> +<div class="paragraph"><p>Careful! This will build the file even if it already existed +before.</p></div> +<div class="paragraph"><p>To build this file, Erlang.mk uses information it finds in +the <code>DEPS</code> and <code>ERLC_OPTS</code> variables, among others. This +means that the Rebar family builds your project much the +same way as Erlang.mk.</p></div> +<div class="paragraph"><p>Careful though! Different build tools have different fetching +strategies. If some applications provide differing dependencies, +they might be fetched differently by other build tools. Check +the upcoming Sanity check chapter to find out how to detect such +issues.</p></div> +<div class="paragraph"><p>You can automatically generate this file when you build +your application, by making it a dependency of the <code>app</code> +target:</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: #990000">app::</span> rebar.config</tt></pre></div></div> +<div class="paragraph"><p>Don’t forget to commit the file when it changes!</p></div> +<div class="paragraph"><p>If you run into other issues, it’s probably because you use a +feature specific to Erlang.mk, like the <code>cp</code> fetch method. +It could also be that we forgot to handle something! Sorry. +We are of course interested to hear about any compatibility +problems you may have, just open a ticket!</p></div> +</div> +<div class="sect3"> +<h4 id="_application_resource_file">Application resource file</h4> +<div class="paragraph"><p>Erlang.mk has two ways to generate an application resource +file: from the information found in the Makefile, or from +the information found in the <em>src/$(PROJECT).app.src</em> file. +Needless to say, if you have this file in your repository, +then you don’t need to worry about compatibility with other +build tools.</p></div> +<div class="paragraph"><p>If you don’t, however, it’s not much harder. Every time +Erlang.mk will compile your application, it will produce +a new <em>ebin/$(PROJECT).app</em> file. Simply commit this file +when it changes. It will only change when you modify the +configuration, add or remove modules.</p></div> +</div> +</div> +</div> + + + <nav style="margin:1em 0"> - <a style="float:left" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/escripts/"> - Escripts + <a style="float:left" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/kerl/"> + OTP version management </a> diff --git a/docs/en/erlang.mk/1/guide/contributing/index.html b/docs/en/erlang.mk/1/guide/contributing/index.html index 0d549029..c6719e0c 100644 --- a/docs/en/erlang.mk/1/guide/contributing/index.html +++ b/docs/en/erlang.mk/1/guide/contributing/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: Contributing</title> @@ -67,137 +67,140 @@ <h1 class="lined-header"><span>Contributing</span></h1> -<div class="paragraph"><p>You are welcome and encouraged to contribute.</p></div>
-<div class="paragraph"><p>This is how.</p></div>
-<div class="sect1">
-<h2 id="_priorities">Priorities</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>From the most important to the least important:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Bugs
-</p>
-</li>
-<li>
-<p>
-Package issues/additions
-</p>
-</li>
-<li>
-<p>
-Refactoring
-</p>
-</li>
-<li>
-<p>
-Features
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_bugs">Bugs</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you have found a bug, you should open a ticket. Include
-everything relevant including the command you used, output,
-a link to the code that triggers the issue, why you think
-this is a bug, etc.</p></div>
-<div class="paragraph"><p>If you think you have found a bug but you are not sure, you
-should open a ticket as previously explained.</p></div>
-<div class="paragraph"><p>If you have found a bug and you need it to be solved RIGHT
-NOW, open a ticket as previously explained.</p></div>
-<div class="paragraph"><p>Once you have opened a ticket, be patient, try to answer
-questions in a timely manner and confirm that the bug was
-indeed fixed when it is.</p></div>
-<div class="paragraph"><p>If you can’t be patient, either try to solve the bug and
-contribute the fix back or become a paying customer.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_code">Code</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The code is located in the <em>core/*.mk</em> and <em>plugins/*.mk</em> files.
-The tests are located in the <em>test/Makefile</em> and <em>test/*.mk</em> files.</p></div>
-<div class="paragraph"><p>If you have a fix or a hack for a bug, you should open a
-pull request. Any fix should include a test case that fails
-before the fix and is working after.</p></div>
-<div class="paragraph"><p>If you have a test case that reproduces a bug, but no fix for
-it, you should open a pull request.</p></div>
-<div class="paragraph"><p>Changes need to be tested with at least the <code>make check</code>
-command. A specific test case can be tested using <code>make check c=CASE</code>
-with <code>CASE</code> the name of the target to run. Output can be
-modulated using the <code>V</code> variable, which is an integer
-from 0 to 4. A typical use would be <code>make check c=dialyzer V=3</code>.
-The value 4 is particular and shows expanded commands right
-before they are executed.</p></div>
-<div class="paragraph"><p>To run tests in parallel, use the <code>-j</code> option. It is generally
-a good idea to also use the <code>-k</code> option to run all tests even
-if one fails. For example: <code>make check -j 32 -k</code>.</p></div>
-<div class="paragraph"><p>Some changes should be tested against all packages. Continue
-reading for more details on testing them.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_packages">Packages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can search existing packages using the <code>make search q=STRING</code>
-command. This can be done both from an Erlang.mk project or
-directly from the Erlang.mk repository.</p></div>
-<div class="paragraph"><p>Packages can be added to the index using the <code>pkg_add.sh</code> script.</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>$ git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com<span style="color: #990000">/</span><span style="color: #009900">$YOURUSERNAME</span>/erlang<span style="color: #990000">.</span>mk
-$ cd erlang<span style="color: #990000">.</span>mk
-$ <span style="color: #990000">.</span>/pkg_add<span style="color: #990000">.</span>sh cowboy git https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/cowboy <span style="color: #993399">1.0</span><span style="color: #990000">.</span><span style="color: #993399">0</span>
- http<span style="color: #990000">:</span>//ninenines<span style="color: #990000">.</span>eu <span style="color: #FF0000">"Small, fast and modular HTTP server."</span>
-$ git push origin master</tt></pre></div></div>
-<div class="paragraph"><p>Before sending a pull request, you should test your package.
-You can use the following command: <code>make check p=PACKAGE</code>,
-where <code>PACKAGE</code> is the name of the package, for example
-<code>cowboy</code>.</p></div>
-<div class="paragraph"><p>To test all packages, the <code>make packages</code> command can be used.
-This can take a long time. Some packages will fail with certain
-versions of Erlang, or if a prerequisite is missing from your system.
-You can of course speed things up using the <code>-j</code> and <code>-k</code> flags.</p></div>
-<div class="paragraph"><p>After all packages have been tested, you can run the command
-<code>make summary</code> to know what changed since the previous run.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_documentation">Documentation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The documentation is always right.</p></div>
-<div class="paragraph"><p>If you think you have found a mistake in the documentation,
-this is a bug. You can either open a ticket or send a pull
-request.</p></div>
-<div class="paragraph"><p>To make sure that the documentation changes work, install
-the listed <a href="../asciidoc">Requirements</a> on your system and
-run <code>make docs</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_feature_requests">Feature requests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you have an awesome idea or need something that Erlang.mk
-doesn’t provide yet, open a ticket. Provide as much detail as
-possible.</p></div>
-<div class="paragraph"><p>If you have code, great! Open a pull request as previously
-explained.</p></div>
-<div class="paragraph"><p>If not, you can still improve your feature request by writing
-the related documentation.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>You are welcome and encouraged to contribute.</p></div> +<div class="paragraph"><p>This is how.</p></div> +<div class="sect1"> +<h2 id="_priorities">Priorities</h2> +<div class="sectionbody"> +<div class="paragraph"><p>From the most important to the least important:</p></div> +<div class="ulist"><ul> +<li> +<p> +Bugs +</p> +</li> +<li> +<p> +Package issues/additions +</p> +</li> +<li> +<p> +Refactoring +</p> +</li> +<li> +<p> +Features +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_bugs">Bugs</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you have found a bug, you should open a ticket. Include +everything relevant including the command you used, output, +a link to the code that triggers the issue, why you think +this is a bug, etc.</p></div> +<div class="paragraph"><p>If you think you have found a bug but you are not sure, you +should open a ticket as previously explained.</p></div> +<div class="paragraph"><p>If you have found a bug and you need it to be solved RIGHT +NOW, open a ticket as previously explained.</p></div> +<div class="paragraph"><p>Once you have opened a ticket, be patient, try to answer +questions in a timely manner and confirm that the bug was +indeed fixed when it is.</p></div> +<div class="paragraph"><p>If you can’t be patient, either try to solve the bug and +contribute the fix back or become a paying customer.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_code">Code</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The code is located in the <em>core/*.mk</em> and <em>plugins/*.mk</em> files. +The tests are located in the <em>test/Makefile</em> and <em>test/*.mk</em> files.</p></div> +<div class="paragraph"><p>If you have a fix or a hack for a bug, you should open a +pull request. Any fix should include a test case that fails +before the fix and is working after.</p></div> +<div class="paragraph"><p>If you have a test case that reproduces a bug, but no fix for +it, you should open a pull request.</p></div> +<div class="paragraph"><p>Changes need to be tested with at least the <code>make check</code> +command. A specific test case can be tested using <code>make check c=CASE</code> +with <code>CASE</code> the name of the target to run. Output can be +modulated using the <code>V</code> variable, which is an integer +from 0 to 4. A typical use would be <code>make check c=dialyzer V=3</code>. +The value 4 is particular and shows expanded commands right +before they are executed.</p></div> +<div class="paragraph"><p>To run tests in parallel, use the <code>-j</code> option. It is generally +a good idea to also use the <code>-k</code> option to run all tests even +if one fails. For example: <code>make check -j 32 -k</code>.</p></div> +<div class="paragraph"><p>Some changes should be tested against all packages. Continue +reading for more details on testing them.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_packages">Packages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can search existing packages using the <code>make search q=STRING</code> +command. This can be done both from an Erlang.mk project or +directly from the Erlang.mk repository.</p></div> +<div class="paragraph"><p>Packages can be added to the index using the <code>pkg_add.sh</code> script.</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>$ git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com<span style="color: #990000">/</span><span style="color: #009900">$YOURUSERNAME</span>/erlang<span style="color: #990000">.</span>mk +$ cd erlang<span style="color: #990000">.</span>mk +$ <span style="color: #990000">.</span>/pkg_add<span style="color: #990000">.</span>sh cowboy git https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/cowboy <span style="color: #993399">1.0</span><span style="color: #990000">.</span><span style="color: #993399">0</span> + http<span style="color: #990000">:</span>//ninenines<span style="color: #990000">.</span>eu <span style="color: #FF0000">"Small, fast and modular HTTP server."</span> +$ git push origin master</tt></pre></div></div> +<div class="paragraph"><p>Before sending a pull request, you should test your package. +You can use the following command: <code>make check p=PACKAGE</code>, +where <code>PACKAGE</code> is the name of the package, for example +<code>cowboy</code>.</p></div> +<div class="paragraph"><p>To test all packages, the <code>make packages</code> command can be used. +This can take a long time. Some packages will fail with certain +versions of Erlang, or if a prerequisite is missing from your system. +You can of course speed things up using the <code>-j</code> and <code>-k</code> flags.</p></div> +<div class="paragraph"><p>After all packages have been tested, you can run the command +<code>make summary</code> to know what changed since the previous run.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_documentation">Documentation</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The documentation is always right.</p></div> +<div class="paragraph"><p>If you think you have found a mistake in the documentation, +this is a bug. You can either open a ticket or send a pull +request.</p></div> +<div class="paragraph"><p>To make sure that the documentation changes work, install +the listed <a href="../asciidoc">Requirements</a> on your system and +run <code>make docs</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_feature_requests">Feature requests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you have an awesome idea or need something that Erlang.mk +doesn’t provide yet, open a ticket. Provide as much detail as +possible.</p></div> +<div class="paragraph"><p>If you have code, great! Open a pull request as previously +explained.</p></div> +<div class="paragraph"><p>If not, you can still improve your feature request by writing +the related documentation.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/coverage/index.html b/docs/en/erlang.mk/1/guide/coverage/index.html index 39cfde17..d341f6f5 100644 --- a/docs/en/erlang.mk/1/guide/coverage/index.html +++ b/docs/en/erlang.mk/1/guide/coverage/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: Code coverage</title> @@ -67,13 +67,16 @@ <h1 class="lined-header"><span>Code coverage</span></h1> -<div class="paragraph"><p>Placeholder chapter.</p></div>
+<div class="paragraph"><p>Placeholder chapter.</p></div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/deps/index.html b/docs/en/erlang.mk/1/guide/deps/index.html index 330146d6..c5a1904a 100644 --- a/docs/en/erlang.mk/1/guide/deps/index.html +++ b/docs/en/erlang.mk/1/guide/deps/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: Packages and dependencies</title> @@ -67,610 +67,717 @@ <h1 class="lined-header"><span>Packages and dependencies</span></h1> -<div class="paragraph"><p>Erlang.mk can fetch and compile the dependencies that your
-project requires. Erlang.mk improves upon the concepts
-introduced by Rebar, so they should be familiar to many
-seasoned Erlang developers.</p></div>
-<div class="paragraph"><p>Erlang.mk is not a package manager, nor is it trying to be,
-but it does include an index of Erlang packages to make
-discovering useful projects easier.</p></div>
-<div class="paragraph"><p>This chapter will explain how to use packages, add
-dependencies to your project or bundle them directly
-in a single repository.</p></div>
-<div class="sect1">
-<h2 id="_searching_packages">Searching packages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk gives you access to nearly 500 packages, with more
-being added regularly.</p></div>
-<div class="paragraph"><p>To find a package, search for it:</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 search <span style="color: #009900">q</span><span style="color: #990000">=</span>pool</tt></pre></div></div>
-<div class="paragraph"><p>This will return all packages matching this word, like worker
-pool and acceptor pool projects.</p></div>
-<div class="paragraph"><p>You can also list everything and use regular command line
-tools to find what you need, for 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>$ make search <span style="color: #990000">|</span> less</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_adding_dependencies_to_your_project">Adding dependencies to your project</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Once you find the package you need, adding it as a dependency
-to your project is a one-liner:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>And that’s it! The next time you run <code>make</code>, Erlang.mk will
-fetch and compile Cowboy. Erlang.mk will also ensure Cowboy
-is available whenever you use the shell, run tests and any
-other operations.</p></div>
-<div class="paragraph"><p>Erlang.mk will fill in the application resource file with
-all applications found in <code>DEPS</code>. But not all dependencies
-are Erlang applications, and not all dependencies need to
-be a runtime dependency. That’s where the <code>BUILD_DEPS</code>
-variable comes in: it works just like <code>DEPS</code>, except the
-dependencies listed there will not be added as runtime
-dependencies.</p></div>
-<div class="paragraph"><p>For example, you could add a parse transform project like
-this to make it available only at build time:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Or you could depend on a C project directly, if you are
-building a NIF:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>This dependency will be built before your application, so
-you could easily copy the resulting shared file into your
-<em>priv/</em> directory as part of the build process. More information
-about that in the <a href="../ports">NIFs and port drivers</a>
-chapter.</p></div>
-<div class="paragraph"><p>Another variable, <code>LOCAL_DEPS</code>, allows specifying runtime
-dependencies which are part of Erlang/OTP itself, but also
-dependencies that are included in the repository. Since they
-are already on your system, there is no need to fetch them.
-Do note that there is no way to choose the version, the
-application used will be the one already on your system.</p></div>
-<div class="paragraph"><p>You could depend on the Crypto application, for example:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Erlang.mk comes with additional types of dependencies.
-It has <code>TEST_DEPS</code> for dependencies used only for testing:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p><code>DOC_DEPS</code> for dependencies used only when building documentation:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p><code>REL_DEPS</code> for dependencies required to build the release,
-or to include extra applications in the release:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>And <code>SHELL_DEPS</code> for dependencies to make available when running
-the <code>make shell</code> command:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>All these will be documented in more details in their respective
-chapters.</p></div>
-<div class="sect3">
-<h4 id="_modifying_the_dependency_source_or_version">Modifying the dependency source or version</h4>
-<div class="paragraph"><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></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><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></div>
-<div class="paragraph"><p>If you simply want to change the commit number, all you
-need to do is to define the <code>dep_$(DEP_NAME)_commit</code>
-variable. In the case of Cowboy, this would look like this:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Erlang.mk will use the package index to get all information
-about Cowboy, except the commit number which will be overriden.</p></div>
-<div class="paragraph"><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>dep_$(DEP_NAME)</code> variable with everything:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>This will fetch Cowboy from your fork at the given commit.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_fetch_methods">Fetch methods</h4>
-<div class="paragraph"><p>Erlang.mk comes with a number of different fetch methods.
-You can fetch from Git, Mercurial, SVN, to name a few.
-There are fetch methods that will work everywhere, and
-fetch methods that will only work in a given environment.</p></div>
-<div class="paragraph"><p>The following table lists all existing methods:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="33%" />
-<col width="33%" />
-<col width="33%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Name </th>
-<th align="center" valign="top"> Format </th>
-<th align="center" valign="top"> Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">git</p></td>
-<td align="center" valign="top"><p class="table">git repo commit</p></td>
-<td align="center" valign="top"><p class="table">Clone the Git repository and checkout the given version</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">git-submodule</p></td>
-<td align="center" valign="top"><p class="table">git-submodule</p></td>
-<td align="center" valign="top"><p class="table">Initialize and update the Git submodule</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">hg</p></td>
-<td align="center" valign="top"><p class="table">hg repo commit</p></td>
-<td align="center" valign="top"><p class="table">Clone the Mercurial repository and update to the given version</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">svn</p></td>
-<td align="center" valign="top"><p class="table">svn repo</p></td>
-<td align="center" valign="top"><p class="table">Checkout the given SVN repository</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">cp</p></td>
-<td align="center" valign="top"><p class="table">cp path/to/repo</p></td>
-<td align="center" valign="top"><p class="table">Recursively copy a local directory</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">ln</p></td>
-<td align="center" valign="top"><p class="table">ln path/to/repo</p></td>
-<td align="center" valign="top"><p class="table">Symbolically link a local directory</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">hex</p></td>
-<td align="center" valign="top"><p class="table">hex version</p></td>
-<td align="center" valign="top"><p class="table">Download the given project version from hex.pm</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">fail</p></td>
-<td align="center" valign="top"><p class="table">N/A</p></td>
-<td align="center" valign="top"><p class="table">Always fail, reserved for internal use</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">legacy</p></td>
-<td align="center" valign="top"><p class="table">N/A</p></td>
-<td align="center" valign="top"><p class="table">Legacy Erlang.mk fetcher, reserved for internal use</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="paragraph"><p>The <code>git</code> and <code>hg</code> methods both have a repository and commit.
-You can use any valid commit, tag or branch in that repository
-for the commit value.</p></div>
-<div class="paragraph"><p>For example, to fetch Cowboy with tag 2.0.0-pre.2 from Git:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Or to fetch Ehsa tag 4.0.3 from Mercurial:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Git also comes with a concept of submodules. Erlang.mk can
-automatically initializes and updates submodules for dependencies,
-as long as they were added beforehand using <code>git submodule add</code>:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The <code>svn</code> method only has a repository value, but that’s
-simply because the SVN repository URL can also contain
-the path and commit.</p></div>
-<div class="paragraph"><p>This would fetch an example project from the trunk:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>And this would fetch a separate example project from a
-specific commit:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>You can copy a directory from your machine using the <code>cp</code> method.
-It only takes the path to copy from:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Finally, you can use a package from the
-<a href="https://hex.pm/">Hex repository</a>:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-<div class="sect3">
-<h4 id="_custom_fetch_methods">Custom fetch methods</h4>
-<div class="paragraph"><p>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 <code>dep_fetch_$(METHOD)</code> to be available fetch
-methods. You can do anything inside this variable, as long
-as you create a folder named <em>$(DEPS_DIR)/$(call dep_name,$1)</em>.
-Or in layman terms, if your dependency is Cowboy, this would
-become <em>deps/cowboy</em>.</p></div>
-<div class="paragraph"><p>To give an example, this is what the Git method does:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Note that, like dependency information, this custom fetch method
-must be written before including <em>erlang.mk</em>.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_how_deps_are_fetched_and_built">How deps are fetched and built</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The order in which dependencies are fetched and built is well
-defined. This means that Erlang.mk will get the same applications
-regardless of the command or options being used.</p></div>
-<div class="paragraph"><p>In tree traversal terms, where the list of dependencies is a
-tree, Erlang.mk fetches everything using the pre-order traversal
-method. The steps can be summarized like this, starting from
-the root application:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Fetch all dependencies for the application
-</p>
-</li>
-<li>
-<p>
-Build first dependency
-</p>
-</li>
-<li>
-<p>
-Build Nth dependency
-</p>
-</li>
-<li>
-<p>
-Build last dependency
-</p>
-</li>
-</ol></div>
-<div class="paragraph"><p>Every time a dependency is built, these same steps are followed,
-recursively.</p></div>
-<div class="paragraph"><p>Do note that the first step, fetching all dependencies of
-an application, is not guaranteed to be ordered. The reason
-for this is that it is not possible to have the same dependency
-listed twice in a single application, and therefore there can
-be no conflicts. Remember, this step only fetches, at no point
-are different applications built in parallel.</p></div>
-<div class="paragraph"><p>What about conflicts between the dependencies of different
-applications? Simple. Since builds are ordered, this means
-that the first version of an application that is fetched
-will be the one that wins.</p></div>
-<div class="paragraph"><p>This means that if project A depends on projects B and C,
-in this order, and that both B and C depend on a different
-version of D, it will always be B’s version of D that wins,
-because we fetch the dependencies of B before fetching
-those from C.</p></div>
-<div class="paragraph"><p>Similarly, if project A depends on projects B, C and D,
-regardless of the order, and A, B and C depend on a
-different version of D, it will always be A’s version
-that wins, because we fetch all dependencies of A before
-fetching those from B or C.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_fetching_and_listing_dependencies_only">Fetching and listing dependencies only</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can fetch all dependencies recursively without building anything,
-with the <code>make fetch-deps</code> command. It follows the same rules described
-in the section above.</p></div>
-<div class="paragraph"><p>You can list all dependencies recursively, again without building
-anything, with the <code>make list-deps</code> command. It will obviously need
-to fetch all dependencies exactly like <code>make fetch-deps</code>. Once
-everything is fetched, it prints a sorted list of absolute paths to the
-dependencies.</p></div>
-<div class="paragraph"><p>By default, <code>fetch-deps</code> and <code>list-deps</code> work on the <code>BUILD_DEPS</code>
-and <code>DEPS</code> lists only. To also fetch/list <code>TEST_DEPS</code>, <code>DOC_DEPS</code>,
-<code>REL_DEPS</code> and/or <code>SHELL_DEPS</code>, you have two possibilities:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-You can use <code>make fetch-test-deps</code>, <code>make fetch-doc-deps</code>, <code>make
- fetch-rel-deps</code> and <code>make fetch-shell-deps</code> commands respectively.
- If you want to list them, you can use <code>make list-test-deps</code>, <code>make
- list-doc-deps</code>, <code>make list-rel-deps</code> and <code>make list-shell-deps</code>
- respectively.
-</p>
-</li>
-<li>
-<p>
-You can use <code>make fetch-deps</code> or <code>make list-deps</code> with the Makefile
- variable <code>DEP_TYPES</code> set to a list of dependency types you want.
- The types are <code>test</code>, <code>doc</code>, <code>rel</code> and <code>shell</code> respectively. For
- example, you can list test and doc dependencies with <code>make list-deps
- DEP_TYPES='test doc'</code>.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Note that only first level ‘TEST_DEPS<code>, `DOC_DEPS</code>, <code>REL_DEPS</code> and
-<code>SHELL_DEPS</code> are included, not dependencies’ one. In other word,
-<code>make list-test-deps</code> lists the <code>TEST_DEPS</code> of your project, but not
-<code>TEST_DEPS</code> of the projects yours depend on.</p></div>
-<div class="paragraph"><p>No matter which method you use, <code>BUILD_DEPS</code> and <code>DEPS</code> are always
-included.</p></div>
-<div class="paragraph"><p>Internally, the <code>make fetch-*</code> commands store the complete list of
-dependencies in files named <code>$(ERLANG_MK_RECURSIVE_DEPS_LIST)</code>,
-<code>$(ERLANG_MK_RECURSIVE_TEST_DEPS_LIST)</code>,
-<code>$(ERLANG_MK_RECURSIVE_DOC_DEPS_LIST)</code>,
-<code>$(ERLANG_MK_RECURSIVE_REL_DEPS_LIST)</code> and
-<code>$(ERLANG_MK_RECURSIVE_SHELL_DEPS_LIST)</code>. Those files are simply printed
-by the <code>make list-*</code> commands.</p></div>
-<div class="paragraph"><p><code>make list-*</code> commands are made for human beings. If you need the list
-of dependencies in a Makefile or a script, you should use the content
-of those files directly instead. The reason is that <code>make fetch-*</code> and
-<code>make list-*</code> may have unwanted content in their output, such as actual
-fetching of dependencies.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ignoring_unwanted_dependencies">Ignoring unwanted dependencies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Sometimes, you may want to ignore dependencies entirely.
-Not even fetch them. You may want to do this because a
-project you depend on depends on an application you do
-not need (like a dependency for building documentation
-or testing). Or maybe the dependency is already installed
-on your system.</p></div>
-<div class="paragraph"><p>To ignore a dependency, simply add it to the <code>IGNORE_DEPS</code>
-variable:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>This will only ignore dependencies that are needed for
-building. It is therefore safe to write:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The PropEr application will be fetched as intended when
-running <code>make tests</code> or <code>make check</code>. It will however
-not be fetched when running <code>make</code> or <code>make deps</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependencies_directory">Dependencies directory</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Dependencies are fetched in <em>$(DEPS_DIR)</em>. By default this is
-the <em>deps</em> directory. You can change this default, but you
-should only do so if it was not defined previously. Erlang.mk
-uses this variable to tell dependencies where to fetch their
-own dependencies.</p></div>
-<div class="paragraph"><p>You will therefore need to use <code>?=</code> instead of <code>=</code>. Of course,
-if you know you will never use this project as a dependency,
-<code>=</code> will work. But to avoid it biting you later on, do this:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The <code>$(CURDIR)</code> part is important, otherwise dependencies of
-dependencies will be fetched in the wrong directory.</p></div>
-<div class="paragraph"><p>Erlang.mk will also export the <code>REBAR_DEPS_DIR</code> variable for
-compatibility with Rebar build tools, as long as they are
-recent enough.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_many_applications_in_one_repository">Many applications in one repository</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>In addition to the dependencies that are fetched, Erlang.mk
-also allows you to have dependencies local to your repository.
-This kind of layout is sometimes called multi-application
-repositories, or repositories with multiple applications.</p></div>
-<div class="paragraph"><p>They work exactly the same as remote dependencies, except:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-They are not fetched
-</p>
-</li>
-<li>
-<p>
-They are not autopatched
-</p>
-</li>
-<li>
-<p>
-They are not deleted on <code>make distclean</code>
-</p>
-</li>
-<li>
-<p>
-They are not automatically added to the application resource file
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>To properly fill the application resource file and compile apps in
-the right order, you will need to define the <code>LOCAL_DEPS</code> variable
-for each relevant application, the same as for OTP applications. Apps
-can depend on each other in this way, and their compilation order
-will follow the same rules as regular dependencies in <code>DEPS</code>.</p></div>
-<div class="paragraph"><p>The top-level <code>LOCAL_DEPS</code> variable, if defined, will determine which
-apps (along with their dependencies) to build, and also which apps
-should be added to the top-level application resource file, if there
-is one. This may be useful, for example, for specifying a different
-set of apps to build for different releases. If <code>LOCAL_DEPS</code> is not
-defined, then all apps in the <em>$(APPS_DIR)</em> will be built, but none
-will be automatically added to the top-level application resource
-file.</p></div>
-<div class="paragraph"><p>If there is a conflict between a local dependency and a
-remote dependency, then the local dependency always wins;
-an error will be triggered when trying to fetch the
-conflicting remote dependency.</p></div>
-<div class="paragraph"><p>To start using dependencies local to the repository, simply
-create a folder named <em>$(APPS_DIR)</em>. By default, this folder
-is the <em>apps/</em> directory.</p></div>
-<div class="paragraph"><p>You can use Erlang.mk to bootstrap local dependencies by
-using the command <code>make new-app</code> or <code>make new-lib</code>. This
-command will create the necessary directories and bootstrap
-the application.</p></div>
-<div class="paragraph"><p>For example, to create a full fledged OTP application as
-a local dependency:</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 new-app <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div>
-<div class="paragraph"><p>Or, the same as an OTP library:</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 new-lib <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div>
-<div class="paragraph"><p>Templates also work with local dependencies, from the root
-directory of the project. You do need however to tell
-Erlang.mk to create the files in the correct application:</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 new <span style="color: #009900">t</span><span style="color: #990000">=</span>gen_server <span style="color: #009900">n</span><span style="color: #990000">=</span>my_server <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_repositories_with_no_application_at_the_root_level">Repositories with no application at the root level</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It’s possible to use Erlang.mk with only applications in
-<em>$(APPS_DIR)</em>, and nothing at the root of the repository.
-Just create a folder, put the <em>erlang.mk</em> file in it,
-write a Makefile that includes it, and start creating
-your applications.</p></div>
-<div class="paragraph"><p>Similarly, it’s possible to have a repository with only
-dependencies found in <em>$(DEPS_DIR)</em>. You just need to
-create a Makefile and specify the dependencies you want.
-This allows you to create a repository for handling the
-building of releases, for example.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_autopatch">Autopatch</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk will automatically patch all the dependencies it
-fetches. It needs to do this to ensure that the dependencies
-become compatible with not only Erlang.mk, but also with
-the version of Erlang.mk that is currently used.</p></div>
-<div class="paragraph"><p>When fetching a dependency, the following operations are
-performed:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Fetch the dependency using the configured fetch method
-</p>
-</li>
-<li>
-<p>
-If it contains a <em>configure.ac</em> or <em>configure.in</em> file, run <code>autoreconf -Wall -vif -I m4</code>
-</p>
-</li>
-<li>
-<p>
-If it contains a <em>configure</em> script, run it
-</p>
-</li>
-<li>
-<p>
-Run autopatch on the project
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Autopatch first checks if there is any project-specific patch
-enabled. There are currently two: <code>RABBITMQ_CLIENT_PATCH</code> for
-the <code>amqp_client</code> dependency, and <code>RABBITMQ_SERVER_PATCH</code> for
-the <code>rabbit</code> dependency. These are needed only for RabbitMQ
-versions before 3.6.0 (assuming you are using upstream RabbitMQ,
-and not a fork).</p></div>
-<div class="paragraph"><p>Otherwise, autopatch performs different operations depending
-on the kind of project it finds the dependency to be.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Rebar projects are automatically converted to use Erlang.mk
-as their build tool. This essentially patches Rebar out, and
-fixes and converts the project to be compatible with Erlang.mk.
-</p>
-</li>
-<li>
-<p>
-Erlang.mk projects have their <em>Makefile</em> patched, if necessary,
-to include the top-level project’s Erlang.mk. This is to ensure
-that functionality works across all dependencies, even if the
-dependency’s Erlang.mk is outdated. The patched Makefile
-can be safely committed if necessary.
-</p>
-</li>
-<li>
-<p>
-Other Erlang projects get a small Erlang.mk Makefile
-generated automatically.
-</p>
-</li>
-<li>
-<p>
-Projects with no source directory and no Makefile get an
-empty Makefile generated, for compatibility purposes.
-</p>
-</li>
-<li>
-<p>
-Other projects with no Makefile are left untouched.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>You can disable the replacing of the <em>erlang.mk</em> file by
-defining the <code>NO_AUTOPATCH_ERLANG_MK</code> variable:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>You can also disable autopatch entirely for a few select
-projects using the <code>NO_AUTOPATCH</code> variable:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_skipping_deps">Skipping deps</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It is possible to temporarily skip all dependency operations.
-This is done by defining the <code>SKIP_DEPS</code> variable. Use cases
-include being somewhere with no connection to download them,
-or perhaps a peculiar setup.</p></div>
-<div class="paragraph"><p>A typical usage would be:</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 <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>When the variable is defined:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Dependencies will not be compiled or downloaded when required
-</p>
-</li>
-<li>
-<p>
-The dependency directory <em>$(DEPS_DIR)</em> will not be removed on <code>make distclean</code>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>This variable only applies to remote dependencies.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk can fetch and compile the dependencies that your +project requires. Erlang.mk improves upon the concepts +introduced by Rebar, so they should be familiar to many +seasoned Erlang developers.</p></div> +<div class="paragraph"><p>Erlang.mk is not a package manager, nor is it trying to be, +but it does include an index of Erlang packages to make +discovering useful projects easier.</p></div> +<div class="paragraph"><p>This chapter will explain how to use packages, add +dependencies to your project or bundle them directly +in a single repository.</p></div> +<div class="sect1"> +<h2 id="_searching_packages">Searching packages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk gives you access to nearly 500 packages, with more +being added regularly.</p></div> +<div class="paragraph"><p>To find a package, search for it:</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 search <span style="color: #009900">q</span><span style="color: #990000">=</span>pool</tt></pre></div></div> +<div class="paragraph"><p>This will return all packages matching this word, like worker +pool and acceptor pool projects.</p></div> +<div class="paragraph"><p>You can also list everything and use regular command line +tools to find what you need, for 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>$ make search <span style="color: #990000">|</span> less</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_adding_dependencies_to_your_project">Adding dependencies to your project</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Once you find the package you need, adding it as a dependency +to your project is a one-liner:</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">DEPS =</span> cowboy</tt></pre></div></div> +<div class="paragraph"><p>And that’s it! The next time you run <code>make</code>, Erlang.mk will +fetch and compile Cowboy. Erlang.mk will also ensure Cowboy +is available whenever you use the shell, run tests and any +other operations.</p></div> +<div class="paragraph"><p>Erlang.mk will fill in the application resource file with +all applications found in <code>DEPS</code>. But not all dependencies +are Erlang applications, and not all dependencies need to +be a runtime dependency. That’s where the <code>BUILD_DEPS</code> +variable comes in: it works just like <code>DEPS</code>, except the +dependencies listed there will not be added as runtime +dependencies.</p></div> +<div class="paragraph"><p>For example, you could add a parse transform project like +this to make it available only at build time:</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">BUILD_DEPS =</span> erlando</tt></pre></div></div> +<div class="paragraph"><p>Or you could depend on a C project directly, if you are +building a NIF:</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">BUILD_DEPS =</span> leveldb +<span style="color: #009900">dep_leveldb =</span> git https<span style="color: #990000">:</span>//github.com/basho/leveldb 2.1.3</tt></pre></div></div> +<div class="paragraph"><p>This dependency will be built before your application, so +you could easily copy the resulting shared file into your +<em>priv/</em> directory as part of the build process. More information +about that in the <a href="../ports">NIFs and port drivers</a> +chapter.</p></div> +<div class="paragraph"><p>Another variable, <code>LOCAL_DEPS</code>, allows specifying runtime +dependencies which are part of Erlang/OTP itself, but also +dependencies that are included in the repository. Since they +are already on your system, there is no need to fetch them. +Do note that there is no way to choose the version, the +application used will be the one already on your system.</p></div> +<div class="paragraph"><p>You could depend on the Crypto application, for 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">LOCAL_DEPS =</span> crypto</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk comes with additional types of dependencies. +It has <code>TEST_DEPS</code> for dependencies used only for testing:</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">TEST_DEPS =</span> ct_helper +<span style="color: #009900">dep_ct_helper =</span> git https<span style="color: #990000">:</span>//github.com/ninenines/ct_helper master</tt></pre></div></div> +<div class="paragraph"><p><code>DOC_DEPS</code> for dependencies used only when building documentation:</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">DOC_DEPS =</span> edown</tt></pre></div></div> +<div class="paragraph"><p><code>REL_DEPS</code> for dependencies required to build the release, +or to include extra applications in the release:</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">REL_DEPS =</span> recon</tt></pre></div></div> +<div class="paragraph"><p>And <code>SHELL_DEPS</code> for dependencies to make available when running +the <code>make shell</code> 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">SHELL_DEPS =</span> tddreloader</tt></pre></div></div> +<div class="paragraph"><p>All these will be documented in more details in their respective +chapters.</p></div> +<div class="sect3"> +<h4 id="_modifying_the_dependency_source_or_version">Modifying the dependency source or version</h4> +<div class="paragraph"><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></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">DEPS =</span> cowboy</tt></pre></div></div> +<div class="paragraph"><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></div> +<div class="paragraph"><p>If you simply want to change the commit number, all you +need to do is to define the <code>dep_$(DEP_NAME)_commit</code> +variable. In the case of Cowboy, this would look like this:</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">DEPS =</span> cowboy +<span style="color: #009900">dep_cowboy_commit =</span> 2.0.0-pre.2</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk will use the package index to get all information +about Cowboy, except the commit number which will be overriden.</p></div> +<div class="paragraph"><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>dep_$(DEP_NAME)</code> variable with everything:</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">DEPS =</span> cowboy +<span style="color: #009900">dep_cowboy =</span> git https<span style="color: #990000">:</span>//github.com/essen/cowboy 2.0.0-pre.2</tt></pre></div></div> +<div class="paragraph"><p>This will fetch Cowboy from your fork at the given commit.</p></div> +</div> +<div class="sect3"> +<h4 id="_fetch_methods">Fetch methods</h4> +<div class="paragraph"><p>Erlang.mk comes with a number of different fetch methods. +You can fetch from Git, Mercurial, SVN, to name a few. +There are fetch methods that will work everywhere, and +fetch methods that will only work in a given environment.</p></div> +<div class="paragraph"><p>The following table lists all existing methods:</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="33%" /> +<col width="33%" /> +<col width="33%" /> +<thead> +<tr> +<th align="left" valign="top"> Name </th> +<th align="center" valign="top"> Format </th> +<th align="center" valign="top"> Description</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">git</p></td> +<td align="center" valign="top"><p class="table">git repo commit</p></td> +<td align="center" valign="top"><p class="table">Clone the Git repository and checkout the given version</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">git-submodule</p></td> +<td align="center" valign="top"><p class="table">git-submodule</p></td> +<td align="center" valign="top"><p class="table">Initialize and update the Git submodule</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">hg</p></td> +<td align="center" valign="top"><p class="table">hg repo commit</p></td> +<td align="center" valign="top"><p class="table">Clone the Mercurial repository and update to the given version</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">svn</p></td> +<td align="center" valign="top"><p class="table">svn repo</p></td> +<td align="center" valign="top"><p class="table">Checkout the given SVN repository</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">cp</p></td> +<td align="center" valign="top"><p class="table">cp path/to/repo</p></td> +<td align="center" valign="top"><p class="table">Recursively copy a local directory</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">ln</p></td> +<td align="center" valign="top"><p class="table">ln path/to/repo</p></td> +<td align="center" valign="top"><p class="table">Symbolically link a local directory</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">hex</p></td> +<td align="center" valign="top"><p class="table">hex version</p></td> +<td align="center" valign="top"><p class="table">Download the given project version from hex.pm</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">fail</p></td> +<td align="center" valign="top"><p class="table">N/A</p></td> +<td align="center" valign="top"><p class="table">Always fail, reserved for internal use</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">legacy</p></td> +<td align="center" valign="top"><p class="table">N/A</p></td> +<td align="center" valign="top"><p class="table">Legacy Erlang.mk fetcher, reserved for internal use</p></td> +</tr> +</tbody> +</table> +</div> +<div class="paragraph"><p>The <code>git</code> and <code>hg</code> methods both have a repository and commit. +You can use any valid commit, tag or branch in that repository +for the commit value.</p></div> +<div class="paragraph"><p>For example, to fetch Cowboy with tag 2.0.0-pre.2 from Git:</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">dep_cowboy =</span> git https<span style="color: #990000">:</span>//github.com/ninenines/cowboy 2.0.0-pre.2</tt></pre></div></div> +<div class="paragraph"><p>Or to fetch Ehsa tag 4.0.3 from Mercurial:</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">dep_ehsa =</span> hg https<span style="color: #990000">:</span>//bitbucket.org/a12n/ehsa 4.0.3</tt></pre></div></div> +<div class="paragraph"><p>Git also comes with a concept of submodules. Erlang.mk can +automatically initializes and updates submodules for dependencies, +as long as they were added beforehand using <code>git submodule add</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><span style="color: #009900">dep_cowboy =</span> git-submodule</tt></pre></div></div> +<div class="paragraph"><p>The <code>svn</code> method only has a repository value, but that’s +simply because the SVN repository URL can also contain +the path and commit.</p></div> +<div class="paragraph"><p>This would fetch an example project from the trunk:</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">dep_ex1 =</span> svn https<span style="color: #990000">:</span>//example.com/svn/trunk/project/ex<span style="color: #993399">1</span></tt></pre></div></div> +<div class="paragraph"><p>And this would fetch a separate example project from a +specific commit:</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">dep_ex2 =</span> svn svn<span style="color: #990000">:</span>//example.com/svn/branches/erlang-proj/ex<span style="color: #993399">2</span>@<span style="color: #993399">264</span></tt></pre></div></div> +<div class="paragraph"><p>You can copy a directory from your machine using the <code>cp</code> method. +It only takes the path to copy from:</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">dep_cowboy =</span> cp <span style="color: #009900">$(HOME)</span>/ninenines/cowboy</tt></pre></div></div> +<div class="paragraph"><p>Finally, you can use a package from the +<a href="https://hex.pm/">Hex repository</a>:</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">dep_cowboy =</span> hex 1.0.3</tt></pre></div></div> +</div> +<div class="sect3"> +<h4 id="_custom_fetch_methods">Custom fetch methods</h4> +<div class="paragraph"><p>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 <code>dep_fetch_$(METHOD)</code> to be available fetch +methods. You can do anything inside this variable, as long +as you create a folder named <em>$(DEPS_DIR)/$(call dep_name,$1)</em>. +Or in layman terms, if your dependency is Cowboy, this would +become <em>deps/cowboy</em>.</p></div> +<div class="paragraph"><p>To give an example, this is what the Git method does:</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>define dep_fetch_git + git clone -q -n -- <span style="color: #009900">$(</span>call dep_repo<span style="color: #990000">,</span><span style="color: #009900">$1</span><span style="color: #990000">)</span> <span style="color: #009900">$(DEPS_DIR)</span><span style="color: #990000">/</span><span style="color: #009900">$(</span>call dep_name<span style="color: #990000">,</span><span style="color: #009900">$1</span><span style="color: #990000">);</span> <span style="color: #990000">\</span> + cd <span style="color: #009900">$(DEPS_DIR)</span><span style="color: #990000">/</span><span style="color: #009900">$(</span>call dep_name<span style="color: #990000">,</span><span style="color: #009900">$1</span><span style="color: #990000">)</span> <span style="color: #990000">&&</span> git checkout -q <span style="color: #009900">$(</span>call dep_commit<span style="color: #990000">,</span><span style="color: #009900">$1</span><span style="color: #990000">);</span> +endef</tt></pre></div></div> +<div class="paragraph"><p>Note that, like dependency information, this custom fetch method +must be written before including <em>erlang.mk</em>.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_how_deps_are_fetched_and_built">How deps are fetched and built</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The order in which dependencies are fetched and built is well +defined. This means that Erlang.mk will get the same applications +regardless of the command or options being used.</p></div> +<div class="paragraph"><p>In tree traversal terms, where the list of dependencies is a +tree, Erlang.mk fetches everything using the pre-order traversal +method. The steps can be summarized like this, starting from +the root application:</p></div> +<div class="olist arabic"><ol class="arabic"> +<li> +<p> +Fetch all dependencies for the application +</p> +</li> +<li> +<p> +Build first dependency +</p> +</li> +<li> +<p> +Build Nth dependency +</p> +</li> +<li> +<p> +Build last dependency +</p> +</li> +</ol></div> +<div class="paragraph"><p>Every time a dependency is built, these same steps are followed, +recursively.</p></div> +<div class="paragraph"><p>Do note that the first step, fetching all dependencies of +an application, is not guaranteed to be ordered. The reason +for this is that it is not possible to have the same dependency +listed twice in a single application, and therefore there can +be no conflicts. Remember, this step only fetches, at no point +are different applications built in parallel.</p></div> +<div class="paragraph"><p>What about conflicts between the dependencies of different +applications? Simple. Since builds are ordered, this means +that the first version of an application that is fetched +will be the one that wins.</p></div> +<div class="paragraph"><p>This means that if project A depends on projects B and C, +in this order, and that both B and C depend on a different +version of D, it will always be B’s version of D that wins, +because we fetch the dependencies of B before fetching +those from C.</p></div> +<div class="paragraph"><p>Similarly, if project A depends on projects B, C and D, +regardless of the order, and A, B and C depend on a +different version of D, it will always be A’s version +that wins, because we fetch all dependencies of A before +fetching those from B or C.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_fetching_and_listing_dependencies_only">Fetching and listing dependencies only</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can fetch all dependencies recursively without building anything, +with the <code>make fetch-deps</code> command. It follows the same rules described +in the section above.</p></div> +<div class="paragraph"><p>You can list all dependencies recursively, again without building +anything, with the <code>make list-deps</code> command. It will obviously need +to fetch all dependencies exactly like <code>make fetch-deps</code>. Once +everything is fetched, it prints a sorted list of absolute paths to the +dependencies.</p></div> +<div class="paragraph"><p>By default, <code>fetch-deps</code> and <code>list-deps</code> work on the <code>BUILD_DEPS</code> +and <code>DEPS</code> lists only. To also fetch/list <code>TEST_DEPS</code>, <code>DOC_DEPS</code>, +<code>REL_DEPS</code> and/or <code>SHELL_DEPS</code>, you have two possibilities:</p></div> +<div class="ulist"><ul> +<li> +<p> +You can use <code>make fetch-test-deps</code>, <code>make fetch-doc-deps</code>, <code>make + fetch-rel-deps</code> and <code>make fetch-shell-deps</code> commands respectively. + If you want to list them, you can use <code>make list-test-deps</code>, <code>make + list-doc-deps</code>, <code>make list-rel-deps</code> and <code>make list-shell-deps</code> + respectively. +</p> +</li> +<li> +<p> +You can use <code>make fetch-deps</code> or <code>make list-deps</code> with the Makefile + variable <code>DEP_TYPES</code> set to a list of dependency types you want. + The types are <code>test</code>, <code>doc</code>, <code>rel</code> and <code>shell</code> respectively. For + example, you can list test and doc dependencies with <code>make list-deps + DEP_TYPES='test doc'</code>. +</p> +</li> +</ul></div> +<div class="paragraph"><p>Note that only first level ‘TEST_DEPS<code>, `DOC_DEPS</code>, <code>REL_DEPS</code> and +<code>SHELL_DEPS</code> are included, not dependencies’ one. In other word, +<code>make list-test-deps</code> lists the <code>TEST_DEPS</code> of your project, but not +<code>TEST_DEPS</code> of the projects yours depend on.</p></div> +<div class="paragraph"><p>No matter which method you use, <code>BUILD_DEPS</code> and <code>DEPS</code> are always +included.</p></div> +<div class="paragraph"><p>Internally, the <code>make fetch-*</code> commands store the complete list of +dependencies in files named <code>$(ERLANG_MK_RECURSIVE_DEPS_LIST)</code>, +<code>$(ERLANG_MK_RECURSIVE_TEST_DEPS_LIST)</code>, +<code>$(ERLANG_MK_RECURSIVE_DOC_DEPS_LIST)</code>, +<code>$(ERLANG_MK_RECURSIVE_REL_DEPS_LIST)</code> and +<code>$(ERLANG_MK_RECURSIVE_SHELL_DEPS_LIST)</code>. Those files are simply printed +by the <code>make list-*</code> commands.</p></div> +<div class="paragraph"><p><code>make list-*</code> commands are made for human beings. If you need the list +of dependencies in a Makefile or a script, you should use the content +of those files directly instead. The reason is that <code>make fetch-*</code> and +<code>make list-*</code> may have unwanted content in their output, such as actual +fetching of dependencies.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_ignoring_unwanted_dependencies">Ignoring unwanted dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Sometimes, you may want to ignore dependencies entirely. +Not even fetch them. You may want to do this because a +project you depend on depends on an application you do +not need (like a dependency for building documentation +or testing). Or maybe the dependency is already installed +on your system.</p></div> +<div class="paragraph"><p>To ignore a dependency, simply add it to the <code>IGNORE_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>IGNORE_DEPS <span style="color: #990000">+=</span> edown proper</tt></pre></div></div> +<div class="paragraph"><p>This will only ignore dependencies that are needed for +building. It is therefore safe to write:</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>IGNORE_DEPS <span style="color: #990000">+=</span> edown proper +<span style="color: #009900">TEST_DEPS =</span> proper</tt></pre></div></div> +<div class="paragraph"><p>The PropEr application will be fetched as intended when +running <code>make tests</code> or <code>make check</code>. It will however +not be fetched when running <code>make</code> or <code>make deps</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependencies_directory">Dependencies directory</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Dependencies are fetched in <em>$(DEPS_DIR)</em>. By default this is +the <em>deps</em> directory. You can change this default, but you +should only do so if it was not defined previously. Erlang.mk +uses this variable to tell dependencies where to fetch their +own dependencies.</p></div> +<div class="paragraph"><p>You will therefore need to use <code>?=</code> instead of <code>=</code>. Of course, +if you know you will never use this project as a dependency, +<code>=</code> will work. But to avoid it biting you later on, do this:</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>DEPS_DIR <span style="color: #990000">?=</span> <span style="color: #009900">$(CURDIR)</span>/libs</tt></pre></div></div> +<div class="paragraph"><p>The <code>$(CURDIR)</code> part is important, otherwise dependencies of +dependencies will be fetched in the wrong directory.</p></div> +<div class="paragraph"><p>Erlang.mk will also export the <code>REBAR_DEPS_DIR</code> variable for +compatibility with Rebar build tools, as long as they are +recent enough.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_many_applications_in_one_repository">Many applications in one repository</h2> +<div class="sectionbody"> +<div class="paragraph"><p>In addition to the dependencies that are fetched, Erlang.mk +also allows you to have dependencies local to your repository. +This kind of layout is sometimes called multi-application +repositories, or repositories with multiple applications.</p></div> +<div class="paragraph"><p>They work exactly the same as remote dependencies, except:</p></div> +<div class="ulist"><ul> +<li> +<p> +They are not fetched +</p> +</li> +<li> +<p> +They are not autopatched +</p> +</li> +<li> +<p> +They are not deleted on <code>make distclean</code> +</p> +</li> +<li> +<p> +They are not automatically added to the application resource file +</p> +</li> +</ul></div> +<div class="paragraph"><p>To properly fill the application resource file and compile apps in +the right order, you will need to define the <code>LOCAL_DEPS</code> variable +for each relevant application, the same as for OTP applications. Apps +can depend on each other in this way, and their compilation order +will follow the same rules as regular dependencies in <code>DEPS</code>.</p></div> +<div class="paragraph"><p>The top-level <code>LOCAL_DEPS</code> variable, if defined, will determine which +apps (along with their dependencies) to build, and also which apps +should be added to the top-level application resource file, if there +is one. This may be useful, for example, for specifying a different +set of apps to build for different releases. If <code>LOCAL_DEPS</code> is not +defined, then all apps in the <em>$(APPS_DIR)</em> will be built, but none +will be automatically added to the top-level application resource +file.</p></div> +<div class="paragraph"><p>If there is a conflict between a local dependency and a +remote dependency, then the local dependency always wins; +an error will be triggered when trying to fetch the +conflicting remote dependency.</p></div> +<div class="paragraph"><p>To start using dependencies local to the repository, simply +create a folder named <em>$(APPS_DIR)</em>. By default, this folder +is the <em>apps/</em> directory.</p></div> +<div class="paragraph"><p>You can use Erlang.mk to bootstrap local dependencies by +using the command <code>make new-app</code> or <code>make new-lib</code>. This +command will create the necessary directories and bootstrap +the application.</p></div> +<div class="paragraph"><p>For example, to create a full fledged OTP application as +a local dependency:</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 new-app <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div> +<div class="paragraph"><p>Or, the same as an OTP library:</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 new-lib <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div> +<div class="paragraph"><p>Templates also work with local dependencies, from the root +directory of the project. You do need however to tell +Erlang.mk to create the files in the correct application:</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 new <span style="color: #009900">t</span><span style="color: #990000">=</span>gen_server <span style="color: #009900">n</span><span style="color: #990000">=</span>my_server <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_repositories_with_no_application_at_the_root_level">Repositories with no application at the root level</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It’s possible to use Erlang.mk with only applications in +<em>$(APPS_DIR)</em>, and nothing at the root of the repository. +Just create a folder, put the <em>erlang.mk</em> file in it, +write a Makefile that includes it, and start creating +your applications.</p></div> +<div class="paragraph"><p>Similarly, it’s possible to have a repository with only +dependencies found in <em>$(DEPS_DIR)</em>. You just need to +create a Makefile and specify the dependencies you want. +This allows you to create a repository for handling the +building of releases, for example.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_autopatch">Autopatch</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk will automatically patch all the dependencies it +fetches. It needs to do this to ensure that the dependencies +become compatible with not only Erlang.mk, but also with +the version of Erlang.mk that is currently used.</p></div> +<div class="paragraph"><p>When fetching a dependency, the following operations are +performed:</p></div> +<div class="ulist"><ul> +<li> +<p> +Fetch the dependency using the configured fetch method +</p> +</li> +<li> +<p> +If it contains a <em>configure.ac</em> or <em>configure.in</em> file, run <code>autoreconf -Wall -vif -I m4</code> +</p> +</li> +<li> +<p> +If it contains a <em>configure</em> script, run it +</p> +</li> +<li> +<p> +Run autopatch on the project +</p> +</li> +</ul></div> +<div class="paragraph"><p>Autopatch first checks if there is any project-specific patch +enabled. There are currently two: <code>RABBITMQ_CLIENT_PATCH</code> for +the <code>amqp_client</code> dependency, and <code>RABBITMQ_SERVER_PATCH</code> for +the <code>rabbit</code> dependency. These are needed only for RabbitMQ +versions before 3.6.0 (assuming you are using upstream RabbitMQ, +and not a fork).</p></div> +<div class="paragraph"><p>Otherwise, autopatch performs different operations depending +on the kind of project it finds the dependency to be.</p></div> +<div class="ulist"><ul> +<li> +<p> +Rebar projects are automatically converted to use Erlang.mk +as their build tool. This essentially patches Rebar out, and +fixes and converts the project to be compatible with Erlang.mk. +</p> +</li> +<li> +<p> +Erlang.mk projects have their <em>Makefile</em> patched, if necessary, +to include the top-level project’s Erlang.mk. This is to ensure +that functionality works across all dependencies, even if the +dependency’s Erlang.mk is outdated. The patched Makefile +can be safely committed if necessary. +</p> +</li> +<li> +<p> +Other Erlang projects get a small Erlang.mk Makefile +generated automatically. +</p> +</li> +<li> +<p> +Projects with no source directory and no Makefile get an +empty Makefile generated, for compatibility purposes. +</p> +</li> +<li> +<p> +Other projects with no Makefile are left untouched. +</p> +</li> +</ul></div> +<div class="paragraph"><p>You can disable the replacing of the <em>erlang.mk</em> file by +defining the <code>NO_AUTOPATCH_ERLANG_MK</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><span style="color: #009900">NO_AUTOPATCH_ERLANG_MK =</span> <span style="color: #993399">1</span></tt></pre></div></div> +<div class="paragraph"><p>You can also disable autopatch entirely for a few select +projects using the <code>NO_AUTOPATCH</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><span style="color: #009900">NO_AUTOPATCH =</span> cowboy ranch cowlib</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_skipping_deps">Skipping deps</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is possible to temporarily skip all dependency operations. +This is done by defining the <code>SKIP_DEPS</code> variable. Use cases +include being somewhere with no connection to download them, +or perhaps a peculiar setup.</p></div> +<div class="paragraph"><p>A typical usage would be:</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 <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>When the variable is defined:</p></div> +<div class="ulist"><ul> +<li> +<p> +Dependencies will not be compiled or downloaded when required +</p> +</li> +<li> +<p> +The dependency directory <em>$(DEPS_DIR)</em> will not be removed on <code>make distclean</code> +</p> +</li> +</ul></div> +<div class="paragraph"><p>This variable only applies to remote dependencies.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/dialyzer/index.html b/docs/en/erlang.mk/1/guide/dialyzer/index.html index d6c7a467..5d8779f8 100644 --- a/docs/en/erlang.mk/1/guide/dialyzer/index.html +++ b/docs/en/erlang.mk/1/guide/dialyzer/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: Dialyzer</title> @@ -67,83 +67,86 @@ <h1 class="lined-header"><span>Dialyzer</span></h1> -<div class="paragraph"><p>Dialyzer is a tool that will detect discrepancies in your
-program. It does so using a technique known as success
-typing analysis which has the advantage of providing no
-false positives. Dialyzer is able to detect type errors,
-dead code and more.</p></div>
-<div class="paragraph"><p>Erlang.mk provides a wrapper around Dialyzer.</p></div>
-<div class="sect1">
-<h2 id="_how_it_works">How it works</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Dialyzer requires a PLT file to work. The PLT file contains
-the analysis information from all applications which are not
-expected to change, or rarely do. These would be all the
-dependencies of the application or applications you are
-currently working on, including standard applications in
-Erlang/OTP itself.</p></div>
-<div class="paragraph"><p>Dialyzer can generate this PLT file. Erlang.mk includes rules
-to automatically generate the PLT file when it is missing.</p></div>
-<div class="paragraph"><p>Once the PLT file is generated, Dialyzer can perform the
-analysis in record time.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>In a typical usage scenario, no variable needs to be set.
-The defaults should be enough. Do note however that the
-dependencies need to be set properly using the <code>DEPS</code> and
-<code>LOCAL_DEPS</code> variables.</p></div>
-<div class="paragraph"><p>The <code>DIALYZER_PLT</code> file indicates where the PLT file will
-be written to (and read from). By default this is
-<em>$(PROJECT).plt</em> in the project’s directory. Note that
-the <code>DIALYZER_PLT</code> variable is exported and is understood
-by Dialyzer directly.</p></div>
-<div class="paragraph"><p>The <code>PLT_APPS</code> variable can be used to add additional
-applications to the PLT. You can either list application
-names or paths to these applications.</p></div>
-<div class="paragraph"><p>Erlang.mk defines two variables for specifying options
-for the analysis: <code>DIALYZER_DIRS</code> and <code>DIALYZER_OPTS</code>.
-The former one defines which directories should be part
-of the analysis. The latter defines what extra warnings
-Dialyzer should report.</p></div>
-<div class="paragraph"><p>Note that Erlang.mk enables the race condition warnings
-by default. As it can take considerably large resources
-to run, you may want to disable it on larger projects.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To perform an analysis, run 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 dialyze</tt></pre></div></div>
-<div class="paragraph"><p>This will create the PLT file if it doesn’t exist.</p></div>
-<div class="paragraph"><p>The analysis will also be performed when you run the
-following command, alongside tests:</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 check</tt></pre></div></div>
-<div class="paragraph"><p>You can use the <code>plt</code> target to create the PLT file if
-it doesn’t exist. This is normally not necessary as
-Dialyzer creates it automatically.</p></div>
-<div class="paragraph"><p>The PLT file will be removed when you run <code>make distclean</code>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Dialyzer is a tool that will detect discrepancies in your +program. It does so using a technique known as success +typing analysis which has the advantage of providing no +false positives. Dialyzer is able to detect type errors, +dead code and more.</p></div> +<div class="paragraph"><p>Erlang.mk provides a wrapper around Dialyzer.</p></div> +<div class="sect1"> +<h2 id="_how_it_works">How it works</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Dialyzer requires a PLT file to work. The PLT file contains +the analysis information from all applications which are not +expected to change, or rarely do. These would be all the +dependencies of the application or applications you are +currently working on, including standard applications in +Erlang/OTP itself.</p></div> +<div class="paragraph"><p>Dialyzer can generate this PLT file. Erlang.mk includes rules +to automatically generate the PLT file when it is missing.</p></div> +<div class="paragraph"><p>Once the PLT file is generated, Dialyzer can perform the +analysis in record time.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>In a typical usage scenario, no variable needs to be set. +The defaults should be enough. Do note however that the +dependencies need to be set properly using the <code>DEPS</code> and +<code>LOCAL_DEPS</code> variables.</p></div> +<div class="paragraph"><p>The <code>DIALYZER_PLT</code> file indicates where the PLT file will +be written to (and read from). By default this is +<em>$(PROJECT).plt</em> in the project’s directory. Note that +the <code>DIALYZER_PLT</code> variable is exported and is understood +by Dialyzer directly.</p></div> +<div class="paragraph"><p>The <code>PLT_APPS</code> variable can be used to add additional +applications to the PLT. You can either list application +names or paths to these applications.</p></div> +<div class="paragraph"><p>Erlang.mk defines two variables for specifying options +for the analysis: <code>DIALYZER_DIRS</code> and <code>DIALYZER_OPTS</code>. +The former one defines which directories should be part +of the analysis. The latter defines what extra warnings +Dialyzer should report.</p></div> +<div class="paragraph"><p>Note that Erlang.mk enables the race condition warnings +by default. As it can take considerably large resources +to run, you may want to disable it on larger projects.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To perform an analysis, run 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 dialyze</tt></pre></div></div> +<div class="paragraph"><p>This will create the PLT file if it doesn’t exist.</p></div> +<div class="paragraph"><p>The analysis will also be performed when you run the +following command, alongside tests:</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 check</tt></pre></div></div> +<div class="paragraph"><p>You can use the <code>plt</code> target to create the PLT file if +it doesn’t exist. This is normally not necessary as +Dialyzer creates it automatically.</p></div> +<div class="paragraph"><p>The PLT file will be removed when you run <code>make distclean</code>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/edoc/index.html b/docs/en/erlang.mk/1/guide/edoc/index.html index bc6befd3..6fcaeeed 100644 --- a/docs/en/erlang.mk/1/guide/edoc/index.html +++ b/docs/en/erlang.mk/1/guide/edoc/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: EDoc comments</title> @@ -67,60 +67,72 @@ <h1 class="lined-header"><span>EDoc comments</span></h1> -<div class="paragraph"><p>Erlang.mk provides a thin wrapper on top of EDoc, an application
-that generates documentation based on comments found in modules.</p></div>
-<div class="sect1">
-<h2 id="_writing_edoc_comments">Writing EDoc comments</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/edoc/chapter.html">EDoc user guide</a>
-explains everything you need to know about EDoc comments.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>EDOC_OPTS</code> variable allows you to specify additional
-EDoc options. Options are documented in the
-<a href="http://www.erlang.org/doc/man/edoc.html#run-2">EDoc manual</a>.</p></div>
-<div class="paragraph"><p>A common use for this variable is to enable Markdown in doc
-comments, using the <code>edown</code> application:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To build all documentation, you would typically use:</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 docs</tt></pre></div></div>
-<div class="paragraph"><p>Do note, however, that EDoc comments will only be generated
-automatically if the <em>doc/overview.edoc</em> file exists. If you
-do not want that file and still want to generate doc comments,
-two solutions are available.</p></div>
-<div class="paragraph"><p>You can generate EDoc documentation directly:</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 edoc</tt></pre></div></div>
-<div class="paragraph"><p>You can enable automatic generation on <code>make docs</code> by adding
-the following to your Makefile:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk provides a thin wrapper on top of EDoc, an application +that generates documentation based on comments found in modules.</p></div> +<div class="sect1"> +<h2 id="_writing_edoc_comments">Writing EDoc comments</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/edoc/chapter.html">EDoc user guide</a> +explains everything you need to know about EDoc comments.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>EDOC_OPTS</code> variable allows you to specify additional +EDoc options. Options are documented in the +<a href="http://www.erlang.org/doc/man/edoc.html#run-2">EDoc manual</a>.</p></div> +<div class="paragraph"><p>A common use for this variable is to enable Markdown in doc +comments, using the <code>edown</code> application:</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">DOC_DEPS =</span> edown +<span style="color: #009900">EDOC_OPTS =</span> {doclet<span style="color: #990000">,</span> edown_doclet}</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To build all documentation, you would typically use:</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 docs</tt></pre></div></div> +<div class="paragraph"><p>Do note, however, that EDoc comments will only be generated +automatically if the <em>doc/overview.edoc</em> file exists. If you +do not want that file and still want to generate doc comments, +two solutions are available.</p></div> +<div class="paragraph"><p>You can generate EDoc documentation directly:</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 edoc</tt></pre></div></div> +<div class="paragraph"><p>You can enable automatic generation on <code>make docs</code> by adding +the following to your Makefile:</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: #990000">docs::</span> edoc</tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/escripts/index.html b/docs/en/erlang.mk/1/guide/escripts/index.html index 2bdc36bf..89cffc80 100644 --- a/docs/en/erlang.mk/1/guide/escripts/index.html +++ b/docs/en/erlang.mk/1/guide/escripts/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: Escripts</title> @@ -67,97 +67,105 @@ <h1 class="lined-header"><span>Escripts</span></h1> -<div class="paragraph"><p>Escripts are an alternative to release. They are meant to be
-used for small command line executables written in Erlang.</p></div>
-<div class="paragraph"><p>They are not self-contained, unlike <a href="../relx">releases</a>.
-Erlang must be installed for them to run. This however means
-that they are fairly small compared to releases.</p></div>
-<div class="paragraph"><p>For self-contained executables, check <a href="../sfx">self-extracting releases</a>.</p></div>
-<div class="sect1">
-<h2 id="_requirements">Requirements</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk uses <code>p7zip</code> by default to generate the escript
-archive. Make sure it is installed. On most systems the
-package is named <code>p7zip</code>; on Ubuntu you need <code>p7zip-full</code>.</p></div>
-<div class="paragraph"><p>If <code>p7zip</code> is unavailable, <code>zip</code> may be used by setting
-the <code>ESCRIPT_ZIP</code> variable. For 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>$ make escript <span style="color: #009900">ESCRIPT_ZIP</span><span style="color: #990000">=</span>zip</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_generating_an_escript">Generating an escript</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Run the following command to generate an escript:</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 escript</tt></pre></div></div>
-<div class="paragraph"><p>This will by default create an escript with the same name as
-the project, in the project’s directory. If the project is
-called <code>relx</code> then the escript will be in <code>./relx</code>.</p></div>
-<div class="paragraph"><p>You can run the escript as you would any executable:</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: #990000">.</span>/relx</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can change the name of the escript by setting <code>ESCRIPT_NAME</code>.
-The name determines both the default output file name and the
-entry module containing the function <code>main/1</code>.</p></div>
-<div class="paragraph"><p><code>ESCRIPT_FILE</code> can be set if you need a different file name
-or location.</p></div>
-<div class="paragraph"><p>The escript header can be entirely customized. The first line
-is the shebang, set by <code>ESCRIPT_SHEBANG</code>. The second line is
-a comment, set by <code>ESCRIPT_COMMENT</code>. The third line is the
-arguments the VM will use when running the escript, set by
-<code>ESCRIPT_EMU_ARGS</code>.</p></div>
-<div class="paragraph"><p>Finally, <code>ESCRIPT_ZIP</code> can be set to customize the command used
-to create the zip file. Read on for more information.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_extra_files">Extra files</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Generating an escript is a two-part process. First, a zip file
-is created with the contents of the escript. Then a header is
-added to this file to create the escript.</p></div>
-<div class="paragraph"><p>It is possible to add commands that will be executed between
-the two steps. You can for example add extra files to the zip
-archive:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The <code>ESCRIPT_ZIP</code> variable contains the command to run to add
-files to the zip archive <code>ESCRIPT_ZIP_FILE</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_optimizing_for_size">Optimizing for size</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk will by default compile BEAM files with debug
-information. You may want to disable this behavior to obtain
-smaller escript files. Simply set <code>ERLC_OPTS</code> to a value that
-does not include <code>+debug_info</code>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Escripts are an alternative to release. They are meant to be +used for small command line executables written in Erlang.</p></div> +<div class="paragraph"><p>They are not self-contained, unlike <a href="../relx">releases</a>. +Erlang must be installed for them to run. This however means +that they are fairly small compared to releases.</p></div> +<div class="paragraph"><p>For self-contained executables, check <a href="../sfx">self-extracting releases</a>.</p></div> +<div class="sect1"> +<h2 id="_requirements">Requirements</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk uses <code>p7zip</code> by default to generate the escript +archive. Make sure it is installed. On most systems the +package is named <code>p7zip</code>; on Ubuntu you need <code>p7zip-full</code>.</p></div> +<div class="paragraph"><p>If <code>p7zip</code> is unavailable, <code>zip</code> may be used by setting +the <code>ESCRIPT_ZIP</code> variable. For 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>$ make escript <span style="color: #009900">ESCRIPT_ZIP</span><span style="color: #990000">=</span>zip</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_generating_an_escript">Generating an escript</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Run the following command to generate an escript:</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 escript</tt></pre></div></div> +<div class="paragraph"><p>This will by default create an escript with the same name as +the project, in the project’s directory. If the project is +called <code>relx</code> then the escript will be in <code>./relx</code>.</p></div> +<div class="paragraph"><p>You can run the escript as you would any executable:</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: #990000">.</span>/relx</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can change the name of the escript by setting <code>ESCRIPT_NAME</code>. +The name determines both the default output file name and the +entry module containing the function <code>main/1</code>.</p></div> +<div class="paragraph"><p><code>ESCRIPT_FILE</code> can be set if you need a different file name +or location.</p></div> +<div class="paragraph"><p>The escript header can be entirely customized. The first line +is the shebang, set by <code>ESCRIPT_SHEBANG</code>. The second line is +a comment, set by <code>ESCRIPT_COMMENT</code>. The third line is the +arguments the VM will use when running the escript, set by +<code>ESCRIPT_EMU_ARGS</code>.</p></div> +<div class="paragraph"><p>Finally, <code>ESCRIPT_ZIP</code> can be set to customize the command used +to create the zip file. Read on for more information.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_extra_files">Extra files</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Generating an escript is a two-part process. First, a zip file +is created with the contents of the escript. Then a header is +added to this file to create the escript.</p></div> +<div class="paragraph"><p>It is possible to add commands that will be executed between +the two steps. You can for example add extra files to the zip +archive:</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: #990000">escript-zip::</span> + <span style="color: #009900">$(verbose)</span> <span style="color: #009900">$(ESCRIPT_ZIP)</span> <span style="color: #009900">$(ESCRIPT_ZIP_FILE)</span> priv/templates<span style="color: #990000">/*</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>ESCRIPT_ZIP</code> variable contains the command to run to add +files to the zip archive <code>ESCRIPT_ZIP_FILE</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_optimizing_for_size">Optimizing for size</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk will by default compile BEAM files with debug +information. You may want to disable this behavior to obtain +smaller escript files. Simply set <code>ERLC_OPTS</code> to a value that +does not include <code>+debug_info</code>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> @@ -167,8 +175,8 @@ does not include <code>+debug_info</code>.</p></div> - <a style="float:right" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/compat/"> - Compatibility with other build tools + <a style="float:right" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/kerl/"> + OTP version management </a> </nav> diff --git a/docs/en/erlang.mk/1/guide/eunit/index.html b/docs/en/erlang.mk/1/guide/eunit/index.html index d3af8b7b..83435883 100644 --- a/docs/en/erlang.mk/1/guide/eunit/index.html +++ b/docs/en/erlang.mk/1/guide/eunit/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: EUnit</title> @@ -67,147 +67,158 @@ <h1 class="lined-header"><span>EUnit</span></h1> -<div class="paragraph"><p>EUnit is the tool of choice for unit testing. Erlang.mk
-automates a few things on top of EUnit, including the
-discovery and running of unit tests.</p></div>
-<div class="sect1">
-<h2 id="_writing_tests">Writing tests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/eunit/chapter.html">EUnit user guide</a>
-is the best place to learn how to write tests. Of note is
-that all functions ending with <code>_test</code> or <code>_test_</code> will be
-picked up as EUnit test cases.</p></div>
-<div class="paragraph"><p>Erlang.mk will automatically pick up tests found in any of
-the Erlang modules of your application. It will also pick up
-tests located in the <em>$(TEST_DIR)</em> directory, which defaults
-to <em>test/</em>.</p></div>
-<div class="paragraph"><p>It is generally a good practice to hide test code from
-the code you ship to production. With Erlang.mk, you can
-do this thanks to the <code>TEST</code> macro. It is only defined
-when running tests:</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="font-weight: bold"><span style="color: #000080">-ifdef</span></span>(<span style="color: #009900">TEST</span>)<span style="color: #990000">.</span>
-
-<span style="font-style: italic"><span style="color: #9A1900">%% Insert tests here.</span></span>
-
-<span style="font-weight: bold"><span style="color: #000080">-endif</span></span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Be careful, however, if you include the EUnit header file,
-as it also defines the <code>TEST</code> macro. Make sure to only include
-it inside an <code>ifdef</code> block, otherwise tests will always be
-compiled.</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="font-weight: bold"><span style="color: #000080">-ifdef</span></span>(<span style="color: #009900">TEST</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000080">-include_lib</span></span>(<span style="color: #990000">\</span><span style="color: #FF0000">"eunit/include/eunit.hrl\").</span>
-
-<span style="color: #FF0000">%% Insert tests here.</span>
-
-<span style="color: #FF0000">-endif.</span></tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk will automatically recompile your code when you
-perform a normal build after running tests, and vice versa.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>EUNIT_OPTS</code> variable allows you to specify additional
-EUnit options. Options are documented in the
-<a href="http://www.erlang.org/doc/man/eunit.html#test-2">EUnit manual</a>.
-At the time of writing, the only available option is <code>verbose</code>:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The <code>EUNIT_ERL_OPTS</code> variable allows you to specify options
-to be passed to <code>erl</code> when running EUnit tests. For example,
-you can load the <em>vm.args</em> and <em>sys.config</em> files:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To run all tests (including EUnit):</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 tests</tt></pre></div></div>
-<div class="paragraph"><p>To run all tests and static checks (including EUnit):</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 check</tt></pre></div></div>
-<div class="paragraph"><p>You can also run EUnit separately:</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 eunit</tt></pre></div></div>
-<div class="paragraph"><p>EUnit will be quiet by default, only outputting errors.
-You can easily make it verbose for a single invocation:</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 eunit <span style="color: #009900">EUNIT_OPTS</span><span style="color: #990000">=</span>verbose</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk allows you to run all tests from a specific
-module, or a specific test case from that module, using
-the variable <code>t</code>.</p></div>
-<div class="paragraph"><p>For example, to run all tests from the <code>cow_http_hd</code>
-module (instead of all tests from the entire project),
-one could write:</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 eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd</tt></pre></div></div>
-<div class="paragraph"><p>Similarly, to run a specific test case:</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 eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd<span style="color: #990000">:</span>parse_accept_test_</tt></pre></div></div>
-<div class="paragraph"><p>To do the same against a multi-application repository,
-you can use the <code>-C</code> option:</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 -C apps/my_app eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>my_module<span style="color: #990000">:</span>hello_test</tt></pre></div></div>
-<div class="paragraph"><p>Note that this also applies to dependencies. From Cowboy,
-you can run the following directly:</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 -C deps/cowlib eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd</tt></pre></div></div>
-<div class="paragraph"><p>Finally, <a href="../coverage">code coverage</a> is available,
-but covered in its own chapter.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>EUnit is the tool of choice for unit testing. Erlang.mk +automates a few things on top of EUnit, including the +discovery and running of unit tests.</p></div> +<div class="sect1"> +<h2 id="_writing_tests">Writing tests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/eunit/chapter.html">EUnit user guide</a> +is the best place to learn how to write tests. Of note is +that all functions ending with <code>_test</code> or <code>_test_</code> will be +picked up as EUnit test cases.</p></div> +<div class="paragraph"><p>Erlang.mk will automatically pick up tests found in any of +the Erlang modules of your application. It will also pick up +tests located in the <em>$(TEST_DIR)</em> directory, which defaults +to <em>test/</em>.</p></div> +<div class="paragraph"><p>It is generally a good practice to hide test code from +the code you ship to production. With Erlang.mk, you can +do this thanks to the <code>TEST</code> macro. It is only defined +when running tests:</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="font-weight: bold"><span style="color: #000080">-ifdef</span></span>(<span style="color: #009900">TEST</span>)<span style="color: #990000">.</span> + +<span style="font-style: italic"><span style="color: #9A1900">%% Insert tests here.</span></span> + +<span style="font-weight: bold"><span style="color: #000080">-endif</span></span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Be careful, however, if you include the EUnit header file, +as it also defines the <code>TEST</code> macro. Make sure to only include +it inside an <code>ifdef</code> block, otherwise tests will always be +compiled.</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="font-weight: bold"><span style="color: #000080">-ifdef</span></span>(<span style="color: #009900">TEST</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000080">-include_lib</span></span>(<span style="color: #990000">\</span><span style="color: #FF0000">"eunit/include/eunit.hrl\").</span> + +<span style="color: #FF0000">%% Insert tests here.</span> + +<span style="color: #FF0000">-endif.</span></tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk will automatically recompile your code when you +perform a normal build after running tests, and vice versa.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>EUNIT_OPTS</code> variable allows you to specify additional +EUnit options. Options are documented in the +<a href="http://www.erlang.org/doc/man/eunit.html#test-2">EUnit manual</a>. +At the time of writing, the only available option is <code>verbose</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><span style="color: #009900">EUNIT_OPTS =</span> verbose</tt></pre></div></div> +<div class="paragraph"><p>The <code>EUNIT_ERL_OPTS</code> variable allows you to specify options +to be passed to <code>erl</code> when running EUnit tests. For example, +you can load the <em>vm.args</em> and <em>sys.config</em> files:</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">EUNIT_ERL_OPTS =</span> -args_file rel/vm.args -config rel/sys.config</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To run all tests (including EUnit):</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 tests</tt></pre></div></div> +<div class="paragraph"><p>To run all tests and static checks (including EUnit):</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 check</tt></pre></div></div> +<div class="paragraph"><p>You can also run EUnit separately:</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 eunit</tt></pre></div></div> +<div class="paragraph"><p>EUnit will be quiet by default, only outputting errors. +You can easily make it verbose for a single invocation:</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 eunit <span style="color: #009900">EUNIT_OPTS</span><span style="color: #990000">=</span>verbose</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk allows you to run all tests from a specific +module, or a specific test case from that module, using +the variable <code>t</code>.</p></div> +<div class="paragraph"><p>For example, to run all tests from the <code>cow_http_hd</code> +module (instead of all tests from the entire project), +one could write:</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 eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd</tt></pre></div></div> +<div class="paragraph"><p>Similarly, to run a specific test case:</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 eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd<span style="color: #990000">:</span>parse_accept_test_</tt></pre></div></div> +<div class="paragraph"><p>To do the same against a multi-application repository, +you can use the <code>-C</code> option:</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 -C apps/my_app eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>my_module<span style="color: #990000">:</span>hello_test</tt></pre></div></div> +<div class="paragraph"><p>Note that this also applies to dependencies. From Cowboy, +you can run the following directly:</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 -C deps/cowlib eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd</tt></pre></div></div> +<div class="paragraph"><p>Finally, <a href="../coverage">code coverage</a> is available, +but covered in its own chapter.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/external_plugins/index.html b/docs/en/erlang.mk/1/guide/external_plugins/index.html index 13d83701..6a901281 100644 --- a/docs/en/erlang.mk/1/guide/external_plugins/index.html +++ b/docs/en/erlang.mk/1/guide/external_plugins/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: External plugins</title> @@ -67,116 +67,163 @@ <h1 class="lined-header"><span>External plugins</span></h1> -<div class="paragraph"><p>It is often convenient to be able to keep the build files
-used by all your projects in one place. Those files could
-be Makefiles, configuration files, templates and more.</p></div>
-<div class="paragraph"><p>Erlang.mk allows you to automatically load plugins from
-dependencies. Plugins can do anything, including defining
-new variables, defining file templates, hooking themselves
-inside the normal Erlang.mk processing or even adding new
-rules.</p></div>
-<div class="paragraph"><p>You can load plugins using one of two methods. You can
-either load all plugins from a dependency, or just one.
-We will also cover conventions about writing external
-plugins.</p></div>
-<div class="sect1">
-<h2 id="_loading_all_plugins_from_a_dependency">Loading all plugins from a dependency</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To load plugins from a dependency, all you need to do is add
-the dependency name to <code>DEP_PLUGINS</code> in addition to the list
-of dependencies.</p></div>
-<div class="paragraph"><p>For example, if you have <code>cowboy</code> in <code>DEPS</code>, add <code>cowboy</code> in
-<code>DEP_PLUGINS</code> also:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>This will load the file <em>plugins.mk</em> in the root folder of
-the Cowboy repository.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_loading_one_plugin_from_a_dependency">Loading one plugin from a dependency</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Now that we know how to load all plugins, let’s take a look
-at how to load one specific plugin from a dependency.</p></div>
-<div class="paragraph"><p>To do this, instead of writing only the name of the dependency,
-we will write its name and the path to the plugin file. This
-means that writing <code>DEP_PLUGINS = cowboy</code> is equivalent to
-writing <code>DEP_PLUGINS = cowboy/plugins.mk</code>.</p></div>
-<div class="paragraph"><p>Knowing this, if we were to load the plugin <em>mk/dist.mk</em>
-from Cowboy and no other, we would write the following in
-our Makefile:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_writing_external_plugins">Writing external plugins</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <em>plugins.mk</em> file is a convention. It is meant to load
-all the plugins from the dependency. The code for the plugin
-can be written directly in <em>plugins.mk</em> or be separate.</p></div>
-<div class="paragraph"><p>If you are providing more than one plugin with your repository,
-the recommended way is to create one file per plugin in the
-<em>mk/</em> folder in your repository, and then include those
-individual plugins in <em>plugins.mk</em>.</p></div>
-<div class="paragraph"><p>For example, if you have two plugins <em>mk/dist.mk</em> and
-<em>mk/templates.mk</em>, you could write the following <em>plugins.mk</em>
-file:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The <code>THIS</code> variable is required to relatively include files.</p></div>
-<div class="paragraph"><p>This allows users to not only be able to select individual
-plugins, but also select all plugins from the dependency
-in one go if they wish to do so.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_early_stage_plugins">Early-stage plugins</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Plugins declared in <code>DEP_PLUGINS</code> 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.
-You need to use "Early-stage plugins". They are declared using the
-<code>DEP_EARLY_PLUGINS</code> variable instead. Plugins listed in this variable
-are loaded near the beginning of Erlang.mk Otherwise, they work exactly
-the same.</p></div>
-<div class="paragraph"><p>If you only give the name of a dependency, the default file loaded is
-<em>early-plugins.mk</em>. You can specify a filename exactly like you would
-have done it with regular plugins.</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_loading_plugins_local_to_the_application">Loading plugins local to the application</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>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
-plugin: the dependency name is simply the name of your application or
-library.</p></div>
-<div class="paragraph"><p>For example, the following Makefile loads a plugin in the <em>mk</em>
-subdirectory:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>This also works with early-stage plugins:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Like external plugins, if you do not specify the path to the plugin, it
-defaults to <em>plugins.mk</em> or <em>early-plugins.mk</em>, located at the root of
-your application:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
+<div class="paragraph"><p>It is often convenient to be able to keep the build files +used by all your projects in one place. Those files could +be Makefiles, configuration files, templates and more.</p></div> +<div class="paragraph"><p>Erlang.mk allows you to automatically load plugins from +dependencies. Plugins can do anything, including defining +new variables, defining file templates, hooking themselves +inside the normal Erlang.mk processing or even adding new +rules.</p></div> +<div class="paragraph"><p>You can load plugins using one of two methods. You can +either load all plugins from a dependency, or just one. +We will also cover conventions about writing external +plugins.</p></div> +<div class="sect1"> +<h2 id="_loading_all_plugins_from_a_dependency">Loading all plugins from a dependency</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To load plugins from a dependency, all you need to do is add +the dependency name to <code>DEP_PLUGINS</code> in addition to the list +of dependencies.</p></div> +<div class="paragraph"><p>For example, if you have <code>cowboy</code> in <code>DEPS</code>, add <code>cowboy</code> in +<code>DEP_PLUGINS</code> also:</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">DEPS =</span> cowboy +<span style="color: #009900">DEP_PLUGINS =</span> cowboy</tt></pre></div></div> +<div class="paragraph"><p>This will load the file <em>plugins.mk</em> in the root folder of +the Cowboy repository.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_loading_one_plugin_from_a_dependency">Loading one plugin from a dependency</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Now that we know how to load all plugins, let’s take a look +at how to load one specific plugin from a dependency.</p></div> +<div class="paragraph"><p>To do this, instead of writing only the name of the dependency, +we will write its name and the path to the plugin file. This +means that writing <code>DEP_PLUGINS = cowboy</code> is equivalent to +writing <code>DEP_PLUGINS = cowboy/plugins.mk</code>.</p></div> +<div class="paragraph"><p>Knowing this, if we were to load the plugin <em>mk/dist.mk</em> +from Cowboy and no other, we would write the following in +our Makefile:</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">DEPS =</span> cowboy +<span style="color: #009900">DEP_PLUGINS =</span> cowboy/mk/dist.mk</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_writing_external_plugins">Writing external plugins</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <em>plugins.mk</em> file is a convention. It is meant to load +all the plugins from the dependency. The code for the plugin +can be written directly in <em>plugins.mk</em> or be separate.</p></div> +<div class="paragraph"><p>If you are providing more than one plugin with your repository, +the recommended way is to create one file per plugin in the +<em>mk/</em> folder in your repository, and then include those +individual plugins in <em>plugins.mk</em>.</p></div> +<div class="paragraph"><p>For example, if you have two plugins <em>mk/dist.mk</em> and +<em>mk/templates.mk</em>, you could write the following <em>plugins.mk</em> +file:</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: #990000">THIS :=</span> <span style="color: #009900">$(</span>dir <span style="color: #009900">$(</span>realpath <span style="color: #009900">$(</span>lastword <span style="color: #009900">$(MAKEFILE_LIST))))</span> +include <span style="color: #009900">$(THIS)</span>/mk/dist.mk +include <span style="color: #009900">$(THIS)</span>/mk/templates.mk</tt></pre></div></div> +<div class="paragraph"><p>The <code>THIS</code> variable is required to relatively include files.</p></div> +<div class="paragraph"><p>This allows users to not only be able to select individual +plugins, but also select all plugins from the dependency +in one go if they wish to do so.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_early_stage_plugins">Early-stage plugins</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Plugins declared in <code>DEP_PLUGINS</code> 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. +You need to use "Early-stage plugins". They are declared using the +<code>DEP_EARLY_PLUGINS</code> variable instead. Plugins listed in this variable +are loaded near the beginning of Erlang.mk Otherwise, they work exactly +the same.</p></div> +<div class="paragraph"><p>If you only give the name of a dependency, the default file loaded is +<em>early-plugins.mk</em>. You can specify a filename exactly like you would +have done it with regular plugins.</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="font-style: italic"><span style="color: #9A1900"># In your application's Makefile</span></span> +<span style="color: #009900">BUILD_DEPS =</span> common_deps +<span style="color: #009900">DEP_EARLY_PLUGINS =</span> common_deps</tt></pre></div></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="font-style: italic"><span style="color: #9A1900"># In the plugin's early-plugins.mk</span></span> +DEPS <span style="color: #990000">+=</span> cowboy +<span style="color: #009900">TEST_DEPS =</span> ct_helper +<span style="color: #009900">dep_ct_helper =</span> git https<span style="color: #990000">:</span>//github.com/ninenines/ct_helper master</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_loading_plugins_local_to_the_application">Loading plugins local to the application</h2> +<div class="sectionbody"> +<div class="paragraph"><p>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 +plugin: the dependency name is simply the name of your application or +library.</p></div> +<div class="paragraph"><p>For example, the following Makefile loads a plugin in the <em>mk</em> +subdirectory:</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">DEP_PLUGINS =</span> <span style="color: #009900">$(PROJECT)</span>/mk/dist.mk</tt></pre></div></div> +<div class="paragraph"><p>This also works with early-stage plugins:</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">DEP_EARLY_PLUGINS =</span> <span style="color: #009900">$(PROJECT)</span>/mk/variables.mk</tt></pre></div></div> +<div class="paragraph"><p>Like external plugins, if you do not specify the path to the plugin, it +defaults to <em>plugins.mk</em> or <em>early-plugins.mk</em>, located at the root of +your application:</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="font-style: italic"><span style="color: #9A1900"># Loads ./early-plugins.mk</span></span> +<span style="color: #009900">DEP_EARLY_PLUGINS =</span> <span style="color: #009900">$(PROJECT)</span> +<span style="font-style: italic"><span style="color: #9A1900"># Loads ./plugins.mk</span></span> +<span style="color: #009900">DEP_PLUGINS =</span> <span style="color: #009900">$(PROJECT)</span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/external_plugins_list/index.html b/docs/en/erlang.mk/1/guide/external_plugins_list/index.html index 452edb39..694b0c58 100644 --- a/docs/en/erlang.mk/1/guide/external_plugins_list/index.html +++ b/docs/en/erlang.mk/1/guide/external_plugins_list/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: List of plugins</title> @@ -67,93 +67,96 @@ <h1 class="lined-header"><span>List of plugins</span></h1> -<div class="paragraph"><p>This is a non-exhaustive list of Erlang.mk plugins, sorted
-alphabetically.</p></div>
-<div class="sect1">
-<h2 id="_efene_mk">efene.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <a href="https://github.com/ninenines/efene.mk">Efene plugin</a> for Erlang.mk.
-<a href="http://efene.org/">Efene</a> is an alternative language for the BEAM.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_elixir_mk">elixir.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <a href="https://github.com/botsunit/elixir.mk">Elixir plugin</a> for
-Erlang.mk. <a href="http://elixir-lang.org/">Elixir</a> is an alternative
-language for the BEAM.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_elvis_mk">elvis.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <a href="https://github.com/inaka/elvis.mk">Elvis plugin</a> for Erlang.mk.
-Elvis is an <a href="https://github.com/inaka/elvis">Erlang style reviewer</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_geas">geas</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="https://github.com/crownedgrouse/geas">Geas</a> gives aggregated
-information on a project and its dependencies, and is available
-as an Erlang.mk plugin.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_hexer_mk">hexer.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <a href="https://github.com/inaka/hexer.mk">Hex plugin</a> for Erlang.mk
-using the <code>hexer</code> tool.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_hexpm_mk">hexpm.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Another <a href="https://github.com/botsunit/hexpm.mk">Hex plugin</a> for
-Erlang.mk, with support for Hex dependency operators.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_jorel">jorel</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="https://github.com/emedia-project/jorel">Jorel</a> is Just anOther RELease
-assembler for Erlang/OTP, and is available as an Erlang.mk plugin.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_lfe_mk">lfe.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <a href="https://github.com/ninenines/lfe.mk">LFE plugin</a> for Erlang.mk.
-LFE, or <a href="http://lfe.io/">Lisp Flavoured Erlang</a>, is an alternative
-language for the BEAM.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_mix_mk">mix.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A <a href="https://github.com/botsunit/mix.mk">Mix plugin</a> for Erlang.mk,
-to generate a compatible configuration file for
-<a href="http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html">Mix</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_reload_mk">reload.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A <a href="https://github.com/bullno1/reload.mk">live reload plugin</a> for Erlang.mk.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rust_mk">rust.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A <a href="https://github.com/goertzenator/rust.mk">plugin</a> to build <a href="https://www.rust-lang.org/">Rust</a> crates and install binaries into <code>priv/</code>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This is a non-exhaustive list of Erlang.mk plugins, sorted +alphabetically.</p></div> +<div class="sect1"> +<h2 id="_efene_mk">efene.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <a href="https://github.com/ninenines/efene.mk">Efene plugin</a> for Erlang.mk. +<a href="http://efene.org/">Efene</a> is an alternative language for the BEAM.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_elixir_mk">elixir.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <a href="https://github.com/botsunit/elixir.mk">Elixir plugin</a> for +Erlang.mk. <a href="http://elixir-lang.org/">Elixir</a> is an alternative +language for the BEAM.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_elvis_mk">elvis.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <a href="https://github.com/inaka/elvis.mk">Elvis plugin</a> for Erlang.mk. +Elvis is an <a href="https://github.com/inaka/elvis">Erlang style reviewer</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_geas">geas</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="https://github.com/crownedgrouse/geas">Geas</a> gives aggregated +information on a project and its dependencies, and is available +as an Erlang.mk plugin.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_hexer_mk">hexer.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <a href="https://github.com/inaka/hexer.mk">Hex plugin</a> for Erlang.mk +using the <code>hexer</code> tool.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_hexpm_mk">hexpm.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Another <a href="https://github.com/botsunit/hexpm.mk">Hex plugin</a> for +Erlang.mk, with support for Hex dependency operators.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_jorel">jorel</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="https://github.com/emedia-project/jorel">Jorel</a> is Just anOther RELease +assembler for Erlang/OTP, and is available as an Erlang.mk plugin.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_lfe_mk">lfe.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <a href="https://github.com/ninenines/lfe.mk">LFE plugin</a> for Erlang.mk. +LFE, or <a href="http://lfe.io/">Lisp Flavoured Erlang</a>, is an alternative +language for the BEAM.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_mix_mk">mix.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A <a href="https://github.com/botsunit/mix.mk">Mix plugin</a> for Erlang.mk, +to generate a compatible configuration file for +<a href="http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html">Mix</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_reload_mk">reload.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A <a href="https://github.com/bullno1/reload.mk">live reload plugin</a> for Erlang.mk.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_rust_mk">rust.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A <a href="https://github.com/goertzenator/rust.mk">plugin</a> to build <a href="https://www.rust-lang.org/">Rust</a> crates and install binaries into <code>priv/</code>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/getting_started/index.html b/docs/en/erlang.mk/1/guide/getting_started/index.html index 2652c05d..dc20db0c 100644 --- a/docs/en/erlang.mk/1/guide/getting_started/index.html +++ b/docs/en/erlang.mk/1/guide/getting_started/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: Getting started</title> @@ -67,364 +67,371 @@ <h1 class="lined-header"><span>Getting started</span></h1> -<div class="paragraph"><p>This chapter explains how to get started using Erlang.mk.</p></div>
-<div class="sect1">
-<h2 id="_creating_a_folder_for_your_project">Creating a folder for your project</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The first step is always to create a new folder that will
-contain your project.</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>$ mkdir hello_joe
-$ cd hello_joe</tt></pre></div></div>
-<div class="paragraph"><p>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,
-put all your projects in a common folder with the same name
-as your username. For example <em>$HOME/ninenines/cowboy</em> for
-the Cowboy project.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_downloading_erlang_mk">Downloading Erlang.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>At the time of writing, Erlang.mk is unlikely to be present
-in your Erlang distribution, or even in your OS packages.</p></div>
-<div class="paragraph"><p>The next step is therefore to download it:</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>$ wget https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk</tt></pre></div></div>
-<div class="paragraph"><p>Or:</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>$ curl -O https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk</tt></pre></div></div>
-<div class="paragraph"><p>Alternatively, just <a href="https://erlang.mk/erlang.mk">click on this link</a>.</p></div>
-<div class="paragraph"><p>Make sure you put the file inside the folder we created previously.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_started_with_otp_applications">Getting started with OTP applications</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An OTP application is an Erlang application that has a supervision
-tree. In other words, it will always have processes running.</p></div>
-<div class="paragraph"><p>This kind of project can be automatically generated by Erlang.mk.
-All you need to do is use the <code>bootstrap</code> target:</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</tt></pre></div></div>
-<div class="paragraph"><p>Something similar to the following snippet will then appear
-on your screen:</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>git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build
-Cloning into <span style="color: #FF0000">'.erlang.mk.build'</span><span style="color: #990000">...</span>
-remote<span style="color: #990000">:</span> Counting objects<span style="color: #990000">:</span> <span style="color: #993399">4035</span><span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-remote<span style="color: #990000">:</span> Compressing objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">12</span><span style="color: #990000">/</span><span style="color: #993399">12</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-remote<span style="color: #990000">:</span> Total <span style="color: #993399">4035</span> <span style="color: #990000">(</span>delta <span style="color: #993399">8</span><span style="color: #990000">),</span> reused <span style="color: #993399">4</span> <span style="color: #990000">(</span>delta <span style="color: #993399">4</span><span style="color: #990000">),</span> pack-reused <span style="color: #993399">4019</span>
-Receiving objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">4035</span><span style="color: #990000">/</span><span style="color: #993399">4035</span><span style="color: #990000">),</span> <span style="color: #993399">1.10</span> MiB <span style="color: #990000">|</span> <span style="color: #993399">784.00</span> KiB/s<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-Resolving deltas<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">2442</span><span style="color: #990000">/</span><span style="color: #993399">2442</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-Checking connectivity<span style="color: #990000">...</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -f build<span style="color: #990000">.</span>config <span style="color: #990000">];</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span> cp build<span style="color: #990000">.</span>config <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span>
-cd <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build <span style="color: #990000">&&</span> make
-make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Entering directory <span style="color: #FF0000">'/home/essen/tmp/hello_joe/.erlang.mk.build'</span>
-awk <span style="color: #FF0000">'FNR==1 && NR!=1{print ""}1'</span> core/core<span style="color: #990000">.</span>mk index<span style="color: #990000">/*.</span>mk core/index<span style="color: #990000">.</span>mk core/deps<span style="color: #990000">.</span>mk plugins/protobuffs<span style="color: #990000">.</span>mk core/erlc<span style="color: #990000">.</span>mk core/docs<span style="color: #990000">.</span>mk core/test<span style="color: #990000">.</span>mk plugins/asciidoc<span style="color: #990000">.</span>mk plugins/bootstrap<span style="color: #990000">.</span>mk plugins/c_src<span style="color: #990000">.</span>mk plugins/ci<span style="color: #990000">.</span>mk plugins/ct<span style="color: #990000">.</span>mk plugins/dialyzer<span style="color: #990000">.</span>mk plugins/edoc<span style="color: #990000">.</span>mk plugins/elvis<span style="color: #990000">.</span>mk plugins/erlydtl<span style="color: #990000">.</span>mk plugins/escript<span style="color: #990000">.</span>mk plugins/eunit<span style="color: #990000">.</span>mk plugins/relx<span style="color: #990000">.</span>mk plugins/shell<span style="color: #990000">.</span>mk plugins/triq<span style="color: #990000">.</span>mk plugins/xref<span style="color: #990000">.</span>mk plugins/cover<span style="color: #990000">.</span>mk <span style="color: #990000">\</span>
- <span style="color: #990000">|</span> sed <span style="color: #FF0000">'s/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/'</span> <span style="color: #990000">></span> erlang<span style="color: #990000">.</span>mk
-make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Leaving directory <span style="color: #FF0000">'/home/essen/tmp/hello_joe/.erlang.mk.build'</span>
-cp <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>/erlang<span style="color: #990000">.</span>mk
-rm -rf <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build</tt></pre></div></div>
-<div class="paragraph"><p>This is Erlang.mk bootstrapping itself. Indeed, the file you
-initially downloaded contains nothing more than the code needed
-to bootstrap. This operation is done only once. Consult the
-<a href="../updating">Updating Erlang.mk</a> chapter for more
-information.</p></div>
-<div class="paragraph"><p>Of course, the generated project can now be compiled:</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>Cheers!</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_started_with_otp_libraries">Getting started with OTP libraries</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An OTP library is an Erlang application that has no supervision
-tree. In other words, it is nothing but modules.</p></div>
-<div class="paragraph"><p>This kind of project can also be generated by Erlang.mk, using
-the <code>bootstrap-lib</code> target:</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</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk will once again bootstrap itself and generate all
-the files for your project. You can now compile it:</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>Enjoy!</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_started_with_otp_releases">Getting started with OTP releases</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An OTP release is the combination of the Erlang RunTime System (ERTS)
-along with all the libraries and files that your node will need
-to run. It is entirely self contained, and can often be sent as-is
-to your production system and run without any extra setup.</p></div>
-<div class="paragraph"><p>Erlang.mk can of course bootstrap your project to generate releases.
-You can use the <code>bootstrap-rel</code> target for this purpose:</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 bootstrap-rel</tt></pre></div></div>
-<div class="paragraph"><p>This target can be combined with <code>bootstrap</code> or <code>bootstrap-lib</code> to
-create a project that will build a release:</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 bootstrap-rel</tt></pre></div></div>
-<div class="paragraph"><p>It is often very useful to keep the top-level project for
-commands useful during operations, and put the components
-of the system in separate applications that you will then
-depend on. Consult the <a href="../deps">Packages and dependencies</a>
-chapter for more information.</p></div>
-<div class="paragraph"><p>When you run <code>make</code> from now on, Erlang.mk will compile your
-project and build the release:</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 hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src
- GEN distclean-relx-rel
- GEN /home/essen/tmp/hello_joe/relx
-<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span>
-<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span>
- /home/essen/tmp/hello_joe/ebin
- /usr/lib/erlang/lib
- /home/essen/tmp/hello_joe/deps
-<span style="color: #990000">===></span> Resolved hello_joe_release-<span style="color: #993399">1</span>
-<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang
-<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span></tt></pre></div></div>
-<div class="paragraph"><p>The first time you run this command, Erlang.mk will download
-<em>relx</em>, the release building tool. So don’t worry if you see
-more output than above.</p></div>
-<div class="paragraph"><p>If building the release is slow, no need to upgrade your
-hardware just yet. Just consult the <a href="../relx">Releases</a>
-chapter for various tips to speed up build time during
-development.</p></div>
-<div class="paragraph"><p>You can start the release using the <em>./_rel/hello_joe_release/bin/hello_joe_release</em>
-script, or simply run <code>make run</code>. The latter will also compile
-your project and build the release if it wasn’t already:</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 run
- APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src
- GEN distclean-relx-rel
-<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span>
-<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span>
- /home/essen/tmp/hello_joe/ebin
- /usr/lib/erlang/lib
- /home/essen/tmp/hello_joe/deps
-<span style="color: #990000">===></span> Resolved hello_joe_release-<span style="color: #993399">1</span>
-<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang
-<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span>
-Exec<span style="color: #990000">:</span> /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/erts-<span style="color: #993399">7.0</span>/bin/erlexec -boot /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/hello_joe_release -boot_var ERTS_LIB_DIR /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/erts-<span style="color: #993399">7.0</span><span style="color: #990000">/..</span>/lib -env ERL_LIBS /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/lib -config /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/sys<span style="color: #990000">.</span>config -args_file /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/vm<span style="color: #990000">.</span>args -- console
-Root<span style="color: #990000">:</span> /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release
-/home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release
-heart_beat_kill_pid <span style="color: #990000">=</span> <span style="color: #993399">16389</span>
-Erlang/OTP <span style="color: #993399">18</span> <span style="color: #990000">[</span>erts-<span style="color: #993399">7.0</span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">source</span></span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="color: #993399">64</span>-bit<span style="color: #990000">]</span> <span style="color: #990000">[</span>smp<span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>async-threads<span style="color: #990000">:</span><span style="color: #993399">10</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>hipe<span style="color: #990000">]</span> <span style="color: #990000">[</span>kernel-poll<span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">false</span></span><span style="color: #990000">]</span>
-
-Eshell V7<span style="color: #990000">.</span><span style="color: #993399">0</span> <span style="color: #990000">(</span>abort with <span style="color: #990000">^</span>G<span style="color: #990000">)</span>
-<span style="color: #990000">(</span>hello_joe@<span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">)</span><span style="color: #993399">1</span><span style="color: #990000">></span></tt></pre></div></div>
-<div class="paragraph"><p>Simple as that!</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_started_from_scratch">Getting started from scratch</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you already have an application, or you want to have full
-control over what files will be created, you can setup Erlang.mk
-manually.</p></div>
-<div class="paragraph"><p>Erlang.mk is very easy to setup: all that you need to do is to
-create a folder, put Erlang.mk in it, and write a one line
-Makefile containing:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>For a step by step:</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>$ mkdir hello_joe
-$ cd hello_joe
-$ curl https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk -o erlang<span style="color: #990000">.</span>mk
-$ echo <span style="color: #FF0000">"include erlang.mk"</span> <span style="color: #990000">></span> Makefile
-$ make</tt></pre></div></div>
-<div class="paragraph"><p>From that point onward you can create an <code>src/</code> folder or start
-using templates.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_spaces_instead_of_tabs">Using spaces instead of tabs</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk defaults to tabs when creating files from templates.
-This is in part because of a personal preference, and in part
-because it is much easier to convert tabs to spaces than the
-opposite.</p></div>
-<div class="paragraph"><p>Use the <code>SP</code> variable if you prefer spaces. Set it to the number
-of spaces per indentation level you want.</p></div>
-<div class="paragraph"><p>For example, if you prefer two spaces per indentation level:</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 <span style="color: #009900">SP</span><span style="color: #990000">=</span><span style="color: #993399">2</span></tt></pre></div></div>
-<div class="paragraph"><p>When you bootstrap the project initially, the variable automatically
-gets added to the Makefile, so you only need to provide it when
-you get started.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_templates">Using templates</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It is no secret that Erlang’s OTP behaviors tend to have some
-boilerplate. It is rarely an issue of course, except when
-creating new modules. That’s why Erlang.mk not only comes with
-templates for generating projects, but also individual modules!</p></div>
-<div class="paragraph"><p>You can list all available templates with the <code>list-templates</code>
-target:</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 list-templates
-Available templates<span style="color: #990000">:</span> cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server ranch_protocol supervisor</tt></pre></div></div>
-<div class="paragraph"><p>To generate a module, let’s say a <code>gen_server</code>, all you need to
-do is to call <code>make new</code> with the appropriate arguments:</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 new <span style="color: #009900">t</span><span style="color: #990000">=</span>gen_server <span style="color: #009900">n</span><span style="color: #990000">=</span>my_server</tt></pre></div></div>
-<div class="paragraph"><p>This will create a module located in <em>src/my_server.erl</em>
-using the <code>gen_server</code> template.</p></div>
-<div class="paragraph"><p>This module is automatically compiled the next time you run
-<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
- ERLC my_server<span style="color: #990000">.</span>erl
- APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src</tt></pre></div></div>
-<div class="paragraph"><p>All that’s left to do is to open it in your favorite editor
-and make it do something!</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_hiding_erlang_mk_from_git">Hiding Erlang.mk from git</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk is a large text file. It can easily take a large part of
-a <code>git diff</code> or a <code>git grep</code> command. You can avoid this by telling
-Git that <em>erlang.mk</em> is a binary file.</p></div>
-<div class="paragraph"><p>Add this to your <em>.gitattributes</em> file. This is a file that you
-can create at the root of your repository:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>erlang.mk -diff</code></pre>
-</div></div>
-<div class="paragraph"><p>The <em>erlang.mk</em> file will still appear in diffs and greps, but
-as a binary file, meaning its contents won’t be shown by default
-anymore.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_help">Getting help</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>During development, if you don’t remember the name of a target,
-you can always run <code>make help</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 <span style="font-weight: bold"><span style="color: #0000FF">help</span></span>
-erlang<span style="color: #990000">.</span>mk <span style="color: #990000">(</span>version <span style="color: #993399">1.2</span><span style="color: #990000">.</span><span style="color: #993399">0</span>-<span style="color: #993399">642</span>-gccd2b9f<span style="color: #990000">)</span> is distributed under the terms of the ISC License<span style="color: #990000">.</span>
-Copyright <span style="color: #990000">(</span>c<span style="color: #990000">)</span> <span style="color: #993399">2013</span>-<span style="color: #993399">2016</span> Loïc Hoguin <span style="color: #990000"><</span>essen@ninenines<span style="color: #990000">.</span>eu<span style="color: #990000">></span>
-
-Usage<span style="color: #990000">:</span> <span style="color: #990000">[</span><span style="color: #009900">V</span><span style="color: #990000">=</span><span style="color: #993399">1</span><span style="color: #990000">]</span> make <span style="color: #990000">[</span>target<span style="color: #990000">]...</span>
-
-Core targets<span style="color: #990000">:</span>
- all Run deps<span style="color: #990000">,</span> app and rel targets <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> that order
- app Compile the project
- deps Fetch dependencies <span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">if</span></span> needed<span style="color: #990000">)</span> and compile them
- search <span style="color: #009900">q</span><span style="color: #990000">=...</span> Search <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> a package <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> the built-in index
- rel Build a release <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> applicable
- docs Build the documentation <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project
- install-docs Install the man pages <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project
- check Compile and run all tests and analysis <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project
- tests Run the tests <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project
- clean Delete temporary and output files from most targets
- distclean Delete all temporary and output files
- <span style="font-weight: bold"><span style="color: #0000FF">help</span></span> Display this <span style="font-weight: bold"><span style="color: #0000FF">help</span></span> and <span style="font-weight: bold"><span style="color: #0000FF">exit</span></span>
- erlang-mk Update erlang<span style="color: #990000">.</span>mk to the latest version
-
-Bootstrap targets<span style="color: #990000">:</span>
- bootstrap Generate a skeleton of an OTP application
- bootstrap-lib Generate a skeleton of an OTP library
- bootstrap-rel Generate the files needed to build a release
- new <span style="color: #009900">t</span><span style="color: #990000">=</span>TPL <span style="color: #009900">n</span><span style="color: #990000">=</span>NAME Generate a module NAME based on the template TPL
- list-templates List available templates
-<span style="color: #990000">...</span></tt></pre></div></div>
-<div class="paragraph"><p>This guide should provide any other answer. If not, please
-open a ticket on <a href="https://github.com/ninenines/erlang.mk/issues">the official repository</a>
-and we will work on improving the guide.</p></div>
-<div class="paragraph"><p>Commercial support is available through Nine Nines. Please contact
-Loïc Hoguin by sending an email to <a href="mailto:[email protected]">[email protected]</a>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter explains how to get started using Erlang.mk.</p></div> +<div class="sect1"> +<h2 id="_creating_a_folder_for_your_project">Creating a folder for your project</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The first step is always to create a new folder that will +contain your project.</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>$ mkdir hello_joe +$ cd hello_joe</tt></pre></div></div> +<div class="paragraph"><p>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, +put all your projects in a common folder with the same name +as your username. For example <em>$HOME/ninenines/cowboy</em> for +the Cowboy project.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_downloading_erlang_mk">Downloading Erlang.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>At the time of writing, Erlang.mk is unlikely to be present +in your Erlang distribution, or even in your OS packages.</p></div> +<div class="paragraph"><p>The next step is therefore to download it:</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>$ wget https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk</tt></pre></div></div> +<div class="paragraph"><p>Or:</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>$ curl -O https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk</tt></pre></div></div> +<div class="paragraph"><p>Alternatively, just <a href="https://erlang.mk/erlang.mk">click on this link</a>.</p></div> +<div class="paragraph"><p>Make sure you put the file inside the folder we created previously.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_started_with_otp_applications">Getting started with OTP applications</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An OTP application is an Erlang application that has a supervision +tree. In other words, it will always have processes running.</p></div> +<div class="paragraph"><p>This kind of project can be automatically generated by Erlang.mk. +All you need to do is use the <code>bootstrap</code> target:</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</tt></pre></div></div> +<div class="paragraph"><p>Something similar to the following snippet will then appear +on your screen:</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>git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build +Cloning into <span style="color: #FF0000">'.erlang.mk.build'</span><span style="color: #990000">...</span> +remote<span style="color: #990000">:</span> Counting objects<span style="color: #990000">:</span> <span style="color: #993399">4035</span><span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +remote<span style="color: #990000">:</span> Compressing objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">12</span><span style="color: #990000">/</span><span style="color: #993399">12</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +remote<span style="color: #990000">:</span> Total <span style="color: #993399">4035</span> <span style="color: #990000">(</span>delta <span style="color: #993399">8</span><span style="color: #990000">),</span> reused <span style="color: #993399">4</span> <span style="color: #990000">(</span>delta <span style="color: #993399">4</span><span style="color: #990000">),</span> pack-reused <span style="color: #993399">4019</span> +Receiving objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">4035</span><span style="color: #990000">/</span><span style="color: #993399">4035</span><span style="color: #990000">),</span> <span style="color: #993399">1.10</span> MiB <span style="color: #990000">|</span> <span style="color: #993399">784.00</span> KiB/s<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +Resolving deltas<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">2442</span><span style="color: #990000">/</span><span style="color: #993399">2442</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +Checking connectivity<span style="color: #990000">...</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -f build<span style="color: #990000">.</span>config <span style="color: #990000">];</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span> cp build<span style="color: #990000">.</span>config <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span> +cd <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build <span style="color: #990000">&&</span> make +make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Entering directory <span style="color: #FF0000">'/home/essen/tmp/hello_joe/.erlang.mk.build'</span> +awk <span style="color: #FF0000">'FNR==1 && NR!=1{print ""}1'</span> core/core<span style="color: #990000">.</span>mk index<span style="color: #990000">/*.</span>mk core/index<span style="color: #990000">.</span>mk core/deps<span style="color: #990000">.</span>mk plugins/protobuffs<span style="color: #990000">.</span>mk core/erlc<span style="color: #990000">.</span>mk core/docs<span style="color: #990000">.</span>mk core/test<span style="color: #990000">.</span>mk plugins/asciidoc<span style="color: #990000">.</span>mk plugins/bootstrap<span style="color: #990000">.</span>mk plugins/c_src<span style="color: #990000">.</span>mk plugins/ci<span style="color: #990000">.</span>mk plugins/ct<span style="color: #990000">.</span>mk plugins/dialyzer<span style="color: #990000">.</span>mk plugins/edoc<span style="color: #990000">.</span>mk plugins/elvis<span style="color: #990000">.</span>mk plugins/erlydtl<span style="color: #990000">.</span>mk plugins/escript<span style="color: #990000">.</span>mk plugins/eunit<span style="color: #990000">.</span>mk plugins/relx<span style="color: #990000">.</span>mk plugins/shell<span style="color: #990000">.</span>mk plugins/triq<span style="color: #990000">.</span>mk plugins/xref<span style="color: #990000">.</span>mk plugins/cover<span style="color: #990000">.</span>mk <span style="color: #990000">\</span> + <span style="color: #990000">|</span> sed <span style="color: #FF0000">'s/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/'</span> <span style="color: #990000">></span> erlang<span style="color: #990000">.</span>mk +make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Leaving directory <span style="color: #FF0000">'/home/essen/tmp/hello_joe/.erlang.mk.build'</span> +cp <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>/erlang<span style="color: #990000">.</span>mk +rm -rf <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build</tt></pre></div></div> +<div class="paragraph"><p>This is Erlang.mk bootstrapping itself. Indeed, the file you +initially downloaded contains nothing more than the code needed +to bootstrap. This operation is done only once. Consult the +<a href="../updating">Updating Erlang.mk</a> chapter for more +information.</p></div> +<div class="paragraph"><p>Of course, the generated project can now be compiled:</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>Cheers!</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_started_with_otp_libraries">Getting started with OTP libraries</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An OTP library is an Erlang application that has no supervision +tree. In other words, it is nothing but modules.</p></div> +<div class="paragraph"><p>This kind of project can also be generated by Erlang.mk, using +the <code>bootstrap-lib</code> target:</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</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk will once again bootstrap itself and generate all +the files for your project. You can now compile it:</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>Enjoy!</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_started_with_otp_releases">Getting started with OTP releases</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An OTP release is the combination of the Erlang RunTime System (ERTS) +along with all the libraries and files that your node will need +to run. It is entirely self contained, and can often be sent as-is +to your production system and run without any extra setup.</p></div> +<div class="paragraph"><p>Erlang.mk can of course bootstrap your project to generate releases. +You can use the <code>bootstrap-rel</code> target for this purpose:</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 bootstrap-rel</tt></pre></div></div> +<div class="paragraph"><p>This target can be combined with <code>bootstrap</code> or <code>bootstrap-lib</code> to +create a project that will build a release:</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 bootstrap-rel</tt></pre></div></div> +<div class="paragraph"><p>It is often very useful to keep the top-level project for +commands useful during operations, and put the components +of the system in separate applications that you will then +depend on. Consult the <a href="../deps">Packages and dependencies</a> +chapter for more information.</p></div> +<div class="paragraph"><p>When you run <code>make</code> from now on, Erlang.mk will compile your +project and build the release:</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 hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src + GEN distclean-relx-rel + GEN /home/essen/tmp/hello_joe/relx +<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span> +<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span> + /home/essen/tmp/hello_joe/ebin + /usr/lib/erlang/lib + /home/essen/tmp/hello_joe/deps +<span style="color: #990000">===></span> Resolved hello_joe_release-<span style="color: #993399">1</span> +<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang +<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span></tt></pre></div></div> +<div class="paragraph"><p>The first time you run this command, Erlang.mk will download +<em>relx</em>, the release building tool. So don’t worry if you see +more output than above.</p></div> +<div class="paragraph"><p>If building the release is slow, no need to upgrade your +hardware just yet. Just consult the <a href="../relx">Releases</a> +chapter for various tips to speed up build time during +development.</p></div> +<div class="paragraph"><p>You can start the release using the <em>./_rel/hello_joe_release/bin/hello_joe_release</em> +script, or simply run <code>make run</code>. The latter will also compile +your project and build the release if it wasn’t already:</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 run + APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src + GEN distclean-relx-rel +<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span> +<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span> + /home/essen/tmp/hello_joe/ebin + /usr/lib/erlang/lib + /home/essen/tmp/hello_joe/deps +<span style="color: #990000">===></span> Resolved hello_joe_release-<span style="color: #993399">1</span> +<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang +<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span> +Exec<span style="color: #990000">:</span> /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/erts-<span style="color: #993399">7.0</span>/bin/erlexec -boot /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/hello_joe_release -boot_var ERTS_LIB_DIR /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/erts-<span style="color: #993399">7.0</span><span style="color: #990000">/..</span>/lib -env ERL_LIBS /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/lib -config /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/sys<span style="color: #990000">.</span>config -args_file /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/vm<span style="color: #990000">.</span>args -- console +Root<span style="color: #990000">:</span> /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release +/home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release +heart_beat_kill_pid <span style="color: #990000">=</span> <span style="color: #993399">16389</span> +Erlang/OTP <span style="color: #993399">18</span> <span style="color: #990000">[</span>erts-<span style="color: #993399">7.0</span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">source</span></span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="color: #993399">64</span>-bit<span style="color: #990000">]</span> <span style="color: #990000">[</span>smp<span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>async-threads<span style="color: #990000">:</span><span style="color: #993399">10</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>hipe<span style="color: #990000">]</span> <span style="color: #990000">[</span>kernel-poll<span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">false</span></span><span style="color: #990000">]</span> + +Eshell V7<span style="color: #990000">.</span><span style="color: #993399">0</span> <span style="color: #990000">(</span>abort with <span style="color: #990000">^</span>G<span style="color: #990000">)</span> +<span style="color: #990000">(</span>hello_joe@<span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">)</span><span style="color: #993399">1</span><span style="color: #990000">></span></tt></pre></div></div> +<div class="paragraph"><p>Simple as that!</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_started_from_scratch">Getting started from scratch</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you already have an application, or you want to have full +control over what files will be created, you can setup Erlang.mk +manually.</p></div> +<div class="paragraph"><p>Erlang.mk is very easy to setup: all that you need to do is to +create a folder, put Erlang.mk in it, and write a one line +Makefile containing:</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</tt></pre></div></div> +<div class="paragraph"><p>For a step by step:</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>$ mkdir hello_joe +$ cd hello_joe +$ curl https<span style="color: #990000">:</span>//erlang<span style="color: #990000">.</span>mk/erlang<span style="color: #990000">.</span>mk -o erlang<span style="color: #990000">.</span>mk +$ echo <span style="color: #FF0000">"include erlang.mk"</span> <span style="color: #990000">></span> Makefile +$ make</tt></pre></div></div> +<div class="paragraph"><p>From that point onward you can create an <code>src/</code> folder or start +using templates.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_spaces_instead_of_tabs">Using spaces instead of tabs</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk defaults to tabs when creating files from templates. +This is in part because of a personal preference, and in part +because it is much easier to convert tabs to spaces than the +opposite.</p></div> +<div class="paragraph"><p>Use the <code>SP</code> variable if you prefer spaces. Set it to the number +of spaces per indentation level you want.</p></div> +<div class="paragraph"><p>For example, if you prefer two spaces per indentation level:</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 <span style="color: #009900">SP</span><span style="color: #990000">=</span><span style="color: #993399">2</span></tt></pre></div></div> +<div class="paragraph"><p>When you bootstrap the project initially, the variable automatically +gets added to the Makefile, so you only need to provide it when +you get started.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_templates">Using templates</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is no secret that Erlang’s OTP behaviors tend to have some +boilerplate. It is rarely an issue of course, except when +creating new modules. That’s why Erlang.mk not only comes with +templates for generating projects, but also individual modules!</p></div> +<div class="paragraph"><p>You can list all available templates with the <code>list-templates</code> +target:</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 list-templates +Available templates<span style="color: #990000">:</span> cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server ranch_protocol supervisor</tt></pre></div></div> +<div class="paragraph"><p>To generate a module, let’s say a <code>gen_server</code>, all you need to +do is to call <code>make new</code> with the appropriate arguments:</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 new <span style="color: #009900">t</span><span style="color: #990000">=</span>gen_server <span style="color: #009900">n</span><span style="color: #990000">=</span>my_server</tt></pre></div></div> +<div class="paragraph"><p>This will create a module located in <em>src/my_server.erl</em> +using the <code>gen_server</code> template.</p></div> +<div class="paragraph"><p>This module is automatically compiled the next time you run +<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 + ERLC my_server<span style="color: #990000">.</span>erl + APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src</tt></pre></div></div> +<div class="paragraph"><p>All that’s left to do is to open it in your favorite editor +and make it do something!</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_hiding_erlang_mk_from_git">Hiding Erlang.mk from git</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk is a large text file. It can easily take a large part of +a <code>git diff</code> or a <code>git grep</code> command. You can avoid this by telling +Git that <em>erlang.mk</em> is a binary file.</p></div> +<div class="paragraph"><p>Add this to your <em>.gitattributes</em> file. This is a file that you +can create at the root of your repository:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>erlang.mk -diff</code></pre> +</div></div> +<div class="paragraph"><p>The <em>erlang.mk</em> file will still appear in diffs and greps, but +as a binary file, meaning its contents won’t be shown by default +anymore.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_help">Getting help</h2> +<div class="sectionbody"> +<div class="paragraph"><p>During development, if you don’t remember the name of a target, +you can always run <code>make help</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 <span style="font-weight: bold"><span style="color: #0000FF">help</span></span> +erlang<span style="color: #990000">.</span>mk <span style="color: #990000">(</span>version <span style="color: #993399">1.2</span><span style="color: #990000">.</span><span style="color: #993399">0</span>-<span style="color: #993399">642</span>-gccd2b9f<span style="color: #990000">)</span> is distributed under the terms of the ISC License<span style="color: #990000">.</span> +Copyright <span style="color: #990000">(</span>c<span style="color: #990000">)</span> <span style="color: #993399">2013</span>-<span style="color: #993399">2016</span> Loïc Hoguin <span style="color: #990000"><</span>essen@ninenines<span style="color: #990000">.</span>eu<span style="color: #990000">></span> + +Usage<span style="color: #990000">:</span> <span style="color: #990000">[</span><span style="color: #009900">V</span><span style="color: #990000">=</span><span style="color: #993399">1</span><span style="color: #990000">]</span> make <span style="color: #990000">[</span>target<span style="color: #990000">]...</span> + +Core targets<span style="color: #990000">:</span> + all Run deps<span style="color: #990000">,</span> app and rel targets <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> that order + app Compile the project + deps Fetch dependencies <span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">if</span></span> needed<span style="color: #990000">)</span> and compile them + search <span style="color: #009900">q</span><span style="color: #990000">=...</span> Search <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> a package <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> the built-in index + rel Build a release <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> applicable + docs Build the documentation <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project + install-docs Install the man pages <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project + check Compile and run all tests and analysis <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project + tests Run the tests <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project + clean Delete temporary and output files from most targets + distclean Delete all temporary and output files + <span style="font-weight: bold"><span style="color: #0000FF">help</span></span> Display this <span style="font-weight: bold"><span style="color: #0000FF">help</span></span> and <span style="font-weight: bold"><span style="color: #0000FF">exit</span></span> + erlang-mk Update erlang<span style="color: #990000">.</span>mk to the latest version + +Bootstrap targets<span style="color: #990000">:</span> + bootstrap Generate a skeleton of an OTP application + bootstrap-lib Generate a skeleton of an OTP library + bootstrap-rel Generate the files needed to build a release + new <span style="color: #009900">t</span><span style="color: #990000">=</span>TPL <span style="color: #009900">n</span><span style="color: #990000">=</span>NAME Generate a module NAME based on the template TPL + list-templates List available templates +<span style="color: #990000">...</span></tt></pre></div></div> +<div class="paragraph"><p>This guide should provide any other answer. If not, please +open a ticket on <a href="https://github.com/ninenines/erlang.mk/issues">the official repository</a> +and we will work on improving the guide.</p></div> +<div class="paragraph"><p>Commercial support is available through Nine Nines. Please contact +Loïc Hoguin by sending an email to <a href="mailto:[email protected]">[email protected]</a>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/history/index.html b/docs/en/erlang.mk/1/guide/history/index.html index 07482cec..5bad3b62 100644 --- a/docs/en/erlang.mk/1/guide/history/index.html +++ b/docs/en/erlang.mk/1/guide/history/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: Short history</title> @@ -67,67 +67,70 @@ <h1 class="lined-header"><span>Short history</span></h1> -<div class="paragraph"><p>This chapter aims to be a brief record of the life of the
-Erlang.mk project.</p></div>
-<div class="sect1">
-<h2 id="_before_erlang_mk">Before Erlang.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk originates from the Cowboy project. Cowboy started
-as a Rebar project and I, Loïc Hoguin, was very happy with it
-for a couple years. Over time however I started getting annoyed
-and frustrated by a number of things, including bad defaults,
-changing defaults and overall slowness.</p></div>
-<div class="paragraph"><p>In particular, at the time I gave up on Rebar, the Cowboy
-test suite was taking about five minutes to run. A quick experiment
-showed I could get much lower times by simply invoking <code>ct_run</code>
-directly. On January 4th, 2013, the Cowboy test suite took less
-than a minute to complete.</p></div>
-<div class="paragraph"><p>Following this success I started removing a little more and,
-on the fateful day of January 5th, 2013, removed the dependency
-on Rebar entirely. Rebar, and in particular the concept of
-dependencies, was, and still is, a pretty strong influence.</p></div>
-<div class="paragraph"><p>Erlang.mk was conceived.</p></div>
-<div class="paragraph"><p>A few months passed and, on May 1st, 2013, the Erlang.mk
-repository was created. Erlang.mk was born.</p></div>
-<div class="paragraph"><p>Little did I know how much it would grow.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_lifetime_of_the_project">Lifetime of the project</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk would eventually become a much larger file able to
-deal with many more projects than just Cowboy. From the birth
-of the project, the biggest force for growth was user contributions,
-because Erlang.mk appealed to a variety of people with different
-needs, needs that Erlang.mk was not fulfilling yet.</p></div>
-<div class="paragraph"><p>The project was split into smaller files focused on a different
-feature each, and a build script was written to build the single
-Erlang.mk file.</p></div>
-<div class="paragraph"><p>A test suite was contributed by a user, and later taken as a basis
-for the current, much more complete test suite. Turns out testing
-a Makefile is pretty straightforward.</p></div>
-<div class="paragraph"><p>A package index was added to solve the problem of discovering
-Erlang projects.</p></div>
-<div class="paragraph"><p>After trying to see if Erlang build tools could cooperate, the
-decision was made to improve compatibility with existing Rebar
-projects by patching Rebar out, using Rebar. This feature, called
-autopatch, proved very successful and made Erlang.mk compatible
-with more than 90% of all Erlang projects.</p></div>
-<div class="paragraph"><p>Erlang.mk documentation was much improved and the Erlang.mk website
-was created in the summer of 2015.</p></div>
-<div class="paragraph"><p>Over the year of 2015, Erlang.mk went from curiosity to a serious
-alternative to other Erlang build tools. The user base increased
-immensely and large projects started using it, including RabbitMQ
-from the 3.6.0 release onward.</p></div>
-<div class="paragraph"><p>A bright future lies ahead.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter aims to be a brief record of the life of the +Erlang.mk project.</p></div> +<div class="sect1"> +<h2 id="_before_erlang_mk">Before Erlang.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk originates from the Cowboy project. Cowboy started +as a Rebar project and I, Loïc Hoguin, was very happy with it +for a couple years. Over time however I started getting annoyed +and frustrated by a number of things, including bad defaults, +changing defaults and overall slowness.</p></div> +<div class="paragraph"><p>In particular, at the time I gave up on Rebar, the Cowboy +test suite was taking about five minutes to run. A quick experiment +showed I could get much lower times by simply invoking <code>ct_run</code> +directly. On January 4th, 2013, the Cowboy test suite took less +than a minute to complete.</p></div> +<div class="paragraph"><p>Following this success I started removing a little more and, +on the fateful day of January 5th, 2013, removed the dependency +on Rebar entirely. Rebar, and in particular the concept of +dependencies, was, and still is, a pretty strong influence.</p></div> +<div class="paragraph"><p>Erlang.mk was conceived.</p></div> +<div class="paragraph"><p>A few months passed and, on May 1st, 2013, the Erlang.mk +repository was created. Erlang.mk was born.</p></div> +<div class="paragraph"><p>Little did I know how much it would grow.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_lifetime_of_the_project">Lifetime of the project</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk would eventually become a much larger file able to +deal with many more projects than just Cowboy. From the birth +of the project, the biggest force for growth was user contributions, +because Erlang.mk appealed to a variety of people with different +needs, needs that Erlang.mk was not fulfilling yet.</p></div> +<div class="paragraph"><p>The project was split into smaller files focused on a different +feature each, and a build script was written to build the single +Erlang.mk file.</p></div> +<div class="paragraph"><p>A test suite was contributed by a user, and later taken as a basis +for the current, much more complete test suite. Turns out testing +a Makefile is pretty straightforward.</p></div> +<div class="paragraph"><p>A package index was added to solve the problem of discovering +Erlang projects.</p></div> +<div class="paragraph"><p>After trying to see if Erlang build tools could cooperate, the +decision was made to improve compatibility with existing Rebar +projects by patching Rebar out, using Rebar. This feature, called +autopatch, proved very successful and made Erlang.mk compatible +with more than 90% of all Erlang projects.</p></div> +<div class="paragraph"><p>Erlang.mk documentation was much improved and the Erlang.mk website +was created in the summer of 2015.</p></div> +<div class="paragraph"><p>Over the year of 2015, Erlang.mk went from curiosity to a serious +alternative to other Erlang build tools. The user base increased +immensely and large projects started using it, including RabbitMQ +from the 3.6.0 release onward.</p></div> +<div class="paragraph"><p>A bright future lies ahead.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/index.html b/docs/en/erlang.mk/1/guide/index.html index 5b8db024..0e1f31d0 100644 --- a/docs/en/erlang.mk/1/guide/index.html +++ b/docs/en/erlang.mk/1/guide/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: Erlang.mk User Guide</title> @@ -67,173 +67,178 @@ <h1 class="lined-header"><span>Erlang.mk User Guide</span></h1> -<div class="ulist"><ul>
-<li>
-<p>
-<a href="installation/">Installation</a>
-</p>
-</li>
-<li>
-<p>
-<a href="getting_started/">Getting started</a>
-</p>
-</li>
-<li>
-<p>
-<a href="overview/">Overview</a>
-</p>
-</li>
-<li>
-<p>
-<a href="updating/">Updating Erlang.mk</a>
-</p>
-</li>
-<li>
-<p>
-<a href="limitations/">Limitations</a>
-</p>
-</li>
-</ul></div>
-<div class="sect1">
-<h2 id="code">Code</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="app/">Building</a>
-</p>
-</li>
-<li>
-<p>
-<a href="deps/">Packages and dependencies</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ports/">NIFs and port drivers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="releases/">Releases</a>
-</p>
-</li>
-<li>
-<p>
-<a href="sfx/">Self-extracting releases</a>
-</p>
-</li>
-<li>
-<p>
-<a href="escripts/">Escripts</a>
-</p>
-</li>
-<li>
-<p>
-<a href="compat/">Compatibility with other build tools</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="docs">Documentation</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="asciidoc/">Asciidoc documentation</a>
-</p>
-</li>
-<li>
-<p>
-<a href="edoc/">EDoc comments</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="tests">Tests</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="shell/">Erlang shell</a>
-</p>
-</li>
-<li>
-<p>
-<a href="eunit/">EUnit</a>
-</p>
-</li>
-<li>
-<p>
-<a href="common_test/">Common Test</a>
-</p>
-</li>
-<li>
-<p>
-<a href="coverage/">Code coverage</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ci/">Continuous integration</a>
-</p>
-</li>
-<li>
-<p>
-<a href="dialyzer/">Dialyzer</a>
-</p>
-</li>
-<li>
-<p>
-<a href="xref/">Xref</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="plugins">Third-party plugins</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="external_plugins/">External plugins</a>
-</p>
-</li>
-<li>
-<p>
-<a href="external_plugins_list/">List of plugins</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="about">About Erlang.mk</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="why/">Why erlang.mk?</a>
-</p>
-</li>
-<li>
-<p>
-<a href="history/">Short history</a>
-</p>
-</li>
-<li>
-<p>
-<a href="contributing/">Contributing</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
+<div class="ulist"><ul> +<li> +<p> +<a href="installation/">Installation</a> +</p> +</li> +<li> +<p> +<a href="getting_started/">Getting started</a> +</p> +</li> +<li> +<p> +<a href="overview/">Overview</a> +</p> +</li> +<li> +<p> +<a href="updating/">Updating Erlang.mk</a> +</p> +</li> +<li> +<p> +<a href="limitations/">Limitations</a> +</p> +</li> +</ul></div> +<div class="sect1"> +<h2 id="code">Code</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="app/">Building</a> +</p> +</li> +<li> +<p> +<a href="deps/">Packages and dependencies</a> +</p> +</li> +<li> +<p> +<a href="ports/">NIFs and port drivers</a> +</p> +</li> +<li> +<p> +<a href="releases/">Releases</a> +</p> +</li> +<li> +<p> +<a href="sfx/">Self-extracting releases</a> +</p> +</li> +<li> +<p> +<a href="escripts/">Escripts</a> +</p> +</li> +<li> +<p> +<a href="kerl/">OTP version management</a> +</p> +</li> +<li> +<p> +<a href="compat/">Compatibility with other build tools</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="docs">Documentation</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="asciidoc/">Asciidoc documentation</a> +</p> +</li> +<li> +<p> +<a href="edoc/">EDoc comments</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="tests">Tests</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="shell/">Erlang shell</a> +</p> +</li> +<li> +<p> +<a href="eunit/">EUnit</a> +</p> +</li> +<li> +<p> +<a href="common_test/">Common Test</a> +</p> +</li> +<li> +<p> +<a href="coverage/">Code coverage</a> +</p> +</li> +<li> +<p> +<a href="ci/">Continuous integration</a> +</p> +</li> +<li> +<p> +<a href="dialyzer/">Dialyzer</a> +</p> +</li> +<li> +<p> +<a href="xref/">Xref</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="plugins">Third-party plugins</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="external_plugins/">External plugins</a> +</p> +</li> +<li> +<p> +<a href="external_plugins_list/">List of plugins</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="about">About Erlang.mk</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="why/">Why erlang.mk?</a> +</p> +</li> +<li> +<p> +<a href="history/">Short history</a> +</p> +</li> +<li> +<p> +<a href="contributing/">Contributing</a> +</p> +</li> +</ul></div> +</div> +</div> diff --git a/docs/en/erlang.mk/1/guide/installation/index.html b/docs/en/erlang.mk/1/guide/installation/index.html index c909fec1..806b25e8 100644 --- a/docs/en/erlang.mk/1/guide/installation/index.html +++ b/docs/en/erlang.mk/1/guide/installation/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: Installation</title> @@ -67,186 +67,189 @@ <h1 class="lined-header"><span>Installation</span></h1> -<div class="sect1">
-<h2 id="_on_unix">On Unix</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk requires GNU Make to be installed. While it will
-currently work with GNU Make 3.81, support for this version
-is deprecated and will be removed in 2017. We recommend
-GNU Make 4.1 or later.</p></div>
-<div class="paragraph"><p>Git and Erlang/OTP must also be installed.</p></div>
-<div class="paragraph"><p>Some functionality requires that Autoconf 2.59 or later be
-installed, in order to compile Erlang/OTP. Erlang/OTP may
-have further requirements depending on your needs.</p></div>
-<div class="paragraph"><p>Some packages may require additional libraries.</p></div>
-<div class="sect3">
-<h4 id="_linux">Linux</h4>
-<div class="paragraph"><p>The commands to install packages vary between distributions:</p></div>
-<div class="listingblock">
-<div class="title">Arch Linux</div>
-<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>$ pacman -S erlang git make</tt></pre></div></div>
-</div>
-<div class="sect3">
-<h4 id="_freebsd">FreeBSD</h4>
-<div class="paragraph"><p>FreeBSD comes with binary and source packages:</p></div>
-<div class="listingblock">
-<div class="title">Install binary packages</div>
-<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>$ pkg install erlang git gmake</tt></pre></div></div>
-<div class="paragraph"><p>On FreeBSD the <code>make</code> command is BSD Make. Use <code>gmake</code> instead.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_os_x_and_macos">OS X and macOS</h4>
-<div class="paragraph"><p>While Apple distributes their own GNU Make, their version is
-very old and plagued with numerous bugs. It is recommended
-to install a more recent version from either Homebrew or
-MacPorts:</p></div>
-<div class="listingblock">
-<div class="title">Homebrew</div>
-<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>$ brew install erlang git homebrew/dupes/make</tt></pre></div></div>
-<div class="paragraph"><p>Homebrew installs GNU Make as <code>gmake</code>. The <code>make</code> command
-is the one provided by Apple.</p></div>
-<div class="listingblock">
-<div class="title">MacPorts</div>
-<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>$ sudo port install erlang git gmake</tt></pre></div></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_on_windows">On Windows</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk can be used on Windows inside an MSYS2 environment.
-Cygwin, MSYS (the original) and native Windows (both Batch
-and PowerShell) are currently not supported.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">Erlang.mk expects Unix line breaks in most of the files
-(LF instead of CRLF). Make sure to configure your text editor
-adequately.</td>
-</tr></table>
-</div>
-<div class="paragraph"><p>The rest of this section details how to setup Erlang/OTP and
-MSYS2 in order to use Erlang.mk.</p></div>
-<div class="sect3">
-<h4 id="_installing_erlang_otp">Installing Erlang/OTP</h4>
-<div class="paragraph"><p>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 <a href="http://www.erlang.org/download.html">official download page</a>.
-It is recommended that you use the 64-bit installer unless
-technically impossible. Please follow the instructions from
-the installer to complete the installation.</p></div>
-<div class="paragraph"><p>The OTP team also provides a short guide to
-<a href="http://www.erlang.org/download.html">installing Erlang/OTP on Windows</a>
-if you need additional references.</p></div>
-<div class="paragraph"><p>You can install Erlang/OTP silently using the <code>/S</code> switch
-on the command line:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>C:\Users\essen\Downloads> otp_win64_18.0.exe /S</code></pre>
-</div></div>
-</div>
-<div class="sect3">
-<h4 id="_installing_msys2">Installing MSYS2</h4>
-<div class="paragraph"><p>The only supported environment on Windows is MSYS2. MSYS2 is
-a lightweight Unix-like environment for Windows that comes
-with the Arch Linux package manager, <code>pacman</code>.</p></div>
-<div class="paragraph"><p>The MSYS2 project provides a <a href="http://msys2.github.io">one click installer</a>
-and instructions to set things up post-installation.</p></div>
-<div class="paragraph"><p>It is currently not possible to use the installer silently.
-Thankfully, the MSYS2 project provides an archive that can
-be used in lieu of the installer. The archive however requires
-<em>7zip</em> to decompress it.</p></div>
-<div class="paragraph"><p>First, download the
-<a href="http://sourceforge.net/projects/msys2/files/Base/x86_64/msys2-base-x86_64-20150512.tar.xz/download">MSYS2 base archive</a>
-and extract it under <em>C:\</em>. Assuming you downloaded the
-archive as <em>msys2.tar.xz</em> and put it in <em>C:\</em>, you can
-use the following commands to extract it:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>C:\> 7z x msys2.tar.xz
-C:\> 7z x msys2.tar > NUL</code></pre>
-</div></div>
-<div class="paragraph"><p>Then you can run the two commands needed to perform the
-post-installation setup:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>C:\> C:\msys64\usr\bin\bash -lc "pacman --needed --noconfirm -Sy bash pacman pacman-mirrors msys2-runtime"
-C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -Syu"</code></pre>
-</div></div>
-</div>
-<div class="sect3">
-<h4 id="_installing_the_required_msys2_packages">Installing the required MSYS2 packages</h4>
-<div class="paragraph"><p>After following these instructions, you can install GNU Make,
-Git and any other required softwares. From an MSYS2 shell,
-you can call <code>pacman</code> directly:</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>$ pacman -S git make</tt></pre></div></div>
-<div class="paragraph"><p>You can use <code>pacman -Ss</code> to search packages. For example,
-to find all packages related to GCC:</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>$ pacman -Ss gcc</tt></pre></div></div>
-<div class="paragraph"><p>If you are going to compile C/C++ code, you will need to
-install this package, as Erlang.mk cannot use the normal
-"gcc" package:</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>$ pacman -S mingw-w<span style="color: #993399">64</span>-x86_64-gcc</tt></pre></div></div>
-<div class="paragraph"><p>You can also run commands under the MSYS2 environment from
-the Windows command line or batch files. This command will
-install GNU Make and Git:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -S git make"</code></pre>
-</div></div>
-<div class="paragraph"><p>You can use similar <code>bash</code> commands if you need to run programs
-inside the MSYS2 environment from a batch file.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_gotchas">Gotchas</h4>
-<div class="paragraph"><p>While most of the basic functionality will just work, there are
-still some issues. Erlang.mk needs to be fixed to pass the
-right paths when running Erlang scripts. We are working on it.
-Erlang.mk is fully tested on both Linux and Windows, but is
-lacking tests in the areas not yet covered by this guide,
-so expect bugs to be fixed as more tests are added.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_on_unix">On Unix</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk requires GNU Make to be installed. While it will +currently work with GNU Make 3.81, support for this version +is deprecated and will be removed in 2017. We recommend +GNU Make 4.1 or later.</p></div> +<div class="paragraph"><p>Git and Erlang/OTP must also be installed.</p></div> +<div class="paragraph"><p>Some functionality requires that Autoconf 2.59 or later be +installed, in order to compile Erlang/OTP. Erlang/OTP may +have further requirements depending on your needs.</p></div> +<div class="paragraph"><p>Some packages may require additional libraries.</p></div> +<div class="sect3"> +<h4 id="_linux">Linux</h4> +<div class="paragraph"><p>The commands to install packages vary between distributions:</p></div> +<div class="listingblock"> +<div class="title">Arch Linux</div> +<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>$ pacman -S erlang git make</tt></pre></div></div> +</div> +<div class="sect3"> +<h4 id="_freebsd">FreeBSD</h4> +<div class="paragraph"><p>FreeBSD comes with binary and source packages:</p></div> +<div class="listingblock"> +<div class="title">Install binary packages</div> +<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>$ pkg install erlang git gmake</tt></pre></div></div> +<div class="paragraph"><p>On FreeBSD the <code>make</code> command is BSD Make. Use <code>gmake</code> instead.</p></div> +</div> +<div class="sect3"> +<h4 id="_os_x_and_macos">OS X and macOS</h4> +<div class="paragraph"><p>While Apple distributes their own GNU Make, their version is +very old and plagued with numerous bugs. It is recommended +to install a more recent version from either Homebrew or +MacPorts:</p></div> +<div class="listingblock"> +<div class="title">Homebrew</div> +<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>$ brew install erlang git homebrew/dupes/make</tt></pre></div></div> +<div class="paragraph"><p>Homebrew installs GNU Make as <code>gmake</code>. The <code>make</code> command +is the one provided by Apple.</p></div> +<div class="listingblock"> +<div class="title">MacPorts</div> +<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>$ sudo port install erlang git gmake</tt></pre></div></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_on_windows">On Windows</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk can be used on Windows inside an MSYS2 environment. +Cygwin, MSYS (the original) and native Windows (both Batch +and PowerShell) are currently not supported.</p></div> +<div class="admonitionblock"> +<table><tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content">Erlang.mk expects Unix line breaks in most of the files +(LF instead of CRLF). Make sure to configure your text editor +adequately.</td> +</tr></table> +</div> +<div class="paragraph"><p>The rest of this section details how to setup Erlang/OTP and +MSYS2 in order to use Erlang.mk.</p></div> +<div class="sect3"> +<h4 id="_installing_erlang_otp">Installing Erlang/OTP</h4> +<div class="paragraph"><p>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 <a href="http://www.erlang.org/download.html">official download page</a>. +It is recommended that you use the 64-bit installer unless +technically impossible. Please follow the instructions from +the installer to complete the installation.</p></div> +<div class="paragraph"><p>The OTP team also provides a short guide to +<a href="http://www.erlang.org/download.html">installing Erlang/OTP on Windows</a> +if you need additional references.</p></div> +<div class="paragraph"><p>You can install Erlang/OTP silently using the <code>/S</code> switch +on the command line:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>C:\Users\essen\Downloads> otp_win64_18.0.exe /S</code></pre> +</div></div> +</div> +<div class="sect3"> +<h4 id="_installing_msys2">Installing MSYS2</h4> +<div class="paragraph"><p>The only supported environment on Windows is MSYS2. MSYS2 is +a lightweight Unix-like environment for Windows that comes +with the Arch Linux package manager, <code>pacman</code>.</p></div> +<div class="paragraph"><p>The MSYS2 project provides a <a href="http://msys2.github.io">one click installer</a> +and instructions to set things up post-installation.</p></div> +<div class="paragraph"><p>It is currently not possible to use the installer silently. +Thankfully, the MSYS2 project provides an archive that can +be used in lieu of the installer. The archive however requires +<em>7zip</em> to decompress it.</p></div> +<div class="paragraph"><p>First, download the +<a href="http://sourceforge.net/projects/msys2/files/Base/x86_64/msys2-base-x86_64-20150512.tar.xz/download">MSYS2 base archive</a> +and extract it under <em>C:\</em>. Assuming you downloaded the +archive as <em>msys2.tar.xz</em> and put it in <em>C:\</em>, you can +use the following commands to extract it:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>C:\> 7z x msys2.tar.xz +C:\> 7z x msys2.tar > NUL</code></pre> +</div></div> +<div class="paragraph"><p>Then you can run the two commands needed to perform the +post-installation setup:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>C:\> C:\msys64\usr\bin\bash -lc "pacman --needed --noconfirm -Sy bash pacman pacman-mirrors msys2-runtime" +C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -Syu"</code></pre> +</div></div> +</div> +<div class="sect3"> +<h4 id="_installing_the_required_msys2_packages">Installing the required MSYS2 packages</h4> +<div class="paragraph"><p>After following these instructions, you can install GNU Make, +Git and any other required softwares. From an MSYS2 shell, +you can call <code>pacman</code> directly:</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>$ pacman -S git make</tt></pre></div></div> +<div class="paragraph"><p>You can use <code>pacman -Ss</code> to search packages. For example, +to find all packages related to GCC:</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>$ pacman -Ss gcc</tt></pre></div></div> +<div class="paragraph"><p>If you are going to compile C/C++ code, you will need to +install this package, as Erlang.mk cannot use the normal +"gcc" package:</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>$ pacman -S mingw-w<span style="color: #993399">64</span>-x86_64-gcc</tt></pre></div></div> +<div class="paragraph"><p>You can also run commands under the MSYS2 environment from +the Windows command line or batch files. This command will +install GNU Make and Git:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -S git make"</code></pre> +</div></div> +<div class="paragraph"><p>You can use similar <code>bash</code> commands if you need to run programs +inside the MSYS2 environment from a batch file.</p></div> +</div> +<div class="sect3"> +<h4 id="_gotchas">Gotchas</h4> +<div class="paragraph"><p>While most of the basic functionality will just work, there are +still some issues. Erlang.mk needs to be fixed to pass the +right paths when running Erlang scripts. We are working on it. +Erlang.mk is fully tested on both Linux and Windows, but is +lacking tests in the areas not yet covered by this guide, +so expect bugs to be fixed as more tests are added.</p></div> +</div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/kerl.asciidoc b/docs/en/erlang.mk/1/guide/kerl.asciidoc new file mode 100644 index 00000000..c557d432 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/kerl.asciidoc @@ -0,0 +1,76 @@ +[[kerl]] +== OTP version management + +Erlang.mk comes with integrated support for +https://github.com/kerl/kerl[Kerl], a shell script that +automates the downloading, building and installing of +Erlang/OTP. It can be used to easily build a specific +Erlang/OTP version (with or without custom build options) +or maintain different versions side by side. + +=== Erlang versions + +Erlang.mk uses the Git tags from Erlang/OTP to identify +OTP versions. The most recent tag at the time of writing +is `OTP-20.0.4`, which is a patch release of `OTP-20.0`. +A patch release is a non-official release containing a +few fixes on top of the official release. + +Older versions used a slightly different versioning scheme +and tag format, for example: `OTP_R16B03`. Beware though, +there also was an `OTP_R16B03-1` release that fixed a +critical issue in the initial release. + +The README file for all official Erlang/OTP releases can +be found on http://www.erlang.org/downloads[erlang.org]. +To obtain information about patch releases when they are +released you need to be subscribed to the +http://erlang.org/mailman/listinfo/erlang-questions[erlang-questions mailing list]. + +[[otp_version_pinning]] +=== OTP version pinning + +Erlang.mk can use a specific version of Erlang/OTP when +interacting with your project. This can be very useful +when you are working with a team because you can define +the version you need in the Makefile and Erlang.mk will +ensure this version is used by everyone in your team. + +To pin the version all you need to do is to set the +`ERLANG_OTP` variable in your Makefile before including +Erlang.mk. For example, to use `OTP-20.0.4`: + +[source,make] +---- +ERLANG_OTP = OTP-20.0.4 + +include erlang.mk +---- + +The next time you run `make` Erlang.mk will build and +use the version you configured. + +Note that there has been reports that this functionality +is not compatible with the `.ONESHELL` feature from +GNU Make. + +=== Continuous integration + +Erlang.mk can automatically test your project against +many different Erlang/OTP versions. This functionality +is documented in the xref:ci[Continuous integration] chapter. + +=== Configuring Kerl + +All of the Kerl variables can be configured directly in the +Makefile. All you need to do is to export them. For example, +to change the installation directory for the Erlang/OTP +versions managed by Kerl, you could add the following to +your Makefile: + +[source,make] +export KERL_INSTALL_DIR = $(CURDIR)/erlang + +When configuring paths like this, always make sure to provide +an absolute path in the value. Erlang.mk will NOT expand them +automatically for you. diff --git a/docs/en/erlang.mk/1/guide/kerl/index.html b/docs/en/erlang.mk/1/guide/kerl/index.html new file mode 100644 index 00000000..d5474929 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/kerl/index.html @@ -0,0 +1,233 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <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.26" /> + + <title>Nine Nines: OTP version management</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>OTP version management</span></h1> + +<div class="paragraph"><p>Erlang.mk comes with integrated support for +<a href="https://github.com/kerl/kerl">Kerl</a>, a shell script that +automates the downloading, building and installing of +Erlang/OTP. It can be used to easily build a specific +Erlang/OTP version (with or without custom build options) +or maintain different versions side by side.</p></div> +<div class="sect1"> +<h2 id="_erlang_versions">Erlang versions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk uses the Git tags from Erlang/OTP to identify +OTP versions. The most recent tag at the time of writing +is <code>OTP-20.0.4</code>, which is a patch release of <code>OTP-20.0</code>. +A patch release is a non-official release containing a +few fixes on top of the official release.</p></div> +<div class="paragraph"><p>Older versions used a slightly different versioning scheme +and tag format, for example: <code>OTP_R16B03</code>. Beware though, +there also was an <code>OTP_R16B03-1</code> release that fixed a +critical issue in the initial release.</p></div> +<div class="paragraph"><p>The README file for all official Erlang/OTP releases can +be found on <a href="http://www.erlang.org/downloads">erlang.org</a>. +To obtain information about patch releases when they are +released you need to be subscribed to the +<a href="http://erlang.org/mailman/listinfo/erlang-questions">erlang-questions mailing list</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="otp_version_pinning">OTP version pinning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk can use a specific version of Erlang/OTP when +interacting with your project. This can be very useful +when you are working with a team because you can define +the version you need in the Makefile and Erlang.mk will +ensure this version is used by everyone in your team.</p></div> +<div class="paragraph"><p>To pin the version all you need to do is to set the +<code>ERLANG_OTP</code> variable in your Makefile before including +Erlang.mk. For example, to use <code>OTP-20.0.4</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><span style="color: #009900">ERLANG_OTP =</span> OTP-20.0.4 + +include erlang.mk</tt></pre></div></div> +<div class="paragraph"><p>The next time you run <code>make</code> Erlang.mk will build and +use the version you configured.</p></div> +<div class="paragraph"><p>Note that there has been reports that this functionality +is not compatible with the <code>.ONESHELL</code> feature from +GNU Make.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_continuous_integration">Continuous integration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk can automatically test your project against +many different Erlang/OTP versions. This functionality +is documented in the <a href="../ci">Continuous integration</a> chapter.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuring_kerl">Configuring Kerl</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All of the Kerl variables can be configured directly in the +Makefile. All you need to do is to export them. For example, +to change the installation directory for the Erlang/OTP +versions managed by Kerl, you could add the following to +your Makefile:</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="font-weight: bold"><span style="color: #0000FF">export</span></span> KERL_INSTALL_DIR <span style="color: #990000">=</span> <span style="color: #009900">$(CURDIR)</span>/erlang</tt></pre></div></div> +<div class="paragraph"><p>When configuring paths like this, always make sure to provide +an absolute path in the value. Erlang.mk will NOT expand them +automatically for you.</p></div> +</div> +</div> + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/escripts/"> + Escripts + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/compat/"> + Compatibility with other build tools + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Erlang.mk + 1 + + User Guide +</h3> + +<ul> + + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/erlang.mk/1/guide">1</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/erlang.mk/1/guide/limitations/index.html b/docs/en/erlang.mk/1/guide/limitations/index.html index abf19700..48561e8f 100644 --- a/docs/en/erlang.mk/1/guide/limitations/index.html +++ b/docs/en/erlang.mk/1/guide/limitations/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: Limitations</title> @@ -67,55 +67,58 @@ <h1 class="lined-header"><span>Limitations</span></h1> -<div class="paragraph"><p>No software is perfect.</p></div>
-<div class="paragraph"><p>It’s very important, when evaluating and when using a tool,
-to understand its limitations, so as to avoid making mistakes
-and wasting valuable time.</p></div>
-<div class="paragraph"><p>This chapter lists all known limitations of Erlang.mk.</p></div>
-<div class="sect1">
-<h2 id="_erlang_must_be_available">Erlang must be available</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Currently Erlang.mk requires you to install Erlang beforehand.
-Installing Erlang is not always easy, particularly if you need
-a specific version of Erlang for a specific project.</p></div>
-<div class="paragraph"><p>In addition, the Erlang being used must be in your <code>$PATH</code>
-before you use Erlang.mk.</p></div>
-<div class="paragraph"><p>In the future we envision, Erlang.mk could manage the Erlang
-version you need to use a project. Erlang.mk already does this
-for running tests when using <code>make ci</code>, so doing this during
-development is just a step away.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_spaces_in_path">Spaces in path</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk will currently not work properly if the path to the
-project contains spaces. To check if that is the case, use the
-command <code>pwd</code>.</p></div>
-<div class="paragraph"><p>This issue is due to how Makefiles work. There might be ways
-to solve it, we have not given up on it, but it’s very low
-priority considering how simple the workaround is.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependency_tracking_and_modification_times">Dependency tracking and modification times</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang source files that depend on other files will have their
-modification time updated when they need to be recompiled due
-to a dependency having changed. This could cause some editors to
-think the file changed when it didn’t.</p></div>
-<div class="paragraph"><p>Erlang.mk must use this method in order to be able to compile
-files in one <code>erlc</code> invocation. The benefits greatly outweigh
-the issue in this case and so there are currently no plans to
-fix this behavior.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>No software is perfect.</p></div> +<div class="paragraph"><p>It’s very important, when evaluating and when using a tool, +to understand its limitations, so as to avoid making mistakes +and wasting valuable time.</p></div> +<div class="paragraph"><p>This chapter lists all known limitations of Erlang.mk.</p></div> +<div class="sect1"> +<h2 id="_erlang_must_be_available">Erlang must be available</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Currently Erlang.mk requires you to install Erlang beforehand. +Installing Erlang is not always easy, particularly if you need +a specific version of Erlang for a specific project.</p></div> +<div class="paragraph"><p>In addition, the Erlang being used must be in your <code>$PATH</code> +before you use Erlang.mk.</p></div> +<div class="paragraph"><p>In the future we envision, Erlang.mk could manage the Erlang +version you need to use a project. Erlang.mk already does this +for running tests when using <code>make ci</code>, so doing this during +development is just a step away.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_spaces_in_path">Spaces in path</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk will currently not work properly if the path to the +project contains spaces. To check if that is the case, use the +command <code>pwd</code>.</p></div> +<div class="paragraph"><p>This issue is due to how Makefiles work. There might be ways +to solve it, we have not given up on it, but it’s very low +priority considering how simple the workaround is.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependency_tracking_and_modification_times">Dependency tracking and modification times</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang source files that depend on other files will have their +modification time updated when they need to be recompiled due +to a dependency having changed. This could cause some editors to +think the file changed when it didn’t.</p></div> +<div class="paragraph"><p>Erlang.mk must use this method in order to be able to compile +files in one <code>erlc</code> invocation. The benefits greatly outweigh +the issue in this case and so there are currently no plans to +fix this behavior.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/overview/index.html b/docs/en/erlang.mk/1/guide/overview/index.html index 5c072e64..2a6cbf1f 100644 --- a/docs/en/erlang.mk/1/guide/overview/index.html +++ b/docs/en/erlang.mk/1/guide/overview/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: Overview</title> @@ -67,100 +67,103 @@ <h1 class="lined-header"><span>Overview</span></h1> -<div class="paragraph"><p>Now that you know how to get started, let’s take a look at
-what Erlang.mk can do for you.</p></div>
-<div class="sect1">
-<h2 id="_building_your_project">Building your project</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk is first and foremost a build tool. It is especially
-tailored for Erlang developers and follows widely accepted
-practices in the Erlang community.</p></div>
-<div class="paragraph"><p>Erlang.mk will happily build all <a href="../building">Erlang-specific files</a>
-you throw at it. Other kinds of files too, like C or C++ code
-when you are working on <a href="../ports">a NIF or a port driver</a>.</p></div>
-<div class="paragraph"><p>Erlang.mk embraces the concept of <a href="../deps">source dependencies</a>.
-It can fetch dependency source code using a variety of mechanisms,
-including fetching from Git, Mercurial or SVN.</p></div>
-<div class="paragraph"><p>Erlang.mk will automatically <a href="../relx">generate releases</a>
-when applicable. It can also <a href="../escript">generate escripts</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exploring_the_package_index">Exploring the package index</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk comes with a <a href="../deps">built-in package index</a>.
-It is built as an extension of the dependency system and is
-meant to be used for discovery purposes.</p></div>
-<div class="paragraph"><p>No package is ever installed, they are only used as dependencies
-and are always project-specific. They can be thought of as a
-shortcut over plain dependencies.</p></div>
-<div class="paragraph"><p>You can get a list of all packages known to Erlang.mk by using
-the <code>search</code> target:</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 search</tt></pre></div></div>
-<div class="paragraph"><p>You can also use this target to search across all packages, for
-example to find all packages related to Cowboy:</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 search <span style="color: #009900">q</span><span style="color: #990000">=</span>cowboy</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_generating_documentation">Generating documentation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk supports <em>EDoc</em> and <em>Asciidoc</em>.</p></div>
-<div class="paragraph"><p><a href="../edoc">EDoc</a> generates HTML documentation directly from
-your source code.</p></div>
-<div class="paragraph"><p>While it is convenient, ask yourself: if all the documentation is
-inside the source code, why not just open the source code directly?
-That’s where <em>Asciidoc</em> comes in.</p></div>
-<div class="paragraph"><p>The <a href="../asciidoc">Asciidoc</a> plugin expects all documentation
-to be separate from source. It will generate HTML, PDF, man pages and
-more from the documentation you write in the <em>doc/src/</em> folder in
-your repository.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_running_tests">Running tests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk supports a lot of different testing and static
-analysis tools.</p></div>
-<div class="paragraph"><p>The <a href="../shell">make shell</a> command allows you
-to test your project manually. You can automate these
-unit tests with <a href="../eunit">EUnit</a> and test
-your entire system with <a href="../ct">Common Test</a>.
-<a href="../coverage">Code coverage</a> can of course
-be enabled during tests.</p></div>
-<div class="paragraph"><p>Erlang.mk comes with features to make your life easier when
-setting up and using <a href="../ci">Continuous integration</a>.</p></div>
-<div class="paragraph"><p>On the static analysis side of things, Erlang.mk comes with
-support for <a href="../dialyzer">Dialyzer</a> and <a href="#xref">Xref</a>,
-to perform success typing analysis and cross referencing
-of the code.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_need_more">Need more?</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Not convinced yet? You can read about <a href="../why">why you should use Erlang.mk</a>
-and its <a href="../history">history</a>. And if you’re still not
-convinced after that, it’s OK! The world would be boring if
-everyone agreed on everything all the time.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Now that you know how to get started, let’s take a look at +what Erlang.mk can do for you.</p></div> +<div class="sect1"> +<h2 id="_building_your_project">Building your project</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk is first and foremost a build tool. It is especially +tailored for Erlang developers and follows widely accepted +practices in the Erlang community.</p></div> +<div class="paragraph"><p>Erlang.mk will happily build all <a href="../building">Erlang-specific files</a> +you throw at it. Other kinds of files too, like C or C++ code +when you are working on <a href="../ports">a NIF or a port driver</a>.</p></div> +<div class="paragraph"><p>Erlang.mk embraces the concept of <a href="../deps">source dependencies</a>. +It can fetch dependency source code using a variety of mechanisms, +including fetching from Git, Mercurial or SVN.</p></div> +<div class="paragraph"><p>Erlang.mk will automatically <a href="../relx">generate releases</a> +when applicable. It can also <a href="../escript">generate escripts</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exploring_the_package_index">Exploring the package index</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk comes with a <a href="../deps">built-in package index</a>. +It is built as an extension of the dependency system and is +meant to be used for discovery purposes.</p></div> +<div class="paragraph"><p>No package is ever installed, they are only used as dependencies +and are always project-specific. They can be thought of as a +shortcut over plain dependencies.</p></div> +<div class="paragraph"><p>You can get a list of all packages known to Erlang.mk by using +the <code>search</code> target:</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 search</tt></pre></div></div> +<div class="paragraph"><p>You can also use this target to search across all packages, for +example to find all packages related to Cowboy:</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 search <span style="color: #009900">q</span><span style="color: #990000">=</span>cowboy</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_generating_documentation">Generating documentation</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk supports <em>EDoc</em> and <em>Asciidoc</em>.</p></div> +<div class="paragraph"><p><a href="../edoc">EDoc</a> generates HTML documentation directly from +your source code.</p></div> +<div class="paragraph"><p>While it is convenient, ask yourself: if all the documentation is +inside the source code, why not just open the source code directly? +That’s where <em>Asciidoc</em> comes in.</p></div> +<div class="paragraph"><p>The <a href="../asciidoc">Asciidoc</a> plugin expects all documentation +to be separate from source. It will generate HTML, PDF, man pages and +more from the documentation you write in the <em>doc/src/</em> folder in +your repository.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_running_tests">Running tests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk supports a lot of different testing and static +analysis tools.</p></div> +<div class="paragraph"><p>The <a href="../shell">make shell</a> command allows you +to test your project manually. You can automate these +unit tests with <a href="../eunit">EUnit</a> and test +your entire system with <a href="../ct">Common Test</a>. +<a href="../coverage">Code coverage</a> can of course +be enabled during tests.</p></div> +<div class="paragraph"><p>Erlang.mk comes with features to make your life easier when +setting up and using <a href="../ci">Continuous integration</a>.</p></div> +<div class="paragraph"><p>On the static analysis side of things, Erlang.mk comes with +support for <a href="../dialyzer">Dialyzer</a> and <a href="#xref">Xref</a>, +to perform success typing analysis and cross referencing +of the code.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_need_more">Need more?</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Not convinced yet? You can read about <a href="../why">why you should use Erlang.mk</a> +and its <a href="../history">history</a>. And if you’re still not +convinced after that, it’s OK! The world would be boring if +everyone agreed on everything all the time.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/ports.asciidoc b/docs/en/erlang.mk/1/guide/ports.asciidoc index 02c636fd..907ee366 100644 --- a/docs/en/erlang.mk/1/guide/ports.asciidoc +++ b/docs/en/erlang.mk/1/guide/ports.asciidoc @@ -98,3 +98,37 @@ The source files are automatically gathered from the contents of '$(C_SRC_DIR)'. Erlang.mk looks for '.c', '.C', '.cc' and '.cpp' source files. You can define the variable `SOURCES` to manually list the files to compile. + +=== Propagating compile and linker flags to sub-Makefiles + +In some cases it might be necessary to propagate the flags +you just defined to the sub-Makefiles of your local project. +You generally can't just export those as this could impact +the building of dependencies. + +Makefiles allow you to export variables for specific targets. +When doing this, the variables will be exported only when +this target runs, and not for other targets. It is therefore +possible to export them when building the C code without +impacting other build steps. + +By adding this to your Makefile all five variables will be +made available to sub-Makefiles when building C code: + +[source,make] +---- +app-c_src: export CC += +app-c_src: export CFLAGS += +app-c_src: export CPPFLAGS += +app-c_src: export LDFLAGS += +app-c_src: export LDLIBS += +---- + +Appending an empty string to the existing value is necessary +because Makefiles expect an assignment for target-specific +exports. Alternatively you can set a new value: + +[source,make] +---- +app-c_src: export CFLAGS = -O3 +---- diff --git a/docs/en/erlang.mk/1/guide/ports/index.html b/docs/en/erlang.mk/1/guide/ports/index.html index 619cfb40..24fa8b15 100644 --- a/docs/en/erlang.mk/1/guide/ports/index.html +++ b/docs/en/erlang.mk/1/guide/ports/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: NIFs and port drivers</title> @@ -67,148 +67,202 @@ <h1 class="lined-header"><span>NIFs and port drivers</span></h1> -<div class="paragraph"><p>Erlang.mk can not only build Erlang projects, but also the C code
-that some projects come with, like NIFs and port drivers.</p></div>
-<div class="paragraph"><p>There are two ways to build the C code: using a custom Makefile,
-or making Erlang.mk do it directly. The C code will be built
-as needed when you run <code>make</code>.</p></div>
-<div class="sect1">
-<h2 id="_c_source_code_location_and_erlang_environment">C source code location and Erlang environment</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The C source code should be located in the <em>$(C_SRC_DIR)</em> directory.
-It defaults to <em>c_src/</em>. Should you need to modify it, all you
-need to do is to set the variable in your Makefile before including
-Erlang.mk:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>When this directory exists, Erlang.mk will automatically create a
-file named <em>$(C_SRC_ENV)</em>. This file defaults to <em>$(C_SRC_DIR)/env.mk</em>.
-This can also be changed:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>It contains a few variable definitions for the environment used for the build:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>ERTS_INCLUDE_DIR</code>
-</dt>
-<dd>
-<p>
- Path to the ERTS include files (<em>erl_driver.h</em>, <em>erl_nif.h</em> and more).
-</p>
-</dd>
-<dt class="hdlist1">
-<code>ERL_INTERFACE_INCLUDE_DIR</code>
-</dt>
-<dd>
-<p>
- Path to the Erl_Interface include files (<em>ei.h</em> and related).
-</p>
-</dd>
-<dt class="hdlist1">
-<code>ERL_INTERFACE_LIB_DIR</code>
-</dt>
-<dd>
-<p>
- Path to the Erl_Interface static libraries.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_a_custom_makefile">Using a custom Makefile</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk will automatically run <code>make</code> if it detects a Makefile
-in <em>$(C_SRC_DIR)/Makefile</em>.</p></div>
-<div class="paragraph"><p>The Makefile should have at least two targets: a default target
-(which can be anything, for example <code>all</code>) which is invoked when
-building the C code, and a <code>clean</code> target invoked when cleaning
-it.</p></div>
-<div class="paragraph"><p>You can include the <em>env.mk</em> file to benefit from the Erlang
-environment detection:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_erlang_mk_directly">Using Erlang.mk directly</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You don’t need to write a Makefile to build C source code, however.
-Erlang.mk comes with rules to build both shared libraries and
-executables, using the source files it finds in <em>$(C_SRC_DIR)</em>.</p></div>
-<div class="paragraph"><p>By default, Erlang.mk will create a shared library. To change
-this and create an executable instead, put this in your Makefile
-before including Erlang.mk:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The generated file name varies depending on the type of project
-you have (shared library or executable) and on the platform you
-build the project on.</p></div>
-<div class="paragraph"><p>For shared libraries, the generated file name will be
-<em>$(C_SRC_OUTPUT)$(C_SRC_SHARED_EXTENSION)</em>, with the default
-being <em>$(CURDIR)/priv/$(PROJECT)</em> followed by the extension:
-<code>.dll</code> on Windows, <code>.so</code> everywhere else.</p></div>
-<div class="paragraph"><p>For executables, the generated file name is
-<em>$(C_SRC_OUTPUT)$(C_SRC_EXECUTABLE_EXTENSION)</em>, with the same
-default except for the extension: <code>.exe</code> on Windows, and otherwise
-nothing.</p></div>
-<div class="paragraph"><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>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>CC</code>
-</dt>
-<dd>
-<p>
- The compiler to be used.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>CFLAGS</code>
-</dt>
-<dd>
-<p>
- C compiler flags.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>CXXFLAGS</code>
-</dt>
-<dd>
-<p>
- C++ compiler flags.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>LDFLAGS</code>
-</dt>
-<dd>
-<p>
- Linker flags.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>LDLIBS</code>
-</dt>
-<dd>
-<p>
- Libraries to link against.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The source files are automatically gathered from the contents
-of <em>$(C_SRC_DIR)</em>. Erlang.mk looks for <em>.c</em>, <em>.C</em>, <em>.cc</em> and <em>.cpp</em>
-source files. You can define the variable <code>SOURCES</code> to manually
-list the files to compile.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk can not only build Erlang projects, but also the C code +that some projects come with, like NIFs and port drivers.</p></div> +<div class="paragraph"><p>There are two ways to build the C code: using a custom Makefile, +or making Erlang.mk do it directly. The C code will be built +as needed when you run <code>make</code>.</p></div> +<div class="sect1"> +<h2 id="_c_source_code_location_and_erlang_environment">C source code location and Erlang environment</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The C source code should be located in the <em>$(C_SRC_DIR)</em> directory. +It defaults to <em>c_src/</em>. Should you need to modify it, all you +need to do is to set the variable in your Makefile before 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">C_SRC_DIR =</span> <span style="color: #009900">$(CURDIR)</span>/my_nif_source</tt></pre></div></div> +<div class="paragraph"><p>When this directory exists, Erlang.mk will automatically create a +file named <em>$(C_SRC_ENV)</em>. This file defaults to <em>$(C_SRC_DIR)/env.mk</em>. +This can also be changed:</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">C_SRC_ENV =</span> <span style="color: #009900">$(C_SRC_DIR)</span>/erlang_env.mk</tt></pre></div></div> +<div class="paragraph"><p>It contains a few variable definitions for the environment used for the build:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +<code>ERTS_INCLUDE_DIR</code> +</dt> +<dd> +<p> + Path to the ERTS include files (<em>erl_driver.h</em>, <em>erl_nif.h</em> and more). +</p> +</dd> +<dt class="hdlist1"> +<code>ERL_INTERFACE_INCLUDE_DIR</code> +</dt> +<dd> +<p> + Path to the Erl_Interface include files (<em>ei.h</em> and related). +</p> +</dd> +<dt class="hdlist1"> +<code>ERL_INTERFACE_LIB_DIR</code> +</dt> +<dd> +<p> + Path to the Erl_Interface static libraries. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_a_custom_makefile">Using a custom Makefile</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk will automatically run <code>make</code> if it detects a Makefile +in <em>$(C_SRC_DIR)/Makefile</em>.</p></div> +<div class="paragraph"><p>The Makefile should have at least two targets: a default target +(which can be anything, for example <code>all</code>) which is invoked when +building the C code, and a <code>clean</code> target invoked when cleaning +it.</p></div> +<div class="paragraph"><p>You can include the <em>env.mk</em> file to benefit from the Erlang +environment detection:</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 env.mk</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_erlang_mk_directly">Using Erlang.mk directly</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You don’t need to write a Makefile to build C source code, however. +Erlang.mk comes with rules to build both shared libraries and +executables, using the source files it finds in <em>$(C_SRC_DIR)</em>.</p></div> +<div class="paragraph"><p>By default, Erlang.mk will create a shared library. To change +this and create an executable instead, put this in your Makefile +before 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">C_SRC_TYPE =</span> executable</tt></pre></div></div> +<div class="paragraph"><p>The generated file name varies depending on the type of project +you have (shared library or executable) and on the platform you +build the project on.</p></div> +<div class="paragraph"><p>For shared libraries, the generated file name will be +<em>$(C_SRC_OUTPUT)$(C_SRC_SHARED_EXTENSION)</em>, with the default +being <em>$(CURDIR)/priv/$(PROJECT)</em> followed by the extension: +<code>.dll</code> on Windows, <code>.so</code> everywhere else.</p></div> +<div class="paragraph"><p>For executables, the generated file name is +<em>$(C_SRC_OUTPUT)$(C_SRC_EXECUTABLE_EXTENSION)</em>, with the same +default except for the extension: <code>.exe</code> on Windows, and otherwise +nothing.</p></div> +<div class="paragraph"><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> +<div class="dlist"><dl> +<dt class="hdlist1"> +<code>CC</code> +</dt> +<dd> +<p> + The compiler to be used. +</p> +</dd> +<dt class="hdlist1"> +<code>CFLAGS</code> +</dt> +<dd> +<p> + C compiler flags. +</p> +</dd> +<dt class="hdlist1"> +<code>CXXFLAGS</code> +</dt> +<dd> +<p> + C++ compiler flags. +</p> +</dd> +<dt class="hdlist1"> +<code>LDFLAGS</code> +</dt> +<dd> +<p> + Linker flags. +</p> +</dd> +<dt class="hdlist1"> +<code>LDLIBS</code> +</dt> +<dd> +<p> + Libraries to link against. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>The source files are automatically gathered from the contents +of <em>$(C_SRC_DIR)</em>. Erlang.mk looks for <em>.c</em>, <em>.C</em>, <em>.cc</em> and <em>.cpp</em> +source files. You can define the variable <code>SOURCES</code> to manually +list the files to compile.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_propagating_compile_and_linker_flags_to_sub_makefiles">Propagating compile and linker flags to sub-Makefiles</h2> +<div class="sectionbody"> +<div class="paragraph"><p>In some cases it might be necessary to propagate the flags +you just defined to the sub-Makefiles of your local project. +You generally can’t just export those as this could impact +the building of dependencies.</p></div> +<div class="paragraph"><p>Makefiles allow you to export variables for specific targets. +When doing this, the variables will be exported only when +this target runs, and not for other targets. It is therefore +possible to export them when building the C code without +impacting other build steps.</p></div> +<div class="paragraph"><p>By adding this to your Makefile all five variables will be +made available to sub-Makefiles when building C 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><span style="color: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> CC <span style="color: #990000">+=</span> +<span style="color: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> CFLAGS <span style="color: #990000">+=</span> +<span style="color: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> CPPFLAGS <span style="color: #990000">+=</span> +<span style="color: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> LDFLAGS <span style="color: #990000">+=</span> +<span style="color: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> LDLIBS <span style="color: #990000">+=</span></tt></pre></div></div> +<div class="paragraph"><p>Appending an empty string to the existing value is necessary +because Makefiles expect an assignment for target-specific +exports. Alternatively you can set a new value:</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: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> CFLAGS <span style="color: #990000">=</span> -O<span style="color: #993399">3</span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/releases/index.html b/docs/en/erlang.mk/1/guide/releases/index.html index e3c46057..606c47e3 100644 --- a/docs/en/erlang.mk/1/guide/releases/index.html +++ b/docs/en/erlang.mk/1/guide/releases/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: Releases</title> @@ -67,199 +67,226 @@ <h1 class="lined-header"><span>Releases</span></h1> -<div class="paragraph"><p>Erlang.mk relies on <em>Relx</em> for generating releases. This
-chapter covers the Erlang.mk-specific bits. Consult the
-<a href="https://erlware.github.io/relx/">Relx website</a> for more information.</p></div>
-<div class="sect1">
-<h2 id="_setup">Setup</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk will create a release if it detects a Relx configuration
-file in the <em>$(RELX_CONFIG)</em> location. This defaults to
-<em>$(CURDIR)/relx.config</em>. You can override it by defining
-the variable before including Erlang.mk:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Relx does not need to be installed. Erlang.mk will download
-and build it automatically.</p></div>
-<div class="paragraph"><p>The Relx executable will be saved in the <em>$(RELX)</em> file. This
-location defaults to <em>$(CURDIR)/relx</em> and can be overriden.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can specify additional Relx options using the <code>RELX_OPTS</code>
-variable. For example, to enable <code>dev_mode</code>:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><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>RELX_OUTPUT_DIR</code>. It defaults to the <em>_rel</em>
-directory. You can also override it:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_generating_the_release">Generating the release</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Now that you’re all set, all you need to do is generate the
-release. As mentioned before, Erlang.mk will automatically
-generate it when it detects the <em>$(RELX_CONFIG)</em> file. This
-means the following command will also build the release:</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>If you need to generate the release, and only the release,
-the <code>rel</code> target can be used:</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>Erlang.mk always generates a tarball alongside the release,
-which can be directly uploaded to a server. The tarball is
-located at <code>$(RELX_OUTPUT_DIR)/<name>/<name>-<vsn>.tar.gz</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_running_the_release">Running the release</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk provides a convenience function for running the
-release with one simple 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 run</tt></pre></div></div>
-<div class="paragraph"><p>This command will also build the project and generate the
-release if they weren’t already. It starts the release in
-<em>console mode</em>, meaning you will also have a shell ready to
-use to check things as needed.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_upgrading_a_release">Upgrading a release</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk provides a <code>relup</code> target for generating release
-upgrades. Release upgrades allow updating the code and the
-state of a running release without restarting it.</p></div>
-<div class="paragraph"><p>Once your changes are done, you need to update the version
-of the application(s) that will be updated. You also need
-to update the version of the release.</p></div>
-<div class="paragraph"><p>For each application that needs to be updated, an
-<a href="http://erlang.org/doc/man/appup.html">appup file</a>
-must be written. Refer to the Erlang/OTP documentation
-for more details.</p></div>
-<div class="paragraph"><p>For the purpose of this section, assume the initial release
-version was <code>1</code>, and the new version is <code>2</code>. The name of the
-release will be <code>example</code>.</p></div>
-<div class="paragraph"><p>Once all this is done, you can build the tarball for the
-release upgrade:</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 relup</tt></pre></div></div>
-<div class="paragraph"><p>This will create an archive at the root directory of the
-release, <code>$RELX_OUTPUT_DIR/example/example-2.tar.gz</code>.</p></div>
-<div class="paragraph"><p>Move the archive to the correct location on the running
-node. From the release’s root directory:</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>$ mkdir releases<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">/</span>
-$ mv path/to/example-<span style="color: #993399">2</span><span style="color: #990000">.</span>tar<span style="color: #990000">.</span>gz releases<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">/</span></tt></pre></div></div>
-<div class="paragraph"><p>Finally, upgrade the release:</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>$ bin/example_release upgrade <span style="color: #FF0000">"2/example_release"</span></tt></pre></div></div>
-<div class="paragraph"><p>Or on Windows:</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>$ bin/example_release<span style="color: #990000">.</span>cmd upgrade <span style="color: #FF0000">"2/example_release"</span></tt></pre></div></div>
-<div class="paragraph"><p>Your release was upgraded!</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_relx_semver_value">Getting Relx semver value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>There is a <strong>workaround</strong> to get the semver value which is
-generated by Relx based on VCS history.</p></div>
-<div class="paragraph"><p>Create a file <em>rel/version</em> with only one line inside:</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: #FF6600">release_version</span> }}</tt></pre></div></div>
-<div class="paragraph"><p>Add/Update the <code>overlay</code> section of your <code>relx.config</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>{<span style="color: #FF6600">overlay</span>, [
- {<span style="color: #FF6600">template</span>, <span style="color: #FF0000">"rel/version"</span>, <span style="color: #FF0000">"version"</span>}
-]}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>When you run <code>make rel</code> it creates the file <em>$(RELX_OUTPUT_DIR)/example/version</em>
-which contains the version value generated by Relx.</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>$ cat _rel/app/release
-<span style="color: #993399">1.0</span><span style="color: #990000">.</span><span style="color: #993399">0</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0</tt></pre></div></div>
-<div class="paragraph"><p>In your <code>Makefile</code> you can use this simple snippet to get the version,
-but please keep in mind that this should depend on the <code>rel</code> target:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>For example:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Would output:</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 myrecipe
-<span style="color: #990000">...</span>
-<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span>
-<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span>
- /home/username/example/apps
- /home/username/example/deps
- /usr/lib/erlang/lib
- /home/username/example<span style="color: #990000">/</span>_rel
-<span style="color: #990000">===></span> Resolved example-<span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0
-<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang
-<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span>
-<span style="color: #990000">===></span> tarball /home/username/example<span style="color: #990000">/</span>_rel/example/example-<span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0<span style="color: #990000">.</span>tar<span style="color: #990000">.</span>gz successfully created<span style="color: #990000">!</span>
-echo APP_VERSION <span style="color: #990000">=</span> <span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0
-APP_VERSION <span style="color: #990000">=</span> <span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0</tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk relies on <em>Relx</em> for generating releases. This +chapter covers the Erlang.mk-specific bits. Consult the +<a href="https://erlware.github.io/relx/">Relx website</a> for more information.</p></div> +<div class="sect1"> +<h2 id="_setup">Setup</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk will create a release if it detects a Relx configuration +file in the <em>$(RELX_CONFIG)</em> location. This defaults to +<em>$(CURDIR)/relx.config</em>. You can override it by defining +the variable before 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">RELX_CONFIG =</span> <span style="color: #009900">$(CURDIR)</span>/webchat.config</tt></pre></div></div> +<div class="paragraph"><p>Relx does not need to be installed. Erlang.mk will download +and build it automatically.</p></div> +<div class="paragraph"><p>The Relx executable will be saved in the <em>$(RELX)</em> file. This +location defaults to <em>$(CURDIR)/relx</em> and can be overriden.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can specify additional Relx options using the <code>RELX_OPTS</code> +variable. For example, to enable <code>dev_mode</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><span style="color: #009900">RELX_OPTS =</span> -d <span style="font-weight: bold"><span style="color: #0000FF">true</span></span></tt></pre></div></div> +<div class="paragraph"><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>RELX_OUTPUT_DIR</code>. It defaults to the <em>_rel</em> +directory. You can also override it:</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">RELX_OUTPUT_DIR =</span> /path/to/staging/directory</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_generating_the_release">Generating the release</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Now that you’re all set, all you need to do is generate the +release. As mentioned before, Erlang.mk will automatically +generate it when it detects the <em>$(RELX_CONFIG)</em> file. This +means the following command will also build the release:</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>If you need to generate the release, and only the release, +the <code>rel</code> target can be used:</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>Erlang.mk always generates a tarball alongside the release, +which can be directly uploaded to a server. The tarball is +located at <code>$(RELX_OUTPUT_DIR)/<name>/<name>-<vsn>.tar.gz</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_running_the_release">Running the release</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk provides a convenience function for running the +release with one simple 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 run</tt></pre></div></div> +<div class="paragraph"><p>This command will also build the project and generate the +release if they weren’t already. It starts the release in +<em>console mode</em>, meaning you will also have a shell ready to +use to check things as needed.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_upgrading_a_release">Upgrading a release</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk provides a <code>relup</code> target for generating release +upgrades. Release upgrades allow updating the code and the +state of a running release without restarting it.</p></div> +<div class="paragraph"><p>Once your changes are done, you need to update the version +of the application(s) that will be updated. You also need +to update the version of the release.</p></div> +<div class="paragraph"><p>For each application that needs to be updated, an +<a href="http://erlang.org/doc/man/appup.html">appup file</a> +must be written. Refer to the Erlang/OTP documentation +for more details.</p></div> +<div class="paragraph"><p>For the purpose of this section, assume the initial release +version was <code>1</code>, and the new version is <code>2</code>. The name of the +release will be <code>example</code>.</p></div> +<div class="paragraph"><p>Once all this is done, you can build the tarball for the +release upgrade:</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 relup</tt></pre></div></div> +<div class="paragraph"><p>This will create an archive at the root directory of the +release, <code>$RELX_OUTPUT_DIR/example/example-2.tar.gz</code>.</p></div> +<div class="paragraph"><p>Move the archive to the correct location on the running +node. From the release’s root directory:</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>$ mkdir releases<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">/</span> +$ mv path/to/example-<span style="color: #993399">2</span><span style="color: #990000">.</span>tar<span style="color: #990000">.</span>gz releases<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">/</span></tt></pre></div></div> +<div class="paragraph"><p>Finally, upgrade the release:</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>$ bin/example_release upgrade <span style="color: #FF0000">"2/example_release"</span></tt></pre></div></div> +<div class="paragraph"><p>Or on Windows:</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>$ bin/example_release<span style="color: #990000">.</span>cmd upgrade <span style="color: #FF0000">"2/example_release"</span></tt></pre></div></div> +<div class="paragraph"><p>Your release was upgraded!</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_relx_semver_value">Getting Relx semver value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>There is a <strong>workaround</strong> to get the semver value which is +generated by Relx based on VCS history.</p></div> +<div class="paragraph"><p>Create a file <em>rel/version</em> with only one line inside:</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: #FF6600">release_version</span> }}</tt></pre></div></div> +<div class="paragraph"><p>Add/Update the <code>overlay</code> section of your <code>relx.config</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>{<span style="color: #FF6600">overlay</span>, [ + {<span style="color: #FF6600">template</span>, <span style="color: #FF0000">"rel/version"</span>, <span style="color: #FF0000">"version"</span>} +]}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>When you run <code>make rel</code> it creates the file <em>$(RELX_OUTPUT_DIR)/example/version</em> +which contains the version value generated by Relx.</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>$ cat _rel/app/release +<span style="color: #993399">1.0</span><span style="color: #990000">.</span><span style="color: #993399">0</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0</tt></pre></div></div> +<div class="paragraph"><p>In your <code>Makefile</code> you can use this simple snippet to get the version, +but please keep in mind that this should depend on the <code>rel</code> target:</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">$(</span>shell cat <span style="color: #009900">$(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)</span></tt></pre></div></div> +<div class="paragraph"><p>For 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>include erlang.mk + +<span style="color: #009900">APP_VERSION =</span> <span style="color: #009900">$(</span>shell cat <span style="color: #009900">$(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)</span> +<span style="color: #990000">myrecipe:</span> all + echo APP_VERSION <span style="color: #990000">=</span> <span style="color: #009900">$(APP_VERSION)</span></tt></pre></div></div> +<div class="paragraph"><p>Would output:</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 myrecipe +<span style="color: #990000">...</span> +<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span> +<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span> + /home/username/example/apps + /home/username/example/deps + /usr/lib/erlang/lib + /home/username/example<span style="color: #990000">/</span>_rel +<span style="color: #990000">===></span> Resolved example-<span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0 +<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang +<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span> +<span style="color: #990000">===></span> tarball /home/username/example<span style="color: #990000">/</span>_rel/example/example-<span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0<span style="color: #990000">.</span>tar<span style="color: #990000">.</span>gz successfully created<span style="color: #990000">!</span> +echo APP_VERSION <span style="color: #990000">=</span> <span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0 +APP_VERSION <span style="color: #990000">=</span> <span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0</tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/sfx/index.html b/docs/en/erlang.mk/1/guide/sfx/index.html index 38a1f25b..a97c253f 100644 --- a/docs/en/erlang.mk/1/guide/sfx/index.html +++ b/docs/en/erlang.mk/1/guide/sfx/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: Self-extracting releases</title> @@ -67,61 +67,64 @@ <h1 class="lined-header"><span>Self-extracting releases</span></h1> -<div class="paragraph"><p>Erlang.mk allows you to package <a href="../relx">Relx releases</a> as
-self-extracting archives. These archives contain all the
-files in the release and come in the form of a script that
-will extract and run the release automatically.</p></div>
-<div class="paragraph"><p>This allows you to package the release as a single file
-that can then be executed.</p></div>
-<div class="paragraph"><p>This feature is currently experimental. Feedback is much
-appreciated.</p></div>
-<div class="sect1">
-<h2 id="_generating_the_self_extracting_archive">Generating the self-extracting archive</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To generate a self-extracting release, all you need to do
-is pass the <code>SFX=1</code> variable to Make when you build the
-release:</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 <span style="color: #009900">SFX</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div>
-<div class="paragraph"><p>This will create a self-extracting archive in
-<code>$RELX_OUTPUT_DIR/<name>.run</code>. For example if the release
-is named <code>hello_world</code> and <code>$RELX_OUTPUT_DIR</code> is the default,
-the file will be located at <code>_rel/hello_world.run</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_running_the_release">Running the release</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Simply execute the script to get started:</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: #990000">./</span>_rel/hello_world<span style="color: #990000">.</span>run
-Exec<span style="color: #990000">:</span> /tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta/erts-<span style="color: #993399">8.1</span>/bin/erlexec <span style="color: #990000">...</span>
-Root<span style="color: #990000">:</span> /tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta
-/tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta
-Erlang/OTP <span style="color: #993399">19</span> <span style="color: #990000">[</span>erts-<span style="color: #993399">8.1</span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">source</span></span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="color: #993399">64</span>-bit<span style="color: #990000">]</span> <span style="color: #990000">[</span>smp<span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">...</span>
-
-Eshell V8<span style="color: #990000">.</span><span style="color: #993399">1</span> <span style="color: #990000">(</span>abort with <span style="color: #990000">^</span>G<span style="color: #990000">)</span>
-<span style="color: #990000">(</span>hello_world@localhost<span style="color: #990000">)</span><span style="color: #993399">1</span><span style="color: #990000">></span></tt></pre></div></div>
-<div class="paragraph"><p>As you can see the archive is extracted to a temporary
-directory before the release can be started.</p></div>
-<div class="paragraph"><p>The self-extracting script currently only supports starting
-the release in <code>console</code> mode.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk allows you to package <a href="../relx">Relx releases</a> as +self-extracting archives. These archives contain all the +files in the release and come in the form of a script that +will extract and run the release automatically.</p></div> +<div class="paragraph"><p>This allows you to package the release as a single file +that can then be executed.</p></div> +<div class="paragraph"><p>This feature is currently experimental. Feedback is much +appreciated.</p></div> +<div class="sect1"> +<h2 id="_generating_the_self_extracting_archive">Generating the self-extracting archive</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To generate a self-extracting release, all you need to do +is pass the <code>SFX=1</code> variable to Make when you build the +release:</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 <span style="color: #009900">SFX</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div> +<div class="paragraph"><p>This will create a self-extracting archive in +<code>$RELX_OUTPUT_DIR/<name>.run</code>. For example if the release +is named <code>hello_world</code> and <code>$RELX_OUTPUT_DIR</code> is the default, +the file will be located at <code>_rel/hello_world.run</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_running_the_release">Running the release</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Simply execute the script to get started:</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: #990000">./</span>_rel/hello_world<span style="color: #990000">.</span>run +Exec<span style="color: #990000">:</span> /tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta/erts-<span style="color: #993399">8.1</span>/bin/erlexec <span style="color: #990000">...</span> +Root<span style="color: #990000">:</span> /tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta +/tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta +Erlang/OTP <span style="color: #993399">19</span> <span style="color: #990000">[</span>erts-<span style="color: #993399">8.1</span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">source</span></span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="color: #993399">64</span>-bit<span style="color: #990000">]</span> <span style="color: #990000">[</span>smp<span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">...</span> + +Eshell V8<span style="color: #990000">.</span><span style="color: #993399">1</span> <span style="color: #990000">(</span>abort with <span style="color: #990000">^</span>G<span style="color: #990000">)</span> +<span style="color: #990000">(</span>hello_world@localhost<span style="color: #990000">)</span><span style="color: #993399">1</span><span style="color: #990000">></span></tt></pre></div></div> +<div class="paragraph"><p>As you can see the archive is extracted to a temporary +directory before the release can be started.</p></div> +<div class="paragraph"><p>The self-extracting script currently only supports starting +the release in <code>console</code> mode.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/shell/index.html b/docs/en/erlang.mk/1/guide/shell/index.html index 28a13113..873e7b2f 100644 --- a/docs/en/erlang.mk/1/guide/shell/index.html +++ b/docs/en/erlang.mk/1/guide/shell/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: Erlang shell</title> @@ -67,53 +67,72 @@ <h1 class="lined-header"><span>Erlang shell</span></h1> -<div class="paragraph"><p>Erlang.mk provides a convenient target for starting a shell
-with all the paths set properly to experiment with your code.</p></div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>SHELL_DEPS</code> variable can be used to define dependencies
-that are only to be used when the <code>make shell</code> command is called.
-For example, if you want to use <em>kjell</em> as your shell:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Dependencies are downloaded and compiled the first time you
-run the <code>make shell</code> command.</p></div>
-<div class="paragraph"><p>You can customize the executable used to start the Erlang shell.
-To continue with our example, if you want to use <em>kjell</em> as your
-shell, you also need to change <code>SHELL_ERL</code> and point it to the
-<code>kjell</code> executable:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>You can specify additional options to be used when starting the
-shell using the <code>SHELL_OPTS</code> variable:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Any of the usual <code>erl</code> options can be used, including <code>-eval</code>:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To start the shell, all you need is 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 shell</tt></pre></div></div>
-<div class="paragraph"><p>The shell can be stopped as usual with a double Ctrl+C or the
-command <code>q().</code>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk provides a convenient target for starting a shell +with all the paths set properly to experiment with your code.</p></div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>SHELL_DEPS</code> variable can be used to define dependencies +that are only to be used when the <code>make shell</code> command is called. +For example, if you want to use <em>kjell</em> as your shell:</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">SHELL_DEPS =</span> kjell</tt></pre></div></div> +<div class="paragraph"><p>Dependencies are downloaded and compiled the first time you +run the <code>make shell</code> command.</p></div> +<div class="paragraph"><p>You can customize the executable used to start the Erlang shell. +To continue with our example, if you want to use <em>kjell</em> as your +shell, you also need to change <code>SHELL_ERL</code> and point it to the +<code>kjell</code> executable:</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">SHELL_ERL =</span> <span style="color: #009900">$(DEPS_DIR)</span>/kjell/bin/kjell</tt></pre></div></div> +<div class="paragraph"><p>You can specify additional options to be used when starting the +shell using the <code>SHELL_OPTS</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><span style="color: #009900">SHELL_OPTS =</span> -setcookie chocolate</tt></pre></div></div> +<div class="paragraph"><p>Any of the usual <code>erl</code> options can be used, including <code>-eval</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><span style="color: #009900">SHELL_OPTS =</span> -eval <span style="color: #FF0000">'my_app:run()'</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To start the shell, all you need is 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 shell</tt></pre></div></div> +<div class="paragraph"><p>The shell can be stopped as usual with a double Ctrl+C or the +command <code>q().</code>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/updating/index.html b/docs/en/erlang.mk/1/guide/updating/index.html index 96223e32..826e1b0d 100644 --- a/docs/en/erlang.mk/1/guide/updating/index.html +++ b/docs/en/erlang.mk/1/guide/updating/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: Updating Erlang.mk</title> @@ -67,95 +67,98 @@ <h1 class="lined-header"><span>Updating Erlang.mk</span></h1> -<div class="paragraph"><p>This chapter describes how to update the <em>erlang.mk</em> file
-in your repository.</p></div>
-<div class="sect1">
-<h2 id="_initial_bootstrap">Initial bootstrap</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The first time you use Erlang.mk, it will bootstrap itself.
-It always uses the most recent version for this, so you don’t
-have to update after creating your project.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_updating">Updating</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Later on though, updating becomes a necessity. Erlang.mk
-developers and contributors relentlessly improve the project
-and add new features; it would be a waste not to benefit
-from this.</p></div>
-<div class="paragraph"><p>That’s why updating Erlang.mk is so simple. All you need
-to do is to call <code>make erlang-mk</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 erlang-mk
-git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build
-Cloning into <span style="color: #FF0000">'.erlang.mk.build'</span><span style="color: #990000">...</span>
-remote<span style="color: #990000">:</span> Counting objects<span style="color: #990000">:</span> <span style="color: #993399">4035</span><span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-remote<span style="color: #990000">:</span> Compressing objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">12</span><span style="color: #990000">/</span><span style="color: #993399">12</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-remote<span style="color: #990000">:</span> Total <span style="color: #993399">4035</span> <span style="color: #990000">(</span>delta <span style="color: #993399">8</span><span style="color: #990000">),</span> reused <span style="color: #993399">4</span> <span style="color: #990000">(</span>delta <span style="color: #993399">4</span><span style="color: #990000">),</span> pack-reused <span style="color: #993399">4019</span>
-Receiving objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">4035</span><span style="color: #990000">/</span><span style="color: #993399">4035</span><span style="color: #990000">),</span> <span style="color: #993399">1.10</span> MiB <span style="color: #990000">|</span> <span style="color: #993399">1000.00</span> KiB/s<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-Resolving deltas<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">2442</span><span style="color: #990000">/</span><span style="color: #993399">2442</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-Checking connectivity<span style="color: #990000">...</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -f build<span style="color: #990000">.</span>config <span style="color: #990000">];</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span> cp build<span style="color: #990000">.</span>config <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span>
-cd <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build <span style="color: #990000">&&</span> make
-make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Entering directory <span style="color: #FF0000">'/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'</span>
-awk <span style="color: #FF0000">'FNR==1 && NR!=1{print ""}1'</span> core/core<span style="color: #990000">.</span>mk index<span style="color: #990000">/*.</span>mk core/index<span style="color: #990000">.</span>mk core/deps<span style="color: #990000">.</span>mk plugins/protobuffs<span style="color: #990000">.</span>mk core/erlc<span style="color: #990000">.</span>mk core/docs<span style="color: #990000">.</span>mk core/test<span style="color: #990000">.</span>mk plugins/asciidoc<span style="color: #990000">.</span>mk plugins/bootstrap<span style="color: #990000">.</span>mk plugins/c_src<span style="color: #990000">.</span>mk plugins/ci<span style="color: #990000">.</span>mk plugins/ct<span style="color: #990000">.</span>mk plugins/dialyzer<span style="color: #990000">.</span>mk plugins/edoc<span style="color: #990000">.</span>mk plugins/elvis<span style="color: #990000">.</span>mk plugins/erlydtl<span style="color: #990000">.</span>mk plugins/escript<span style="color: #990000">.</span>mk plugins/eunit<span style="color: #990000">.</span>mk plugins/relx<span style="color: #990000">.</span>mk plugins/shell<span style="color: #990000">.</span>mk plugins/triq<span style="color: #990000">.</span>mk plugins/xref<span style="color: #990000">.</span>mk plugins/cover<span style="color: #990000">.</span>mk <span style="color: #990000">\</span>
- <span style="color: #990000">|</span> sed <span style="color: #FF0000">'s/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/'</span> <span style="color: #990000">></span> erlang<span style="color: #990000">.</span>mk
-make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Leaving directory <span style="color: #FF0000">'/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'</span>
-cp <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>/erlang<span style="color: #990000">.</span>mk
-rm -rf <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build</tt></pre></div></div>
-<div class="paragraph"><p>All that’s left to do is to commit the file!</p></div>
-<div class="paragraph"><p>Yep, it’s that easy.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_customizing_the_build">Customizing the build</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk allows you to customize which components are to be included
-in the <em>erlang.mk</em> file. The <code>WITHOUT</code> variable allows you to
-remove components from the default Erlang.mk build. The <em>build.config</em>
-file lets you define exactly what goes in (including your own code!),
-and in what order.</p></div>
-<div class="paragraph"><p>The <code>WITHOUT</code> file contains the list of components to exclude from
-the build. For example, to exclude the package index and the EDoc
-plugin when bootstrapping your application:</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 <span style="color: #009900">WITHOUT</span><span style="color: #990000">=</span><span style="color: #FF0000">"index plugins/edoc"</span></tt></pre></div></div>
-<div class="paragraph"><p>The generated Erlang.mk will never include those components when
-you update it, until you change your mind and use the <code>WITHOUT</code>
-variable again when you upgrade:</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 erlang-mk <span style="color: #009900">WITHOUT</span><span style="color: #990000">=</span>index</tt></pre></div></div>
-<div class="paragraph"><p>The <em>build.config</em> file is automatically used when you bootstrap
-Erlang.mk or when you update it with <code>make erlang-mk</code>.</p></div>
-<div class="paragraph"><p>The <em>build.config</em> file contains the list of all files that will
-be built into the resulting <em>erlang.mk</em> file. You can start from
-the <a href="https://github.com/ninenines/erlang.mk/blob/master/build.config">most recent version</a>
-and customize to your needs.</p></div>
-<div class="paragraph"><p>You can also name the file differently or put it in a separate folder
-by modifying the value for <code>ERLANG_MK_BUILD_CONFIG</code>. You can also
-tell Erlang.mk to use a different temporary directory by changing
-the <code>ERLANG_MK_BUILD_DIR</code> variable.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter describes how to update the <em>erlang.mk</em> file +in your repository.</p></div> +<div class="sect1"> +<h2 id="_initial_bootstrap">Initial bootstrap</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The first time you use Erlang.mk, it will bootstrap itself. +It always uses the most recent version for this, so you don’t +have to update after creating your project.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_updating">Updating</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Later on though, updating becomes a necessity. Erlang.mk +developers and contributors relentlessly improve the project +and add new features; it would be a waste not to benefit +from this.</p></div> +<div class="paragraph"><p>That’s why updating Erlang.mk is so simple. All you need +to do is to call <code>make erlang-mk</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 erlang-mk +git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build +Cloning into <span style="color: #FF0000">'.erlang.mk.build'</span><span style="color: #990000">...</span> +remote<span style="color: #990000">:</span> Counting objects<span style="color: #990000">:</span> <span style="color: #993399">4035</span><span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +remote<span style="color: #990000">:</span> Compressing objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">12</span><span style="color: #990000">/</span><span style="color: #993399">12</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +remote<span style="color: #990000">:</span> Total <span style="color: #993399">4035</span> <span style="color: #990000">(</span>delta <span style="color: #993399">8</span><span style="color: #990000">),</span> reused <span style="color: #993399">4</span> <span style="color: #990000">(</span>delta <span style="color: #993399">4</span><span style="color: #990000">),</span> pack-reused <span style="color: #993399">4019</span> +Receiving objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">4035</span><span style="color: #990000">/</span><span style="color: #993399">4035</span><span style="color: #990000">),</span> <span style="color: #993399">1.10</span> MiB <span style="color: #990000">|</span> <span style="color: #993399">1000.00</span> KiB/s<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +Resolving deltas<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">2442</span><span style="color: #990000">/</span><span style="color: #993399">2442</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +Checking connectivity<span style="color: #990000">...</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -f build<span style="color: #990000">.</span>config <span style="color: #990000">];</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span> cp build<span style="color: #990000">.</span>config <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span> +cd <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build <span style="color: #990000">&&</span> make +make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Entering directory <span style="color: #FF0000">'/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'</span> +awk <span style="color: #FF0000">'FNR==1 && NR!=1{print ""}1'</span> core/core<span style="color: #990000">.</span>mk index<span style="color: #990000">/*.</span>mk core/index<span style="color: #990000">.</span>mk core/deps<span style="color: #990000">.</span>mk plugins/protobuffs<span style="color: #990000">.</span>mk core/erlc<span style="color: #990000">.</span>mk core/docs<span style="color: #990000">.</span>mk core/test<span style="color: #990000">.</span>mk plugins/asciidoc<span style="color: #990000">.</span>mk plugins/bootstrap<span style="color: #990000">.</span>mk plugins/c_src<span style="color: #990000">.</span>mk plugins/ci<span style="color: #990000">.</span>mk plugins/ct<span style="color: #990000">.</span>mk plugins/dialyzer<span style="color: #990000">.</span>mk plugins/edoc<span style="color: #990000">.</span>mk plugins/elvis<span style="color: #990000">.</span>mk plugins/erlydtl<span style="color: #990000">.</span>mk plugins/escript<span style="color: #990000">.</span>mk plugins/eunit<span style="color: #990000">.</span>mk plugins/relx<span style="color: #990000">.</span>mk plugins/shell<span style="color: #990000">.</span>mk plugins/triq<span style="color: #990000">.</span>mk plugins/xref<span style="color: #990000">.</span>mk plugins/cover<span style="color: #990000">.</span>mk <span style="color: #990000">\</span> + <span style="color: #990000">|</span> sed <span style="color: #FF0000">'s/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/'</span> <span style="color: #990000">></span> erlang<span style="color: #990000">.</span>mk +make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Leaving directory <span style="color: #FF0000">'/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'</span> +cp <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>/erlang<span style="color: #990000">.</span>mk +rm -rf <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build</tt></pre></div></div> +<div class="paragraph"><p>All that’s left to do is to commit the file!</p></div> +<div class="paragraph"><p>Yep, it’s that easy.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_customizing_the_build">Customizing the build</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk allows you to customize which components are to be included +in the <em>erlang.mk</em> file. The <code>WITHOUT</code> variable allows you to +remove components from the default Erlang.mk build. The <em>build.config</em> +file lets you define exactly what goes in (including your own code!), +and in what order.</p></div> +<div class="paragraph"><p>The <code>WITHOUT</code> file contains the list of components to exclude from +the build. For example, to exclude the package index and the EDoc +plugin when bootstrapping your application:</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 <span style="color: #009900">WITHOUT</span><span style="color: #990000">=</span><span style="color: #FF0000">"index plugins/edoc"</span></tt></pre></div></div> +<div class="paragraph"><p>The generated Erlang.mk will never include those components when +you update it, until you change your mind and use the <code>WITHOUT</code> +variable again when you upgrade:</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 erlang-mk <span style="color: #009900">WITHOUT</span><span style="color: #990000">=</span>index</tt></pre></div></div> +<div class="paragraph"><p>The <em>build.config</em> file is automatically used when you bootstrap +Erlang.mk or when you update it with <code>make erlang-mk</code>.</p></div> +<div class="paragraph"><p>The <em>build.config</em> file contains the list of all files that will +be built into the resulting <em>erlang.mk</em> file. You can start from +the <a href="https://github.com/ninenines/erlang.mk/blob/master/build.config">most recent version</a> +and customize to your needs.</p></div> +<div class="paragraph"><p>You can also name the file differently or put it in a separate folder +by modifying the value for <code>ERLANG_MK_BUILD_CONFIG</code>. You can also +tell Erlang.mk to use a different temporary directory by changing +the <code>ERLANG_MK_BUILD_DIR</code> variable.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/why/index.html b/docs/en/erlang.mk/1/guide/why/index.html index bc1881cf..0c73daaf 100644 --- a/docs/en/erlang.mk/1/guide/why/index.html +++ b/docs/en/erlang.mk/1/guide/why/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: Why Erlang.mk</title> @@ -67,92 +67,95 @@ <h1 class="lined-header"><span>Why Erlang.mk</span></h1> -<div class="paragraph"><p>Why would you choose Erlang.mk, if not for its
-<a href="../overview">many features</a>? This chapter will
-attempt to answer that.</p></div>
-<div class="sect1">
-<h2 id="_erlang_mk_is_fast">Erlang.mk is fast</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk is as fast as it gets.</p></div>
-<div class="paragraph"><p>Erlang.mk will group the compilation of files so as to avoid
-running the BEAM more than necessary. This saves many seconds
-compared to traditional Makefiles, even on small projects.</p></div>
-<div class="paragraph"><p>Erlang.mk will not try to be too smart. It provides a simple
-solution that works for most people, and gives additional
-options for projects that run into edge cases, often in the
-form of extra variables or rules to be defined.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_gives_you_the_full_power_of_unix">Erlang.mk gives you the full power of Unix</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk is a Makefile.</p></div>
-<div class="paragraph"><p>You could use Erlang.mk directly without configuring anything
-and it would just work. But you can also extend it greatly
-either through configuration or hooks, and you can of course
-add your own rules to the Makefile.</p></div>
-<div class="paragraph"><p>In all cases: for configuration, hooks or custom rules, you
-have all the power of Unix at your disposal, and can call
-any utility <em>or even any language interpreter</em> you want,
-every time you need to. Erlang.mk also allows you to write
-scripts in this small language called Erlang directly inside
-your Makefile if you ever need to…</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_is_a_text_file">Erlang.mk is a text file</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk is a Makefile.</p></div>
-<div class="paragraph"><p>Which means Erlang.mk is a simple text file. You can edit a
-text file. Nothing stops you. If you run into any bug, or
-behavior that does not suit you, you can just open the
-<em>erlang.mk</em> file in your favorite editor, fix and/or comment
-a few lines, save, and try again. It’s as simple as it gets.</p></div>
-<div class="paragraph"><p>Currently using a binary build tool? Good luck with that.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_can_manage_erlang_itself">Erlang.mk can manage Erlang itself</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk isn’t written in Erlang.</p></div>
-<div class="paragraph"><p>That’s not a good thing, you say? Well, here’s one thing
-that Erlang.mk and Makefiles can do for you that Erlang
-build tool can’t easily: choose what version of Erlang is
-to be used for compiling the project.</p></div>
-<div class="paragraph"><p>This really is a one-liner in Erlang.mk (a few more lines
-if you also let it download and build Erlang directly)
-and allows for even greater things, like testing your
-project across all supported Erlang versions in one small
-command: <code>make -k ci</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_can_do_more_than_erlang">Erlang.mk can do more than Erlang</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk doesn’t care what your dependencies are written in.</p></div>
-<div class="paragraph"><p>Erlang.mk will happily compile any dependency, as long as
-they come with a Makefile. The dependency can be written
-in C, C++ or even Javascript… Who cares, really? If you
-need Erlang.mk to fetch it, then Erlang.mk will fetch it
-and compile it as needed.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_integrates_nicely_in_make_and_automake_projects">Erlang.mk integrates nicely in Make and Automake projects</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you are planning to put your project in the middle of
-a Make or Automake-based build environment, then the most
-logical thing to do is to use a Makefile.</p></div>
-<div class="paragraph"><p>Erlang.mk will happily sit in such an environment and behave
-as you expect it to.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Why would you choose Erlang.mk, if not for its +<a href="../overview">many features</a>? This chapter will +attempt to answer that.</p></div> +<div class="sect1"> +<h2 id="_erlang_mk_is_fast">Erlang.mk is fast</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk is as fast as it gets.</p></div> +<div class="paragraph"><p>Erlang.mk will group the compilation of files so as to avoid +running the BEAM more than necessary. This saves many seconds +compared to traditional Makefiles, even on small projects.</p></div> +<div class="paragraph"><p>Erlang.mk will not try to be too smart. It provides a simple +solution that works for most people, and gives additional +options for projects that run into edge cases, often in the +form of extra variables or rules to be defined.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_gives_you_the_full_power_of_unix">Erlang.mk gives you the full power of Unix</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk is a Makefile.</p></div> +<div class="paragraph"><p>You could use Erlang.mk directly without configuring anything +and it would just work. But you can also extend it greatly +either through configuration or hooks, and you can of course +add your own rules to the Makefile.</p></div> +<div class="paragraph"><p>In all cases: for configuration, hooks or custom rules, you +have all the power of Unix at your disposal, and can call +any utility <em>or even any language interpreter</em> you want, +every time you need to. Erlang.mk also allows you to write +scripts in this small language called Erlang directly inside +your Makefile if you ever need to…</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_is_a_text_file">Erlang.mk is a text file</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk is a Makefile.</p></div> +<div class="paragraph"><p>Which means Erlang.mk is a simple text file. You can edit a +text file. Nothing stops you. If you run into any bug, or +behavior that does not suit you, you can just open the +<em>erlang.mk</em> file in your favorite editor, fix and/or comment +a few lines, save, and try again. It’s as simple as it gets.</p></div> +<div class="paragraph"><p>Currently using a binary build tool? Good luck with that.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_can_manage_erlang_itself">Erlang.mk can manage Erlang itself</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk isn’t written in Erlang.</p></div> +<div class="paragraph"><p>That’s not a good thing, you say? Well, here’s one thing +that Erlang.mk and Makefiles can do for you that Erlang +build tool can’t easily: choose what version of Erlang is +to be used for compiling the project.</p></div> +<div class="paragraph"><p>This really is a one-liner in Erlang.mk (a few more lines +if you also let it download and build Erlang directly) +and allows for even greater things, like testing your +project across all supported Erlang versions in one small +command: <code>make -k ci</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_can_do_more_than_erlang">Erlang.mk can do more than Erlang</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk doesn’t care what your dependencies are written in.</p></div> +<div class="paragraph"><p>Erlang.mk will happily compile any dependency, as long as +they come with a Makefile. The dependency can be written +in C, C++ or even Javascript… Who cares, really? If you +need Erlang.mk to fetch it, then Erlang.mk will fetch it +and compile it as needed.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_integrates_nicely_in_make_and_automake_projects">Erlang.mk integrates nicely in Make and Automake projects</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you are planning to put your project in the middle of +a Make or Automake-based build environment, then the most +logical thing to do is to use a Makefile.</p></div> +<div class="paragraph"><p>Erlang.mk will happily sit in such an environment and behave +as you expect it to.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/xref/index.html b/docs/en/erlang.mk/1/guide/xref/index.html index 6cb0e2ec..7913e3d9 100644 --- a/docs/en/erlang.mk/1/guide/xref/index.html +++ b/docs/en/erlang.mk/1/guide/xref/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: Xref</title> @@ -67,13 +67,16 @@ <h1 class="lined-header"><span>Xref</span></h1> -<div class="paragraph"><p>Placeholder chapter.</p></div>
+<div class="paragraph"><p>Placeholder chapter.</p></div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/index.html b/docs/en/erlang.mk/1/index.html index d87c4243..0194031a 100644 --- a/docs/en/erlang.mk/1/index.html +++ b/docs/en/erlang.mk/1/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file |