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

[Roland Hieber <rhi@pengutronix.de>]

On Tue, Sep 03, 2019 at 01:50:25PM +0200, Alexander Dahl wrote:
> After discussing these topics in IRC, it seemed reasonable to add some
> explanation on how to create a new layer from scratch.

\o/ someone else did a task on my overlong todo list :D

> 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``

We have done that too sometimes in the past, but if the config files in
the base layer are not in the right versions, the MD5 sum in the config
diffs in the inherited layer will not match. I think this should be
mentioned here.

> +   - Use a Git submodule with a BSP in a folder ``base``.
> +   - Copy over your whole existing BSP to a new subfolder ``base``.

Subtree merges are another possibility, although I've never done one.

> +
> +#. 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

I think you should be able to select the config from base/ directly
without copying them? mol?

> +
> +#. Use ``ptxdist menu`` like usual.

menuconfig? platformconfig? 

> +#. Put your new layer into Git and add configs and delta configs to it.

nit: s/Git/SCM/, or something like that

> +
> +.. _DistroKit: https://www.pengutronix.de/de/software/distrokit.html
> -- 
> 2.20.1
> 
> 
> _______________________________________________
> ptxdist mailing list
> ptxdist@pengutronix.de
> 

-- 
Roland Hieber                     | r.hieber@pengutronix.de     |
Pengutronix e.K.                  | https://www.pengutronix.de/ |
Peiner Str. 6-8, 31137 Hildesheim | Phone: +49-5121-206917-5086 |
Amtsgericht Hildesheim, HRA 2686  | Fax:   +49-5121-206917-5555 |

_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de