diff options
Diffstat (limited to 'poky/documentation/ref-manual')
| -rw-r--r-- | poky/documentation/ref-manual/classes.rst | 10 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/devtool-reference.rst | 4 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/faq.rst | 6 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/features.rst | 2 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/images.rst | 2 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/release-process.rst | 8 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/structure.rst | 2 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/system-requirements.rst | 10 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/tasks.rst | 38 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/terms.rst | 4 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/variables.rst | 66 |
11 files changed, 114 insertions, 38 deletions
diff --git a/poky/documentation/ref-manual/classes.rst b/poky/documentation/ref-manual/classes.rst index 81dab1f4b3..7b4ce2c67d 100644 --- a/poky/documentation/ref-manual/classes.rst +++ b/poky/documentation/ref-manual/classes.rst @@ -392,7 +392,7 @@ and BusyBox. It could have been called "kconfig" too. ``compress_doc`` ================ -Enables compression for man pages and info pages. This class is intended +Enables compression for manual and info pages. This class is intended to be inherited globally. The default compression mechanism is gz (gzip) but you can select an alternative mechanism by setting the :term:`DOC_COMPRESS` variable. @@ -664,7 +664,7 @@ information about using :ref:`ref-classes-devshell`. The :ref:`ref-classes-devupstream` class uses :term:`BBCLASSEXTEND` to add a variant of the recipe that fetches from an alternative URI (e.g. Git) instead of a -tarball. Following is an example:: +tarball. Here is an example:: BBCLASSEXTEND = "devupstream:target" SRC_URI:class-devupstream = "git://git.example.com/example;branch=main" @@ -1217,8 +1217,8 @@ Please keep in mind that the QA checks are meant to detect real or potential problems in the packaged output. So exercise caution when disabling these checks. -Here are the tests you can list with the :term:`WARN_QA` and -:term:`ERROR_QA` variables: +The tests you can list with the :term:`WARN_QA` and +:term:`ERROR_QA` variables are: - ``already-stripped:`` Checks that produced binaries have not already been stripped prior to the build system extracting debug @@ -3217,7 +3217,7 @@ information. The :ref:`ref-classes-uboot-sign` class provides support for U-Boot verified boot. It is intended to be inherited from U-Boot recipes. -Here are variables used by this class: +The variables used by this class are: - :term:`SPL_MKIMAGE_DTCOPTS`: DTC options for U-Boot ``mkimage`` when building the FIT image. diff --git a/poky/documentation/ref-manual/devtool-reference.rst b/poky/documentation/ref-manual/devtool-reference.rst index e167f58092..9319addc3c 100644 --- a/poky/documentation/ref-manual/devtool-reference.rst +++ b/poky/documentation/ref-manual/devtool-reference.rst @@ -378,7 +378,7 @@ command:: Unless you provide a specific recipe name on the command line, the command checks all recipes in all configured layers. -Following is a partial example table that reports on all the recipes:: +Here is a partial example table that reports on all the recipes:: $ devtool check-upgrade-status ... @@ -598,7 +598,7 @@ The ``devtool status`` command has no command-line options:: $ devtool status -Following is sample output after using +Here is sample output after using :ref:`devtool add <ref-manual/devtool-reference:adding a new recipe to the workspace layer>` to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory:: diff --git a/poky/documentation/ref-manual/faq.rst b/poky/documentation/ref-manual/faq.rst index a3a15506c3..bab284bbfd 100644 --- a/poky/documentation/ref-manual/faq.rst +++ b/poky/documentation/ref-manual/faq.rst @@ -90,7 +90,7 @@ HTTPS requests and direct them to the ``http://`` sources mirror. You can use ``file://`` URLs to point to local directories or network shares as well. -Here are other options:: +Another option is to set:: BB_NO_NETWORK = "1" @@ -106,7 +106,7 @@ This statement limits the build system to pulling source from the :term:`PREMIRRORS` only. Again, this technique is useful for reproducing builds. -Here is another technique:: +Here is yet another technique:: BB_GENERATE_MIRROR_TARBALLS = "1" @@ -135,7 +135,7 @@ Most source fetching by the OpenEmbedded build system is done by single user or can be in ``/usr/local/etc/wgetrc`` as a global user file. -Following is the applicable code for setting various proxy types in the +Here is the applicable code for setting various proxy types in the ``.wgetrc`` file. By default, these settings are disabled with comments. To use them, remove the comments:: diff --git a/poky/documentation/ref-manual/features.rst b/poky/documentation/ref-manual/features.rst index dd14339bc2..96e79d608a 100644 --- a/poky/documentation/ref-manual/features.rst +++ b/poky/documentation/ref-manual/features.rst @@ -268,7 +268,7 @@ you can add several different predefined packages such as development utilities or packages with debug information needed to investigate application problems or profile applications. -Here are the image features available for all images: +The image features available for all images are: - *allow-empty-password:* Allows Dropbear and OpenSSH to accept logins from accounts having an empty password string. diff --git a/poky/documentation/ref-manual/images.rst b/poky/documentation/ref-manual/images.rst index 0f6d6bdb3f..c45f9104a9 100644 --- a/poky/documentation/ref-manual/images.rst +++ b/poky/documentation/ref-manual/images.rst @@ -32,7 +32,7 @@ that contain image recipe files:: $ ls meta*/recipes*/images/*.bb -Following is a list of supported recipes: +Here is a list of supported recipes: - ``build-appliance-image``: An example virtual machine that contains all the pieces required to run builds using the build system as well diff --git a/poky/documentation/ref-manual/release-process.rst b/poky/documentation/ref-manual/release-process.rst index c861feaa9d..920794679d 100644 --- a/poky/documentation/ref-manual/release-process.rst +++ b/poky/documentation/ref-manual/release-process.rst @@ -14,7 +14,7 @@ Major and Minor Release Cadence The Yocto Project delivers major releases (e.g. &DISTRO;) using a six month cadence roughly timed each April and October of the year. -Following are examples of some major YP releases with their codenames +Here are examples of some major YP releases with their codenames also shown. See the ":ref:`ref-manual/release-process:major release codenames`" section for information on codenames used with major releases. @@ -29,8 +29,8 @@ major holidays in various geographies. The Yocto project delivers minor (point) releases on an unscheduled basis and are usually driven by the accumulation of enough significant -fixes or enhancements to the associated major release. Following are -some example past point releases: +fixes or enhancements to the associated major release. +Some example past point releases are: - 4.1.3 - 4.0.8 @@ -175,7 +175,7 @@ consists of the following pieces: piece of software. The test allows the packages to be run within a target image. -- ``oe-selftest``: Tests combination BitBake invocations. These tests +- ``oe-selftest``: Tests combinations of BitBake invocations. These tests operate outside the OpenEmbedded build system itself. The ``oe-selftest`` can run all tests by default or can run selected tests or test suites. diff --git a/poky/documentation/ref-manual/structure.rst b/poky/documentation/ref-manual/structure.rst index f1b11ad69b..acadd5efa3 100644 --- a/poky/documentation/ref-manual/structure.rst +++ b/poky/documentation/ref-manual/structure.rst @@ -537,7 +537,7 @@ recipe-specific :term:`WORKDIR` directories. Thus, the This directory holds information that BitBake uses for accounting purposes to track what tasks have run and when they have run. The directory is sub-divided by architecture, package name, and version. -Following is an example:: +Here is an example:: stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do diff --git a/poky/documentation/ref-manual/system-requirements.rst b/poky/documentation/ref-manual/system-requirements.rst index 9dee24a1fa..bcca42e36e 100644 --- a/poky/documentation/ref-manual/system-requirements.rst +++ b/poky/documentation/ref-manual/system-requirements.rst @@ -168,8 +168,8 @@ with a supported Ubuntu or Debian Linux distribution:: Here are the packages needed to build Project documentation manuals:: - $ sudo apt install make python3-pip inkscape texlive-latex-extra - &PIP3_HOST_PACKAGES_DOC; + $ sudo apt install git make inkscape texlive-latex-extra + $ sudo apt install sphinx python3-saneyaml python3-sphinx-rtd-theme Fedora Packages --------------- @@ -181,7 +181,7 @@ with a supported Fedora Linux distribution:: Here are the packages needed to build Project documentation manuals:: - $ sudo dnf install make python3-pip which inkscape texlive-fncychap + $ sudo dnf install git make python3-pip which inkscape texlive-fncychap &PIP3_HOST_PACKAGES_DOC; openSUSE Packages @@ -194,7 +194,7 @@ with a supported openSUSE distribution:: Here are the packages needed to build Project documentation manuals:: - $ sudo zypper install make python3-pip which inkscape texlive-fncychap + $ sudo zypper install git make python3-pip which inkscape texlive-fncychap &PIP3_HOST_PACKAGES_DOC; @@ -221,7 +221,7 @@ with a supported AlmaLinux distribution:: Here are the packages needed to build Project documentation manuals:: - $ sudo dnf install make python3-pip which inkscape texlive-fncychap + $ sudo dnf install git make python3-pip which inkscape texlive-fncychap &PIP3_HOST_PACKAGES_DOC; .. _system-requirements-buildtools: diff --git a/poky/documentation/ref-manual/tasks.rst b/poky/documentation/ref-manual/tasks.rst index 0db960b22f..c28cd7a94a 100644 --- a/poky/documentation/ref-manual/tasks.rst +++ b/poky/documentation/ref-manual/tasks.rst @@ -470,9 +470,29 @@ You can run this task using BitBake as follows:: $ bitbake -c cleanall recipe -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. +You should never use the :ref:`ref-tasks-cleanall` task in a normal +scenario. If you want to start fresh with the :ref:`ref-tasks-fetch` task, +use instead:: + + $ bitbake -f -c fetch recipe + +.. note:: + + The reason to prefer ``bitbake -f -c fetch`` is that the + :ref:`ref-tasks-cleanall` task would break in some cases, such as:: + + $ bitbake -c fetch recipe + $ bitbake -c cleanall recipe-native + $ bitbake -c unpack recipe + + because after step 1 there is a stamp file for the + :ref:`ref-tasks-fetch` task of ``recipe``, and it won't be removed at + step 2 because step 2 uses a different work directory. So the unpack task + at step 3 will try to extract the downloaded archive and fail as it has + been deleted in step 2. + + Note that this also applies to BitBake from concurrent processes when a + shared download directory (:term:`DL_DIR`) is setup. .. _ref-tasks-cleansstate: @@ -496,6 +516,18 @@ scratch is guaranteed. .. note:: + Using :ref:`ref-tasks-cleansstate` with a shared :term:`SSTATE_DIR` is + not recommended because it could trigger an error during the build of a + separate BitBake instance. This is because the builds check sstate "up + front" but download the files later, so it if is deleted in the + meantime, it will cause an error but not a total failure as it will + rebuild it. + + The reliable and preferred way to force a new build is to use ``bitbake + -f`` instead. + +.. note:: + 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:: diff --git a/poky/documentation/ref-manual/terms.rst b/poky/documentation/ref-manual/terms.rst index 31ddeae009..ad9c46c339 100644 --- a/poky/documentation/ref-manual/terms.rst +++ b/poky/documentation/ref-manual/terms.rst @@ -4,7 +4,7 @@ Yocto Project Terms ******************* -Following is a list of terms and definitions users new to the Yocto Project +Here is a list of terms and definitions users new to the Yocto Project development environment might find helpful. While some of these terms are universal, the list includes them just in case: @@ -67,7 +67,7 @@ universal, the list includes them just in case: :term:`TOPDIR` variable points to the :term:`Build Directory`. You have a lot of flexibility when creating the :term:`Build Directory`. - Following are some examples that show how to create the directory. The + Here are some examples that show how to create the directory. The examples assume your :term:`Source Directory` is named ``poky``: - Create the :term:`Build Directory` inside your Source Directory and let diff --git a/poky/documentation/ref-manual/variables.rst b/poky/documentation/ref-manual/variables.rst index 6f7d6ff01e..7ae61ad0ff 100644 --- a/poky/documentation/ref-manual/variables.rst +++ b/poky/documentation/ref-manual/variables.rst @@ -311,7 +311,7 @@ system and gives an overview of their function and contents. :term:`BB_ALLOWED_NETWORKS` Specifies a space-delimited list of hosts that the fetcher is allowed - to use to obtain the required source code. Following are + to use to obtain the required source code. Here are considerations surrounding this variable: - This host list is only used if :term:`BB_NO_NETWORK` is either not set @@ -2292,7 +2292,7 @@ system and gives an overview of their function and contents. :term:`DOC_COMPRESS` When inheriting the :ref:`ref-classes-compress_doc` class, this variable sets the compression policy used when the - OpenEmbedded build system compresses man pages and info pages. By + OpenEmbedded build system compresses manual and info pages. By default, the compression method used is gz (gzip). Other policies available are xz and bz2. @@ -3234,6 +3234,14 @@ system and gives an overview of their function and contents. GROUPADD_PARAM:${PN} = "-r netdev" + More than one group can be added by separating each set of different + groups' parameters with a semicolon. + + Here is an example adding multiple groups from the ``useradd-example.bb`` + file in the ``meta-skeleton`` layer:: + + GROUPADD_PARAM:${PN} = "-g 880 group1; -g 890 group2" + For information on the standard Linux shell command ``groupadd``, see https://linux.die.net/man/8/groupadd. @@ -6557,7 +6565,7 @@ system and gives an overview of their function and contents. The :term:`PREFERRED_PROVIDER` variable is set with the name (:term:`PN`) of the recipe you prefer to provide "virtual/kernel". - Following are more examples:: + Here are more examples:: PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" PREFERRED_PROVIDER_virtual/libgl ?= "mesa" @@ -6742,11 +6750,11 @@ system and gives an overview of their function and contents. .. note:: - A corresponding mechanism for virtual runtime dependencies - (packages) exists. However, the mechanism does not depend on any - special functionality beyond ordinary variable assignments. For - example, ``VIRTUAL-RUNTIME_dev_manager`` refers to the package of - the component that manages the ``/dev`` directory. + A corresponding mechanism for virtual runtime dependencies (packages) + exists. However, the mechanism does not depend on any special + functionality beyond ordinary variable assignments. For example, + :term:`VIRTUAL-RUNTIME_dev_manager <VIRTUAL-RUNTIME>` refers to the + package of the component that manages the ``/dev`` directory. Setting the "preferred provider" for runtime dependencies is as simple as using the following assignment in a configuration file:: @@ -7612,6 +7620,10 @@ system and gives an overview of their function and contents. configuration will not take effect. :term:`SDKPATH` + Defines the path used to collect the SDK components and build the + installer. + + :term:`SDKPATHINSTALL` Defines the path offered to the user for installation of the SDK that is generated by the OpenEmbedded build system. The path appears as the default location for installing the SDK when you run the SDK's @@ -7621,7 +7633,7 @@ system and gives an overview of their function and contents. :term:`SDKTARGETSYSROOT` The full path to the sysroot used for cross-compilation within an SDK as it will be when installed into the default - :term:`SDKPATH`. + :term:`SDKPATHINSTALL`. :term:`SECTION` The section in which packages should be categorized. Package @@ -7913,6 +7925,11 @@ system and gives an overview of their function and contents. image), compared to just using the :ref:`ref-classes-create-spdx` class with no option. + :term:`SPDX_NAMESPACE_PREFIX` + This option could be used in order to change the prefix of ``spdxDocument`` + and the prefix of ``documentNamespace``. It is set by default to + ``http://spdx.org/spdxdoc``. + :term:`SPDX_PRETTY` This option makes the SPDX output more human-readable, using identation and newlines, instead of the default output in a @@ -9391,7 +9408,7 @@ system and gives an overview of their function and contents. configuration can define the :term:`UBOOT_MACHINE` and optionally the :term:`IMAGE_FSTYPES` and the :term:`UBOOT_BINARY`. - Following is an example from the ``meta-freescale`` layer. :: + Here is an example from the ``meta-freescale`` layer. :: UBOOT_CONFIG ??= "sdcard-ifc-secure-boot sdcard-ifc sdcard-qspi lpuart qspi secure-boot nor" UBOOT_CONFIG[nor] = "ls1021atwr_nor_defconfig" @@ -9868,6 +9885,33 @@ system and gives an overview of their function and contents. Additionally, you should also set the :term:`USERADD_ERROR_DYNAMIC` variable. + :term:`VIRTUAL-RUNTIME` + :term:`VIRTUAL-RUNTIME` is a commonly used prefix for defining virtual + packages for runtime usage, typically for use in :term:`RDEPENDS` + or in image definitions. + + An example is ``VIRTUAL-RUNTIME_base-utils`` that makes it possible + to either use BusyBox based utilities:: + + VIRTUAL-RUNTIME_base-utils = "busybox" + + or their full featured implementations from GNU Coreutils + and other projects:: + + VIRTUAL-RUNTIME_base-utils = "packagegroup-core-base-utils" + + Here are two examples using this virtual runtime package. The + first one is in :yocto_git:`initramfs-framework_1.0.bb + </poky/tree/meta/recipes-core/initrdscripts/initramfs-framework_1.0.bb?h=scarthgap>`:: + + RDEPENDS:${PN} += "${VIRTUAL-RUNTIME_base-utils}" + + The second example is in the :yocto_git:`core-image-initramfs-boot + </poky/tree/meta/recipes-core/images/core-image-initramfs-boot.bb?h=scarthgap>` + image definition:: + + PACKAGE_INSTALL = "${INITRAMFS_SCRIPTS} ${VIRTUAL-RUNTIME_base-utils} base-passwd" + :term:`VOLATILE_LOG_DIR` Specifies the persistence of the target's ``/var/log`` directory, which is used to house postinstall target log files. @@ -9929,7 +9973,7 @@ system and gives an overview of their function and contents. With the :term:`WKS_FILE_DEPENDS` variable, you have the possibility to specify a list of additional dependencies (e.g. native tools, bootloaders, and so forth), that are required to build Wic images. - Following is an example:: + Here is an example:: WKS_FILE_DEPENDS = "some-native-tool" |