From 6e4fcfabb728dfa2114a4076a4d8247caf25fe09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 29 Dec 2015 00:29:21 +0100 Subject: Update user guide --- guide/plugins_usage.html | 69 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 guide/plugins_usage.html (limited to 'guide/plugins_usage.html') diff --git a/guide/plugins_usage.html b/guide/plugins_usage.html new file mode 100644 index 0000000..a72e402 --- /dev/null +++ b/guide/plugins_usage.html @@ -0,0 +1,69 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 22. External plugins

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.

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.

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.

22.1. Loading all plugins from a dependency

To load plugins from a dependency, all you need to do is add +the dependency name to DEP_PLUGINS in addition to the list +of dependencies.

For example, if you have cowboy in DEPS, add cowboy in +DEP_PLUGINS also:

DEPS = cowboy
+DEP_PLUGINS = cowboy

This will load the file plugins.mk in the root folder of +the Cowboy repository.

22.2. Loading one plugin from a dependency

Now that we know how to load all plugins, let’s take a look +at how to load one specific plugin from a dependency.

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 DEP_PLUGINS = cowboy is equivalent to +writing DEP_PLUGINS = cowboy/plugins.mk.

Knowing this, if we were to load the plugin mk/dist.mk +from Cowboy and no other, we would write the following in +our Makefile:

DEPS = cowboy
+DEP_PLUGINS = cowboy/mk/dist.mk

22.3. Writing external plugins

The plugins.mk 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 plugins.mk or be separate.

If you are providing more than one plugin with your repository, +the recommended way is to create one file per plugin in the +mk/ folder in your repository, and then include those +individual plugins in plugins.mk.

For example, if you have two plugins mk/dist.mk and +mk/templates.mk, you could write the following plugins.mk +file:

THIS := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
+include $(THIS)/mk/dist.mk
+include $(THIS)/mk/templates.mk

The THIS variable is required to relatively include files.

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.

Prev Up Next
 Home 
+
+ + -- cgit v1.2.3