diff options
Diffstat (limited to 'docs/en/erlang.mk')
30 files changed, 1500 insertions, 3420 deletions
diff --git a/docs/en/erlang.mk/1/guide/app/index.html b/docs/en/erlang.mk/1/guide/app/index.html index 55c2d223..3c4d62d3 100644 --- a/docs/en/erlang.mk/1/guide/app/index.html +++ b/docs/en/erlang.mk/1/guide/app/index.html @@ -62,642 +62,348 @@ <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"> +<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> +<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> <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 +<p>To build a project, all you have to do is type <code>make</code>:</p> +<div class="listingblock"><div class="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"> +<pre><tt>$ make</tt></pre> +</div></div> +<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> +<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> <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"> +<p>Erlang.mk gives you control over three steps of the build process, allowing you to do a partial build if needed.</p> +<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> +<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> +<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> <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 +<p>You can build your application and dependencies without generating a release by running the following command:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make app</tt></pre> +</div></div> +<p>To build your application without touching dependencies at all, you can use the <code>SKIP_DEPS</code> variable:</p> +<div class="listingblock"><div class="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"> +<pre><tt>$ make app <font color="#009900">SKIP_DEPS</font><font color="#990000">=</font><font color="#993399">1</font></tt></pre> +</div></div> +<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> +<p>Note that this command may fail if a required dependency is missing.</p> <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 +<p>You can build all dependencies, and nothing else, by running the following command:</p> +<div class="listingblock"><div class="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"> +<pre><tt>$ make deps</tt></pre> +</div></div> +<p>This will fetch and compile all dependencies and their dependencies, recursively.</p> +<p><a href="../deps">Packages and dependencies</a> are covered in the next chapter.</p> <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 +<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> +<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 class="listingblock"><div class="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"> +<pre><tt>$ make rel</tt></pre> +</div></div> +<p>Consult the <a href="../relx">Releases</a> chapter for more information about what releases are and how they are generated.</p> <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"> +<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> +<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> +<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> <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> +<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> +<dl><dt><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> +<dt><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> +<dt><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> +<dt><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> +<dt><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> +<dt><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> +<dt><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> +<dt><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> +<dt><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 +</dl> +<p>There's no need for quotes or anything. The relevant part of the Cowboy Makefile follows, if you need an example:</p> +<div class="listingblock"><div class="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"> +<pre><tt><font color="#009900">PROJECT =</font> cowboy +<font color="#009900">PROJECT_DESCRIPTION =</font> Small<font color="#990000">,</font> fast<font color="#990000">,</font> modular HTTP server<font color="#990000">.</font> +<font color="#009900">PROJECT_VERSION =</font> 2.0.0-pre.2 +<font color="#009900">PROJECT_REGISTERED =</font> cowboy_clock + +<font color="#009900">LOCAL_DEPS =</font> crypto +<font color="#009900">DEPS =</font> cowlib ranch</tt></pre> +</div></div> +<p>Any space before and after the value is dropped.</p> +<p><a href="../deps">Dependencies</a> are covered in details in the next chapter.</p> <h4 id="_application_environment">Application environment</h4> -<div class="paragraph"><p>The <code>PROJECT_ENV</code> variable is used to set the application -environment:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<p>The <code>PROJECT_ENV</code> variable is used to set the application environment:</p> +<div class="listingblock"><div class="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 PROJECT_ENV -<span style="color: #990000">[</span> - {chips<span style="color: #990000">,</span> <span style="color: #990000">[</span>currysauce<span style="color: #990000">,</span>{mushypeas<span style="color: #990000">,</span><span style="font-weight: bold"><span style="color: #0000FF">false</span></span>}<span style="color: #990000">]</span>}<span style="color: #990000">,</span> - {pizza<span style="color: #990000">,</span> <span style="color: #990000">[</span>{size<span style="color: #990000">,</span>large}<span style="color: #990000">,</span>{toppings<span style="color: #990000">,[</span>anchovies<span style="color: #990000">]</span>}<span style="color: #990000">]</span>} -<span style="color: #990000">]</span> -endef</tt></pre></div></div> -<div class="paragraph"><p>If you have a large set of environment variables, you may find it -easier to use a separate file. Do this by including the following -in your Makefile:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<font color="#990000">[</font> + {chips<font color="#990000">,</font> <font color="#990000">[</font>currysauce<font color="#990000">,</font>{mushypeas<font color="#990000">,</font><b><font color="#0000FF">false</font></b>}<font color="#990000">]</font>}<font color="#990000">,</font> + {pizza<font color="#990000">,</font> <font color="#990000">[</font>{size<font color="#990000">,</font>large}<font color="#990000">,</font>{toppings<font color="#990000">,[</font>anchovies<font color="#990000">]</font>}<font color="#990000">]</font>} +<font color="#990000">]</font> +endef</tt></pre> +</div></div> +<p>If you have a large set of environment variables, you may find it easier to use a separate file. Do this by including the following in your Makefile:</p> +<div class="listingblock"><div class="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_ENV_FILE =</span> src/env.src -<span style="color: #009900">PROJECT_ENV =</span> <span style="color: #009900">$(</span>subst <span style="color: #990000">\</span>n<span style="color: #990000">,</span><span style="color: #009900">$(newline)</span><span style="color: #990000">,</span><span style="color: #009900">$(</span>shell cat <span style="color: #009900">$(PROJECT_ENV_FILE)</span> <span style="color: #990000">|</span> sed -e <span style="color: #FF0000">'s/$$/</span><span style="color: #CC33CC">\\</span><span style="color: #FF0000">n/;'</span><span style="color: #990000">))</span> -ebin<span style="color: #990000">/</span><span style="color: #009900">$(PROJECT)</span>.app<span style="color: #990000">::</span> <span style="color: #009900">$(PROJECT_ENV_FILE)</span></tt></pre></div></div> -<div class="paragraph"><p>The file has the same contents as the <code>PROJECT_ENV</code> variable:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt><font color="#009900">PROJECT_ENV_FILE =</font> src/env.src +<font color="#009900">PROJECT_ENV =</font> <font color="#009900">$(</font>subst <font color="#990000">\</font>n<font color="#990000">,</font><font color="#009900">$(newline)</font><font color="#990000">,</font><font color="#009900">$(</font>shell cat <font color="#009900">$(PROJECT_ENV_FILE)</font> <font color="#990000">|</font> sed -e <font color="#FF0000">'s/$$/</font><font color="#CC33CC">\\</font><font color="#FF0000">n/;'</font><font color="#990000">))</font> +ebin<font color="#990000">/</font><font color="#009900">$(PROJECT)</font>.app<font color="#990000">::</font> <font color="#009900">$(PROJECT_ENV_FILE)</font></tt></pre> +</div></div> +<p>The file has the same contents as the <code>PROJECT_ENV</code> variable:</p> +<div class="listingblock"><div class="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">chips</span>, [<span style="color: #FF6600">currysauce</span>,{<span style="color: #FF6600">mushypeas</span>,<span style="color: #000080">false</span>}]}, - {<span style="color: #FF6600">pizza</span>, [{<span style="font-weight: bold"><span style="color: #000080">size</span></span>,<span style="color: #FF6600">large</span>},{<span style="color: #FF6600">toppings</span>,[<span style="color: #FF6600">anchovies</span>]}]} -]</tt></pre></div></div> -</div> -<div class="sect3"> + {<font color="#FF6600">chips</font>, [<font color="#FF6600">currysauce</font>,{<font color="#FF6600">mushypeas</font>,<font color="#000080">false</font>}]}, + {<font color="#FF6600">pizza</font>, [{<b><font color="#000080">size</font></b>,<font color="#FF6600">large</font>},{<font color="#FF6600">toppings</font>,[<font color="#FF6600">anchovies</font>]}]} +]</tt></pre> +</div></div> <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 +<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> +<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> +<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> +<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 class="listingblock"><div class="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"> +<pre><tt>$ make -f erlang<font color="#990000">.</font>mk bootstrap-lib <font color="#009900">LEGACY</font><font color="#990000">=</font><font color="#993399">1</font></tt></pre> +</div></div> <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> +<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> +<ul><li>The application was built as a dependency of another, or </li> -<li> -<p> -The legacy method was used, and the <em>.app.src</em> file contained <code>{id, "git"}</code> -</p> +<li>The legacy method was used, and the <em>.app.src</em> file contained <code>{id, "git"}</code> </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 +</ul> +<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 class="listingblock"><div class="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"> +<pre><tt><font color="#993399">1</font><font color="#990000">></font> <b><font color="#000000">application:get_all_key</font></b>(<font color="#FF6600">cowboy</font>)<font color="#990000">.</font> +{<font color="#FF6600">ok</font>,[{<font color="#FF6600">description</font>,<font color="#FF0000">"Small, fast, modular HTTP server."</font>}, + {<font color="#FF6600">id</font>,<font color="#FF0000">"2.0.0-pre.2-25-g0ffde50-dirty"</font>},</tt></pre> +</div></div> <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> +<p>Erlang.mk supports a variety of different source file formats. The following formats are supported natively:</p> +<table rules="all" width="100%" frame="border" + cellspacing="0" cellpadding="4"> +<thead><tr><th>Extension</th> +<th>Location</th> +<th>Description</th> +<th>Output</th> +</tr></thead><tbody><tr><td>.erl</td> +<td>src/</td> +<td>Erlang source</td> +<td>ebin/*.beam</td> </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><td>.core</td> +<td>src/</td> +<td>Core Erlang source</td> +<td>ebin/*.beam</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><td>.xrl</td> +<td>src/</td> +<td>Leex source</td> +<td>src/*.erl</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><td>.yrl</td> +<td>src/</td> +<td>Yecc source</td> +<td>src/*.erl</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><td>.asn1</td> +<td>asn1/</td> +<td>ASN.1 files</td> +<td>include/*.hrl include/*.asn1db src/*.erl</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><td>.mib</td> +<td>mibs/</td> +<td>SNMP MIB files</td> +<td>include/*.hrl priv/mibs/*.bin</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> +</tbody></table> +<p>Files are always searched recursively.</p> +<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> +<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> +<p>Erlang.mk also comes with plugins for the following formats:</p> +<table rules="all" width="100%" frame="border" + cellspacing="0" cellpadding="4"> +<thead><tr><th>Extension</th> +<th>Location</th> +<th>Description</th> +<th>Output</th> +</tr></thead><tbody><tr><td>.dtl</td> +<td>templates/</td> +<td>Django templates</td> +<td>ebin/*.beam</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><td>.proto</td> +<td>src/</td> +<td>Protocol buffers</td> +<td>ebin/*.beam</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"> +</tbody></table> <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"> +<p>Erlang.mk provides a few variables that you can use to customize the build process and the resulting files.</p> <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 +<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> +<p>By default, Erlang.mk will set the following options:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">ERLC_OPTS =</font> -Werror <font color="#990000">+</font>debug_info <font color="#990000">+</font>warn_export_vars <font color="#990000">+</font>warn_shadow_vars <font color="#990000">+</font>warn_obsolete_guard</tt></pre> +</div></div> +<p>In other words: warnings as errors, debug info (recommended) and enable warnings for exported variables, shadow variables and obsolete guard functions.</p> +<p>You can redefine this variable in your Makefile to change it completely, either before or after including Erlang.mk:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">ERLC_OPTS =</font> <font color="#990000">+</font>debug_info</tt></pre> +</div></div> +<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 class="listingblock"><div class="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"> +<font color="#990000">ERLC_OPTS :=</font> <font color="#009900">$(</font>filter-out -Werror<font color="#990000">,</font><font color="#009900">$(ERLC_OPTS))</font></tt></pre> +</div></div> <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"> +<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> +<p>By default, Erlang.mk will leave this empty.</p> +<p>You can redefine this variable in your Makefile. Please see the <code>ERLC_OPTS</code> section for instructions.</p> <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 +<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> +<p>To exclude a module, simply list it in the variable, either before or after including Erlang.mk:</p> +<div class="listingblock"><div class="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"> +<pre><tt><font color="#009900">ERLC_EXCLUDE =</font> cowboy_http2</tt></pre> +</div></div> <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"> +<p>The first time you run <code>make</code>, Erlang.mk will build everything.</p> +<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> +<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> +<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> <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 +<p>NOTE: This section is about the dependency tracking between files inside your project, not application dependencies.</p> +<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> +<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> +<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 class="listingblock"><div class="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 +<pre><tt>NO_MAKEDEP <font color="#990000">?=</font> <font color="#993399">1</font></tt></pre> +</div></div> +<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 class="listingblock"><div class="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"> +<pre><tt>$ <font color="#009900">NO_MAKEDEP</font><font color="#990000">=</font> make</tt></pre> +</div></div> +<p>Otherwise, <code>make clean app</code> will of course force the recompilation of your project.</p> +<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> <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 +<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> +<p>The easiest way is after:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">PROJECT =</font> 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 +<font color="#009900">$(PROJECT)</font>.d<font color="#990000">::</font> src/generated_mod.erl + +src/generated_mod.erl<font color="#990000">::</font> gen-mod.sh + <font color="#009900">$(gen_verbose)</font> <font color="#990000">.</font>/gen-mod.sh <font color="#009900">$@</font></tt></pre> +</div></div> +<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> +<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> +<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 class="listingblock"><div class="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 +<pre><tt><font color="#009900">PROJECT =</font> example -.DEFAULT_GOAL <span style="color: #990000">=</span> all +.DEFAULT_GOAL <font color="#990000">=</font> all -<span style="color: #009900">$(PROJECT)</span>.d<span style="color: #990000">::</span> src/generated_mod.erl +<font color="#009900">$(PROJECT)</font>.d<font color="#990000">::</font> 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"> +src/generated_mod.erl<font color="#990000">::</font> gen-mod.sh + <font color="#009900">$(gen_verbose)</font> <font color="#990000">.</font>/gen-mod.sh <font color="#009900">$@</font></tt></pre> +</div></div> <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 +<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> +<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> +<p>To clean:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make clean</tt></pre> +</div></div> +<p>Or distclean:</p> +<div class="listingblock"><div class="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> +<pre><tt>$ make distclean</tt></pre> +</div></div> +<p>That is the question.</p> +<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> + diff --git a/docs/en/erlang.mk/1/guide/asciidoc/index.html b/docs/en/erlang.mk/1/guide/asciidoc/index.html index bb13a400..530c81cc 100644 --- a/docs/en/erlang.mk/1/guide/asciidoc/index.html +++ b/docs/en/erlang.mk/1/guide/asciidoc/index.html @@ -62,100 +62,63 @@ <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"> +<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> <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"> +<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> <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"> +<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> +<p>The <a href="http://asciidoc.org/userguide.html">AsciiDoc user guide</a> describes the AsciiDoc syntax.</p> +<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> +<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> +<p>For manual pages, it is good practice to use section 3 for modules, and section 7 for the application itself.</p> <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"> +<p>All of the AsciiDoc related configuration can be done directly inside the files themselves.</p> <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 +<p>To build all documentation:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make docs</tt></pre> +</div></div> +<p>To build only the AsciiDoc documentation:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make asciidoc</tt></pre> +</div></div> +<p>To build only the user guide:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make asciidoc-guide</tt></pre> +</div></div> +<p>To build only the manual:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make asciidoc-manual</tt></pre> +</div></div> +<p>To install man pages on Unix:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make install-docs</tt></pre> +</div></div> +<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> +<p>To install man pages to a custom location:</p> +<div class="listingblock"><div class="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> +<pre><tt>$ make install-docs <font color="#009900">MAN_INSTALL_PATH</font><font color="#990000">=</font>/opt/share/man</tt></pre> +</div></div> +<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> + diff --git a/docs/en/erlang.mk/1/guide/ci/index.html b/docs/en/erlang.mk/1/guide/ci/index.html index cacdb813..c5cd6e97 100644 --- a/docs/en/erlang.mk/1/guide/ci/index.html +++ b/docs/en/erlang.mk/1/guide/ci/index.html @@ -62,80 +62,51 @@ <h1 class="lined-header"><span>Continuous integration</span></h1> -<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"> +<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> <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 +<p>To use the CI plugin you must first configure which versions of Erlang/OTP will be used. Erlang.mk provides three separate configuration variables depending on whether you need a normal OTP release, a HiPE-enabled release or an ErLLVM-enabled release.</p> +<p>At the time of writing, this is how you would test against all the most recent patch releases of Erlang/OTP 19 and above:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">CI_OTP =</font> 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> +<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 class="listingblock"><div class="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"> +<pre><tt><font color="#009900">CI_HIPE =</font> <font color="#009900">$(</font>lastword <font color="#009900">$(CI_OTP))</font> +<font color="#009900">CI_ERLLVM =</font> <font color="#009900">$(CI_HIPE)</font></tt></pre> +</div></div> +<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> <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 +<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 class="listingblock"><div class="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"> +<pre><tt>$ make ci -k</tt></pre> +</div></div> <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 +<p>The <code>ci</code> target can be extended. For example to run Dialyzer at the end of CI:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#990000">ci::</font> dialyze</tt></pre> +</div></div> +<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> +<p>For example, to ensure dependencies are re-fetched/built before testing individual Erlang/OTP releases:</p> +<div class="listingblock"><div class="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> +<pre><tt><font color="#990000">ci-setup::</font> distclean</tt></pre> +</div></div> +<p>Similarly, the <code>ci-extra</code> target can be extended to run extra commands after an Erlang/OTP version has been tested.</p> + 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 f6430831..a5af0283 100644 --- a/docs/en/erlang.mk/1/guide/common_test/index.html +++ b/docs/en/erlang.mk/1/guide/common_test/index.html @@ -62,127 +62,92 @@ <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"> +<p>Common Test is Erlang's functional testing framework. Erlang.mk automates the discovery and running of Common Test suites.</p> <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"> +<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> <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 +<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 class="listingblock"><div class="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 +<pre><tt><font color="#009900">CT_OPTS =</font> -ct_hooks cowboy_ct_hook</tt></pre> +</div></div> +<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> +<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 class="listingblock"><div class="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 +<pre><tt><font color="#009900">CT_SUITES =</font> http ws</tt></pre> +</div></div> +<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 class="listingblock"><div class="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"> +<pre><tt><font color="#009900">CT_LOGS_DIR =</font> ct_output_log_dir</tt></pre> +</div></div> <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 +<p>To run all tests (including Common Test):</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make tests</tt></pre> +</div></div> +<p>To run all tests and static checks (including Common Test):</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make check</tt></pre> +</div></div> +<p>You can also run Common Test separately:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make ct</tt></pre> +</div></div> +<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 class="listingblock"><div class="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 +<pre><tt>$ make ct-http</tt></pre> +</div></div> +<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> +<p>To run all tests from the <code>http_compress</code> group in the <code>http_SUITE</code> test suite, write:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make ct-http <font color="#009900">t</font><font color="#990000">=</font>http_compress</tt></pre> +</div></div> +<p>Similarly, to run a specific test case in that group:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make ct-http <font color="#009900">t</font><font color="#990000">=</font>http_compress<font color="#990000">:</font>headers_dupe</tt></pre> +</div></div> +<p>To do the same against a multi-application repository, you can use the <code>-C</code> option:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make -C apps/my_app ct-http <font color="#009900">t</font><font color="#990000">=</font>my_group<font color="#990000">:</font>my_case</tt></pre> +</div></div> +<p>Note that this also applies to dependencies. When using Cowboy as a dependency, you can run the following directly:</p> +<div class="listingblock"><div class="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> +<pre><tt>$ make -C deps/cowboy ct-http <font color="#009900">t</font><font color="#990000">=</font>http_compress</tt></pre> +</div></div> +<p>Finally, <a href="../coverage">code coverage</a> is available, but covered in its own chapter.</p> + diff --git a/docs/en/erlang.mk/1/guide/compat/index.html b/docs/en/erlang.mk/1/guide/compat/index.html index 56ec41dc..a4420e66 100644 --- a/docs/en/erlang.mk/1/guide/compat/index.html +++ b/docs/en/erlang.mk/1/guide/compat/index.html @@ -62,90 +62,39 @@ <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"> +<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> +<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> <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"> +<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> +<p><em>Autoload</em> is documented in more details in the <a href="../deps">Packages and dependencies</a> chapter.</p> <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"> +<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> +<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> <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 +<p>Erlang.mk comes with a target that generates a <em>rebar.config</em> file when invoked:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make rebar<font color="#990000">.</font>config</tt></pre> +</div></div> +<p>Careful! This will build the file even if it already existed before.</p> +<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> +<!-- @todo Sanity check chapter.--> +<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> +<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 class="listingblock"><div class="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"> +<pre><tt><font color="#990000">app::</font> rebar.config</tt></pre> +</div></div> +<p>Don't forget to commit the file when it changes!</p> +<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> <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> +<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> +<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> + diff --git a/docs/en/erlang.mk/1/guide/contributing/index.html b/docs/en/erlang.mk/1/guide/contributing/index.html index 97a00e86..9ba72273 100644 --- a/docs/en/erlang.mk/1/guide/contributing/index.html +++ b/docs/en/erlang.mk/1/guide/contributing/index.html @@ -62,131 +62,57 @@ <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"> +<p>You are welcome and encouraged to contribute.</p> +<p>This is how.</p> <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> +<p>From the most important to the least important:</p> +<ul><li>Bugs </li> -<li> -<p> -Package issues/additions -</p> +<li>Package issues/additions </li> -<li> -<p> -Refactoring -</p> +<li>Refactoring </li> -<li> -<p> -Features -</p> +<li>Features </li> -</ul></div> -</div> -</div> -<div class="sect1"> +</ul> <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"> +<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> +<p>If you think you have found a bug but you are not sure, you should open a ticket as previously explained.</p> +<p>If you have found a bug and you need it to be solved RIGHT NOW, open a ticket as previously explained.</p> +<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> +<p>If you can't be patient, either try to solve the bug and contribute the fix back or become a paying customer.</p> <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"> +<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> +<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> +<p>If you have a test case that reproduces a bug, but no fix for it, you should open a pull request.</p> +<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> +<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> +<p>Some changes should be tested against all packages. Continue reading for more details on testing them.</p> <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 +<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> +<p>Packages can be added to the index using the <code>pkg_add.sh</code> script.</p> +<div class="listingblock"><div class="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"> +<pre><tt>$ git clone https<font color="#990000">:</font>//github<font color="#990000">.</font>com<font color="#990000">/</font><font color="#009900">$YOURUSERNAME</font>/erlang<font color="#990000">.</font>mk +$ cd erlang<font color="#990000">.</font>mk +$ <font color="#990000">.</font>/pkg_add<font color="#990000">.</font>sh cowboy git https<font color="#990000">:</font>//github<font color="#990000">.</font>com/ninenines/cowboy <font color="#993399">1.0</font><font color="#990000">.</font><font color="#993399">0</font> + http<font color="#990000">:</font>//ninenines<font color="#990000">.</font>eu <font color="#FF0000">"Small, fast and modular HTTP server."</font> +$ git push origin master</tt></pre> +</div></div> +<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> +<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> +<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> <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"> +<p>The documentation is always right.</p> +<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> +<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> <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> +<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> +<p>If you have code, great! Open a pull request as previously explained.</p> +<p>If not, you can still improve your feature request by writing the related documentation.</p> + diff --git a/docs/en/erlang.mk/1/guide/coverage/index.html b/docs/en/erlang.mk/1/guide/coverage/index.html index aa986318..b740872c 100644 --- a/docs/en/erlang.mk/1/guide/coverage/index.html +++ b/docs/en/erlang.mk/1/guide/coverage/index.html @@ -62,7 +62,9 @@ <h1 class="lined-header"><span>Code coverage</span></h1> -<div class="paragraph"><p>Placeholder chapter.</p></div> +<!-- @todo Write it.--> +<p>Placeholder chapter.</p> + diff --git a/docs/en/erlang.mk/1/guide/deps/index.html b/docs/en/erlang.mk/1/guide/deps/index.html index 845cfd09..a582e021 100644 --- a/docs/en/erlang.mk/1/guide/deps/index.html +++ b/docs/en/erlang.mk/1/guide/deps/index.html @@ -62,708 +62,387 @@ <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"> +<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> +<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> +<p>This chapter will explain how to use packages, add dependencies to your project or bundle them directly in a single repository.</p> <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 +<p>Erlang.mk gives you access to nearly 500 packages, with more being added regularly.</p> +<p>To find a package, search for it:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make search <font color="#009900">q</font><font color="#990000">=</font>pool</tt></pre> +</div></div> +<p>This will return all packages matching this word, like worker pool and acceptor pool projects.</p> +<p>You can also list everything and use regular command line tools to find what you need, for example:</p> +<div class="listingblock"><div class="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"> +<pre><tt>$ make search <font color="#990000">|</font> less</tt></pre> +</div></div> +<!-- @todo Simplify adding packages, add a new chapter explaining--> +<!-- everything, then link to this new chapter from here.--> <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 +<p>Once you find the package you need, adding it as a dependency to your project is a one-liner:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">DEPS =</font> cowboy</tt></pre> +</div></div> +<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> +<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> +<p>For example, you could add a parse transform project like this to make it available only at build time:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">BUILD_DEPS =</font> erlando</tt></pre> +</div></div> +<p>Or you could depend on a C project directly, if you are building a NIF:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">BUILD_DEPS =</font> leveldb +<font color="#009900">dep_leveldb =</font> git https<font color="#990000">:</font>//github.com/basho/leveldb 2.1.3</tt></pre> +</div></div> +<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> +<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> +<p>You could depend on the Crypto application, for example:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">LOCAL_DEPS =</font> crypto</tt></pre> +</div></div> +<p>Erlang.mk comes with additional types of dependencies. It has <code>TEST_DEPS</code> for dependencies used only for testing:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">TEST_DEPS =</font> ct_helper +<font color="#009900">dep_ct_helper =</font> git https<font color="#990000">:</font>//github.com/ninenines/ct_helper master</tt></pre> +</div></div> +<p><code>DOC_DEPS</code> for dependencies used only when building documentation:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">DOC_DEPS =</font> edown</tt></pre> +</div></div> +<p><code>REL_DEPS</code> for dependencies required to build the release, or to include extra applications in the release:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">REL_DEPS =</font> recon</tt></pre> +</div></div> +<p>And <code>SHELL_DEPS</code> for dependencies to make available when running the <code>make shell</code> command:</p> +<div class="listingblock"><div class="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"> +<pre><tt><font color="#009900">SHELL_DEPS =</font> tddreloader</tt></pre> +</div></div> +<p>All these will be documented in more details in their respective chapters.</p> <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 +<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 class="listingblock"><div class="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 +<pre><tt><font color="#009900">DEPS =</font> cowboy</tt></pre> +</div></div> +<p>If you need a different version, you need to define another variable. There are two ways to do this, each being useful for different reasons.</p> +<p>If you simply want to change the commit number, all you need to do is to define the <code>dep_$(DEP_NAME)_commit</code> variable. In the case of Cowboy, this would look like this:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">DEPS =</font> cowboy +<font color="#009900">dep_cowboy_commit =</font> 2.0.0-pre.2</tt></pre> +</div></div> +<p>Erlang.mk will use the package index to get all information about Cowboy, except the commit number which will be overriden.</p> +<p>If you need to set the fetch method or repository information 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 class="listingblock"><div class="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"> +<pre><tt><font color="#009900">DEPS =</font> cowboy +<font color="#009900">dep_cowboy =</font> git https<font color="#990000">:</font>//github.com/essen/cowboy 2.0.0-pre.2</tt></pre> +</div></div> +<p>This will fetch Cowboy from your fork at the given commit.</p> <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> +<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> +<p>The following table lists all existing methods:</p> +<table rules="all" width="100%" frame="border" + cellspacing="0" cellpadding="4"> +<thead><tr><th>Name</th> +<th>Format</th> +<th>Description</th> +</tr></thead><tbody><tr><td>git</td> +<td>git repo commit</td> +<td>Clone the Git repository and checkout the given version</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><td>git-submodule</td> +<td>git-submodule</td> +<td>Initialize and update the Git submodule</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><td>hg</td> +<td>hg repo commit</td> +<td>Clone the Mercurial repository and update to the given version</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><td>svn</td> +<td>svn repo</td> +<td>Checkout the given SVN repository</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><td>cp</td> +<td>cp path/to/repo</td> +<td>Recursively copy a local directory</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><td>ln</td> +<td>ln path/to/repo</td> +<td>Symbolically link a local directory</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><td>hex</td> +<td>hex version</td> +<td>Download the given project version from hex.pm</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><td>fail</td> +<td>N/A</td> +<td>Always fail, reserved for internal use</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><td>legacy</td> +<td>N/A</td> +<td>Legacy Erlang.mk fetcher, reserved for internal use</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 +</tbody></table> +<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> +<p>For example, to fetch Cowboy with tag 2.0.0-pre.2 from Git:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">dep_cowboy =</font> git https<font color="#990000">:</font>//github.com/ninenines/cowboy 2.0.0-pre.2</tt></pre> +</div></div> +<p>Or to fetch Ehsa tag 4.0.3 from Mercurial:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">dep_ehsa =</font> hg https<font color="#990000">:</font>//bitbucket.org/a12n/ehsa 4.0.3</tt></pre> +</div></div> +<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 class="listingblock"><div class="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 +<pre><tt><font color="#009900">dep_cowboy =</font> git-submodule</tt></pre> +</div></div> +<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> +<p>This would fetch an example project from the trunk:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">dep_ex1 =</font> svn https<font color="#990000">:</font>//example.com/svn/trunk/project/ex<font color="#993399">1</font></tt></pre> +</div></div> +<p>And this would fetch a separate example project from a specific commit:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">dep_ex2 =</font> svn svn<font color="#990000">:</font>//example.com/svn/branches/erlang-proj/ex<font color="#993399">2</font>@<font color="#993399">264</font></tt></pre> +</div></div> +<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 class="listingblock"><div class="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 +<pre><tt><font color="#009900">dep_cowboy =</font> cp <font color="#009900">$(HOME)</font>/ninenines/cowboy</tt></pre> +</div></div> +<p>Finally, you can use a package from the <a href="https://hex.pm/">Hex repository</a>:</p> +<div class="listingblock"><div class="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"> +<pre><tt><font color="#009900">dep_cowboy =</font> hex 1.0.3</tt></pre> +</div></div> <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 +<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> +<p>To give an example, this is what the Git method does:</p> +<div class="listingblock"><div class="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"> + git clone -q -n -- <font color="#009900">$(</font>call dep_repo<font color="#990000">,</font><font color="#009900">$1</font><font color="#990000">)</font> <font color="#009900">$(DEPS_DIR)</font><font color="#990000">/</font><font color="#009900">$(</font>call dep_name<font color="#990000">,</font><font color="#009900">$1</font><font color="#990000">);</font> <font color="#990000">\</font> + cd <font color="#009900">$(DEPS_DIR)</font><font color="#990000">/</font><font color="#009900">$(</font>call dep_name<font color="#990000">,</font><font color="#009900">$1</font><font color="#990000">)</font> <font color="#990000">&&</font> git checkout -q <font color="#009900">$(</font>call dep_commit<font color="#990000">,</font><font color="#009900">$1</font><font color="#990000">);</font> +endef</tt></pre> +</div></div> +<p>Note that, like dependency information, this custom fetch method must be written before including <em>erlang.mk</em>.</p> <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> +<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> +<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> +<ol><li>Fetch all dependencies for the application </li> -<li> -<p> -Build first dependency -</p> +<li>Build first dependency </li> -<li> -<p> -Build Nth dependency -</p> +<li>Build Nth dependency </li> -<li> -<p> -Build last dependency -</p> +<li>Build last dependency </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"> +</ol> +<p>Every time a dependency is built, these same steps are followed, recursively.</p> +<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> +<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> +<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> +<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> <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> +<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> +<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> +<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> +<ul><li>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. </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>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>. </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"> +</ul> +<p>Note that only first level <code>TEST_DEPS</code>, <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> +<p>No matter which method you use, <code>BUILD_DEPS</code> and <code>DEPS</code> are always included.</p> +<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> +<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> <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 +<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> +<p>To ignore a dependency, simply add it to the <code>IGNORE_DEPS</code> variable:</p> +<div class="listingblock"><div class="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 +<pre><tt>IGNORE_DEPS <font color="#990000">+=</font> edown proper</tt></pre> +</div></div> +<p>This will only ignore dependencies that are needed for building. It is therefore safe to write:</p> +<div class="listingblock"><div class="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"> +<pre><tt>IGNORE_DEPS <font color="#990000">+=</font> edown proper +<font color="#009900">TEST_DEPS =</font> proper</tt></pre> +</div></div> +<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> <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 +<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> +<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 class="listingblock"><div class="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"> +<pre><tt>DEPS_DIR <font color="#990000">?=</font> <font color="#009900">$(CURDIR)</font>/libs</tt></pre> +</div></div> +<p>The <code>$(CURDIR)</code> part is important, otherwise dependencies of dependencies will be fetched in the wrong directory.</p> +<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> <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> +<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> +<p>They work exactly the same as remote dependencies, except:</p> +<ul><li>They are not fetched </li> -<li> -<p> -They are not autopatched -</p> +<li>They are not autopatched </li> -<li> -<p> -They are not deleted on <code>make distclean</code> -</p> +<li>They are not deleted on <code>make distclean</code> </li> -<li> -<p> -They are not automatically added to the application resource file -</p> +<li>They are not automatically added to the application resource file </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 +</ul> +<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> +<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> +<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> +<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> +<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> +<p>For example, to create a full fledged OTP application as a local dependency:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make new-app <b><font color="#0000FF">in</font></b><font color="#990000">=</font>webchat</tt></pre> +</div></div> +<p>Or, the same as an OTP library:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make new-lib <b><font color="#0000FF">in</font></b><font color="#990000">=</font>webchat</tt></pre> +</div></div> +<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 class="listingblock"><div class="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"> +<pre><tt>$ make new <font color="#009900">t</font><font color="#990000">=</font>gen_server <font color="#009900">n</font><font color="#990000">=</font>my_server <b><font color="#0000FF">in</font></b><font color="#990000">=</font>webchat</tt></pre> +</div></div> <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"> +<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> +<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> <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> +<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> +<p>When fetching a dependency, the following operations are performed:</p> +<ul><li>Fetch the dependency using the configured fetch method </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>If it contains a <em>configure.ac</em> or <em>configure.in</em> file, run <code>autoreconf -Wall -vif -I m4</code> </li> -<li> -<p> -If it contains a <em>configure</em> script, run it -</p> +<li>If it contains a <em>configure</em> script, run it </li> -<li> -<p> -Run autopatch on the project -</p> +<li>Run autopatch on the project </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> +</ul> +<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> +<p>Otherwise, autopatch performs different operations depending on the kind of project it finds the dependency to be.</p> +<ul><li>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. </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>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. </li> -<li> -<p> -Other Erlang projects get a small Erlang.mk Makefile -generated automatically. -</p> +<li>Other Erlang projects get a small Erlang.mk Makefile generated automatically. </li> -<li> -<p> -Projects with no source directory and no Makefile get an -empty Makefile generated, for compatibility purposes. -</p> +<li>Projects with no source directory and no Makefile get an empty Makefile generated, for compatibility purposes. </li> -<li> -<p> -Other projects with no Makefile are left untouched. -</p> +<li>Other projects with no Makefile are left untouched. </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 +</ul> +<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 class="listingblock"><div class="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 +<pre><tt><font color="#009900">NO_AUTOPATCH_ERLANG_MK =</font> <font color="#993399">1</font></tt></pre> +</div></div> +<p>You can also disable autopatch entirely for a few select projects using the <code>NO_AUTOPATCH</code> variable:</p> +<div class="listingblock"><div class="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"> +<pre><tt><font color="#009900">NO_AUTOPATCH =</font> cowboy ranch cowlib</tt></pre> +</div></div> <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 +<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> +<p>A typical usage would be:</p> +<div class="listingblock"><div class="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> +<pre><tt>$ make <font color="#009900">SKIP_DEPS</font><font color="#990000">=</font><font color="#993399">1</font></tt></pre> +</div></div> +<p>When the variable is defined:</p> +<ul><li>Dependencies will not be compiled or downloaded when required </li> -<li> -<p> -The dependency directory <em>$(DEPS_DIR)</em> will not be removed on <code>make distclean</code> -</p> +<li>The dependency directory <em>$(DEPS_DIR)</em> will not be removed on <code>make distclean</code> </li> -</ul></div> -<div class="paragraph"><p>This variable only applies to remote dependencies.</p></div> -</div> -</div> +</ul> +<p>This variable only applies to remote dependencies.</p> + diff --git a/docs/en/erlang.mk/1/guide/dialyzer/index.html b/docs/en/erlang.mk/1/guide/dialyzer/index.html index fedd4cae..e548daf4 100644 --- a/docs/en/erlang.mk/1/guide/dialyzer/index.html +++ b/docs/en/erlang.mk/1/guide/dialyzer/index.html @@ -62,77 +62,37 @@ <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"> +<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> +<p>Erlang.mk provides a wrapper around Dialyzer.</p> <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"> +<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> +<p>Dialyzer can generate this PLT file. Erlang.mk includes rules to automatically generate the PLT file when it is missing.</p> +<p>Once the PLT file is generated, Dialyzer can perform the analysis in record time.</p> <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"> +<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> +<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> +<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> +<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> +<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> <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 +<p>To perform an analysis, run the following command:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make dialyze</tt></pre> +</div></div> +<p>This will create the PLT file if it doesn't exist.</p> +<p>The analysis will also be performed when you run the following command, alongside tests:</p> +<div class="listingblock"><div class="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> +<pre><tt>$ make check</tt></pre> +</div></div> +<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> +<p>The PLT file will be removed when you run <code>make distclean</code>.</p> + diff --git a/docs/en/erlang.mk/1/guide/edoc/index.html b/docs/en/erlang.mk/1/guide/edoc/index.html index cb234d92..06f620ad 100644 --- a/docs/en/erlang.mk/1/guide/edoc/index.html +++ b/docs/en/erlang.mk/1/guide/edoc/index.html @@ -62,63 +62,43 @@ <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"> +<p>Erlang.mk provides a thin wrapper on top of EDoc, an application that generates documentation based on comments found in modules.</p> <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"> +<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> <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 +<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> +<p>A common use for this variable is to enable Markdown in doc comments, using the <code>edown</code> application:</p> +<div class="listingblock"><div class="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"> +<pre><tt><font color="#009900">DOC_DEPS =</font> edown +<font color="#009900">EDOC_OPTS =</font> {doclet<font color="#990000">,</font> edown_doclet}</tt></pre> +</div></div> <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 +<p>To build all documentation, you would typically use:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make docs</tt></pre> +</div></div> +<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> +<p>You can generate EDoc documentation directly:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make edoc</tt></pre> +</div></div> +<p>You can enable automatic generation on <code>make docs</code> by adding the following to your Makefile:</p> +<div class="listingblock"><div class="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> +<pre><tt><font color="#990000">docs::</font> edoc</tt></pre> +</div></div> + diff --git a/docs/en/erlang.mk/1/guide/escripts/index.html b/docs/en/erlang.mk/1/guide/escripts/index.html index fbe0a336..b33b5841 100644 --- a/docs/en/erlang.mk/1/guide/escripts/index.html +++ b/docs/en/erlang.mk/1/guide/escripts/index.html @@ -62,96 +62,53 @@ <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"> +<p>Escripts are an alternative to release. They are meant to be used for small command line executables written in Erlang.</p> +<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> +<p>For self-contained executables, check <a href="../sfx">self-extracting releases</a>.</p> <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 +<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> +<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 class="listingblock"><div class="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"> +<pre><tt>$ make escript <font color="#009900">ESCRIPT_ZIP</font><font color="#990000">=</font>zip</tt></pre> +</div></div> <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 +<p>Run the following command to generate an escript:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make escript</tt></pre> +</div></div> +<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> +<p>You can run the escript as you would any executable:</p> +<div class="listingblock"><div class="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"> +<pre><tt>$ <font color="#990000">.</font>/relx</tt></pre> +</div></div> <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"> +<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> +<p><code>ESCRIPT_FILE</code> can be set if you need a different file name or location.</p> +<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> +<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> <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 +<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> +<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 class="listingblock"><div class="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"> +<pre><tt><font color="#990000">escript-zip::</font> + <font color="#009900">$(verbose)</font> <font color="#009900">$(ESCRIPT_ZIP)</font> <font color="#009900">$(ESCRIPT_ZIP_FILE)</font> priv/templates<font color="#990000">/*</font></tt></pre> +</div></div> +<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> <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> +<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> + diff --git a/docs/en/erlang.mk/1/guide/eunit/index.html b/docs/en/erlang.mk/1/guide/eunit/index.html index b1d257c2..6073d3f8 100644 --- a/docs/en/erlang.mk/1/guide/eunit/index.html +++ b/docs/en/erlang.mk/1/guide/eunit/index.html @@ -62,149 +62,110 @@ <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"> +<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> <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 +<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> +<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> +<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 class="listingblock"><div class="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> +<pre><tt><b><font color="#000080">-ifdef</font></b>(<font color="#009900">TEST</font>)<font color="#990000">.</font> -<span style="font-style: italic"><span style="color: #9A1900">%% Insert tests here.</span></span> +<i><font color="#9A1900">%% Insert tests here.</font></i> -<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 +<b><font color="#000080">-endif</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<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 class="listingblock"><div class="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> +<pre><tt><b><font color="#000080">-ifdef</font></b>(<font color="#009900">TEST</font>)<font color="#990000">.</font> -<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> +<b><font color="#000080">-include_lib</font></b>(<font color="#990000">\</font><font color="#FF0000">"eunit/include/eunit.hrl\").</font> -<span style="color: #FF0000">%% Insert tests here.</span> +<font color="#FF0000">%% Insert tests here.</font> -<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"> +<font color="#FF0000">-endif.</font></tt></pre> +</div></div> +<p>Erlang.mk will automatically recompile your code when you perform a normal build after running tests, and vice versa.</p> <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 +<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 class="listingblock"><div class="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 +<pre><tt><font color="#009900">EUNIT_OPTS =</font> verbose</tt></pre> +</div></div> +<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 class="listingblock"><div class="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"> +<pre><tt><font color="#009900">EUNIT_ERL_OPTS =</font> -args_file rel/vm.args -config rel/sys.config</tt></pre> +</div></div> <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 +<p>To run all tests (including EUnit):</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make tests</tt></pre> +</div></div> +<p>To run all tests and static checks (including EUnit):</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make check</tt></pre> +</div></div> +<p>You can also run EUnit separately:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make eunit</tt></pre> +</div></div> +<p>EUnit will be quiet by default, only outputting errors. You can easily make it verbose for a single invocation:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make eunit <font color="#009900">EUNIT_OPTS</font><font color="#990000">=</font>verbose</tt></pre> +</div></div> +<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> +<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 class="listingblock"><div class="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 +<pre><tt>$ make eunit <font color="#009900">t</font><font color="#990000">=</font>cow_http_hd</tt></pre> +</div></div> +<p>Similarly, to run a specific test case:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make eunit <font color="#009900">t</font><font color="#990000">=</font>cow_http_hd<font color="#990000">:</font>parse_accept_test_</tt></pre> +</div></div> +<p>To do the same against a multi-application repository, you can use the <code>-C</code> option:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make -C apps/my_app eunit <font color="#009900">t</font><font color="#990000">=</font>my_module<font color="#990000">:</font>hello_test</tt></pre> +</div></div> +<p>Note that this also applies to dependencies. From Cowboy, you can run the following directly:</p> +<div class="listingblock"><div class="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> +<pre><tt>$ make -C deps/cowlib eunit <font color="#009900">t</font><font color="#990000">=</font>cow_http_hd</tt></pre> +</div></div> +<p>Finally, <a href="../coverage">code coverage</a> is available, but covered in its own chapter.</p> + 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 da596541..3eaac0d6 100644 --- a/docs/en/erlang.mk/1/guide/external_plugins/index.html +++ b/docs/en/erlang.mk/1/guide/external_plugins/index.html @@ -62,154 +62,92 @@ <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"> +<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> +<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> +<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> <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 +<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> +<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 class="listingblock"><div class="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"> +<pre><tt><font color="#009900">DEPS =</font> cowboy +<font color="#009900">DEP_PLUGINS =</font> cowboy</tt></pre> +</div></div> +<p>This will load the file <em>plugins.mk</em> in the root folder of the Cowboy repository.</p> <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 +<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> +<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> +<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 class="listingblock"><div class="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"> +<pre><tt><font color="#009900">DEPS =</font> cowboy +<font color="#009900">DEP_PLUGINS =</font> cowboy/mk/dist.mk</tt></pre> +</div></div> <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 +<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> +<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> +<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 class="listingblock"><div class="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"> +<pre><tt><font color="#990000">THIS :=</font> <font color="#009900">$(</font>dir <font color="#009900">$(</font>realpath <font color="#009900">$(</font>lastword <font color="#009900">$(MAKEFILE_LIST))))</font> +include <font color="#009900">$(THIS)</font>/mk/dist.mk +include <font color="#009900">$(THIS)</font>/mk/templates.mk</tt></pre> +</div></div> +<p>The <code>THIS</code> variable is required to relatively include files.</p> +<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> <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 +<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> +<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 class="listingblock"><div class="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 +<pre><tt><i><font color="#9A1900"># In your application's Makefile</font></i> +<font color="#009900">BUILD_DEPS =</font> common_deps +<font color="#009900">DEP_EARLY_PLUGINS =</font> 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 +<pre><tt><i><font color="#9A1900"># In the plugin's early-plugins.mk</font></i> +DEPS <font color="#990000">+=</font> cowboy +<font color="#009900">TEST_DEPS =</font> ct_helper +<font color="#009900">dep_ct_helper =</font> git https<font color="#990000">:</font>//github.com/ninenines/ct_helper master</tt></pre> +</div></div> +<h2 id="_loading__plugins_local_to_the_application">Loading plugins local to the application</h2> +<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> +<p>For example, the following Makefile loads a plugin in the <em>mk</em> subdirectory:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">DEP_PLUGINS =</font> <font color="#009900">$(PROJECT)</font>/mk/dist.mk</tt></pre> +</div></div> +<p>This also works with early-stage plugins:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">DEP_EARLY_PLUGINS =</font> <font color="#009900">$(PROJECT)</font>/mk/variables.mk</tt></pre> +</div></div> +<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 class="listingblock"><div class="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> +<pre><tt><i><font color="#9A1900"># Loads ./early-plugins.mk</font></i> +<font color="#009900">DEP_EARLY_PLUGINS =</font> <font color="#009900">$(PROJECT)</font> +<i><font color="#9A1900"># Loads ./plugins.mk</font></i> +<font color="#009900">DEP_PLUGINS =</font> <font color="#009900">$(PROJECT)</font></tt></pre> +</div></div> + 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 37c88134..ddcd559d 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 @@ -62,87 +62,30 @@ <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"> +<p>This is a non-exhaustive list of Erlang.mk plugins, sorted alphabetically.</p> <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"> +<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> <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"> +<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> <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"> +<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> <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"> +<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> <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"> +<p>An <a href="https://github.com/inaka/hexer.mk">Hex plugin</a> for Erlang.mk using the <code>hexer</code> tool.</p> <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"> +<p>Another <a href="https://github.com/botsunit/hexpm.mk">Hex plugin</a> for Erlang.mk, with support for Hex dependency operators.</p> <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"> +<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> <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"> +<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> <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"> +<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> <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"> +<p>A <a href="https://github.com/bullno1/reload.mk">live reload plugin</a> for Erlang.mk.</p> <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> +<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> + 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 70ea7527..e6f3b05f 100644 --- a/docs/en/erlang.mk/1/guide/getting_started/index.html +++ b/docs/en/erlang.mk/1/guide/getting_started/index.html @@ -62,362 +62,258 @@ <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"> +<p>This chapter explains how to get started using Erlang.mk.</p> <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 +<p>The first step is always to create a new folder that will contain your project.</p> +<div class="listingblock"><div class="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"> +$ cd hello_joe</tt></pre> +</div></div> +<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> <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 +<p>At the time of writing, Erlang.mk is unlikely to be present in your Erlang distribution, or even in your OS packages.</p> +<p>The next step is therefore to download it:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ wget https<font color="#990000">:</font>//erlang<font color="#990000">.</font>mk/erlang<font color="#990000">.</font>mk</tt></pre> +</div></div> +<p>Or:</p> +<div class="listingblock"><div class="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"> +<pre><tt>$ curl -O https<font color="#990000">:</font>//erlang<font color="#990000">.</font>mk/erlang<font color="#990000">.</font>mk</tt></pre> +</div></div> +<p>Alternatively, just <a href="https://erlang.mk/erlang.mk">click on this link</a>.</p> +<p>Make sure you put the file inside the folder we created previously.</p> <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 +<p>An OTP application is an Erlang application that has a supervision tree. In other words, it will always have processes running.</p> +<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 class="listingblock"><div class="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 +<pre><tt>$ make -f erlang<font color="#990000">.</font>mk bootstrap</tt></pre> +</div></div> +<p>Something similar to the following snippet will then appear on your screen:</p> +<div class="listingblock"><div class="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 +<pre><tt>git clone https<font color="#990000">:</font>//github<font color="#990000">.</font>com/ninenines/erlang<font color="#990000">.</font>mk <font color="#990000">.</font>erlang<font color="#990000">.</font>mk<font color="#990000">.</font>build +Cloning into <font color="#FF0000">'.erlang.mk.build'</font><font color="#990000">...</font> +remote<font color="#990000">:</font> Counting objects<font color="#990000">:</font> <font color="#993399">4035</font><font color="#990000">,</font> <b><font color="#0000FF">done</font></b><font color="#990000">.</font> +remote<font color="#990000">:</font> Compressing objects<font color="#990000">:</font> <font color="#993399">100</font><font color="#990000">%</font> <font color="#990000">(</font><font color="#993399">12</font><font color="#990000">/</font><font color="#993399">12</font><font color="#990000">),</font> <b><font color="#0000FF">done</font></b><font color="#990000">.</font> +remote<font color="#990000">:</font> Total <font color="#993399">4035</font> <font color="#990000">(</font>delta <font color="#993399">8</font><font color="#990000">),</font> reused <font color="#993399">4</font> <font color="#990000">(</font>delta <font color="#993399">4</font><font color="#990000">),</font> pack-reused <font color="#993399">4019</font> +Receiving objects<font color="#990000">:</font> <font color="#993399">100</font><font color="#990000">%</font> <font color="#990000">(</font><font color="#993399">4035</font><font color="#990000">/</font><font color="#993399">4035</font><font color="#990000">),</font> <font color="#993399">1.10</font> MiB <font color="#990000">|</font> <font color="#993399">784.00</font> KiB/s<font color="#990000">,</font> <b><font color="#0000FF">done</font></b><font color="#990000">.</font> +Resolving deltas<font color="#990000">:</font> <font color="#993399">100</font><font color="#990000">%</font> <font color="#990000">(</font><font color="#993399">2442</font><font color="#990000">/</font><font color="#993399">2442</font><font color="#990000">),</font> <b><font color="#0000FF">done</font></b><font color="#990000">.</font> +Checking connectivity<font color="#990000">...</font> <b><font color="#0000FF">done</font></b><font color="#990000">.</font> +<b><font color="#0000FF">if</font></b> <font color="#990000">[</font> -f build<font color="#990000">.</font>config <font color="#990000">];</font> <b><font color="#0000FF">then</font></b> cp build<font color="#990000">.</font>config <font color="#990000">.</font>erlang<font color="#990000">.</font>mk<font color="#990000">.</font>build<font color="#990000">;</font> <b><font color="#0000FF">fi</font></b> +cd <font color="#990000">.</font>erlang<font color="#990000">.</font>mk<font color="#990000">.</font>build <font color="#990000">&&</font> make +make<font color="#990000">[</font><font color="#993399">1</font><font color="#990000">]:</font> Entering directory <font color="#FF0000">'/home/essen/tmp/hello_joe/.erlang.mk.build'</font> +awk <font color="#FF0000">'FNR==1 && NR!=1{print ""}1'</font> core/core<font color="#990000">.</font>mk index<font color="#990000">/*.</font>mk core/index<font color="#990000">.</font>mk core/deps<font color="#990000">.</font>mk plugins/protobuffs<font color="#990000">.</font>mk core/erlc<font color="#990000">.</font>mk core/docs<font color="#990000">.</font>mk core/test<font color="#990000">.</font>mk plugins/asciidoc<font color="#990000">.</font>mk plugins/bootstrap<font color="#990000">.</font>mk plugins/c_src<font color="#990000">.</font>mk plugins/ci<font color="#990000">.</font>mk plugins/ct<font color="#990000">.</font>mk plugins/dialyzer<font color="#990000">.</font>mk plugins/edoc<font color="#990000">.</font>mk plugins/elvis<font color="#990000">.</font>mk plugins/erlydtl<font color="#990000">.</font>mk plugins/escript<font color="#990000">.</font>mk plugins/eunit<font color="#990000">.</font>mk plugins/relx<font color="#990000">.</font>mk plugins/shell<font color="#990000">.</font>mk plugins/triq<font color="#990000">.</font>mk plugins/xref<font color="#990000">.</font>mk plugins/cover<font color="#990000">.</font>mk <font color="#990000">\</font> + <font color="#990000">|</font> sed <font color="#FF0000">'s/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/'</font> <font color="#990000">></font> erlang<font color="#990000">.</font>mk +make<font color="#990000">[</font><font color="#993399">1</font><font color="#990000">]:</font> Leaving directory <font color="#FF0000">'/home/essen/tmp/hello_joe/.erlang.mk.build'</font> +cp <font color="#990000">.</font>erlang<font color="#990000">.</font>mk<font color="#990000">.</font>build/erlang<font color="#990000">.</font>mk <font color="#990000">.</font>/erlang<font color="#990000">.</font>mk +rm -rf <font color="#990000">.</font>erlang<font color="#990000">.</font>mk<font color="#990000">.</font>build</tt></pre> +</div></div> +<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> +<p>Of course, the generated project can now be compiled:</p> +<div class="listingblock"><div class="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"> +<pre><tt>$ make</tt></pre> +</div></div> +<p>Cheers!</p> <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 +<p>An OTP library is an Erlang application that has no supervision tree. In other words, it is nothing but modules.</p> +<p>This kind of project can also be generated by Erlang.mk, using the <code>bootstrap-lib</code> target:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make -f erlang<font color="#990000">.</font>mk bootstrap-lib</tt></pre> +</div></div> +<p>Erlang.mk will once again bootstrap itself and generate all the files for your project. You can now compile it:</p> +<div class="listingblock"><div class="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"> +<pre><tt>$ make</tt></pre> +</div></div> +<p>Enjoy!</p> <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 +<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> +<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 class="listingblock"><div class="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 +<pre><tt>$ make bootstrap-rel</tt></pre> +</div></div> +<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 class="listingblock"><div class="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 +<pre><tt>$ make -f erlang<font color="#990000">.</font>mk bootstrap-lib bootstrap-rel</tt></pre> +</div></div> +<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> +<p>When you run <code>make</code> from now on, Erlang.mk will compile your project and build the release:</p> +<div class="listingblock"><div class="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 + APP hello_joe<font color="#990000">.</font>app<font color="#990000">.</font>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> +<font color="#990000">===></font> Starting relx build process <font color="#990000">...</font> +<font color="#990000">===></font> Resolving OTP Applications from directories<font color="#990000">:</font> /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 +<font color="#990000">===></font> Resolved hello_joe_release-<font color="#993399">1</font> +<font color="#990000">===></font> Including Erts from /usr/lib/erlang +<font color="#990000">===></font> release successfully created<font color="#990000">!</font></tt></pre> +</div></div> +<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> +<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> +<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 class="listingblock"><div class="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 + APP hello_joe<font color="#990000">.</font>app<font color="#990000">.</font>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> +<font color="#990000">===></font> Starting relx build process <font color="#990000">...</font> +<font color="#990000">===></font> Resolving OTP Applications from directories<font color="#990000">:</font> /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"> +<font color="#990000">===></font> Resolved hello_joe_release-<font color="#993399">1</font> +<font color="#990000">===></font> Including Erts from /usr/lib/erlang +<font color="#990000">===></font> release successfully created<font color="#990000">!</font> +Exec<font color="#990000">:</font> /home/essen/tmp/hello_joe<font color="#990000">/</font>_rel/hello_joe_release/erts-<font color="#993399">7.0</font>/bin/erlexec -boot /home/essen/tmp/hello_joe<font color="#990000">/</font>_rel/hello_joe_release/releases<font color="#990000">/</font><font color="#993399">1</font>/hello_joe_release -boot_var ERTS_LIB_DIR /home/essen/tmp/hello_joe<font color="#990000">/</font>_rel/hello_joe_release/erts-<font color="#993399">7.0</font><font color="#990000">/..</font>/lib -env ERL_LIBS /home/essen/tmp/hello_joe<font color="#990000">/</font>_rel/hello_joe_release/releases<font color="#990000">/</font><font color="#993399">1</font>/lib -config /home/essen/tmp/hello_joe<font color="#990000">/</font>_rel/hello_joe_release/releases<font color="#990000">/</font><font color="#993399">1</font>/sys<font color="#990000">.</font>config -args_file /home/essen/tmp/hello_joe<font color="#990000">/</font>_rel/hello_joe_release/releases<font color="#990000">/</font><font color="#993399">1</font>/vm<font color="#990000">.</font>args -- console +Root<font color="#990000">:</font> /home/essen/tmp/hello_joe<font color="#990000">/</font>_rel/hello_joe_release +/home/essen/tmp/hello_joe<font color="#990000">/</font>_rel/hello_joe_release +heart_beat_kill_pid <font color="#990000">=</font> <font color="#993399">16389</font> +Erlang/OTP <font color="#993399">18</font> <font color="#990000">[</font>erts-<font color="#993399">7.0</font><font color="#990000">]</font> <font color="#990000">[</font><b><font color="#0000FF">source</font></b><font color="#990000">]</font> <font color="#990000">[</font><font color="#993399">64</font>-bit<font color="#990000">]</font> <font color="#990000">[</font>smp<font color="#990000">:</font><font color="#993399">4</font><font color="#990000">:</font><font color="#993399">4</font><font color="#990000">]</font> <font color="#990000">[</font>async-threads<font color="#990000">:</font><font color="#993399">10</font><font color="#990000">]</font> <font color="#990000">[</font>hipe<font color="#990000">]</font> <font color="#990000">[</font>kernel-poll<font color="#990000">:</font><b><font color="#0000FF">false</font></b><font color="#990000">]</font> + +Eshell V7<font color="#990000">.</font><font color="#993399">0</font> <font color="#990000">(</font>abort with <font color="#990000">^</font>G<font color="#990000">)</font> +<font color="#990000">(</font>hello_joe@<font color="#993399">127.0</font><font color="#990000">.</font><font color="#993399">0.1</font><font color="#990000">)</font><font color="#993399">1</font><font color="#990000">></font> </tt></pre> +</div></div> +<p>Simple as that!</p> <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 +<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> +<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 class="listingblock"><div class="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 +<pre><tt>include erlang.mk</tt></pre> +</div></div> +<p>For a step by step:</p> +<div class="listingblock"><div class="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"> +$ curl https<font color="#990000">:</font>//erlang<font color="#990000">.</font>mk/erlang<font color="#990000">.</font>mk -o erlang<font color="#990000">.</font>mk +$ echo <font color="#FF0000">"include erlang.mk"</font> <font color="#990000">></font> Makefile +$ make</tt></pre> +</div></div> +<p>From that point onward you can create an <code>src/</code> folder or start using templates.</p> <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 +<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> +<p>Use the <code>SP</code> variable if you prefer spaces. Set it to the number of spaces per indentation level you want.</p> +<p>For example, if you prefer two spaces per indentation level:</p> +<div class="listingblock"><div class="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"> +<pre><tt>$ make -f erlang<font color="#990000">.</font>mk bootstrap <font color="#009900">SP</font><font color="#990000">=</font><font color="#993399">2</font></tt></pre> +</div></div> +<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> <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 +<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> +<p>You can list all available templates with the <code>list-templates</code> target:</p> +<div class="listingblock"><div class="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 gen_statem 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 +Available templates<font color="#990000">:</font> cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server gen_statem ranch_protocol supervisor</tt></pre> +</div></div> +<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 class="listingblock"><div class="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 +<pre><tt>$ make new <font color="#009900">t</font><font color="#990000">=</font>gen_server <font color="#009900">n</font><font color="#990000">=</font>my_server</tt></pre> +</div></div> +<p>This will create a module located in <em>src/my_server.erl</em> using the <code>gen_server</code> template.</p> +<p>This module is automatically compiled the next time you run <code>make</code>:</p> +<div class="listingblock"><div class="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> + ERLC my_server<font color="#990000">.</font>erl + APP hello_joe<font color="#990000">.</font>app<font color="#990000">.</font>src</tt></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"> +<p>All that's left to do is to open it in your favorite editor and make it do something!</p> +<h2 id="_hiding_erlang_mk_from_git">Hiding Erlang.mk from git</h2> +<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> +<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 class="listingblock"><div class="content"><pre>erlang.mk -diff</pre></div></div> +<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> <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 +<p>During development, if you don't remember the name of a target, you can always run <code>make help</code>:</p> +<div class="listingblock"><div class="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> +<pre><tt>$ make <b><font color="#0000FF">help</font></b> +erlang<font color="#990000">.</font>mk <font color="#990000">(</font>version <font color="#993399">1.2</font><font color="#990000">.</font><font color="#993399">0</font>-<font color="#993399">642</font>-gccd2b9f<font color="#990000">)</font> is distributed under the terms of the ISC License<font color="#990000">.</font> +Copyright <font color="#990000">(</font>c<font color="#990000">)</font> <font color="#993399">2013</font>-<font color="#993399">2016</font> Loïc Hoguin <font color="#990000"><</font>essen@ninenines<font color="#990000">.</font>eu<font color="#990000">></font> -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> +Usage<font color="#990000">:</font> <font color="#990000">[</font><font color="#009900">V</font><font color="#990000">=</font><font color="#993399">1</font><font color="#990000">]</font> make <font color="#990000">[</font>target<font color="#990000">]...</font> -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 +Core targets<font color="#990000">:</font> + all Run deps<font color="#990000">,</font> app and rel targets <b><font color="#0000FF">in</font></b> 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 + deps Fetch dependencies <font color="#990000">(</font><b><font color="#0000FF">if</font></b> needed<font color="#990000">)</font> and compile them + search <font color="#009900">q</font><font color="#990000">=...</font> Search <b><font color="#0000FF">for</font></b> a package <b><font color="#0000FF">in</font></b> the built-in index + rel Build a release <b><font color="#0000FF">for</font></b> this project<font color="#990000">,</font> <b><font color="#0000FF">if</font></b> applicable + docs Build the documentation <b><font color="#0000FF">for</font></b> this project + install-docs Install the man pages <b><font color="#0000FF">for</font></b> this project + check Compile and run all tests and analysis <b><font color="#0000FF">for</font></b> this project + tests Run the tests <b><font color="#0000FF">for</font></b> 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 + <b><font color="#0000FF">help</font></b> Display this <b><font color="#0000FF">help</font></b> and <b><font color="#0000FF">exit</font></b> + erlang-mk Update erlang<font color="#990000">.</font>mk to the latest version -Bootstrap targets<span style="color: #990000">:</span> +Bootstrap targets<font color="#990000">:</font> 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 + new <font color="#009900">t</font><font color="#990000">=</font>TPL <font color="#009900">n</font><font color="#990000">=</font>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> +<font color="#990000">...</font></tt></pre> +</div></div> +<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> +<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> + diff --git a/docs/en/erlang.mk/1/guide/history/index.html b/docs/en/erlang.mk/1/guide/history/index.html index 8ca7ac35..9f4af14a 100644 --- a/docs/en/erlang.mk/1/guide/history/index.html +++ b/docs/en/erlang.mk/1/guide/history/index.html @@ -62,61 +62,24 @@ <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"> +<p>This chapter aims to be a brief record of the life of the Erlang.mk project.</p> <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"> +<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> +<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> +<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> +<p>Erlang.mk was conceived.</p> +<p>A few months passed and, on May 1st, 2013, the Erlang.mk repository was created. Erlang.mk was born.</p> +<p>Little did I know how much it would grow.</p> <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> +<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> +<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> +<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> +<p>A package index was added to solve the problem of discovering Erlang projects.</p> +<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> +<p>Erlang.mk documentation was much improved and the Erlang.mk website was created in the summer of 2015.</p> +<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> +<p>A bright future lies ahead.</p> + diff --git a/docs/en/erlang.mk/1/guide/index.html b/docs/en/erlang.mk/1/guide/index.html index 3c66d012..79f94c2f 100644 --- a/docs/en/erlang.mk/1/guide/index.html +++ b/docs/en/erlang.mk/1/guide/index.html @@ -62,188 +62,76 @@ <h1 class="lined-header"><span>Erlang.mk User Guide</span></h1> -<div class="ulist"><ul> -<li> -<p> -<a href="installation/">Installation</a> -</p> +<ul><li><a href="installation/">Installation</a> </li> -<li> -<p> -<a href="getting_started/">Getting started</a> -</p> +<li><a href="getting_started/">Getting started</a> </li> -<li> -<p> -<a href="overview/">Overview</a> -</p> +<li><a href="overview/">Overview</a> </li> -<li> -<p> -<a href="updating/">Updating Erlang.mk</a> -</p> +<li><a href="updating/">Updating Erlang.mk</a> </li> -<li> -<p> -<a href="limitations/">Limitations</a> -</p> +<li><a href="limitations/">Limitations</a> </li> -</ul></div> -<div class="sect1"> +</ul> <h2 id="code">Code</h2> -<div class="sectionbody"> -<div class="ulist"><ul> -<li> -<p> -<a href="app/">Building</a> -</p> +<ul><li><a href="app/">Building</a> </li> -<li> -<p> -<a href="deps/">Packages and dependencies</a> -</p> +<li><a href="deps/">Packages and dependencies</a> </li> -<li> -<p> -<a href="ports/">NIFs and port drivers</a> -</p> +<li><a href="ports/">NIFs and port drivers</a> </li> -<li> -<p> -<a href="releases/">Releases</a> -</p> +<li><a href="releases/">Releases</a> </li> -<li> -<p> -<a href="sfx/">Self-extracting releases</a> -</p> +<li><a href="sfx/">Self-extracting releases</a> </li> -<li> -<p> -<a href="escripts/">Escripts</a> -</p> +<li><a href="escripts/">Escripts</a> </li> -<li> -<p> -<a href="kerl/">OTP version management</a> -</p> +<li><a href="kerl/">OTP version management</a> </li> -<li> -<p> -<a href="compat/">Compatibility with other build tools</a> -</p> +<li><a href="compat/">Compatibility with other build tools</a> </li> -</ul></div> -</div> -</div> -<div class="sect1"> +</ul> <h2 id="docs">Documentation</h2> -<div class="sectionbody"> -<div class="ulist"><ul> -<li> -<p> -<a href="asciidoc/">Asciidoc documentation</a> -</p> +<ul><li><a href="asciidoc/">Asciidoc documentation</a> </li> -<li> -<p> -<a href="edoc/">EDoc comments</a> -</p> +<li><a href="edoc/">EDoc comments</a> </li> -<li> -<p> -<a href="sphinx/">Sphinx documentation</a> -</p> +<li><a href="sphinx/">Sphinx documentation</a> </li> -</ul></div> -</div> -</div> -<div class="sect1"> +</ul> <h2 id="tests">Tests</h2> -<div class="sectionbody"> -<div class="ulist"><ul> -<li> -<p> -<a href="shell/">Erlang shell</a> -</p> +<ul><li><a href="shell/">Erlang shell</a> </li> -<li> -<p> -<a href="eunit/">EUnit</a> -</p> +<li><a href="eunit/">EUnit</a> </li> -<li> -<p> -<a href="common_test/">Common Test</a> -</p> +<li><a href="common_test/">Common Test</a> </li> -<li> -<p> -<a href="triq/">Triq</a> -</p> +<li><a href="triq/">Triq</a> </li> -<li> -<p> -<a href="coverage/">Code coverage</a> -</p> +<li><a href="coverage/">Code coverage</a> </li> -<li> -<p> -<a href="ci/">Continuous integration</a> -</p> +<li><a href="ci/">Continuous integration</a> </li> -<li> -<p> -<a href="dialyzer/">Dialyzer</a> -</p> +<li><a href="dialyzer/">Dialyzer</a> </li> -<li> -<p> -<a href="xref/">Xref</a> -</p> +<li><a href="xref/">Xref</a> </li> -</ul></div> -</div> -</div> -<div class="sect1"> +</ul> <h2 id="plugins">Third-party plugins</h2> -<div class="sectionbody"> -<div class="ulist"><ul> -<li> -<p> -<a href="external_plugins/">External plugins</a> -</p> +<ul><li><a href="external_plugins/">External plugins</a> </li> -<li> -<p> -<a href="external_plugins_list/">List of plugins</a> -</p> +<li><a href="external_plugins_list/">List of plugins</a> </li> -</ul></div> -</div> -</div> -<div class="sect1"> +</ul> <h2 id="about">About Erlang.mk</h2> -<div class="sectionbody"> -<div class="ulist"><ul> -<li> -<p> -<a href="why/">Why erlang.mk?</a> -</p> +<ul><li><a href="why/">Why erlang.mk?</a> </li> -<li> -<p> -<a href="history/">Short history</a> -</p> +<li><a href="history/">Short history</a> </li> -<li> -<p> -<a href="contributing/">Contributing</a> -</p> +<li><a href="contributing/">Contributing</a> </li> -</ul></div> -</div> -</div> +</ul> + diff --git a/docs/en/erlang.mk/1/guide/installation/index.html b/docs/en/erlang.mk/1/guide/installation/index.html index 867fb9ed..e1d4284e 100644 --- a/docs/en/erlang.mk/1/guide/installation/index.html +++ b/docs/en/erlang.mk/1/guide/installation/index.html @@ -62,183 +62,95 @@ <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"> +<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> +<p>Git and Erlang/OTP must also be installed.</p> +<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> +<p>Some packages may require additional libraries.</p> <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 +<p>The commands to install packages vary between distributions:</p> +<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 class="paragraph"><p>Alpine Linux and other distributions based on BusyBox come -with an incompatible <code>awk</code> program. Installing the GNU Awk -(<code>gawk</code> on Alpine) solves this issue.</p></div> -</div> -<div class="sect3"> +<pre><tt>$ pacman -S erlang git make</tt></pre> +</div></div> +<p>Alpine Linux and other distributions based on BusyBox come with an incompatible <code>awk</code> program. Installing the GNU Awk (<code>gawk</code> on Alpine) solves this issue.</p> <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 +<p>FreeBSD comes with binary and source packages:</p> +<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"> +<pre><tt>$ pkg install erlang git gmake</tt></pre> +</div></div> +<p>On FreeBSD the <code>make</code> command is BSD Make. Use <code>gmake</code> instead.</p> <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 +<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 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 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 +<pre><tt>$ brew install erlang git make</tt></pre> +</div></div> +<p>Homebrew installs GNU Make as <code>gmake</code>. The <code>make</code> command is the one provided by Apple.</p> +<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"> +<pre><tt>$ sudo port install erlang git gmake</tt></pre> +</div></div> <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"> +<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> +<p>NOTE: Erlang.mk expects Unix line breaks in most of the files (LF instead of CRLF). Make sure to configure your text editor adequately.</p> +<p>The rest of this section details how to setup Erlang/OTP and MSYS2 in order to use Erlang.mk.</p> <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"> +<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> +<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> +<p>You can install Erlang/OTP silently using the <code>/S</code> switch on the command line:</p> +<div class="listingblock"><div class="content"><pre>C:\Users\essen\Downloads> otp_win64_18.0.exe /S</pre></div></div> <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"> +<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> +<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> +<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> +<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 class="listingblock"><div class="content"><pre>C:\> 7z x msys2.tar.xz +C:\> 7z x msys2.tar > NUL</pre></div></div> +<p>Then you can run the two commands needed to perform the post-installation setup:</p> +<div class="listingblock"><div class="content"><pre>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"</pre></div></div> <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 +<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 class="listingblock"><div class="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 +<pre><tt>$ pacman -S git make</tt></pre> +</div></div> +<p>You can use <code>pacman -Ss</code> to search packages. For example, to find all packages related to GCC:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ pacman -Ss gcc</tt></pre> +</div></div> +<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 class="listingblock"><div class="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> +<pre><tt>$ pacman -S mingw-w<font color="#993399">64</font>-x86_64-gcc</tt></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"> +<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 class="listingblock"><div class="content"><pre>C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -S git make"</pre></div></div> +<p>You can use similar <code>bash</code> commands if you need to run programs inside the MSYS2 environment from a batch file.</p> <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> +<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> + diff --git a/docs/en/erlang.mk/1/guide/kerl/index.html b/docs/en/erlang.mk/1/guide/kerl/index.html index 4fc8f102..eb9fe097 100644 --- a/docs/en/erlang.mk/1/guide/kerl/index.html +++ b/docs/en/erlang.mk/1/guide/kerl/index.html @@ -62,84 +62,36 @@ <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"> +<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> <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"> +<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> +<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> +<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> <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 +<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> +<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 class="listingblock"><div class="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"> +<pre><tt><font color="#009900">ERLANG_OTP =</font> OTP-20.0.4 + +include erlang.mk</tt></pre> +</div></div> +<p>The next time you run <code>make</code> Erlang.mk will build and use the version you configured.</p> +<p>Note that there has been reports that this functionality is not compatible with the <code>.ONESHELL</code> feature from GNU Make.</p> <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"> +<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> <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 +<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 class="listingblock"><div class="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> +<pre><tt><b><font color="#0000FF">export</font></b> KERL_INSTALL_DIR <font color="#990000">=</font> <font color="#009900">$(CURDIR)</font>/erlang</tt></pre> +</div></div> +<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> + diff --git a/docs/en/erlang.mk/1/guide/limitations/index.html b/docs/en/erlang.mk/1/guide/limitations/index.html index 431a3ab8..659fb209 100644 --- a/docs/en/erlang.mk/1/guide/limitations/index.html +++ b/docs/en/erlang.mk/1/guide/limitations/index.html @@ -62,49 +62,20 @@ <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"> +<p>No software is perfect.</p> +<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> +<p>This chapter lists all known limitations of Erlang.mk.</p> <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"> +<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> +<p>In addition, the Erlang being used must be in your <code>$PATH</code> before you use Erlang.mk.</p> +<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> <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"> +<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> +<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> <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> +<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> +<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> + diff --git a/docs/en/erlang.mk/1/guide/overview/index.html b/docs/en/erlang.mk/1/guide/overview/index.html index 1a4b2b9d..9fa002de 100644 --- a/docs/en/erlang.mk/1/guide/overview/index.html +++ b/docs/en/erlang.mk/1/guide/overview/index.html @@ -62,94 +62,42 @@ <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"> +<p>Now that you know how to get started, let's take a look at what Erlang.mk can do for you.</p> <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"> +<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> +<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> +<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> +<p>Erlang.mk will automatically <a href="../relx">generate releases</a> when applicable. It can also <a href="../escript">generate escripts</a>.</p> <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 +<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> +<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> +<p>You can get a list of all packages known to Erlang.mk by using the <code>search</code> target:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make search</tt></pre> +</div></div> +<p>You can also use this target to search across all packages, for example to find all packages related to Cowboy:</p> +<div class="listingblock"><div class="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"> +<pre><tt>$ make search <font color="#009900">q</font><font color="#990000">=</font>cowboy</tt></pre> +</div></div> <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"> +<p>Erlang.mk supports <em>EDoc</em> and <em>Asciidoc</em>.</p> +<p><a href="../edoc">EDoc</a> generates HTML documentation directly from your source code.</p> +<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> +<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> <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"> +<p>Erlang.mk supports a lot of different testing and static analysis tools.</p> +<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> +<p>Erlang.mk comes with features to make your life easier when setting up and using <a href="../ci">Continuous integration</a>.</p> +<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> <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> +<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> + diff --git a/docs/en/erlang.mk/1/guide/ports/index.html b/docs/en/erlang.mk/1/guide/ports/index.html index 39744520..99478311 100644 --- a/docs/en/erlang.mk/1/guide/ports/index.html +++ b/docs/en/erlang.mk/1/guide/ports/index.html @@ -62,193 +62,97 @@ <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"> +<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> +<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> +<!-- @todo something for easier bootstrapping--> <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 +<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 class="listingblock"><div class="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 +<pre><tt><font color="#009900">C_SRC_DIR =</font> <font color="#009900">$(CURDIR)</font>/my_nif_source</tt></pre> +</div></div> +<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 class="listingblock"><div class="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> +<pre><tt><font color="#009900">C_SRC_ENV =</font> <font color="#009900">$(C_SRC_DIR)</font>/erlang_env.mk</tt></pre> +</div></div> +<p>It contains a few variable definitions for the environment used for the build:</p> +<dl><dt><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> +<dt><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> +<dt><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"> +</dl> <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 +<p>Erlang.mk will automatically run <code>make</code> if it detects a Makefile in <em>$(C_SRC_DIR)/Makefile</em>.</p> +<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> +<p>You can include the <em>env.mk</em> file to benefit from the Erlang environment detection:</p> +<div class="listingblock"><div class="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"> +<pre><tt>include env.mk</tt></pre> +</div></div> <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 +<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> +<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 class="listingblock"><div class="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> +<pre><tt><font color="#009900">C_SRC_TYPE =</font> executable</tt></pre> +</div></div> +<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> +<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> +<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> +<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> +<dl><dt><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> +<dt><code>CFLAGS</code></dt> +<dd><p>C compiler flags.</p> </dd> -<dt class="hdlist1"> -<code>CXXFLAGS</code> -</dt> -<dd> -<p> - C++ compiler flags. -</p> +<dt><code>CXXFLAGS</code></dt> +<dd><p>C++ compiler flags.</p> </dd> -<dt class="hdlist1"> -<code>LDFLAGS</code> -</dt> -<dd> -<p> - Linker flags. -</p> +<dt><code>LDFLAGS</code></dt> +<dd><p>Linker flags.</p> </dd> -<dt class="hdlist1"> -<code>LDLIBS</code> -</dt> -<dd> -<p> - Libraries to link against. -</p> +<dt><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"> +</dl> +<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> <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 +<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> +<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> +<p>By adding this to your Makefile all five variables will be made available to sub-Makefiles when building C code:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#990000">app-c_src:</font> <b><font color="#0000FF">export</font></b> CC <font color="#990000">+=</font> +<font color="#990000">app-c_src:</font> <b><font color="#0000FF">export</font></b> CFLAGS <font color="#990000">+=</font> +<font color="#990000">app-c_src:</font> <b><font color="#0000FF">export</font></b> CPPFLAGS <font color="#990000">+=</font> +<font color="#990000">app-c_src:</font> <b><font color="#0000FF">export</font></b> LDFLAGS <font color="#990000">+=</font> +<font color="#990000">app-c_src:</font> <b><font color="#0000FF">export</font></b> LDLIBS <font color="#990000">+=</font></tt></pre> +</div></div> +<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 class="listingblock"><div class="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> +<pre><tt><font color="#990000">app-c_src:</font> <b><font color="#0000FF">export</font></b> CFLAGS <font color="#990000">=</font> -O<font color="#993399">3</font></tt></pre> +</div></div> + diff --git a/docs/en/erlang.mk/1/guide/releases/index.html b/docs/en/erlang.mk/1/guide/releases/index.html index f731a3d9..09b27b21 100644 --- a/docs/en/erlang.mk/1/guide/releases/index.html +++ b/docs/en/erlang.mk/1/guide/releases/index.html @@ -62,217 +62,159 @@ <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"> +<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> <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 +<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 class="listingblock"><div class="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"> +<pre><tt><font color="#009900">RELX_CONFIG =</font> <font color="#009900">$(CURDIR)</font>/webchat.config</tt></pre> +</div></div> +<p>Relx does not need to be installed. Erlang.mk will download and build it automatically.</p> +<p>The Relx executable will be saved in the <em>$(RELX)</em> file. This location defaults to <em>$(CURDIR)/relx</em> and can be overriden.</p> +<!-- @todo You can use a custom location by ???--> <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 +<p>You can specify additional Relx options using the <code>RELX_OPTS</code> variable. For example, to enable <code>dev_mode</code>:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">RELX_OPTS =</font> -d <b><font color="#0000FF">true</font></b></tt></pre> +</div></div> +<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 class="listingblock"><div class="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"> +<pre><tt><font color="#009900">RELX_OUTPUT_DIR =</font> /path/to/staging/directory</tt></pre> +</div></div> <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 +<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 class="listingblock"><div class="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 +<pre><tt>$ make</tt></pre> +</div></div> +<p>If you need to generate the release, and only the release, the <code>rel</code> target can be used:</p> +<div class="listingblock"><div class="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"> +<pre><tt>$ make rel</tt></pre> +</div></div> +<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> <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 +<p>Erlang.mk provides a convenience function for running the release with one simple command:</p> +<div class="listingblock"><div class="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"> +<pre><tt>$ make run</tt></pre> +</div></div> +<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> <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 +<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> +<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> +<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> +<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> +<p>Once all this is done, you can build the tarball for the release upgrade:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ make relup</tt></pre> +</div></div> +<p>This will create an archive at the root directory of the release, <code>$RELX_OUTPUT_DIR/example/example-2.tar.gz</code>.</p> +<p>Move the archive to the correct location on the running node. From the release's root directory:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ mkdir releases<font color="#990000">/</font><font color="#993399">2</font><font color="#990000">/</font> +$ mv path/to/example-<font color="#993399">2</font><font color="#990000">.</font>tar<font color="#990000">.</font>gz releases<font color="#990000">/</font><font color="#993399">2</font><font color="#990000">/</font></tt></pre> +</div></div> +<p>Finally, upgrade the release:</p> +<div class="listingblock"><div class="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 +<pre><tt>$ bin/example_release upgrade <font color="#FF0000">"2/example_release"</font></tt></pre> +</div></div> +<p>Or on Windows:</p> +<div class="listingblock"><div class="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"> +<pre><tt>$ bin/example_release<font color="#990000">.</font>cmd upgrade <font color="#FF0000">"2/example_release"</font></tt></pre> +</div></div> +<p>Your release was upgraded!</p> <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 +<p>There is a <strong>workaround</strong> to get the semver value which is generated by Relx based on VCS history.</p> +<p>Create a file <em>rel/version</em> with only one line inside:</p> +<div class="listingblock"><div class="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 +<pre><tt>{{ <font color="#FF6600">release_version</font> }}</tt></pre> +</div></div> +<p>Add/Update the <code>overlay</code> section of your <code>relx.config</code>:</p> +<div class="listingblock"><div class="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 +<pre><tt>{<font color="#FF6600">overlay</font>, [ + {<font color="#FF6600">template</font>, <font color="#FF0000">"rel/version"</font>, <font color="#FF0000">"version"</font>} +]}<font color="#990000">.</font></tt></pre> +</div></div> +<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 class="listingblock"><div class="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 +<font color="#993399">1.0</font><font color="#990000">.</font><font color="#993399">0</font><font color="#990000">+</font>build<font color="#990000">.</font><font color="#993399">11</font><font color="#990000">.</font>ref5612aa0</tt></pre> +</div></div> +<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 class="listingblock"><div class="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 +<pre><tt><font color="#009900">$(</font>shell cat <font color="#009900">$(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)</font></tt></pre> +</div></div> +<p>For example:</p> +<div class="listingblock"><div class="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 +<font color="#009900">APP_VERSION =</font> <font color="#009900">$(</font>shell cat <font color="#009900">$(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)</font> +<font color="#990000">myrecipe:</font> all + echo APP_VERSION <font color="#990000">=</font> <font color="#009900">$(APP_VERSION)</font></tt></pre> +</div></div> +<p>Would output:</p> +<div class="listingblock"><div class="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> +<font color="#990000">...</font> +<font color="#990000">===></font> Starting relx build process <font color="#990000">...</font> +<font color="#990000">===></font> Resolving OTP Applications from directories<font color="#990000">:</font> /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> + /home/username/example<font color="#990000">/</font>_rel +<font color="#990000">===></font> Resolved example-<font color="#993399">0.3</font><font color="#990000">.</font><font color="#993399">10</font><font color="#990000">+</font>build<font color="#990000">.</font><font color="#993399">11</font><font color="#990000">.</font>ref5612aa0 +<font color="#990000">===></font> Including Erts from /usr/lib/erlang +<font color="#990000">===></font> release successfully created<font color="#990000">!</font> +<font color="#990000">===></font> tarball /home/username/example<font color="#990000">/</font>_rel/example/example-<font color="#993399">0.3</font><font color="#990000">.</font><font color="#993399">10</font><font color="#990000">+</font>build<font color="#990000">.</font><font color="#993399">11</font><font color="#990000">.</font>ref5612aa0<font color="#990000">.</font>tar<font color="#990000">.</font>gz successfully created<font color="#990000">!</font> +echo APP_VERSION <font color="#990000">=</font> <font color="#993399">0.3</font><font color="#990000">.</font><font color="#993399">10</font><font color="#990000">+</font>build<font color="#990000">.</font><font color="#993399">11</font><font color="#990000">.</font>ref5612aa0 +APP_VERSION <font color="#990000">=</font> <font color="#993399">0.3</font><font color="#990000">.</font><font color="#993399">10</font><font color="#990000">+</font>build<font color="#990000">.</font><font color="#993399">11</font><font color="#990000">.</font>ref5612aa0</tt></pre> +</div></div> + diff --git a/docs/en/erlang.mk/1/guide/sfx/index.html b/docs/en/erlang.mk/1/guide/sfx/index.html index b9942e94..10b337f4 100644 --- a/docs/en/erlang.mk/1/guide/sfx/index.html +++ b/docs/en/erlang.mk/1/guide/sfx/index.html @@ -62,55 +62,36 @@ <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"> +<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> +<p>This allows you to package the release as a single file that can then be executed.</p> +<p>This feature is currently experimental. Feedback is much appreciated.</p> <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 +<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 class="listingblock"><div class="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"> +<pre><tt>$ make <font color="#009900">SFX</font><font color="#990000">=</font><font color="#993399">1</font></tt></pre> +</div></div> +<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> <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 +<p>Simply execute the script to get started:</p> +<div class="listingblock"><div class="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> +<pre><tt>$ <font color="#990000">./</font>_rel/hello_world<font color="#990000">.</font>run +Exec<font color="#990000">:</font> /tmp/tmp<font color="#990000">.</font>3eeEq7E1ta/erts-<font color="#993399">8.1</font>/bin/erlexec <font color="#990000">...</font> +Root<font color="#990000">:</font> /tmp/tmp<font color="#990000">.</font>3eeEq7E1ta +/tmp/tmp<font color="#990000">.</font>3eeEq7E1ta +Erlang/OTP <font color="#993399">19</font> <font color="#990000">[</font>erts-<font color="#993399">8.1</font><font color="#990000">]</font> <font color="#990000">[</font><b><font color="#0000FF">source</font></b><font color="#990000">]</font> <font color="#990000">[</font><font color="#993399">64</font>-bit<font color="#990000">]</font> <font color="#990000">[</font>smp<font color="#990000">:</font><font color="#993399">4</font><font color="#990000">:</font><font color="#993399">4</font><font color="#990000">]</font> <font color="#990000">...</font> + +Eshell V8<font color="#990000">.</font><font color="#993399">1</font> <font color="#990000">(</font>abort with <font color="#990000">^</font>G<font color="#990000">)</font> +<font color="#990000">(</font>hello_world@localhost<font color="#990000">)</font><font color="#993399">1</font><font color="#990000">></font></tt></pre> +</div></div> +<p>As you can see the archive is extracted to a temporary directory before the release can be started.</p> +<p>The self-extracting script currently only supports starting the release in <code>console</code> mode.</p> + diff --git a/docs/en/erlang.mk/1/guide/shell/index.html b/docs/en/erlang.mk/1/guide/shell/index.html index ff3f3524..c287d6b1 100644 --- a/docs/en/erlang.mk/1/guide/shell/index.html +++ b/docs/en/erlang.mk/1/guide/shell/index.html @@ -62,66 +62,48 @@ <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"> +<p>Erlang.mk provides a convenient target for starting a shell with all the paths set properly to experiment with your code.</p> <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 +<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 class="listingblock"><div class="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 +<pre><tt><font color="#009900">SHELL_DEPS =</font> kjell</tt></pre> +</div></div> +<p>Dependencies are downloaded and compiled the first time you run the <code>make shell</code> command.</p> +<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 class="listingblock"><div class="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 +<pre><tt><font color="#009900">SHELL_ERL =</font> <font color="#009900">$(DEPS_DIR)</font>/kjell/bin/kjell</tt></pre> +</div></div> +<p>You can specify additional options to be used when starting the shell using the <code>SHELL_OPTS</code> variable:</p> +<div class="listingblock"><div class="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 +<pre><tt><font color="#009900">SHELL_OPTS =</font> -setcookie chocolate</tt></pre> +</div></div> +<p>Any of the usual <code>erl</code> options can be used, including <code>-eval</code>:</p> +<div class="listingblock"><div class="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"> +<pre><tt><font color="#009900">SHELL_OPTS =</font> -eval <font color="#FF0000">'my_app:run()'</font></tt></pre> +</div></div> <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 +<p>To start the shell, all you need is the following command:</p> +<div class="listingblock"><div class="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 class="paragraph"><p>Note that the <code>shell</code> target does not build the application. To do it, -use either the <code>app</code> target or, if you want to include also test -modules, the <code>test-build</code> target.</p></div> -</div> -</div> +<pre><tt>$ make shell</tt></pre> +</div></div> +<p>The shell can be stopped as usual with a double Ctrl+C or the command <code>q().</code>.</p> +<p>Note that the <code>shell</code> target does not build the application. To do it, use either the <code>app</code> target or, if you want to include also test modules, the <code>test-build</code> target.</p> + diff --git a/docs/en/erlang.mk/1/guide/sphinx/index.html b/docs/en/erlang.mk/1/guide/sphinx/index.html index 379dc8a6..c6956ea4 100644 --- a/docs/en/erlang.mk/1/guide/sphinx/index.html +++ b/docs/en/erlang.mk/1/guide/sphinx/index.html @@ -62,34 +62,16 @@ <h1 class="lined-header"><span>Sphinx documentation</span></h1> -<div class="paragraph"><p>Erlang.mk includes targets for running the -<a href="http://www.sphinx-doc.org/">Sphinx documentation generator</a>, which can produce -documentation in various formats, like HTML, man pages, Texinfo, LaTeX, and -others.</p></div> -<div class="sect1"> +<p>Erlang.mk includes targets for running the <a href="http://www.sphinx-doc.org/">Sphinx documentation generator</a>, which can produce documentation in various formats, like HTML, man pages, Texinfo, LaTeX, and others.</p> <h2 id="_writing_sphinx_documentation">Writing Sphinx documentation</h2> -<div class="sectionbody"> -<div class="paragraph"><p>Sphinx generates documentation from a set of -<a href="http://www.sphinx-doc.org/en/stable/rest.html">reST</a> documents. There is -a <a href="http://www.sphinx-doc.org/en/stable/tutorial.html">quick start guide</a> on -Sphinx' website. For Erlang.mk, we’ll set up a minimal environment instead.</p></div> -</div> -</div> -<div class="sect1"> +<p>Sphinx generates documentation from a set of <a href="http://www.sphinx-doc.org/en/stable/rest.html">reST</a> documents. There is a <a href="http://www.sphinx-doc.org/en/stable/tutorial.html">quick start guide</a> on Sphinx' website. For Erlang.mk, we'll set up a minimal environment instead.</p> <h2 id="_basic_setup">Basic setup</h2> -<div class="sectionbody"> -<div class="paragraph"><p>By default, Erlang.mk expects Sphinx documentation to be placed in the <em>doc</em> -directory, with <em>doc/conf.py</em> config file in particular. The file contains -information about the project, among the other things.</p></div> -<div class="paragraph"><p>A minimal <em>doc/conf.py</em> will look similar to this:</p></div> -<div class="listingblock"> -<div class="content"></div></div> -<div class="paragraph"><p>It points to a <em>doc/index.rst</em> document. A simple skeleton includes a table of -contents for all documentation, and links to generated index of terms and -a search page:</p></div> -<div class="listingblock"> -<div class="content"> -<pre><code>My Project +<p>By default, Erlang.mk expects Sphinx documentation to be placed in the <em>doc</em> directory, with <em>doc/conf.py</em> config file in particular. The file contains information about the project, among the other things.</p> +<p>A minimal <em>doc/conf.py</em> will look similar to this:</p> +<div class="listingblock"><div class="content">source-highlight: could not find a language definition for python +</div></div> +<p>It points to a <em>doc/index.rst</em> document. A simple skeleton includes a table of contents for all documentation, and links to generated index of terms and a search page:</p> +<div class="listingblock"><div class="content"><pre>My Project ========== Contents: @@ -103,104 +85,51 @@ Indices and tables ================== * :ref:`genindex` -* :ref:`search`</code></pre> -</div></div> -<div class="paragraph"><p>The skeleton above has a link to one other page, <em>doc/other_page.rst</em>. Simple -header with some text will do for now:</p></div> -<div class="listingblock"> -<div class="content"> -<pre><code>Other Page +* :ref:`search`</pre></div></div> +<p>The skeleton above has a link to one other page, <em>doc/other_page.rst</em>. Simple header with some text will do for now:</p> +<div class="listingblock"><div class="content"><pre>Other Page ========== -Lorem ipsum dolor sit amet...</code></pre> -</div></div> -<div class="paragraph"><p>The files above are enough to build HTML documentation to the <em>html</em> directory.</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +Lorem ipsum dolor sit amet...</pre></div></div> +<p>The files above are enough to build HTML documentation to the <em>html</em> directory.</p> +<div class="listingblock"><div class="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 <span style="font-style: italic"><span style="color: #9A1900"># all the docs, including EDoc and AsciiDoc if applicable</span></span> -$ make sphinx <span style="font-style: italic"><span style="color: #9A1900"># Sphinx docs specifically</span></span></tt></pre></div></div> -</div> -</div> -<div class="sect1"> +<pre><tt>$ make docs <i><font color="#9A1900"># all the docs, including EDoc and AsciiDoc if applicable</font></i> +$ make sphinx <i><font color="#9A1900"># Sphinx docs specifically</font></i></tt></pre> +</div></div> <h2 id="_erlang_mk_configuration">Erlang.mk configuration</h2> -<div class="sectionbody"> -<div class="paragraph"><p>Erlang.mk defaults to the following configuration:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<p>Erlang.mk defaults to the following configuration:</p> +<div class="listingblock"><div class="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">SPHINX_FORMATS =</span> html -<span style="color: #009900">SPHINX_SOURCE =</span> doc</tt></pre></div></div> -<div class="paragraph"><p>To change the location of Sphinx sources, you need to set the <code>$(SPHINX_SOURCE)</code> -variable. The <em>conf.py</em> file should also be placed in that directory, unless you -specify <code>$(SPHINX_CONFDIR)</code>.</p></div> -<div class="paragraph"><p>The variable <code>$(SPHINX_OPTS)</code> allows to provide options to <code>sphinx-build</code>, which -is particularly useful for <code>-D name=value</code> options. You can even forego -<em>doc/conf.py</em> file, using <code>-D name=value</code> in combination with the <code>-C</code> option, -though in this case you will need to manually call <code>make sphinx</code> or add the -<code>sphinx</code> target to dependencies of <code>docs</code>.</p></div> -<div class="paragraph"><p>The <code>$(SPHINX_FORMATS)</code> variable lists formats to generate. By default only HTML -is generated, but it can also build man pages or LaTeX documents which can later -be converted to PDF. See the -<a href="http://www.sphinx-doc.org/en/stable/invocation.html#cmdoption-sphinx-build-b">description of the <code>-b</code> option</a> -for <code>sphinx-build</code> for a list of known formats.</p></div> -<div class="paragraph"><p>Formats are by default generated to a directory called after the format -(<em>html</em> for HTML, <em>man</em> for man pages, and so on). To change this behaviour -for a specific format, you can set the <code>$(sphinx_$(format)_output)</code> variable, e.g. -<code>$(sphinx_html_output)</code> for <em>html</em> or <code>$(sphinx_man_output)</code> for <em>man</em>. -There are also <code>$(sphinx_$(format)_opts)</code> variables for setting <code>sphinx-build</code> -options for a single format only.</p></div> -</div> -</div> -<div class="sect1"> +<pre><tt><font color="#009900">SPHINX_FORMATS =</font> html +<font color="#009900">SPHINX_SOURCE =</font> doc</tt></pre> +</div></div> +<p>To change the location of Sphinx sources, you need to set the <code>$(SPHINX_SOURCE)</code> variable. The <em>conf.py</em> file should also be placed in that directory, unless you specify <code>$(SPHINX_CONFDIR)</code>.</p> +<p>The variable <code>$(SPHINX_OPTS)</code> allows to provide options to <code>sphinx-build</code>, which is particularly useful for <code>-D name=value</code> options. You can even forego <em>doc/conf.py</em> file, using <code>-D name=value</code> in combination with the <code>-C</code> option, though in this case you will need to manually call <code>make sphinx</code> or add the <code>sphinx</code> target to dependencies of <code>docs</code>.</p> +<p>The <code>$(SPHINX_FORMATS)</code> variable lists formats to generate. By default only HTML is generated, but it can also build man pages or LaTeX documents which can later be converted to PDF. See the <a href="http://www.sphinx-doc.org/en/stable/invocation.html#cmdoption-sphinx-build-b">description of the `-b` option</a> for <code>sphinx-build</code> for a list of known formats.</p> +<p>Formats are by default generated to a directory called after the format (<em>html</em> for HTML, <em>man</em> for man pages, and so on). To change this behaviour for a specific format, you can set the <code>$(sphinx_$(format)_output)</code> variable, e.g. <code>$(sphinx_html_output)</code> for <em>html</em> or <code>$(sphinx_man_output)</code> for <em>man</em>. There are also <code>$(sphinx_$(format)_opts)</code> variables for setting <code>sphinx-build</code> options for a single format only.</p> <h2 id="_generating_man_pages">Generating man pages</h2> -<div class="sectionbody"> -<div class="paragraph"><p>To generate man pages, you need to include <code>man</code> in <code>$(SPHINX_FORMATS)</code> in -your Makefile and define the <code>man_pages</code> option in <em>doc/conf.py</em>:</p></div> -<div class="listingblock"> -<div class="content"></div></div> -<div class="paragraph"><p>As the -<a href="http://www.sphinx-doc.org/en/stable/config.html#options-for-manual-page-output">Sphinx documentation</a> -indicates, the structure is:</p></div> -<div class="ulist"><ul> -<li> -<p> -<code>doc_name</code> is the path to the man page’s source (relative <code>$(SPHINX_SOURCE)</code>), - without the <em>.rst</em> suffix -</p> +<p>To generate man pages, you need to include <code>man</code> in <code>$(SPHINX_FORMATS)</code> in your Makefile and define the <code>man_pages</code> option in <em>doc/conf.py</em>:</p> +<div class="listingblock"><div class="content">source-highlight: could not find a language definition for python +</div></div> +<p>As the <a href="http://www.sphinx-doc.org/en/stable/config.html#options-for-manual-page-output">Sphinx documentation</a> indicates, the structure is:</p> +<ul><li><code>doc_name</code> is the path to the man page's source (relative <code>$(SPHINX_SOURCE)</code>), without the <em>.rst</em> suffix </li> -<li> -<p> -<code>page_name</code> is the name of the resulting man page, which will be used as a base - for the output file name and will be included in the generated man page -</p> +<li><code>page_name</code> is the name of the resulting man page, which will be used as a base for the output file name and will be included in the generated man page </li> -<li> -<p> -<code>Manpage Title</code> is a short, one-line description, which will be included in - the generated man page on a position that’s used by the <code>apropos</code> command -</p> +<li><code>Manpage Title</code> is a short, one-line description, which will be included in the generated man page on a position that's used by the <code>apropos</code> command </li> -<li> -<p> -<code>Page Author</code> (or more of them) will be included in the autogenerated <code>AUTHOR</code> - section. Leaving this field empty disables generating the <code>AUTHOR</code> section -</p> +<li><code>Page Author</code> (or more of them) will be included in the autogenerated <code>AUTHOR</code> section. Leaving this field empty disables generating the <code>AUTHOR</code> section </li> -<li> -<p> -<code>1</code> is the man page section number -</p> +<li><code>1</code> is the man page section number </li> -</ul></div> -<div class="paragraph"><p>With the above configuration (and Erlang.mk’s defaults), <em>doc/doc_name.rst</em> will -be used to generate <em>man/page_name.1</em>.</p></div> -</div> -</div> +</ul> +<p>With the above configuration (and Erlang.mk's defaults), <em>doc/doc_name.rst</em> will be used to generate <em>man/page_name.1</em>.</p> + diff --git a/docs/en/erlang.mk/1/guide/triq/index.html b/docs/en/erlang.mk/1/guide/triq/index.html index 5b478a0b..5f1f5608 100644 --- a/docs/en/erlang.mk/1/guide/triq/index.html +++ b/docs/en/erlang.mk/1/guide/triq/index.html @@ -62,44 +62,43 @@ <h1 class="lined-header"><span>Triq</span></h1> -<div class="paragraph"><p><a href="https://triq.gitlab.io/">Triq</a> is a QuickCheck-like library for -property-based testing. Erlang.mk automates discovery and checking of -Triq properties.</p></div> -<div class="paragraph"><p>To run all tests (including Triq):</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<p><a href="https://triq.gitlab.io/">Triq</a> is a QuickCheck-like library for property-based testing. Erlang.mk automates discovery and checking of Triq properties.</p> +<p>To run all tests (including Triq):</p> +<div class="listingblock"><div class="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 Triq):</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt>$ make tests</tt></pre> +</div></div> +<p>To run all tests and static checks (including Triq):</p> +<div class="listingblock"><div class="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 Triq separately:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt>$ make check</tt></pre> +</div></div> +<p>You can also run Triq separately:</p> +<div class="listingblock"><div class="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 triq</tt></pre></div></div> -<div class="paragraph"><p>To check properties from a single module:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt>$ make triq</tt></pre> +</div></div> +<p>To check properties from a single module:</p> +<div class="listingblock"><div class="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 triq <span style="color: #009900">t</span><span style="color: #990000">=</span>foo_tests</tt></pre></div></div> -<div class="paragraph"><p>To check a single property:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt>$ make triq <font color="#009900">t</font><font color="#990000">=</font>foo_tests</tt></pre> +</div></div> +<p>To check a single property:</p> +<div class="listingblock"><div class="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 triq <span style="color: #009900">t</span><span style="color: #990000">=</span>foo_tests<span style="color: #990000">:</span>bar</tt></pre></div></div> +<pre><tt>$ make triq <font color="#009900">t</font><font color="#990000">=</font>foo_tests<font color="#990000">:</font>bar</tt></pre> +</div></div> + diff --git a/docs/en/erlang.mk/1/guide/updating/index.html b/docs/en/erlang.mk/1/guide/updating/index.html index 44f5adb4..86e18069 100644 --- a/docs/en/erlang.mk/1/guide/updating/index.html +++ b/docs/en/erlang.mk/1/guide/updating/index.html @@ -62,89 +62,56 @@ <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"> +<p>This chapter describes how to update the <em>erlang.mk</em> file in your repository.</p> <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"> +<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> <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 +<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> +<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 class="listingblock"><div class="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"> +git clone https<font color="#990000">:</font>//github<font color="#990000">.</font>com/ninenines/erlang<font color="#990000">.</font>mk <font color="#990000">.</font>erlang<font color="#990000">.</font>mk<font color="#990000">.</font>build +Cloning into <font color="#FF0000">'.erlang.mk.build'</font><font color="#990000">...</font> +remote<font color="#990000">:</font> Counting objects<font color="#990000">:</font> <font color="#993399">4035</font><font color="#990000">,</font> <b><font color="#0000FF">done</font></b><font color="#990000">.</font> +remote<font color="#990000">:</font> Compressing objects<font color="#990000">:</font> <font color="#993399">100</font><font color="#990000">%</font> <font color="#990000">(</font><font color="#993399">12</font><font color="#990000">/</font><font color="#993399">12</font><font color="#990000">),</font> <b><font color="#0000FF">done</font></b><font color="#990000">.</font> +remote<font color="#990000">:</font> Total <font color="#993399">4035</font> <font color="#990000">(</font>delta <font color="#993399">8</font><font color="#990000">),</font> reused <font color="#993399">4</font> <font color="#990000">(</font>delta <font color="#993399">4</font><font color="#990000">),</font> pack-reused <font color="#993399">4019</font> +Receiving objects<font color="#990000">:</font> <font color="#993399">100</font><font color="#990000">%</font> <font color="#990000">(</font><font color="#993399">4035</font><font color="#990000">/</font><font color="#993399">4035</font><font color="#990000">),</font> <font color="#993399">1.10</font> MiB <font color="#990000">|</font> <font color="#993399">1000.00</font> KiB/s<font color="#990000">,</font> <b><font color="#0000FF">done</font></b><font color="#990000">.</font> +Resolving deltas<font color="#990000">:</font> <font color="#993399">100</font><font color="#990000">%</font> <font color="#990000">(</font><font color="#993399">2442</font><font color="#990000">/</font><font color="#993399">2442</font><font color="#990000">),</font> <b><font color="#0000FF">done</font></b><font color="#990000">.</font> +Checking connectivity<font color="#990000">...</font> <b><font color="#0000FF">done</font></b><font color="#990000">.</font> +<b><font color="#0000FF">if</font></b> <font color="#990000">[</font> -f build<font color="#990000">.</font>config <font color="#990000">];</font> <b><font color="#0000FF">then</font></b> cp build<font color="#990000">.</font>config <font color="#990000">.</font>erlang<font color="#990000">.</font>mk<font color="#990000">.</font>build<font color="#990000">;</font> <b><font color="#0000FF">fi</font></b> +cd <font color="#990000">.</font>erlang<font color="#990000">.</font>mk<font color="#990000">.</font>build <font color="#990000">&&</font> make +make<font color="#990000">[</font><font color="#993399">1</font><font color="#990000">]:</font> Entering directory <font color="#FF0000">'/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'</font> +awk <font color="#FF0000">'FNR==1 && NR!=1{print ""}1'</font> core/core<font color="#990000">.</font>mk index<font color="#990000">/*.</font>mk core/index<font color="#990000">.</font>mk core/deps<font color="#990000">.</font>mk plugins/protobuffs<font color="#990000">.</font>mk core/erlc<font color="#990000">.</font>mk core/docs<font color="#990000">.</font>mk core/test<font color="#990000">.</font>mk plugins/asciidoc<font color="#990000">.</font>mk plugins/bootstrap<font color="#990000">.</font>mk plugins/c_src<font color="#990000">.</font>mk plugins/ci<font color="#990000">.</font>mk plugins/ct<font color="#990000">.</font>mk plugins/dialyzer<font color="#990000">.</font>mk plugins/edoc<font color="#990000">.</font>mk plugins/elvis<font color="#990000">.</font>mk plugins/erlydtl<font color="#990000">.</font>mk plugins/escript<font color="#990000">.</font>mk plugins/eunit<font color="#990000">.</font>mk plugins/relx<font color="#990000">.</font>mk plugins/shell<font color="#990000">.</font>mk plugins/triq<font color="#990000">.</font>mk plugins/xref<font color="#990000">.</font>mk plugins/cover<font color="#990000">.</font>mk <font color="#990000">\</font> + <font color="#990000">|</font> sed <font color="#FF0000">'s/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/'</font> <font color="#990000">></font> erlang<font color="#990000">.</font>mk +make<font color="#990000">[</font><font color="#993399">1</font><font color="#990000">]:</font> Leaving directory <font color="#FF0000">'/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'</font> +cp <font color="#990000">.</font>erlang<font color="#990000">.</font>mk<font color="#990000">.</font>build/erlang<font color="#990000">.</font>mk <font color="#990000">.</font>/erlang<font color="#990000">.</font>mk +rm -rf <font color="#990000">.</font>erlang<font color="#990000">.</font>mk<font color="#990000">.</font>build</tt></pre> +</div></div> +<p>All that's left to do is to commit the file!</p> +<p>Yep, it's that easy.</p> <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 +<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> +<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 class="listingblock"><div class="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 +<pre><tt>$ make -f erlang<font color="#990000">.</font>mk bootstrap <font color="#009900">WITHOUT</font><font color="#990000">=</font><font color="#FF0000">"index plugins/edoc"</font></tt></pre> +</div></div> +<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 class="listingblock"><div class="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> +<pre><tt>$ make erlang-mk <font color="#009900">WITHOUT</font><font color="#990000">=</font>index</tt></pre> +</div></div> +<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> +<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> +<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> + diff --git a/docs/en/erlang.mk/1/guide/why/index.html b/docs/en/erlang.mk/1/guide/why/index.html index a18ba0d2..659a4a99 100644 --- a/docs/en/erlang.mk/1/guide/why/index.html +++ b/docs/en/erlang.mk/1/guide/why/index.html @@ -62,86 +62,30 @@ <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"> +<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> <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"> +<p>Erlang.mk is as fast as it gets.</p> +<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> +<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> <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"> +<p>Erlang.mk is a Makefile.</p> +<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> +<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> <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"> +<p>Erlang.mk is a Makefile.</p> +<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> +<p>Currently using a binary build tool? Good luck with that.</p> <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"> +<p>Erlang.mk isn't written in Erlang.</p> +<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> +<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> <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"> +<p>Erlang.mk doesn't care what your dependencies are written in.</p> +<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> <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> +<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> +<p>Erlang.mk will happily sit in such an environment and behave as you expect it to.</p> + diff --git a/docs/en/erlang.mk/1/guide/xref/index.html b/docs/en/erlang.mk/1/guide/xref/index.html index 6de10fea..8459f374 100644 --- a/docs/en/erlang.mk/1/guide/xref/index.html +++ b/docs/en/erlang.mk/1/guide/xref/index.html @@ -62,7 +62,9 @@ <h1 class="lined-header"><span>Xref</span></h1> -<div class="paragraph"><p>Placeholder chapter.</p></div> +<!-- @todo Write it.--> +<p>Placeholder chapter.</p> + |