1
0
mirror of https://git.yoctoproject.org/poky synced 2026-06-01 13:09:50 +00:00

manuals: add missing references to classes

Sometimes fixing line length in modified paragraphs too.

[YOCTO #14508]
Reported-by: Quentin Schulz <foss@0leil.net>
(From yocto-docs rev: 885b60f5540849bf19240a01a77efce1d1b5d9f0)

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Michael Opdenacker
2022-10-13 08:42:10 +02:00
committed by Richard Purdie
parent 7ecd9877e6
commit 55621c31f1
21 changed files with 182 additions and 156 deletions
@@ -91,11 +91,11 @@ consistency.
nativesdk
~~~~~~~~~
The suffix ``nativesdk`` is now implemented as a prefix, which
simplifies a lot of the packaging code for ``nativesdk`` recipes. All
custom ``nativesdk`` recipes, which are relocatable packages that are
native to :term:`SDK_ARCH`, and any references need to
be updated to use ``nativesdk-*`` instead of ``*-nativesdk``.
The suffix ``nativesdk`` is now implemented as a prefix, which simplifies a
lot of the packaging code for :ref:`nativesdk <ref-classes-nativesdk>` recipes.
All custom :ref:`nativesdk <ref-classes-nativesdk>` recipes, which are
relocatable packages that are native to :term:`SDK_ARCH`, and any references
need to be updated to use ``nativesdk-*`` instead of ``*-nativesdk``.
.. _migration-1.3-task-recipes:
@@ -109,12 +109,11 @@ automatic upgrade path for most packages. However, you should update
references in your own recipes and configurations as they could be
removed in future releases. You should also rename any custom ``task-*``
recipes to ``packagegroup-*``, and change them to inherit
``packagegroup`` instead of ``task``, as well as taking the opportunity
to remove anything now handled by :ref:`ref-classes-packagegroup`, such as
providing ``-dev`` and ``-dbg`` packages, setting
:term:`LIC_FILES_CHKSUM`, and so forth. See the
:ref:`ref-classes-packagegroup` section for
further details.
:ref:`packagegroup <ref-classes-packagegroup>` instead of ``task``, as well
as taking the opportunity to remove anything now handled by
:ref:`ref-classes-packagegroup`, such as providing ``-dev`` and ``-dbg``
packages, setting :term:`LIC_FILES_CHKSUM`, and so forth. See the
:ref:`ref-classes-packagegroup` section for further details.
.. _migration-1.3-image-features:
@@ -130,6 +130,11 @@ The following directory changes exist:
it easier to delete :term:`TMPDIR` and preserve the build history.
Additionally, data for produced SDKs is now split by :term:`IMAGE_NAME`.
- When :ref:`buildhistory <ref-classes-buildhistory>` is enabled, its output
is now written under the :term:`Build Directory` rather than :term:`TMPDIR`.
Doing so makes it easier to delete :term:`TMPDIR` and preserve the build
history. Additionally, data for produced SDKs is now split by :term:`IMAGE_NAME`.
- The ``pkgdata`` directory produced as part of the packaging process
has been collapsed into a single machine-specific directory. This
directory is located under ``sysroots`` and uses a machine-specific
@@ -220,9 +220,10 @@ Package Test (ptest)
Package Tests (ptest) are built but not installed by default. For
information on using Package Tests, see the
":ref:`dev-manual/common-tasks:testing packages with ptest`"
section in the Yocto Project Development Tasks Manual. For information on the
``ptest`` class, see the ":ref:`ref-classes-ptest`" section.
":ref:`dev-manual/common-tasks:testing packages with ptest`" section in the
Yocto Project Development Tasks Manual. For information on the
:ref:`ptest <ref-classes-ptest>` class, see the ":ref:`ref-classes-ptest`"
section.
.. _migration-1.6-build-changes:
@@ -237,7 +238,7 @@ will enable a separate :term:`Build Directory` by default as well. Recipes
building Autotools-based software that fails to build with a separate
:term:`Build Directory` should be changed to inherit from the
:ref:`autotools-brokensep <ref-classes-autotools>` class instead of
the ``autotools`` or ``autotools_stage``\ classes.
the :ref:`autotools <ref-classes-autotools>` or ``autotools_stage`` classes.
.. _migration-1.6-building-qemu-native:
@@ -76,15 +76,15 @@ particular, users need to ensure that ``${S}`` (source files) and
``${B}`` (build artifacts) are used correctly in functions such as
:ref:`ref-tasks-configure` and
:ref:`ref-tasks-install`. For kernel recipes that do not
inherit from ``kernel-yocto`` or include ``linux-yocto.inc``, you might
inherit from :ref:`kernel-yocto <ref-classes-kernel-yocto>` or include ``linux-yocto.inc``, you might
wish to refer to the ``linux.inc`` file in the ``meta-oe`` layer for the
kinds of changes you need to make. For reference, here is the
:oe_git:`commit </meta-openembedded/commit/meta-oe/recipes-kernel/linux/linux.inc?id=fc7132ede27ac67669448d3d2845ce7d46c6a1ee>`
where the ``linux.inc`` file in ``meta-oe`` was updated.
Recipes that rely on the kernel source code and do not inherit the
module classes might need to add explicit dependencies on the
:ref:`ref-tasks-shared_workdir` kernel task, for example::
:ref:`module <ref-classes-module>` classes might need to add explicit
dependencies on the :ref:`ref-tasks-shared_workdir` kernel task, for example::
do_configure[depends] += "virtual/kernel:do_shared_workdir"
@@ -64,7 +64,7 @@ Makefile Environment Changes
:term:`EXTRA_OEMAKE` now defaults to "" instead of
"-e MAKEFLAGS=". Setting :term:`EXTRA_OEMAKE` to "-e MAKEFLAGS=" by default
was a historical accident that has required many classes (e.g.
``autotools``, ``module``) and recipes to override this default in order
:ref:`autotools <ref-classes-autotools>`, ``module``) and recipes to override this default in order
to work with sensible build systems. When upgrading to the release, you
must edit any recipe that relies upon this old default by either setting
:term:`EXTRA_OEMAKE` back to "-e MAKEFLAGS=" or by explicitly setting any
@@ -191,7 +191,7 @@ The following classes have changed:
- ``autotools_stage``: Removed because the
:ref:`autotools <ref-classes-autotools>` class now provides its
functionality. Recipes that inherited from ``autotools_stage`` should
now inherit from ``autotools`` instead.
now inherit from :ref:`autotools <ref-classes-autotools>` instead.
- ``boot-directdisk``: Merged into the ``image-vm`` class. The
``boot-directdisk`` class was rarely directly used. Consequently,
@@ -401,9 +401,9 @@ These additional changes exist:
as these directories are automatically found and added.
- Inaccurate disk and CPU percentage data has been dropped from
``buildstats`` output. This data has been replaced with
:ref:`buildstats <ref-classes-buildstats>` output. This data has been replaced with
``getrusage()`` data and corrected IO statistics. You will probably
need to update any custom code that reads the ``buildstats`` data.
need to update any custom code that reads the :ref:`buildstats <ref-classes-buildstats>` data.
- The ``meta/conf/distro/include/package_regex.inc`` is now deprecated.
The contents of this file have been moved to individual recipes.
@@ -481,9 +481,9 @@ The following miscellaneous changes have occurred:
is an unnecessary burden.
If you need to preserve these ``.la`` files (e.g. in a custom
distribution), you must change
:term:`INHERIT_DISTRO` such that
"remove-libtool" is not included in the value.
distribution), you must change :term:`INHERIT_DISTRO` such that
":ref:`remove-libtool <ref-classes-remove-libtool>`" is not included
in the value.
- Extensible SDKs built for GCC 5+ now refuse to install on a
distribution where the host GCC version is 4.8 or 4.9. This change
@@ -492,18 +492,17 @@ The following miscellaneous changes have occurred:
the :ref:`uninative <ref-classes-uninative>` class for additional
information.
- All native and nativesdk recipes now use a separate
- All :ref:`native <ref-classes-native>` and
:ref:`nativesdk <ref-classes-nativesdk>` recipes now use a separate
:term:`DISTRO_FEATURES` value instead of sharing the value used by
recipes for the target, in order to avoid unnecessary rebuilds.
The :term:`DISTRO_FEATURES` for ``native`` recipes is
:term:`DISTRO_FEATURES_NATIVE` added to
an intersection of :term:`DISTRO_FEATURES` and
:term:`DISTRO_FEATURES_FILTER_NATIVE`.
The :term:`DISTRO_FEATURES` for :ref:`native <ref-classes-native>` recipes
is :term:`DISTRO_FEATURES_NATIVE` added to an intersection of
:term:`DISTRO_FEATURES` and :term:`DISTRO_FEATURES_FILTER_NATIVE`.
For nativesdk recipes, the corresponding variables are
:term:`DISTRO_FEATURES_NATIVESDK`
and
For :ref:`nativesdk <ref-classes-nativesdk>` recipes, the corresponding
variables are :term:`DISTRO_FEATURES_NATIVESDK` and
:term:`DISTRO_FEATURES_FILTER_NATIVESDK`.
- The ``FILESDIR`` variable, which was previously deprecated and rarely
@@ -128,7 +128,8 @@ missing from :term:`DEPENDS`).
This change affects classes beyond just the two mentioned (i.e.
``distutils`` and ``distutils3``). Any recipe that inherits ``distutils*``
classes are affected. For example, the ``setuptools`` and ``setuptools3``
classes are affected. For example, the ``setuptools`` and
:ref:`setuptools3 <ref-classes-setuptools3>`
recipes are affected since they inherit the ``distutils*`` classes.
Fetching these types of dependencies that are not provided in the
@@ -315,13 +316,12 @@ This section provides information about automatic testing changes:
exists and has been replaced by the
:term:`TESTIMAGE_AUTO` variable.
- Inheriting the ``testimage`` and ``testsdk`` Classes: Best
practices now dictate that you use the
:term:`IMAGE_CLASSES` variable rather than the
- Inheriting the :ref:`testimage <ref-classes-testimage>` and
:ref:`testsdk <ref-classes-testsdk>` classes: best practices now dictate
that you use the :term:`IMAGE_CLASSES` variable rather than the
:term:`INHERIT` variable when you inherit the
:ref:`testimage <ref-classes-testimage>` and
:ref:`testsdk <ref-classes-testsdk>` classes used for automatic
testing.
:ref:`testsdk <ref-classes-testsdk>` classes used for automatic testing.
.. _migration-2.6-openssl-changes:
@@ -282,8 +282,8 @@ The following miscellaneous changes have occurred.
- You must change the host distro identifier used in
:term:`NATIVELSBSTRING` to use all lowercase
characters even if it does not contain a version number. This change
is necessary only if you are not using ``uninative`` and
:term:`SANITY_TESTED_DISTROS`.
is necessary only if you are not using
:ref:`uninative <ref-classes-uninative>` and :term:`SANITY_TESTED_DISTROS`.
- In the ``base-files`` recipe, writing the hostname into
``/etc/hosts`` and ``/etc/hostname`` is now done within the main
@@ -217,7 +217,13 @@ Most recipes and classes that inherit the :ref:`deploy <ref-classes-deploy>` cla
Custom SDK / SDK-style recipes need to include ``nativesdk-sdk-provides-dummy``
-------------------------------------------------------------------------------
All ``nativesdk`` packages require ``/bin/sh`` due to their postinstall scriptlets, thus this package has to be dummy-provided within the SDK and ``nativesdk-sdk-provides-dummy`` now does this. If you have a custom SDK recipe (or your own SDK-style recipe similar to e.g. ``buildtools-tarball``), you will need to ensure ``nativesdk-sdk-provides-dummy`` or an equivalent is included in :term:`TOOLCHAIN_HOST_TASK`.
All :ref:`nativesdk <ref-classes-nativesdk>` packages require ``/bin/sh`` due
to their postinstall scriptlets, thus this package has to be dummy-provided
within the SDK and ``nativesdk-sdk-provides-dummy`` now does this. If you have
a custom SDK recipe (or your own SDK-style recipe similar to e.g.
``buildtools-tarball``), you will need to ensure
``nativesdk-sdk-provides-dummy`` or an equivalent is included in
:term:`TOOLCHAIN_HOST_TASK`.
``ld.so.conf`` now moved back to main ``glibc`` package
@@ -61,13 +61,15 @@ need to update those.
New ``python3targetconfig`` class
---------------------------------
A new :ref:`python3targetconfig <ref-classes-python3targetconfig>` class has been
created for situations where you would previously have inherited the
:ref:`python3native <ref-classes-python3native>` class but need access to target configuration data (such as
correct installation directories). Recipes where this situation applies should
be changed to inherit ``python3targetconfig`` instead of ``python3native``. This
also adds a dependency on target ``python3``, so it should only be used where
appropriate in order to avoid unnecessarily lengthening builds.
A new :ref:`python3targetconfig <ref-classes-python3targetconfig>` class has
been created for situations where you would previously have inherited the
:ref:`python3native <ref-classes-python3native>` class but need access to
target configuration data (such as correct installation directories). Recipes
where this situation applies should be changed to inherit
:ref:`python3targetconfig <ref-classes-python3targetconfig>` instead of
:ref:`python3native <ref-classes-python3native>`. This also adds a dependency
on target ``python3``, so it should only be used where appropriate in order to
avoid unnecessarily lengthening builds.
Some example recipes where this change has been made: ``gpgme``, ``libcap-ng``,
``python3-pycairo``.
@@ -124,7 +124,7 @@ Removed classes
- ``image-mklibs``: not actively tested and upstream mklibs still
requires Python 2
- ``meta``: no longer useful. Recipes that need to skip installing
packages should inherit ``nopackages`` instead.
packages should inherit :ref:`nopackages <ref-classes-nopackages>` instead.
Prelinking disabled by default
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -79,18 +79,19 @@ any new Yocto Project release.
the migration (e.g. added/removed packages, added/removed files, size
changes etc.). To do this, follow these steps:
1. Enable buildhistory before the migration
1. Enable :ref:`buildhistory <ref-classes-buildhistory>` before the migration
2. Run a pre-migration build
3. Capture the buildhistory output (as specified by :term:`BUILDHISTORY_DIR`)
and ensure it is preserved for subsequent builds. How you would do this
depends on how you are running your builds - if you are doing this all on
one workstation in the same :term:`Build Directory` you may not need to do
anything other than not deleting the buildhistory output directory. For
builds in a pipeline it may be more complicated.
3. Capture the :ref:`buildhistory <ref-classes-buildhistory>` output (as
specified by :term:`BUILDHISTORY_DIR`) and ensure it is preserved for
subsequent builds. How you would do this depends on how you are running
your builds - if you are doing this all on one workstation in the same
:term:`Build Directory` you may not need to do anything other than not
deleting the :ref:`buildhistory <ref-classes-buildhistory>` output
directory. For builds in a pipeline it may be more complicated.
4. Set a tag in the buildhistory output (which is a git repository) before
4. Set a tag in the :ref:`buildhistory <ref-classes-buildhistory>` output (which is a git repository) before
migration, to make the commit from the pre-migration build easy to find
as you may end up running multiple builds during the migration.
@@ -99,7 +100,7 @@ any new Yocto Project release.
6. Run a build
7. Check the output changes between the previously set tag and HEAD in the
buildhistory output using ``git diff`` or ``buildhistory-diff``.
:ref:`buildhistory <ref-classes-buildhistory>` output using ``git diff`` or ``buildhistory-diff``.
For more information on using buildhistory, see
For more information on using :ref:`buildhistory <ref-classes-buildhistory>`, see
:ref:`dev-manual/common-tasks:maintaining build output quality`.
@@ -7,7 +7,7 @@ New Features / Enhancements in 3.4
- Linux kernel 5.14, glibc 2.34 and ~280 other recipe upgrades
- Switched override character to ':' (replacing '_') for more robust parsing and improved performance --- see the above migration guide for help
- Rust integrated into core, providing rust support for cross-compilation and SDK
- New create-spdx class for creating SPDX SBoM documents
- New :ref:`create-spdx <ref-classes-create-spdx>` class for creating SPDX SBoM documents
- New recipes: cargo, core-image-ptest-all, core-image-ptest-fast, core-image-weston-sdk, erofs-utils, gcompat, gi-docgen, libmicrohttpd, libseccomp, libstd-rs, perlcross, python3-markdown, python3-pyyaml, python3-smartypants, python3-typogrify, rust, rust-cross, rust-cross-canadian, rust-hello-world, rust-llvm, rust-tools-cross-canadian, rustfmt, xwayland
- Several optimisations to reduce unnecessary task dependencies for faster builds
- seccomp integrated into core, with additional enabling for gnutls, systemd, qemu
@@ -68,7 +68,9 @@ New Features / Enhancements in 3.4
- SDK-related enhancements:
- Enable :ref:`ref-tasks-populate_sdk` with multilibs
- New ``SDKPATHINSTALL`` variable decouples default install path from built in path to avoid rebuilding nativesdk components on e.g. :term:`DISTRO_VERSION` changes
- New ``SDKPATHINSTALL`` variable decouples default install path from
built in path to avoid rebuilding :ref:`nativesdk <ref-classes-nativesdk>`
components on e.g. :term:`DISTRO_VERSION` changes
- eSDK: Error if trying to generate an eSDK from a multiconfig
- eSDK: introduce :term:`TOOLCHAIN_HOST_TASK_ESDK` to be used in place of :term:`TOOLCHAIN_HOST_TASK` to add components to the host part of the eSDK
@@ -8,9 +8,10 @@ New Features / Enhancements in 4.0
- Linux kernel 5.15, glibc 2.35 and ~300 other recipe upgrades
- Reproducibility: this release fixes the reproducibility issues with ``rust-llvm`` and
``golang``. Recipes in OpenEmbedded-Core are now fully reproducible. Functionality
previously in the optional "reproducible" class has been merged into the base class.
- Reproducibility: this release fixes the reproducibility issues with
``rust-llvm`` and ``golang``. Recipes in OpenEmbedded-Core are now fully
reproducible. Functionality previously in the optional "reproducible"
class has been merged into the :ref:`base <ref-classes-base>` class.
- Network access is now disabled by default for tasks other than where it is expected to ensure build integrity (where host kernel supports it)
@@ -215,7 +216,7 @@ New Features / Enhancements in 4.0
- Ensure addition of patch-fuzz retriggers do_qa_patch
- Added a sanity check for allarch packagegroups
- create-spdx class improvements:
- :ref:`create-spdx <ref-classes-create-spdx>` class improvements:
- Get SPDX-License-Identifier from source files
- Generate manifest also for SDKs
@@ -235,8 +236,10 @@ New Features / Enhancements in 4.0
- SDK-related enhancements:
- Extended recipes to ``nativesdk``: ``cargo``, ``librsvg``, ``libstd-rs``, ``libva``, ``python3-docutil``, ``python3-packaging``
- Enabled nativesdk recipes to find a correct version of the rust cross compiler
- Extended recipes to :ref:`nativesdk <ref-classes-nativesdk>`: ``cargo``,
``librsvg``, ``libstd-rs``, ``libva``, ``python3-docutil``, ``python3-packaging``
- Enabled :ref:`nativesdk <ref-classes-nativesdk>` recipes to find a correct version
of the rust cross compiler
- Support creating per-toolchain cmake file in SDK
- Rust enhancements:
@@ -58,7 +58,7 @@ New Features / Enhancements in 4.1
- Dependency of -dev package on main package is now an :term:`RRECOMMENDS` and can be easily set via new :term:`DEV_PKG_DEPENDENCY` variable
- Support for CPU, I/O and memory pressure regulation in BitBake
- Pressure data gathering in ``buildstats`` and rendering in ``pybootchartgui``
- Pressure data gathering in :ref:`buildstats <ref-classes-buildstats>` and rendering in ``pybootchartgui``
- New Picobuild system for lightweight Python PEP-517 build support in the :ref:`python_pep517 <ref-classes-python_pep517>` class
@@ -99,8 +99,8 @@ New Features / Enhancements in 4.1
- :ref:`Support for using the regular build system as an SDK <sdk-manual/extensible:Setting up the Extensible SDK environment directly in a Yocto build>`
- :ref:`image-buildinfo <ref-classes-image-buildinfo>` class now also writes build information to SDKs
- New :term:`SDK_TOOLCHAIN_LANGS` variable to control support of rust / go in SDK
- rust-llvm: enabled nativesdk variant
- python3-pluggy: enabled for native/nativesdk
- rust-llvm: enabled :ref:`nativesdk <ref-classes-nativesdk>` variant
- python3-pluggy: enabled for :ref:`native <ref-classes-native>` / :ref:`nativesdk <ref-classes-nativesdk>`
- QEMU/runqemu enhancements:
@@ -113,7 +113,8 @@ New Features / Enhancements in 4.1
- New variable :term:`UBOOT_MKIMAGE_KERNEL_TYPE`
- New variable :term:`FIT_PAD_ALG` to control FIT image padding algorithm
- New :term:`KERNEL_DEPLOY_DEPEND` variable to allow disabling image dependency on deploying the kernel
- image_types: isolate the write of UBI configuration to a ``write_ubi_config`` function that can be easily overridden
- :ref:`image_types <ref-classes-image_types>`: isolate the write of UBI
configuration to a ``write_ubi_config`` function that can be easily overridden
- openssh: add support for config snippet includes to ssh and sshd
- :ref:`create-spdx <ref-classes-create-spdx>`: Add ``SPDX_PRETTY`` option