1  # aeplugin_rebar3 plugin
 2  
 3  This is a rebar3 plugin for building Aeternity node plugin packages.
 4  
 5  For an example, see [aeplugin_dev_mode](https://github.com/aeternity/aeplugin_dev_mode)
 6  
 7  The plugin ensures that dependencies that are also dependencies of the Aeternity node,
 8  are fetched with the same version as that used by the node the plugin is built for.
 9  
10  By default, dependencies will be checked against the `master` branch of the Aeternity repos,
11  but another branch or tag can be specified, or a local repository on disk can be used.
12  
13  The command `rebar3 ae_plugin` packs the plugin application and all dependencies not
14  already included in the Aeternity node build into a zip (`".ez"`) archive. This archive
15  is then copied (or symlinked) into the `plugins/` archive of the Aeternity node, where it
16  is automatically picked up and extracted into `plugins/lib/`, from where it is then loaded.
17  
18  ## Usage
19  
20  To activate the plugin, add it to the `rebar.config` file of your AE node plugin application.
21  
22  ```erlang
23  {plugins, [
24             {aeplugin_rebar3, {git, "https://github.com/aeternity/aeplugin_rebar3", {branch,"master"}}}
25            ]}.
26  ```
27  
28  ### Specifying the Aeternity root
29  
30  By default, the `master` branch of the [Aeternity repos](https://github.com/aeternity/aeternity) is used.
31  Specifically, the `rebar.lock` file is fetched, and dependency targets and versions are extracted.
32  
33  A different root can be specified in one of two ways, listed in order of priority:
34  
35  1. Create a symbolic link to an Aeternity source package on-disk. Name the link `aeternity`.
36  2. Specify the target as `aeternity_root` in your `rebar.config`.
37     The value can either be `{local, AeternityDir}` or `{git, URI, BranchOrTag}`
38  
39  ```erlang
40  {aeternity_root, {git, "https://github.com/aeternity/aeternity", "master"}}.
41  ```
42  
43  ### Name Aeternity dependencies
44  
45  Dependencies that are also dependencies of the Aeternity node, are listed as `{App, {ae, App}}`.
46  
47  Example:
48  
49  ```erlang
50  {deps, [
51          {lager, {ae, lager}},
52          {cowboy, {ae, cowboy}},
53          {aeserialization, {ae, aeserialization}},
54          {jsx, {ae, jsx}},
55          ...
56         ]}.
57  ```
58  
59  (Strictly speaking, the 2nd element in the `{ae,...}` tuple can be anything, as the plugin
60  currently ignores it. Rebar3 seems to expect a 2-tuple, though.)
61  
62  ### Build the archive file
63  
64  `rebar3 ae_plugin`
65  
66  The `ae_plugin` command depends on `compile`, so the code will be automatically compiled first.
67  
68  The archive file will be placed in the profile build directory (e.g. `_build/default`) of your
69  plugin application, and named `PluginName.ez`. Example:
70  
71  ```
72  aeplugin_dev_mode.ez
73  ```