diff options
| -rw-r--r-- | core/deps.mk | 15 | ||||
| -rw-r--r-- | doc/src/guide/book.asciidoc | 4 | ||||
| -rw-r--r-- | doc/src/guide/external_plugins.asciidoc | 73 |
3 files changed, 92 insertions, 0 deletions
diff --git a/core/deps.mk b/core/deps.mk index 44b822e..4ac58ca 100644 --- a/core/deps.mk +++ b/core/deps.mk @@ -573,3 +573,18 @@ $(foreach dep,$(DEPS),$(eval $(call dep_target,$(dep)))) distclean-deps: $(gen_verbose) rm -rf $(DEPS_DIR) + +# External plugins. + +DEP_PLUGINS ?= + +define core_dep_plugin +-include $(DEPS_DIR)/$(1) + +$(DEPS_DIR)/$(1): $(DEPS_DIR)/$(2) ; +endef + +$(foreach p,$(DEP_PLUGINS),\ + $(eval $(if $(findstring /,$p),\ + $(call core_dep_plugin,$p,$(firstword $(subst /, ,$p))),\ + $(call core_dep_plugin,$p/plugins.mk,$p)))) diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc index e858ae8..e42e5bf 100644 --- a/doc/src/guide/book.asciidoc +++ b/doc/src/guide/book.asciidoc @@ -9,3 +9,7 @@ include::getting_started.asciidoc[Getting started] include::overview.asciidoc[Overview] include::updating.asciidoc[Updating Erlang.mk] + += Advanced + +include::external_plugins.asciidoc[External plugins] diff --git a/doc/src/guide/external_plugins.asciidoc b/doc/src/guide/external_plugins.asciidoc new file mode 100644 index 0000000..e5fdbd7 --- /dev/null +++ b/doc/src/guide/external_plugins.asciidoc @@ -0,0 +1,73 @@ +== 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 eaxmple, if you have two plugins 'mk/dist.mk' and +'mk/templates.mk', you could write the following 'plugins.mk' +file: + +[source,make] +include mk/dist.mk +include mk/templates.mk + +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. |