diff options
Diffstat (limited to 'guide/getting_started.html')
| -rw-r--r-- | guide/getting_started.html | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/guide/getting_started.html b/guide/getting_started.html new file mode 100644 index 0000000..3ffaa9a --- /dev/null +++ b/guide/getting_started.html @@ -0,0 +1,164 @@ +<!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} +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="ch02.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="ulink" href="updating.asciidoc" target="_top">Updating Erlang.mk</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="ulink" href="deps.asciidoc" target="_top">Packages and dependencies</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="ulink" href="relx.asciidoc" target="_top">Releases</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> |