From dfc5890443a042d1744bce99bc2ecf6e1ebdff5f Mon Sep 17 00:00:00 2001
From: Michael Olbrich <m.olbrich@pengutronix.de>
Date: Wed, 20 Jun 2018 08:20:59 +0200
Subject: doc: add section about creating new templates

Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>
---
 doc/dev_manual.rst | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
index 811fad59d..c638ad019 100644
--- a/doc/dev_manual.rst
+++ b/doc/dev_manual.rst
@@ -1542,3 +1542,81 @@ Enabling this new entry will also run our stages in
 
     $ ptxdist go
 
+Creating new Package Templates
+------------------------------
+
+For larger project it can be convenient to have project specific package
+templates. This can be achieved by either modifying existing templates or
+by creating completely new templates.
+
+Modifying a Template
+~~~~~~~~~~~~~~~~~~~~
+
+A template can be modified by providing new input files. This is easier
+than creating a new template but does not allow to specify new variables to
+substitute in the input files.
+
+PTXdist looks for template files the same way it looks for rules files. The
+only difference is, that it searches in the ``templates/`` subdirectory.
+So a modified ``./rules/templates/template-target-make`` can be used to
+tweak the ``target`` template.
+
+Creating a new Template
+~~~~~~~~~~~~~~~~~~~~~~~
+
+For a completely new template, some bash scripting is required. All shell
+code must be placed in a file named like this:
+``./scripts/lib/ptxd_lib_*.sh``.
+
+The minimum requirement for a new template is:
+-  a shell function that creates the new package
+-  registering the new template
+
+.. code-block:: sh
+
+    ptxd_template_new_mypkg() {
+        # create the package here
+    }
+    export -f ptxd_template_new_mypkg
+    ptxd_template_help_list[${#ptxd_template_help_list[@]}]="mypkg"
+    ptxd_template_help_list[${#ptxd_template_help_list[@]}]="create awsame mypkg package"
+
+PTXdist provides several helper functions to simply the template.
+Using those functions, the package creation process is split into two
+parts:
+
+-  query the user for input and export variables
+-  Create the new package files from the template source files by
+   substituting all instances of ``@<variable>@`` with the value of the
+   corresponding variable.
+
+A simple template function could look like this:
+
+.. code-block:: sh
+
+    ptxd_template_new_mypkg() {
+        ptxd_template_read_basic &&
+        ptxd_template_read "enter download section" DL_SECTION "foobar"
+        ptxd_template_read_author &&
+        export section="local_${dlsection}" &&
+        ptxd_template_write_rules
+    }
+
+This template requires ``rules/templates/template-mypkg-make`` and
+``rules/templates/template-mypkg-in`` as source files. They could be
+derived from the ``target`` template with a simple modification:
+
+.. code-block:: make
+
+    @PACKAGE@_SUFFIX	:= tar.xz
+    @PACKAGE@_URL	:= http://dl.my-company.local/downloads/@DL_SECTION@/$(@PACKAGE@).$(@PACKAGE@_SUFFIX)
+
+The helper functions that are used in the example above are defined in
+``scripts/lib/ptxd_lib_template.sh`` in the PTXdist source tree.
+
+The template is a normal shell function. Arbitrary things can be done here
+to create the new package. The helper functions are just the most
+convenient way to crate simple templates. It is also possible to create
+more files. For examples, the builtin ``genimage`` template creates a extra
+config file for the new package.
+
-- 
cgit v1.2.3