[ptxdist] [RFC PATCH] doc: Add section on creating new layers

[Alexander Dahl <ada@thorsis.com>]

After discussing these topics in IRC, it seemed reasonable to add some
explanation on how to create a new layer from scratch.

Signed-off-by: Alexander Dahl <ada@thorsis.com>
---
 doc/dev_manual.rst | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
index d79ebdba7..746f3d695 100644
--- a/doc/dev_manual.rst
+++ b/doc/dev_manual.rst
@@ -1631,6 +1631,8 @@ 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.
 
+.. _layers:
+
 Layers in PTXdist
 -----------------
 
@@ -1740,3 +1742,32 @@ layer.
 
 The make macros that provide these features are currently used by the
 barebox and kernel packages and templates.
+
+Creating a new Layer
+~~~~~~~~~~~~~~~~~~~~
+
+Adding new layers on top of an already existing BSP is easy:
+
+#. Create an empty folder, e.g. next to the existing BSP.
+#. The lower layer is just a folder named ``base`` (see layers_ above). You
+   may do one of the following (or something else you consider convenient):
+
+   - Create a symbolic link ``base`` to an outside laying BSP folder. For
+     an easy start, you can try this method with DistroKit_ for example:
+     ``$ ln -s ../DistroKit base``
+   - Use a Git submodule with a BSP in a folder ``base``.
+   - Copy over your whole existing BSP to a new subfolder ``base``.
+
+#. If needed select **ptxconfig** and/or **platformconfig** after copying
+   that file from the lower layer to your new layer:
+
+.. code-block:: text
+
+   $ mkdir -p configs/platform-v7a
+   $ cp base/configs/platform-v7a/platformconfig configs/platform-v7a/
+   $ ptxdist platform configs/platform-v7a/platformconfig
+
+#. Use ``ptxdist menu`` like usual.
+#. Put your new layer into Git and add configs and delta configs to it.
+
+.. _DistroKit: https://www.pengutronix.de/de/software/distrokit.html
-- 
2.20.1


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de