From a6f9a450af99a7a95848dde671de658bb53a43dc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Thu, 21 Nov 2024 15:55:37 +0100
Subject: Move templates outside the source .mk files

Templates now no longer use Make variables for substitution
but instead replace strings with their equivalent:

  template_name: Corresponds to n=template_name
  project_name:  Corresponds to $(PROJECT) or in=project_name

This allows defining templates outside of Makefiles. For
example an external plugin could define their templates
in templates/my_template.erl and then have the following
in the included Makefile:

  tpl_my_template = $(file < $(THIS)/templates/my_template.erl)

By default the created file will be in src/template_name.erl.
This can be overriden with the tplp_* variable:

  tplp_my_template = src/model/my_template.erl

Substitution is applied both to the template contents and
to its path.

In addition, attempting to overwrite an existing file when
creating a template will result in failure.
---
 doc/src/guide/external_plugins.asciidoc | 28 ++++++++++++++++++++++++++--
 doc/src/guide/getting_started.asciidoc  | 14 +++++++++++++-
 2 files changed, 39 insertions(+), 3 deletions(-)

(limited to 'doc')

diff --git a/doc/src/guide/external_plugins.asciidoc b/doc/src/guide/external_plugins.asciidoc
index 5f165f5..bb42f1a 100644
--- a/doc/src/guide/external_plugins.asciidoc
+++ b/doc/src/guide/external_plugins.asciidoc
@@ -90,7 +90,7 @@ help-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.
+your applications, a regular plugin 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
@@ -111,7 +111,7 @@ DEPS += cowboy
 TEST_DEPS = ct_helper
 dep_ct_helper = git https://github.com/ninenines/ct_helper master
 
-=== Loading  plugins local to the application
+=== 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
@@ -138,3 +138,27 @@ your application:
 DEP_EARLY_PLUGINS = $(PROJECT)
 # Loads ./plugins.mk
 DEP_PLUGINS = $(PROJECT)
+
+=== Adding templates via plugins
+
+Plugins may add templates either from within their Makefile or from
+an external file. The recommended method is to use an external file;
+however do note it only works for Make 4 and above:
+
+[source,make]
+THIS := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
+tpl_test_mk = $(file < $(THIS)/templates/my_template.erl)
+
+With 'templates/my_template.erl' containing:
+
+[source,erlang]
+-module(template_name).
+
+Erlang.mk will do string substitution replacing the following
+strings with their equivalent:
+
+* `template_name`: the name provided by the user
+* `project_name`: either `$(PROJECT)` or the target application's name
+* `template_sp`: internal; propagates whitespace settings to Makefiles
+* `rel_deps_dir`: internal; path to deps/* from within an apps/* Makefile
+* `rel_root_dir`: internal; path to top-level directory from within an apps/* Makefile
diff --git a/doc/src/guide/getting_started.asciidoc b/doc/src/guide/getting_started.asciidoc
index 5f782ca..c1e7589 100644
--- a/doc/src/guide/getting_started.asciidoc
+++ b/doc/src/guide/getting_started.asciidoc
@@ -271,8 +271,20 @@ You can list all available templates with the `list-templates`
 target:
 
 [source,bash]
+----
 $ make list-templates
-Available templates: cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server gen_statem ranch_protocol supervisor
+Available templates:
+    cowboy_http_h
+    cowboy_loop_h
+    cowboy_rest_h
+    cowboy_websocket_h
+    gen_fsm
+    gen_server
+    gen_statem
+    module
+    ranch_protocol
+    supervisor
+----
 
 To generate a module, let's say a `gen_server`, all you need to
 do is to call `make new` with the appropriate arguments:
-- 
cgit v1.2.3