From 92b54aacc0de5446dd5497c39897b0bbff72e626 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 13 Jun 2018 09:54:12 +0200 Subject: Rebuild using Asciideck --- .../erlang.mk/1/guide/external_plugins/index.html | 178 +++++++-------------- 1 file changed, 58 insertions(+), 120 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 da596541..3eaac0d6 100644 --- a/docs/en/erlang.mk/1/guide/external_plugins/index.html +++ b/docs/en/erlang.mk/1/guide/external_plugins/index.html @@ -62,154 +62,92 @@

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.

-
+

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.

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

-
- -
+
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)
-
-
+
# Loads ./early-plugins.mk
+DEP_EARLY_PLUGINS = $(PROJECT)
+# Loads ./plugins.mk
+DEP_PLUGINS = $(PROJECT)
+ + -- cgit v1.2.3