From 292598164a304a3da3288e6fb8963f13045d1e7f Mon Sep 17 00:00:00 2001 From: Richard Purdie Date: Mon, 14 Sep 2020 22:48:44 +0200 Subject: sphinx: ref-manual links fixes and many other cleanups to import (From yocto-docs rev: d079e418d5a81610e1f06a7a6ca45dd040c1402e) Signed-off-by: Richard Purdie --- documentation/ref-manual/ref-classes.rst | 436 ++++++++++++++++++------------- 1 file changed, 258 insertions(+), 178 deletions(-) (limited to 'documentation/ref-manual/ref-classes.rst') diff --git a/documentation/ref-manual/ref-classes.rst b/documentation/ref-manual/ref-classes.rst index ace69e15a7..60ce8efd21 100644 --- a/documentation/ref-manual/ref-classes.rst +++ b/documentation/ref-manual/ref-classes.rst @@ -47,7 +47,7 @@ splitting out of debug symbols during packaging). even if the recipes do not produce architecture-specific output. Configuring such recipes for all architectures causes the - ```do_package_write_*`` <#ref-tasks-package_write_deb>`__ tasks to + ```do_package_write_*`` tasks to have different signatures for the machines with different tunings. Additionally, unnecessary rebuilds occur every time an image for a different ``MACHINE`` is built even when the recipe never changes. @@ -67,9 +67,8 @@ inherit the ``allarch`` class. The ``archiver`` class supports releasing source code and other materials with the binaries. -For more details on the source archiver, see the "`Maintaining Open -Source License Compliance During Your Product's -Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__" +For more details on the source archiver, see the +":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" section in the Yocto Project Development Tasks Manual. You can also see the :term:`ARCHIVER_MODE` variable for information about the variable flags (varflags) that help control archive creation. @@ -86,8 +85,8 @@ standardization. This class defines a set of tasks (e.g. ``configure``, ``compile`` and so forth) that work for all Autotooled packages. It should usually be enough to define a few standard variables and then simply ``inherit autotools``. These classes can also work with software -that emulates Autotools. For more information, see the "`Autotooled -Package <&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package>`__" section +that emulates Autotools. For more information, see the +":ref:`new-recipe-autotooled-package`" section in the Yocto Project Development Tasks Manual. By default, the ``autotools*`` classes use out-of-tree builds (i.e. @@ -177,7 +176,7 @@ example use for this class. :: SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}" - + See the " Fetchers @@ -229,8 +228,10 @@ value as a variable flag (varflag) and provide a reason, which is reported, if the package is requested to be built as the value. For example, if you want to blacklist a recipe called "exoticware", you add the following to your ``local.conf`` or distribution configuration: -INHERIT += "blacklist" PNBLACKLIST[exoticware] = "Not supported by our -organization." +:: + + INHERIT += "blacklist" + PNBLACKLIST[exoticware] = "Not supported by our organization." .. _ref-classes-buildhistory: @@ -240,8 +241,8 @@ organization." The ``buildhistory`` class records a history of build output metadata, which can be used to detect possible regressions as well as used for analysis of the build output. For more information on using Build -History, see the "`Maintaining Build Output -Quality <&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality>`__" +History, see the +":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`" section in the Yocto Project Development Tasks Manual. .. _ref-classes-buildstats: @@ -411,8 +412,7 @@ cross-compilation tools. The ``cross-canadian`` class provides support for the recipes that build the Canadian Cross-compilation tools for SDKs. See the -"`Cross-Development Toolchain -Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__" +":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`" section in the Yocto Project Overview and Concepts Manual for more discussion on these cross-compilation tools. @@ -423,8 +423,7 @@ discussion on these cross-compilation tools. The ``crosssdk`` class provides support for the recipes that build the cross-compilation tools used for building SDKs. See the -"`Cross-Development Toolchain -Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__" +":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`" section in the Yocto Project Overview and Concepts Manual for more discussion on these cross-compilation tools. @@ -465,8 +464,7 @@ staging the files from ``DEPLOYDIR`` to ``DEPLOY_DIR_IMAGE``. ==================== The ``devshell`` class adds the ``do_devshell`` task. Distribution -policy dictates whether to include this class. See the "`Using a -Development Shell <&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell>`__" +policy dictates whether to include this class. See the ":ref:`platdev-appdev-devshell`" section in the Yocto Project Development Tasks Manual for more information about using ``devshell``. @@ -478,16 +476,26 @@ information about using ``devshell``. The ``devupstream`` class uses :term:`BBCLASSEXTEND` to add a variant of the recipe that fetches from an alternative URI (e.g. Git) instead of a -tarball. Following is an example: BBCLASSEXTEND = "devupstream:target" -SRC_URI_class-devupstream = "git://git.example.com/example" -SRCREV_class-devupstream = "abcd1234" Adding the above statements to -your recipe creates a variant that has +tarball. Following is an example: +:: + + BBCLASSEXTEND = "devupstream:target" + SRC_URI_class-devupstream = "git://git.example.com/example" + SRCREV_class-devupstream = "abcd1234" + +Adding the above statements to your recipe creates a variant that has :term:`DEFAULT_PREFERENCE` set to "-1". Consequently, you need to select the variant of the recipe to use it. Any development-specific adjustments can be done by using the ``class-devupstream`` override. Here is an example: -DEPENDS_append_class-devupstream = " gperf-native" -do_configure_prepend_class-devupstream() { touch ${S}/README } The class +:: + + DEPENDS_append_class-devupstream = " gperf-native" + do_configure_prepend_class-devupstream() { + touch ${S}/README + } + +The class currently only supports creating a development variant of the target recipe, not ``native`` or ``nativesdk`` variants. @@ -587,15 +595,19 @@ that use the :term:`B` variable to point to the directory in which the OpenEmbedded build system places the generated objects built from the recipes. By default, the ``B`` directory is set to the following, which is separate from the source directory (``S``): -${WORKDIR}/${BPN}/{PV}/ See these variables for more information: +:: + + ${WORKDIR}/${BPN}/{PV}/ + +See these variables for more information: :term:`WORKDIR`, :term:`BPN`, and :term:`PV`, For more information on the ``externalsrc`` class, see the comments in ``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`. For information on how to use the -``externalsrc`` class, see the "`Building Software from an External -Source <&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source>`__" +``externalsrc`` class, see the +":ref:`dev-manual/dev-manual-common-tasks:building software from an external source`" section in the Yocto Project Development Tasks Manual. .. _ref-classes-extrausers: @@ -619,15 +631,36 @@ be performed using the useradd class to add user and group configuration to a specific recipe. -Here is an example that uses this class in an image recipe: inherit -extrausers EXTRA_USERS_PARAMS = "\\ useradd -p '' tester; \\ groupadd -developers; \\ userdel nobody; \\ groupdel -g video; \\ groupmod -g 1020 -developers; \\ usermod -s /bin/sh tester; \\ " Here is an example that -adds two users named "tester-jim" and "tester-sue" and assigns -passwords: inherit extrausers EXTRA_USERS_PARAMS = "\\ useradd -P -tester01 tester-jim; \\ useradd -P tester01 tester-sue; \\ " Finally, -here is an example that sets the root password to "1876*18": inherit -extrausers EXTRA_USERS_PARAMS = "\\ usermod -P 1876*18 root; \\ " +Here is an example that uses this class in an image recipe: +:: + + inherit extrausers + EXTRA_USERS_PARAMS = "\ + useradd -p '' tester; \ + groupadd developers; \ + userdel nobody; \ + groupdel -g video; \ + groupmod -g 1020 developers; \ + usermod -s /bin/sh tester; \ + " + +Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns +passwords: +:: + + inherit extrausers + EXTRA_USERS_PARAMS = "\ + useradd -P tester01 tester-jim; \ + useradd -P tester01 tester-sue; \ + " + +Finally, here is an example that sets the root password to "1876*18": +:: + + inherit extrausers + EXTRA_USERS_PARAMS = "\ + usermod -P 1876*18 root; \ + " .. _ref-classes-fontcache: @@ -837,8 +870,7 @@ provided by the recipe ``icecc-create-env-native.bb``. .. note:: This script is a modified version and not the one that comes with - icecc - . + icecc. If you do not want the Icecream distributed compile support to apply to specific recipes or classes, you can effectively "blacklist" them by @@ -863,10 +895,18 @@ At the distribution level, you can inherit the ``icecc`` class to be sure that all builders start with the same sstate signatures. After inheriting the class, you can then disable the feature by setting the :term:`ICECC_DISABLED` variable to "1" as follows: -INHERIT_DISTRO_append = " icecc" ICECC_DISABLED ??= "1" This practice +:: + + INHERIT_DISTRO_append = " icecc" + ICECC_DISABLED ??= "1" + +This practice makes sure everyone is using the same signatures but also requires individuals that do want to use Icecream to enable the feature -individually as follows in your ``local.conf`` file: ICECC_DISABLED = "" +individually as follows in your ``local.conf`` file: +:: + + ICECC_DISABLED = "" .. _ref-classes-image: @@ -884,11 +924,11 @@ then one or more image files are created. - The ``IMAGE_INSTALL`` variable controls the list of packages to install into the image. -For information on customizing images, see the "`Customizing -Images <&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage>`__" section +For information on customizing images, see the +":ref:`usingpoky-extend-customimage`" section in the Yocto Project Development Tasks Manual. For information on how images are created, see the -"`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__" section in the +":ref:`images-dev-environment`" section in the Yocto Project Overview and Concpets Manual. .. _ref-classes-image-buildinfo: @@ -912,19 +952,19 @@ types. By default, the :ref:`image ` class automatically enables the ``image_types`` class. The ``image`` class uses the -``IMGCLASSES`` variable as follows: IMGCLASSES = -"rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}" IMGCLASSES += -"${@['populate_sdk_base', 'populate_sdk_ext']['linux' in -d.getVar("SDK_OS")]}" IMGCLASSES += -"${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', -'image-live', '', d)}" IMGCLASSES += -"${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', -'', d)}" IMGCLASSES += "image_types_wic" IMGCLASSES += -"rootfs-postcommands" IMGCLASSES += "image-postinst-intercepts" inherit -${IMGCLASSES} - -The ``image_types`` class also handles conversion and compression of -images. +``IMGCLASSES`` variable as follows: +:: + + IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}" + IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}" + IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}" + IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}" + IMGCLASSES += "image_types_wic" + IMGCLASSES += "rootfs-postcommands" + IMGCLASSES += "image-postinst-intercepts" + inherit ${IMGCLASSES} + +The ``image_types`` class also handles conversion and compression of images. .. note:: @@ -957,7 +997,9 @@ the size of libraries contained in the image. By default, the class is enabled in the ``local.conf.template`` using the :term:`USER_CLASSES` variable as follows: -USER_CLASSES ?= "buildstats image-mklibs image-prelink" +:: + + USER_CLASSES ?= "buildstats image-mklibs image-prelink" .. _ref-classes-image-prelink: @@ -971,7 +1013,9 @@ time. By default, the class is enabled in the ``local.conf.template`` using the :term:`USER_CLASSES` variable as follows: -USER_CLASSES ?= "buildstats image-mklibs image-prelink" +:: + + USER_CLASSES ?= "buildstats image-mklibs image-prelink" .. _ref-classes-insane: @@ -1000,32 +1044,36 @@ should use :term:`INSANE_SKIP`. For example, to skip the check for symbolic link ``.so`` files in the main package of a recipe, add the following to the recipe. You need to realize that the package name override, in this example ``${PN}``, must be used: -INSANE_SKIP_${PN} += "dev-so" Please keep in mind that the QA checks +:: + + INSANE_SKIP_${PN} += "dev-so" + +Please keep in mind that the QA checks exist in order to detect real or potential problems in the packaged output. So exercise caution when disabling these checks. The following list shows the tests you can list with the ``WARN_QA`` and ``ERROR_QA`` variables: -- *``already-stripped:``* Checks that produced binaries have not +- ``already-stripped:`` Checks that produced binaries have not already been stripped prior to the build system extracting debug symbols. It is common for upstream software projects to default to stripping debug symbols for output binaries. In order for debugging to work on the target using ``-dbg`` packages, this stripping must be disabled. -- *``arch:``* Checks the Executable and Linkable Format (ELF) type, bit +- ``arch:`` Checks the Executable and Linkable Format (ELF) type, bit size, and endianness of any binaries to ensure they match the target architecture. This test fails if any binaries do not match the type since there would be an incompatibility. The test could indicate that the wrong compiler or compiler options have been used. Sometimes software, like bootloaders, might need to bypass this check. -- *``buildpaths:``* Checks for paths to locations on the build host +- ``buildpaths:`` Checks for paths to locations on the build host inside the output files. Currently, this test triggers too many false positives and thus is not normally enabled. -- *``build-deps:``* Determines if a build-time dependency that is +- ``build-deps:`` Determines if a build-time dependency that is specified through :term:`DEPENDS`, explicit :term:`RDEPENDS`, or task-level dependencies exists to match any runtime dependency. This determination is particularly @@ -1045,20 +1093,20 @@ The following list shows the tests you can list with the ``WARN_QA`` and ``initscripts`` recipe is actually built and thus the ``initscripts-functions`` package is made available. -- *``compile-host-path:``* Checks the +- ``compile-host-path:`` Checks the :ref:`ref-tasks-compile` log for indications that paths to locations on the build host were used. Using such paths might result in host contamination of the build output. -- *``debug-deps:``* Checks that all packages except ``-dbg`` packages +- ``debug-deps:`` Checks that all packages except ``-dbg`` packages do not depend on ``-dbg`` packages, which would cause a packaging bug. -- *``debug-files:``* Checks for ``.debug`` directories in anything but +- ``debug-files:`` Checks for ``.debug`` directories in anything but the ``-dbg`` package. The debug files should all be in the ``-dbg`` package. Thus, anything packaged elsewhere is incorrect packaging. -- *``dep-cmp:``* Checks for invalid version comparison statements in +- ``dep-cmp:`` Checks for invalid version comparison statements in runtime dependency relationships between packages (i.e. in :term:`RDEPENDS`, :term:`RRECOMMENDS`, @@ -1069,22 +1117,22 @@ The following list shows the tests you can list with the ``WARN_QA`` and comparisons might trigger failures or undesirable behavior when passed to the package manager. -- *``desktop:``* Runs the ``desktop-file-validate`` program against any +- ``desktop:`` Runs the ``desktop-file-validate`` program against any ``.desktop`` files to validate their contents against the specification for ``.desktop`` files. -- *``dev-deps:``* Checks that all packages except ``-dev`` or +- ``dev-deps:`` Checks that all packages except ``-dev`` or ``-staticdev`` packages do not depend on ``-dev`` packages, which would be a packaging bug. -- *``dev-so:``* Checks that the ``.so`` symbolic links are in the +- ``dev-so:`` Checks that the ``.so`` symbolic links are in the ``-dev`` package and not in any of the other packages. In general, these symlinks are only useful for development purposes. Thus, the ``-dev`` package is the correct location for them. Some very rare cases do exist for dynamically loaded modules where these symlinks are needed instead in the main package. -- *``file-rdeps:``* Checks that file-level dependencies identified by +- ``file-rdeps:`` Checks that file-level dependencies identified by the OpenEmbedded build system at packaging time are satisfied. For example, a shell script might start with the line ``#!/bin/bash``. This line would translate to a file dependency on ``/bin/bash``. Of @@ -1097,10 +1145,10 @@ The following list shows the tests you can list with the ``WARN_QA`` and :term:`RDEPENDS` exist to handle any file-level dependency detected in packaged files. -- *``files-invalid:``* Checks for :term:`FILES` variable +- ``files-invalid:`` Checks for :term:`FILES` variable values that contain "//", which is invalid. -- *``host-user-contaminated:``* Checks that no package produced by the +- ``host-user-contaminated:`` Checks that no package produced by the recipe contains any files outside of ``/home`` with a user or group ID that matches the user running BitBake. A match usually indicates that the files are being installed with an incorrect UID/GID, since @@ -1108,16 +1156,16 @@ The following list shows the tests you can list with the ``WARN_QA`` and see the section describing the :ref:`ref-tasks-install` task. -- *``incompatible-license:``* Report when packages are excluded from +- ``incompatible-license:`` Report when packages are excluded from being created due to being marked with a license that is in :term:`INCOMPATIBLE_LICENSE`. -- *``install-host-path:``* Checks the +- ``install-host-path:`` Checks the :ref:`ref-tasks-install` log for indications that paths to locations on the build host were used. Using such paths might result in host contamination of the build output. -- *``installed-vs-shipped:``* Reports when files have been installed +- ``installed-vs-shipped:`` Reports when files have been installed within ``do_install`` but have not been included in any package by way of the :term:`FILES` variable. Files that do not appear in any package cannot be present in an image later on in the @@ -1125,67 +1173,69 @@ The following list shows the tests you can list with the ``WARN_QA`` and installed at all. These files can be deleted at the end of ``do_install`` if the files are not needed in any package. -- *``invalid-chars:``* Checks that the recipe metadata variables +- ``invalid-chars:`` Checks that the recipe metadata variables :term:`DESCRIPTION`, :term:`SUMMARY`, :term:`LICENSE`, and :term:`SECTION` do not contain non-UTF-8 characters. Some package managers do not support such characters. -- *``invalid-packageconfig:``* Checks that no undefined features are +- ``invalid-packageconfig:`` Checks that no undefined features are being added to :term:`PACKAGECONFIG`. For example, any name "foo" for which the following form does not exist: - PACKAGECONFIG[foo] = "..." + :: + + PACKAGECONFIG[foo] = "..." -- *``la:``* Checks ``.la`` files for any ``TMPDIR`` paths. Any ``.la`` +- ``la:`` Checks ``.la`` files for any ``TMPDIR`` paths. Any ``.la`` file containing these paths is incorrect since ``libtool`` adds the correct sysroot prefix when using the files automatically itself. -- *``ldflags:``* Ensures that the binaries were linked with the +- ``ldflags:`` Ensures that the binaries were linked with the :term:`LDFLAGS` options provided by the build system. If this test fails, check that the ``LDFLAGS`` variable is being passed to the linker command. -- *``libdir:``* Checks for libraries being installed into incorrect +- ``libdir:`` Checks for libraries being installed into incorrect (possibly hardcoded) installation paths. For example, this test will catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is "lib32". Another example is when recipes install ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib". -- *``libexec:``* Checks if a package contains files in +- ``libexec:`` Checks if a package contains files in ``/usr/libexec``. This check is not performed if the ``libexecdir`` variable has been set explicitly to ``/usr/libexec``. -- *``packages-list:``* Checks for the same package being listed +- ``packages-list:`` Checks for the same package being listed multiple times through the :term:`PACKAGES` variable value. Installing the package in this manner can cause errors during packaging. -- *``perm-config:``* Reports lines in ``fs-perms.txt`` that have an +- ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an invalid format. -- *``perm-line:``* Reports lines in ``fs-perms.txt`` that have an +- ``perm-line:`` Reports lines in ``fs-perms.txt`` that have an invalid format. -- *``perm-link:``* Reports lines in ``fs-perms.txt`` that specify +- ``perm-link:`` Reports lines in ``fs-perms.txt`` that specify 'link' where the specified target already exists. -- *``perms:``* Currently, this check is unused but reserved. +- ``perms:`` Currently, this check is unused but reserved. -- *``pkgconfig:``* Checks ``.pc`` files for any +- ``pkgconfig:`` Checks ``.pc`` files for any :term:`TMPDIR`/:term:`WORKDIR` paths. Any ``.pc`` file containing these paths is incorrect since ``pkg-config`` itself adds the correct sysroot prefix when the files are accessed. -- *``pkgname:``* Checks that all packages in +- ``pkgname:`` Checks that all packages in :term:`PACKAGES` have names that do not contain invalid characters (i.e. characters other than 0-9, a-z, ., +, and -). -- *``pkgv-undefined:``* Checks to see if the ``PKGV`` variable is +- ``pkgv-undefined:`` Checks to see if the ``PKGV`` variable is undefined during :ref:`ref-tasks-package`. -- *``pkgvarcheck:``* Checks through the variables +- ``pkgvarcheck:`` Checks through the variables :term:`RDEPENDS`, :term:`RRECOMMENDS`, :term:`RSUGGESTS`, @@ -1199,7 +1249,7 @@ The following list shows the tests you can list with the ``WARN_QA`` and unnecessarily complicate dependencies of other packages within the same recipe or have other unintended consequences. -- *``pn-overrides:``* Checks that a recipe does not have a name +- ``pn-overrides:`` Checks that a recipe does not have a name (:term:`PN`) value that appears in :term:`OVERRIDES`. If a recipe is named such that its ``PN`` value matches something already in ``OVERRIDES`` (e.g. @@ -1208,43 +1258,43 @@ The following list shows the tests you can list with the ``WARN_QA`` and For example, assignments such as ``FILES_${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``. -- *``rpaths:``* Checks for rpaths in the binaries that contain build +- ``rpaths:`` Checks for rpaths in the binaries that contain build system paths such as ``TMPDIR``. If this test fails, bad ``-rpath`` options are being passed to the linker commands and your binaries have potential security issues. -- *``split-strip:``* Reports that splitting or stripping debug symbols +- ``split-strip:`` Reports that splitting or stripping debug symbols from binaries has failed. -- *``staticdev:``* Checks for static library files (``*.a``) in +- ``staticdev:`` Checks for static library files (``*.a``) in non-``staticdev`` packages. -- *``symlink-to-sysroot:``* Checks for symlinks in packages that point +- ``symlink-to-sysroot:`` Checks for symlinks in packages that point into :term:`TMPDIR` on the host. Such symlinks will work on the host, but are clearly invalid when running on the target. -- *``textrel:``* Checks for ELF binaries that contain relocations in +- ``textrel:`` Checks for ELF binaries that contain relocations in their ``.text`` sections, which can result in a performance impact at runtime. See the explanation for the ```ELF binary`` <#qa-issue-textrel>`__ message for more information regarding runtime performance issues. -- *``unlisted-pkg-lics:``* Checks that all declared licenses applying +- ``unlisted-pkg-lics:`` Checks that all declared licenses applying for a package are also declared on the recipe level (i.e. any license in ``LICENSE_*`` should appear in :term:`LICENSE`). -- *``useless-rpaths:``* Checks for dynamic library load paths (rpaths) +- ``useless-rpaths:`` Checks for dynamic library load paths (rpaths) in the binaries that by default on a standard system are searched by the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will not cause any breakage, they do waste space and are unnecessary. -- *``var-undefined:``* Reports when variables fundamental to packaging +- ``var-undefined:`` Reports when variables fundamental to packaging (i.e. :term:`WORKDIR`, :term:`DEPLOY_DIR`, :term:`D`, :term:`PN`, and :term:`PKGD`) are undefined during :ref:`ref-tasks-package`. -- *``version-going-backwards:``* If Build History is enabled, reports +- ``version-going-backwards:`` If Build History is enabled, reports when a package being written out has a lower version than the previously written package under the same name. If you are placing output packages into a feed and upgrading packages on a target system @@ -1257,7 +1307,7 @@ The following list shows the tests you can list with the ``WARN_QA`` and If you are not using runtime package management on your target system, then you do not need to worry about this situation. -- *``xorg-driver-abi:``* Checks that all packages containing Xorg +- ``xorg-driver-abi:`` Checks that all packages containing Xorg drivers have ABI dependencies. The ``xserver-xorg`` recipe provides driver ABI names. All drivers should depend on the ABI versions that they have been built against. Driver recipes that include @@ -1293,9 +1343,8 @@ packages such as ``kernel-vmlinux``. The ``kernel`` class contains logic that allows you to embed an initial RAM filesystem (initramfs) image when you build the kernel image. For -information on how to build an initramfs, see the "`Building an Initial -RAM Filesystem (initramfs) -Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" section in +information on how to build an initramfs, see the +":ref:`building-an-initramfs-image`" section in the Yocto Project Development Tasks Manual. Various other classes are used by the ``kernel`` and ``module`` classes @@ -1545,8 +1594,7 @@ and implements the :ref:`ref-tasks-compile` and everything needed to build and package a kernel module. For general information on out-of-tree Linux kernel modules, see the -"`Incorporating Out-of-Tree -Modules <&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules>`__" +":ref:`kernel-dev/kernel-dev-common:incorporating out-of-tree modules`" section in the Yocto Project Linux Kernel Development Manual. .. _ref-classes-module-base: @@ -1569,9 +1617,8 @@ The ``multilib*`` classes provide support for building libraries with different target optimizations or target architectures and installing them side-by-side in the same image. -For more information on using the Multilib feature, see the "`Combining -Multiple Versions of Library Files into One -Image <&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image>`__" +For more information on using the Multilib feature, see the +":ref:`combining-multiple-versions-library-files-into-one-image`" section in the Yocto Project Development Tasks Manual. .. _ref-classes-native: @@ -1597,14 +1644,18 @@ a couple different ways: naming convention: :: - myrecipe-native.bb - + myrecipe-native.bb + Not using this naming convention can lead to subtle problems caused by existing code that depends on that naming convention. - Create or modify a target recipe that contains the following: - :term:`BBCLASSEXTEND` = "native" Inside the + :: + + BBCLASSEXTEND = "native" + + Inside the recipe, use ``_class-native`` and ``_class-target`` overrides to specify any functionality specific to the respective native or target case. @@ -1632,7 +1683,11 @@ couple different ways: that the ``nativesdk`` class is inherited last. - Create a ``nativesdk`` variant of any recipe by adding the following: - :term:`BBCLASSEXTEND` = "nativesdk" Inside the + :: + + BBCLASSEXTEND = "nativesdk" + + Inside the recipe, use ``_class-nativesdk`` and ``_class-target`` overrides to specify any functionality specific to the respective SDK machine or target case. @@ -1643,7 +1698,7 @@ couple different ways: :: nativesdk-myrecipe.bb - + Not doing so can lead to subtle problems because code exists that depends on the naming convention. @@ -1675,9 +1730,8 @@ package manager (NPM) `__. npm:// fetcher to have dependencies fetched and packaged automatically. -For information on how to create NPM packages, see the "`Creating Node -Package Manager (NPM) -Packages <&YOCTO_DOCS_DEV_URL;#creating-node-package-manager-npm-packages>`__" +For information on how to create NPM packages, see the +":ref:`dev-manual/dev-manual-common-tasks:creating node package manager (npm) packages`" section in the Yocto Project Development Tasks Manual. .. _ref-classes-oelint: @@ -1706,8 +1760,12 @@ before attempting to fetch it from the upstream specified in To use this class, inherit it globally and specify :term:`SOURCE_MIRROR_URL`. Here is an example: -INHERIT += "own-mirrors" SOURCE_MIRROR_URL = -"http://example.com/my-source-mirror" You can specify only a single URL +:: + + INHERIT += "own-mirrors" + SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" + +You can specify only a single URL in ``SOURCE_MIRROR_URL``. .. _ref-classes-package: @@ -1742,9 +1800,8 @@ first class listed in this variable is used for image generation. If you take the optional step to set up a repository (package feed) on the development host that can be used by DNF, you can install packages from the feed while you are running the image on the target (i.e. -runtime installation of packages). For more information, see the "`Using -Runtime Package -Management <&YOCTO_DOCS_DEV_URL;#using-runtime-package-management>`__" +runtime installation of packages). For more information, see the +":ref:`dev-manual/dev-manual-common-tasks:using runtime package management`" section in the Yocto Project Development Tasks Manual. The package-specific class you choose can affect build-time performance @@ -1774,9 +1831,9 @@ consider some further things about using RPM: You can find additional information on the effects of the package class at these two Yocto Project mailing list links: -- `https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html <&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html>`__ +- https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html -- `https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html <&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html>`__ +- https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html .. _ref-classes-package_deb: @@ -1870,9 +1927,8 @@ group recipes (e.g. ``PACKAGES``, ``PACKAGE_ARCH``, ``ALLOW_EMPTY``, and so forth). It is highly recommended that all package group recipes inherit this class. -For information on how to use this class, see the "`Customizing Images -Using Custom Package -Groups <&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks>`__" +For information on how to use this class, see the +":ref:`usingpoky-extend-customimage-customtasks`" section in the Yocto Project Development Tasks Manual. Previously, this class was called the ``task`` class. @@ -1937,8 +1993,7 @@ files. The ``populate_sdk`` class provides support for SDK-only recipes. For information on advantages gained when building a cross-development toolchain using the :ref:`ref-tasks-populate_sdk` -task, see the "`Building an SDK -Installer <&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer>`__" +task, see the ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`" section in the Yocto Project Application Development and the Extensible Software Development Kit (eSDK) manual. @@ -1950,19 +2005,19 @@ Software Development Kit (eSDK) manual. The ``populate_sdk_*`` classes support SDK creation and consist of the following classes: -- *``populate_sdk_base``:* The base class supporting SDK creation under +- ``populate_sdk_base``: The base class supporting SDK creation under all package managers (i.e. DEB, RPM, and opkg). -- *``populate_sdk_deb``:* Supports creation of the SDK given the Debian +- ``populate_sdk_deb``: Supports creation of the SDK given the Debian package manager. -- *``populate_sdk_rpm``:* Supports creation of the SDK given the RPM +- ``populate_sdk_rpm``: Supports creation of the SDK given the RPM package manager. -- *``populate_sdk_ipk``:* Supports creation of the SDK given the opkg +- ``populate_sdk_ipk``: Supports creation of the SDK given the opkg (IPK format) package manager. -- *``populate_sdk_ext``:* Supports extensible SDK creation under all +- ``populate_sdk_ext``: Supports extensible SDK creation under all package managers. The ``populate_sdk_base`` class inherits the appropriate @@ -1977,8 +2032,10 @@ contains the cross-compiler and associated tooling, and the target, which contains a target root filesystem that is configured for the SDK usage. These two images reside in :term:`SDK_OUTPUT`, which consists of the following: -${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs -${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs +:: + + ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs + ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs Finally, the base populate SDK class creates the toolchain environment setup script, the tarball of the SDK, and the installer. @@ -1989,13 +2046,12 @@ These classes are inherited by and used with the ``populate_sdk_base`` class. For more information on the cross-development toolchain generation, see -the "`Cross-Development Toolchain -Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__" +the ":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`" section in the Yocto Project Overview and Concepts Manual. For information on advantages gained when building a cross-development toolchain using the :ref:`ref-tasks-populate_sdk` -task, see the "`Building an SDK -Installer <&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer>`__" +task, see the +":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`" section in the Yocto Project Application Development and the Extensible Software Development Kit (eSDK) manual. @@ -2034,8 +2090,8 @@ The ``primport`` class provides functionality for importing ``prserv.bbclass`` ================== -The ``prserv`` class provides functionality for using a `PR -service <&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service>`__ in order to +The ``prserv`` class provides functionality for using a :ref:`PR +service ` in order to automatically manage the incrementing of the :term:`PR` variable for each recipe. @@ -2054,11 +2110,10 @@ runtime tests for recipes that build software that provides these tests. This class is intended to be inherited by individual recipes. However, the class' functionality is largely disabled unless "ptest" appears in -:term:`DISTRO_FEATURES`. See the "`Testing -Packages With -ptest <&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest>`__" section in -the Yocto Project Development Tasks Manual for more information on -ptest. +:term:`DISTRO_FEATURES`. See the +":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`" +section in the Yocto Project Development Tasks Manual for more information +on ptest. .. _ref-classes-ptest-gnome: @@ -2068,10 +2123,9 @@ ptest. Enables package tests (ptests) specifically for GNOME packages, which have tests intended to be executed with ``gnome-desktop-testing``. -For information on setting up and running ptests, see the "`Testing -Packages With -ptest <&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest>`__" section in -the Yocto Project Development Tasks Manual. +For information on setting up and running ptests, see the +":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`" +section in the Yocto Project Development Tasks Manual. .. _ref-classes-python-dir: @@ -2142,7 +2196,9 @@ absent from both the sysroot and target packages. If a recipe needs the ``.la`` files to be installed, then the recipe can override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows: -REMOVE_LIBTOOL_LA = "0" +:: + + REMOVE_LIBTOOL_LA = "0" .. note:: @@ -2155,9 +2211,9 @@ REMOVE_LIBTOOL_LA = "0" ``report-error.bbclass`` ======================== -The ``report-error`` class supports enabling the `error reporting -tool <&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool>`__, which -allows you to submit build error information to a central database. +The ``report-error`` class supports enabling the :ref:`error reporting +tool `", +which allows you to submit build error information to a central database. The class collects debug information for recipe, recipe version, task, machine, distro, build system, target system, host distro, branch, @@ -2182,14 +2238,20 @@ preserves these files for inspection and possible debugging purposes. If you would rather have these files deleted to save disk space as the build progresses, you can enable ``rm_work`` by adding the following to your ``local.conf`` file, which is found in the :term:`Build Directory`. -INHERIT += "rm_work" If you are +:: + + INHERIT += "rm_work" + +If you are modifying and building source code out of the work directory for a recipe, enabling ``rm_work`` will potentially result in your changes to the source being lost. To exclude some recipes from having their work directories deleted by ``rm_work``, you can add the names of the recipe or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which can also be set in your ``local.conf`` file. Here is an example: -RM_WORK_EXCLUDE += "busybox glibc" +:: + + RM_WORK_EXCLUDE += "busybox glibc" .. _ref-classes-rootfs*: @@ -2219,8 +2281,7 @@ The root filesystem is created from packages using one of the :term:`PACKAGE_CLASSES` variable. For information on how root filesystem images are created, see the -"`Image -Generation <&YOCTO_DOCS_OM_URL;#image-generation-dev-environment>`__" +:ref:`image-generation-dev-environment`" section in the Yocto Project Overview and Concepts Manual. .. _ref-classes-sanity: @@ -2339,9 +2400,9 @@ The ``sstate`` class provides support for Shared State (sstate). By default, the class is enabled through the :term:`INHERIT_DISTRO` variable's default value. -For more information on sstate, see the "`Shared State -Cache <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__" section in the Yocto -Project Overview and Concepts Manual. +For more information on sstate, see the +":ref:`overview-manual/overview-manual-concepts:shared state cache`" +section in the Yocto Project Overview and Concepts Manual. .. _ref-classes-staging: @@ -2510,14 +2571,17 @@ You should set :term:`SYSTEMD_SERVICE` to the name of the service file. You should also use a package name override to indicate the package to which the value applies. If the value applies to the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here -is an example from the connman recipe: SYSTEMD_SERVICE_${PN} = -"connman.service" Services are set up to start on boot automatically +is an example from the connman recipe: +:: + + SYSTEMD_SERVICE_${PN} = "connman.service" + +Services are set up to start on boot automatically unless you have set :term:`SYSTEMD_AUTO_ENABLE` to "disable". -For more information on ``systemd``, see the "`Selecting an -Initialization -Manager <&YOCTO_DOCS_DEV_URL;#selecting-an-initialization-manager>`__" +For more information on ``systemd``, see the +":ref:`dev-manual/dev-manual-common-tasks:selecting an initialization manager`" section in the Yocto Project Development Tasks Manual. .. _ref-classes-systemd-boot: @@ -2593,13 +2657,17 @@ The tests are commands that run on the target system over ``ssh``. Each test is written in Python and makes use of the ``unittest`` module. The ``testimage.bbclass`` runs tests on an image when called using the -following: $ bitbake -c testimage image The ``testimage-auto`` class +following: +:: + + $ bitbake -c testimage image + +The ``testimage-auto`` class runs tests on an image after the image is constructed (i.e. :term:`TESTIMAGE_AUTO` must be set to "1"). For information on how to enable, run, and create new tests, see the -"`Performing Automated Runtime -Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__" +":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" section in the Yocto Project Development Tasks Manual. .. _ref-classes-testsdk: @@ -2609,7 +2677,10 @@ section in the Yocto Project Development Tasks Manual. This class supports running automated tests against software development kits (SDKs). The ``testsdk`` class runs tests on an SDK when called -using the following: $ bitbake -c testsdk image +using the following: +:: + + $ bitbake -c testsdk image .. note:: @@ -2682,7 +2753,9 @@ The ``typecheck`` class provides support for validating the values of variables set at the configuration level against their defined types. The OpenEmbedded build system allows you to define the type of a variable using the "type" varflag. Here is an example: -IMAGE_FEATURES[type] = "list" +:: + + IMAGE_FEATURES[type] = "list" .. _ref-classes-uboot-config: @@ -2690,11 +2763,18 @@ IMAGE_FEATURES[type] = "list" ======================== The ``uboot-config`` class provides support for U-Boot configuration for -a machine. Specify the machine in your recipe as follows: UBOOT_CONFIG -??= UBOOT_CONFIG[foo] = "config,images" You can also specify -the machine using this method: UBOOT_MACHINE = "config" See the -:term:`UBOOT_CONFIG` and -:term:`UBOOT_MACHINE` variables for additional +a machine. Specify the machine in your recipe as follows: +:: + + UBOOT_CONFIG ??= + UBOOT_CONFIG[foo] = "config,images" + +You can also specify the machine using this method: +:: + + UBOOT_MACHINE = "config" + +See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional information. .. _ref-classes-uninative: -- cgit v1.2.3-54-g00ecf