Re: [PATCH 6/9] dev-manual: update custom distribution section

[Michael Opdenacker <michael.opdenacker@bootlin.com>]

Hi Paul,

On 4/14/24 at 22:43, Paul Eggleton wrote:
> In keeping with the addition of the motd message pointing out that
> the poky DISTRO is a reference distribution, adjust the opening of the
> Creating Your Own Distribution section to match. Additionally, add a
> section on the end pointing out what users need to consider if they just
> take a copy of the poky distribution and modify it.
>
> Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> ---
>   .../dev-manual/custom-distribution.rst        | 34 ++++++++++++++++---
>   1 file changed, 30 insertions(+), 4 deletions(-)
>
> diff --git a/documentation/dev-manual/custom-distribution.rst b/documentation/dev-manual/custom-distribution.rst
> index 47faed0d04..93a1961d17 100644
> --- a/documentation/dev-manual/custom-distribution.rst
> +++ b/documentation/dev-manual/custom-distribution.rst
> @@ -4,10 +4,16 @@ Creating Your Own Distribution
>   ******************************
>   
>   When you build an image using the Yocto Project and do not alter any
> -distribution :term:`Metadata`, you are
> -creating a Poky distribution. If you wish to gain more control over
> -package alternative selections, compile-time options, and other
> -low-level configurations, you can create your own distribution.
> +distribution :term:`Metadata`, you are using the ``poky`` distribution.
> +``poky`` is explicitly a *reference* distribution for testing and
> +development purposes. It enables most hardware and software features
> +so that they can be tested, but this also means that from a security
> +point of view the attack surface is very large. Additionally, at some
> +point it is likely that you will want to gain more control over package
> +alternative selections, compile-time options, and other low-level
> +configurations. For both of these reasons, if you are using the Yocto
> +Project for production use then you are strongly encouraged to create
> +your own distribution.
>   
>   To create your own distribution, the basic steps consist of creating
>   your own distribution layer, creating your own distribution
> @@ -107,3 +113,23 @@ layer. The following steps provide some more detail:
>      For information on append files, see the
>      ":ref:`dev-manual/layers:appending other layers metadata with your layer`"
>      section.
> +
> +Copying and modifying the ``poky`` distribution
> +===============================================
> +
> +Instead of creating a custom distribution from scratch as per above, you may
> +wish to start your custom distribution configuration by copying the ``poky``
> +distribution provided within the ``meta-poky`` layer and then modifying it.
> +This is fine, however if you do this you should keep the following in mind:
> +
> +-  Every reference to ``poky`` needs to be updated in your copy so that it
> +   will still apply. This includes override usage within files (e.g. ``:poky``)
> +   and in directory names. This is a good opportunity to evaluate each one of
> +   these customizations to see if they are needed for your use case.
> +
> +-  Unless you also intend to use them, the ``poky-tiny``, ``poky-altcfg`` and
> +   ``poky-bleeding`` variants and any references to them can be removed.
> +
> +-  More generally, the ``poky`` distribution configuration enables a lot more
> +   than you likely need for your production use case. You should evaluate *every*
> +   configuration choice made in your copy to determine if it is needed.


Looks good to me, though I replaced "``poky``" by "Poky" (when referring 
to the distro name, not the string) to be consistent with the rest of 
the documentation.
Thanks!
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com