diff options
Diffstat (limited to 'poky/documentation/ref-manual')
| -rw-r--r-- | poky/documentation/ref-manual/classes.rst | 5 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/devtool-reference.rst | 2 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/features.rst | 92 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/release-process.rst | 17 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/system-requirements.rst | 87 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/tasks.rst | 10 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/variables.rst | 156 |
7 files changed, 176 insertions, 193 deletions
diff --git a/poky/documentation/ref-manual/classes.rst b/poky/documentation/ref-manual/classes.rst index 7ff0fcb335..e8dec31b00 100644 --- a/poky/documentation/ref-manual/classes.rst +++ b/poky/documentation/ref-manual/classes.rst @@ -858,8 +858,9 @@ introspection. This functionality is only enabled if the .. note:: - This functionality is backfilled by default and, if not applicable, - should be disabled through :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or + This functionality is :ref:`backfilled <ref-features-backfill>` by default + and, if not applicable, should be disabled through + :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`, respectively. .. _ref-classes-grub-efi: diff --git a/poky/documentation/ref-manual/devtool-reference.rst b/poky/documentation/ref-manual/devtool-reference.rst index 32e64d02a2..e167f58092 100644 --- a/poky/documentation/ref-manual/devtool-reference.rst +++ b/poky/documentation/ref-manual/devtool-reference.rst @@ -353,7 +353,7 @@ variables in package recipes. :yocto_git:`maintainers.inc </poky/tree/meta/conf/distro/include/maintainers.inc>` file. - - If the recipe is using the :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:git fetcher (\`\`git://\`\`)` + - If the recipe is using the :ref:`bitbake-user-manual/bitbake-user-manual-fetching:git fetcher (\`\`git://\`\`)` rather than a tarball, the commit hash points to the commit that matches the recipe's latest version tag, or in the absence of suitable tags, to the latest commit (when :term:`UPSTREAM_CHECK_COMMITS` set to ``1`` diff --git a/poky/documentation/ref-manual/features.rst b/poky/documentation/ref-manual/features.rst index 051bf9320a..5a064329f1 100644 --- a/poky/documentation/ref-manual/features.rst +++ b/poky/documentation/ref-manual/features.rst @@ -6,7 +6,7 @@ Features This chapter provides a reference of shipped machine and distro features you can include as part of your image, a reference on image features you -can select, and a reference on feature backfilling. +can select, and a reference on :ref:`ref-features-backfill`. Features provide a mechanism for working out which packages should be included in the generated images. Distributions can select which @@ -416,58 +416,50 @@ these valid features is as follows: Feature Backfilling =================== -Sometimes it is necessary in the OpenEmbedded build system to extend -:term:`MACHINE_FEATURES` or -:term:`DISTRO_FEATURES` to control functionality -that was previously enabled and not able to be disabled. For these -cases, we need to add an additional feature item to appear in one of -these variables, but we do not want to force developers who have -existing values of the variables in their configuration to add the new -feature in order to retain the same overall level of functionality. -Thus, the OpenEmbedded build system has a mechanism to automatically -"backfill" these added features into existing distro or machine +Sometimes it is necessary in the OpenEmbedded build system to +add new functionality to :term:`MACHINE_FEATURES` or +:term:`DISTRO_FEATURES`, but at the same time, allow existing +distributions or machine definitions to opt out of such new +features, to retain the same overall level of functionality. + +To make this possible, the OpenEmbedded build system has a mechanism to +automatically "backfill" features into existing distro or machine configurations. You can see the list of features for which this is done -by finding the -:term:`DISTRO_FEATURES_BACKFILL` and -:term:`MACHINE_FEATURES_BACKFILL` -variables in the ``meta/conf/bitbake.conf`` file. - -Because such features are backfilled by default into all configurations -as described in the previous paragraph, developers who wish to disable -the new features need to be able to selectively prevent the backfilling -from occurring. They can do this by adding the undesired feature or -features to the +by checking the :term:`DISTRO_FEATURES_BACKFILL` and +:term:`MACHINE_FEATURES_BACKFILL` variables in the +``meta/conf/bitbake.conf`` file. + +These two variables are paired with the :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` -or -:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` -variables for distro features and machine features respectively. - -Here are two examples to help illustrate feature backfilling: - -- *The "pulseaudio" distro feature option*: Previously, PulseAudio - support was enabled within the Qt and GStreamer frameworks. Because - of this, the feature is backfilled and thus enabled for all distros - through the :term:`DISTRO_FEATURES_BACKFILL` variable in the - ``meta/conf/bitbake.conf`` file. However, your distro needs to - disable the feature. You can disable the feature without affecting - other existing distro configurations that need PulseAudio support by - adding "pulseaudio" to :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` in - your distro's ``.conf`` file. Adding the feature to this variable - when it also exists in the :term:`DISTRO_FEATURES_BACKFILL` variable - prevents the build system from adding the feature to your - configuration's :term:`DISTRO_FEATURES`, effectively disabling the - feature for that particular distro. +and :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` variables +which allow distro or machine configuration maintainers to `consider` any +added feature, and decide when they wish to keep or exclude such feature, +thus preventing the backfilling from happening. + +Here are two examples to illustrate feature backfilling: + +- *The "pulseaudio" distro feature option*: Previously, PulseAudio support was + enabled within the Qt and GStreamer frameworks. Because of this, the feature + is now backfilled and thus enabled for all distros through the + :term:`DISTRO_FEATURES_BACKFILL` variable in the ``meta/conf/bitbake.conf`` + file. However, if your distro needs to disable the feature, you can do so + without affecting other existing distro configurations that need PulseAudio + support. You do this by adding "pulseaudio" to + :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` in your distro's ``.conf`` + file. So, adding the feature to this variable when it also exists in the + :term:`DISTRO_FEATURES_BACKFILL` variable prevents the build system from + adding the feature to your configuration's :term:`DISTRO_FEATURES`, + effectively disabling the feature for that particular distro. - *The "rtc" machine feature option*: Previously, real time clock (RTC) support was enabled for all target devices. Because of this, the feature is backfilled and thus enabled for all machines through the - :term:`MACHINE_FEATURES_BACKFILL` variable in the - ``meta/conf/bitbake.conf`` file. However, your target device does not - have this capability. You can disable RTC support for your device - without affecting other machines that need RTC support by adding the - feature to your machine's :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` - list in the machine's ``.conf`` file. Adding the feature to this - variable when it also exists in the :term:`MACHINE_FEATURES_BACKFILL` - variable prevents the build system from adding the feature to your - configuration's :term:`MACHINE_FEATURES`, effectively disabling RTC - support for that particular machine. + :term:`MACHINE_FEATURES_BACKFILL` variable in the ``meta/conf/bitbake.conf`` + file. However, if your target device does not have this capability, you can + disable RTC support for your device without affecting other machines + that need RTC support. You do this by adding the "rtc" feature to the + :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` list in your machine's ``.conf`` + file. So, adding the feature to this variable when it also exists in the + :term:`MACHINE_FEATURES_BACKFILL` variable prevents the build system from + adding the feature to your configuration's :term:`MACHINE_FEATURES`, + effectively disabling RTC support for that particular machine. diff --git a/poky/documentation/ref-manual/release-process.rst b/poky/documentation/ref-manual/release-process.rst index 19e8040638..fa057e055c 100644 --- a/poky/documentation/ref-manual/release-process.rst +++ b/poky/documentation/ref-manual/release-process.rst @@ -97,6 +97,23 @@ through the same release process as do point releases. You can find more information about stable branch maintenance at :yocto_wiki:`/Stable_branch_maintenance`. +.. note:: + + In some circumstances, a layer can be created by the community in order to + add a specific feature or support a new version of some package for an LTS + release. This is called a "mixin" layer. These are thin and specific + purpose layers which can be stacked with an LTS release to "mix" a specific + feature into that build. These are created on an as-needed basis and + maintained by the people who need them. + + Policies on testing these layers depend on how widespread their usage is and + determined on a case-by-case basis. You can find some "mixin" layers in the + :yocto_git:`meta-lts-mixins </meta-lts-mixins>` repository. While the Yocto + Project provides hosting for those repositories, it does not provides + testing on them. Other "mixin" layers may be released elsewhere by the wider + community. + + Testing and Quality Assurance ============================= diff --git a/poky/documentation/ref-manual/system-requirements.rst b/poky/documentation/ref-manual/system-requirements.rst index 38d4aaf5a7..0fbe3f12c8 100644 --- a/poky/documentation/ref-manual/system-requirements.rst +++ b/poky/documentation/ref-manual/system-requirements.rst @@ -110,8 +110,10 @@ function. Ubuntu and Debian ----------------- -Here are the required packages by function given a -supported Ubuntu or Debian Linux distribution: +Here are the packages needed to build an image on a headless system +with a supported Ubuntu or Debian Linux distribution:: + + $ sudo apt install &UBUNTU_HOST_PACKAGES_ESSENTIAL; .. note:: @@ -123,80 +125,63 @@ supported Ubuntu or Debian Linux distribution: $ sudo apt build-dep qemu $ sudo apt remove oss4-dev -- *Essentials:* Packages needed to build an image on a headless system:: - - $ sudo apt install &UBUNTU_HOST_PACKAGES_ESSENTIAL; +Here are the packages needed to build Project documentation manuals:: -- *Documentation:* Packages needed if you are going to build out the - Yocto Project documentation manuals:: - - $ sudo apt install make python3-pip inkscape texlive-latex-extra - &PIP3_HOST_PACKAGES_DOC; + $ sudo apt install make python3-pip inkscape texlive-latex-extra + &PIP3_HOST_PACKAGES_DOC; Fedora Packages --------------- -Here are the required packages by function given a -supported Fedora Linux distribution: - -- *Essentials:* Packages needed to build an image for a headless - system:: +Here are the packages needed to build an image on a headless system +with a supported Fedora Linux distribution:: - $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; + $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; -- *Documentation:* Packages needed if you are going to build out the - Yocto Project documentation manuals:: +Here are the packages needed to build Project documentation manuals:: - $ sudo dnf install make python3-pip which inkscape texlive-fncychap - &PIP3_HOST_PACKAGES_DOC; + $ sudo dnf install make python3-pip which inkscape texlive-fncychap + &PIP3_HOST_PACKAGES_DOC; openSUSE Packages ----------------- -Here are the required packages by function given a -supported openSUSE Linux distribution: +Here are the packages needed to build an image on a headless system +with a supported openSUSE distribution:: -- *Essentials:* Packages needed to build an image for a headless - system:: + $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; - $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; +Here are the packages needed to build Project documentation manuals:: -- *Documentation:* Packages needed if you are going to build out the - Yocto Project documentation manuals:: + $ sudo zypper install make python3-pip which inkscape texlive-fncychap + &PIP3_HOST_PACKAGES_DOC; - $ sudo zypper install make python3-pip which inkscape texlive-fncychap - &PIP3_HOST_PACKAGES_DOC; +AlmaLinux Packages +------------------ -AlmaLinux-8 Packages --------------------- +Here are the packages needed to build an image on a headless system +with a supported AlmaLinux distribution:: -Here are the required packages by function given a -supported AlmaLinux-8 Linux distribution: + $ sudo dnf install &ALMALINUX8_HOST_PACKAGES_ESSENTIAL; -- *Essentials:* Packages needed to build an image for a headless - system:: - - $ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL; - - .. note:: +.. note:: - - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is - a collection of packages from Fedora built on RHEL/CentOS for - easy installation of packages not included in enterprise Linux - by default. You need to install these packages separately. + - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is + a collection of packages from Fedora built on RHEL/CentOS for + easy installation of packages not included in enterprise Linux + by default. You need to install these packages separately. - - The ``PowerTools`` repo provides additional packages such as - ``rpcgen`` and ``texinfo``. + - The ``PowerTools/CRB`` repo provides additional packages such as + ``rpcgen`` and ``texinfo``. - - The ``makecache`` command consumes additional Metadata from - ``epel-release``. + - The ``makecache`` command consumes additional Metadata from + ``epel-release``. -- *Documentation:* Packages needed if you are going to build out the - Yocto Project documentation manuals:: +Here are the packages needed to build Project documentation manuals:: - $ sudo dnf install make python3-pip which inkscape texlive-fncychap - &PIP3_HOST_PACKAGES_DOC; + $ sudo dnf install make python3-pip which inkscape texlive-fncychap + &PIP3_HOST_PACKAGES_DOC; .. _system-requirements-buildtools: diff --git a/poky/documentation/ref-manual/tasks.rst b/poky/documentation/ref-manual/tasks.rst index 7a664cc6c0..f2b93185af 100644 --- a/poky/documentation/ref-manual/tasks.rst +++ b/poky/documentation/ref-manual/tasks.rst @@ -14,8 +14,8 @@ Normal Recipe Build Tasks The following sections describe normal tasks associated with building a recipe. For more information on tasks and dependencies, see the -":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and -":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the +":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and +":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the BitBake User Manual. .. _ref-tasks-build: @@ -118,9 +118,9 @@ If the :ref:`ref-tasks-deploy` task re-executes, any previous output is removed ``do_fetch`` ------------ -Fetches the source code. This task uses the -:term:`SRC_URI` variable and the argument's prefix to -determine the correct :ref:`fetcher <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` +Fetches the source code. This task uses the :term:`SRC_URI` variable and the +argument's prefix to determine the correct +:ref:`fetcher <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` module. .. _ref-tasks-image: diff --git a/poky/documentation/ref-manual/variables.rst b/poky/documentation/ref-manual/variables.rst index 9b581599e3..c787a17937 100644 --- a/poky/documentation/ref-manual/variables.rst +++ b/poky/documentation/ref-manual/variables.rst @@ -243,12 +243,12 @@ system and gives an overview of their function and contents. To add a tune to the list, be sure to append it with spaces using the "+=" BitBake operator. Do not simply replace the list by using the "=" operator. See the - ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`" section in the BitBake + ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`" section in the BitBake User Manual for more information. :term:`AZ_SAS` Azure Storage Shared Access Signature, when using the - :ref:`Azure Storage fetcher (az://) <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` + :ref:`Azure Storage fetcher (az://) <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` This variable can be defined to be used by the fetcher to authenticate and gain access to non-public artifacts:: @@ -1833,15 +1833,14 @@ system and gives an overview of their function and contents. DEPENDS = "bar" - The practical effect of the previous - assignment is that all files installed by bar will be available in - the appropriate staging sysroot, given by the - :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time the - :ref:`ref-tasks-configure` task for ``foo`` runs. - This mechanism is implemented by having :ref:`ref-tasks-configure` depend on - the :ref:`ref-tasks-populate_sysroot` task of - each recipe listed in :term:`DEPENDS`, through a - ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` + The practical effect of the previous assignment is that all files + installed by bar will be available in the appropriate staging sysroot, + given by the :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time + the :ref:`ref-tasks-configure` task for ``foo`` runs. This mechanism is + implemented by having :ref:`ref-tasks-configure` depend on the + :ref:`ref-tasks-populate_sysroot` task of each recipe listed in + :term:`DEPENDS`, through a + ``[``\ :ref:`deptask <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` declaration in the :ref:`ref-classes-base` class. .. note:: @@ -1888,12 +1887,12 @@ system and gives an overview of their function and contents. to the recipe that installs ``libbar``, other recipes might fail to link against ``libfoo``. - For information on runtime dependencies, see the - :term:`RDEPENDS` variable. You can also see the - ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and - ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the - BitBake User Manual for additional information on tasks and - dependencies. + For information on runtime dependencies, see the :term:`RDEPENDS` + variable. You can also see the + ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and + ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" + sections in the BitBake User Manual for additional information on tasks + and dependencies. :term:`DEPLOY_DIR` Points to the general area that the OpenEmbedded build system uses to @@ -2111,19 +2110,27 @@ system and gives an overview of their function and contents. provide with this variable, see the ":ref:`ref-features-distro`" section. :term:`DISTRO_FEATURES_BACKFILL` - Features to be added to :term:`DISTRO_FEATURES` if not also present in - :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`. + A space-separated list of features to be added to :term:`DISTRO_FEATURES` + if not also present in :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`. This variable is set in the ``meta/conf/bitbake.conf`` file. It is not intended to be user-configurable. It is best to just reference - the variable to see which distro features are being backfilled for - all distro configurations. See the ":ref:`ref-features-backfill`" section - for more information. + the variable to see which distro features are being + :ref:`backfilled <ref-features-backfill>` for all distro configurations. :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` - Features from :term:`DISTRO_FEATURES_BACKFILL` that should not be - backfilled (i.e. added to :term:`DISTRO_FEATURES`) during the build. See - the ":ref:`ref-features-backfill`" section for more information. + A space-separated list of features from :term:`DISTRO_FEATURES_BACKFILL` + that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added + to :term:`DISTRO_FEATURES`) during the build. + + This corresponds to an opt-out mechanism. When new default distro + features are introduced, distribution maintainers can review (`consider`) + them and decide to exclude them from the + :ref:`backfilled <ref-features-backfill>` features. Therefore, the + combination of :term:`DISTRO_FEATURES_BACKFILL` and + :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` makes it possible to + add new default features without breaking existing distributions. + :term:`DISTRO_FEATURES_DEFAULT` A convenience variable that gives you the default list of distro @@ -2809,15 +2816,13 @@ system and gives an overview of their function and contents. recipe to correctly extend the path. :term:`FILESOVERRIDES` - A subset of :term:`OVERRIDES` used by the - OpenEmbedded build system for creating - :term:`FILESPATH`. The :term:`FILESOVERRIDES` variable - uses overrides to automatically extend the - :term:`FILESPATH` variable. For an example of how - that works, see the :term:`FILESPATH` variable + A subset of :term:`OVERRIDES` used by the OpenEmbedded build system for + creating :term:`FILESPATH`. The :term:`FILESOVERRIDES` variable uses + overrides to automatically extend the :term:`FILESPATH` variable. For an + example of how that works, see the :term:`FILESPATH` variable description. Additionally, you find more information on how overrides are handled in the - ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" + ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" section of the BitBake User Manual. By default, the :term:`FILESOVERRIDES` variable is defined as:: @@ -3539,19 +3544,19 @@ system and gives an overview of their function and contents. section in the Yocto Project Development Tasks Manual. - Using :term:`IMAGE_INSTALL` with the - :ref:`+= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>` + :ref:`+= <bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>` BitBake operator within the ``/conf/local.conf`` file or from - within an image recipe is not recommended. Use of this operator - in these ways can cause ordering issues. Since - :ref:`ref-classes-core-image` sets :term:`IMAGE_INSTALL` to a default - value using the - :ref:`?= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>` + within an image recipe is not recommended. Use of this operator in + these ways can cause ordering issues. Since + :ref:`ref-classes-core-image` sets :term:`IMAGE_INSTALL` to a + default value using the + :ref:`?= <bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>` operator, using a ``+=`` operation against :term:`IMAGE_INSTALL` results in unexpected behavior when used within - ``conf/local.conf``. Furthermore, the same operation from - within an image recipe may or may not succeed depending on the - specific situation. In both these cases, the behavior is - contrary to how most users expect the ``+=`` operator to work. + ``conf/local.conf``. Furthermore, the same operation from within an + image recipe may or may not succeed depending on the specific + situation. In both these cases, the behavior is contrary to how + most users expect the ``+=`` operator to work. :term:`IMAGE_LINGUAS` Specifies the list of locales to install into the image during the @@ -3913,7 +3918,7 @@ system and gives an overview of their function and contents. ``classes-global/`` or ``classes/`` subdirectories. For more information on :term:`INHERIT`, see the - :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" + :ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" section in the BitBake User Manual. :term:`INHERIT_DISTRO` @@ -4736,31 +4741,7 @@ system and gives an overview of their function and contents. ``LAYERRECOMMENDS_mylayer``). :term:`LAYERSERIES_COMPAT` - Lists the versions of the :term:`OpenEmbedded-Core (OE-Core)` for which - a layer is compatible. Using the :term:`LAYERSERIES_COMPAT` variable - allows the layer maintainer to indicate which combinations of the - layer and OE-Core can be expected to work. The variable gives the - system a way to detect when a layer has not been tested with new - releases of OE-Core (e.g. the layer is not maintained). - - To specify the OE-Core versions for which a layer is compatible, use - this variable in your layer's ``conf/layer.conf`` configuration file. - For the list, use the Yocto Project - :yocto_wiki:`Release Name </Releases>` (e.g. - &DISTRO_NAME_NO_CAP;). To specify multiple OE-Core versions for the - layer, use a space-separated list:: - - LAYERSERIES_COMPAT_layer_root_name = "&DISTRO_NAME_NO_CAP; &DISTRO_NAME_NO_CAP_MINUS_ONE;" - - .. note:: - - Setting :term:`LAYERSERIES_COMPAT` is required by the Yocto Project - Compatible version 2 standard. - The OpenEmbedded build system produces a warning if the variable - is not set for any given layer. - - See the ":ref:`dev-manual/layers:creating your own layer`" - section in the Yocto Project Development Tasks Manual. + See :term:`bitbake:LAYERSERIES_COMPAT` in the BitBake manual. :term:`LAYERVERSION` Optionally specifies the version of a layer as a single number. You @@ -5129,19 +5110,27 @@ system and gives an overview of their function and contents. shipped, see the ":ref:`ref-features-machine`" section. :term:`MACHINE_FEATURES_BACKFILL` - Features to be added to :term:`MACHINE_FEATURES` if not also present in + A list of space-separated features to be added to + :term:`MACHINE_FEATURES` if not also present in :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. - This variable is set in the ``meta/conf/bitbake.conf`` file. It is - not intended to be user-configurable. It is best to just reference - the variable to see which machine features are being backfilled for - all machine configurations. See the ":ref:`ref-features-backfill`" - section for more information. + This variable is set in the ``meta/conf/bitbake.conf`` file. It is not + intended to be user-configurable. It is best to just reference the + variable to see which machine features are being + :ref:`backfilled <ref-features-backfill>` for all machine configurations. :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` - Features from :term:`MACHINE_FEATURES_BACKFILL` that should not be - backfilled (i.e. added to :term:`MACHINE_FEATURES`) during the build. See - the ":ref:`ref-features-backfill`" section for more information. + A list of space-separated features from :term:`MACHINE_FEATURES_BACKFILL` + that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added + to :term:`MACHINE_FEATURES`) during the build. + + This corresponds to an opt-out mechanism. When new default machine + features are introduced, machine definition maintainers can review + (`consider`) them and decide to exclude them from the + :ref:`backfilled <ref-features-backfill>` features. Therefore, the + combination of :term:`MACHINE_FEATURES_BACKFILL` and + :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` makes it possible to + add new default features without breaking existing machine definitions. :term:`MACHINEOVERRIDES` A colon-separated list of overrides that apply to the current @@ -5603,7 +5592,7 @@ system and gives an overview of their function and contents. FOO:an-override = "overridden" See the - ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" + ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" section in the BitBake User Manual for more information on the overrides mechanism. @@ -6808,12 +6797,11 @@ system and gives an overview of their function and contents. RDEPENDS:${PN} = "foo (>= 1.2)" - For information on build-time dependencies, see the - :term:`DEPENDS` variable. You can also see the - ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and - ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the - BitBake User Manual for additional information on tasks and - dependencies. + For information on build-time dependencies, see the :term:`DEPENDS` + variable. You can also see the + ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and + ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the + BitBake User Manual for additional information on tasks and dependencies. :term:`RECIPE_NO_UPDATE_REASON` If a recipe should not be replaced by a more recent upstream version, |