Redefine terms now that the Poky repository is obsolete
v3 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 v3:
- Rename "project" to "bitbake-builds"
- Apply suggestions from Quentin (thanks!)
- Link to v2: https://patch.msgid.link/[email protected]
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 | 143 +++++++++++-------------- 2 files changed, 74 insertions(+), 80 deletions(-)
---
base-commit: f43bb42123928181d76f81c0343ece777ac143d0
change-id: 20251224-terms-refresh-cdcd529ee508
PATCH v3 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 ``bitbake-builds``: - - 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 bitbake-builds + $ source layers/openembedded-core/oe-init-build-env - - Create the :term:`Build Directory` inside your home directory and - specifically name it ``test-builds``: + - Or provide a path to the :term:`Build Directory` when sourcing + ``oe-init-build-env``. 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 test-builds + $ source bitbake-builds/layers/openembedded-core/oe-init-build-env mybuilds/YP-&DISTRO; - - 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``: + This path can also be an absolute path and be outside of the current + working directory: - .. code-block:: shell + .. code-block:: console - $ source poky/oe-init-build-env mybuilds/YP-&DISTRO; + $ source bitbake-builds/layers/openembedded-core/oe-init-build-env /opt/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 v3 1/5] ref-manual/terms.rst: refresh the Build Directory definition
Hi Antonin,
Quoted 41 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 +11
-8@@ -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 ``bitbake-builds``: - - 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 bitbake-builds + $ source layers/openembedded-core/oe-init-build-env
documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 89
Quoted 10 lines
documentation/ref-manual/terms.rst +5
-3- - Create the :term:`Build Directory` inside your home directory and - specifically name it ``test-builds``: + - Or provide a path to the :term:`Build Directory` when sourcing + ``oe-init-build-env``. 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
You used to have .. code-block:: console in v2 according to b4 diff, that was the right move (and would be consistent with the code-block before and after that one).
Either fix up when merging or send a follow-up patch?
Cheers,
Quentin
PATCH v3 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 v3 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 | 80 +++++++++++++++----------------------- 1 file changed, 32 insertions(+), 48 deletions(-)
documentation/ref-manual/terms.rst +32 -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 "bitbake-builds". + + A typical layout for the :term:`Source Directory` would be: - Creating a local copy of the - poky - Git repository is the recommended method for setting up your - Source Directory. + .. code-block:: text - Sometimes you might hear the term "poky directory" used to refer to - this directory structure. + bitbake-builds/ + ├── build/ + └── layers/ + + 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`. + + 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,11 @@ 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), + 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 v3 3/5] ref-manual/terms.rst: simplify the Source Directory definition
Hi Antonin,
Quoted 11 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
bitbake-builds
Quoted 6 lines
and is the one that should be used when showing examples in the documentation.
A typical Source Directory would look like the following:
project/
Ditto.
[...]
Quoted 1 line
+ The Source Directory contains BitBake, OpenEmbedded-Core (OE-Core),
s/Source Directory/:term:Source Directory/ s/BitBake/:term:BitBake/
s/OpenEmbedded-Core (OE-Core)/:term:OpenEmbedded-Core (OE-Core)/
documentation/ref-manual/terms.rst universal, the list includes them just in case: · line 569
Quoted 3 lines
documentation/ref-manual/terms.rst +3
-0+ and other files that all support the Yocto Project. + + Consequently, you must have the Source Directory in place on your
s/Source Directory/:term:Source Directory/
With those changes,
Thanks!
Quentin
PATCH v3 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 ``bitbake-builds`` as the name of the +:term:`Source Directory`. Here's how to create it: + +.. code-block:: console + + $ mkdir bitbake-builds + $ cd bitbake-builds + +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
PATCH v3 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, 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