From: michael.opdenacker@bootlin.com
To: docs@lists.yoctoproject.org
Cc: Michael Opdenacker <michael.opdenacker@bootlin.com>,
Paul Eggleton <paul.eggleton@microsoft.com>
Subject: [kirkstone][PATCH 2/6] dev-manual: update custom distribution section
Date: Thu, 2 May 2024 08:57:17 +0200 [thread overview]
Message-ID: <20240502065721.22607-3-michael.opdenacker@bootlin.com> (raw)
In-Reply-To: <20240502065721.22607-1-michael.opdenacker@bootlin.com>
From: Michael Opdenacker <michael.opdenacker@bootlin.com>
From: Paul Eggleton <bluelightning@bluelightning.org>
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>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.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..0bc386d606 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.
--
2.34.1
next prev parent reply other threads:[~2024-05-02 6:57 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-05-02 6:57 [kirkstone][PATCH 0/6] documentation backports michael.opdenacker
2024-05-02 6:57 ` [kirkstone][PATCH 1/6] ref-manual: variables: Update default INHERIT_DISTRO value michael.opdenacker
2024-05-02 6:57 ` michael.opdenacker [this message]
2024-05-02 6:57 ` [kirkstone][PATCH 3/6] documentation: standards.md: align with master branch michael.opdenacker
2024-05-02 6:57 ` [kirkstone][PATCH 4/6] documentation/poky.yaml.in: drop mesa/sdl from essential host packages michael.opdenacker
2024-05-02 6:57 ` [kirkstone][PATCH 5/6] migration-notes: add release notes for 4.0.18 michael.opdenacker
2024-05-02 6:57 ` [kirkstone][PATCH 6/6] ref-manual: update releases.svg michael.opdenacker
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240502065721.22607-3-michael.opdenacker@bootlin.com \
--to=michael.opdenacker@bootlin.com \
--cc=docs@lists.yoctoproject.org \
--cc=paul.eggleton@microsoft.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).