Initial commit, new website system

1 files changed, 77 insertions, 0 deletions

diff --git a/docs/en/erlang.mk/1/guide/external_plugins.asciidoc b/docs/en/erlang.mk/1/guide/external_plugins.asciidoc
new file mode 100644
index 00000000..d3dafaac
--- /dev/null
+++ b/docs/en/erlang.mk/1/guide/external_plugins.asciidoc
@@ -0,0 +1,77 @@
+[[plugins_usage]]
+== 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:
+
+[source,make]
+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:
+
+[source,make]
+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:
+
+[source,make]
+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.