@@ -81,7 +81,7 @@ directory of that Layer. This directory is what you add to the
``conf/bblayers.conf`` file found in your
:term:`Build Directory`, which is
established after you run the OpenEmbedded build environment setup
-script (i.e. :ref:`ref-manual/structure:``oe-init-build-env```).
+script (i.e. :ref:`structure-core-script`).
Adding the root directory allows the :term:`OpenEmbedded Build System`
to recognize the BSP
layer and from it build an image. Here is an example::
@@ -221,7 +221,7 @@ section.
Checking connectivity... done.
#. *Initialize the Build Environment:* While in the directory where the
- different layers are cloned, run the :ref:`ref-manual/structure:``oe-init-build-env```
+ different layers are cloned, run the :ref:`structure-core-script`
environment setup script located in :term:`OpenEmbedded-Core (OE-Core)` to
define the OpenEmbedded build environment on your build host. ::
@@ -16,6 +16,19 @@ and directories.
names that contain spaces. Be sure that the Source Directory you use
does not contain these types of names.
+For the following sections, we assume the core components of the :term:`Source
+Directory` are organized as follows:
+
+.. code-block:: text
+
+ ├── build/
+ │ └── ...
+ └── layers/
+ ├── bitbake/
+ ├── meta-yocto/
+ ├── openembedded-core/
+ └── yocto-docs/
+
.. _structure-core:
Top-Level Core Components
@@ -67,8 +80,8 @@ about the contents of the :term:`Build Directory`.
.. _handbook:
-``documentation/``
-------------------
+``layers/yocto-docs/``
+----------------------
This directory holds the source for the Yocto Project documentation as
well as templates and tools that allow you to generate PDF and HTML
@@ -76,37 +89,22 @@ versions of the manuals. Each manual is contained in its own sub-folder;
for example, the files for this reference manual reside in the
``ref-manual/`` directory.
+This directory is not mandatory for building with :term:`BitBake`.
+
.. _structure-core-meta:
-``meta/``
----------
+``layers/openembedded-core/meta/``
+----------------------------------
This directory contains the minimal, underlying OpenEmbedded-Core
metadata. The directory holds recipes, common classes, and machine
configuration for strictly emulated targets (``qemux86``, ``qemuarm``,
and so forth.)
-.. _structure-core-meta-poky:
-
-``meta-poky/``
---------------
-
-Designed above the ``meta/`` content, this directory adds just enough
-metadata to define the Poky reference distribution.
-
-.. _structure-core-meta-yocto-bsp:
-
-``meta-yocto-bsp/``
--------------------
-
-This directory contains the Yocto Project reference hardware Board
-Support Packages (BSPs). For more information on BSPs, see the
-:doc:`/bsp-guide/index`.
-
.. _structure-meta-selftest:
-``meta-selftest/``
-------------------
+``layers/openembedded-core/meta-selftest/``
+-------------------------------------------
This directory adds additional recipes and append files used by the
OpenEmbedded selftests to verify the behavior of the build system. You
@@ -115,15 +113,15 @@ want to run the selftests.
.. _structure-meta-skeleton:
-``meta-skeleton/``
-------------------
+``layers/openembedded-core/meta-skeleton/``
+-------------------------------------------
This directory contains template recipes for BSP and kernel development.
.. _structure-core-scripts:
-``scripts/``
-------------
+``layers/openembedded-core/scripts/``
+-------------------------------------
This directory contains various integration scripts that implement extra
functionality in the Yocto Project environment (e.g. QEMU scripts). The
@@ -136,8 +134,8 @@ back to the Yocto Project, such as ``create-pull-request`` and
.. _structure-core-script:
-``oe-init-build-env``
----------------------
+``layers/openembedded-core/oe-init-build-env``
+----------------------------------------------
This script sets up the OpenEmbedded build environment. Running this
script with the ``source`` command in a shell makes changes to ``PATH``
@@ -166,16 +164,27 @@ targets to build. Here is an example::
You can also run generated QEMU images with a command like 'runqemu qemux86-64'
+.. note::
+
+ When using :doc:`bitbake-setup <bitbake:bitbake-user-manual/bitbake-user-manual-environment-setup>`,
+ this script is indirectly sourced when sourcing the ``init-build-env``
+ located in the :term:`bitbake:Setup`'s build directory. However, compared to
+ ``oe-init-build-env``, the bitbake-setup ``init-build-env`` does not take any
+ argument, as it is already located in a :term:`Build Directory`.
+
+ See :doc:`bitbake:bitbake-user-manual/bitbake-user-manual-environment-setup`
+ for more information.
+
The default output of the ``oe-init-build-env`` script is from the
-``conf-summary.txt`` and ``conf-notes.txt`` files, which are found in the ``meta-poky`` directory
-within the :term:`Source Directory`. If you design a
-custom distribution, you can include your own versions of these
-configuration files where you can provide a brief summary and detailed usage
-notes, such as a list of the targets defined by your distribution.
-See the
-":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`"
-section in the Yocto Project Development Tasks Manual for more
-information.
+``conf-summary.txt`` and ``conf-notes.txt`` files, which are found in the
+``meta/conf/templates/default`` directory of :term:`OpenEmbedded-Core
+(OE-Core)`. If you design a custom distribution, you can include your own
+versions of these configuration files where you can provide a brief summary and
+detailed usage notes, such as a list of the targets defined by your
+distribution. See the
+":ref:`dev-manual/custom-template-configuration-directory:creating a custom
+template configuration directory`" section in the Yocto Project Development
+Tasks Manual for more information.
By default, running this script without a :term:`Build Directory` argument
creates the ``build/`` directory in your current working directory. If
@@ -188,8 +197,8 @@ your choice. For example, the following command creates a
$ source oe-init-build-env ~/mybuilds
The OpenEmbedded build system uses the template configuration files, which
-are found by default in the ``meta-poky/conf/templates/default`` directory in the Source
-Directory. See the
+are found by default in the ``meta/conf/templates/default`` directory in
+:term:`OpenEmbedded-Core (OE-Core)`. See the
":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`"
section in the Yocto Project Development Tasks Manual for more
information.
@@ -198,17 +207,30 @@ information.
The OpenEmbedded build system does not support file or directory
names that contain spaces. If you attempt to run the ``oe-init-build-env``
- script from a Source Directory that contains spaces in either the
+ script from a :term:`Source Directory` that contains spaces in either the
filenames or directory names, the script returns an error indicating
- no such file or directory. Be sure to use a Source Directory free of
+ no such file or directory. Be sure to use a :term:`Source Directory` free of
names containing spaces.
-.. _structure-basic-top-level:
+.. _structure-core-meta-poky:
+
+``layers/meta-yocto/meta-poky/``
+--------------------------------
+
+Dependent on the :term:`OpenEmbedded-Core (OE-Core)` metadata, this directory
+adds just enough metadata to define the Poky reference distribution.
-``LICENSE, README, and README.hardware``
-----------------------------------------
+Namely, it contains the distro :term:`configuration file` for Poky:
+``conf/distro/poky.conf``.
+
+.. _structure-core-meta-yocto-bsp:
-These files are standard top-level files.
+``layers/meta-yocto/meta-yocto-bsp/``
+-------------------------------------
+
+This directory contains the Yocto Project reference hardware Board
+Support Packages (BSPs). For more information on BSPs, see the
+:doc:`/bsp-guide/index`.
.. _structure-build:
@@ -257,7 +279,7 @@ This directory should not be shared between builds.
you need to share the :ref:`overview-manual/concepts:Hash Equivalence`
database, don't share this file and instead refer to the
:doc:`/dev-manual/hashequivserver` document of the Yocto Project Development
- Tasks Manual to setup Hash Equivalence server.
+ Tasks Manual to setup a Hash Equivalence server.
.. _structure-build-conf-local.conf:
@@ -275,9 +297,9 @@ file, it is recommended to put them into a distro :term:`configuration file`, or
to create layer :term:`configuration fragments <Configuration Fragment>` from
changes made here.
-The :term:`OpenEmbedded Build System` can create it from a ``local.conf.sample``
-file when you ``source`` the top-level build environment setup script
-:ref:`structure-core-script`.
+The :term:`OpenEmbedded Build System` can create the ``local.conf`` file from a
+``local.conf.sample`` file when you ``source`` the top-level build environment
+setup script :ref:`structure-core-script`.
The source ``local.conf.sample`` file used depends on the
:term:`TEMPLATECONF` script variable, which defaults to ``meta-poky/conf/templates/default``
@@ -298,8 +320,8 @@ file, it uses ``sed`` to substitute final
.. note::
You can see how the :term:`TEMPLATECONF` variable is used by looking at the
- ``scripts/oe-setup-builddir`` script in the :term:`Source Directory`.
- You can find the Yocto Project version of the ``local.conf.sample`` file in
+ ``scripts/oe-setup-builddir`` script in :term:`OpenEmbedded-Core (OE-Core)`.
+ You can find the :term:`Poky` version of the ``local.conf.sample`` file in
the ``meta-poky/conf/templates/default`` directory.
.. _structure-build-conf-bblayers.conf:
@@ -319,9 +341,9 @@ when you ``source`` the top-level build environment setup script (i.e.
As with the :ref:`structure-build-conf-local.conf` file, the source ``bblayers.conf.sample``
file used depends on the :term:`TEMPLATECONF` script variable, which
-defaults to ``meta-poky/conf/templates/default`` when you are building from the Yocto
-Project development environment, and to ``meta/conf/templates/default`` when you are
-building from the OpenEmbedded-Core environment. Because the script
+defaults to ``meta-poky/conf/templates/default`` when you are building using the
+:term:`Poky` reference distro, and to ``meta/conf/templates/default`` when you are
+building from the OpenEmbedded-Core environment (default). Because the script
variable points to the source of the ``bblayers.conf.sample`` file, this
implies that you can base your build from any layer by setting the
variable in the top-level build environment setup script as follows::
@@ -329,12 +351,12 @@ variable in the top-level build environment setup script as follows::
TEMPLATECONF=your_layer/conf/templates/your_template_name
Once the build process gets the sample file, it uses ``sed`` to substitute final
-``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values.
+``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` occurrences.
.. note::
You can see how the :term:`TEMPLATECONF` variable is defined by the ``scripts/oe-setup-builddir``
- script in the :term:`Source Directory`. You can find the Yocto Project
+ script in the :term:`Source Directory`. You can find the :term:`Poky`
version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/templates/default``
directory.
@@ -351,8 +373,9 @@ You could for example edit this file to limit the number of threads used by
want to access downloaded files (:term:`DL_DIR`).
This file can be shared for multiple build directories. For example,
-``bitbake-setup`` makes the :ref:`structure-build-conf-site.conf` file a
-symbolic link to a common ``site.conf`` file::
+:doc:`bitbake-setup <bitbake:bitbake-user-manual/bitbake-user-manual-environment-setup>`
+makes the :ref:`structure-build-conf-site.conf` file a symbolic link to a common
+``site.conf`` file::
├── poky-master-poky-distro_poky-machine_qemux86-64/
│ └── build/
@@ -757,11 +780,12 @@ space if they were to be shared with the standard :term:`Sysroot` mechanism.
.. _structure-meta:
-The Metadata --- ``meta/``
-==========================
+The OpenEmbedded-Core (OE-Core) Metadata --- ``meta/``
+======================================================
-As mentioned previously, :term:`Metadata` is the core of the
-Yocto Project. Metadata has several important subdivisions:
+As mentioned previously, the :term:`OpenEmbedded-Core (OE-Core)`
+:term:`metadata` is the core of the Yocto Project. This metadata has several
+important subdivisions:
.. _structure-meta-classes:
@@ -63,7 +63,7 @@ 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```, or
+ (i.e. :ref:`structure-core-script`, 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`.
Remove references to the Poky repository, replace by OpenEmbedded-Core in most cases. Add a introductory directory layout at the top that is reflected in the following section. This document no longer uses Poky as its source directory, so all paths are explicitly mentioned, to highlight the separation between core components. This lead to some re-organization of some sections. Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> --- documentation/bsp-guide/bsp.rst | 4 +- documentation/ref-manual/structure.rst | 150 +++++++++++++++++++-------------- documentation/ref-manual/terms.rst | 2 +- 3 files changed, 90 insertions(+), 66 deletions(-)