[PATCH 3/5] ref-manual/terms.rst: simplify the Source Directory definition

Antonin Godard
2025-12-24T16:24:52Z

Now that we no longer have Poky around, simplify the Source Directory
definition:

- Make references to existing documents that show how to create this
Source Directory.

- This directory contains sources, the layout in which they are
presented does not matter so much, as it can be different and/or
freeform depending on whether we use bitbake-setup or not.

The definition chooses "project" as the name of the source directory
and is the one that should be used when showing examples in the
documentation.

Other parts of the documentation referencing to this as the Poky
repository still have to be updated.

This will also mean that this definition will be used a lot less across
the documentation: in most cases, when the "Source Directory" is
referenced as the Poky repository, it can be replaced by
OpenEmbedded-Core, Bitbake, the documentation, or meta-yocto. We'll keep
this definition around regardless, as it can be useful to denote this
group of directories in a more general sense.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
documentation/ref-manual/terms.rst | 66 +++++++++++---------------------------
1 file changed, 18 insertions(+), 48 deletions(-)

diff --git a/documentation/ref-manual/terms.rst b/documentation/ref-manual/terms.rst
index b7a7679ae..21e30de96 100644
--- a/documentation/ref-manual/terms.rst
+++ b/documentation/ref-manual/terms.rst
@@ -526,20 +526,23 @@ universal, the list includes them just in case:
a software bill of materials`" section of the Development Tasks manual.

:term:`Source Directory`
- This term refers to the directory structure
- created as a result of creating a local copy of the ``poky`` Git
- repository ``git://git.yoctoproject.org/poky`` or expanding a
- released ``poky`` tarball.
+ This term refers to the directory structure created as a result of setting
+ up your environment to build images with the Yocto Project, which can be
+ done in two ways:

- .. note::
+ - Using the ``bitbake-setup`` command-line utility (see :doc:`Setting Up
+ The Environment With bitbake-setup
+ <bitbake:bitbake-user-manual/bitbake-user-manual-environment-setup>`).
+
+ - Manually setting up the :term:`Layers <Layer>` (see
+ :doc:`/dev-manual/poky-manual-setup`).

- Creating a local copy of the
- poky
- Git repository is the recommended method for setting up your
- Source Directory.
+ In either case, the result will be a set of :term:`Layers <Layer>` and a
+ :term:`Build Directory`: this is the Source Directory for your build. The
+ documentation usually denotes this directory with the name "project".

- Sometimes you might hear the term "poky directory" used to refer to
- this directory structure.
+ We present a :term:`Source Directory` structure and its components in the
+ :doc:`/ref-manual/structure` section of the Yocto Project Reference Manual.

.. note::

@@ -547,43 +550,10 @@ universal, the list includes them just in case:
names that contain spaces. Be sure that the Source Directory you
use does not contain these types of names.

- The Source Directory contains BitBake, Documentation, Metadata and
- other files that all support the Yocto Project. Consequently, you
- must have the Source Directory in place on your development system in
- order to do any development using the Yocto Project.
-
- When you create a local copy of the Git repository, you can name the
- repository anything you like. Throughout much of the documentation,
- "poky" is used as the name of the top-level folder of the local copy
- of the poky Git repository. So, for example, cloning the ``poky`` Git
- repository results in a local Git repository whose top-level folder
- is also named "poky".
-
- While it is not recommended that you use tarball extraction to set up
- the Source Directory, if you do, the top-level directory name of the
- Source Directory is derived from the Yocto Project release tarball.
- For example, downloading and unpacking poky tarballs from
- :yocto_dl:`/releases/yocto/&DISTRO_REL_LATEST_TAG;/`
- results in a Source Directory whose root folder is named poky.
-
-
- It is important to understand the differences between the Source
- Directory created by unpacking a released tarball as compared to
- cloning ``git://git.yoctoproject.org/poky``. When you unpack a
- tarball, you have an exact copy of the files based on the time of
- release --- a fixed release point. Any changes you make to your local
- files in the Source Directory are on top of the release and will
- remain local only. On the other hand, when you clone the ``poky`` Git
- repository, you have an active development repository with access to
- the upstream repository's branches and tags. In this case, any local
- changes you make to the local Source Directory can be later applied
- to active development branches of the upstream ``poky`` Git
- repository.
-
- For more information on concepts related to Git repositories,
- branches, and tags, see the
- ":ref:`overview-manual/development-environment:repositories, tags, and branches`"
- section in the Yocto Project Overview and Concepts Manual.
+ The Source Directory contains BitBake, OpenEmbedded-Core (OE-Core),
+ Documentation, Metadata and other files that all support the Yocto Project.
+ Consequently, you must have the Source Directory in place on your
+ development system in order to do any development using the Yocto Project.

:term:`SPDX`
This term means *Software Package Data Exchange*, and is used as an open

--
2.51.0