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/documentation/ref-manual | |
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/documentation/ref-manual')
-rw-r--r-- | poky/documentation/ref-manual/classes.rst | 22 | ||||
-rw-r--r-- | poky/documentation/ref-manual/faq.rst | 13 | ||||
-rw-r--r-- | poky/documentation/ref-manual/images.rst | 6 | ||||
-rw-r--r-- | poky/documentation/ref-manual/qa-checks.rst | 14 | ||||
-rw-r--r-- | poky/documentation/ref-manual/structure.rst | 2 | ||||
-rw-r--r-- | poky/documentation/ref-manual/system-requirements.rst | 2 | ||||
-rw-r--r-- | poky/documentation/ref-manual/tasks.rst | 62 | ||||
-rw-r--r-- | poky/documentation/ref-manual/variables.rst | 142 |
8 files changed, 151 insertions, 112 deletions
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: |