diff options
| author | Patrick Williams <patrick@stwcx.xyz> | 2022-10-16 22:26:09 +0300 |
|---|---|---|
| committer | Patrick Williams <patrick@stwcx.xyz> | 2022-10-16 22:27:46 +0300 |
| commit | 2194f503e17619bcd36b4289902d13457aac638e (patch) | |
| tree | cafb71f7044ec9752543d5696295a7584927d249 /poky | |
| parent | bdfb8a9cebc292bab790500a6439e4d83ec57bdf (diff) | |
| download | openbmc-2194f503e17619bcd36b4289902d13457aac638e.tar.xz | |
subtree updates
meta-arm: 0164b4ca7a..13199c55c0:
Adam Johnston (1):
arm-bsp/linux-yocto: Upgrade kernel to v5.19 for N1SDP
Anton Antonov (4):
meta-arm/trusted-services: Use GCC toolchain for specific TS recipes only.
arm/trusted-services: Remove patches merged upstream
arm/trusted-services: Remove remaining patches merged upstream
arm/trusted-services: include documentation
Davidson K (1):
arm-bsp/linux-arm64-ack: make it compatible with gcc-12 for TC
Emekcan (2):
arm-bsp/linux-yocto: update RPMSG_CTRL config for corstone1000
arm-bsp/kernel: Fix TEE driver bug for corstone1000
Jon Mason (3):
CI: trusted services as a feature instead of a machine
CI: cleanups for targets and removed tests
arm-bsp: zephyr removal
Peter Hoyes (1):
arm/lib: Do not log FVP return codes < 0
Ross Burton (2):
arm/optee-spdevkit: remove
CI: restrict compression threading
Rui Miguel Silva (1):
arm-bsp/corstone1000: bump kernel version to 5.19
Rupinderjit Singh (1):
arm: update Android common kernel
Satish Kumar (4):
arm-bsp/u-boot: corstone1000: esrt support
arm-bsp/trusted-firmware-m: corstone1000: bump tfm SHA
arm-bsp/trusted-firmware-m: corstone1000: fix sournce dir of libmetal and openamp
arm-bsp/trusted-firmware-m: corstone1000: secure debug code checkout from yocto
Sumit Garg (2):
arm-toolchain: update Arm GCC to 11.3
external-arm-toolchain: Enable 11.3.rel1 support
Vishnu Banavath (1):
arm-bsp/corstone500: upgrade kernel to v5.19
meta-raspberrypi: 45d56d82b7..fc5f80a47e:
Devendra Tewari (3):
rpi-cmdline: Leave cma value to kernel default
libcamera: Tweak to build for Raspberry Pi
rpi-libcamera-apps: add new recipe
Martin Jansa (1):
lirc: rename bbappend to match 0.10.%
Zygmunt Krynicki (2):
ci: fix typo: unconditionally
ci: fix apparent typo in file patterns
meta-openembedded: ce0b93fc12..6529e5f963:
Alexander Kanavin (3):
python3-cchardet: depend on cython
python3-gevent: make compatible with python 3.11
python3-pybluez: add python 3.11 patch
Anuj Mittal (1):
opencv: fix reproducibility issues
Devendra Tewari (2):
libcamera: Bump SRCREV and add libyaml to DEPENDS
libcamera: Remove boost from DEPENDS
Fabio Estevam (1):
spice: Include aarch64 to COMPATIBLE_HOST
Federico Pellegrin (2):
chrony: add pkgconfig class as pkg-config is explicitly searched for
chrony: correct parameter to configure to disable readline usage
Hao Jiang (1):
mctp: install the .target files
Jiaqing Zhao (1):
openldap: Upgrade 2.5.12 -> 2.5.13
Khem Raj (2):
open62541: Disable lto on riscv/clang
python3-gevent: Upgrade to 22.8.0
Leon Anavi (10):
python3-networkx: Upgrade 2.8.6 -> 2.8.7
python3-coverage: Upgrade 6.4.4 -> 6.5.0
python3-rdflib: Upgrade 6.1.1 -> 6.2.0
python3-tabulate: Upgrade 0.8.10 -> 0.9.0
python3-imageio: Upgrade 2.22.0 -> 2.22.1
python3-astroid: Upgrade 2.12.10 -> 2.12.11
python3-jsonref: Upgrade 0.2 -> 0.3.0
python3-sentry-sdk: Upgrade 1.5.12 -> 1.9.10
python3-greenlet: Upgrade 1.1.3 -> 1.1.3.post0
python3-xmltodict: Upgrade 0.12.0 -> 0.13.0
Markus Volk (2):
blueman: upgrade 2.2.4 -> 2.3.2
gtkmm3: upgrade 3.24.5 -> 3.24.7
Martin Jansa (2):
re2: fix branch name from master to main
jack: fix compatibility with python-3.11
Mathieu Dubois-Briand (3):
mbedtls: Fix CVE product name
mbedtls: Update to 2.28.1 version
mbedtls: Whitelist CVE-2021-43666, CVE-2021-45451
Matthias Klein (1):
paho-mqtt-c: upgrade 1.3.10 -> 1.3.11
Michael Opdenacker (1):
tio: correct license information
Mingli Yu (1):
mariadb: not use qemu to run cross-compiled binaries
S. Lockwood-Childs (1):
x265: support aarch64
Thomas Perrot (1):
spitools: remove unused BPV variable
Vyacheslav Yurkov (1):
opcua: Add new recipe
Wang Mingyu (20):
ctags: upgrade 5.9.20220925.0 -> 5.9.20221002.0
dnfdragora: upgrade 2.1.2 -> 2.1.3
dool: upgrade 1.0.0 -> 1.1.0
freeglut: upgrade 3.2.1 -> 3.4.0
gspell: upgrade 1.11.1 -> 1.12.0
hwdata: upgrade 0.362 -> 0.363
iperf3: upgrade 3.11 -> 3.12
libnet-dns-perl: upgrade 1.34 -> 1.35
lirc: upgrade 0.10.1 -> 0.10.2
metacity: upgrade 3.44.0 -> 3.46.0
flatbuffers: upgrade 2.0.8 -> 22.9.29
opencl-headers: upgrade 2022.09.23 -> 2022.09.30
php: upgrade 8.1.10 -> 8.1.11
poppler: upgrade 22.09.0 -> 22.10.0
xfstests: upgrade 2022.09.04 -> 2022.09.25
links: upgrade 2.27 -> 2.28
st: upgrade 0.8.5 -> 0.9
python3-requests-toolbelt: upgrade 0.9.1 -> 0.10.0
Add nativesdk-systemd-systemctl as dependency of dnf-plugin-tui
dnf-plugin-tui: Add nativesdk
Yi Zhao (4):
strongswan: upgrade 5.9.7 -> 5.9.8
open-vm-tools: upgrade 11.3.5 -> 12.1.0
dhcp-relay: upgrade 4.4.3 -> 4.4.3-P1
frr: Security fix CVE-2022-37032
zhengrq.fnst (5):
python3-protobuf: upgrade 4.21.6 -> 4.21.7
stunnel: upgrade 5.65 -> 5.66
python3-web3: upgrade 5.31.0 -> 5.31.1
wolfssl: upgrade 5.5.0 -> 5.5.1
python3-xmlschema: upgrade 2.1.0 -> 2.1.1
meta-security: 824d2762f6..e8e7318189:
Armin Kuster (3):
apparmor: update to 3.0.7
libgssglue: update to 0.7
cryptmount: update to 6.0
Michael Haener (1):
tpm: update the linux-yocto rule with the one from sanity-meta-tpm class
poky: 5200799866..3e5faccfaf:
Johan Korsnes (1):
migration guides: 3.4: remove spurious space in example
Lee Chee Yang (1):
migration guides: add release notes for 4.0.4
Michael Opdenacker (35):
manuals: improve initramfs details
manuals: add references to the "do_fetch" task
manuals: add reference to the "do_install" task
manuals: add references to the "do_build" task
manuals: add reference to "do_configure" task
manuals: add reference to the "do_compile" task
manuals: add references to the "do_deploy" task
manuals: add references to the "do_image" task
manuals: add references to the "do_package" task
manuals: add references to the "do_package_qa" task
overview-manual: concepts.rst: add reference to "do_packagedata" task
manuals: add references to the "do_patch" task
manuals: add references to "do_package_write_*" tasks
ref-manual: variables.rst: add reference to "do_populate_lic" task
manuals: add reference to the "do_populate_sdk" task
overview-manual: concepts.rst: add reference to "do_populate_sdk_ext" task
manuals: add references to "do_populate_sysroot" task
manuals: add references to the "do_unpack" task
dev-manual: common-tasks.rst: add reference to "do_clean" task
manuals: add references to the "do_cleanall" task
ref-manual: tasks.rst: add references to the "do_cleansstate" task
manuals: add references to the "do_devshell" task
dev-manual: common-tasks.rst: add reference to "do_listtasks" task
manuals: add references to the "do_bundle_initramfs" task
manuals: add references to the "do_rootfs" task
ref-manual: tasks.rst: add reference to the "do_kernel_checkout" task
manuals: add reference to the "do_kernel_configcheck" task
manuals: add references to the "do_kernel_configme" task
ref-manual: tasks.rst: add reference to the "do_kernel_metadata" task
migration-guides: add reference to the "do_shared_workdir" task
ref-manual: tasks.rst: add reference to the "do_validate_branches" task
ref-manual: tasks.rst: add reference to the "do_image_complete" task
ref-manual: system-requirements: Ubuntu 22.04 now supported
overview-manual: concepts.rst: fix formating and add references
ref-manual/faq.rst: update references to products built with OE / Yocto Project
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
Change-Id: I14d679e25bd1c7545bc2d0f545f876aeb0a333b4
Diffstat (limited to 'poky')
28 files changed, 602 insertions, 307 deletions
diff --git a/poky/documentation/dev-manual/common-tasks.rst b/poky/documentation/dev-manual/common-tasks.rst index 559709d6f3..a4741c5a8b 100644 --- a/poky/documentation/dev-manual/common-tasks.rst +++ b/poky/documentation/dev-manual/common-tasks.rst @@ -1731,7 +1731,7 @@ your software is built: If you need to install one or more custom CMake toolchain files that are supplied by the application you are building, install the - files to ``${D}${datadir}/cmake/Modules`` during ``do_install``. + files to ``${D}${datadir}/cmake/Modules`` during :ref:`ref-tasks-install`. - *Other:* If your source files do not have a ``configure.ac`` or ``CMakeLists.txt`` file, then your software is built using some @@ -1826,8 +1826,8 @@ out-of-tree modules. Your recipe will also need the following:: Compilation ----------- -During a build, the ``do_compile`` task happens after source is fetched, -unpacked, and configured. If the recipe passes through ``do_compile`` +During a build, the :ref:`ref-tasks-compile` task happens after source is fetched, +unpacked, and configured. If the recipe passes through :ref:`ref-tasks-compile` successfully, nothing needs to be done. However, if the compile step fails, you need to diagnose the failure. @@ -1888,7 +1888,7 @@ Here are some common issues that cause failures. Installing ---------- -During ``do_install``, the task copies the built files along with their +During :ref:`ref-tasks-install`, the task copies the built files along with their hierarchy to locations that would mirror their locations on the target device. The installation process copies files from the ``${``\ :term:`S`\ ``}``, @@ -1906,14 +1906,14 @@ the software being built: - *Autotools and CMake:* If the software your recipe is building uses Autotools or CMake, the OpenEmbedded build system understands how to install the software. Consequently, you do not have to have a - ``do_install`` task as part of your recipe. You just need to make + :ref:`ref-tasks-install` task as part of your recipe. You just need to make sure the install portion of the build completes with no issues. However, if you wish to install additional files not already being installed by ``make install``, you should do this using a ``do_install:append`` function using the install command as described in the "Manual" bulleted item later in this list. -- *Other (using* ``make install``\ *)*: You need to define a ``do_install`` +- *Other (using* ``make install``\ *)*: You need to define a :ref:`ref-tasks-install` function in your recipe. The function should call ``oe_runmake install`` and will likely need to pass in the destination directory as well. How you pass that path is dependent on @@ -1923,7 +1923,7 @@ the software being built: For an example recipe using ``make install``, see the ":ref:`dev-manual/common-tasks:makefile-based package`" section. -- *Manual:* You need to define a ``do_install`` function in your +- *Manual:* You need to define a :ref:`ref-tasks-install` function in your recipe. The function must first use ``install -d`` to create the directories under ``${``\ :term:`D`\ ``}``. Once the @@ -1946,10 +1946,10 @@ installed correctly. might need to replace hard-coded paths in an initscript with values of variables provided by the build system, such as replacing ``/usr/bin/`` with ``${bindir}``. If you do perform such - modifications during ``do_install``, be sure to modify the + modifications during :ref:`ref-tasks-install`, be sure to modify the destination file after copying rather than before copying. Modifying after copying ensures that the build system can - re-execute ``do_install`` if needed. + re-execute :ref:`ref-tasks-install` if needed. - ``oe_runmake install``, which can be run directly or can be run indirectly by the @@ -1958,7 +1958,7 @@ installed correctly. runs ``make install`` in parallel. Sometimes, a Makefile can have missing dependencies between targets that can result in race conditions. If you experience intermittent failures during - ``do_install``, you might be able to work around them by disabling + :ref:`ref-tasks-install`, you might be able to work around them by disabling parallel Makefile installs by adding the following to the recipe:: PARALLEL_MAKEINST = "" @@ -1980,7 +1980,7 @@ additional definitions in your recipe. If you are adding services and the service initialization script or the service file itself is not installed, you must provide for that installation in your recipe using a ``do_install:append`` function. If -your recipe already has a ``do_install`` function, update the function +your recipe already has a :ref:`ref-tasks-install` function, update the function near its end rather than adding an additional ``do_install:append`` function. @@ -2028,10 +2028,10 @@ Successful packaging is a combination of automated processes performed by the OpenEmbedded build system and some specific steps you need to take. The following list describes the process: -- *Splitting Files*: The ``do_package`` task splits the files produced +- *Splitting Files*: The :ref:`ref-tasks-package` task splits the files produced by the recipe into logical components. Even software that produces a single binary might still have debug symbols, documentation, and - other logical components that should be split out. The ``do_package`` + other logical components that should be split out. The :ref:`ref-tasks-package` task ensures that files are split up and packaged correctly. - *Running QA Checks*: The @@ -2337,7 +2337,7 @@ Single .c File Package (Hello World!) Building an application from a single file that is stored locally (e.g. under ``files``) requires a recipe that has the file listed in the :term:`SRC_URI` variable. Additionally, you need to manually write the -``do_compile`` and ``do_install`` tasks. The :term:`S` variable defines the +:ref:`ref-tasks-compile` and :ref:`ref-tasks-install` tasks. The :term:`S` variable defines the directory containing the source code, which is set to :term:`WORKDIR` in this case --- the directory BitBake uses for the build. @@ -2401,14 +2401,14 @@ Makefile-Based Package Applications that use GNU ``make`` also require a recipe that has the source archive listed in :term:`SRC_URI`. You do not need to add a -``do_compile`` step since by default BitBake starts the ``make`` command +:ref:`ref-tasks-compile` step since by default BitBake starts the ``make`` command to compile the application. If you need additional ``make`` options, you should store them in the :term:`EXTRA_OEMAKE` or :term:`PACKAGECONFIG_CONFARGS` variables. BitBake passes these options into the GNU ``make`` -invocation. Note that a ``do_install`` task is still required. -Otherwise, BitBake runs an empty ``do_install`` task by default. +invocation. Note that a :ref:`ref-tasks-install` task is still required. +Otherwise, BitBake runs an empty :ref:`ref-tasks-install` task by default. Some applications might require extra parameters to be passed to the compiler. For example, the application might need an additional header @@ -2551,7 +2551,7 @@ doing the following: ``${``\ :term:`S`\ ``}``. If ``${S}`` might contain a Makefile, or if you inherit some class - that replaces ``do_configure`` and ``do_compile`` with custom + that replaces :ref:`ref-tasks-configure` and :ref:`ref-tasks-compile` with custom versions, then you can use the ``[``\ :ref:`noexec <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` flag to turn the tasks into no-ops, as follows:: @@ -2567,7 +2567,7 @@ doing the following: :ref:`ref-tasks-patch` tasks to the :ref:`ref-tasks-install` task. -- Make sure your ``do_install`` task installs the binaries +- Make sure your :ref:`ref-tasks-install` task installs the binaries appropriately. - Ensure that you set up :term:`FILES` @@ -2881,7 +2881,7 @@ you can use as references. If you are creating a new kernel recipe, normal recipe-writing rules apply for setting up a :term:`SRC_URI`. Thus, you need to specify any necessary patches and set :term:`S` to point at the source code. You need to -create a ``do_configure`` task that configures the unpacked kernel with +create a :ref:`ref-tasks-configure` task that configures the unpacked kernel with a ``defconfig`` file. You can do this by using a ``make defconfig`` command or, more commonly, by copying in a suitable ``defconfig`` file and then running ``make oldconfig``. By making use of ``inherit kernel`` @@ -3446,7 +3446,7 @@ Follow these general steps: you added to the patch. 6. *Test Your Changes:* Once you have modified the source code, the - easiest way to test your changes is by calling the ``do_compile`` + easiest way to test your changes is by calling the :ref:`ref-tasks-compile` task as shown in the following example:: $ bitbake -c compile -f package @@ -3458,7 +3458,7 @@ Follow these general steps: .. note:: All the modifications you make to the temporary source code disappear - once you run the ``do_clean`` or ``do_cleanall`` tasks using BitBake + once you run the :ref:`ref-tasks-clean` or :ref:`ref-tasks-cleanall` tasks using BitBake (i.e. ``bitbake -c clean package`` and ``bitbake -c cleanall package``). Modifications will also disappear if you use the ``rm_work`` feature as described in the @@ -3853,8 +3853,8 @@ to be added to the recipe that builds the ``core-image-sato`` image:: do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_rootfs" In this example, the `from_multiconfig` is "x86". The `to_multiconfig` is "arm". The -task on which the ``do_image`` task in the recipe depends is the -``do_rootfs`` task from the ``core-image-minimal`` recipe associated +task on which the :ref:`ref-tasks-image` task in the recipe depends is the +:ref:`ref-tasks-rootfs` task from the ``core-image-minimal`` recipe associated with the "arm" multiconfig. Once you set up this dependency, you can build the "x86" multiconfig @@ -3864,7 +3864,7 @@ using a BitBake command as follows:: This command executes all the tasks needed to create the ``core-image-sato`` image for the "x86" multiconfig. Because of the -dependency, BitBake also executes through the ``do_rootfs`` task for the +dependency, BitBake also executes through the :ref:`ref-tasks-rootfs` task for the "arm" multiconfig build. Having a recipe depend on the root filesystem of another build might not @@ -3882,99 +3882,59 @@ and have separate configuration files, BitBake places the artifacts for each build in the respective temporary build directories (i.e. :term:`TMPDIR`). -Building an Initial RAM Filesystem (initramfs) Image +Building an Initial RAM Filesystem (Initramfs) Image ---------------------------------------------------- -An initial RAM filesystem (initramfs) image provides a temporary root -filesystem used for early system initialization (e.g. loading of modules -needed to locate and mount the "real" root filesystem). +An initial RAM filesystem (:term:`Initramfs`) image provides a temporary root +filesystem used for early system initialization, typically providing tools and +loading modules needed to locate and mount the final root filesystem. -.. note:: - - The initramfs image is the successor of initial RAM disk (initrd). It - is a "copy in and out" (cpio) archive of the initial filesystem that - gets loaded into memory during the Linux startup process. Because - Linux uses the contents of the archive during initialization, the - initramfs image needs to contain all of the device drivers and tools - needed to mount the final root filesystem. - -Follow these steps to create an initramfs image: +Follow these steps to create an :term:`Initramfs` image: -1. *Create the initramfs Image Recipe:* You can reference the +1. *Create the Initramfs Image Recipe:* You can reference the ``core-image-minimal-initramfs.bb`` recipe found in the ``meta/recipes-core`` directory of the :term:`Source Directory` - as an example - from which to work. - -2. *Decide if You Need to Bundle the initramfs Image Into the Kernel - Image:* If you want the initramfs image that is built to be bundled - in with the kernel image, set the - :term:`INITRAMFS_IMAGE_BUNDLE` - variable to "1" in your ``local.conf`` configuration file and set the - :term:`INITRAMFS_IMAGE` - variable in the recipe that builds the kernel image. - - .. note:: + as an example from which to work. - It is recommended that you bundle the initramfs image with the - kernel image to avoid circular dependencies between the kernel - recipe and the initramfs recipe should the initramfs image include - kernel modules. +2. *Decide if You Need to Bundle the Initramfs Image Into the Kernel + Image:* If you want the :term:`Initramfs` image that is built to be bundled + in with the kernel image, set the :term:`INITRAMFS_IMAGE_BUNDLE` + variable to ``"1"`` in your ``local.conf`` configuration file and set the + :term:`INITRAMFS_IMAGE` variable in the recipe that builds the kernel image. - Setting the :term:`INITRAMFS_IMAGE_BUNDLE` flag causes the initramfs + Setting the :term:`INITRAMFS_IMAGE_BUNDLE` flag causes the :term:`Initramfs` image to be unpacked into the ``${B}/usr/`` directory. The unpacked - initramfs image is then passed to the kernel's ``Makefile`` using the - :term:`CONFIG_INITRAMFS_SOURCE` - variable, allowing the initramfs image to be built into the kernel - normally. - - .. note:: - - Bundling the initramfs with the kernel conflates the code in the initramfs - with the GPLv2 licensed Linux kernel binary. Thus only GPLv2 compatible - software may be part of a bundled initramfs. - - .. note:: - - If you choose to not bundle the initramfs image with the kernel - image, you are essentially using an - `Initial RAM Disk (initrd) <https://en.wikipedia.org/wiki/Initrd>`__. - Creating an initrd is handled primarily through the :term:`INITRD_IMAGE`, - ``INITRD_LIVE``, and ``INITRD_IMAGE_LIVE`` variables. For more - information, see the :ref:`ref-classes-image-live` file. - -3. *Optionally Add Items to the initramfs Image Through the initramfs - Image Recipe:* If you add items to the initramfs image by way of its - recipe, you should use - :term:`PACKAGE_INSTALL` - rather than - :term:`IMAGE_INSTALL`. - :term:`PACKAGE_INSTALL` gives more direct control of what is added to the - image as compared to the defaults you might not necessarily want that - are set by the :ref:`image <ref-classes-image>` - or :ref:`core-image <ref-classes-core-image>` - classes. - -4. *Build the Kernel Image and the initramfs Image:* Build your kernel - image using BitBake. Because the initramfs image recipe is a - dependency of the kernel image, the initramfs image is built as well + :term:`Initramfs` image is then passed to the kernel's ``Makefile`` using the + :term:`CONFIG_INITRAMFS_SOURCE` variable, allowing the :term:`Initramfs` + image to be built into the kernel normally. + +3. *Optionally Add Items to the Initramfs Image Through the Initramfs + Image Recipe:* If you add items to the :term:`Initramfs` image by way of its + recipe, you should use :term:`PACKAGE_INSTALL` rather than + :term:`IMAGE_INSTALL`. :term:`PACKAGE_INSTALL` gives more direct control of + what is added to the image as compared to the defaults you might not + necessarily want that are set by the :ref:`image <ref-classes-image>` + or :ref:`core-image <ref-classes-core-image>` classes. + +4. *Build the Kernel Image and the Initramfs Image:* Build your kernel + image using BitBake. Because the :term:`Initramfs` image recipe is a + dependency of the kernel image, the :term:`Initramfs` image is built as well and bundled with the kernel image if you used the - :term:`INITRAMFS_IMAGE_BUNDLE` - variable described earlier. + :term:`INITRAMFS_IMAGE_BUNDLE` variable described earlier. Bundling an Initramfs Image From a Separate Multiconfig ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There may be a case where we want to build an initramfs image which does not +There may be a case where we want to build an :term:`Initramfs` image which does not inherit the same distro policy as our main image, for example, we may want -our main image to use ``TCLIBC="glibc"``, but to use ``TCLIBC="musl"`` in our initramfs +our main image to use ``TCLIBC="glibc"``, but to use ``TCLIBC="musl"`` in our :term:`Initramfs` image to keep a smaller footprint. However, by performing the steps mentioned -above the initramfs image will inherit ``TCLIBC="glibc"`` without allowing us +above the :term:`Initramfs` image will inherit ``TCLIBC="glibc"`` without allowing us to override it. To achieve this, you need to perform some additional steps: -1. *Create a multiconfig for your initramfs image:* You can perform the steps +1. *Create a multiconfig for your Initramfs image:* You can perform the steps on ":ref:`dev-manual/common-tasks:building images for multiple targets using multiple configurations`" to create a separate multiconfig. For the sake of simplicity let's assume such multiconfig is called: ``initramfscfg.conf`` and contains the variables:: @@ -3982,7 +3942,7 @@ To achieve this, you need to perform some additional steps: TMPDIR="${TOPDIR}/tmp-initramfscfg" TCLIBC="musl" -2. *Set additional initramfs variables on your main configuration:* +2. *Set additional Initramfs variables on your main configuration:* Additionally, on your main configuration (``local.conf``) you need to set the variables:: @@ -3995,9 +3955,9 @@ To achieve this, you need to perform some additional steps: buildsystem know where the :term:`INITRAMFS_IMAGE` will be located. Building a system with such configuration will build the kernel using the - main configuration but the ``do_bundle_initramfs`` task will grab the + main configuration but the :ref:`ref-tasks-bundle_initramfs` task will grab the selected :term:`INITRAMFS_IMAGE` from :term:`INITRAMFS_DEPLOY_DIR_IMAGE` - instead, resulting in a musl based initramfs image bundled in the kernel + instead, resulting in a musl based :term:`Initramfs` image bundled in the kernel but a glibc based main image. The same is applicable to avoid inheriting :term:`DISTRO_FEATURES` on :term:`INITRAMFS_IMAGE` @@ -4171,7 +4131,7 @@ file:: Finally, you should consider exactly the type of root filesystem you need to meet your needs while also reducing its size. For example, consider ``cramfs``, ``squashfs``, ``ubifs``, ``ext2``, or an -``initramfs`` using ``initramfs``. Be aware that ``ext3`` requires a 1 +:term:`Initramfs` using ``initramfs``. Be aware that ``ext3`` requires a 1 Mbyte journal. If you are okay with running read-only, you do not need this journal. @@ -4740,7 +4700,7 @@ the built library. The :term:`PACKAGES` and :term:`FILES:* <FILES>` variables in the ``meta/conf/bitbake.conf`` configuration file define how files installed -by the ``do_install`` task are packaged. By default, the :term:`PACKAGES` +by the :ref:`ref-tasks-install` task are packaged. By default, the :term:`PACKAGES` variable includes ``${PN}-staticdev``, which represents all static library files. @@ -6902,7 +6862,7 @@ The previous example specifies a number of things in the call to ``do_split_packages``. - A directory within the files installed by your recipe through - ``do_install`` in which to search. + :ref:`ref-tasks-install` in which to search. - A regular expression used to match module files in that directory. In the example, note the parentheses () that mark the part of the @@ -8481,7 +8441,7 @@ The following list shows the files produced for SDKs: information. - ``sstate-task-sizes.txt:`` A text file containing name-value pairs - with information about task group sizes (e.g. ``do_populate_sysroot`` + with information about task group sizes (e.g. :ref:`ref-tasks-populate_sysroot` tasks have a total size). The ``sstate-task-sizes.txt`` file exists only when an extensible SDK is created. @@ -8802,7 +8762,7 @@ perform a one-time setup of your controller image by doing the following: - Installs normal linux utilities not BusyBox ones (e.g. ``bash``, ``coreutils``, ``tar``, ``gzip``, and ``kmod``). - - Uses a custom Initial RAM Disk (initramfs) image with a custom + - Uses a custom :term:`Initramfs` image with a custom installer. A normal image that you can install usually creates a single root filesystem partition. This image uses another installer that creates a specific partition layout. Not all Board Support @@ -9081,7 +9041,7 @@ Class methods are as follows: - *hasPackage(pkg):* Returns "True" if ``pkg`` is in the installed package list of the image, which is based on the manifest file that - is generated during the ``do_rootfs`` task. + is generated during the :ref:`ref-tasks-rootfs` task. - *hasFeature(feature):* Returns "True" if the feature is in :term:`IMAGE_FEATURES` or @@ -9633,11 +9593,11 @@ Running Specific Tasks ---------------------- Any given recipe consists of a set of tasks. The standard BitBake -behavior in most cases is: ``do_fetch``, ``do_unpack``, ``do_patch``, -``do_configure``, ``do_compile``, ``do_install``, ``do_package``, -``do_package_write_*``, and ``do_build``. The default task is -``do_build`` and any tasks on which it depends build first. Some tasks, -such as ``do_devshell``, are not part of the default build chain. If you +behavior in most cases is: :ref:`ref-tasks-fetch`, :ref:`ref-tasks-unpack`, :ref:`ref-tasks-patch`, +:ref:`ref-tasks-configure`, :ref:`ref-tasks-compile`, :ref:`ref-tasks-install`, :ref:`ref-tasks-package`, +:ref:`do_package_write_* <ref-tasks-package_write_deb>`, and :ref:`ref-tasks-build`. The default task is +:ref:`ref-tasks-build` and any tasks on which it depends build first. Some tasks, +such as :ref:`ref-tasks-devshell`, are not part of the default build chain. If you wish to run a task that is not part of the default build chain, you can use the ``-c`` option in BitBake. Here is an example:: @@ -9677,7 +9637,7 @@ The following example shows one way you can use the ``-f`` option:: This sequence first builds and then recompiles ``matchbox-desktop``. The last command reruns all tasks (basically the packaging tasks) after the -compile. BitBake recognizes that the ``do_compile`` task was rerun and +compile. BitBake recognizes that the :ref:`ref-tasks-compile` task was rerun and therefore understands that the other tasks also need to be run again. Another, shorter way to rerun a task and all @@ -9724,7 +9684,7 @@ task dependency mechanisms. You can view a list of tasks in a given package by running the -``do_listtasks`` task as follows:: +:ref:`ref-tasks-listtasks` task as follows:: $ bitbake matchbox-desktop -c listtasks diff --git a/poky/documentation/dev-manual/qemu.rst b/poky/documentation/dev-manual/qemu.rst index 88a63c1808..9f4bc264a3 100644 --- a/poky/documentation/dev-manual/qemu.rst +++ b/poky/documentation/dev-manual/qemu.rst @@ -123,9 +123,9 @@ available. Follow these general steps to run QEMU: $ runqemu qemux86-64 core-image-minimal ext4 - - This example specifies to boot an initial RAM disk image and to - enable audio in QEMU. For this case, ``runqemu`` set the internal - variable ``FSTYPE`` to "cpio.gz". Also, for audio to be enabled, + - This example specifies to boot an :term:`Initramfs` image and to + enable audio in QEMU. For this case, ``runqemu`` sets the internal + variable ``FSTYPE`` to ``cpio.gz``. Also, for audio to be enabled, an appropriate driver must be installed (see the previous description for the ``audio`` option for more information). :: @@ -394,7 +394,7 @@ command line: options are basically identical. If you do not provide a MACHINE option, ``runqemu`` tries to determine it based on other options. -- ``ramfs``: Indicates you are booting an initial RAM disk (initramfs) +- ``ramfs``: Indicates you are booting an :term:`Initramfs` image, which means the ``FSTYPE`` is ``cpio.gz``. - ``iso``: Indicates you are booting an ISO image, which means the diff --git a/poky/documentation/kernel-dev/common.rst b/poky/documentation/kernel-dev/common.rst index fb8d7cd029..0a1819ceae 100644 --- a/poky/documentation/kernel-dev/common.rst +++ b/poky/documentation/kernel-dev/common.rst @@ -1316,7 +1316,7 @@ In order to run this task, you must have an existing ``.config`` file. See the ":ref:`kernel-dev/common:using \`\`menuconfig\`\``" section for information on how to create a configuration file. -Following is sample output from the ``do_kernel_configcheck`` task: +Following is sample output from the :ref:`ref-tasks-kernel_configcheck` task: .. code-block:: none @@ -1396,7 +1396,7 @@ possible by reading the output of the kernel configuration fragment audit, noting any issues, making changes to correct the issues, and then repeating. -As part of the kernel build process, the ``do_kernel_configcheck`` task +As part of the kernel build process, the :ref:`ref-tasks-kernel_configcheck` task runs. This task validates the kernel configuration by checking the final ``.config`` file against the input files. During the check, the task produces warning messages for the following issues: @@ -1430,13 +1430,13 @@ To streamline the configuration, do the following: successfully. Use this configuration file as your baseline. 2. *Run Configure and Check Tasks:* Separately run the - ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks:: + :ref:`ref-tasks-kernel_configme` and :ref:`ref-tasks-kernel_configcheck` tasks:: $ bitbake linux-yocto -c kernel_configme -f $ bitbake linux-yocto -c kernel_configcheck -f 3. *Process the Results:* Take the resulting list of files from the - ``do_kernel_configcheck`` task warnings and do the following: + :ref:`ref-tasks-kernel_configcheck` task warnings and do the following: - Drop values that are redefined in the fragment but do not change the final ``.config`` file. @@ -1450,7 +1450,7 @@ To streamline the configuration, do the following: 4. *Re-Run Configure and Check Tasks:* After you have worked through the output of the kernel configuration audit, you can re-run the - ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks to see the + :ref:`ref-tasks-kernel_configme` and :ref:`ref-tasks-kernel_configcheck` tasks to see the results of your changes. If you have more issues, you can deal with them as described in the previous step. diff --git a/poky/documentation/migration-guides/migration-1.3.rst b/poky/documentation/migration-guides/migration-1.3.rst index 6a1755d1dc..3ba189b773 100644 --- a/poky/documentation/migration-guides/migration-1.3.rst +++ b/poky/documentation/migration-guides/migration-1.3.rst @@ -62,7 +62,7 @@ Previously, an inconsistent mix of spaces and tabs existed, which made extending these functions using ``_append`` or ``_prepend`` complicated given that Python treats whitespace as syntactically significant. If you are defining or extending any Python functions (e.g. -``populate_packages``, ``do_unpack``, ``do_patch`` and so forth) in +``populate_packages``, :ref:`ref-tasks-unpack`, :ref:`ref-tasks-patch` and so forth) in custom recipes or classes, you need to ensure you are using consistent four-space indentation. diff --git a/poky/documentation/migration-guides/migration-1.7.rst b/poky/documentation/migration-guides/migration-1.7.rst index 8213ab58d9..7b179f2aa1 100644 --- a/poky/documentation/migration-guides/migration-1.7.rst +++ b/poky/documentation/migration-guides/migration-1.7.rst @@ -165,7 +165,7 @@ The following changes have occurred to the QA check process: more parallel execution. This change is unlikely to be an issue except for highly customized recipes that disable packaging tasks themselves by marking them as ``noexec``. For those packages, you - will need to disable the ``do_package_qa`` task as well. + will need to disable the :ref:`ref-tasks-package_qa` task as well. - Files being overwritten during the :ref:`ref-tasks-populate_sysroot` task now diff --git a/poky/documentation/migration-guides/migration-1.8.rst b/poky/documentation/migration-guides/migration-1.8.rst index 51a13873e2..f058029b30 100644 --- a/poky/documentation/migration-guides/migration-1.8.rst +++ b/poky/documentation/migration-guides/migration-1.8.rst @@ -84,7 +84,7 @@ 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 -``do_shared_workdir`` kernel task, for example:: +:ref:`ref-tasks-shared_workdir` kernel task, for example:: do_configure[depends] += "virtual/kernel:do_shared_workdir" @@ -128,7 +128,7 @@ when the :ref:`ref-tasks-configure` task needs to be re-executed. One of the improvements is to attempt to run "make clean" during the -``do_configure`` task if a ``Makefile`` exists. Some software packages +:ref:`ref-tasks-configure` task if a ``Makefile`` exists. Some software packages do not provide a working clean target within their make files. If you have such recipes, you need to set :term:`CLEANBROKEN` to "1" within the recipe, for example:: diff --git a/poky/documentation/migration-guides/migration-2.1.rst b/poky/documentation/migration-guides/migration-2.1.rst index b2d8a0b678..c19ba5501c 100644 --- a/poky/documentation/migration-guides/migration-2.1.rst +++ b/poky/documentation/migration-guides/migration-2.1.rst @@ -108,12 +108,12 @@ this change should not be a problem. However, if you have a recipe that bypasses the standard :ref:`ref-tasks-configure` task from the :ref:`autotools <ref-classes-autotools>` class and the software the recipe is building uses a very old version of ``autoconf``, the recipe might be incapable -of determining the correct size of ``off_t`` during ``do_configure``. +of determining the correct size of ``off_t`` during :ref:`ref-tasks-configure`. The best course of action is to patch the software as necessary to allow the default implementation from the :ref:`autotools <ref-classes-autotools>` class to work such that ``autoreconf`` succeeds and produces a working configure script, -and to remove the overridden ``do_configure`` task such that the default +and to remove the overridden :ref:`ref-tasks-configure` task such that the default implementation does get used. .. _migration-2.1-image-generation-split-out-from-filesystem-generation: @@ -128,12 +128,12 @@ separate :ref:`ref-tasks-image` tasks for clarity both in operation and in the code. For most cases, this change does not present any problems. However, if -you have made customizations that directly modify the ``do_rootfs`` task -or that mention ``do_rootfs``, you might need to update those changes. -In particular, if you had added any tasks after ``do_rootfs``, you +you have made customizations that directly modify the :ref:`ref-tasks-rootfs` task +or that mention :ref:`ref-tasks-rootfs`, you might need to update those changes. +In particular, if you had added any tasks after :ref:`ref-tasks-rootfs`, you should make edits so that those tasks are after the :ref:`ref-tasks-image-complete` task rather than -after ``do_rootfs`` so that your added tasks run at the correct +after :ref:`ref-tasks-rootfs` so that your added tasks run at the correct time. A minor part of this restructuring is that the post-processing diff --git a/poky/documentation/migration-guides/migration-2.4.rst b/poky/documentation/migration-guides/migration-2.4.rst index 964ed92937..8904495022 100644 --- a/poky/documentation/migration-guides/migration-2.4.rst +++ b/poky/documentation/migration-guides/migration-2.4.rst @@ -54,7 +54,7 @@ occurred: when "pam" is in :term:`DISTRO_FEATURES`. - The ``switch_root`` program is now packaged in a separate - "util-linux-switch-root" package for small initramfs images that + "util-linux-switch-root" package for small :term:`Initramfs` images that do not need the whole ``util-linux`` package or the busybox binary, which are both much larger than ``switch_root``. The main ``util-linux`` package has a recommended runtime dependency (i.e. diff --git a/poky/documentation/migration-guides/migration-2.5.rst b/poky/documentation/migration-guides/migration-2.5.rst index abd26809df..04f4cd7e73 100644 --- a/poky/documentation/migration-guides/migration-2.5.rst +++ b/poky/documentation/migration-guides/migration-2.5.rst @@ -261,7 +261,7 @@ The following are additional changes: ``pkg_postinst_ontarget()`` or call ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``. Any failure of a ``pkg_postinst()`` script (including ``exit 1``) - will trigger a warning during ``do_rootfs``. + will trigger a warning during :ref:`ref-tasks-rootfs`. For more information, see the ":ref:`dev-manual/common-tasks:post-installation scripts`" diff --git a/poky/documentation/migration-guides/migration-2.6.rst b/poky/documentation/migration-guides/migration-2.6.rst index 11e659de7c..32bb48bccc 100644 --- a/poky/documentation/migration-guides/migration-2.6.rst +++ b/poky/documentation/migration-guides/migration-2.6.rst @@ -135,7 +135,7 @@ Fetching these types of dependencies that are not provided in the sysroot negatively affects the ability to reproduce builds. This type of fetching is now explicitly disabled. Consequently, any missing dependencies in Python recipes that use these classes now result in an -error during the ``do_configure`` task. +error during the :ref:`ref-tasks-configure` task. .. _migration-2.6-linux-yocto-configuration-audit-issues-now-correctly-reported: diff --git a/poky/documentation/migration-guides/migration-3.1.rst b/poky/documentation/migration-guides/migration-3.1.rst index cc788efeba..a6106eefae 100644 --- a/poky/documentation/migration-guides/migration-3.1.rst +++ b/poky/documentation/migration-guides/migration-3.1.rst @@ -234,7 +234,7 @@ Packaging changes Additional warnings ------------------- -Warnings will now be shown at ``do_package_qa`` time in the following +Warnings will now be shown at :ref:`ref-tasks-package_qa` time in the following circumstances: - A recipe installs ``.desktop`` files containing ``MimeType`` keys but diff --git a/poky/documentation/migration-guides/migration-3.2.rst b/poky/documentation/migration-guides/migration-3.2.rst index 92b7f91f2c..a714bd6bca 100644 --- a/poky/documentation/migration-guides/migration-3.2.rst +++ b/poky/documentation/migration-guides/migration-3.2.rst @@ -60,7 +60,7 @@ pseudo as the interprocess round trip to the server is avoided. There is a possible complication where some existing recipe may break, for example, a recipe was found to be writing to ``${B}/install`` for -``make install`` in ``do_install`` and since ``${B}`` is listed as not to be tracked, +``make install`` in :ref:`ref-tasks-install` and since ``${B}`` is listed as not to be tracked, there were errors trying to ``chown root`` for files in this location. Another example was the ``tcl`` recipe where the source directory :term:`S` is set to a subdirectory of the source tree but files were written out to the directory @@ -191,7 +191,7 @@ Globbing no longer supported in ``file://`` entries in ``SRC_URI`` Globbing (``*`` and ``?`` wildcards) in ``file://`` URLs within :term:`SRC_URI` did not properly support file checksums, thus changes to the source files -would not always change the do_fetch task checksum, and consequently would +would not always change the :ref:`ref-tasks-fetch` task checksum, and consequently would not ensure that the changed files would be incorporated in subsequent builds. Unfortunately it is not practical to make globbing work generically here, so @@ -207,9 +207,9 @@ files into a subdirectory and reference that instead. deploy class now cleans ``DEPLOYDIR`` before ``do_deploy`` ---------------------------------------------------------- -``do_deploy`` as implemented in the :ref:`deploy <ref-classes-deploy>` class now cleans up ${:term:`DEPLOYDIR`} before running, just as ``do_install`` cleans up ${:term:`D`} before running. This reduces the risk of :term:`DEPLOYDIR` being accidentally contaminated by files from previous runs, possibly even with different config, in case of incremental builds. +:ref:`ref-tasks-deploy` as implemented in the :ref:`deploy <ref-classes-deploy>` class now cleans up ${:term:`DEPLOYDIR`} before running, just as :ref:`ref-tasks-install` cleans up ${:term:`D`} before running. This reduces the risk of :term:`DEPLOYDIR` being accidentally contaminated by files from previous runs, possibly even with different config, in case of incremental builds. -Most recipes and classes that inherit the :ref:`deploy <ref-classes-deploy>` class or interact with ``do_deploy`` are unlikely to be affected by this unless they add ``prefuncs`` to ``do_deploy`` *which also* put files into ``${DEPLOYDIR}`` --- these should be refactored to use ``do_deploy_prepend`` instead. +Most recipes and classes that inherit the :ref:`deploy <ref-classes-deploy>` class or interact with :ref:`ref-tasks-deploy` are unlikely to be affected by this unless they add ``prefuncs`` to :ref:`ref-tasks-deploy` *which also* put files into ``${DEPLOYDIR}`` --- these should be refactored to use ``do_deploy_prepend`` instead. .. _migration-3.2-nativesdk-sdk-provides-dummy: @@ -265,10 +265,10 @@ using the GL options. .. _migration-3.2-initramfs-suffix: -initramfs images now use a blank suffix +Initramfs images now use a blank suffix --------------------------------------- -The reference initramfs images (``core-image-minimal-initramfs``, +The reference :term:`Initramfs` images (``core-image-minimal-initramfs``, ``core-image-tiny-initramfs`` and ``core-image-testmaster-initramfs``) now set an empty string for :term:`IMAGE_NAME_SUFFIX`, which otherwise defaults to ``".rootfs"``. These images aren't root filesystems and thus the rootfs diff --git a/poky/documentation/migration-guides/migration-3.4.rst b/poky/documentation/migration-guides/migration-3.4.rst index bc2c75d42e..4ceea7b0e4 100644 --- a/poky/documentation/migration-guides/migration-3.4.rst +++ b/poky/documentation/migration-guides/migration-3.4.rst @@ -22,7 +22,7 @@ syntax, so the following:: SRC_URI_append = " file://somefile" SRC_URI_append_qemux86 = " file://somefile2" - SRC_URI_remove_qemux86-64 = " file://somefile3" + SRC_URI_remove_qemux86-64 = "file://somefile3" SRC_URI_prepend_qemuarm = "file://somefile4 " FILES_${PN}-ptest = "${bindir}/xyz" IMAGE_CMD_tar = "tar" @@ -34,7 +34,7 @@ would now become:: SRC_URI:append = " file://somefile" SRC_URI:append:qemux86 = " file://somefile2" - SRC_URI:remove:qemux86-64 = " file://somefile3" + SRC_URI:remove:qemux86-64 = "file://somefile3" SRC_URI:prepend:qemuarm = "file://somefile4 " FILES:${PN}-ptest = "${bindir}/xyz" IMAGE_CMD:tar = "tar" @@ -206,7 +206,7 @@ Package/recipe splitting Image / SDK generation changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Recursive dependencies on the ``do_build`` task are now disabled when +- Recursive dependencies on the :ref:`ref-tasks-build` task are now disabled when building SDKs. These are generally not needed; in the unlikely event that you do encounter problems then it will probably be as a result of missing explicit dependencies that need to be added. diff --git a/poky/documentation/migration-guides/migration-4.0.rst b/poky/documentation/migration-guides/migration-4.0.rst index 79e53f89ac..02d3c3e2bd 100644 --- a/poky/documentation/migration-guides/migration-4.0.rst +++ b/poky/documentation/migration-guides/migration-4.0.rst @@ -93,8 +93,8 @@ Fetching changes do_mytask[network] = "1" - This is allowed by default from ``do_fetch`` but not from any of our other standard - tasks. Recipes shouldn't be accessing the network outside of ``do_fetch`` as it + This is allowed by default from :ref:`ref-tasks-fetch` but not from any of our other standard + tasks. Recipes shouldn't be accessing the network outside of :ref:`ref-tasks-fetch` as it usually undermines fetcher source mirroring, image and licence manifests, software auditing and supply chain security. @@ -145,7 +145,7 @@ Python changes :ref:`python_setuptools_build_meta <ref-classes-python_setuptools_build_meta>` and :ref:`python_poetry_core <ref-classes-python_poetry_core>`. -- The :ref:`setuptools3 <ref-classes-setuptools3>` class ``do_install()`` task now +- The :ref:`setuptools3 <ref-classes-setuptools3>` class :ref:`ref-tasks-install` task now installs the ``wheel`` binary archive. In current versions of ``setuptools`` the legacy ``setup.py install`` method is deprecated. If the ``setup.py`` cannot be used with wheels, for example it creates files outside of the Python module or standard diff --git a/poky/documentation/migration-guides/release-4.0.rst b/poky/documentation/migration-guides/release-4.0.rst index fe1efaec1f..9f67daaffb 100644 --- a/poky/documentation/migration-guides/release-4.0.rst +++ b/poky/documentation/migration-guides/release-4.0.rst @@ -8,3 +8,4 @@ Release 4.0 (kirkstone) release-notes-4.0.1 release-notes-4.0.2 release-notes-4.0.3 + release-notes-4.0.4 diff --git a/poky/documentation/migration-guides/release-notes-3.4.rst b/poky/documentation/migration-guides/release-notes-3.4.rst index 323e4df7ae..de1d209682 100644 --- a/poky/documentation/migration-guides/release-notes-3.4.rst +++ b/poky/documentation/migration-guides/release-notes-3.4.rst @@ -36,7 +36,7 @@ New Features / Enhancements in 3.4 - Kernel-related enhancements: - - Support zstd-compressed modules and initramfs images + - Support zstd-compressed modules and :term:`Initramfs` images - Allow opt-out of split kernel modules - linux-yocto-dev: base AUTOREV on specified version - kernel-yocto: provide debug / summary information for metadata @@ -67,7 +67,7 @@ New Features / Enhancements in 3.4 - SDK-related enhancements: - - Enable do_populate_sdk with multilibs + - 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 - 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 @@ -211,7 +211,7 @@ The following corrections have been made to the LICENSE values set by recipes: Other license-related notes: - When creating recipes for Python software, recipetool will now treat "BSD" as "BSD-3-Clause" for the purposes of setting LICENSE, as that is the most common understanding. -- Please be aware that an initramfs bundled with the kernel using :term:`INITRAMFS_IMAGE_BUNDLE` should only contain GPLv2-compatible software; this is now mentioned in the documentation. +- Please be aware that an :term:`Initramfs` bundled with the kernel using :term:`INITRAMFS_IMAGE_BUNDLE` should only contain GPLv2-compatible software; this is now mentioned in the documentation. Security Fixes in 3.4 ~~~~~~~~~~~~~~~~~~~~~ diff --git a/poky/documentation/migration-guides/release-notes-4.0.4.rst b/poky/documentation/migration-guides/release-notes-4.0.4.rst new file mode 100644 index 0000000000..2623a1dca7 --- /dev/null +++ b/poky/documentation/migration-guides/release-notes-4.0.4.rst @@ -0,0 +1,299 @@ +Release notes for Yocto-4.0.4 (Kirkstone) +----------------------------------------- + +Security Fixes in Yocto-4.0.4 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- binutils : fix :cve:`2022-38533` +- curl: fix :cve:`2022-35252` +- sqlite: fix :cve:`2022-35737` +- grub2: fix :cve:`2021-3695`, :cve:`2021-3696`, :cve:`2021-3697`, :cve:`2022-28733`, :cve:`2022-28734` and :cve:`2022-28735` +- u-boot: fix :cve:`2022-30552` and :cve:`2022-33967` +- libxml2: Ignore :cve:`2016-3709` +- libtiff: fix :cve:`2022-34526` +- zlib: fix :cve:`2022-37434` +- gnutls: fix :cve:`2022-2509` +- u-boot: fix :cve:`2022-33103` +- qemu: fix :cve:`2021-3507`, :cve:`2021-3929`, :cve:`2021-4158`, :cve:`2022-0216` and :cve:`2022-0358` + + +Fixes in Yocto-4.0.4 +~~~~~~~~~~~~~~~~~~~~ + +- apr: Cache configure tests which use AC_TRY_RUN +- apr: Use correct strerror_r implementation based on libc type +- apt: fix nativesdk-apt build failure during the second time build +- archiver.bbclass: remove unsed do_deploy_archives[dirs] +- archiver.bbclass: some recipes that uses the kernelsrc bbclass uses the shared source +- autoconf: Fix strict prototype errors in generated tests +- autoconf: Update K & R stype functions +- bind: upgrade to 9.18.5 +- bitbake.conf: set BB_DEFAULT_UMASK using ??= +- bitbake: ConfHandler/BBHandler: Improve comment error messages and add tests +- bitbake: ConfHandler: Remove lingering close +- bitbake: bb/utils: movefile: use the logger for printing +- bitbake: bb/utils: remove: check the path again the expand python glob +- bitbake: bitbake-user-manual: Correct description of the ??= operator +- bitbake: bitbake-user-manual: npm fetcher: improve description of SRC_URI format +- bitbake: bitbake: bitbake-user-manual: hashserv can be accessed on a dedicated domain +- bitbake: bitbake: runqueue: add cpu/io pressure regulation +- bitbake: bitbake: runqueue: add memory pressure regulation +- bitbake: cooker: Drop sre_constants usage +- bitbake: doc: bitbake-user-manual: add explicit target for crates fetcher +- bitbake: doc: bitbake-user-manual: document npm and npmsw fetchers +- bitbake: event.py: ignore exceptions from stdout and sterr operations in atexit +- bitbake: fetch2: Ensure directory exists before creating symlink +- bitbake: fetch2: gitsm: fix incorrect handling of git submodule relative urls +- bitbake: runqueue: Change pressure file warning to a note +- bitbake: runqueue: Fix unihash cache mismatch issues +- bitbake: toaster: fix kirkstone version +- bitbake: utils: Pass lock argument in fileslocked +- bluez5: upgrade to 5.65 +- boost: fix install of fiber shared libraries +- cairo: Adapt the license information based on what is being built +- classes: cve-check: Get shared database lock +- cmake: remove CMAKE_ASM_FLAGS variable in toolchain file +- connman: Backports for security fixes +- core-image.bbclass: Exclude openssh complementary packages +- cracklib: Drop using register keyword +- cracklib: upgrade to 2.9.8 +- create-spdx: Fix supplier field +- create-spdx: handle links to inaccessible locations +- create-spdx: ignore packing control files from ipk and deb +- cve-check: Don't use f-strings +- cve-check: close cursors as soon as possible +- devtool/upgrade: catch bb.fetch2.decodeurl errors +- devtool/upgrade: correctly clean up when recipe filename isn't yet known +- devtool: error out when workspace is using old override syntax +- ell: upgrade to 0.50 +- epiphany: upgrade to 42.4 +- externalsrc: Don't wipe out src dir when EXPORT_FUNCTIONS is used. +- gcc-multilib-config: Fix i686 toolchain relocation issues +- gcr: Define _GNU_SOURCE +- gdk-pixbuf: upgrade to 2.42.9 +- glib-networking: upgrade to 2.72.2 +- go: upgrade to v1.17.13 +- insane.bbclass: Skip patches not in oe-core by full path +- iso-codes: upgrade to 4.11.0 +- kernel-fitimage.bbclass: add padding algorithm property in config nodes +- kernel-fitimage.bbclass: only package unique DTBs +- kernel: Always set CC and LD for the kernel build +- kernel: Use consistent make flags for menuconfig +- lib:npm_registry: initial checkin +- libatomic-ops: upgrade to 7.6.14 +- libcap: upgrade to 2.65 +- libjpeg-turbo: upgrade to 2.1.4 +- libpam: use /run instead of /var/run in systemd tmpfiles +- libtasn1: upgrade to 4.19.0 +- liburcu: upgrade to 0.13.2 +- libwebp: upgrade to 1.2.4 +- libwpe: upgrade to 1.12.3 +- libxml2: Port gentest.py to Python-3 +- lighttpd: upgrade to 1.4.66 +- linux-yocto/5.10: update genericx86* machines to v5.10.135 +- linux-yocto/5.10: update to v5.10.137 +- linux-yocto/5.15: update genericx86* machines to v5.15.59 +- linux-yocto/5.15: update to v5.15.62 +- linux-yocto: Fix COMPATIBLE_MACHINE regex match +- linux-yocto: prepend the the value with a space when append to KERNEL_EXTRA_ARGS +- lttng-modules: fix 5.19+ build +- lttng-modules: fix build against mips and v5.19 kernel +- lttng-modules: fix build for kernel 5.10.137 +- lttng-modules: replace mips compaction fix with upstream change +- lz4: upgrade to 1.9.4 +- maintainers: update opkg maintainer +- meta: introduce UBOOT_MKIMAGE_KERNEL_TYPE +- migration guides: add missing release notes +- mobile-broadband-provider-info: upgrade to 20220725 +- nativesdk: Clear TUNE_FEATURES +- npm: replace 'npm pack' call by 'tar czf' +- npm: return content of 'package.json' in 'npm_pack' +- npm: take 'version' directly from 'package.json' +- npm: use npm_registry to cache package +- oeqa/gotoolchain: put writable files in the Go module cache +- oeqa/gotoolchain: set CGO_ENABLED=1 +- oeqa/parselogs: add qemuarmv5 arm-charlcd masking +- oeqa/qemurunner: add run_serial() comment +- oeqa/selftest: rename git.py to intercept.py +- oeqa: qemurunner: Report UNIX Epoch timestamp on login +- package_rpm: Do not replace square brackets in %files +- packagegroup-self-hosted: update for strace +- parselogs: Ignore xf86OpenConsole error +- perf: Fix reproducibility issues with 5.19 onwards +- pinentry: enable _XOPEN_SOURCE on musl for wchar usage in curses +- poky.conf: add ubuntu-22.04 to tested distros +- poky.conf: bump version for 4.0.4 +- pseudo: Update to include recent upstream minor fixes +- python3-pip: Fix RDEPENDS after the update +- ref-manual: add numa to machine features +- relocate_sdk.py: ensure interpreter size error causes relocation to fail +- rootfs-postcommands.bbclass: avoid moving ssh host keys if etc is writable +- rootfs.py: dont try to list installed packages for baremetal images +- rootfspostcommands.py: Cleanup subid backup files generated by shadow-utils +- ruby: drop capstone support +- runqemu: Add missing space on default display option +- runqemu: display host uptime when starting +- sanity: add a comment to ensure CONNECTIVITY_CHECK_URIS is correct +- scripts/oe-setup-builddir: make it known where configurations come from +- scripts/runqemu.README: fix typos and trailing whitespaces +- selftest/wic: Tweak test case to not depend on kernel size +- shadow: Avoid nss warning/error with musl +- shadow: Enable subid support +- system-requirements.rst: Add Ubuntu 22.04 to list of supported distros +- systemd: Add 'no-dns-fallback' PACKAGECONFIG option +- systemd: Fix unwritable /var/lock when no sysvinit handling +- sysvinit-inittab/start_getty: Fix respawn too fast +- tcp-wrappers: Fix implicit-function-declaration warnings +- tzdata: upgrade to 2022b +- util-linux: Remove --enable-raw from EXTRA_OECONF +- vala: upgrade to 0.56.3 +- vim: Upgrade to 9.0.0453 +- watchdog: Include needed system header for function decls +- webkitgtk: upgrade to 2.36.5 +- weston: upgrade to 10.0.2 +- wic/bootimg-efi: use cross objcopy when building unified kernel image +- wic: add target tools to PATH when executing native commands +- wic: depend on cross-binutils +- wireless-regdb: upgrade to 2022.08.12 +- wpebackend-fdo: upgrade to 1.12.1 +- xinetd: Pass missing -D_GNU_SOURCE +- xz: update to 5.2.6 + + +Known Issues in Yocto-4.0.4 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- N/A + + +Contributors to Yocto-4.0.4 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Alejandro Hernandez Samaniego +- Alex Stewart +- Alexander Kanavin +- Alexandre Belloni +- Andrei Gherzan +- Anuj Mittal +- Aryaman Gupta +- Awais Belal +- Beniamin Sandu +- Bertrand Marquis +- Bruce Ashfield +- Changqing Li +- Chee Yang Lee +- Daiane Angolini +- Enrico Scholz +- Ernst Sjöstrand +- Gennaro Iorio +- Hitendra Prajapati +- Jacob Kroon +- Jon Mason +- Jose Quaresma +- Joshua Watt +- Kai Kang +- Khem Raj +- Kristian Amlie +- LUIS ENRIQUEZ +- Mark Hatle +- Martin Beeger +- Martin Jansa +- Mateusz Marciniec +- Michael Opdenacker +- Mihai Lindner +- Mikko Rapeli +- Ming Liu +- Niko Mauno +- Ola x Nilsson +- Otavio Salvador +- Paul Eggleton +- Pavel Zhukov +- Peter Bergin +- Peter Kjellerstedt +- Peter Marko +- Rajesh Dangi +- Randy MacLeod +- Rasmus Villemoes +- Richard Purdie +- Robert Joslyn +- Roland Hieber +- Ross Burton +- Sakib Sajal +- Shubham Kulkarni +- Steve Sakoman +- Ulrich Ölmann +- Yang Xu +- Yongxin Liu +- ghassaneben +- pgowda +- wangmy + +Repositories / Downloads for Yocto-4.0.4 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +poky + +- Repository Location: https://git.yoctoproject.org/git/poky +- Branch: :yocto_git:`kirkstone </poky/log/?h=kirkstone>` +- Tag: :yocto_git:`yocto-4.0.4 </poky/log/?h=yocto-4.0.4>` +- Git Revision: :yocto_git:`d64bef1c7d713b92a51228e5ade945835e5a94a4 </poky/commit/?id=d64bef1c7d713b92a51228e5ade945835e5a94a4>` +- Release Artefact: poky-d64bef1c7d713b92a51228e5ade945835e5a94a4 +- sha: b5e92506b31f88445755bad2f45978b747ad1a5bea66ca897370542df5f1e7db +- Download Locations: + http://downloads.yoctoproject.org/releases/yocto/yocto-4.0.4/poky-d64bef1c7d713b92a51228e5ade945835e5a94a4.tar.bz2 + http://mirrors.kernel.org/yocto/yocto/yocto-4.0.4/poky-d64bef1c7d713b92a51228e5ade945835e5a94a4.tar.bz2 + +openembedded-core + +- Repository Location: https://git.openembedded.org/openembedded-core +- Branch: :oe_git:`kirkstone </openembedded-core/log/?h=kirkstone>` +- Tag: :oe_git:`yocto-4.0.4 </openembedded-core/log/?h=yocto-4.0.4>` +- Git Revision: :oe_git:`f7766da462905ec67bf549d46b8017be36cd5b2a </openembedded-core/commit/?id=f7766da462905ec67bf549d46b8017be36cd5b2a>` +- Release Artefact: oecore-f7766da462905ec67bf549d46b8017be36cd5b2a +- sha: ce0ac011474db5e5f0bb1be3fb97f890a02e46252a719dbcac5813268e48ff16 +- Download Locations: + http://downloads.yoctoproject.org/releases/yocto/yocto-4.0.4/oecore-f7766da462905ec67bf549d46b8017be36cd5b2a.tar.bz2 + http://mirrors.kernel.org/yocto/yocto/yocto-4.0.4/oecore-f7766da462905ec67bf549d46b8017be36cd5b2a.tar.bz2 + +meta-mingw + +- Repository Location: https://git.yoctoproject.org/git/meta-mingw +- Branch: :yocto_git:`kirkstone </meta-mingw/log/?h=kirkstone>` +- Tag: :yocto_git:`yocto-4.0.4 </meta-mingw/log/?h=yocto-4.0.4>` +- Git Revision: :yocto_git:`a90614a6498c3345704e9611f2842eb933dc51c1 </meta-mingw/commit/?id=a90614a6498c3345704e9611f2842eb933dc51c1>` +- Release Artefact: meta-mingw-a90614a6498c3345704e9611f2842eb933dc51c1 +- sha: 49f9900bfbbc1c68136f8115b314e95d0b7f6be75edf36a75d9bcd1cca7c6302 +- Download Locations: + http://downloads.yoctoproject.org/releases/yocto/yocto-4.0.4/meta-mingw-a90614a6498c3345704e9611f2842eb933dc51c1.tar.bz2 + http://mirrors.kernel.org/yocto/yocto/yocto-4.0.4/meta-mingw-a90614a6498c3345704e9611f2842eb933dc51c1.tar.bz2 + +meta-gplv2 + +- Repository Location: https://git.yoctoproject.org/git/meta-gplv2 +- Branch: :yocto_git:`kirkstone </meta-gplv2/log/?h=kirkstone>` +- Tag: :yocto_git:`yocto-4.0.4 </meta-gplv2/log/?h=yocto-4.0.4>` +- Git Revision: :yocto_git:`d2f8b5cdb285b72a4ed93450f6703ca27aa42e8a </meta-gplv2/commit/?id=d2f8b5cdb285b72a4ed93450f6703ca27aa42e8a>` +- Release Artefact: meta-gplv2-d2f8b5cdb285b72a4ed93450f6703ca27aa42e8a +- sha: c386f59f8a672747dc3d0be1d4234b6039273d0e57933eb87caa20f56b9cca6d +- Download Locations: + http://downloads.yoctoproject.org/releases/yocto/yocto-4.0.4/meta-gplv2-d2f8b5cdb285b72a4ed93450f6703ca27aa42e8a.tar.bz2 + http://mirrors.kernel.org/yocto/yocto/yocto-4.0.4/meta-gplv2-d2f8b5cdb285b72a4ed93450f6703ca27aa42e8a.tar.bz2 + +bitbake + +- Repository Location: https://git.openembedded.org/bitbake +- Branch: :oe_git:`2.0 </bitbake/log/?h=2.0>` +- Tag: :oe_git:`yocto-4.0.4 </bitbake/log/?h=yocto-4.0.4>` +- Git Revision: :oe_git:`ac576d6fad6bba0cfea931883f25264ea83747ca </bitbake/commit/?id=ac576d6fad6bba0cfea931883f25264ea83747ca>` +- Release Artefact: bitbake-ac576d6fad6bba0cfea931883f25264ea83747ca +- sha: 526c2768874eeda61ade8c9ddb3113c90d36ef44a026d6690f02de6f3dd0ea12 +- Download Locations: + http://downloads.yoctoproject.org/releases/yocto/yocto-4.0.4/bitbake-ac576d6fad6bba0cfea931883f25264ea83747ca.tar.bz2 + http://mirrors.kernel.org/yocto/yocto/yocto-4.0.4/bitbake-ac576d6fad6bba0cfea931883f25264ea83747ca.tar.bz2 + +yocto-docs + +- Repository Location: https://git.yoctoproject.org/git/yocto-docs +- Branch: :yocto_git:`kirkstone </yocto-docs/log/?h=kirkstone>` +- Tag: :yocto_git:`yocto-4.0.4 </yocto-docs/log/?h=yocto-4.0.4>` +- Git Revision: :yocto_git:`f632dad24c39778f948014029e74db3c871d9d21 </yocto-docs/commit/?id=f632dad24c39778f948014029e74db3c871d9d21>` diff --git a/poky/documentation/migration-guides/release-notes-4.0.rst b/poky/documentation/migration-guides/release-notes-4.0.rst index b675cae217..a61ccc6913 100644 --- a/poky/documentation/migration-guides/release-notes-4.0.rst +++ b/poky/documentation/migration-guides/release-notes-4.0.rst @@ -30,7 +30,7 @@ New Features / Enhancements in 4.0 - New :ref:`overlayfs <ref-classes-overlayfs>` and :ref:`overlayfs-etc <ref-classes-overlayfs-etc>` classes and - ``overlayroot`` support in the initramfs framework to make it easier to + ``overlayroot`` support in the :term:`Initramfs` framework to make it easier to overlay read-only filesystems (for example) with `OverlayFS <https://en.wikipedia.org/wiki/OverlayFS>`__. @@ -168,7 +168,7 @@ New Features / Enhancements in 4.0 - Kernel-related enhancements: - - Allow initramfs to be built from a separate multiconfig + - Allow :term:`Initramfs` to be built from a separate multiconfig - Make kernel-base recommend kernel-image, not depend (allowing images containing kernel modules without kernel image) - linux-yocto: split vtpm for more granular inclusion - linux-yocto: cfg/debug: add configs for kcsan @@ -182,7 +182,7 @@ New Features / Enhancements in 4.0 - FIT image related enhancements: - - New ``FIT_SUPPORTED_INITRAMFS_FSTYPES`` variable to allow extending initramfs image types to look for + - New ``FIT_SUPPORTED_INITRAMFS_FSTYPES`` variable to allow extending :term:`Initramfs` image types to look for - New ``FIT_CONF_PREFIX`` variable to allow overriding FIT configuration prefix - Use 'bbnote' for better logging @@ -276,7 +276,7 @@ New Features / Enhancements in 4.0 - volatile-binds: SELinux and overlayfs extensions in mount-copybind - gtk-icon-cache: Allow using gtk4 - kmod: Add an exclude directive to depmod -- os-release: add os-release-initrd package for use in systemd-based initramfs images +- os-release: add os-release-initrd package for use in systemd-based :term:`Initramfs` images - gstreamer1.0-plugins-base: add support for graphene - gpg-sign: Add parameters to gpg signature function - package_manager: sign DEB package feeds diff --git a/poky/documentation/overview-manual/concepts.rst b/poky/documentation/overview-manual/concepts.rst index 8e0303f0e0..39b87138a8 100644 --- a/poky/documentation/overview-manual/concepts.rst +++ b/poky/documentation/overview-manual/concepts.rst @@ -703,16 +703,12 @@ the source files and unpack them into the .. note:: - For every local file (e.g. - file:// - ) that is part of a recipe's - SRC_URI - statement, the OpenEmbedded build system takes a checksum of the file - for the recipe and inserts the checksum into the signature for the - do_fetch - task. If any local file has been modified, the - do_fetch - task and all tasks that depend on it are re-executed. + For every local file (e.g. ``file://``) that is part of a recipe's + :term:`SRC_URI` statement, the OpenEmbedded build system takes a + checksum of the file for the recipe and inserts the checksum into + the signature for the :ref:`ref-tasks-fetch` task. If any local + file has been modified, the :ref:`ref-tasks-fetch` task and all + tasks that depend on it are re-executed. By default, everything is accomplished in the Build Directory, which has a defined structure. For additional general information on the Build @@ -892,7 +888,7 @@ following as well as other items: splitting out debugging symbols, looking at shared library dependencies between packages, and looking at package relationships. -The ``do_packagedata`` task creates package metadata based on the +The :ref:`ref-tasks-packagedata` task creates package metadata based on the analysis such that the build system can generate the final packages. The :ref:`ref-tasks-populate_sysroot` task stages (copies) a subset of the files installed by the @@ -905,7 +901,7 @@ the analysis and package splitting process use several areas: individual packages. - :term:`PKGDESTWORK`: A - temporary work area (i.e. ``pkgdata``) used by the ``do_package`` + temporary work area (i.e. ``pkgdata``) used by the :ref:`ref-tasks-package` task to save package metadata. - :term:`PKGDEST`: The parent @@ -1012,7 +1008,7 @@ all the post installation scripts must succeed on the build host during the package installation phase since the root filesystem on the target is read-only. -The final stages of the ``do_rootfs`` task handle post processing. Post +The final stages of the :ref:`ref-tasks-rootfs` task handle post processing. Post processing includes creation of a manifest file and optimizations. The manifest file (``.manifest``) resides in the same directory as the @@ -1036,7 +1032,7 @@ the variable. This variable specifies a list of functions to call before the build system creates the final image output files. -The build system dynamically creates ``do_image_*`` tasks as needed, +The build system dynamically creates :ref:`do_image_* <ref-tasks-image>` tasks as needed, based on the image types specified in the :term:`IMAGE_FSTYPES` variable. The process turns everything into an image file or a set of image files @@ -1085,7 +1081,7 @@ the extensible SDK (eSDK): For more information on the cross-development toolchain generation, see the ":ref:`overview-manual/concepts:cross-development toolchain generation`" section. For information on advantages gained when building a - cross-development toolchain using the do_populate_sdk task, see the + cross-development toolchain using the :ref:`ref-tasks-populate_sdk` task, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`" section in the Yocto Project Application Development and the Extensible Software Development Kit (eSDK) manual. @@ -1100,13 +1096,13 @@ actually install. For information on the variables listed in the figure, see the ":ref:`overview-manual/concepts:application development sdk`" section. -The ``do_populate_sdk`` task helps create the standard SDK and handles +The :ref:`ref-tasks-populate_sdk` task helps create the standard SDK and handles two parts: a target part and a host part. The target part is the part built for the target hardware and includes libraries and headers. The host part is the part of the SDK that runs on the :term:`SDKMACHINE`. -The ``do_populate_sdk_ext`` task helps create the extensible SDK and +The :ref:`ref-tasks-populate_sdk_ext` task helps create the extensible SDK and handles host and target parts differently than its counter part does for the standard SDK. For the extensible SDK, the task encapsulates the build system, which includes everything needed (host and target) for the @@ -1198,7 +1194,7 @@ the work involved would be equal to or greater than the underlying task. In the build system, the common tasks that have setscene variants are :ref:`ref-tasks-package`, -``do_package_write_*``, +:ref:`do_package_write_* <ref-tasks-package_write_deb>`, :ref:`ref-tasks-deploy`, :ref:`ref-tasks-packagedata`, and :ref:`ref-tasks-populate_sysroot`. @@ -1208,15 +1204,15 @@ end result. The build system has knowledge of the relationship between these tasks and other preceding tasks. For example, if BitBake runs ``do_populate_sysroot_setscene`` for something, it does not make sense -to run any of the ``do_fetch``, ``do_unpack``, ``do_patch``, -``do_configure``, ``do_compile``, and ``do_install`` tasks. However, if -``do_package`` needs to be run, BitBake needs to run those other tasks. +to run any of the :ref:`ref-tasks-fetch`, :ref:`ref-tasks-unpack`, :ref:`ref-tasks-patch`, +:ref:`ref-tasks-configure`, :ref:`ref-tasks-compile`, and :ref:`ref-tasks-install` tasks. However, if +:ref:`ref-tasks-package` needs to be run, BitBake needs to run those other tasks. It becomes more complicated if everything can come from an sstate cache because some objects are simply not required at all. For example, you do not need a compiler or native tools, such as quilt, if there isn't anything -to compile or patch. If the ``do_package_write_*`` packages are available -from sstate, BitBake does not need the ``do_package`` task data. +to compile or patch. If the :ref:`do_package_write_* <ref-tasks-package_write_deb>` packages are available +from sstate, BitBake does not need the :ref:`ref-tasks-package` task data. To handle all these complexities, BitBake runs in two phases. The first is the "setscene" stage. During this stage, BitBake first checks the @@ -1801,14 +1797,14 @@ from the :ref:`deploy <ref-classes-deploy>` class:: The following list explains the previous example: -- Adding "do_deploy" to ``SSTATETASKS`` adds some required +- Adding ``do_deploy`` to ``SSTATETASKS`` adds some required sstate-related processing, which is implemented in the :ref:`sstate <ref-classes-sstate>` class, to before and after the :ref:`ref-tasks-deploy` task. - The ``do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"`` declares that - ``do_deploy`` places its output in ``${DEPLOYDIR}`` when run normally + :ref:`ref-tasks-deploy` places its output in ``${DEPLOYDIR}`` when run normally (i.e. when not using the sstate cache). This output becomes the input to the shared state cache. @@ -1818,15 +1814,15 @@ The following list explains the previous example: .. note:: - If ``do_deploy`` is not already in the shared state cache or if its input + If :ref:`ref-tasks-deploy` is not already in the shared state cache or if its input checksum (signature) has changed from when the output was cached, the task runs to populate the shared state cache, after which the contents of the shared state cache is copied to ${:term:`DEPLOY_DIR_IMAGE`}. If - ``do_deploy`` is in the shared state cache and its signature indicates + :ref:`ref-tasks-deploy` is in the shared state cache and its signature indicates that the cached output is still valid (i.e. if no relevant task inputs have changed), then the contents of the shared state cache copies directly to ${:term:`DEPLOY_DIR_IMAGE`} by the ``do_deploy_setscene`` task - instead, skipping the ``do_deploy`` task. + instead, skipping the :ref:`ref-tasks-deploy` task. - The following task definition is glue logic needed to make the previous settings effective:: @@ -1836,16 +1832,16 @@ The following list explains the previous example: } addtask do_deploy_setscene - ``sstate_setscene()`` takes the flags above as input and accelerates the ``do_deploy`` task + ``sstate_setscene()`` takes the flags above as input and accelerates the :ref:`ref-tasks-deploy` task through the shared state cache if possible. If the task was accelerated, ``sstate_setscene()`` returns True. Otherwise, it - returns False, and the normal ``do_deploy`` task runs. For more + returns False, and the normal :ref:`ref-tasks-deploy` task runs. For more information, see the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:setscene`" section in the BitBake User Manual. - The ``do_deploy[dirs] = "${DEPLOYDIR} ${B}"`` line creates - ``${DEPLOYDIR}`` and ``${B}`` before the ``do_deploy`` task runs, and - also sets the current working directory of ``do_deploy`` to ``${B}``. + ``${DEPLOYDIR}`` and ``${B}`` before the :ref:`ref-tasks-deploy` task runs, and + also sets the current working directory of :ref:`ref-tasks-deploy` to ``${B}``. For more information, see the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" section in the BitBake User Manual. @@ -1854,7 +1850,7 @@ The following list explains the previous example: In cases where ``sstate-inputdirs`` and ``sstate-outputdirs`` would be the same, you can use ``sstate-plaindirs``. For example, to preserve the - ${:term:`PKGD`} and ${:term:`PKGDEST`} output from the ``do_package`` + ${:term:`PKGD`} and ${:term:`PKGDEST`} output from the :ref:`ref-tasks-package` task, use the following:: do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" @@ -2101,12 +2097,12 @@ dependencies, you must manually declare the dependencies. :term:`PRIVATE_LIBS` inside the package's recipe. -- ``pcdeps``: During the ``do_package`` task of each recipe, all +- ``pcdeps``: During the :ref:`ref-tasks-package` task of each recipe, all pkg-config modules (``*.pc`` files) installed by the recipe are located. For each module, the package that contains the module is registered as providing the module. The resulting module-to-package mapping is saved globally in :term:`PKGDATA_DIR` by the - ``do_packagedata`` task. + :ref:`ref-tasks-packagedata` task. Simultaneously, all pkg-config modules installed by the recipe are inspected to see what other pkg-config modules they depend on. A @@ -2147,7 +2143,7 @@ dependencies, you must manually declare the dependencies. :term:`ALLOW_EMPTY` variable for more information. -The ``do_package`` task depends on the ``do_packagedata`` task of each +The :ref:`ref-tasks-package` task depends on the :ref:`ref-tasks-packagedata` task of each recipe in :term:`DEPENDS` through use of a ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` declaration, which guarantees that the required @@ -2162,8 +2158,8 @@ operations that are normally reserved for the root user (e.g. :ref:`ref-tasks-install`, :ref:`do_package_write* <ref-tasks-package_write_deb>`, :ref:`ref-tasks-rootfs`, and -:ref:`do_image* <ref-tasks-image>`). For example, -the ``do_install`` task benefits from being able to set the UID and GID +:ref:`do_image_* <ref-tasks-image>`). For example, +the :ref:`ref-tasks-install` task benefits from being able to set the UID and GID of installed files to arbitrary values. One approach to allowing tasks to perform root-only operations would be diff --git a/poky/documentation/ref-manual/classes.rst b/poky/documentation/ref-manual/classes.rst index 11e0d472e8..5e49613b2f 100644 --- a/poky/documentation/ref-manual/classes.rst +++ b/poky/documentation/ref-manual/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_*`` tasks to + :ref:`do_package_write_* <ref-tasks-package_write_deb>` tasks to have different signatures for the machines with different tunings. Additionally, unnecessary rebuilds occur every time an image for a different :term:`MACHINE` is built even when the recipe never changes. @@ -444,7 +444,7 @@ staging the files from :term:`DEPLOYDIR` to :term:`DEPLOY_DIR_IMAGE`. ``devshell.bbclass`` ==================== -The ``devshell`` class adds the ``do_devshell`` task. Distribution +The ``devshell`` class adds the :ref:`ref-tasks-devshell` task. Distribution policy dictates whether to include this class. See the ":ref:`dev-manual/common-tasks:using a development shell`" section in the Yocto Project Development Tasks Manual for more information about using ``devshell``. @@ -1081,12 +1081,12 @@ Here are the tests you can list with the :term:`WARN_QA` and might result in host contamination of the build output. - ``installed-vs-shipped:`` Reports when files have been installed - within ``do_install`` but have not been included in any package by + within :ref:`ref-tasks-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 build process. Ideally, all installed files should be packaged or not installed at all. These files can be deleted at the end of - ``do_install`` if the files are not needed in any package. + :ref:`ref-tasks-install` if the files are not needed in any package. - ``invalid-chars:`` Checks that the recipe metadata variables :term:`DESCRIPTION`, @@ -1256,9 +1256,9 @@ package installs all packages with modules and various other kernel 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 -":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section in +RAM filesystem (:term:`Initramfs`) image when you build the kernel image. For +information on how to build an :term:`Initramfs`, see the +":ref:`dev-manual/common-tasks:building an initial ram filesystem (Initramfs) image`" section in the Yocto Project Development Tasks Manual. Various other classes are used by the ``kernel`` and ``module`` classes @@ -1339,7 +1339,7 @@ Only a single U-boot boot script can be added to the FIT image created by ``kernel-fitimage`` and the boot script is optional. The boot script is specified in the ITS file as a text file containing U-boot commands. When using a boot script the user should configure the -U-boot ``do_install`` task to copy the script to sysroot. +U-boot :ref:`ref-tasks-install` task to copy the script to sysroot. So the script can be included in the FIT image by the ``kernel-fitimage`` class. At run-time, U-boot CONFIG_BOOTCOMMAND define can be configured to load the boot script from the FIT image and executes it. @@ -2401,7 +2401,7 @@ uses these build systems, the recipe needs to inherit the ``setuptools3`` class. .. note:: - The ``setuptools3`` class ``do_compile()`` task now calls + The ``setuptools3`` class :ref:`ref-tasks-compile` task now calls ``setup.py bdist_wheel`` to build the ``wheel`` binary archive format (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__). @@ -2412,7 +2412,7 @@ uses these build systems, the recipe needs to inherit the ``setuptools3`` class. .. note:: - The ``setuptools3`` class ``do_install()`` task now installs the ``wheel`` + The ``setuptools3`` class :ref:`ref-tasks-install` task now installs the ``wheel`` binary archive. In current versions of ``setuptools`` the legacy ``setup.py install`` method is deprecated. If the ``setup.py`` cannot be used with wheels, for example it creates files outside of the Python module or @@ -2527,7 +2527,7 @@ stages: want to share with other recipes that have dependencies on the originating recipe. Normally these dependencies are installed through the :ref:`ref-tasks-install` task into - ``${``\ :term:`D`\ ``}``. The ``do_populate_sysroot`` task + ``${``\ :term:`D`\ ``}``. The :ref:`ref-tasks-populate_sysroot` task copies a subset of these files into ``${SYSROOT_DESTDIR}``. This subset of files is controlled by the :term:`SYSROOT_DIRS`, diff --git a/poky/documentation/ref-manual/faq.rst b/poky/documentation/ref-manual/faq.rst index 61049523a0..af49d57715 100644 --- a/poky/documentation/ref-manual/faq.rst +++ b/poky/documentation/ref-manual/faq.rst @@ -54,13 +54,10 @@ Yocto Project is fairly straightforward. **Q:** Are there any products built using the OpenEmbedded build system? -**A:** The software running on the `Vernier -LabQuest <https://vernier.com/labquest/>`__ is built using the -OpenEmbedded build system. See the `Vernier -LabQuest <https://www.vernier.com/products/interfaces/labq/>`__ website -for more information. There are a number of pre-production devices using -the OpenEmbedded build system and the Yocto Project team announces them -as soon as they are released. +**A:** See :yocto_wiki:`Products that use the Yocto Project +</Project_Users#Products_that_use_the_Yocto_Project>` in the Yocto Project +Wiki. Don't hesitate to contribute to this page if you know other such +products. **Q:** What does the OpenEmbedded build system produce as output? @@ -437,7 +434,7 @@ practice very effective. **Q:** The files provided by my ``*-native`` recipe do not appear to be available to other recipes. Files are missing from the native sysroot, my recipe is installing to the wrong place, or I am getting permissions -errors during the do_install task in my recipe! What is wrong? +errors during the :ref:`ref-tasks-install` task in my recipe! What is wrong? **A:** This situation results when a build system does not recognize the environment variables supplied to it by :term:`BitBake`. The diff --git a/poky/documentation/ref-manual/images.rst b/poky/documentation/ref-manual/images.rst index 31fb567687..4b771d0601 100644 --- a/poky/documentation/ref-manual/images.rst +++ b/poky/documentation/ref-manual/images.rst @@ -78,11 +78,11 @@ Following is a list of supported recipes: libraries you can use in a host development environment. - ``core-image-minimal-initramfs``: A ``core-image-minimal`` image that - has the Minimal RAM-based Initial Root Filesystem (initramfs) as part + has the Minimal RAM-based Initial Root Filesystem (:term:`Initramfs`) as part of the kernel, which allows the system to find the first "init" program more efficiently. See the :term:`PACKAGE_INSTALL` variable for - additional information helpful when working with initramfs images. + additional information helpful when working with :term:`Initramfs` images. - ``core-image-minimal-mtdutils``: A ``core-image-minimal`` image that has support for the Minimal MTD Utilities, which let the user @@ -121,7 +121,7 @@ Following is a list of supported recipes: section in the Yocto Project Development Tasks Manual. - ``core-image-testmaster-initramfs``: A RAM-based Initial Root - Filesystem (initramfs) image tailored for use with the + Filesystem (:term:`Initramfs`) image tailored for use with the ``core-image-testmaster`` image. - ``core-image-weston``: A very basic Wayland image with a terminal. diff --git a/poky/documentation/ref-manual/qa-checks.rst b/poky/documentation/ref-manual/qa-checks.rst index fbab1dc92e..9455bec3fd 100644 --- a/poky/documentation/ref-manual/qa-checks.rst +++ b/poky/documentation/ref-manual/qa-checks.rst @@ -162,7 +162,7 @@ Errors and Warnings normally expected to be empty (such as ``/tmp``). These files may be more appropriately installed to a different location, or perhaps alternatively not installed at all, usually by updating the - ``do_install`` task/function. + :ref:`ref-tasks-install` task/function. .. _qa-check-arch: @@ -536,7 +536,7 @@ Errors and Warnings in (e.g. ``FILES:${``\ :term:`PN`\ ``}`` for the main package). - - Delete the files at the end of the ``do_install`` task if the + - Delete the files at the end of the :ref:`ref-tasks-install` task if the files are not needed in any package. @@ -582,7 +582,7 @@ Errors and Warnings ``${datadir}/mime/packages``) and yet does not inherit the mime class which will ensure that these get properly installed. Either add ``inherit mime`` to the recipe or remove the files at the - ``do_install`` step if they are not needed. + :ref:`ref-tasks-install` step if they are not needed. .. _qa-check-mime-xdg: @@ -592,7 +592,7 @@ Errors and Warnings The specified package contains a .desktop file with a 'MimeType' key present, but does not inherit the mime-xdg class that is required in order for that to be activated. Either add ``inherit mime`` to the - recipe or remove the files at the ``do_install`` step if they are not + recipe or remove the files at the :ref:`ref-tasks-install` step if they are not needed. @@ -667,8 +667,8 @@ Errors and Warnings If ``usrmerge`` is in :term:`DISTRO_FEATURES`, this check will ensure that no package installs files to root (``/bin``, ``/sbin``, ``/lib``, ``/lib64``) directories. If you are seeing this - message, it indicates that the ``do_install`` step (or perhaps the build process that - ``do_install`` is calling into, e.g. ``make install`` is using hardcoded paths instead + message, it indicates that the :ref:`ref-tasks-install` step (or perhaps the build process that + :ref:`ref-tasks-install` is calling into, e.g. ``make install`` is using hardcoded paths instead of the variables set up for this (``bindir``, ``sbindir``, etc.), and should be changed so that it does. @@ -677,7 +677,7 @@ Errors and Warnings - ``Fuzz detected: <patch output> [patch-fuzz]`` - This check looks for evidence of "fuzz" when applying patches within the ``do_patch`` + This check looks for evidence of "fuzz" when applying patches within the :ref:`ref-tasks-patch` task. Patch fuzz is a situation when the ``patch`` tool ignores some of the context lines in order to apply the patch. Consider this example: diff --git a/poky/documentation/ref-manual/structure.rst b/poky/documentation/ref-manual/structure.rst index 429f81e14c..533745b370 100644 --- a/poky/documentation/ref-manual/structure.rst +++ b/poky/documentation/ref-manual/structure.rst @@ -630,7 +630,7 @@ Here are key subdirectories within each recipe work directory: split into individual packages. - ``${WORKDIR}/packages-split``: Contains the output of the - ``do_package`` task after the output has been split into individual + :ref:`ref-tasks-package` task after the output has been split into individual packages. There are subdirectories for each individual package created by the recipe. diff --git a/poky/documentation/ref-manual/system-requirements.rst b/poky/documentation/ref-manual/system-requirements.rst index 62da1bfaaa..acc97c9d08 100644 --- a/poky/documentation/ref-manual/system-requirements.rst +++ b/poky/documentation/ref-manual/system-requirements.rst @@ -41,6 +41,8 @@ distributions: - Ubuntu 20.04 (LTS) +- Ubuntu 22.04 (LTS) + - Fedora 34 - Fedora 35 diff --git a/poky/documentation/ref-manual/tasks.rst b/poky/documentation/ref-manual/tasks.rst index cb08a75c90..d4408d1422 100644 --- a/poky/documentation/ref-manual/tasks.rst +++ b/poky/documentation/ref-manual/tasks.rst @@ -36,7 +36,7 @@ directory set to ``${``\ :term:`B`\ ``}``. The default behavior of this task is to run the ``oe_runmake`` function if a makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found. -If no such file is found, the ``do_compile`` task does nothing. +If no such file is found, the :ref:`ref-tasks-compile` task does nothing. .. _ref-tasks-compile_ptest_base: @@ -58,7 +58,7 @@ The default behavior of this task is to run ``oe_runmake clean`` if a makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found and :term:`CLEANBROKEN` is not set to "1". If no such file is found or the :term:`CLEANBROKEN` variable is set to "1", the -``do_configure`` task does nothing. +:ref:`ref-tasks-configure` task does nothing. .. _ref-tasks-configure_ptest_base: @@ -81,7 +81,7 @@ Recipes implementing this task should inherit the :ref:`deploy <ref-classes-deploy>` class and should write the output to ``${``\ :term:`DEPLOYDIR`\ ``}``, which is not to be confused with ``${DEPLOY_DIR}``. The :ref:`deploy <ref-classes-deploy>` class sets up -``do_deploy`` as a shared state (sstate) task that can be accelerated +:ref:`ref-tasks-deploy` as a shared state (sstate) task that can be accelerated through sstate use. The sstate mechanism takes care of copying the output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``. @@ -90,14 +90,14 @@ output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``. Do not write the output directly to ``${DEPLOY_DIR_IMAGE}``, as this causes the sstate mechanism to malfunction. -The ``do_deploy`` task is not added as a task by default and +The :ref:`ref-tasks-deploy` task is not added as a task by default and consequently needs to be added manually. If you want the task to run after :ref:`ref-tasks-compile`, you can add it by doing the following:: addtask deploy after do_compile -Adding ``do_deploy`` after other tasks works the same way. +Adding :ref:`ref-tasks-deploy` after other tasks works the same way. .. note:: @@ -110,7 +110,7 @@ Adding ``do_deploy`` after other tasks works the same way. See the ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" section in the BitBake User Manual for more information. -If the ``do_deploy`` task re-executes, any previous output is removed +If the :ref:`ref-tasks-deploy` task re-executes, any previous output is removed (i.e. "cleaned"). .. _ref-tasks-fetch: @@ -128,15 +128,15 @@ module. ``do_image`` ------------ -Starts the image generation process. The ``do_image`` task runs after +Starts the image generation process. The :ref:`ref-tasks-image` task runs after the OpenEmbedded build system has run the :ref:`ref-tasks-rootfs` task during which packages are identified for installation into the image and the root filesystem is created, complete with post-processing. -The ``do_image`` task performs pre-processing on the image through the +The :ref:`ref-tasks-image` task performs pre-processing on the image through the :term:`IMAGE_PREPROCESS_COMMAND` and -dynamically generates supporting ``do_image_*`` tasks as needed. +dynamically generates supporting :ref:`do_image_* <ref-tasks-image>` tasks as needed. For more information on image creation, see the ":ref:`overview-manual/concepts:image generation`" section in the Yocto Project Overview and Concepts Manual. @@ -146,13 +146,13 @@ section in the Yocto Project Overview and Concepts Manual. ``do_image_complete`` --------------------- -Completes the image generation process. The ``do_image_complete`` task +Completes the image generation process. The :ref:`do_image_complete <ref-tasks-image-complete>` task runs after the OpenEmbedded build system has run the :ref:`ref-tasks-image` task during which image -pre-processing occurs and through dynamically generated ``do_image_*`` +pre-processing occurs and through dynamically generated :ref:`do_image_* <ref-tasks-image>` tasks the image is constructed. -The ``do_image_complete`` task performs post-processing on the image +The :ref:`do_image_complete <ref-tasks-image-complete>` task performs post-processing on the image through the :term:`IMAGE_POSTPROCESS_COMMAND`. @@ -168,9 +168,9 @@ section in the Yocto Project Overview and Concepts Manual. Copies files that are to be packaged into the holding area ``${``\ :term:`D`\ ``}``. This task runs with the current working directory set to ``${``\ :term:`B`\ ``}``, which is the -compilation directory. The ``do_install`` task, as well as other tasks +compilation directory. The :ref:`ref-tasks-install` task, as well as other tasks that either directly or indirectly depend on the installed files (e.g. -:ref:`ref-tasks-package`, ``do_package_write_*``, and +:ref:`ref-tasks-package`, :ref:`do_package_write_* <ref-tasks-package_write_deb>`, and :ref:`ref-tasks-rootfs`), run under :ref:`fakeroot <overview-manual/concepts:fakeroot and pseudo>`. @@ -212,7 +212,7 @@ based on available packages and files. This task makes use of the :term:`PACKAGES` and :term:`FILES` variables. -The ``do_package`` task, in conjunction with the +The :ref:`ref-tasks-package` task, in conjunction with the :ref:`ref-tasks-packagedata` task, also saves some important package metadata. For additional information, see the :term:`PKGDESTWORK` variable and the @@ -327,7 +327,7 @@ file as a patch file:: " Conversely, if you have a file whose file type is ``.patch`` or ``.diff`` -and you want to exclude it so that the ``do_patch`` task does not apply +and you want to exclude it so that the :ref:`ref-tasks-patch` task does not apply it during the patch phase, you can use the "apply=no" parameter with the :term:`SRC_URI` statement:: @@ -392,7 +392,7 @@ For information on what directories are copied by default, see the these variables inside your recipe if you need to make additional (or fewer) directories available to other recipes at build time. -The ``do_populate_sysroot`` task is a shared state (sstate) task, which +The :ref:`ref-tasks-populate_sysroot` task is a shared state (sstate) task, which means that the task can be accelerated through sstate use. Realize also that if the task is re-executed, any previous output is removed (i.e. "cleaned"). @@ -447,7 +447,7 @@ Validates the :term:`SRC_URI` value. ------------ Removes all output files for a target from the -:ref:`ref-tasks-unpack` task forward (i.e. ``do_unpack``, +:ref:`ref-tasks-unpack` task forward (i.e. :ref:`ref-tasks-unpack`, :ref:`ref-tasks-configure`, :ref:`ref-tasks-compile`, :ref:`ref-tasks-install`, and @@ -473,7 +473,7 @@ use the :ref:`ref-tasks-cleansstate` task instead Removes all output files, shared state (:ref:`sstate <overview-manual/concepts:shared state cache>`) cache, and downloaded source files for a target (i.e. the contents of -:term:`DL_DIR`). Essentially, the ``do_cleanall`` task is +:term:`DL_DIR`). Essentially, the :ref:`ref-tasks-cleanall` task is identical to the :ref:`ref-tasks-cleansstate` task with the added removal of downloaded source files. @@ -481,7 +481,7 @@ You can run this task using BitBake as follows:: $ bitbake -c cleanall recipe -Typically, you would not normally use the ``cleanall`` task. Do so only +Typically, you would not normally use the :ref:`ref-tasks-cleanall` task. Do so only if you want to start fresh with the :ref:`ref-tasks-fetch` task. @@ -492,7 +492,7 @@ task. Removes all output files and shared state (:ref:`sstate <overview-manual/concepts:shared state cache>`) cache for a -target. Essentially, the ``do_cleansstate`` task is identical to the +target. Essentially, the :ref:`ref-tasks-cleansstate` task is identical to the :ref:`ref-tasks-clean` task with the added removal of shared state (:ref:`sstate <overview-manual/concepts:shared state cache>`) cache. @@ -501,13 +501,13 @@ You can run this task using BitBake as follows:: $ bitbake -c cleansstate recipe -When you run the ``do_cleansstate`` task, the OpenEmbedded build system +When you run the :ref:`ref-tasks-cleansstate` task, the OpenEmbedded build system no longer uses any sstate. Consequently, building the recipe from scratch is guaranteed. .. note:: - The ``do_cleansstate`` task cannot remove sstate from a remote sstate + The :ref:`ref-tasks-cleansstate` task cannot remove sstate from a remote sstate mirror. If you need to build a target from scratch using remote mirrors, use the "-f" option as follows:: @@ -575,10 +575,8 @@ information on live image types. ``do_bundle_initramfs`` ----------------------- -Combines an initial RAM disk (initramfs) image and kernel together to -form a single image. The -:term:`CONFIG_INITRAMFS_SOURCE` variable -has some more information about these types of images. +Combines an :term:`Initramfs` image and kernel together to +form a single image. .. _ref-tasks-rootfs: @@ -657,7 +655,7 @@ section in the Yocto Project Linux Kernel Development Manual. Converts the newly unpacked kernel source into a form with which the OpenEmbedded build system can work. Because the kernel source can be -fetched in several different ways, the ``do_kernel_checkout`` task makes +fetched in several different ways, the :ref:`ref-tasks-kernel_checkout` task makes sure that subsequent tasks are given a clean working tree copy of the kernel with the correct branches checked out. @@ -668,7 +666,7 @@ kernel with the correct branches checked out. Validates the configuration produced by the :ref:`ref-tasks-kernel_menuconfig` task. The -``do_kernel_configcheck`` task produces warnings when a requested +:ref:`ref-tasks-kernel_configcheck` task produces warnings when a requested configuration does not appear in the final ``.config`` file or when you override a policy configuration in a hardware configuration fragment. You can run this task explicitly and view the output by using the @@ -686,7 +684,7 @@ section in the Yocto Project Linux Kernel Development Manual. ---------------------- After the kernel is patched by the :ref:`ref-tasks-patch` -task, the ``do_kernel_configme`` task assembles and merges all the +task, the :ref:`ref-tasks-kernel_configme` task assembles and merges all the kernel config fragments into a merged configuration that can then be passed to the kernel configuration phase proper. This is also the time during which user-specified defconfigs are applied if present, and where @@ -719,7 +717,7 @@ information on this configuration tool. Collects all the features required for a given kernel build, whether the features come from :term:`SRC_URI` or from Git -repositories. After collection, the ``do_kernel_metadata`` task +repositories. After collection, the :ref:`ref-tasks-kernel_metadata` task processes the features into a series of config fragments and patches, which can then be applied by subsequent tasks such as :ref:`ref-tasks-patch` and @@ -791,4 +789,4 @@ After the kernel is unpacked but before it is patched, this task makes sure that the machine and metadata branches as specified by the :term:`SRCREV` variables actually exist on the specified branches. Otherwise, if :term:`AUTOREV` is not being used, the -``do_validate_branches`` task fails during the build. +:ref:`ref-tasks-validate_branches` task fails during the build. diff --git a/poky/documentation/ref-manual/variables.rst b/poky/documentation/ref-manual/variables.rst index 2971654531..1685a26776 100644 --- a/poky/documentation/ref-manual/variables.rst +++ b/poky/documentation/ref-manual/variables.rst @@ -1242,24 +1242,24 @@ system and gives an overview of their function and contents. :term:`Source Directory`. :term:`CONFIG_INITRAMFS_SOURCE` - Identifies the initial RAM filesystem (initramfs) source files. The + Identifies the initial RAM filesystem (:term:`Initramfs`) source files. The OpenEmbedded build system receives and uses this kernel Kconfig variable as an environment variable. By default, the variable is set to null (""). The :term:`CONFIG_INITRAMFS_SOURCE` can be either a single cpio archive with a ``.cpio`` suffix or a space-separated list of directories and - files for building the initramfs image. A cpio archive should contain - a filesystem archive to be used as an initramfs image. Directories - should contain a filesystem layout to be included in the initramfs + files for building the :term:`Initramfs` image. A cpio archive should contain + a filesystem archive to be used as an :term:`Initramfs` image. Directories + should contain a filesystem layout to be included in the :term:`Initramfs` image. Files should contain entries according to the format described by the ``usr/gen_init_cpio`` program in the kernel tree. - If you specify multiple directories and files, the initramfs image + If you specify multiple directories and files, the :term:`Initramfs` image will be the aggregate of all of them. - For information on creating an initramfs, see the - ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section + For information on creating an :term:`Initramfs`, see the + ":ref:`dev-manual/common-tasks:building an initial ram filesystem (Initramfs) image`" section in the Yocto Project Development Tasks Manual. :term:`CONFIG_SITE` @@ -1620,7 +1620,7 @@ system and gives an overview of their function and contents. 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 ``do_configure`` depend on + 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>`\ ``]`` @@ -3182,10 +3182,10 @@ system and gives an overview of their function and contents. image, do not use the :term:`IMAGE_INSTALL` variable to specify packages for installation. Instead, use the :term:`PACKAGE_INSTALL` variable, which - allows the initial RAM filesystem (initramfs) recipe to use a + allows the initial RAM filesystem (:term:`Initramfs`) recipe to use a fixed set of packages and not be affected by :term:`IMAGE_INSTALL`. - For information on creating an initramfs, see the - ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" + For information on creating an :term:`Initramfs`, see the + ":ref:`dev-manual/common-tasks:building an initial ram filesystem (Initramfs) image`" section in the Yocto Project Development Tasks Manual. - Using :term:`IMAGE_INSTALL` with the @@ -3265,7 +3265,7 @@ system and gives an overview of their function and contents. to distinguish the image file from other files created during image building; however if this suffix is redundant or not desired you can clear the value of this variable (set the value to ""). For example, - this is typically cleared in initramfs image recipes. + this is typically cleared in :term:`Initramfs` image recipes. :term:`IMAGE_OVERHEAD_FACTOR` Defines a multiplier that the build system applies to the initial @@ -3632,37 +3632,79 @@ system and gives an overview of their function and contents. even if the toolchain's binaries are strippable, there are other files needed for the build that are not strippable. + :term:`Initramfs` + An Initial RAM Filesystem (:term:`Initramfs`) is an optionally compressed + `cpio <https://en.wikipedia.org/wiki/Cpio>`__ archive which is extracted + by the Linux kernel into RAM in a special `tmpfs <https://en.wikipedia.org/wiki/Tmpfs>`__ + instance, used as the initial root filesystem. + + This is a replacement for the legacy init RAM disk ("initrd") + technique, booting on an emulated block device in RAM, but being less + efficient because of the overhead of going through a filesystem and + having to duplicate accessed file contents in the file cache in RAM, + as for any block device. + + .. note: + + As far as bootloaders are concerned, :term:`Initramfs` and "initrd" + images are still copied to RAM in the same way. That's why most + most bootloaders refer to :term:`Initramfs` images as "initrd" + or "init RAM disk". + + This kind of mechanism is typically used for two reasons: + + - For booting the same kernel binary on multiple systems requiring + different device drivers. The Initramfs image is then customized + for each type of system, to include the specific kernel modules + necessary to access the final root filesystem. This technique + is used on all GNU / Linux distributions for desktops and servers. + + - For booting faster. As the root filesystem is extracted into RAM, + accessing the first user-space applications is very fast, compared + to having to initialize a block device, to access multiple blocks + from it, and to go through a filesystem having its own overhead. + For example, this allows to display a splashscreen very early, + and to later take care of mounting the final root filesystem and + loading less time-critical kernel drivers. + + This cpio archive can either be loaded to RAM by the bootloader, + or be included in the kernel binary. + + For information on creating and using an :term:`Initramfs`, see the + ":ref:`dev-manual/common-tasks:building an initial ram filesystem (Initramfs) image`" + section in the Yocto Project Development Tasks Manual. + :term:`INITRAMFS_DEPLOY_DIR_IMAGE` - Indicates the deploy directory used by ``do_bundle_initramfs`` where the + Indicates the deploy directory used by :ref:`ref-tasks-bundle_initramfs` where the :term:`INITRAMFS_IMAGE` will be fetched from. This variable is set by default to ``${DEPLOY_DIR_IMAGE}`` in the :ref:`kernel <ref-classes-kernel>` class and it's only meant to be changed - when building an initramfs image from a separate multiconfig via :term:`INITRAMFS_MULTICONFIG`. + when building an :term:`Initramfs` image from a separate multiconfig via :term:`INITRAMFS_MULTICONFIG`. :term:`INITRAMFS_FSTYPES` Defines the format for the output image of an initial RAM filesystem - (initramfs), which is used during boot. Supported formats are the + (:term:`Initramfs`), which is used during boot. Supported formats are the same as those supported by the :term:`IMAGE_FSTYPES` variable. The default value of this variable, which is set in the ``meta/conf/bitbake.conf`` configuration file in the :term:`Source Directory`, is "cpio.gz". The Linux kernel's - initramfs mechanism, as opposed to the initial RAM filesystem + :term:`Initramfs` mechanism, as opposed to the initial RAM filesystem `initrd <https://en.wikipedia.org/wiki/Initrd>`__ mechanism, expects an optionally compressed cpio archive. :term:`INITRAMFS_IMAGE` Specifies the :term:`PROVIDES` name of an image - recipe that is used to build an initial RAM filesystem (initramfs) + recipe that is used to build an initial RAM filesystem (:term:`Initramfs`) image. In other words, the :term:`INITRAMFS_IMAGE` variable causes an additional recipe to be built as a dependency to whatever root filesystem recipe you might be using (e.g. ``core-image-sato``). The - initramfs image recipe you provide should set + :term:`Initramfs` image recipe you provide should set :term:`IMAGE_FSTYPES` to :term:`INITRAMFS_FSTYPES`. - An initramfs image provides a temporary root filesystem used for + An :term:`Initramfs` image provides a temporary root filesystem used for early system initialization (e.g. loading of modules needed to locate and mount the "real" root filesystem). @@ -3670,8 +3712,8 @@ system and gives an overview of their function and contents. See the ``meta/recipes-core/images/core-image-minimal-initramfs.bb`` recipe in the :term:`Source Directory` - for an example initramfs recipe. To select this sample recipe as - the one built to provide the initramfs image, set :term:`INITRAMFS_IMAGE` + for an example :term:`Initramfs` recipe. To select this sample recipe as + the one built to provide the :term:`Initramfs` image, set :term:`INITRAMFS_IMAGE` to "core-image-minimal-initramfs". You can also find more information by referencing the @@ -3681,13 +3723,13 @@ system and gives an overview of their function and contents. class to see how to use the :term:`INITRAMFS_IMAGE` variable. If :term:`INITRAMFS_IMAGE` is empty, which is the default, then no - initramfs image is built. + :term:`Initramfs` image is built. For more information, you can also see the :term:`INITRAMFS_IMAGE_BUNDLE` variable, which allows the generated image to be bundled inside the - kernel image. Additionally, for information on creating an initramfs - image, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section + kernel image. Additionally, for information on creating an :term:`Initramfs` + image, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (Initramfs) image`" section in the Yocto Project Development Tasks Manual. :term:`INITRAMFS_IMAGE_BUNDLE` @@ -3696,32 +3738,32 @@ system and gives an overview of their function and contents. extra pass (:ref:`ref-tasks-bundle_initramfs`) during kernel compilation in order to build a single binary that contains - both the kernel image and the initial RAM filesystem (initramfs) + both the kernel image and the initial RAM filesystem (:term:`Initramfs`) image. This makes use of the :term:`CONFIG_INITRAMFS_SOURCE` kernel feature. .. note:: - Bundling the initramfs with the kernel conflates the code in the - initramfs with the GPLv2 licensed Linux kernel binary. Thus only GPLv2 - compatible software may be part of a bundled initramfs. + Bundling the :term:`Initramfs` with the kernel conflates the code in the + :term:`Initramfs` with the GPLv2 licensed Linux kernel binary. Thus only GPLv2 + compatible software may be part of a bundled :term:`Initramfs`. .. note:: - Using an extra compilation pass to bundle the initramfs avoids a - circular dependency between the kernel recipe and the initramfs - recipe should the initramfs include kernel modules. Should that be - the case, the initramfs recipe depends on the kernel for the - kernel modules, and the kernel depends on the initramfs recipe - since the initramfs is bundled inside the kernel image. + Using an extra compilation pass to bundle the :term:`Initramfs` avoids a + circular dependency between the kernel recipe and the :term:`Initramfs` + recipe should the :term:`Initramfs` include kernel modules. Should that be + the case, the :term:`Initramfs` recipe depends on the kernel for the + kernel modules, and the kernel depends on the :term:`Initramfs` recipe + since the :term:`Initramfs` is bundled inside the kernel image. The combined binary is deposited into the ``tmp/deploy`` directory, which is part of the :term:`Build Directory`. Setting the variable to "1" in a configuration file causes the OpenEmbedded build system to generate a kernel image with the - initramfs specified in :term:`INITRAMFS_IMAGE` bundled within:: + :term:`Initramfs` specified in :term:`INITRAMFS_IMAGE` bundled within:: INITRAMFS_IMAGE_BUNDLE = "1" @@ -3739,7 +3781,7 @@ system and gives an overview of their function and contents. See the :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/templates/default/local.conf.sample.extended>` file for additional information. Also, for information on creating an - initramfs, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section + :term:`Initramfs`, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (Initramfs) image`" section in the Yocto Project Development Tasks Manual. :term:`INITRAMFS_LINK_NAME` @@ -3764,7 +3806,7 @@ system and gives an overview of their function and contents. This allows the kernel to bundle an :term:`INITRAMFS_IMAGE` coming from a separate multiconfig, this is meant to be used in addition to :term:`INITRAMFS_DEPLOY_DIR_IMAGE`. - For more information on how to bundle an initramfs image from a separate + For more information on how to bundle an :term:`Initramfs` image from a separate multiconfig see the ":ref:`dev-manual/common-tasks:Bundling an Initramfs Image From a Separate Multiconfig`" section in the Yocto Project Development Tasks Manual. @@ -4240,7 +4282,7 @@ system and gives an overview of their function and contents. :term:`KERNELDEPMODDEPEND` does not control whether or not that data exists, but simply whether or not it is used. If you do not need to use the data, set the :term:`KERNELDEPMODDEPEND` variable in your - ``initramfs`` recipe. Setting the variable there when the data is not + :term:`Initramfs` recipe. Setting the variable there when the data is not needed avoids a potential dependency loop. :term:`KFEATURE_DESCRIPTION` @@ -5395,9 +5437,9 @@ system and gives an overview of their function and contents. :term:`IMAGE_INSTALL` variable to specify packages for installation. The exception to this is when working with the :ref:`core-image-minimal-initramfs <ref-manual/images:images>` - image. When working with an initial RAM filesystem (initramfs) image, + image. When working with an initial RAM filesystem (:term:`Initramfs`) image, use the :term:`PACKAGE_INSTALL` variable. For information on creating an - initramfs, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section + :term:`Initramfs`, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (Initramfs) image`" section in the Yocto Project Development Tasks Manual. :term:`PACKAGE_INSTALL_ATTEMPTONLY` @@ -5521,7 +5563,7 @@ system and gives an overview of their function and contents. :ref:`cmake <ref-classes-cmake>` use :term:`PACKAGECONFIG_CONFARGS` to pass :term:`PACKAGECONFIG` options to ``configure`` and ``cmake``, respectively. If you are using :term:`PACKAGECONFIG` but not a class that - handles the ``do_configure`` task, then you need to use + handles the :ref:`ref-tasks-configure` task, then you need to use :term:`PACKAGECONFIG_CONFARGS` appropriately. :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` @@ -5603,7 +5645,7 @@ system and gives an overview of their function and contents. .. note:: If the software being built experiences dependency issues during - the ``do_compile`` task that result in race conditions, you can clear + the :ref:`ref-tasks-compile` task that result in race conditions, you can clear the :term:`PARALLEL_MAKE` variable within the recipe as a workaround. For information on addressing race conditions, see the ":ref:`dev-manual/common-tasks:debugging parallel make races`" @@ -5633,7 +5675,7 @@ system and gives an overview of their function and contents. way to ensure this is to use the ``oe_runmake`` function. If the software being built experiences dependency issues during - the ``do_install`` task that result in race conditions, you can + the :ref:`ref-tasks-install` task that result in race conditions, you can clear the :term:`PARALLEL_MAKEINST` variable within the recipe as a workaround. For information on addressing race conditions, see the ":ref:`dev-manual/common-tasks:debugging parallel make races`" @@ -6200,7 +6242,7 @@ system and gives an overview of their function and contents. The practical effect of the above :term:`RDEPENDS` assignment is that ``bar`` and ``baz`` will be declared as dependencies inside the package ``foo`` when it is written out by one of the - :ref:`do_package_write_\* <ref-tasks-package_write_deb>` tasks. + :ref:`do_package_write_* <ref-tasks-package_write_deb>` tasks. Exactly how this is done depends on which package format is used, which is determined by :term:`PACKAGE_CLASSES`. When the @@ -6212,7 +6254,7 @@ system and gives an overview of their function and contents. added. This dependency is from the recipe's :ref:`ref-tasks-build` (not to be confused with :ref:`ref-tasks-compile`) task to the - ``do_package_write_*`` task of the recipes that build ``bar`` and + :ref:`do_package_write_* <ref-tasks-package_write_deb>` task of the recipes that build ``bar`` and ``baz``. The names of the packages you list within :term:`RDEPENDS` must be the @@ -6709,10 +6751,10 @@ system and gives an overview of their function and contents. A list of shared state tasks added to the extensible SDK. By default, the following tasks are added: - - do_populate_lic - - do_package_qa - - do_populate_sysroot - - do_deploy + - :ref:`ref-tasks-populate_lic` + - :ref:`ref-tasks-package_qa` + - :ref:`ref-tasks-populate_sysroot` + - :ref:`ref-tasks-deploy` Despite the default value of "" for the :term:`SDK_RECRDEP_TASKS` variable, the above four tasks are always added @@ -7382,7 +7424,7 @@ system and gives an overview of their function and contents. For most recipes, this sysroot is the one in which that recipe's :ref:`ref-tasks-populate_sysroot` task copies files. Exceptions include ``-native`` recipes, where the - ``do_populate_sysroot`` task instead uses + :ref:`ref-tasks-populate_sysroot` task instead uses :term:`STAGING_DIR_NATIVE`. Depending on the type of recipe and the build target, :term:`STAGING_DIR_HOST` can have the following values: diff --git a/poky/documentation/sdk-manual/extensible.rst b/poky/documentation/sdk-manual/extensible.rst index 0df6519b8e..09b7169811 100644 --- a/poky/documentation/sdk-manual/extensible.rst +++ b/poky/documentation/sdk-manual/extensible.rst @@ -1112,7 +1112,7 @@ links created within the source tree: ``${``\ :term:`D`\ ``}``. - ``sysroot-destdir/``: Contains a subset of files installed within - ``do_install`` that have been put into the shared sysroot. For + :ref:`ref-tasks-install` that have been put into the shared sysroot. For more information, see the ":ref:`dev-manual/common-tasks:sharing files between recipes`" section. |