|
|
<!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}
main h1, main div.chapter>div.titlepage h2{font-size:2em;margin-top:.67em}
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="ports.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="sfx.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="relx"></a>Chapter 9. Releases</h2></div></div></div><p>Erlang.mk relies on <span class="emphasis"><em>Relx</em></span> for generating releases. This
chapter covers the Erlang.mk-specific bits. Consult the
<a class="ulink" href="https://erlware.github.io/relx/" target="_top">Relx website</a> for more information.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_setup"></a>9.1. Setup</h2></div></div></div><p>Erlang.mk will create a release if it detects a Relx configuration
file in the <span class="emphasis"><em>$(RELX_CONFIG)</em></span> location. This defaults to
<span class="emphasis"><em>$(CURDIR)/relx.config</em></span>. You can override it by defining
the variable before including Erlang.mk:</p><pre class="programlisting">RELX_CONFIG = $(CURDIR)/webchat.config</pre><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 <span class="emphasis"><em>$(RELX)</em></span> file. This
location defaults to <span class="emphasis"><em>$(CURDIR)/relx</em></span> and can be overriden.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_configuration"></a>9.2. Configuration</h2></div></div></div><p>You can specify additional Relx options using the <code class="literal">RELX_OPTS</code>
variable. For example, to enable <code class="literal">dev_mode</code>:</p><pre class="programlisting">RELX_OPTS = -d true</pre><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 class="literal">RELX_OUTPUT_DIR</code>. It defaults to the <span class="emphasis"><em>_rel</em></span>
directory. You can also override it:</p><pre class="programlisting">RELX_OUTPUT_DIR = /path/to/staging/directory</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_generating_the_release"></a>9.3. Generating the release</h2></div></div></div><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 <span class="emphasis"><em>$(RELX_CONFIG)</em></span> file. This
means the following command will also build the release:</p><pre class="programlisting">$ make</pre><p>If you need to generate the release, and only the release,
the <code class="literal">rel</code> target can be used:</p><pre class="programlisting">$ make rel</pre><p>Erlang.mk always generates a tarball alongside the release,
which can be directly uploaded to a server. The tarball is
located at <code class="literal">$(RELX_OUTPUT_DIR)/<name>/<name>-<vsn>.tar.gz</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_running_the_release"></a>9.4. Running the release</h2></div></div></div><p>Erlang.mk provides a convenience function for running the
release with one simple command:</p><pre class="programlisting">$ make run</pre><p>This command will also build the project and generate the
release if they weren’t already. It starts the release in
<span class="emphasis"><em>console mode</em></span>, meaning you will also have a shell ready to
use to check things as needed.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_upgrading_a_release"></a>9.5. Upgrading a release</h2></div></div></div><p>Erlang.mk provides a <code class="literal">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 class="ulink" href="http://erlang.org/doc/man/appup.html" target="_top">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 class="literal">1</code>, and the new version is <code class="literal">2</code>. The name of the
release will be <code class="literal">example</code>.</p><p>Once all this is done, you can build the tarball for the
release upgrade:</p><pre class="programlisting">$ make relup</pre><p>This will create an archive at the root directory of the
release, <code class="literal">$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><pre class="programlisting">$ mkdir releases/2/
$ mv path/to/example-2.tar.gz releases/2/</pre><p>Finally, upgrade the release:</p><pre class="programlisting">$ bin/example_release upgrade "2/example_release"</pre><p>Or on Windows:</p><pre class="programlisting">$ bin/example_release.cmd upgrade "2/example_release"</pre><p>Your release was upgraded!</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_getting_relx_semver_value"></a>9.6. Getting Relx semver value</h2></div></div></div><p>There is a <span class="strong"><strong>workaround</strong></span> to get the semver value which is
generated by Relx based on VCS history.</p><p>Create a file <span class="emphasis"><em>rel/version</em></span> with only one line inside:</p><pre class="programlisting">{{ release_version }}</pre><p>Add/Update the <code class="literal">overlay</code> section of your <code class="literal">relx.config</code>:</p><pre class="programlisting">{overlay, [
{template, "rel/version", "version"}
]}.</pre><p>When you run <code class="literal">make rel</code> it creates the file <span class="emphasis"><em>$(RELX_OUTPUT_DIR)/example/version</em></span>
which contains the version value generated by Relx.</p><pre class="programlisting">$ cat _rel/app/release
1.0.0+build.11.ref5612aa0</pre><p>In your <code class="literal">Makefile</code> you can use this simple snippet to get the version,
but please keep in mind that this should depend on the <code class="literal">rel</code> target:</p><pre class="programlisting">$(shell cat $(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)</pre><p>For example:</p><pre class="programlisting">include erlang.mk
APP_VERSION = $(shell cat $(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)
myrecipe: all
echo APP_VERSION = $(APP_VERSION)</pre><p>Would output:</p><pre class="programlisting">$ make myrecipe
...
===> Starting relx build process ...
===> Resolving OTP Applications from directories:
/home/username/example/apps
/home/username/example/deps
/usr/lib/erlang/lib
/home/username/example/_rel
===> Resolved example-0.3.10+build.11.ref5612aa0
===> Including Erts from /usr/lib/erlang
===> release successfully created!
===> tarball /home/username/example/_rel/example/example-0.3.10+build.11.ref5612aa0.tar.gz successfully created!
echo APP_VERSION = 0.3.10+build.11.ref5612aa0
APP_VERSION = 0.3.10+build.11.ref5612aa0</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ports.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="code.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sfx.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>
|
