Redefine terms now that the Poky repository is obsolete
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.
---
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 | 10 ++- documentation/ref-manual/terms.rst | 118 ++++++++++--------------- 2 files changed, 55 insertions(+), 73 deletions(-)
---
base-commit: f9042e1da554017fe46460c1fd2bdf8c74b3fa18
change-id: 20251224-terms-refresh-cdcd529ee508
PATCH 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``: + - Create the :term:`Build Directory` inside your home 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``: + - 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.51.0
Re: [docs] [PATCH 1/5] ref-manual/terms.rst: refresh the Build Directory definition
Hi Antonin,
Quoted 35 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 +8
-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
documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 84
Quoted 10 lines
documentation/ref-manual/terms.rst +4
-4+ .. 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``: + - Create the :term:`Build Directory` inside your home directory and
I would either end each item (except the last) in the list with "or" or start each item (except the first) with "or, " so it's clear you only need to follow one or the other.
documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 90
Quoted 8 lines
documentation/ref-manual/terms.rst +3
-2+ 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
How is that creating the build directory within my home directory?
Looks ok to me otherwise.
Cheers,
Quentin
PATCH 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.51.0
Re: [docs] [PATCH 2/5] ref-manual/terms.rst: refresh the OpenEmbedded-Core definition
Hi Antonin,
Quoted 3 lines · Antonin Godard via lists.yoctoproject.org
After the Poky repository obsolescence, refresh the OpenEmbedded-Core definition.
Thanks!
Quentin
PATCH 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.
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 | 66 +++++++++++--------------------------- 1 file changed, 18 insertions(+), 48 deletions(-)
documentation/ref-manual/terms.rst +18 -48
@@ -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
Signature · 1 line
2.51.0
Re: [docs] [PATCH 3/5] ref-manual/terms.rst: simplify the Source Directory definition
Hi Antonin,
Quoted 17 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.
Other parts of the documentation referencing to this as the Poky repository still have to be updated.
Quoted 7 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 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.
Quoted 26 lines
Signed-off-by Antonin Godard <[email protected]>--- documentation/ref-manual/terms.rst | 66 +++++++++++--------------------------- 1 file changed, 18 insertions(+), 48 deletions(-)documentation/ref-manual/terms.rst +7
-5@@ -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>`). +
documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 542
Quoted 10 lines
documentation/ref-manual/terms.rst +5
-4+ - 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?
Quoted 41 lines
documentation/ref-manual/terms.rst +2
-31- 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
documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 554
Quoted 10 lines
documentation/ref-manual/terms.rst +2
-8- 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
PATCH 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 | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-)
documentation/dev-manual/poky-manual-setup.rst +9 -1
@@ -22,7 +22,15 @@ 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. +We will name it ``project`` in the following sections: + +.. 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.51.0
Re: [docs] [PATCH 4/5] dev-manual/poky-manual-setup.rst: mention the Source Directory
Hi Antonin,
Quoted 15 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]>--- documentation/dev-manual/poky-manual-setup.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-)documentation/dev-manual/poky-manual-setup.rst +0
-0
documentation/dev-manual/poky-manual-setup.rst release or a Long Term Support release. · line 27
Quoted 7 lines
documentation/dev-manual/poky-manual-setup.rst +3
-1@@ -22,7 +22,15 @@ 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. +We will name it ``project`` in the following sections: +
What do you think about:
We will name it ``project`` in the following sections
to
Throughout the documentation, we will use ``project`` as the :term:Source Directory. Here's how to create it:
?
Otherwise, change ok to me.
Cheers,
Quentin
PATCH 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 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
documentation/ref-manual/terms.rst +1 -1
@@ -403,7 +403,7 @@ universal, the list includes them just in case: :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 + known as :term:`BitBake` which is 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
Signature · 1 line
2.51.0
Re: [docs] [PATCH 5/5] ref-manual/terms.rst: refresh the OpenEmbedded build system definition
Quoted 12 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 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)documentation/ref-manual/terms.rst +0
-0
documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 409
Quoted 8 lines
documentation/ref-manual/terms.rst +1
-1@@ -403,7 +403,7 @@ universal, the list includes them just in case: :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 + known as :term:`BitBake` which is 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
I think we should replace the first two sentences here with:
The build system used by the Yocto Project, using :term:Bitbake as the task executor.
Best regards,
Signature · 1 line
Paul Barker
Re: [docs] [PATCH 5/5] ref-manual/terms.rst: refresh the OpenEmbedded build system definition
Hi,
Quoted 25 lines · Paul Barker
Quoted 12 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 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)documentation/ref-manual/terms.rst +0
-0documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 409
Quoted 8 lines
documentation/ref-manual/terms.rst +1
-1@@ -403,7 +403,7 @@ universal, the list includes them just in case: :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 + known as :term:`BitBake` which is 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 buildI think we should replace the first two sentences here with:
Quoted 2 lines
The build system used by the Yocto Project, using :term:
Bitbakeas the task executor.
I agree, thanks.
Antonin
Signature · 3 lines
Antonin Godard, Bootlin Embedded Linux and Kernel engineering https://bootlin.com