From b5d4cb91f80c833795a2d87050c3674bb7aecdc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 3 Oct 2017 13:39:41 +0200 Subject: Update Hugo, docs --- .../erlang.mk/1/guide/external_plugins/index.html | 257 ++++++++++++--------- 1 file changed, 152 insertions(+), 105 deletions(-) (limited to 'docs/en/erlang.mk/1/guide/external_plugins') diff --git a/docs/en/erlang.mk/1/guide/external_plugins/index.html b/docs/en/erlang.mk/1/guide/external_plugins/index.html index 13d83701..6a901281 100644 --- a/docs/en/erlang.mk/1/guide/external_plugins/index.html +++ b/docs/en/erlang.mk/1/guide/external_plugins/index.html @@ -7,7 +7,7 @@ - + Nine Nines: External plugins @@ -67,116 +67,163 @@

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.

-
-

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:

-
-
-

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

-
-
-
-

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:

-
-
-
-
-
-

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:

-
-
-

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.

-
-
-
-

Early-stage plugins

-
-

Plugins declared in DEP_PLUGINS 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 -DEP_EARLY_PLUGINS variable instead. Plugins listed in this variable -are loaded near the beginning of Erlang.mk Otherwise, they work exactly -the same.

-

If you only give the name of a dependency, the default file loaded is -early-plugins.mk. You can specify a filename exactly like you would -have done it with regular plugins.

-
-
-
-
-
-
-
-

Loading plugins local to the application

-
-

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.

-

For example, the following Makefile loads a plugin in the mk -subdirectory:

-
-
-

This also works with early-stage plugins:

-
-
-

Like external plugins, if you do not specify the path to the plugin, it -defaults to plugins.mk or early-plugins.mk, located at the root of -your application:

-
-
-
-
+

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.

+
+

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.

+
+
+
+

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
+
+
+
+

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.

+
+
+
+

Early-stage plugins

+
+

Plugins declared in DEP_PLUGINS 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 +DEP_EARLY_PLUGINS variable instead. Plugins listed in this variable +are loaded near the beginning of Erlang.mk Otherwise, they work exactly +the same.

+

If you only give the name of a dependency, the default file loaded is +early-plugins.mk. You can specify a filename exactly like you would +have done it with regular plugins.

+
+
+
# In your application's Makefile
+BUILD_DEPS = common_deps
+DEP_EARLY_PLUGINS = common_deps
+
+
+
# In the plugin's early-plugins.mk
+DEPS += cowboy
+TEST_DEPS = ct_helper
+dep_ct_helper = git https://github.com/ninenines/ct_helper master
+
+
+
+

Loading plugins local to the application

+
+

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.

+

For example, the following Makefile loads a plugin in the mk +subdirectory:

+
+
+
DEP_PLUGINS = $(PROJECT)/mk/dist.mk
+

This also works with early-stage plugins:

+
+
+
DEP_EARLY_PLUGINS = $(PROJECT)/mk/variables.mk
+

Like external plugins, if you do not specify the path to the plugin, it +defaults to plugins.mk or early-plugins.mk, located at the root of +your application:

+
+
+
# Loads ./early-plugins.mk
+DEP_EARLY_PLUGINS = $(PROJECT)
+# Loads ./plugins.mk
+DEP_PLUGINS = $(PROJECT)
+
+
+ + +