| Message ID | 20260120-terms-refresh-v2-3-fa49d15b209f@bootlin.com |
|---|---|
| State | New |
| Headers | show |
| Series | Redefine terms now that the Poky repository is obsolete | expand |
Hi Antonin, On 1/20/26 4:17 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. > > A typical Source Directory would look like the following: > > project/ > ├── build/ > └── layers/ > > 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 Not really? The Source Directory will be project/layers/ no? [...] > - 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. > You didn't discuss my feedback on v1 here and it's unchanged, so pasting the same here: 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). Finally, we should probably also s/Source Directory/:term:`Source Directory`/ Cheers, Quentin
On 1/20/26 5:42 PM, Quentin Schulz via lists.yoctoproject.org wrote: > Hi Antonin, > > On 1/20/26 4:17 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. >> >> A typical Source Directory would look like the following: >> >> project/ >> ├── build/ >> └── layers/ >> >> 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 > > Not really? The Source Directory will be project/layers/ no? > Reading your next patch, no, it'll indeed be project/. This confuses me tbh, I don't really like having a Build Directory within the Source directory but eh, what can I do about it :) Ignore this part of the review then. Cheers, Quentin
Hi, On Tue Jan 20, 2026 at 5:42 PM CET, Quentin Schulz via lists.yoctoproject.org wrote: > Hi Antonin, > > On 1/20/26 4:17 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. >> >> A typical Source Directory would look like the following: >> >> project/ >> ├── build/ >> └── layers/ >> >> 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 > > Not really? The Source Directory will be project/layers/ no? No, even though I do find it confusing too to call it Source Directory, it is meant to represent the whole project/ directory as a whole. It was probably more meaningful when poky was there as poky was some source itself. We could rename this term by something else but that would mean replacing it everywhere. > [...] > >> - 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. >> > > You didn't discuss my feedback on v1 here and it's unchanged, so pasting > the same here: I think I've missed it, sorry :/ > 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). For me metadata is what OpenEmbedded-Core contains but could be what meta-openembedded contains: it's recipes, classes, etc. But here I agree it doesn't make sense to be listed. > Also, it doesn't necessarily need to contain the Documentation (e.g. via > a manual setup). True, I'll remove it. > Finally, we should probably also > > s/Source Directory/:term:`Source Directory`/ Thanks, Antonin
diff --git a/documentation/ref-manual/terms.rst b/documentation/ref-manual/terms.rst index d908af4ae..ab8eb6123 100644 --- a/documentation/ref-manual/terms.rst +++ b/documentation/ref-manual/terms.rst @@ -526,20 +526,36 @@ 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>`). + + - Or manually setting up the :term:`Layers <Layer>` (see + :doc:`/dev-manual/poky-manual-setup`). + + 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". + + A typical layout for the :term:`Source Directory` would be: + + .. code-block:: text + + project/ + ├── build/ + └── layers/ - Creating a local copy of the - poky - Git repository is the recommended method for setting up your - Source Directory. + Where the ``layers/`` directory corresponds to the directory containing + :term:`layers <Layer>` for your project, and the ``build/`` directory + corresponds to the :term:`Build Directory`. - 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 + details in the :doc:`/ref-manual/structure` section of the Yocto Project + Reference Manual. .. note:: @@ -547,43 +563,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
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. A typical Source Directory would look like the following: project/ ├── build/ └── layers/ 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 | 79 +++++++++++++++----------------------- 1 file changed, 31 insertions(+), 48 deletions(-)