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

Quentin Schulz
2026-01-15T10:23:13Z

Hi Antonin,

On 12/24/25 5:24 PM, Antonin Godard via lists.yoctoproject.org wrote:
> 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.
>

It'd help to provide the expected directory layout in the commit log at
least.

> 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".

Can we have a code-block here with the typical layout so it's a bit more
visual?

Something like:

project/
├── build/
└── layers/

Also, don't we have a config/ subdirectory when using bitbake-setup?

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

Isn't Metadata what we used to say about the content of OE-Core? This
way of listing implies to me OE-Core isn't metadata (it is).

Also, it doesn't necessarily need to contain the Documentation (e.g. via
a manual setup).

Cheers,
Quentin