Message ID | cb839b9d7e58ddf1927685c3fefcd2fa7e551618.1713127068.git.bluelightning@bluelightning.org |
---|---|
State | New |
Headers | show |
Series | [1/9] ref-manual: Add virtual-slash QA check | expand |
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.
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.
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(-)