Redefine terms now that the Poky repository is obsolete
v2 cover Redefine terms now that the Poky repository is obsolete
The Poky repository's master branch is no longer updated:
https://git.yoctoproject.org/poky/tree/README
Redefine the terms in ref-manual/terms.rst to adapt to the new intended way to set things up, that is: either using bitbake-setup or manually cloning the oe-core/bitbake/meta-yocto layers.
---
Changes in v2:
- Apply suggestions from Quentin (thanks!)
- Link to v1: https://patch.msgid.link/[email protected]
---
Antonin Godard (5):
ref-manual/terms.rst: refresh the Build Directory definition ref-manual/terms.rst: refresh the OpenEmbedded-Core definition ref-manual/terms.rst: simplify the Source Directory definition dev-manual/poky-manual-setup.rst: mention the Source Directory ref-manual/terms.rst: refresh the OpenEmbedded build system definition
documentation/dev-manual/poky-manual-setup.rst | 11 +- documentation/ref-manual/terms.rst | 142 +++++++++++-------------- 2 files changed, 73 insertions(+), 80 deletions(-)
---
base-commit: b8a56b8b2e8c0417b2f7204f80c79b05d95e9ce4
change-id: 20251224-terms-refresh-cdcd529ee508
PATCH v2 1/5 ref-manual/terms.rst: refresh the Build Directory definition
After the Poky repository obsolescence, refresh the build directory definition. Fix the formatting and indenting issues while at it.
--- documentation/ref-manual/terms.rst | 46 +++++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 21 deletions(-)
documentation/ref-manual/terms.rst +25 -21
@@ -63,36 +63,39 @@ universal, the list includes them just in case: This term refers to the area used by the OpenEmbedded build system for builds. The area is created when you ``source`` the setup environment script that is found in the Source Directory - (i.e. :ref:`ref-manual/structure:``oe-init-build-env```). The + (i.e. :ref:`ref-manual/structure:``oe-init-build-env```, or + ``init-build-env`` when using :doc:`bitbake-setup + <bitbake:bitbake-user-manual/bitbake-user-manual-environment-setup>`). The :term:`TOPDIR` variable points to the :term:`Build Directory`. - You have a lot of flexibility when creating the :term:`Build Directory`. + When setting up the build manually (see :doc:`/dev-manual/poky-manual-setup`), + you have a lot of flexibility when creating the :term:`Build Directory`. Here are some examples that show how to create the directory. The - examples assume your :term:`Source Directory` is named ``poky``: + examples assume your :term:`Source Directory` is named ``project``: - - Create the :term:`Build Directory` inside your Source Directory and let - the name of the :term:`Build Directory` default to ``build``: + - Create the :term:`Build Directory` inside your Source Directory and let + the name of the :term:`Build Directory` default to ``build``: - .. code-block:: shell + .. code-block:: console - $ cd poky - $ source oe-init-build-env + $ cd project + $ source layers/openembedded-core/oe-init-build-env - - Create the :term:`Build Directory` inside your home directory and - specifically name it ``test-builds``: + - Or create the :term:`Build Directory` inside your current working + directory and specifically name it ``test-builds``: - .. code-block:: shell + .. code-block:: console - $ source poky/oe-init-build-env test-builds + $ source project/layers/openembedded-core/oe-init-build-env test-builds - - Provide a directory path and specifically name the - :term:`Build Directory`. Any intermediate folders in the pathname - must exist. This next example creates a :term:`Build Directory` - named ``YP-&DISTRO;`` within the existing directory ``mybuilds``: + - Or provide a directory path and specifically name the + :term:`Build Directory`. Any intermediate folders in the pathname + must exist. This next example creates a :term:`Build Directory` + named ``YP-&DISTRO;`` within the existing directory ``mybuilds``: - .. code-block:: shell + .. code-block:: shell - $ source poky/oe-init-build-env mybuilds/YP-&DISTRO; + $ source project/layers/openembedded-core/oe-init-build-env mybuilds/YP-&DISTRO; .. note::
@@ -100,9 +103,10 @@ universal, the list includes them just in case: temporary directory the build system uses for its work. :term:`TMPDIR` cannot be under NFS. Thus, by default, the :term:`Build Directory` cannot be under NFS. However, if you need the :term:`Build Directory` to be under NFS, you can - set this up by setting :term:`TMPDIR` in your ``local.conf`` file to use a local - drive. Doing so effectively separates :term:`TMPDIR` from :term:`TOPDIR`, which is the - :term:`Build Directory`. + set this up by setting :term:`TMPDIR` in your + :ref:`structure-build-conf-site.conf` file to use a local drive. Doing + so effectively separates :term:`TMPDIR` from :term:`TOPDIR`, which is + the :term:`Build Directory`. :term:`Build Host` The system used to build images in a Yocto Project Development
Signature · 1 line
2.52.0
Re: [docs] [PATCH v2 1/5] ref-manual/terms.rst: refresh the Build Directory definition
Hi Antonin,
Quoted 37 lines · Antonin Godard via lists.yoctoproject.org
After the Poky repository obsolescence, refresh the build directory definition. Fix the formatting and indenting issues while at it.
Signed-off-by Antonin Godard <[email protected]>--- documentation/ref-manual/terms.rst | 46 +++++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 21 deletions(-)documentation/ref-manual/terms.rst +9
-6@@ -63,36 +63,39 @@ universal, the list includes them just in case: This term refers to the area used by the OpenEmbedded build system for builds. The area is created when you ``source`` the setup environment script that is found in the Source Directory - (i.e. :ref:`ref-manual/structure:``oe-init-build-env```). The + (i.e. :ref:`ref-manual/structure:``oe-init-build-env```, or + ``init-build-env`` when using :doc:`bitbake-setup + <bitbake:bitbake-user-manual/bitbake-user-manual-environment-setup>`). The :term:`TOPDIR` variable points to the :term:`Build Directory`. - You have a lot of flexibility when creating the :term:`Build Directory`. + When setting up the build manually (see :doc:`/dev-manual/poky-manual-setup`), + you have a lot of flexibility when creating the :term:`Build Directory`. Here are some examples that show how to create the directory. The - examples assume your :term:`Source Directory` is named ``poky``: + examples assume your :term:`Source Directory` is named ``project``: - - Create the :term:`Build Directory` inside your Source Directory and let - the name of the :term:`Build Directory` default to ``build``: + - Create the :term:`Build Directory` inside your Source Directory and let + the name of the :term:`Build Directory` default to ``build``: - .. code-block:: shell + .. code-block:: console
documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 86
Quoted 10 lines
documentation/ref-manual/terms.rst +4
-4- $ cd poky - $ source oe-init-build-env + $ cd project + $ source layers/openembedded-core/oe-init-build-env - - Create the :term:`Build Directory` inside your home directory and - specifically name it ``test-builds``: + - Or create the :term:`Build Directory` inside your current working + directory and specifically name it ``test-builds``:
suggestion: to make more digestable:
Or create the :term:Build Directory named ``test-builds`` inside the current working directory
documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 91
Quoted 11 lines
documentation/ref-manual/terms.rst +3
-6- .. code-block:: shell + .. code-block:: console - $ source poky/oe-init-build-env test-builds + $ source project/layers/openembedded-core/oe-init-build-env test-builds - - Provide a directory path and specifically name the - :term:`Build Directory`. Any intermediate folders in the pathname - must exist. This next example creates a :term:`Build Directory` - named ``YP-&DISTRO;`` within the existing directory ``mybuilds``: + - Or provide a directory path and specifically name the
suggestion:
Or provide a path relative to the current working directory as :term:Build Directory.
documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 92
Quoted 1 line
documentation/ref-manual/terms.rst +1
-0+ :term:`Build Directory`. Any intermediate folders in the pathname
suggestion:
Any parent folder of :term:Build Directory must exist.
documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 93
Quoted 1 line
documentation/ref-manual/terms.rst +1
-0+ must exist. This next example creates a :term:`Build Directory`
s/ / /
documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 98
Quoted 7 lines
documentation/ref-manual/terms.rst +3
-2+ named ``YP-&DISTRO;`` within the existing directory ``mybuilds``: - .. code-block:: shell + .. code-block:: shell - $ source poky/oe-init-build-env mybuilds/YP-&DISTRO; + $ source project/layers/openembedded-core/oe-init-build-env mybuilds/YP-&DISTRO;
question: do we support absolute paths?
Seems like something we could add a word for here? I think we do but I've never tried.
Cheers,
Quentin
PATCH v2 2/5 ref-manual/terms.rst: refresh the OpenEmbedded-Core definition
In reply to Antonin GodardAfter the Poky repository obsolescence, refresh the OpenEmbedded-Core definition.
--- documentation/ref-manual/terms.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
documentation/ref-manual/terms.rst +2 -2
@@ -424,8 +424,8 @@ universal, the list includes them just in case: recipes. The result is a tightly controlled and an quality-assured core set of recipes. - You can see the Metadata in the ``meta`` directory of the Yocto - Project :yocto_git:`Source Repositories </poky>`. + You can browse the source of :term:`OpenEmbedded-Core (OE-Core)` at + :oe_git:`openembedded-core </openembedded-core>`. :term:`Package` In the context of the Yocto Project, this term refers to a
Signature · 1 line
2.52.0
PATCH v2 3/5 ref-manual/terms.rst: simplify the Source Directory definition
In reply to Antonin GodardNow 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.
--- documentation/ref-manual/terms.rst | 79 +++++++++++++++----------------------- 1 file changed, 31 insertions(+), 48 deletions(-)
documentation/ref-manual/terms.rst +31 -48
@@ -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
Signature · 1 line
2.52.0
Re: [docs] [PATCH v2 3/5] ref-manual/terms.rst: simplify the Source Directory definition
Hi Antonin,
Quoted 20 lines · Antonin Godard via lists.yoctoproject.org
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/
Quoted 7 lines
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?
[...]
documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 569
Quoted 9 lines
documentation/ref-manual/terms.rst +4
-4- 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
Re: [docs] [PATCH v2 3/5] ref-manual/terms.rst: simplify the Source Directory definition
Quoted 26 lines · Quentin Schulz via lists.yoctoproject.org
Hi Antonin,
Quoted 23 lines · Antonin Godard via lists.yoctoproject.org
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.
Quoted 7 lines
Quoted 4 lines
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
Re: [docs] [PATCH v2 3/5] ref-manual/terms.rst: simplify the Source Directory definition
In reply to Quentin SchulzHi,
Quoted 26 lines · Quentin Schulz via lists.yoctoproject.org
Hi Antonin,
Quoted 23 lines · Antonin Godard via lists.yoctoproject.org
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.
Quoted 6 lines
Quoted 4 lines
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.
Quoted 12 lines
[...]
documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 569
Quoted 9 lines
documentation/ref-manual/terms.rst +4
-4- 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.
Quoted 2 lines
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 :/
Quoted 2 lines
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.
Quoted 2 lines
Also, it doesn't necessarily need to contain the Documentation (e.g. via a manual setup).
True, I'll remove it.
Quoted 3 lines
Finally, we should probably also
s/Source Directory/:term:
Source Directory/
Thanks,
Antonin
Signature · 3 lines
Antonin Godard, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
PATCH v2 4/5 dev-manual/poky-manual-setup.rst: mention the Source Directory
In reply to Antonin GodardAfter switching to the new definition of "Source Directory", i.e. the base directory for your project (which used to be poky), mention it in this document on manually setting up the layers for a project. As stated in terms.rst, use "project" for the directory name.
--- documentation/dev-manual/poky-manual-setup.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-)
documentation/dev-manual/poky-manual-setup.rst +10 -1
@@ -22,7 +22,16 @@ release or a Long Term Support release. Once you complete the setup instructions for your machine (see the :doc:`/ref-manual/system-requirements` section of the Yocto Project Reference -Manual), you need to get a copy of the different :term:`layers <Layer>` needed +Manual), create a :term:`Source Directory`: the base directory for your project. +Throughout the documentation, we will use ``project`` as the name of the +:term:`Source Directory`. Here's how to create it: + +.. code-block:: console + + $ mkdir project + $ cd project + +You need to get a copy of the different :term:`layers <Layer>` needed to setup the :term:`Poky` reference distribution on your build host. Use the following commands:
Signature · 1 line
2.52.0
Re: [docs] [PATCH v2 4/5] dev-manual/poky-manual-setup.rst: mention the Source Directory
Hi Antonin,
Quoted 6 lines · Antonin Godard via lists.yoctoproject.org
After switching to the new definition of "Source Directory", i.e. the base directory for your project (which used to be poky), mention it in this document on manually setting up the layers for a project. As stated in
terms.rst, use "project" for the directory name.Signed-off-by Antonin Godard <[email protected]>
Thanks!
Quentin
PATCH v2 5/5 ref-manual/terms.rst: refresh the OpenEmbedded build system definition
In reply to Antonin GodardRemove the mention of Poky containing BitBake, just mention BitBake.
--- documentation/ref-manual/terms.rst | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-)
documentation/ref-manual/terms.rst +5 -8
@@ -401,14 +401,11 @@ universal, the list includes them just in case: section for details. :term:`OpenEmbedded Build System` - The build system specific to the Yocto - Project. The OpenEmbedded build system is based on another project - known as "Poky", which uses :term:`BitBake` as the task - executor. Throughout the Yocto Project documentation set, the - OpenEmbedded build system is sometimes referred to simply as "the - build system". If other build systems, such as a host or target build - system are referenced, the documentation clearly states the - difference. + The build system used by the Yocto Project, using :term:`Bitbake` as the + task executor. Throughout the Yocto Project documentation set, the + OpenEmbedded build system is sometimes referred to simply as "the build + system". If other build systems, such as a host or target build system are + referenced, the documentation clearly states the difference. .. note::
Signature · 1 line
2.52.0
Re: [docs] [PATCH v2 5/5] ref-manual/terms.rst: refresh the OpenEmbedded build system definition
Hi Antonin,
Quoted 15 lines · Antonin Godard via lists.yoctoproject.org
Remove the mention of Poky containing BitBake, just mention BitBake.
Signed-off-by Antonin Godard <[email protected]>--- documentation/ref-manual/terms.rst | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-)documentation/ref-manual/terms.rst +0
-0@@ -401,14 +401,11 @@ universal, the list includes them just in case: section for details. :term:`OpenEmbedded Build System`
documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 405
Quoted 10 lines
documentation/ref-manual/terms.rst +2
-8- The build system specific to the Yocto - Project. The OpenEmbedded build system is based on another project - known as "Poky", which uses :term:`BitBake` as the task - executor. Throughout the Yocto Project documentation set, the - OpenEmbedded build system is sometimes referred to simply as "the - build system". If other build systems, such as a host or target build - system are referenced, the documentation clearly states the - difference. + The build system used by the Yocto Project, using :term:`Bitbake` as the + task executor. Throughout the Yocto Project documentation set, the
s/ set// ?
But that already existed before this patch, so
Thanks!
Quentin