1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
<!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="plugins.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="plugins_list.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="plugins_usage"></a>Chapter 25. External plugins</h2></div></div></div><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><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_loading_all_plugins_from_a_dependency"></a>25.1. Loading all plugins from a dependency</h2></div></div></div><p>To load plugins from a dependency, all you need to do is add
the dependency name to <code class="literal">DEP_PLUGINS</code> in addition to the list
of dependencies.</p><p>For example, if you have <code class="literal">cowboy</code> in <code class="literal">DEPS</code>, add <code class="literal">cowboy</code> in
<code class="literal">DEP_PLUGINS</code> also:</p><pre class="programlisting">DEPS = cowboy
DEP_PLUGINS = cowboy</pre><p>This will load the file <span class="emphasis"><em>plugins.mk</em></span> in the root folder of
the Cowboy repository.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_loading_one_plugin_from_a_dependency"></a>25.2. Loading one plugin from a dependency</h2></div></div></div><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 class="literal">DEP_PLUGINS = cowboy</code> is equivalent to
writing <code class="literal">DEP_PLUGINS = cowboy/plugins.mk</code>.</p><p>Knowing this, if we were to load the plugin <span class="emphasis"><em>mk/dist.mk</em></span>
from Cowboy and no other, we would write the following in
our Makefile:</p><pre class="programlisting">DEPS = cowboy
DEP_PLUGINS = cowboy/mk/dist.mk</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_writing_external_plugins"></a>25.3. Writing external plugins</h2></div></div></div><p>The <span class="emphasis"><em>plugins.mk</em></span> 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 <span class="emphasis"><em>plugins.mk</em></span> 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
<span class="emphasis"><em>mk/</em></span> folder in your repository, and then include those
individual plugins in <span class="emphasis"><em>plugins.mk</em></span>.</p><p>For example, if you have two plugins <span class="emphasis"><em>mk/dist.mk</em></span> and
<span class="emphasis"><em>mk/templates.mk</em></span>, you could write the following <span class="emphasis"><em>plugins.mk</em></span>
file:</p><pre class="programlisting">THIS := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
include $(THIS)/mk/dist.mk
include $(THIS)/mk/templates.mk</pre><p>The <code class="literal">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></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_early_stage_plugins"></a>25.4. Early-stage plugins</h2></div></div></div><p>Plugins declared in <code class="literal">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 class="literal">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
<span class="emphasis"><em>early-plugins.mk</em></span>. You can specify a filename exactly like you would
have done it with regular plugins.</p><pre class="programlisting"># In your application's Makefile
BUILD_DEPS = common_deps
DEP_EARLY_PLUGINS = common_deps</pre><pre class="programlisting"># In the plugin's early-plugins.mk
DEPS += cowboy
TEST_DEPS = ct_helper
dep_ct_helper = git https://github.com/ninenines/ct_helper master</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_loading_plugins_local_to_the_application"></a>25.5. Loading plugins local to the application</h2></div></div></div><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 <span class="emphasis"><em>mk</em></span>
subdirectory:</p><pre class="programlisting">DEP_PLUGINS = $(PROJECT)/mk/dist.mk</pre><p>This also works with early-stage plugins:</p><pre class="programlisting">DEP_EARLY_PLUGINS = $(PROJECT)/mk/variables.mk</pre><p>Like external plugins, if you do not specify the path to the plugin, it
defaults to <span class="emphasis"><em>plugins.mk</em></span> or <span class="emphasis"><em>early-plugins.mk</em></span>, located at the root of
your application:</p><pre class="programlisting"># Loads ./early-plugins.mk
DEP_EARLY_PLUGINS = $(PROJECT)
# Loads ./plugins.mk
DEP_PLUGINS = $(PROJECT)</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plugins.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plugins.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plugins_list.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>
|
