|
|
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<title>Erlang.mk User Guide</title>
<style type="text/css"><!--
body{background:white;color:black;font-family:"Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;justify-content:center;margin:0 auto;padding:0;width:600px}
header {align-items:center;display:flex;justify-content:center}
header nav.left{text-align:right;width:150px}
header nav.right{text-align:left;width:150px}
header nav a{display:block;margin:1.5em 1em}
main{margin-top:2em;text-align:justify}
main h2, main h3{margin-top:2em}
a{color:#d9230f;text-decoration:none}
a:hover{text-decoration:underline}
a.xref{display:none}
h1, h2, h3{font-weight:normal}
div.navfooter{margin-bottom:1em}
--></style>
</head>
<body>
<header>
<nav class="left">
<a href="index.html">User guide</a>
<a href="getting_started.html">Tutorials</a>
</nav>
<a href="/" class="logo"><img src="../res/logo-small.png" alt="Erlang.mk" title="Erlang.mk: A build tool for Erlang that just works" height="200" width="206"/></a>
<nav class="right">
<a href="https://github.com/ninenines/erlang.mk/tree/master/index">470+ packages</a>
<a href="https://github.com/ninenines/erlang.mk/issues">Issues?</a>
</nav>
</header>
<main>
<div class="navheader"><table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="installation.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="overview.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="getting_started"></a>Chapter 2. Getting started</h1></div></div></div><p>This chapter explains how to get started using Erlang.mk.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_creating_a_folder_for_your_project"></a>2.1. Creating a folder for your project</h2></div></div></div><p>The first step is always to create a new folder that will
contain your project.</p><pre class="programlisting">$ mkdir hello_joe
$ cd hello_joe</pre><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 <span class="emphasis"><em>$HOME/ninenines/cowboy</em></span> for
the Cowboy project.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_downloading_erlang_mk"></a>2.2. Downloading Erlang.mk</h2></div></div></div><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><pre class="programlisting">$ wget https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk</pre><p>Or:</p><pre class="programlisting">$ curl https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk</pre><p>Alternatively, just <a class="ulink" href="https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk" target="_top">click on this link</a>.</p><p>Make sure you put the file inside the folder we created previously.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_getting_started_with_otp_applications"></a>2.3. Getting started with OTP applications</h2></div></div></div><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 class="literal">bootstrap</code> target:</p><pre class="programlisting">$ make -f erlang.mk bootstrap</pre><p>Something similar to the following snippet will then appear
on your screen:</p><pre class="programlisting">git clone https://github.com/ninenines/erlang.mk .erlang.mk.build
Cloning into '.erlang.mk.build'...
remote: Counting objects: 4035, done.
remote: Compressing objects: 100% (12/12), done.
remote: Total 4035 (delta 8), reused 4 (delta 4), pack-reused 4019
Receiving objects: 100% (4035/4035), 1.10 MiB | 784.00 KiB/s, done.
Resolving deltas: 100% (2442/2442), done.
Checking connectivity... done.
if [ -f build.config ]; then cp build.config .erlang.mk.build; fi
cd .erlang.mk.build && make
make[1]: Entering directory '/home/essen/tmp/hello_joe/.erlang.mk.build'
awk 'FNR==1 && NR!=1{print ""}1' core/core.mk index/*.mk core/index.mk core/deps.mk plugins/protobuffs.mk core/erlc.mk core/docs.mk core/test.mk plugins/asciidoc.mk plugins/bootstrap.mk plugins/c_src.mk plugins/ci.mk plugins/ct.mk plugins/dialyzer.mk plugins/edoc.mk plugins/elvis.mk plugins/erlydtl.mk plugins/escript.mk plugins/eunit.mk plugins/relx.mk plugins/shell.mk plugins/triq.mk plugins/xref.mk plugins/cover.mk \
| sed 's/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/' > erlang.mk
make[1]: Leaving directory '/home/essen/tmp/hello_joe/.erlang.mk.build'
cp .erlang.mk.build/erlang.mk ./erlang.mk
rm -rf .erlang.mk.build</pre><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 class="link" href="updating.html" title="Chapter 4. Updating Erlang.mk">Updating Erlang.mk</a>
<a class="xref" href="updating.html" title="Chapter 4. Updating Erlang.mk">Chapter 4, <em>Updating Erlang.mk</em></a> chapter for more
information.</p><p>Of course, the generated project can now be compiled:</p><pre class="programlisting">$ make</pre><p>Cheers!</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_getting_started_with_otp_libraries"></a>2.4. Getting started with OTP libraries</h2></div></div></div><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 class="literal">bootstrap-lib</code> target:</p><pre class="programlisting">$ make -f erlang.mk bootstrap-lib</pre><p>Erlang.mk will once again bootstrap itself and generate all
the files for your project. You can now compile it:</p><pre class="programlisting">$ make</pre><p>Enjoy!</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_getting_started_with_otp_releases"></a>2.5. Getting started with OTP releases</h2></div></div></div><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 class="literal">bootstrap-rel</code> target for this purpose:</p><pre class="programlisting">$ make bootstrap-rel</pre><p>This target can be combined with <code class="literal">bootstrap</code> or <code class="literal">bootstrap-lib</code> to
create a project that will build a release:</p><pre class="programlisting">$ make -f erlang.mk bootstrap-lib bootstrap-rel</pre><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 class="link" href="deps.html" title="Chapter 7. Packages and dependencies">Packages and dependencies</a>
<a class="xref" href="deps.html" title="Chapter 7. Packages and dependencies">Chapter 7, <em>Packages and dependencies</em></a>
chapter for more information.</p><p>When you run <code class="literal">make</code> from now on, Erlang.mk will compile your
project and build the release:</p><pre class="programlisting">$ make
APP hello_joe.app.src
GEN distclean-relx-rel
GEN /home/essen/tmp/hello_joe/relx
===> Starting relx build process ...
===> Resolving OTP Applications from directories:
/home/essen/tmp/hello_joe/ebin
/usr/lib/erlang/lib
/home/essen/tmp/hello_joe/deps
===> Resolved hello_joe_release-1
===> Including Erts from /usr/lib/erlang
===> release successfully created!</pre><p>The first time you run this command, Erlang.mk will download
<span class="emphasis"><em>relx</em></span>, 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 class="link" href="relx.html" title="Chapter 9. Releases">Releases</a>
<a class="xref" href="relx.html" title="Chapter 9. Releases">Chapter 9, <em>Releases</em></a>
chapter for various tips to speed up build time during
development.</p><p>You can start the release using the <span class="emphasis"><em>./_rel/hello_joe_release/bin/hello_joe_release</em></span>
script, or simply run <code class="literal">make run</code>. The latter will also compile
your project and build the release if it wasn’t already:</p><pre class="programlisting">$ make run
APP hello_joe.app.src
GEN distclean-relx-rel
===> Starting relx build process ...
===> Resolving OTP Applications from directories:
/home/essen/tmp/hello_joe/ebin
/usr/lib/erlang/lib
/home/essen/tmp/hello_joe/deps
===> Resolved hello_joe_release-1
===> Including Erts from /usr/lib/erlang
===> release successfully created!
Exec: /home/essen/tmp/hello_joe/_rel/hello_joe_release/erts-7.0/bin/erlexec -boot /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/hello_joe_release -boot_var ERTS_LIB_DIR /home/essen/tmp/hello_joe/_rel/hello_joe_release/erts-7.0/../lib -env ERL_LIBS /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/lib -config /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/sys.config -args_file /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/vm.args -- console
Root: /home/essen/tmp/hello_joe/_rel/hello_joe_release
/home/essen/tmp/hello_joe/_rel/hello_joe_release
heart_beat_kill_pid = 16389
Erlang/OTP 18 [erts-7.0] [source] [64-bit] [smp:4:4] [async-threads:10] [hipe] [kernel-poll:false]
Eshell V7.0 (abort with ^G)
([email protected])1></pre><p>Simple as that!</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_using_spaces_instead_of_tabs"></a>2.6. Using spaces instead of tabs</h2></div></div></div><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 class="literal">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><pre class="programlisting">$ make -f erlang.mk bootstrap SP=2</pre><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 class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_using_templates"></a>2.7. Using templates</h2></div></div></div><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 class="literal">list-templates</code>
target:</p><pre class="programlisting">$ make list-templates
Available templates: cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server ranch_protocol supervisor</pre><p>To generate a module, let’s say a <code class="literal">gen_server</code>, all you need to
do is to call <code class="literal">make new</code> with the appropriate arguments:</p><pre class="programlisting">$ make new t=gen_server n=my_server</pre><p>This will create a module located in <span class="emphasis"><em>src/my_server.erl</em></span>
using the <code class="literal">gen_server</code> template.</p><p>This module is automatically compiled the next time you run
<code class="literal">make</code>:</p><pre class="programlisting">$ make
ERLC my_server.erl
APP hello_joe.app.src</pre><p>All that’s left to do is to open it in your favorite editor
and make it do something!</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_getting_help"></a>2.8. Getting help</h2></div></div></div><p>During development, if you don’t remember the name of a target,
you can always run <code class="literal">make help</code>:</p><pre class="programlisting">$ make help
erlang.mk (version 1.2.0-642-gccd2b9f) is distributed under the terms of the ISC License.
Copyright (c) 2013-2015 Loïc Hoguin <[email protected]>
Usage: [V=1] make [target]...
Core targets:
all Run deps, app and rel targets in that order
app Compile the project
deps Fetch dependencies (if needed) and compile them
search q=... Search for a package in the built-in index
rel Build a release for this project, if applicable
docs Build the documentation for this project
install-docs Install the man pages for this project
check Compile and run all tests and analysis for this project
tests Run the tests for this project
clean Delete temporary and output files from most targets
distclean Delete all temporary and output files
help Display this help and exit
erlang-mk Update erlang.mk to the latest version
Bootstrap targets:
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 t=TPL n=NAME Generate a module NAME based on the template TPL
list-templates List available templates
...</pre><p>This guide should provide any other answer. If not, please
open a ticket on <a class="ulink" href="https://github.com/ninenines/erlang.mk/issues" target="_top">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 class="ulink" href="mailto:[email protected]" target="_top">[email protected]</a>.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="installation.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="overview.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div>
</main>
</body>
</html>
|
