diff options
Diffstat (limited to 'poky/documentation')
72 files changed, 3076 insertions, 3736 deletions
diff --git a/poky/documentation/Makefile b/poky/documentation/Makefile index d40f390e2..996f01b7d 100644 --- a/poky/documentation/Makefile +++ b/poky/documentation/Makefile @@ -3,7 +3,7 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINXOPTS ?= -j auto +SPHINXOPTS ?= -W --keep-going -j auto SPHINXBUILD ?= sphinx-build SOURCEDIR = . BUILDDIR = _build diff --git a/poky/documentation/README b/poky/documentation/README index 176c6db35..f9e803a28 100644 --- a/poky/documentation/README +++ b/poky/documentation/README @@ -32,7 +32,7 @@ these instances. Manual Organization =================== -Folders exist for individual manuals as follows: +Here the folders corresponding to individual manuals: * sdk-manual - The Yocto Project Software Development Kit (SDK) Developer's Guide. * bsp-guide - The Yocto Project Board Support Package (BSP) Developer's Guide @@ -88,8 +88,8 @@ documentation. Yocto Project documentation website =================================== -A new website has been created to host the Yocto Project -documentation, it can be found at: https://docs.yoctoproject.org/. +The website hosting the Yocto Project documentation, can be found +at: https://docs.yoctoproject.org/. The entire Yocto Project documentation, as well as the BitBake manual, is published on this website, including all previously released @@ -167,7 +167,7 @@ The layout of the Yocto Project manuals is organized as follows Section Section -The following headings styles are defined in Sphinx: +Here are the heading styles defined in Sphinx: Book => overline === Chapter => overline *** diff --git a/poky/documentation/brief-yoctoprojectqs/index.rst b/poky/documentation/brief-yoctoprojectqs/index.rst index 974ae5ebc..b92b0d33d 100644 --- a/poky/documentation/brief-yoctoprojectqs/index.rst +++ b/poky/documentation/brief-yoctoprojectqs/index.rst @@ -238,7 +238,7 @@ an entire Linux distribution, including the toolchain, from source. You can significantly speed up your build and guard against fetcher failures by using mirrors. To use mirrors, add these lines to your - local.conf file in the Build directory: :: + local.conf file in the Build directory:: SSTATE_MIRRORS = "\ file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \ @@ -297,7 +297,7 @@ modular development and makes it easier to reuse the layer metadata. Follow these steps to add a hardware layer: -#. **Find a Layer:** Lots of hardware layers exist. The Yocto Project +#. **Find a Layer:** Many hardware layers are available. The Yocto Project :yocto_git:`Source Repositories <>` has many hardware layers. This example adds the `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer. @@ -318,8 +318,8 @@ Follow these steps to add a hardware layer: Resolving deltas: 100% (13385/13385), done. Checking connectivity... done. - The hardware layer now exists - with other layers inside the Poky reference repository on your build + The hardware layer is now available + next to other layers inside the Poky reference repository on your build host as ``meta-altera`` and contains all the metadata needed to support hardware from Altera, which is owned by Intel. @@ -332,7 +332,7 @@ Follow these steps to add a hardware layer: #. **Change the Configuration to Build for a Specific Machine:** The :term:`MACHINE` variable in the ``local.conf`` file specifies the machine for the build. For this - example, set the ``MACHINE`` variable to ``cyclone5``. These + example, set the :term:`MACHINE` variable to ``cyclone5``. These configurations are used: https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf. @@ -431,8 +431,8 @@ information including the website, wiki pages, and user manuals: information. - **Yocto Project Mailing Lists:** Related mailing lists provide a forum - for discussion, patch submission and announcements. Several mailing - lists exist and are grouped according to areas of concern. See the + for discussion, patch submission and announcements. There are several + mailing lists grouped by topic. See the :ref:`ref-manual/resources:mailing lists` section in the Yocto Project Reference Manual for a complete list of Yocto Project mailing lists. diff --git a/poky/documentation/bsp-guide/bsp.rst b/poky/documentation/bsp-guide/bsp.rst index 89f156442..5c43f53d0 100644 --- a/poky/documentation/bsp-guide/bsp.rst +++ b/poky/documentation/bsp-guide/bsp.rst @@ -26,7 +26,7 @@ A BSP consists of a file structure inside a base directory. Collectively, you can think of the base directory, its file structure, and the contents as a BSP layer. Although not a strict requirement, BSP layers in the Yocto Project use the following well-established naming -convention: :: +convention:: meta-bsp_root_name @@ -58,7 +58,7 @@ Each repository is a BSP layer supported by the Yocto Project (e.g. ``meta-raspberrypi`` and ``meta-intel``). Each of these layers is a repository unto itself and clicking on the layer name displays two URLs from which you can clone the layer's repository to your local system. -Here is an example that clones the Raspberry Pi BSP layer: :: +Here is an example that clones the Raspberry Pi BSP layer:: $ git clone git://git.yoctoproject.org/meta-raspberrypi @@ -84,7 +84,7 @@ established after you run the OpenEmbedded build environment setup script (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). Adding the root directory allows the :term:`OpenEmbedded Build System` to recognize the BSP -layer and from it build an image. Here is an example: :: +layer and from it build an image. Here is an example:: BBLAYERS ?= " \ /usr/local/src/yocto/meta \ @@ -95,11 +95,11 @@ layer and from it build an image. Here is an example: :: .. note:: - Ordering and :term:`BBFILE_PRIORITY` for the layers listed in ``BBLAYERS`` + Ordering and :term:`BBFILE_PRIORITY` for the layers listed in :term:`BBLAYERS` matter. For example, if multiple layers define a machine configuration, the OpenEmbedded build system uses the last layer searched given similar layer priorities. The build system works from the top-down through the layers - listed in ``BBLAYERS``. + listed in :term:`BBLAYERS`. Some BSPs require or depend on additional layers beyond the BSP's root layer in order to be functional. In this case, you need to specify these @@ -113,7 +113,7 @@ this type of layer is OpenEmbedded's `meta-openembedded <https://github.com/openembedded/meta-openembedded>`__ layer. The ``meta-openembedded`` layer contains many ``meta-*`` layers. In cases like this, you need to include the names of the actual layers -you want to work with, such as: :: +you want to work with, such as:: BBLAYERS ?= " \ /usr/local/src/yocto/meta \ @@ -193,7 +193,7 @@ section. #. *Check Out the Proper Branch:* The branch you check out for ``meta-intel`` must match the same branch you are using for the - Yocto Project release (e.g. ``&DISTRO_NAME_NO_CAP;``): :: + Yocto Project release (e.g. ``&DISTRO_NAME_NO_CAP;``):: $ cd meta-intel $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP; @@ -216,7 +216,7 @@ section. The process is identical to the process used for the ``meta-intel`` layer except for the layer's name. For example, if you determine that your hardware most closely matches the ``meta-raspberrypi``, clone - that layer: :: + that layer:: $ git clone git://git.yoctoproject.org/meta-raspberrypi Cloning into 'meta-raspberrypi'... @@ -267,7 +267,7 @@ maintain the distinction that the BSP layer, a build system, and tools are separate components that could be combined in certain end products. Before looking at the recommended form for the directory structure -inside a BSP layer, you should be aware that some requirements do exist +inside a BSP layer, you should be aware that there are some requirements in order for a BSP layer to be considered compliant with the Yocto Project. For that list of requirements, see the ":ref:`bsp-guide/bsp:released bsp requirements`" section. @@ -451,7 +451,7 @@ The following sections describe each part of the proposed BSP format. License Files ------------- -You can find these files in the BSP Layer at: :: +You can find these files in the BSP Layer at:: meta-bsp_root_name/bsp_license_file @@ -469,7 +469,7 @@ section in the Yocto Project Development Tasks Manual. README File ----------- -You can find this file in the BSP Layer at: :: +You can find this file in the BSP Layer at:: meta-bsp_root_name/README @@ -484,7 +484,7 @@ name of the BSP maintainer with his or her contact information. README.sources File ------------------- -You can find this file in the BSP Layer at: :: +You can find this file in the BSP Layer at:: meta-bsp_root_name/README.sources @@ -503,7 +503,7 @@ used to generate the images that ship with the BSP. Pre-built User Binaries ----------------------- -You can find these files in the BSP Layer at: :: +You can find these files in the BSP Layer at:: meta-bsp_root_name/binary/bootable_images @@ -526,7 +526,7 @@ information on the Metadata. Layer Configuration File ------------------------ -You can find this file in the BSP Layer at: :: +You can find this file in the BSP Layer at:: meta-bsp_root_name/conf/layer.conf @@ -550,7 +550,7 @@ template). :: LAYERDEPENDS_bsp = "intel" To illustrate the string substitutions, here are the corresponding -statements from the Raspberry Pi ``conf/layer.conf`` file: :: +statements from the Raspberry Pi ``conf/layer.conf`` file:: # We have a conf and classes directory, append to BBPATH BBPATH .= ":${LAYERDIR}" @@ -576,7 +576,7 @@ recognize the BSP. Hardware Configuration Options ------------------------------ -You can find these files in the BSP Layer at: :: +You can find these files in the BSP Layer at:: meta-bsp_root_name/conf/machine/*.conf @@ -607,14 +607,14 @@ For example, many ``tune-*`` files (e.g. ``tune-arm1136jf-s.inc``, To use an include file, you simply include them in the machine configuration file. For example, the Raspberry Pi BSP -``raspberrypi3.conf`` contains the following statement: :: +``raspberrypi3.conf`` contains the following statement:: include conf/machine/include/rpi-base.inc Miscellaneous BSP-Specific Recipe Files --------------------------------------- -You can find these files in the BSP Layer at: :: +You can find these files in the BSP Layer at:: meta-bsp_root_name/recipes-bsp/* @@ -624,7 +624,7 @@ Raspberry Pi BSP, there is the ``formfactor_0.0.bbappend`` file, which is an append file used to augment the recipe that starts the build. Furthermore, there are machine-specific settings used during the build that are defined by the ``machconfig`` file further down in the -directory. Here is the ``machconfig`` file for the Raspberry Pi BSP: :: +directory. Here is the ``machconfig`` file for the Raspberry Pi BSP:: HAVE_TOUCHSCREEN=0 HAVE_KEYBOARD=1 @@ -644,7 +644,7 @@ directory. Here is the ``machconfig`` file for the Raspberry Pi BSP: :: Display Support Files --------------------- -You can find these files in the BSP Layer at: :: +You can find these files in the BSP Layer at:: meta-bsp_root_name/recipes-graphics/* @@ -655,7 +655,7 @@ to support a display are kept here. Linux Kernel Configuration -------------------------- -You can find these files in the BSP Layer at: :: +You can find these files in the BSP Layer at:: meta-bsp_root_name/recipes-kernel/linux/linux*.bbappend meta-bsp_root_name/recipes-kernel/linux/*.bb @@ -678,14 +678,14 @@ Suppose you are using the ``linux-yocto_4.4.bb`` recipe to build the kernel. In other words, you have selected the kernel in your ``"bsp_root_name".conf`` file by adding :term:`PREFERRED_PROVIDER` and :term:`PREFERRED_VERSION` -statements as follows: :: +statements as follows:: PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" PREFERRED_VERSION_linux-yocto ?= "4.4%" .. note:: - When the preferred provider is assumed by default, the ``PREFERRED_PROVIDER`` + When the preferred provider is assumed by default, the :term:`PREFERRED_PROVIDER` statement does not appear in the ``"bsp_root_name".conf`` file. You would use the ``linux-yocto_4.4.bbappend`` file to append specific @@ -698,7 +698,7 @@ in the Yocto Project Linux Kernel Development Manual. An alternate scenario is when you create your own kernel recipe for the BSP. A good example of this is the Raspberry Pi BSP. If you examine the -``recipes-kernel/linux`` directory you see the following: :: +``recipes-kernel/linux`` directory you see the following:: linux-raspberrypi-dev.bb linux-raspberrypi.inc @@ -763,8 +763,8 @@ workflow. .. note:: - - Four hardware reference BSPs exist that are part of the Yocto - Project release and are located in the ``poky/meta-yocto-bsp`` + - There are four hardware reference BSPs in the Yocto + Project release, located in the ``poky/meta-yocto-bsp`` BSP layer: - Texas Instruments Beaglebone (``beaglebone-yocto``) @@ -773,8 +773,8 @@ workflow. - Two general IA platforms (``genericx86`` and ``genericx86-64``) - - Three core Intel BSPs exist as part of the Yocto Project - release in the ``meta-intel`` layer: + - There are three core Intel BSPs in the Yocto Project + release, in the ``meta-intel`` layer: - ``intel-core2-32``, which is a BSP optimized for the Core2 family of CPUs as well as all CPUs prior to the Silvermont @@ -832,10 +832,8 @@ workflow. Requirements and Recommendations for Released BSPs ================================================== -Certain requirements exist for a released BSP to be considered compliant -with the Yocto Project. Additionally, recommendations also exist. This -section describes the requirements and recommendations for released -BSPs. +This section describes requirements and recommendations for a released +BSP to be considered compliant with the Yocto Project. Released BSP Requirements ------------------------- @@ -864,7 +862,7 @@ Before looking at BSP requirements, you should consider the following: - It is not required that specific packages or package modifications exist in the BSP layer, beyond the requirements for general - compliance with the Yocto Project. For example, no requirement exists + compliance with the Yocto Project. For example, there is no requirement dictating that a specific kernel or kernel version be used in a given BSP. @@ -900,7 +898,7 @@ Yocto Project: - *License File:* You must include a license file in the ``meta-bsp_root_name`` directory. This license covers the BSP Metadata as a whole. You must specify which license to use since no - default license exists when one is not specified. See the + default license exists. See the :yocto_git:`COPYING.MIT </meta-raspberrypi/tree/COPYING.MIT>` file for the Raspberry Pi BSP in the ``meta-raspberrypi`` BSP layer as an example. @@ -1042,7 +1040,7 @@ BSP-specific configuration file named ``interfaces`` to the also supports several other machines: #. Edit the ``init-ifupdown_1.0.bbappend`` file so that it contains the - following: :: + following:: FILESEXTRAPATHS_prepend := "${THISDIR}/files:" @@ -1050,14 +1048,14 @@ also supports several other machines: directory. #. Create and place the new ``interfaces`` configuration file in the - BSP's layer here: :: + BSP's layer here:: meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces .. note:: If the ``meta-xyz`` layer did not support multiple machines, you would place - the interfaces configuration file in the layer here: :: + the interfaces configuration file in the layer here:: meta-xyz/recipes-core/init-ifupdown/files/interfaces @@ -1107,7 +1105,7 @@ system requirements. unsuitable functionality or quality, you can use an encumbered version. -A couple different methods exist within the OpenEmbedded build system to +There are two different methods within the OpenEmbedded build system to satisfy the licensing requirements for an encumbered BSP. The following list describes them in order of preference: @@ -1123,15 +1121,15 @@ list describes them in order of preference: how to use these variables. If you build as you normally would, without specifying any recipes in - the ``LICENSE_FLAGS_WHITELIST``, the build stops and provides you + the :term:`LICENSE_FLAGS_WHITELIST`, the build stops and provides you with the list of recipes that you have tried to include in the image - that need entries in the ``LICENSE_FLAGS_WHITELIST``. Once you enter + that need entries in the :term:`LICENSE_FLAGS_WHITELIST`. Once you enter the appropriate license flags into the whitelist, restart the build to continue where it left off. During the build, the prompt will not appear again since you have satisfied the requirement. Once the appropriate license flags are on the white list in the - ``LICENSE_FLAGS_WHITELIST`` variable, you can build the encumbered + :term:`LICENSE_FLAGS_WHITELIST` variable, you can build the encumbered image with no change at all to the normal build process. #. *Get a Pre-Built Version of the BSP:* You can get this type of BSP by @@ -1144,7 +1142,7 @@ list describes them in order of preference: click-through license agreements presented by the website. If you want to build the image yourself using the recipes contained within the BSP tarball, you will still need to create an appropriate - ``LICENSE_FLAGS_WHITELIST`` to match the encumbered recipes in the + :term:`LICENSE_FLAGS_WHITELIST` to match the encumbered recipes in the BSP. .. note:: @@ -1186,11 +1184,11 @@ Use these steps to create a BSP layer: - *Create a Machine Configuration File:* Create a ``conf/machine/bsp_root_name.conf`` file. See :yocto_git:`meta-yocto-bsp/conf/machine </poky/tree/meta-yocto-bsp/conf/machine>` - for sample ``bsp_root_name.conf`` files. Other samples such as + for sample ``bsp_root_name.conf`` files. There are other samples such as :yocto_git:`meta-ti </meta-ti/tree/conf/machine>` and :yocto_git:`meta-freescale </meta-freescale/tree/conf/machine>` - exist from other vendors that have more specific machine and tuning + from other vendors that have more specific machine and tuning examples. - *Create a Kernel Recipe:* Create a kernel recipe in @@ -1210,7 +1208,7 @@ BSP Layer Configuration Example ------------------------------- The layer's ``conf`` directory contains the ``layer.conf`` configuration -file. In this example, the ``conf/layer.conf`` is the following: :: +file. In this example, the ``conf/layer.conf`` is the following:: # We have a conf and classes directory, add to BBPATH BBPATH .= ":${LAYERDIR}" @@ -1241,8 +1239,8 @@ As mentioned earlier in this section, the existence of a machine configuration file is what makes a layer a BSP layer as compared to a general or kernel layer. -One or more machine configuration files exist in the -``bsp_layer/conf/machine/`` directory of the layer: :: +There are one or more machine configuration files in the +``bsp_layer/conf/machine/`` directory of the layer:: bsp_layer/conf/machine/machine1\.conf bsp_layer/conf/machine/machine2\.conf @@ -1252,7 +1250,7 @@ One or more machine configuration files exist in the For example, the machine configuration file for the `BeagleBone and BeagleBone Black development boards <https://beagleboard.org/bone>`__ is located in the layer ``poky/meta-yocto-bsp/conf/machine`` and is named -``beaglebone-yocto.conf``: :: +``beaglebone-yocto.conf``:: #@TYPE: Machine #@NAME: Beaglebone-yocto machine @@ -1311,7 +1309,7 @@ Project Reference Manual. - :term:`PREFERRED_PROVIDER_virtual/xserver <PREFERRED_PROVIDER>`: The recipe that provides "virtual/xserver" when more than one provider is found. In this case, the recipe that provides - "virtual/xserver" is "xserver-xorg", which exists in + "virtual/xserver" is "xserver-xorg", available in ``poky/meta/recipes-graphics/xorg-xserver``. - :term:`XSERVER`: The packages that @@ -1326,7 +1324,7 @@ Project Reference Manual. .. tip:: - Many ``MACHINE*`` variables exist that help you configure a particular piece + There are many ``MACHINE*`` variables that help you configure a particular piece of hardware. - :term:`EXTRA_IMAGEDEPENDS`: @@ -1339,9 +1337,9 @@ Project Reference Manual. - :term:`DEFAULTTUNE`: Machines use tunings to optimize machine, CPU, and application performance. These features, which are collectively known as "tuning features", - exist in the :term:`OpenEmbedded-Core (OE-Core)` layer (e.g. + are set in the :term:`OpenEmbedded-Core (OE-Core)` layer (e.g. ``poky/meta/conf/machine/include``). In this example, the default - tuning file is "cortexa8hf-neon". + tuning file is ``cortexa8hf-neon``. .. note:: @@ -1407,7 +1405,7 @@ Project Reference Manual. The BeagleBone development board requires an SPL to boot and that SPL file type must be MLO. Consequently, the machine configuration needs - to define ``SPL_BINARY`` as ``MLO``. + to define :term:`SPL_BINARY` as ``MLO``. .. note:: @@ -1447,7 +1445,7 @@ BSP Kernel Recipe Example ------------------------- The kernel recipe used to build the kernel image for the BeagleBone -device was established in the machine configuration: :: +device was established in the machine configuration:: PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" PREFERRED_VERSION_linux-yocto ?= "5.0%" @@ -1458,7 +1456,7 @@ metadata used to build the kernel. In this case, a kernel append file kernel recipe (i.e. ``linux-yocto_5.0.bb``), which is located in :yocto_git:`/poky/tree/meta/recipes-kernel/linux`. -Following is the contents of the append file: :: +Following is the contents of the append file:: KBRANCH_genericx86 = "v5.0/standard/base" KBRANCH_genericx86-64 = "v5.0/standard/base" diff --git a/poky/documentation/conf.py b/poky/documentation/conf.py index 5a2e25f7b..6c6458fed 100644 --- a/poky/documentation/conf.py +++ b/poky/documentation/conf.py @@ -92,6 +92,9 @@ intersphinx_mapping = { 'bitbake': ('https://docs.yoctoproject.org/bitbake/', None) } +# Suppress "WARNING: unknown mimetype for ..." +suppress_warnings = ['epub.unknown_project_files'] + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/poky/documentation/dev-manual/common-tasks.rst b/poky/documentation/dev-manual/common-tasks.rst index 176025f9e..762636a17 100644 --- a/poky/documentation/dev-manual/common-tasks.rst +++ b/poky/documentation/dev-manual/common-tasks.rst @@ -49,15 +49,13 @@ Follow these general steps to create your layer without using tools: (e.g. the cloned ``poky`` repository). While not strictly required, prepend the name of the directory with - the string "meta-". For example: - :: + the string "meta-". For example:: meta-mylayer meta-GUI_xyz meta-mymachine - With rare exceptions, a layer's name follows this form: - :: + With rare exceptions, a layer's name follows this form:: meta-root_name @@ -77,8 +75,7 @@ Follow these general steps to create your layer without using tools: :yocto_git:`Source Repositories </poky/tree/meta-yocto-bsp/conf>` demonstrates the required syntax. For your layer, you need to replace "yoctobsp" with a unique identifier for your layer (e.g. "machinexyz" - for a layer named "meta-machinexyz"): - :: + for a layer named "meta-machinexyz"):: # We have a conf and classes directory, add to BBPATH BBPATH .= ":${LAYERDIR}" @@ -97,10 +94,10 @@ Follow these general steps to create your layer without using tools: - :term:`BBPATH`: Adds the layer's root directory to BitBake's search path. Through the use of the - ``BBPATH`` variable, BitBake locates class files (``.bbclass``), + :term:`BBPATH` variable, BitBake locates class files (``.bbclass``), configuration files, and files that are included with ``include`` and ``require`` statements. For these cases, BitBake uses the - first file that matches the name found in ``BBPATH``. This is + first file that matches the name found in :term:`BBPATH`. This is similar to the way the ``PATH`` variable is used for binaries. It is recommended, therefore, that you use unique class and configuration filenames in your custom layer. @@ -195,8 +192,7 @@ following list: machine "one". To do so, you use an append file named ``base-files.bbappend`` and create a dependency on "foo" by altering the :term:`DEPENDS` - variable: - :: + variable:: DEPENDS = "foo" @@ -209,14 +205,12 @@ following list: ``foo``. To make sure your changes apply only when building machine "one", - use a machine override with the ``DEPENDS`` statement: - :: + use a machine override with the :term:`DEPENDS` statement:: DEPENDS_one = "foo" You should follow the same strategy when using ``_append`` - and ``_prepend`` operations: - :: + and ``_prepend`` operations:: DEPENDS_append_one = " foo" DEPENDS_prepend_one = "foo " @@ -224,8 +218,7 @@ following list: As an actual example, here's a snippet from the generic kernel include file ``linux-yocto.inc``, wherein the kernel compile and link options are adjusted in the - case of a subset of the supported architectures: - :: + case of a subset of the supported architectures:: DEPENDS_append_aarch64 = " libgcc" KERNEL_CC_append_aarch64 = " ${TOOLCHAIN_OPTIONS}" @@ -252,8 +245,7 @@ following list: file, you can use an append file to cause the build to use your own version of the file. For example, an append file in your layer at ``meta-one/recipes-core/base-files/base-files.bbappend`` could - extend :term:`FILESPATH` using :term:`FILESEXTRAPATHS` as follows: - :: + extend :term:`FILESPATH` using :term:`FILESEXTRAPATHS` as follows:: FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:" @@ -263,7 +255,7 @@ following list: are building for a different machine and the ``bblayers.conf`` file includes the ``meta-one`` layer and the location of your machine-specific file is the first location where that file is - found according to ``FILESPATH``, builds for all machines will + found according to :term:`FILESPATH`, builds for all machines will also use that machine-specific file. You can make sure that a machine-specific file is used for a @@ -354,7 +346,7 @@ The application consists of the following sections: of the Yocto Project for which your layer is compatible. - *Acceptance Criteria:* Provide "Yes" or "No" answers for each of the - items in the checklist. Space exists at the bottom of the form for + items in the checklist. There is space at the bottom of the form for any explanations for items for which you answered "No". - *Recommendations:* Provide answers for the questions regarding Linux @@ -375,8 +367,7 @@ the COMMON and DISTRO related tests. Furthermore, if your layer is a BSP layer, the layer must pass the COMMON and BSP set of tests. To execute the script, enter the following commands from your build -directory: -:: +directory:: $ source oe-init-build-env $ yocto-check-layer your_layer_directory @@ -429,11 +420,10 @@ Enabling Your Layer Before the OpenEmbedded build system can use your new layer, you need to enable it. To enable your layer, simply add your layer's path to the -``BBLAYERS`` variable in your ``conf/bblayers.conf`` file, which is +:term:`BBLAYERS` variable in your ``conf/bblayers.conf`` file, which is found in the :term:`Build Directory`. The following example shows how to enable a layer named -``meta-mylayer``: -:: +``meta-mylayer``:: # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf # changes incompatibly @@ -448,7 +438,7 @@ The following example shows how to enable a layer named " BitBake parses each ``conf/layer.conf`` file from the top down as -specified in the ``BBLAYERS`` variable within the ``conf/bblayers.conf`` +specified in the :term:`BBLAYERS` variable within the ``conf/bblayers.conf`` file. During the processing of each ``conf/layer.conf`` file, BitBake adds the recipes, classes and configurations contained within the particular layer to the source directory. @@ -488,8 +478,7 @@ As an example, consider the main formfactor recipe and a corresponding formfactor append file both from the :term:`Source Directory`. Here is the main formfactor recipe, which is named ``formfactor_0.0.bb`` and located in -the "meta" layer at ``meta/recipes-bsp/formfactor``: -:: +the "meta" layer at ``meta/recipes-bsp/formfactor``:: SUMMARY = "Device formfactor information" DESCRIPTION = "A formfactor configuration file provides information about the \ @@ -521,8 +510,7 @@ during the build. Following is the append file, which is named ``formfactor_0.0.bbappend`` and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The -file is in the layer at ``recipes-bsp/formfactor``: -:: +file is in the layer at ``recipes-bsp/formfactor``:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" @@ -543,19 +531,19 @@ have the supporting directory structure set up that will contain any files or patches you will be including from the layer. Using the immediate expansion assignment operator ``:=`` is important -because of the reference to ``THISDIR``. The trailing colon character is +because of the reference to :term:`THISDIR`. The trailing colon character is important as it ensures that items in the list remain colon-separated. .. note:: - BitBake automatically defines the ``THISDIR`` variable. You should + BitBake automatically defines the :term:`THISDIR` variable. You should never set this variable yourself. Using "_prepend" as part of the - ``FILESEXTRAPATHS`` ensures your path will be searched prior to other + :term:`FILESEXTRAPATHS` ensures your path will be searched prior to other paths in the final list. Also, not all append files add extra files. Many append files simply - exist to add build options (e.g. ``systemd``). For these cases, your - append file would not even use the ``FILESEXTRAPATHS`` statement. + allow to add build options (e.g. ``systemd``). For these cases, your + append file would not even use the :term:`FILESEXTRAPATHS` statement. Prioritizing Your Layer ----------------------- @@ -570,8 +558,7 @@ build system to calculate it based on the layer's dependencies. To specify the layer's priority manually, use the :term:`BBFILE_PRIORITY` -variable and append the layer's root name: -:: +variable and append the layer's root name:: BBFILE_PRIORITY_mylayer = "1" @@ -595,8 +582,7 @@ with their paths and priorities and on ``.bbappend`` files and their applicable recipes can help to reveal potential problems. For help on the BitBake layer management tool, use the following -command: -:: +command:: $ bitbake-layers --help NOTE: Starting bitbake server... @@ -676,8 +662,7 @@ The following list describes the available commands: variable values, you need to tidy these up yourself. Consider the following example. Here, the ``bitbake-layers`` command adds the line ``#### bbappended ...`` so that you know where the following - lines originate: - :: + lines originate:: ... DESCRIPTION = "A useful utility" @@ -691,8 +676,7 @@ The following list describes the available commands: EXTRA_OECONF += "--enable-somethingelse" - Ideally, you would tidy up these utilities as follows: - :: + Ideally, you would tidy up these utilities as follows:: ... DESCRIPTION = "Customized utility" @@ -746,14 +730,12 @@ create a layer with the following: In its simplest form, you can use the following command form to create a layer. The command creates a layer whose name corresponds to -"your_layer_name" in the current directory: -:: +"your_layer_name" in the current directory:: $ bitbake-layers create-layer your_layer_name As an example, the following command creates a layer named ``meta-scottrif`` -in your home directory: -:: +in your home directory:: $ cd /usr/home $ bitbake-layers create-layer meta-scottrif @@ -770,8 +752,7 @@ default, you can use the ``--example-recipe-name`` option. The easiest way to see how the ``bitbake-layers create-layer`` command works is to experiment with the script. You can also read the usage -information by entering the following: -:: +information by entering the following:: $ bitbake-layers create-layer --help NOTE: Starting bitbake server... @@ -799,16 +780,14 @@ Once you create your general layer, you must add it to your makes the OpenEmbedded build system aware of your layer so that it can search it for metadata. -Add your layer by using the ``bitbake-layers add-layer`` command: -:: +Add your layer by using the ``bitbake-layers add-layer`` command:: $ bitbake-layers add-layer your_layer_name Here is an example that adds a layer named ``meta-scottrif`` to the configuration file. Following the command that adds the layer is another ``bitbake-layers`` command that -shows the layers that are in your ``bblayers.conf`` file: -:: +shows the layers that are in your ``bblayers.conf`` file:: $ bitbake-layers add-layer meta-scottrif NOTE: Starting bitbake server... @@ -851,8 +830,7 @@ variable changes are in effect for every build and consequently affect all images, which might not be what you require. To add a package to your image using the local configuration file, use -the ``IMAGE_INSTALL`` variable with the ``_append`` operator: -:: +the :term:`IMAGE_INSTALL` variable with the ``_append`` operator:: IMAGE_INSTALL_append = " strace" @@ -870,15 +848,14 @@ takes effect. As shown in its simplest use, ``IMAGE_INSTALL_append`` affects all images. It is possible to extend the syntax so that the variable applies -to a specific image only. Here is an example: -:: +to a specific image only. Here is an example:: IMAGE_INSTALL_append_pn-core-image-minimal = " strace" This example adds ``strace`` to the ``core-image-minimal`` image only. You can add packages using a similar approach through the -``CORE_IMAGE_EXTRA_INSTALL`` variable. If you use this variable, only +:term:`CORE_IMAGE_EXTRA_INSTALL` variable. If you use this variable, only ``core-image-*`` images are affected. Customizing Images Using Custom ``IMAGE_FEATURES`` and ``EXTRA_IMAGE_FEATURES`` @@ -889,18 +866,18 @@ high-level image features by using the :term:`IMAGE_FEATURES` and :term:`EXTRA_IMAGE_FEATURES` variables. Although the functions for both variables are nearly -equivalent, best practices dictate using ``IMAGE_FEATURES`` from within -a recipe and using ``EXTRA_IMAGE_FEATURES`` from within your +equivalent, best practices dictate using :term:`IMAGE_FEATURES` from within +a recipe and using :term:`EXTRA_IMAGE_FEATURES` from within your ``local.conf`` file, which is found in the :term:`Build Directory`. To understand how these features work, the best reference is ``meta/classes/core-image.bbclass``. This class lists out the available -``IMAGE_FEATURES`` of which most map to package groups while some, such +:term:`IMAGE_FEATURES` of which most map to package groups while some, such as ``debug-tweaks`` and ``read-only-rootfs``, resolve as general configuration settings. -In summary, the file looks at the contents of the ``IMAGE_FEATURES`` +In summary, the file looks at the contents of the :term:`IMAGE_FEATURES` variable and then maps or configures the feature accordingly. Based on this information, the build system automatically adds the appropriate packages or configurations to the @@ -908,11 +885,11 @@ packages or configurations to the Effectively, you are enabling extra features by extending the class or creating a custom class for use with specialized image ``.bb`` files. -Use the ``EXTRA_IMAGE_FEATURES`` variable from within your local +Use the :term:`EXTRA_IMAGE_FEATURES` variable from within your local configuration file. Using a separate area from which to enable features with this variable helps you avoid overwriting the features in the image -recipe that are enabled with ``IMAGE_FEATURES``. The value of -``EXTRA_IMAGE_FEATURES`` is added to ``IMAGE_FEATURES`` within +recipe that are enabled with :term:`IMAGE_FEATURES`. The value of +:term:`EXTRA_IMAGE_FEATURES` is added to :term:`IMAGE_FEATURES` within ``meta/conf/bitbake.conf``. To illustrate how you can use these variables to modify your image, @@ -926,8 +903,8 @@ images both include OpenSSH. The ``core-image-minimal`` image does not contain an SSH server. You can customize your image and change these defaults. Edit the -``IMAGE_FEATURES`` variable in your recipe or use the -``EXTRA_IMAGE_FEATURES`` in your ``local.conf`` file so that it +:term:`IMAGE_FEATURES` variable in your recipe or use the +:term:`EXTRA_IMAGE_FEATURES` in your ``local.conf`` file so that it configures the image you are working with to include ``ssh-server-dropbear`` or ``ssh-server-openssh``. @@ -942,15 +919,14 @@ Customizing Images Using Custom .bb Files You can also customize an image by creating a custom recipe that defines additional software as part of the image. The following example shows -the form for the two lines you need: -:: +the form for the two lines you need:: IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2" inherit core-image Defining the software using a custom recipe gives you total control over the contents of the image. It is important to use the correct names of -packages in the ``IMAGE_INSTALL`` variable. You must use the +packages in the :term:`IMAGE_INSTALL` variable. You must use the OpenEmbedded notation and not the Debian notation for the names (e.g. ``glibc-dev`` instead of ``libc6-dev``). @@ -958,8 +934,7 @@ The other method for creating a custom image is to base it on an existing image. For example, if you want to create an image based on ``core-image-sato`` but add the additional package ``strace`` to the image, copy the ``meta/recipes-sato/images/core-image-sato.bb`` to a new -``.bb`` and add the following line to the end of the copy: -:: +``.bb`` and add the following line to the end of the copy:: IMAGE_INSTALL += "strace" @@ -971,27 +946,26 @@ to create a custom package group recipe that is used to build the image or images. A good example of a package group recipe is ``meta/recipes-core/packagegroups/packagegroup-base.bb``. -If you examine that recipe, you see that the ``PACKAGES`` variable lists +If you examine that recipe, you see that the :term:`PACKAGES` variable lists the package group packages to produce. The ``inherit packagegroup`` statement sets appropriate default values and automatically adds ``-dev``, ``-dbg``, and ``-ptest`` complementary packages for each -package specified in the ``PACKAGES`` statement. +package specified in the :term:`PACKAGES` statement. .. note:: The ``inherit packagegroup`` line should be located near the top of the - recipe, certainly before the ``PACKAGES`` statement. + recipe, certainly before the :term:`PACKAGES` statement. -For each package you specify in ``PACKAGES``, you can use ``RDEPENDS`` -and ``RRECOMMENDS`` entries to provide a list of packages the parent +For each package you specify in :term:`PACKAGES`, you can use :term:`RDEPENDS` +and :term:`RRECOMMENDS` entries to provide a list of packages the parent task package should contain. You can see examples of these further down in the ``packagegroup-base.bb`` recipe. Here is a short, fabricated example showing the same basic pieces for a hypothetical packagegroup defined in ``packagegroup-custom.bb``, where -the variable ``PN`` is the standard way to abbreviate the reference to -the full packagegroup name ``packagegroup-custom``: -:: +the variable :term:`PN` is the standard way to abbreviate the reference to +the full packagegroup name ``packagegroup-custom``:: DESCRIPTION = "My Custom Package Groups" @@ -1020,7 +994,7 @@ their dependencies and their recommended package dependencies listed: ``packagegroup-custom-apps``, and ``packagegroup-custom-tools``. To build an image using these package group packages, you need to add ``packagegroup-custom-apps`` and/or ``packagegroup-custom-tools`` to -``IMAGE_INSTALL``. For other forms of image dependencies see the other +:term:`IMAGE_INSTALL`. For other forms of image dependencies see the other areas of this section. Customizing an Image Hostname @@ -1033,13 +1007,11 @@ configured hostname written to ``/etc/hostname`` is "qemux86". You can customize this name by altering the value of the "hostname" variable in the ``base-files`` recipe using either an append file or a -configuration file. Use the following in an append file: -:: +configuration file. Use the following in an append file:: hostname = "myhostname" -Use the following in a configuration file: -:: +Use the following in a configuration file:: hostname_pn-base-files = "myhostname" @@ -1054,8 +1026,7 @@ you can easily reset the default hostname. Another point of interest is that if you unset the variable, the image will have no default hostname in the filesystem. Here is an example that -unsets the variable in a configuration file: -:: +unsets the variable in a configuration file:: hostname_pn-base-files = "" @@ -1089,8 +1060,8 @@ The remainder of the section provides details for the steps. Locate or Automatically Create a Base Recipe -------------------------------------------- -You can always write a recipe from scratch. However, three choices exist -that can help you quickly get a start on a new recipe: +You can always write a recipe from scratch. However, there are three choices +that can help you quickly get started with a new recipe: - ``devtool add``: A command that assists in creating a recipe and an environment conducive to development. @@ -1136,8 +1107,7 @@ To run the tool, you just need to be in your :term:`Build Directory` and have sourced the build environment setup script (i.e. :ref:`structure-core-script`). -To get help on the tool, use the following command: -:: +To get help on the tool, use the following command:: $ recipetool -h NOTE: Starting bitbake server... @@ -1166,22 +1136,20 @@ locates it properly in the layer that contains your source files. Following are some syntax examples: - Use this syntax to generate a recipe based on source. Once generated, - the recipe resides in the existing source code layer: - :: + the recipe resides in the existing source code layer:: recipetool create -o OUTFILE source - Use this syntax to generate a recipe using code that you extract from source. The extracted code is placed in its own layer - defined by ``EXTERNALSRC``. + defined by :term:`EXTERNALSRC`. :: recipetool create -o OUTFILE -x EXTERNALSRC source - Use this syntax to generate a recipe based on source. The options direct ``recipetool`` to generate debugging information. Once generated, - the recipe resides in the existing source code layer: - :: + the recipe resides in the existing source code layer:: recipetool create -d -o OUTFILE source @@ -1236,8 +1204,7 @@ the recipe. recipe through the layer's ``conf/layer.conf`` file and the :term:`BBFILES` variable. This variable sets up a path from which the build system can locate - recipes. Here is the typical use: - :: + recipes. Here is the typical use:: BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ ${LAYERDIR}/recipes-*/*/*.bbappend" @@ -1249,8 +1216,7 @@ the recipe. ":ref:`dev-manual/common-tasks:understanding and creating layers`" section. - *Naming Your Recipe:* When you name your recipe, you need to follow - this naming convention: - :: + this naming convention:: basename_version.bb @@ -1276,8 +1242,7 @@ Assuming you have sourced the build environment setup script (i.e. :ref:`structure-core-script`) and you are in the :term:`Build Directory`, use BitBake to process your recipe. All you need to provide is the -``basename`` of the recipe as described in the previous section: -:: +``basename`` of the recipe as described in the previous section:: $ bitbake basename @@ -1289,8 +1254,7 @@ compilation and packaging files, and so forth. The path to the per-recipe temporary work directory depends on the context in which it is being built. The quickest way to find this path -is to have BitBake return it by running the following: -:: +is to have BitBake return it by running the following:: $ bitbake -e basename | grep ^WORKDIR= @@ -1299,8 +1263,7 @@ top-level folder named ``poky``, a default Build Directory at ``poky/build``, and a ``qemux86-poky-linux`` machine target system. Furthermore, suppose your recipe is named ``foo_1.3.0.bb``. In this case, the work directory the build system uses to build the package -would be as follows: -:: +would be as follows:: poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 @@ -1325,22 +1288,22 @@ Fetching Code The first thing your recipe must do is specify how to fetch the source files. Fetching is controlled mainly through the :term:`SRC_URI` variable. Your recipe -must have a ``SRC_URI`` variable that points to where the source is +must have a :term:`SRC_URI` variable that points to where the source is located. For a graphical representation of source locations, see the ":ref:`overview-manual/concepts:sources`" section in the Yocto Project Overview and Concepts Manual. The :ref:`ref-tasks-fetch` task uses -the prefix of each entry in the ``SRC_URI`` variable value to determine +the prefix of each entry in the :term:`SRC_URI` variable value to determine which :ref:`fetcher <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` to use to get your -source files. It is the ``SRC_URI`` variable that triggers the fetcher. +source files. It is the :term:`SRC_URI` variable that triggers the fetcher. The :ref:`ref-tasks-patch` task uses the variable after source is fetched to apply patches. The OpenEmbedded build system uses :term:`FILESOVERRIDES` for -scanning directory locations for local files in ``SRC_URI``. +scanning directory locations for local files in :term:`SRC_URI`. -The ``SRC_URI`` variable in your recipe must define each unique location +The :term:`SRC_URI` variable in your recipe must define each unique location for your source files. It is good practice to not hard-code version numbers in a URL used in ``SRC_URI``. Rather than hard-code these values, use ``${``\ :term:`PV`\ ``}``, @@ -1352,12 +1315,11 @@ recipe to match the new version. Here is a simple example from the ``meta/recipes-devtools/strace/strace_5.5.bb`` recipe where the source comes from a single tarball. Notice the use of the -:term:`PV` variable: -:: +:term:`PV` variable:: SRC_URI = "https://strace.io/files/${PV}/strace-${PV}.tar.xz \ -Files mentioned in ``SRC_URI`` whose names end in a typical archive +Files mentioned in :term:`SRC_URI` whose names end in a typical archive extension (e.g. ``.tar``, ``.tar.gz``, ``.tar.bz2``, ``.zip``, and so forth), are automatically extracted during the :ref:`ref-tasks-unpack` task. For @@ -1369,8 +1331,7 @@ you must specify :term:`SRCREV` and you should specify :term:`PV` to include the revision with :term:`SRCPV`. Here is an example from the recipe -``meta/recipes-kernel/blktrace/blktrace_git.bb``: -:: +``meta/recipes-kernel/blktrace/blktrace_git.bb``:: SRCREV = "d6918c8832793b4205ed3bfede78c2f915c23385" @@ -1380,20 +1341,19 @@ is an example from the recipe SRC_URI = "git://git.kernel.dk/blktrace.git \ file://ldflags.patch" -If your ``SRC_URI`` statement includes URLs pointing to individual files +If your :term:`SRC_URI` statement includes URLs pointing to individual files fetched from a remote server other than a version control system, BitBake attempts to verify the files against checksums defined in your recipe to ensure they have not been tampered with or otherwise modified since the recipe was written. Two checksums are used: ``SRC_URI[md5sum]`` and ``SRC_URI[sha256sum]``. -If your ``SRC_URI`` variable points to more than a single URL (excluding +If your :term:`SRC_URI` variable points to more than a single URL (excluding SCM URLs), you need to provide the ``md5`` and ``sha256`` checksums for each URL. For these cases, you provide a name for each URL as part of -the ``SRC_URI`` and then reference that name in the subsequent checksum +the :term:`SRC_URI` and then reference that name in the subsequent checksum statements. Here is an example combining lines from the files -``git.inc`` and ``git_2.24.1.bb``: -:: +``git.inc`` and ``git_2.24.1.bb``:: SRC_URI = "${KERNELORG_MIRROR}/software/scm/git/git-${PV}.tar.gz;name=tarball \ ${KERNELORG_MIRROR}/software/scm/git/git-manpages-${PV}.tar.gz;name=manpages" @@ -1409,7 +1369,7 @@ with other signatures on the download page for the upstream source (e.g. OpenEmbedded build system only deals with ``sha256sum`` and ``md5sum``, you should verify all the signatures you find by hand. -If no ``SRC_URI`` checksums are specified when you attempt to build the +If no :term:`SRC_URI` checksums are specified when you attempt to build the recipe, or you provide an incorrect checksum, the build will produce an error for each missing or incorrect checksum. As part of the error message, the build system provides the checksum string corresponding to @@ -1425,7 +1385,7 @@ paste them into your recipe and then run the build again to continue. This final example is a bit more complicated and is from the ``meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.20.bb`` recipe. The -example's ``SRC_URI`` statement identifies multiple files as the source +example's :term:`SRC_URI` statement identifies multiple files as the source files for the recipe: a tarball, a patch file, a desktop file, and an icon. :: @@ -1464,9 +1424,9 @@ If you are fetching your source files from an upstream source archived tarball and the tarball's internal structure matches the common convention of a top-level subdirectory named ``${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``, -then you do not need to set ``S``. However, if ``SRC_URI`` specifies to +then you do not need to set :term:`S`. However, if :term:`SRC_URI` specifies to fetch source from an archive that does not use this convention, or from -an SCM like Git or Subversion, your recipe needs to define ``S``. +an SCM like Git or Subversion, your recipe needs to define :term:`S`. If processing your recipe using BitBake successfully unpacks the source files, you need to be sure that the directory pointed to by ``${S}`` @@ -1476,7 +1436,7 @@ Patching Code ------------- Sometimes it is necessary to patch code after it has been fetched. Any -files mentioned in ``SRC_URI`` whose names end in ``.patch`` or +files mentioned in :term:`SRC_URI` whose names end in ``.patch`` or ``.diff`` or compressed versions of these suffixes (e.g. ``diff.gz`` are treated as patches. The :ref:`ref-tasks-patch` task @@ -1485,7 +1445,7 @@ automatically applies these patches. The build system should be able to apply patches with the "-p1" option (i.e. one directory level in the path will be stripped off). If your patch needs to have more directory levels stripped off, specify the -number of levels using the "striplevel" option in the ``SRC_URI`` entry +number of levels using the "striplevel" option in the :term:`SRC_URI` entry for the patch. Alternatively, if your patch needs to be applied in a specific subdirectory that is not specified in the patch file, use the "patchdir" option in the entry. @@ -1505,25 +1465,24 @@ Your recipe needs to have both the :term:`LIC_FILES_CHKSUM` variables: -- ``LICENSE``: This variable specifies the license for the software. +- :term:`LICENSE`: This variable specifies the license for the software. If you do not know the license under which the software you are building is distributed, you should go to the source code and look for that information. Typical files containing this information - include ``COPYING``, ``LICENSE``, and ``README`` files. You could + include ``COPYING``, :term:`LICENSE`, and ``README`` files. You could also find the information near the top of a source file. For example, given a piece of software licensed under the GNU General Public - License version 2, you would set ``LICENSE`` as follows: - :: + License version 2, you would set :term:`LICENSE` as follows:: LICENSE = "GPLv2" - The licenses you specify within ``LICENSE`` can have any name as long + The licenses you specify within :term:`LICENSE` can have any name as long as you do not use spaces, since spaces are used as separators between license names. For standard licenses, use the names of the files in - ``meta/files/common-licenses/`` or the ``SPDXLICENSEMAP`` flag names + ``meta/files/common-licenses/`` or the :term:`SPDXLICENSEMAP` flag names defined in ``meta/conf/licenses.conf``. -- ``LIC_FILES_CHKSUM``: The OpenEmbedded build system uses this +- :term:`LIC_FILES_CHKSUM`: The OpenEmbedded build system uses this variable to make sure the license text has not changed. If it has, the build produces an error and it affords you the chance to figure it out and correct the problem. @@ -1533,18 +1492,17 @@ variables: the checksums of the files to be sure the text has not changed. Any differences result in an error with the message containing the current checksum. For more explanation and examples of how to set the - ``LIC_FILES_CHKSUM`` variable, see the + :term:`LIC_FILES_CHKSUM` variable, see the ":ref:`dev-manual/common-tasks:tracking license changes`" section. To determine the correct checksum string, you can list the - appropriate files in the ``LIC_FILES_CHKSUM`` variable with incorrect + appropriate files in the :term:`LIC_FILES_CHKSUM` variable with incorrect md5 strings, attempt to build the software, and then note the resulting error messages that will report the correct md5 strings. See the ":ref:`dev-manual/common-tasks:fetching code`" section for additional information. - Here is an example that assumes the software has a ``COPYING`` file: - :: + Here is an example that assumes the software has a ``COPYING`` file:: LIC_FILES_CHKSUM = "file://COPYING;md5=xxx" @@ -1563,8 +1521,8 @@ software is built; and runtime dependencies, which are required to be installed on the target in order for the software to run. Within a recipe, you specify build-time dependencies using the -:term:`DEPENDS` variable. Although -nuances exist, items specified in ``DEPENDS`` should be names of other +:term:`DEPENDS` variable. Although there are nuances, +items specified in :term:`DEPENDS` should be names of other recipes. It is important that you specify all build-time dependencies explicitly. @@ -1631,7 +1589,7 @@ your software is built: - *Autotools:* If your source files have a ``configure.ac`` file, then your software is built using Autotools. If this is the case, you just - need to worry about modifying the configuration. + need to modify the configuration. When using Autotools, your recipe needs to inherit the :ref:`autotools <ref-classes-autotools>` class @@ -1645,7 +1603,7 @@ your software is built: - *CMake:* If your source files have a ``CMakeLists.txt`` file, then your software is built using CMake. If this is the case, you just - need to worry about modifying the configuration. + need to modify the configuration. When you use CMake, your recipe needs to inherit the :ref:`cmake <ref-classes-cmake>` class and your @@ -1681,12 +1639,12 @@ your software is built: Once configuration succeeds, it is always good practice to look at the ``log.do_configure`` file to ensure that the appropriate options have been enabled and no additional build-time dependencies need to be added -to ``DEPENDS``. For example, if the configure script reports that it -found something not mentioned in ``DEPENDS``, or that it did not find +to :term:`DEPENDS`. For example, if the configure script reports that it +found something not mentioned in :term:`DEPENDS`, or that it did not find something that it needed for some desired optional functionality, then -you would need to add those to ``DEPENDS``. Looking at the log might +you would need to add those to :term:`DEPENDS`. Looking at the log might also reveal items being checked for, enabled, or both that you do not -want, or items not being found that are in ``DEPENDS``, in which case +want, or items not being found that are in :term:`DEPENDS`, in which case you would need to look at passing extra options to the configure script as needed. For reference information on configure options specific to the software you are building, you can consult the output of the @@ -1747,8 +1705,7 @@ standard mainline kernel, not your own custom one. When you use custom kernel headers you need to get them from :term:`STAGING_KERNEL_DIR`, which is the directory with kernel headers that are required to build -out-of-tree modules. Your recipe will also need the following: -:: +out-of-tree modules. Your recipe will also need the following:: do_configure[depends] += "virtual/kernel:do_shared_workdir" @@ -1779,8 +1736,7 @@ Here are some common issues that cause failures. To fix the problem, you need to either satisfy the missing dependency in the Makefile or whatever script produced the Makefile, or (as a - workaround) set :term:`PARALLEL_MAKE` to an empty string: - :: + workaround) set :term:`PARALLEL_MAKE` to an empty string:: PARALLEL_MAKE = "" @@ -1806,13 +1762,13 @@ Here are some common issues that cause failures. compilation process notes that files could not be found. In these cases, you need to go back and add additional options to the configure script as well as possibly add additional build-time - dependencies to ``DEPENDS``. + dependencies to :term:`DEPENDS`. Occasionally, it is necessary to apply a patch to the source to ensure the correct paths are used. If you need to specify paths to find files staged into the sysroot from other recipes, use the variables that the OpenEmbedded build system provides (e.g. - ``STAGING_BINDIR``, ``STAGING_INCDIR``, ``STAGING_DATADIR``, and so + :term:`STAGING_BINDIR`, :term:`STAGING_INCDIR`, :term:`STAGING_DATADIR`, and so forth). Installing @@ -1889,8 +1845,7 @@ installed correctly. 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 - parallel Makefile installs by adding the following to the recipe: - :: + parallel Makefile installs by adding the following to the recipe:: PARALLEL_MAKEINST = "" @@ -2006,8 +1961,7 @@ take. The following list describes the process: :term:`MACHINE` value is passed into the configure script or a patch is applied only for a particular machine), you should mark them as such by adding the following to the - recipe: - :: + recipe:: PACKAGE_ARCH = "${MACHINE_ARCH}" @@ -2016,8 +1970,7 @@ take. The following list describes the process: all (e.g. recipes that simply package script files or configuration files), you should use the :ref:`allarch <ref-classes-allarch>` class to - do this for you by adding this to your recipe: - :: + do this for you by adding this to your recipe:: inherit allarch @@ -2061,8 +2014,7 @@ used by the :ref:`ref-tasks-populate_sysroot` task as defined by the the :term:`SYSROOT_DIRS` variable to automatically populate the sysroot. It is possible to modify the list of directories that populate the sysroot. The following example shows how you could add the ``/opt`` directory to -the list of directories within a recipe: -:: +the list of directories within a recipe:: SYSROOT_DIRS += "/opt" @@ -2070,7 +2022,7 @@ the list of directories within a recipe: The `/sysroot-only` is to be used by recipes that generate artifacts that are not included in the target filesystem, allowing them to share - these artifacts without needing to use the ``DEPLOY_DIR``. + these artifacts without needing to use the :term:`DEPLOY_DIR`. For a more complete description of the :ref:`ref-tasks-populate_sysroot` task and its associated functions, see the @@ -2091,13 +2043,12 @@ kernel recipe. Suppose you have three kernel recipes whose in some way uses a :term:`PROVIDES` statement that essentially identifies itself as being able to provide ``virtual/kernel``. Here is one way through the -:ref:`kernel <ref-classes-kernel>` class: -:: +:ref:`kernel <ref-classes-kernel>` class:: PROVIDES += "${@ "virtual/kernel" if (d.getVar("KERNEL_PACKAGE_NAME") == "kernel") else "" }" Any recipe that inherits the ``kernel`` class is -going to utilize a ``PROVIDES`` statement that identifies that recipe as +going to utilize a :term:`PROVIDES` statement that identifies that recipe as being able to provide the ``virtual/kernel`` item. Now comes the time to actually build an image and you need a kernel @@ -2107,8 +2058,7 @@ an example, consider the :yocto_git:`x86-base.inc </poky/tree/meta/conf/machine/include/x86-base.inc>` include file, which is a machine (i.e. :term:`MACHINE`) configuration file. This include file is the reason all x86-based machines use the ``linux-yocto`` kernel. Here are the -relevant lines from the include file: -:: +relevant lines from the include file:: PREFERRED_PROVIDER_virtual/kernel ??= "linux-yocto" PREFERRED_VERSION_linux-yocto ??= "4.15%" @@ -2116,24 +2066,22 @@ relevant lines from the include file: When you use a virtual provider, you do not have to "hard code" a recipe name as a build dependency. You can use the :term:`DEPENDS` variable to state the -build is dependent on ``virtual/kernel`` for example: -:: +build is dependent on ``virtual/kernel`` for example:: DEPENDS = "virtual/kernel" During the build, the OpenEmbedded build system picks the correct recipe needed for the ``virtual/kernel`` dependency based on -the ``PREFERRED_PROVIDER`` variable. If you want to use the small kernel +the :term:`PREFERRED_PROVIDER` variable. If you want to use the small kernel mentioned at the beginning of this section, configure your build as -follows: -:: +follows:: PREFERRED_PROVIDER_virtual/kernel ??= "kernel-small" .. note:: - Any recipe that ``PROVIDES`` a ``virtual/*`` item that is ultimately not - selected through ``PREFERRED_PROVIDER`` does not get built. Preventing these + Any recipe that :term:`PROVIDES` a ``virtual/*`` item that is ultimately not + selected through :term:`PREFERRED_PROVIDER` does not get built. Preventing these recipes from building is usually the desired behavior since this mechanism's purpose is to select between mutually exclusive alternative providers. @@ -2178,8 +2126,7 @@ In order to ensure the versions compare properly, the recommended convention is to set :term:`PV` within the recipe to "previous_version+current_version". You can use an additional variable so that you can use the current version elsewhere. Here is an -example: -:: +example:: REALPV = "0.8.16-rc1" PV = "0.8.15+${REALPV}" @@ -2198,8 +2145,7 @@ required, specify ``${``\ :term:`PN`\ ``}`` in place of PACKAGENAME. -A post-installation function has the following structure: -:: +A post-installation function has the following structure:: pkg_postinst_PACKAGENAME() { # Commands to carry out @@ -2237,8 +2183,8 @@ script to first boot is undesirable and for read-only rootfs impossible. .. note:: - Equivalent support for pre-install, pre-uninstall, and post-uninstall - scripts exist by way of ``pkg_preinst``, ``pkg_prerm``, and ``pkg_postrm``, + There is equivalent support for pre-install, pre-uninstall, and post-uninstall + scripts by way of ``pkg_preinst``, ``pkg_prerm``, and ``pkg_postrm``, respectively. These scrips work in exactly the same way as does ``pkg_postinst`` with the exception that they run at different times. Also, because of when they run, they are not applicable to being run at image @@ -2275,8 +2221,8 @@ 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 -``SRC_URI`` variable. Additionally, you need to manually write the -``do_compile`` and ``do_install`` tasks. The ``S`` variable defines the +:term:`SRC_URI` variable. Additionally, you need to manually write the +``do_compile`` and ``do_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. @@ -2310,7 +2256,7 @@ Autotooled Package ~~~~~~~~~~~~~~~~~~ Applications that use Autotools such as ``autoconf`` and ``automake`` -require a recipe that has a source archive listed in ``SRC_URI`` and +require a recipe that has a source archive listed in :term:`SRC_URI` and also inherit the :ref:`autotools <ref-classes-autotools>` class, which contains the definitions of all the steps needed to build an @@ -2329,7 +2275,7 @@ Following is one example: (``hello_2.3.bb``) inherit autotools gettext -The variable ``LIC_FILES_CHKSUM`` is used to track source license +The variable :term:`LIC_FILES_CHKSUM` is used to track source license changes as described in the ":ref:`dev-manual/common-tasks:tracking license changes`" section in the Yocto Project Overview and Concepts Manual. You can quickly create @@ -2339,7 +2285,7 @@ Makefile-Based Package ~~~~~~~~~~~~~~~~~~~~~~ Applications that use GNU ``make`` also require a recipe that has the -source archive listed in ``SRC_URI``. You do not need to add a +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 to compile the application. If you need additional ``make`` options, you should store them in the @@ -2351,14 +2297,12 @@ Otherwise, BitBake runs an empty ``do_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 -path. You can accomplish this by adding to the ``CFLAGS`` variable. The -following example shows this: -:: +path. You can accomplish this by adding to the :term:`CFLAGS` variable. The +following example shows this:: CFLAGS_prepend = "-I ${S}/include " -In the following example, ``mtd-utils`` is a makefile-based package: -:: +In the following example, ``mtd-utils`` is a makefile-based package:: SUMMARY = "Tools for managing memory technology devices" SECTION = "base" @@ -2397,14 +2341,13 @@ In the following example, ``mtd-utils`` is a makefile-based package: Splitting an Application into Multiple Packages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can use the variables ``PACKAGES`` and ``FILES`` to split an +You can use the variables :term:`PACKAGES` and :term:`FILES` to split an application into multiple packages. Following is an example that uses the ``libxpm`` recipe. By default, this recipe generates a single package that contains the library along with a few binaries. You can modify the recipe to split the binaries -into separate packages: -:: +into separate packages:: require xorg-lib-common.inc @@ -2422,18 +2365,18 @@ into separate packages: In the previous example, we want to ship the ``sxpm`` and ``cxpm`` binaries in separate packages. Since ``bindir`` would be packaged into -the main ``PN`` package by default, we prepend the ``PACKAGES`` variable +the main :term:`PN` package by default, we prepend the :term:`PACKAGES` variable so additional package names are added to the start of list. This results in the extra ``FILES_*`` variables then containing information that define which files and directories go into which packages. Files included by earlier packages are skipped by latter packages. Thus, the -main ``PN`` package does not include the above listed files. +main :term:`PN` package does not include the above listed files. Packaging Externally Produced Binaries ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sometimes, you need to add pre-compiled binaries to an image. For -example, suppose that binaries for proprietary code exist, which are +example, suppose that there are binaries for proprietary code, created by a particular division of a company. Your part of the company needs to use those binaries as part of an image that you are building using the OpenEmbedded build system. Since you only have the binaries @@ -2472,12 +2415,12 @@ Reference Manual's variable glossary. - Using :term:`DEPENDS` is a good idea even for components distributed in binary form, and is often necessary for shared libraries. For a shared library, listing the - library dependencies in ``DEPENDS`` makes sure that the libraries + library dependencies in :term:`DEPENDS` makes sure that the libraries are available in the staging sysroot when other recipes link against the library, which might be necessary for successful linking. - - Using ``DEPENDS`` also allows runtime dependencies between + - Using :term:`DEPENDS` also allows runtime dependencies between packages to be added automatically. See the ":ref:`overview-manual/concepts:automatically added runtime dependencies`" section in the Yocto Project Overview and Concepts Manual for more @@ -2498,8 +2441,7 @@ doing the following: that replaces ``do_configure`` and ``do_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: - :: + flag to turn the tasks into no-ops, as follows:: do_configure[noexec] = "1" do_compile[noexec] = "1" @@ -2558,8 +2500,7 @@ chapter of the BitBake User Manual. supported. The following example shows some of the ways you can use variables in - recipes: - :: + recipes:: S = "${WORKDIR}/postfix-${PV}" CFLAGS += "-DNO_ASM" @@ -2572,8 +2513,7 @@ chapter of the BitBake User Manual. syntax, although access to OpenEmbedded variables and internal methods are also available. - The following is an example function from the ``sed`` recipe: - :: + Here is an example function from the ``sed`` recipe:: do_install () { autotools_do_install @@ -2594,16 +2534,14 @@ chapter of the BitBake User Manual. from other files (``include`` and ``require``) and export variables to the environment (``export``). - The following example shows the use of some of these keywords: - :: + The following example shows the use of some of these keywords:: export POSTCONF = "${STAGING_BINDIR}/postconf" inherit autoconf require otherfile.inc - *Comments (#):* Any lines that begin with the hash character (``#``) - are treated as comment lines and are ignored: - :: + are treated as comment lines and are ignored:: # This is a comment @@ -2615,8 +2553,7 @@ in the BitBake User Manual. - *Line Continuation (\\):* Use the backward slash (``\``) character to split a statement over multiple lines. Place the slash character at - the end of the line that is to be continued on the next line: - :: + the end of the line that is to be continued on the next line:: VAR = "A really long \ line" @@ -2627,8 +2564,7 @@ in the BitBake User Manual. slash character. - *Using Variables (${VARNAME}):* Use the ``${VARNAME}`` syntax to - access the contents of a variable: - :: + access the contents of a variable:: SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" @@ -2648,8 +2584,7 @@ in the BitBake User Manual. when you make the assignment, but this is not generally needed. - *Quote All Assignments ("value"):* Use double quotes around values in - all variable assignments (e.g. ``"value"``). Following is an example: - :: + all variable assignments (e.g. ``"value"``). Following is an example:: VAR1 = "${OTHERVAR}" VAR2 = "The version is ${PV}" @@ -2663,13 +2598,11 @@ in the BitBake User Manual. Here is an example where ``VAR1`` is set to "New value" if it is currently empty. However, if ``VAR1`` has already been set, it - remains unchanged: - :: + remains unchanged:: VAR1 ?= "New value" - In this next example, ``VAR1`` is left with the value "Original value": - :: + In this next example, ``VAR1`` is left with the value "Original value":: VAR1 = "Original value" VAR1 ?= "New value" @@ -2682,8 +2615,7 @@ in the BitBake User Manual. This operator adds a space between the existing content of the variable and the new content. - Here is an example: - :: + Here is an example:: SRC_URI += "file://fix-makefile.patch" @@ -2695,8 +2627,7 @@ in the BitBake User Manual. This operator adds a space between the new content and the existing content of the variable. - Here is an example: - :: + Here is an example:: VAR =+ "Starts" @@ -2708,15 +2639,13 @@ in the BitBake User Manual. The following example shows the space being explicitly added to the start to ensure the appended value is not merged with the existing - value: - :: + value:: SRC_URI_append = " file://fix-makefile.patch" You can also use the ``_append`` operator with overrides, which results in the actions - only being performed for the specified target or machine: - :: + only being performed for the specified target or machine:: SRC_URI_append_sh4 = " file://fix-makefile.patch" @@ -2728,15 +2657,13 @@ in the BitBake User Manual. The following example shows the space being explicitly added to the end to ensure the prepended value is not merged with the existing - value: - :: + value:: CFLAGS_prepend = "-I${S}/myincludes " You can also use the ``_prepend`` operator with overrides, which results in the actions - only being performed for the specified target or machine: - :: + only being performed for the specified target or machine:: CFLAGS_prepend_sh4 = "-I${S}/myincludes " @@ -2746,8 +2673,7 @@ in the BitBake User Manual. value to "standard/base" for any target :term:`MACHINE`, except for qemuarm where it should be set to "standard/arm-versatile-926ejs", - you would do the following: - :: + you would do the following:: KBRANCH = "standard/base" KBRANCH_qemuarm = "standard/arm-versatile-926ejs" @@ -2770,8 +2696,7 @@ in the BitBake User Manual. search and replacement on a variable). You indicate Python code using the ``${@python_code}`` syntax for the - variable assignment: - :: + variable assignment:: SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz @@ -2822,7 +2747,7 @@ file or include from a lower-level configuration file are as follows: - ``PREFERRED_PROVIDER_virtual/kernel`` -- ``MACHINE_FEATURES`` (e.g. "apm screen wifi") +- :term:`MACHINE_FEATURES` (e.g. "apm screen wifi") You might also need these variables: @@ -2830,7 +2755,7 @@ You might also need these variables: - ``KERNEL_IMAGETYPE`` (e.g. "zImage") -- ``IMAGE_FSTYPES`` (e.g. "tar.gz jffs2") +- :term:`IMAGE_FSTYPES` (e.g. "tar.gz jffs2") You can find full details on these variables in the reference section. You can leverage existing machine ``.conf`` files from @@ -2846,8 +2771,8 @@ examples in the Source Directory at ``meta/recipes-kernel/linux`` that you can use as references. If you are creating a new kernel recipe, normal recipe-writing rules -apply for setting up a ``SRC_URI``. Thus, you need to specify any -necessary patches and set ``S`` to point at the source code. You need to +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 a ``defconfig`` file. You can do this by using a ``make defconfig`` command or, more commonly, by copying in a suitable ``defconfig`` file @@ -2860,9 +2785,8 @@ If you are extending an existing kernel recipe, it is usually a matter of adding a suitable ``defconfig`` file. The file needs to be added into a location similar to ``defconfig`` files used for other machines in a given kernel recipe. A possible way to do this is by listing the file in -the ``SRC_URI`` and adding the machine to the expression in -``COMPATIBLE_MACHINE``: -:: +the :term:`SRC_URI` and adding the machine to the expression in +:term:`COMPATIBLE_MACHINE`:: COMPATIBLE_MACHINE = '(qemux86|qemumips)' @@ -2889,8 +2813,7 @@ contains directories for specific machines such as ``qemuarm`` and defaults, see the ``meta/recipes-bsp/formfactor/files/config`` file found in the same area. -Following is an example for "qemuarm" machine: -:: +Following is an example for "qemuarm" machine:: HAVE_TOUCHSCREEN=1 HAVE_KEYBOARD=1 @@ -2909,7 +2832,7 @@ Over time, upstream developers publish new versions for software built by layer recipes. It is recommended to keep recipes up-to-date with upstream version releases. -While several methods exist that allow you upgrade a recipe, you might +While there are several methods to upgrade a recipe, you might consider checking on the upgrade status of a recipe first. You can do so using the ``devtool check-upgrade-status`` command. See the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" @@ -2938,8 +2861,8 @@ commit messages in the layer's tree for the changes made to recipes. .. note:: - Conditions do exist when you should not use AUH to upgrade recipes - and you should instead use either ``devtool upgrade`` or upgrade your + In some conditions, you should not use AUH to upgrade recipes + and should instead use either ``devtool upgrade`` or upgrade your recipes manually: - When AUH cannot complete the upgrade sequence. This situation @@ -2961,22 +2884,19 @@ The following steps describe how to set up the AUH utility: 2. *Make Sure Git is Configured:* The AUH utility requires Git to be configured because AUH uses Git to save upgrades. Thus, you must have Git user and email configured. The following command shows your - configurations: - :: + configurations:: $ git config --list If you do not have the user and - email configured, you can use the following commands to do so: - :: + email configured, you can use the following commands to do so:: $ git config --global user.name some_name $ git config --global user.email username@domain.com 3. *Clone the AUH Repository:* To use AUH, you must clone the repository onto your development host. The following command uses Git to create - a local copy of the repository on your system: - :: + a local copy of the repository on your system:: $ git clone git://git.yoctoproject.org/auto-upgrade-helper Cloning into 'auto-upgrade-helper'... remote: Counting objects: 768, done. @@ -2992,8 +2912,7 @@ The following steps describe how to set up the AUH utility: 4. *Create a Dedicated Build Directory:* Run the :ref:`structure-core-script` script to create a fresh build directory that you use exclusively for - running the AUH utility: - :: + running the AUH utility:: $ cd poky $ source oe-init-build-env your_AUH_build_directory @@ -3003,15 +2922,14 @@ The following steps describe how to set up the AUH utility: undesirably. 5. *Make Configurations in Your Local Configuration File:* Several - settings need to exist in the ``local.conf`` file in the build + settings are needed in the ``local.conf`` file in the build directory you just created for AUH. Make these following configurations: - If you want to enable :ref:`Build History <dev-manual/common-tasks:maintaining build output quality>`, which is optional, you need the following lines in the - ``conf/local.conf`` file: - :: + ``conf/local.conf`` file:: INHERIT =+ "buildhistory" BUILDHISTORY_COMMIT = "1" @@ -3024,23 +2942,20 @@ The following steps describe how to set up the AUH utility: - If you want to enable testing through the :ref:`testimage <ref-classes-testimage*>` class, which is optional, you need to have the following set in - your ``conf/local.conf`` file: - :: + your ``conf/local.conf`` file:: INHERIT += "testimage" .. note:: If your distro does not enable by default ptest, which Poky - does, you need the following in your ``local.conf`` file: - :: + does, you need the following in your ``local.conf`` file:: DISTRO_FEATURES_append = " ptest" 6. *Optionally Start a vncserver:* If you are running in a server - without an X11 session, you need to start a vncserver: - :: + without an X11 session, you need to start a vncserver:: $ vncserver :1 $ export DISPLAY=:1 @@ -3064,45 +2979,38 @@ The following steps describe how to set up the AUH utility: This next set of examples describes how to use the AUH: - *Upgrading a Specific Recipe:* To upgrade a specific recipe, use the - following form: - :: + following form:: $ upgrade-helper.py recipe_name - For example, this command upgrades the ``xmodmap`` recipe: - :: + For example, this command upgrades the ``xmodmap`` recipe:: $ upgrade-helper.py xmodmap - *Upgrading a Specific Recipe to a Particular Version:* To upgrade a - specific recipe to a particular version, use the following form: - :: + specific recipe to a particular version, use the following form:: $ upgrade-helper.py recipe_name -t version - For example, this command upgrades the ``xmodmap`` recipe to version 1.2.3: - :: + For example, this command upgrades the ``xmodmap`` recipe to version 1.2.3:: $ upgrade-helper.py xmodmap -t 1.2.3 - *Upgrading all Recipes to the Latest Versions and Suppressing Email Notifications:* To upgrade all recipes to their most recent versions - and suppress the email notifications, use the following command: - :: + and suppress the email notifications, use the following command:: $ upgrade-helper.py all - *Upgrading all Recipes to the Latest Versions and Send Email Notifications:* To upgrade all recipes to their most recent versions and send email messages to maintainers for each attempted recipe as - well as a status email, use the following command: - :: + well as a status email, use the following command:: $ upgrade-helper.py -e all Once you have run the AUH utility, you can find the results in the AUH -build directory: -:: +build directory:: ${BUILDDIR}/upgrade-helper/timestamp @@ -3127,15 +3035,13 @@ section in the Yocto Project Application Development and the Extensible Software Development Kit (eSDK) Manual. To see all the command-line options available with ``devtool upgrade``, -use the following help command: -:: +use the following help command:: $ devtool upgrade -h If you want to find out what version a recipe is currently at upstream without any attempt to upgrade your local version of the recipe, you can -use the following command: -:: +use the following command:: $ devtool latest-version recipe_name @@ -3161,15 +3067,13 @@ could add it easily using the ":ref:`bitbake-layers <bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script>`" script. For example, suppose you use the ``nano.bb`` recipe from the ``meta-oe`` layer in the ``meta-openembedded`` repository. For this -example, assume that the layer has been cloned into following area: -:: +example, assume that the layer has been cloned into following area:: /home/scottrif/meta-openembedded The following command from your :term:`Build Directory` adds the layer to -your build configuration (i.e. ``${BUILDDIR}/conf/bblayers.conf``): -:: +your build configuration (i.e. ``${BUILDDIR}/conf/bblayers.conf``):: $ bitbake-layers add-layer /home/scottrif/meta-openembedded/meta-oe NOTE: Starting bitbake server... @@ -3210,8 +3114,7 @@ directory automatically upgrades the recipe for you: NOTE: New recipe is /home/scottrif/poky/build/workspace/recipes/nano/nano_2.9.3.bb Continuing with this example, you can use ``devtool build`` to build the -newly upgraded recipe: -:: +newly upgraded recipe:: $ devtool build nano NOTE: Starting bitbake server... @@ -3228,16 +3131,15 @@ newly upgraded recipe: NOTE: nano: compiling from external source tree /home/scottrif/poky/build/workspace/sources/nano NOTE: Tasks Summary: Attempted 520 tasks of which 304 didn't need to be rerun and all succeeded. -Within the ``devtool upgrade`` workflow, opportunity -exists to deploy and test your rebuilt software. For this example, +Within the ``devtool upgrade`` workflow, you can +deploy and test your rebuilt software. For this example, however, running ``devtool finish`` cleans up the workspace once the source in your workspace is clean. This usually means using Git to stage and submit commits for the changes generated by the upgrade process. Once the tree is clean, you can clean things up in this example with the following command from the ``${BUILDDIR}/workspace/sources/nano`` -directory: -:: +directory:: $ devtool finish nano meta-oe NOTE: Starting bitbake server... @@ -3276,9 +3178,9 @@ To manually upgrade recipe versions, follow these general steps: 1. *Change the Version:* Rename the recipe such that the version (i.e. the :term:`PV` part of the recipe name) changes appropriately. If the version is not part of the recipe name, - change the value as it is set for ``PV`` within the recipe itself. + change the value as it is set for :term:`PV` within the recipe itself. -2. *Update* ``SRCREV`` *if Needed*: If the source code your recipe builds +2. *Update* :term:`SRCREV` *if Needed*: If the source code your recipe builds is fetched from Git or some other version control system, update :term:`SRCREV` to point to the commit hash that matches the new version. @@ -3312,7 +3214,7 @@ To manually upgrade recipe versions, follow these general steps: if the recipe is to be released publicly. 5. *Check the Upstream Change Log or Release Notes:* Checking both these - reveals if new features exist that could break + reveals if there are new features that could break backwards-compatibility. If so, you need to take steps to mitigate or eliminate that situation. @@ -3339,30 +3241,27 @@ patches. During a build, the unpacked temporary source code used by recipes to build packages is available in the Build Directory as defined by the :term:`S` variable. Below is the default -value for the ``S`` variable as defined in the +value for the :term:`S` variable as defined in the ``meta/conf/bitbake.conf`` configuration file in the -:term:`Source Directory`: -:: +:term:`Source Directory`:: S = "${WORKDIR}/${BP}" You should be aware that many recipes override the -``S`` variable. For example, recipes that fetch their source from Git -usually set ``S`` to ``${WORKDIR}/git``. +:term:`S` variable. For example, recipes that fetch their source from Git +usually set :term:`S` to ``${WORKDIR}/git``. .. note:: The :term:`BP` represents the base recipe name, which consists of the name - and version: - :: + and version:: BP = "${BPN}-${PV}" The path to the work directory for the recipe (:term:`WORKDIR`) is defined as -follows: -:: +follows:: ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} @@ -3388,8 +3287,7 @@ As an example, assume a Source Directory top-level folder named ``poky``, a default Build Directory at ``poky/build``, and a ``qemux86-poky-linux`` machine target system. Furthermore, suppose your recipe is named ``foo_1.3.0.bb``. In this case, the work directory the -build system uses to build the package would be as follows: -:: +build system uses to build the package would be as follows:: poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 @@ -3426,15 +3324,13 @@ Follow these general steps: 3. *Create a New Patch:* Before modifying source code, you need to create a new patch. To create a new patch file, use ``quilt new`` as - below: - :: + below:: $ quilt new my_changes.patch 4. *Notify Quilt and Add Files:* After creating the patch, you need to notify Quilt about the files you plan to edit. You notify Quilt by - adding the files to the patch you just created: - :: + adding the files to the patch you just created:: $ quilt add file1.c file2.c file3.c @@ -3443,8 +3339,7 @@ Follow these general steps: 6. *Test Your Changes:* Once you have modified the source code, the easiest way to test your changes is by calling the ``do_compile`` - task as shown in the following example: - :: + task as shown in the following example:: $ bitbake -c compile -f package @@ -3474,15 +3369,14 @@ Follow these general steps: ``file2.c``, and ``file3.c`` files. You can find the resulting patch file in the ``patches/`` - subdirectory of the source (``S``) directory. + subdirectory of the source (:term:`S`) directory. 8. *Copy the Patch File:* For simplicity, copy the patch file into a directory named ``files``, which you can create in the same directory that holds the recipe (``.bb``) file or the append (``.bbappend``) file. Placing the patch here guarantees that the OpenEmbedded build - system will find the patch. Next, add the patch into the ``SRC_URI`` - of the recipe. Here is an example: - :: + system will find the patch. Next, add the patch into the :term:`SRC_URI` + of the recipe. Here is an example:: SRC_URI += "file://my_changes.patch" @@ -3503,8 +3397,7 @@ this way can be helpful when debugging a build or preparing software to be used with the OpenEmbedded build system. Following is an example that uses ``devshell`` on a target named -``matchbox-desktop``: -:: +``matchbox-desktop``:: $ bitbake matchbox-desktop -c devshell @@ -3533,8 +3426,7 @@ corresponding ``run.*`` script in the directory (e.g., ``run.do_configure.``\ `pid`). If a task's script does not exist, which would be the case if the task was skipped by way of the sstate cache, you can create the task by first running it outside of the -``devshell``: -:: +``devshell``:: $ bitbake -c task @@ -3562,7 +3454,7 @@ terminal window. use the full compiler name such as ``arm-poky-linux-gnueabi-gcc`` instead of just using ``gcc``. The same applies to other applications such as ``binutils``, ``libtool`` and so forth. - BitBake sets up environment variables such as ``CC`` to assist + BitBake sets up environment variables such as :term:`CC` to assist applications, such as ``make`` to find the correct tools. - It is also worth noting that ``devshell`` still works over X11 @@ -3581,8 +3473,7 @@ specified target. Then a new terminal is opened. Additionally, key Python objects and code are available in the same way they are to BitBake tasks, in particular, the data store 'd'. So, commands such as the following are useful when exploring the data store and running -functions: -:: +functions:: pydevshell> d.getVar("STAGING_DIR") '/media/build1/poky/build/tmp/sysroots' @@ -3602,8 +3493,7 @@ helpful when debugging a build or preparing software to be used with the OpenEmbedded build system. Following is an example that uses ``devpyshell`` on a target named -``matchbox-desktop``: -:: +``matchbox-desktop``:: $ bitbake matchbox-desktop -c devpyshell @@ -3627,7 +3517,7 @@ Building a Simple Image In the development environment, you need to build an image whenever you change hardware support, add or change system libraries, or add or -change services that have dependencies. Several methods exist that allow +change services that have dependencies. There are several methods that allow you to build an image within the Yocto Project. This section presents the basic steps you need to build a simple image using BitBake from a build host running Linux. @@ -3664,8 +3554,7 @@ The following figure and list overviews the build process: 2. *Initialize the Build Environment:* Initialize the build environment by sourcing the build environment script (i.e. - :ref:`structure-core-script`): - :: + :ref:`structure-core-script`):: $ source oe-init-build-env [build_dir] @@ -3684,14 +3573,13 @@ The following figure and list overviews the build process: ``conf/local.conf`` configuration file, which is found in the Build Directory, is set up how you want it. This file defines many aspects of the build environment including the target machine architecture - through the ``MACHINE`` variable, the packaging format used during + through the :term:`MACHINE` variable, the packaging format used during the build (:term:`PACKAGE_CLASSES`), and a centralized tarball download directory through the :term:`DL_DIR` variable. -4. *Build the Image:* Build the image using the ``bitbake`` command: - :: +4. *Build the Image:* Build the image using the ``bitbake`` command:: $ bitbake target @@ -3710,8 +3598,7 @@ The following figure and list overviews the build process: Project Reference Manual. As an example, the following command builds the - ``core-image-minimal`` image: - :: + ``core-image-minimal`` image:: $ bitbake core-image-minimal @@ -3759,12 +3646,11 @@ Follow these steps to set up and execute multiple configuration builds: consider a scenario with two different multiconfigs for the same :term:`MACHINE`: "qemux86" built for two distributions such as "poky" and "poky-lsb". In this case, - you might want to use the same ``TMPDIR``. + you might want to use the same :term:`TMPDIR`. Here is an example showing the minimal statements needed in a configuration file for a "qemux86" target whose temporary build - directory is ``tmpmultix86``: - :: + directory is ``tmpmultix86``:: MACHINE = "qemux86" TMPDIR = "${TOPDIR}/tmpmultix86" @@ -3777,7 +3663,7 @@ Follow these steps to set up and execute multiple configuration builds: .. image:: figures/multiconfig_files.png :align: center - The reason for this required file hierarchy is because the ``BBPATH`` + The reason for this required file hierarchy is because the :term:`BBPATH` variable is not constructed until the layers are parsed. Consequently, using the configuration file as a pre-configuration file is not possible unless it is located in the current working @@ -3788,9 +3674,8 @@ Follow these steps to set up and execute multiple configuration builds: :term:`BBMULTICONFIG` variable in your ``conf/local.conf`` configuration file to specify each multiconfig. Continuing with the example from the previous - figure, the ``BBMULTICONFIG`` variable needs to enable two - multiconfigs: "x86" and "arm" by specifying each configuration file: - :: + figure, the :term:`BBMULTICONFIG` variable needs to enable two + multiconfigs: "x86" and "arm" by specifying each configuration file:: BBMULTICONFIG = "x86 arm" @@ -3804,13 +3689,11 @@ Follow these steps to set up and execute multiple configuration builds: with "". - *Launch BitBake*: Use the following BitBake command form to launch - the multiple configuration build: - :: + the multiple configuration build:: $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ] - For the example in this section, the following command applies: - :: + For the example in this section, the following command applies:: $ bitbake mc:x86:core-image-minimal mc:arm:core-image-sato mc::core-image-base @@ -3825,7 +3708,7 @@ Follow these steps to set up and execute multiple configuration builds: Support for multiple configuration builds in the Yocto Project &DISTRO; (&DISTRO_NAME;) Release does not include Shared State (sstate) optimizations. Consequently, if a build uses the same object twice - in, for example, two different ``TMPDIR`` + in, for example, two different :term:`TMPDIR` directories, the build either loads from an existing sstate cache for that build at the start or builds the object fresh. @@ -3844,15 +3727,13 @@ essentially that the To enable dependencies in a multiple configuration build, you must declare the dependencies in the recipe using the following statement -form: -:: +form:: task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend" To better show how to use this statement, consider the example scenario from the first paragraph of this section. The following statement needs -to be added to the recipe that builds the ``core-image-sato`` image: -:: +to be added to the recipe that builds the ``core-image-sato`` image:: do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_rootfs" @@ -3862,8 +3743,7 @@ task on which the ``do_image`` task in the recipe depends is the with the "arm" multiconfig. Once you set up this dependency, you can build the "x86" multiconfig -using a BitBake command as follows: -:: +using a BitBake command as follows:: $ bitbake mc:x86:core-image-sato @@ -3874,8 +3754,7 @@ dependency, BitBake also executes through the ``do_rootfs`` task for the Having a recipe depend on the root filesystem of another build might not seem that useful. Consider this change to the statement in the -``core-image-sato`` recipe: -:: +``core-image-sato`` recipe:: do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_image" @@ -3927,7 +3806,7 @@ Follow these steps to create an initramfs image: recipe and the initramfs recipe should the initramfs image include kernel modules. - Setting the ``INITRAMFS_IMAGE_BUNDLE`` flag causes the initramfs + Setting the :term:`INITRAMFS_IMAGE_BUNDLE` flag causes the 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` @@ -3949,7 +3828,7 @@ Follow these steps to create an initramfs image: :term:`PACKAGE_INSTALL` rather than :term:`IMAGE_INSTALL`. - ``PACKAGE_INSTALL`` gives more direct control of what is added to the + :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>` @@ -4033,7 +3912,7 @@ your own distribution that are likely modeled after ``poky-tiny``. .. note:: - To use ``poky-tiny`` in your build, set the ``DISTRO`` variable in your + To use ``poky-tiny`` in your build, set the :term:`DISTRO` variable in your ``local.conf`` file to "poky-tiny" as described in the ":ref:`dev-manual/common-tasks:creating your own distribution`" section. @@ -4091,8 +3970,7 @@ happens, which changes the way you build them. You can also modify the filesystem itself or select a different filesystem. First, find out what is hogging your root filesystem by running the -``dirsize.py`` script from your root directory: -:: +``dirsize.py`` script from your root directory:: $ cd root-directory-of-image $ dirsize.py 100000 > dirsize-100k.log @@ -4107,8 +3985,7 @@ the root filesystem that take up large amounts of memory. You need to be sure that what you eliminate does not cripple the functionality you need. One way to see how packages relate to each other -is by using the Dependency Explorer UI with the BitBake command: -:: +is by using the Dependency Explorer UI with the BitBake command:: $ cd image-directory $ bitbake -u taskexp -g image @@ -4124,8 +4001,7 @@ instead of ``udev``. Use your ``local.conf`` file to make changes. For example, to eliminate ``udev`` and ``glib``, set the following in the local configuration -file: -:: +file:: VIRTUAL-RUNTIME_dev_manager = "" @@ -4153,8 +4029,7 @@ building? Which drivers do you build by default? You can modify the kernel source if you want to help with boot time. Run the ``ksize.py`` script from the top-level Linux build directory to -get an idea of what is making up the kernel: -:: +get an idea of what is making up the kernel:: $ cd top-level-linux-build-directory $ ksize.py > ksize.log @@ -4168,8 +4043,7 @@ in a compressed kernel image. Look to reduce the areas that are large and taking up around the "90% rule." To examine, or drill down, into any particular area, use the ``-d`` -option with the script: -:: +option with the script:: $ ksize.py -d > ksize.log @@ -4282,17 +4156,17 @@ your tunings to best consider build times and package feed maintenance. :term:`TMPDIR` across builds. The Yocto Project supports switching between different :term:`MACHINE` values in the same - ``TMPDIR``. This practice is well supported and regularly used by + :term:`TMPDIR`. This practice is well supported and regularly used by developers when building for multiple machines. When you use the same - ``TMPDIR`` for multiple machine builds, the OpenEmbedded build system + :term:`TMPDIR` for multiple machine builds, the OpenEmbedded build system can reuse the existing native and often cross-recipes for multiple machines. Thus, build time decreases. .. note:: If :term:`DISTRO` settings change or fundamental configuration settings - such as the filesystem layout, you need to work with a clean ``TMPDIR``. - Sharing ``TMPDIR`` under these circumstances might work but since it is + such as the filesystem layout, you need to work with a clean :term:`TMPDIR`. + Sharing :term:`TMPDIR` under these circumstances might work but since it is not guaranteed, you should use a clean ``TMPDIR``. - *Enable the Appropriate Package Architecture:* By default, the @@ -4316,8 +4190,7 @@ your tunings to best consider build times and package feed maintenance. machine-architecture dependent, make sure your recipe enables the "machine" package architecture through the :term:`MACHINE_ARCH` - variable: - :: + variable:: PACKAGE_ARCH = "${MACHINE_ARCH}" @@ -4325,8 +4198,7 @@ your tunings to best consider build times and package feed maintenance. specifically enable a package architecture through the :term:`PACKAGE_ARCH`, The OpenEmbedded build system defaults to the - :term:`TUNE_PKGARCH` setting: - :: + :term:`TUNE_PKGARCH` setting:: PACKAGE_ARCH = "${TUNE_PKGARCH}" @@ -4343,7 +4215,7 @@ your tunings to best consider build times and package feed maintenance. sysroot for each machine is generated, the software is not recompiled and only one package feed exists. -- *Manage Granular Level Packaging:* Sometimes cases exist where +- *Manage Granular Level Packaging:* Sometimes there are cases where injecting another level of package architecture beyond the three higher levels noted earlier can be useful. For example, consider how NXP (formerly Freescale) allows for the easy reuse of binary packages @@ -4409,7 +4281,7 @@ By default, the OpenEmbedded build system uses the code. The build process involves fetching the source files, unpacking them, and then patching them if necessary before the build takes place. -Situations exist where you might want to build software from source +There are situations where you might want to build software from source files that are external to and thus outside of the OpenEmbedded build system. For example, suppose you have a project that includes a new BSP with a heavily customized kernel. And, you want to minimize exposing the @@ -4426,15 +4298,13 @@ to do is inherit the and then set the :term:`EXTERNALSRC` variable to point to your external source code. Here are the statements to put in -your ``local.conf`` file: -:: +your ``local.conf`` file:: INHERIT += "externalsrc" EXTERNALSRC_pn-myrecipe = "path-to-your-source-tree" This next example shows how to accomplish the same thing by setting -``EXTERNALSRC`` in the recipe itself or in the recipe's append file: -:: +:term:`EXTERNALSRC` in the recipe itself or in the recipe's append file:: EXTERNALSRC = "path" EXTERNALSRC_BUILD = "path" @@ -4451,8 +4321,7 @@ directory separate from the external source directory as specified by to have the source built in the same directory in which it resides, or some other nominated directory, you can set :term:`EXTERNALSRC_BUILD` -to point to that directory: -:: +to point to that directory:: EXTERNALSRC_BUILD_pn-myrecipe = "path-to-your-source-tree" @@ -4471,26 +4340,24 @@ Follow these steps to populate your Downloads directory: 1. *Create a Clean Downloads Directory:* Start with an empty downloads directory (:term:`DL_DIR`). You start with an empty downloads directory by either removing the files - in the existing directory or by setting ``DL_DIR`` to point to either + in the existing directory or by setting :term:`DL_DIR` to point to either an empty location or one that does not yet exist. 2. *Generate Tarballs of the Source Git Repositories:* Edit your - ``local.conf`` configuration file as follows: - :: + ``local.conf`` configuration file as follows:: DL_DIR = "/home/your-download-dir/" BB_GENERATE_MIRROR_TARBALLS = "1" During the fetch process in the next step, BitBake gathers the source files - and creates tarballs in the directory pointed to by ``DL_DIR``. See + and creates tarballs in the directory pointed to by :term:`DL_DIR`. See the :term:`BB_GENERATE_MIRROR_TARBALLS` variable for more information. 3. *Populate Your Downloads Directory Without Building:* Use BitBake to - fetch your sources but inhibit the build: - :: + fetch your sources but inhibit the build:: $ bitbake target --runonly=fetch @@ -4527,7 +4394,7 @@ directory: The ``SOURCE_MIRROR_URL`` and ``own-mirror`` class set up the system to use the downloads directory as your "own - mirror". Using the ``BB_NO_NETWORK`` variable makes sure that + mirror". Using the :term:`BB_NO_NETWORK` variable makes sure that BitBake's fetching process in step 3 stays local, which means files from your "own-mirror" are used. @@ -4536,8 +4403,7 @@ directory: ``${``\ :term:`TMPDIR`\ ``}`` directory or using a new :term:`Build Directory`. -3. *Build Your Target:* Use BitBake to build your target: - :: +3. *Build Your Target:* Use BitBake to build your target:: $ bitbake target @@ -4550,32 +4416,31 @@ directory: The offline build does not work if recipes attempt to find the latest version of software by setting :term:`SRCREV` to - ``${``\ :term:`AUTOREV`\ ``}``: - :: + ``${``\ :term:`AUTOREV`\ ``}``:: SRCREV = "${AUTOREV}" - When a recipe sets ``SRCREV`` to + When a recipe sets :term:`SRCREV` to ``${AUTOREV}``, the build system accesses the network in an attempt to determine the latest version of software from the SCM. - Typically, recipes that use ``AUTOREV`` are custom or modified + Typically, recipes that use :term:`AUTOREV` are custom or modified recipes. Recipes that reside in public repositories usually do not - use ``AUTOREV``. + use :term:`AUTOREV`. - If you do have recipes that use ``AUTOREV``, you can take steps to + If you do have recipes that use :term:`AUTOREV`, you can take steps to still use the recipes in an offline build. Do the following: 1. Use a configuration generated by enabling :ref:`build history <dev-manual/common-tasks:maintaining build output quality>`. 2. Use the ``buildhistory-collect-srcrevs`` command to collect the - stored ``SRCREV`` values from the build's history. For more + stored :term:`SRCREV` values from the build's history. For more information on collecting these values, see the ":ref:`dev-manual/common-tasks:build history package information`" section. 3. Once you have the correct source revisions, you can modify - those recipes to set ``SRCREV`` to specific versions of the + those recipes to set :term:`SRCREV` to specific versions of the software. Speeding Up a Build @@ -4670,8 +4535,7 @@ that can help you speed up the build: - Disable static library generation for recipes derived from ``autoconf`` or ``libtool``: Following is an example showing how to disable static libraries and still provide an override to handle - exceptions: - :: + exceptions:: STATICLIBCONF = "--disable-static" STATICLIBCONF_sqlite3-native = "" @@ -4716,7 +4580,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 ``PACKAGES`` +by the ``do_install`` task are packaged. By default, the :term:`PACKAGES` variable includes ``${PN}-staticdev``, which represents all static library files. @@ -4726,8 +4590,7 @@ library files. static library files through ``${PN}-dev``. Following is part of the BitBake configuration file, where you can see -how the static library files are defined: -:: +how the static library files are defined:: PACKAGE_BEFORE_PN ?= "" PACKAGES = "${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}" @@ -4785,7 +4648,7 @@ libraries and other binaries to use a different set of libraries. The libraries could differ in architecture, compiler options, or other optimizations. -Several examples exist in the ``meta-skeleton`` layer found in the +There are several examples in the ``meta-skeleton`` layer found in the :term:`Source Directory`: - ``conf/multilib-example.conf`` configuration file @@ -4798,7 +4661,7 @@ Preparing to Use Multilib ~~~~~~~~~~~~~~~~~~~~~~~~~ User-specific requirements drive the Multilib feature. Consequently, -there is no one "out-of-the-box" configuration that likely exists to +there is no one "out-of-the-box" configuration that would meet your needs. In order to enable Multilib, you first need to ensure your recipe is @@ -4833,8 +4696,7 @@ After you have set up the recipes, you need to define the actual combination of multiple libraries you want to build. You accomplish this through your ``local.conf`` configuration file in the :term:`Build Directory`. An example -configuration would be as follows: -:: +configuration would be as follows:: MACHINE = "qemux86-64" require conf/multilib.conf @@ -4850,22 +4712,20 @@ on this particular tuning, see The example then includes ``lib32-glib-2.0`` in all the images, which illustrates one method of including a multiple library dependency. You -can use a normal image build to include this dependency, for example: -:: +can use a normal image build to include this dependency, for example:: $ bitbake core-image-sato You can also build Multilib packages -specifically with a command like this: -:: +specifically with a command like this:: $ bitbake lib32-glib-2.0 Additional Implementation Details ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Generic implementation details as well as details that are specific to -package management systems exist. Following are implementation details +There are generic implementation details as well as details that are specific to +package management systems. Following are implementation details that exist regardless of the package management system: - The typical convention used for the class extension code as used by @@ -4882,8 +4742,7 @@ that exist regardless of the package management system: vendor string presently break Autoconf's ``config.sub``, and other separators are problematic for different reasons. -For the RPM Package Management System, the following implementation -details exist: +Here are the implementation details for the RPM Package Management System: - A unique architecture is defined for the Multilib packages, along with creating a unique deploy folder under ``tmp/deploy/rpm`` in the @@ -4904,8 +4763,7 @@ details exist: - The build system relies on RPM to resolve the identical files in the two (or more) Multilib packages. -For the IPK Package Management System, the following implementation -details exist: +Here are the implementation details for the IPK Package Management System: - The ``${MLPREFIX}`` is not stripped from ``${PN}`` during IPK packaging. The naming for a normal RPM package and a Multilib IPK @@ -4923,9 +4781,9 @@ details exist: Installing Multiple Versions of the Same Library ------------------------------------------------ -Situations can exist where you need to install and use multiple versions -of the same library on the same system at the same time. These -situations almost always exist when a library API changes and you have +There are be situations where you need to install and use multiple versions +of the same library on the same system at the same time. This +almost always happens when a library API changes and you have multiple pieces of software that depend on the separate versions of the library. To accommodate these situations, you can install multiple versions of the same library in parallel on the same system. @@ -4952,8 +4810,7 @@ you have other recipes that depend on a given library, you need to use the :term:`DEPENDS` variable to create the dependency. Continuing with the same example, if you want to have a recipe depend on the 1.8 version of the ``clutter`` library, use -the following in your recipe: -:: +the following in your recipe:: DEPENDS = "clutter-1.8" @@ -4991,13 +4848,12 @@ follows: - You can create and boot ``core-image-minimal`` and ``core-image-sato`` images. -- RPM Package Manager (RPM) support exists for x32 binaries. +- There is RPM Package Manager (RPM) support for x32 binaries. -- Support for large images exists. +- There is support for large images. To use the x32 psABI, you need to edit your ``conf/local.conf`` -configuration file as follows: -:: +configuration file as follows:: MACHINE = "qemux86-64" DEFAULTTUNE = "x86-64-x32" @@ -5006,8 +4862,7 @@ configuration file as follows: Once you have set up your configuration file, use BitBake to build an image that supports -the x32 psABI. Here is an example: -:: +the x32 psABI. Here is an example:: $ bitbake core-image-sato @@ -5061,13 +4916,12 @@ library package involves the following: :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` and that "qemu-usermode" is not in :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. - If either of these conditions exist, nothing will happen. + In either of these conditions, nothing will happen. 3. Try to build the recipe. If you encounter build errors that look like something is unable to find ``.so`` libraries, check where these libraries are located in the source tree and add the following to the - recipe: - :: + recipe:: GIR_EXTRA_LIBS_PATH = "${B}/something/.libs" @@ -5097,8 +4951,7 @@ perhaps QEMU does not work on your build host and target architecture combination. If so, you can use either of the following methods to disable GIR file generations: -- Add the following to your distro configuration: - :: +- Add the following to your distro configuration:: DISTRO_FEATURES_BACKFILL_CONSIDERED = "gobject-introspection-data" @@ -5106,8 +4959,7 @@ disable GIR file generations: QEMU but will still enable building introspection tools and libraries (i.e. building them does not require the use of QEMU). -- Add the following to your machine configuration: - :: +- Add the following to your machine configuration:: MACHINE_FEATURES_BACKFILL_CONSIDERED = "qemu-usermode" @@ -5140,8 +4992,7 @@ working in an image: 3. Launch a Terminal and then start Python in the terminal. -4. Enter the following in the terminal: - :: +4. Enter the following in the terminal:: >>> from gi.repository import GLib >>> GLib.get_host_name() @@ -5152,7 +5003,7 @@ working in an image: Known Issues ------------ -The following know issues exist for GObject Introspection Support: +Here are know issues in GObject Introspection Support: - ``qemu-ppc64`` immediately crashes. Consequently, you cannot build introspection data on that architecture. @@ -5289,8 +5140,7 @@ system needs to meet the following requirements: form generated by the OpenEmbedded build system. - You must build several native tools, which are built to run on the - build system: - :: + build system:: $ bitbake parted-native dosfstools-native mtools-native @@ -5306,8 +5156,7 @@ Getting Help You can get general help for the ``wic`` command by entering the ``wic`` command by itself or by entering the command with a help argument as -follows: -:: +follows:: $ wic -h $ wic --help @@ -5315,32 +5164,27 @@ follows: Currently, Wic supports seven commands: ``cp``, ``create``, ``help``, ``list``, ``ls``, ``rm``, and ``write``. You can get help for all these -commands except "help" by using the following form: -:: +commands except "help" by using the following form:: $ wic help command For example, the following command returns help for the ``write`` -command: -:: +command:: $ wic help write Wic supports help for three topics: ``overview``, ``plugins``, and -``kickstart``. You can get help for any topic using the following form: -:: +``kickstart``. You can get help for any topic using the following form:: $ wic help topic -For example, the following returns overview help for Wic: -:: +For example, the following returns overview help for Wic:: $ wic help overview -One additional level of help exists for Wic. You can get help on +There is one additional level of help for Wic. You can get help on individual images through the ``list`` command. You can use the ``list`` -command to return the available Wic images as follows: -:: +command to return the available Wic images as follows:: $ wic list images genericx86 Create an EFI disk image for genericx86* @@ -5359,8 +5203,7 @@ command to return the available Wic images as follows: Once you know the list of available Wic images, you can use ``help`` with the command to get help on a particular image. For example, the following command returns help on the -"beaglebone-yocto" image: -:: +"beaglebone-yocto" image:: $ wic list beaglebone-yocto help @@ -5397,8 +5240,7 @@ can point to arbitrary kernel, root filesystem locations, and so forth. Contrast this behavior with cooked mode where Wic looks in the Build Directory (e.g. ``tmp/deploy/images/``\ machine). -The general form of the ``wic`` command in raw mode is: -:: +The general form of the ``wic`` command in raw mode is:: $ wic create wks_file options ... @@ -5456,8 +5298,7 @@ a kickstart file and the name of the image from which to use artifacts by using the "-e" option. Wic looks in the Build Directory (e.g. ``tmp/deploy/images/``\ machine) for artifacts. -The general form of the ``wic`` command using Cooked Mode is as follows: -:: +The general form of the ``wic`` command using Cooked Mode is as follows:: $ wic create wks_file -e IMAGE_NAME @@ -5480,14 +5321,12 @@ Using an Existing Kickstart File If you do not want to create your own kickstart file, you can use an existing file provided by the Wic installation. As shipped, kickstart files can be found in the :ref:`overview-manual/development-environment:yocto project source repositories` in the -following two locations: -:: +following two locations:: poky/meta-yocto-bsp/wic poky/scripts/lib/wic/canned-wks -Use the following command to list the available kickstart files: -:: +Use the following command to list the available kickstart files:: $ wic list images genericx86 Create an EFI disk image for genericx86* @@ -5505,15 +5344,13 @@ Use the following command to list the available kickstart files: When you use an existing file, you do not have to use the ``.wks`` extension. Here is an example in Raw -Mode that uses the ``directdisk`` file: -:: +Mode that uses the ``directdisk`` file:: $ wic create directdisk -r rootfs_dir -b bootimg_dir \ -k kernel_dir -n native_sysroot Here are the actual partition language commands used in the -``genericx86.wks`` file to generate an image: -:: +``genericx86.wks`` file to generate an image:: # short-description: Create an EFI disk image for genericx86* # long-description: Creates a partitioned EFI disk image for genericx86* machines @@ -5571,8 +5408,7 @@ When the Wic implementation needs to invoke a partition-specific implementation, it looks for the plugin with the same name as the ``--source`` parameter used in the kickstart file given to that partition. For example, if the partition is set up using the following -command in a kickstart file: -:: +command in a kickstart file:: part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024 @@ -5583,8 +5419,7 @@ members of the matching source plugin (i.e. ``bootimg-pcbios``) in the To be more concrete, here is the corresponding plugin definition from the ``bootimg-pcbios.py`` file for the previous command along with an example method called by the Wic implementation when it needs to prepare -a partition using an implementation-specific function: -:: +a partition using an implementation-specific function:: . . @@ -5675,8 +5510,7 @@ Generate an Image using an Existing Kickstart File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This example runs in Cooked Mode and uses the ``mkefidisk`` kickstart -file: -:: +file:: $ wic create mkefidisk -e core-image-minimal INFO: Building wic-tools... @@ -5712,8 +5546,7 @@ and kickstart file information. Continuing with the example, you can now write the image from the Build Directory onto a USB stick, or whatever media for which you built your image, and boot from the media. You can write the image by using -``bmaptool`` or ``dd``: -:: +``bmaptool`` or ``dd``:: $ oe-run-native bmaptool copy mkefidisk-201804191017-sda.direct /dev/sdX @@ -5761,8 +5594,7 @@ the lines that specify the target disk from which to boot. Next, the example modifies the ``directdisksdb-gpt.wks`` file and changes all instances of "``--ondisk sda``" to "``--ondisk sdb``". The example changes the following two lines and leaves the remaining lines -untouched: -:: +untouched:: part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024 part / --source rootfs --ondisk sdb --fstype=ext4 --label platform --align 1024 --use-uuid @@ -5799,8 +5631,7 @@ Computing (nuc) :term:`MACHINE` the Continuing with the example, you can now directly ``dd`` the image to a USB stick, or whatever media for which you built your image, and boot -the resulting media: -:: +the resulting media:: $ sudo dd if=directdisksdb-gpt-201710090938-sdb.direct of=/dev/sdb 140966+0 records in @@ -5814,8 +5645,7 @@ Using a Modified Kickstart File and Running in Raw Mode This next example manually specifies each build artifact (runs in Raw Mode) and uses a modified kickstart file. The example also uses the ``-o`` option to cause Wic to create the output somewhere other than the -default output directory, which is the current directory: -:: +default output directory, which is the current directory:: $ wic create /home/stephano/my_yocto/test.wks -o /home/stephano/testwic \ --rootfs-dir /home/stephano/build/master/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \ @@ -5860,8 +5690,7 @@ The following example examines the contents of the Wic image, deletes the existing kernel, and then inserts a new kernel: 1. *List the Partitions:* Use the ``wic ls`` command to list all the - partitions in the Wic image: - :: + partitions in the Wic image:: $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic Num Start End Size Fstype @@ -5877,8 +5706,7 @@ the existing kernel, and then inserts a new kernel: .. note:: You can get command usage on any Wic command using the following - form: - :: + form:: $ wic help command @@ -5886,14 +5714,12 @@ the existing kernel, and then inserts a new kernel: For example, the following command shows you the various ways to use the wic ls - command: - :: + command:: $ wic help ls - The following command shows what is in partition one: - :: + The following command shows what is in partition one:: $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1 Volume in drive : is boot @@ -5915,8 +5741,7 @@ the existing kernel, and then inserts a new kernel: If you see the following error, you need to update or create a ``~/.mtoolsrc`` file and be sure to have the line "mtools_skip_check=1" - in the file. Then, run the Wic command again: - :: + in the file. Then, run the Wic command again:: ERROR: _exec_cmd: /usr/bin/mdir -i /tmp/wic-parttfokuwra ::/ returned '1' instead of 0 output: Total number of sectors (47824) not a multiple of sectors per track (32)! @@ -5924,8 +5749,7 @@ the existing kernel, and then inserts a new kernel: 3. *Remove the Old Kernel:* Use the ``wic rm`` command to remove the - ``vmlinuz`` file (kernel): - :: + ``vmlinuz`` file (kernel):: $ wic rm tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz @@ -5937,8 +5761,7 @@ the existing kernel, and then inserts a new kernel: kernel will be in the ``workspace/sources`` area. The following example assumes ``devtool`` was used to build the - kernel: - :: + kernel:: $ wic cp poky_sdk/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+git999-r0/linux-yocto-4.12.12+git999/arch/x86/boot/bzImage \ poky/build/tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz @@ -5968,14 +5791,12 @@ system image files much faster. - If you are using Ubuntu or Debian distributions, you can install the ``bmap-tools`` package using the following command and then use the tool without specifying ``PATH`` even from the root - account: - :: + account:: $ sudo apt-get install bmap-tools - If you are unable to install the ``bmap-tools`` package, you will - need to build Bmaptool before using it. Use the following command: - :: + need to build Bmaptool before using it. Use the following command:: $ bitbake bmap-tools-native @@ -5984,15 +5805,13 @@ that while this example uses a Wic image, you can use Bmaptool to flash any type of image. Use these steps to flash an image using Bmaptool: 1. *Update your local.conf File:* You need to have the following set - in your ``local.conf`` file before building your image: - :: + in your ``local.conf`` file before building your image:: IMAGE_FSTYPES += "wic wic.bmap" 2. *Get Your Image:* Either have your image ready (pre-built with the :term:`IMAGE_FSTYPES` - setting previously mentioned) or take the step to build the image: - :: + setting previously mentioned) or take the step to build the image:: $ bitbake image @@ -6000,20 +5819,17 @@ any type of image. Use these steps to flash an image using Bmaptool: depending on your particular setup. The following commands assume the image resides in the Build Directory's ``deploy/images/`` area: - - If you have write access to the media, use this command form: - :: + - If you have write access to the media, use this command form:: $ oe-run-native bmap-tools-native bmaptool copy build-directory/tmp/deploy/images/machine/image.wic /dev/sdX - If you do not have write access to the media, set your permissions - first and then use the same command form: - :: + first and then use the same command form:: $ sudo chmod 666 /dev/sdX $ oe-run-native bmap-tools-native bmaptool copy build-directory/tmp/deploy/images/machine/image.wic /dev/sdX -For help on the ``bmaptool`` command, use the following command: -:: +For help on the ``bmaptool`` command, use the following command:: $ bmaptool --help @@ -6054,8 +5870,8 @@ your image more secure. General Considerations ---------------------- -General considerations exist that help you create more secure images. -You should consider the following suggestions to help make your device +There are general considerations that help you create more secure images. +You should consider the following suggestions to make your device more secure: - Scan additional code you are adding to the system (e.g. application @@ -6107,8 +5923,7 @@ your build output more secure. The security flags are in the Use the following line in your ``local.conf`` file or in your custom distribution configuration file to enable the security compiler and -linker flags for your build: -:: +linker flags for your build:: require conf/distro/include/security_flags.inc @@ -6123,13 +5938,12 @@ system to make your images more secure: When creating a new project, the default is to provide you with an initial ``local.conf`` file that enables this feature using the :term:`EXTRA_IMAGE_FEATURES` - variable with the line: - :: + variable with the line:: EXTRA_IMAGE_FEATURES = "debug-tweaks" To disable that feature, simply comment out that line in your - ``local.conf`` file, or make sure ``IMAGE_FEATURES`` does not contain + ``local.conf`` file, or make sure :term:`IMAGE_FEATURES` does not contain "debug-tweaks" before producing your final image. Among other things, leaving this in place sets the root password as blank, which makes logging in for debugging or inspection easy during development but @@ -6250,8 +6064,7 @@ layer. The following steps provide some more detail: :term:`DISTRO` variable to point to your distribution's configuration file. For example, if your distribution's configuration file is named ``mydistro.conf``, then - you point to it as follows: - :: + you point to it as follows:: DISTRO = "mydistro" @@ -6292,8 +6105,7 @@ The OpenEmbedded build system uses the environment variable configuration information that ultimately ends up in the :term:`Build Directory` ``conf`` directory. By default, ``TEMPLATECONF`` is set as follows in the ``poky`` -repository: -:: +repository:: TEMPLATECONF=${TEMPLATECONF:-meta-poky/conf} @@ -6335,8 +6147,7 @@ display BitBake targets as part of the script output. Customizing this targets appears as part of the script's output. Here is the default list of targets displayed as a result of running -either of the setup scripts: -:: +either of the setup scripts:: You can now run 'bitbake <target>' @@ -6355,8 +6166,7 @@ Conserving Disk Space During Builds To help conserve disk space during builds, you can add the following statement to your project's ``local.conf`` configuration file found in -the :term:`Build Directory`: -:: +the :term:`Build Directory`:: INHERIT += "rm_work" @@ -6398,8 +6208,8 @@ or to not install a package at all. The following list introduces variables you can use to prevent packages from being installed into your image. Each of these variables only works -with IPK and RPM package types. Support for Debian packages does not -exist. Also, you can use these variables from your ``local.conf`` file +with IPK and RPM package types, not for Debian packages. +Also, you can use these variables from your ``local.conf`` file or attach them to a specific image recipe by using a recipe name override. For more detail on the variables, see the descriptions in the Yocto Project Reference Manual's glossary chapter. @@ -6438,20 +6248,20 @@ the following: .. note:: Technically, a third component, the "epoch" (i.e. :term:`PE`) is involved - but this discussion for the most part ignores ``PE``. + but this discussion for the most part ignores :term:`PE`. The version and revision are taken from the :term:`PV` and :term:`PR` variables, respectively. -- ``PV``: The recipe version. ``PV`` represents the version of the - software being packaged. Do not confuse ``PV`` with the binary +- :term:`PV`: The recipe version. :term:`PV` represents the version of the + software being packaged. Do not confuse :term:`PV` with the binary package version. - ``PR``: The recipe revision. - :term:`SRCPV`: The OpenEmbedded - build system uses this string to help define the value of ``PV`` when + build system uses this string to help define the value of :term:`PV` when the source code revision needs to be included in it. - :yocto_wiki:`PR Service </PR_Service>`: A @@ -6461,26 +6271,26 @@ the following: Whenever the binary package content changes, the binary package version must change. Changing the binary package version is accomplished by -changing or "bumping" the ``PR`` and/or ``PV`` values. Increasing these +changing or "bumping" the :term:`PR` and/or :term:`PV` values. Increasing these values occurs one of two ways: - Automatically using a Package Revision Service (PR Service). -- Manually incrementing the ``PR`` and/or ``PV`` variables. +- Manually incrementing the :term:`PR` and/or :term:`PV` variables. Given a primary challenge of any build system and its users is how to maintain a package feed that is compatible with existing package manager applications such as RPM, APT, and OPKG, using an automated system is much preferred over a manual system. In either system, the main requirement is that binary package version numbering increases in a -linear fashion and that a number of version components exist that +linear fashion and that there is a number of version components that support that linear progression. For information on how to ensure package revisioning remains linear, see the ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`" section. The following three sections provide related information on the PR -Service, the manual method for "bumping" ``PR`` and/or ``PV``, and on +Service, the manual method for "bumping" :term:`PR` and/or :term:`PV`, and on how to ensure binary package revisioning remains linear. Working With a PR Service @@ -6510,44 +6320,42 @@ Because the OpenEmbedded build system uses unique to a given build, the build system knows when to rebuild packages. All the inputs into a given task are represented by a signature, which can trigger a rebuild when different. Thus, the build -system itself does not rely on the ``PR``, ``PV``, and ``PE`` numbers to +system itself does not rely on the :term:`PR`, :term:`PV`, and :term:`PE` numbers to trigger a rebuild. The signatures, however, can be used to generate these values. The PR Service works with both ``OEBasic`` and ``OEBasicHash`` -generators. The value of ``PR`` bumps when the checksum changes and the +generators. The value of :term:`PR` bumps when the checksum changes and the different generator mechanisms change signatures under different circumstances. As implemented, the build system includes values from the PR Service -into the ``PR`` field as an addition using the form "``.x``" so ``r0`` +into the :term:`PR` field as an addition using the form "``.x``" so ``r0`` becomes ``r0.1``, ``r0.2`` and so forth. This scheme allows existing -``PR`` values to be used for whatever reasons, which include manual -``PR`` bumps, should it be necessary. +:term:`PR` values to be used for whatever reasons, which include manual +:term:`PR` bumps, should it be necessary. By default, the PR Service is not enabled or running. Thus, the packages generated are just "self consistent". The build system adds and removes packages and there are no guarantees about upgrade paths but images will be consistent and correct with the latest changes. -The simplest form for a PR Service is for it to exist for a single host +The simplest form for a PR Service is for a single host development system that builds the package feed (building system). For this scenario, you can enable a local PR Service by setting :term:`PRSERV_HOST` in your -``local.conf`` file in the :term:`Build Directory`: -:: +``local.conf`` file in the :term:`Build Directory`:: PRSERV_HOST = "localhost:0" Once the service is started, packages will automatically -get increasing ``PR`` values and BitBake takes care of starting and +get increasing :term:`PR` values and BitBake takes care of starting and stopping the server. If you have a more complex setup where multiple host development systems work against a common, shared package feed, you have a single PR Service running and it is connected to each building system. For this scenario, -you need to start the PR Service using the ``bitbake-prserv`` command: -:: +you need to start the PR Service using the ``bitbake-prserv`` command:: bitbake-prserv --host ip --port port --start @@ -6559,8 +6367,7 @@ server and port. It is also recommended you use build history, which adds some sanity checks to binary package versions, in conjunction with the server that is running the PR Service. To enable build history, add the following to -each building system's ``local.conf`` file: -:: +each building system's ``local.conf`` file:: # It is recommended to activate "buildhistory" for testing the PR service INHERIT += "buildhistory" @@ -6572,7 +6379,7 @@ history, see the .. note:: - The OpenEmbedded build system does not maintain ``PR`` information as + The OpenEmbedded build system does not maintain :term:`PR` information as part of the shared state (sstate) packages. If you maintain an sstate feed, it's expected that either all your building systems that contribute to the sstate feed use a shared PR Service, or you do not @@ -6591,27 +6398,27 @@ The alternative to setting up a PR Service is to manually "bump" the If a committed change results in changing the package output, then the value of the PR variable needs to be increased (or "bumped") as part of -that commit. For new recipes you should add the ``PR`` variable and set +that commit. For new recipes you should add the :term:`PR` variable and set its initial value equal to "r0", which is the default. Even though the default value is "r0", the practice of adding it to a new recipe makes it harder to forget to bump the variable when you make changes to the recipe in future. If you are sharing a common ``.inc`` file with multiple recipes, you can -also use the ``INC_PR`` variable to ensure that the recipes sharing the +also use the :term:`INC_PR` variable to ensure that the recipes sharing the ``.inc`` file are rebuilt when the ``.inc`` file itself is changed. The -``.inc`` file must set ``INC_PR`` (initially to "r0"), and all recipes -referring to it should set ``PR`` to "${INC_PR}.0" initially, +``.inc`` file must set :term:`INC_PR` (initially to "r0"), and all recipes +referring to it should set :term:`PR` to "${INC_PR}.0" initially, incrementing the last number when the recipe is changed. If the ``.inc`` -file is changed then its ``INC_PR`` should be incremented. +file is changed then its :term:`INC_PR` should be incremented. -When upgrading the version of a binary package, assuming the ``PV`` -changes, the ``PR`` variable should be reset to "r0" (or "${INC_PR}.0" -if you are using ``INC_PR``). +When upgrading the version of a binary package, assuming the :term:`PV` +changes, the :term:`PR` variable should be reset to "r0" (or "${INC_PR}.0" +if you are using :term:`INC_PR`). Usually, version increases occur only to binary packages. However, if -for some reason ``PV`` changes but does not increase, you can increase -the ``PE`` variable (Package Epoch). The ``PE`` variable defaults to +for some reason :term:`PV` changes but does not increase, you can increase +the :term:`PE` variable (Package Epoch). The :term:`PE` variable defaults to "0". Binary package version numbering strives to follow the `Debian Version @@ -6626,22 +6433,20 @@ Automatically Incrementing a Package Version Number When fetching a repository, BitBake uses the :term:`SRCREV` variable to determine the specific source code revision from which to build. You set the -``SRCREV`` variable to +:term:`SRCREV` variable to :term:`AUTOREV` to cause the OpenEmbedded build system to automatically use the latest revision of -the software: -:: +the software:: SRCREV = "${AUTOREV}" -Furthermore, you need to reference ``SRCPV`` in ``PV`` in order to +Furthermore, you need to reference :term:`SRCPV` in :term:`PV` in order to automatically update the version whenever the revision of the source -code changes. Here is an example: -:: +code changes. Here is an example:: PV = "1.0+git${SRCPV}" -The OpenEmbedded build system substitutes ``SRCPV`` with the following: +The OpenEmbedded build system substitutes :term:`SRCPV` with the following: .. code-block:: none @@ -6674,7 +6479,7 @@ with a number. The number used depends on the state of the PR Service: In summary, the OpenEmbedded build system does not track the history of binary package versions for this purpose. ``AUTOINC``, in this case, is -comparable to ``PR``. If PR server is not enabled, ``AUTOINC`` in the +comparable to :term:`PR`. If PR server is not enabled, ``AUTOINC`` in the package version is simply replaced by "0". If PR server is enabled, the build system keeps track of the package versions and bumps the number when the package revision changes. @@ -6707,8 +6512,7 @@ package for each one it finds by appending to the :term:`PACKAGES` variable and setting the appropriate values for ``FILES_packagename``, ``RDEPENDS_packagename``, ``DESCRIPTION_packagename``, and so forth. -Here is an example from the ``lighttpd`` recipe: -:: +Here is an example from the ``lighttpd`` recipe:: python populate_packages_prepend () { lighttpd_libdir = d.expand('${libdir}') @@ -6739,7 +6543,7 @@ The previous example specifies a number of things in the call to "Lighttpd module for alias". Often, packaging modules is as simple as the previous example. However, -more advanced options exist that you can use within +there are more advanced options that you can use within ``do_split_packages`` to modify its behavior. And, if you need to, you can add more logic by specifying a hook function that is called for each package. It is also perfectly acceptable to call ``do_split_packages`` @@ -6751,8 +6555,7 @@ directory of the ``poky`` :ref:`source repository <overview-manual/development-e also find examples in ``meta/classes/kernel.bbclass``. Following is a reference that shows ``do_split_packages`` mandatory and -optional arguments: -:: +optional arguments:: Mandatory arguments @@ -6840,8 +6643,7 @@ any dependencies on optional modules from other recipes are satisfied by your recipe. You can be sure these dependencies are satisfied by using the :term:`PACKAGES_DYNAMIC` variable. Here is an example that continues with the ``lighttpd`` recipe -shown earlier: -:: +shown earlier:: PACKAGES_DYNAMIC = "lighttpd-module-.*" @@ -6852,7 +6654,7 @@ ensure that any :term:`RDEPENDS` and :term:`RRECOMMENDS` on a package name starting with the prefix are satisfied during build time. If you are using ``do_split_packages`` as described in the previous section, -the value you put in ``PACKAGES_DYNAMIC`` should correspond to the name +the value you put in :term:`PACKAGES_DYNAMIC` should correspond to the name pattern specified in the call to ``do_split_packages``. Using Runtime Package Management @@ -6933,8 +6735,7 @@ variable to specify the format: :term:`Build Directory` (e.g. ``poky/build/conf/local.conf``). -2. Select the desired package format as follows: - :: +2. Select the desired package format as follows:: PACKAGE_CLASSES ?= "package_packageformat" @@ -6968,15 +6769,13 @@ target's package database(s) later once your image is up and running. Whenever you perform any sort of build step that can potentially generate a package or modify existing package, it is always a good idea to re-generate the package index after the build by using the following -command: -:: +command:: $ bitbake package-index It might be tempting to build the package and the package index at the same time with a command such as -the following: -:: +the following:: $ bitbake some-package package-index @@ -7023,9 +6822,8 @@ From within the build directory where you have built an image based on your packaging choice (i.e. the :term:`PACKAGE_CLASSES` setting), simply start the server. The following example assumes a build -directory of ``poky/build/tmp/deploy/rpm`` and a ``PACKAGE_CLASSES`` -setting of "package_rpm": -:: +directory of ``poky/build/tmp/deploy/rpm`` and a :term:`PACKAGE_CLASSES` +setting of "package_rpm":: $ cd poky/build/tmp/deploy/rpm $ python3 -m http.server @@ -7091,8 +6889,7 @@ for all architectures. You cannot do both: architectures. - *Create a Single (Full) Package Index:* Define a single base URL that - identifies where a full package database is located: - :: + identifies where a full package database is located:: [oe-packages] baseurl=http://my.server/rpm @@ -7210,8 +7007,7 @@ Signing RPM Packages To enable signing RPM packages, you must set up the following configurations in either your ``local.config`` or ``distro.config`` -file: -:: +file:: # Inherit sign_rpm.bbclass to enable signing functionality INHERIT += " sign_rpm" @@ -7226,7 +7022,7 @@ file: `passphrase`. Aside from the ``RPM_GPG_NAME`` and ``RPM_GPG_PASSPHRASE`` variables in -the previous example, two optional variables related to signing exist: +the previous example, two optional variables related to signing are available: - *GPG_BIN:* Specifies a ``gpg`` binary/wrapper that is executed when the package is signed. @@ -7242,21 +7038,20 @@ signed package feeds for IPK and RPM packages. The steps you need to take to enable signed package feed use are similar to the steps used to sign RPM packages. You must define the following in -your ``local.config`` or ``distro.config`` file: -:: +your ``local.config`` or ``distro.config`` file:: INHERIT += "sign_package_feed" PACKAGE_FEED_GPG_NAME = "key_name" PACKAGE_FEED_GPG_PASSPHRASE_FILE = "path_to_file_containing_passphrase" -For signed package feeds, the passphrase must exist in a separate file, +For signed package feeds, the passphrase must be specified in a separate file, which is pointed to by the ``PACKAGE_FEED_GPG_PASSPHRASE_FILE`` variable. Regarding security, keeping a plain text passphrase out of the configuration is more secure. Aside from the ``PACKAGE_FEED_GPG_NAME`` and ``PACKAGE_FEED_GPG_PASSPHRASE_FILE`` variables, three optional variables -related to signed package feeds exist: +related to signed package feeds are available: - *GPG_BIN* Specifies a ``gpg`` binary/wrapper that is executed when the package is signed. @@ -7282,8 +7077,7 @@ hand, the test can be anything from a simple shell script that runs a binary and checks the output to an elaborate system of test binaries and data files. -The test generates output in the format used by Automake: -:: +The test generates output in the format used by Automake:: result: testname @@ -7305,8 +7099,7 @@ To add package testing to your build, add the :term:`DISTRO_FEATURES` and :term:`EXTRA_IMAGE_FEATURES` variables to your ``local.conf`` file, which is found in the -:term:`Build Directory`: -:: +:term:`Build Directory`:: DISTRO_FEATURES_append = " ptest" EXTRA_IMAGE_FEATURES += "ptest-pkgs" @@ -7331,16 +7124,14 @@ test. Here is what you have to do for each recipe: - *Be sure the recipe inherits the* :ref:`ptest <ref-classes-ptest>` *class:* - Include the following line in each recipe: - :: + Include the following line in each recipe:: inherit ptest - *Create run-ptest:* This script starts your test. Locate the script where you will refer to it using :term:`SRC_URI`. Here is an - example that starts a test for ``dbus``: - :: + example that starts a test for ``dbus``:: #!/bin/sh cd test @@ -7352,8 +7143,7 @@ test. Here is what you have to do for each recipe: :term:`DEPENDS` and :term:`RDEPENDS` variables in your recipe in order for the package to meet the dependencies. Here - is an example where the package has a runtime dependency on "make": - :: + is an example where the package has a runtime dependency on "make":: RDEPENDS_${PN}-ptest += "make" @@ -7374,8 +7164,7 @@ test. Here is what you have to do for each recipe: Regardless, you still must add a ``do_compile_ptest`` function to build the test suite. Add a function similar to the following to your - recipe: - :: + recipe:: do_compile_ptest() { oe_runmake buildtest-TESTS @@ -7401,7 +7190,7 @@ use this fetcher in combination with :doc:`devtool </ref-manual/devtool-reference>` to create recipes that produce NPM packages. -Two workflows exist that allow you to create NPM packages using +There are two workflows that allow you to create NPM packages using ``devtool``: the NPM registry modules method and the NPM project code method. @@ -7457,8 +7246,7 @@ which is a file browser web application. You must know the ``cute-files`` module version. The first thing you need to do is use ``devtool`` and the NPM fetcher to -create the recipe: -:: +create the recipe:: $ devtool add "npm://registry.npmjs.org;package=cute-files;version=1.0.2" @@ -7486,8 +7274,7 @@ runs. practical way to have the licenses for all of the dependencies represented in the license manifest of the image. -The ``devtool edit-recipe`` command lets you take a look at the recipe: -:: +The ``devtool edit-recipe`` command lets you take a look at the recipe:: $ devtool edit-recipe cute-files SUMMARY = "Turn any folder on your computer into a cute file browser, available on the local network." @@ -7507,7 +7294,7 @@ The ``devtool edit-recipe`` command lets you take a look at the recipe: ... LICENSE_${PN}-vary = "MIT" -Three key points exist in the previous example: +Here are three key points in the previous example: - :term:`SRC_URI` uses the NPM scheme so that the NPM fetcher is used. @@ -7520,8 +7307,7 @@ Three key points exist in the previous example: :ref:`npm <ref-classes-npm>` class to package up all the modules. -You can run the following command to build the ``cute-files`` package: -:: +You can run the following command to build the ``cute-files`` package:: $ devtool build cute-files @@ -7529,8 +7315,7 @@ Remember that ``nodejs`` must be installed on the target before your package. Assuming 192.168.7.2 for the target's IP address, use the following -command to deploy your package: -:: +command to deploy your package:: $ devtool deploy-target -s cute-files root@192.168.7.2 @@ -7569,15 +7354,13 @@ projects method, you provide ``devtool`` with an URL that points to the source files. Replicating the same example, (i.e. ``cute-files``) use the following -command: -:: +command:: $ devtool add https://github.com/martinaglv/cute-files.git The recipe this command generates is very similar to the recipe created in -the previous section. However, the ``SRC_URI`` looks like the following: -:: +the previous section. However, the :term:`SRC_URI` looks like the following:: SRC_URI = " \ git://github.com/martinaglv/cute-files.git;protocol=https \ @@ -7611,7 +7394,7 @@ of precedence is the same as this list: - ``PACKAGE_ADD_METADATA_<PN>`` -- ``PACKAGE_ADD_METADATA`` +- :term:`PACKAGE_ADD_METADATA` `<PKGTYPE>` is a parameter and expected to be a distinct name of specific package type: @@ -7628,9 +7411,8 @@ The variable can contain multiple [one-line] metadata fields separated by the literal sequence '\\n'. The separator can be redefined using the variable flag ``separator``. -The following is an example that adds two custom fields for ipk -packages: -:: +Here is an example that adds two custom fields for ipk +packages:: PACKAGE_ADD_METADATA_IPK = "Vendor: CustomIpk\nGroup:Applications/Spreadsheets" @@ -7660,8 +7442,7 @@ adding statements to your configuration file so that the build process checks local directories first for existing tarballs before checking the Internet. -Here is an efficient way to set it up in your ``local.conf`` file: -:: +Here is an efficient way to set it up in your ``local.conf`` file:: SOURCE_MIRROR_URL ?= "file:///home/you/your-download-dir/" INHERIT += "own-mirrors" @@ -7692,8 +7473,7 @@ download directory :ref:`structure-build-downloads`, which is located with :term:`DL_DIR`. Use the following BitBake command form to fetch all the necessary -sources without starting the build: -:: +sources without starting the build:: $ bitbake target --runall=fetch @@ -7706,7 +7486,7 @@ Selecting an Initialization Manager =================================== By default, the Yocto Project uses SysVinit as the initialization -manager. However, support also exists for systemd, which is a full +manager. However, there is also support for systemd, which is a full replacement for init with parallel starting of services, reduced shell overhead and other features that are used by many distributions. @@ -7740,15 +7520,13 @@ following sections. Using systemd Exclusively ------------------------- -Set these variables in your distribution configuration file as follows: -:: +Set these variables in your distribution configuration file as follows:: DISTRO_FEATURES_append = " systemd" VIRTUAL-RUNTIME_init_manager = "systemd" You can also prevent the SysVinit distribution feature from -being automatically enabled as follows: -:: +being automatically enabled as follows:: DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit" @@ -7756,8 +7534,7 @@ Doing so removes any redundant SysVinit scripts. To remove initscripts from your image altogether, set this variable -also: -:: +also:: VIRTUAL-RUNTIME_initscripts = "" @@ -7767,8 +7544,7 @@ For information on the backfill variable, see Using systemd for the Main Image and Using SysVinit for the Rescue Image ------------------------------------------------------------------------ -Set these variables in your distribution configuration file as follows: -:: +Set these variables in your distribution configuration file as follows:: DISTRO_FEATURES_append = " systemd" VIRTUAL-RUNTIME_init_manager = "systemd" @@ -7800,8 +7576,7 @@ Using Persistent and Pre-Populated\ ``/dev`` To use the static method for device population, you need to set the :term:`USE_DEVFS` variable to "0" -as follows: -:: +as follows:: USE_DEVFS = "0" @@ -7812,9 +7587,8 @@ variable defines the Device Table to use and should be set in the machine or distro configuration file. Alternatively, you can set this variable in your ``local.conf`` configuration file. -If you do not define the ``IMAGE_DEVICE_TABLES`` variable, the default -``device_table-minimal.txt`` is used: -:: +If you do not define the :term:`IMAGE_DEVICE_TABLES` variable, the default +``device_table-minimal.txt`` is used:: IMAGE_DEVICE_TABLES = "device_table-mymachine.txt" @@ -7826,8 +7600,7 @@ Using ``devtmpfs`` and a Device Manager To use the dynamic method for device population, you need to use (or be sure to set) the :term:`USE_DEVFS` -variable to "1", which is the default: -:: +variable to "1", which is the default:: USE_DEVFS = "1" @@ -7844,8 +7617,7 @@ To have more control over the device nodes, you can use a device manager like ``udev`` or ``busybox-mdev``. You choose the device manager by defining the ``VIRTUAL-RUNTIME_dev_manager`` variable in your machine or distro configuration file. Alternatively, you can set this variable in -your ``local.conf`` configuration file: -:: +your ``local.conf`` configuration file:: VIRTUAL-RUNTIME_dev_manager = "udev" @@ -7866,14 +7638,12 @@ Subversion (SVN), Git, and Bazaar (BZR) repositories. To enable this behavior, the :term:`PV` of the recipe needs to reference -:term:`SRCPV`. Here is an example: -:: +:term:`SRCPV`. Here is an example:: PV = "1.2.3+git${SRCPV}" Then, you can add the following to your -``local.conf``: -:: +``local.conf``:: SRCREV_pn-PN = "${AUTOREV}" @@ -7881,20 +7651,17 @@ Then, you can add the following to your which you want to enable automatic source revision updating. If you do not want to update your local configuration file, you can add -the following directly to the recipe to finish enabling the feature: -:: +the following directly to the recipe to finish enabling the feature:: SRCREV = "${AUTOREV}" The Yocto Project provides a distribution named ``poky-bleeding``, whose -configuration file contains the line: -:: +configuration file contains the line:: require conf/distro/include/poky-floating-revisions.inc This line pulls in the -listed include file that contains numerous lines of exactly that form: -:: +listed include file that contains numerous lines of exactly that form:: #SRCREV_pn-opkg-native ?= "${AUTOREV}" #SRCREV_pn-opkg-sdk ?= "${AUTOREV}" @@ -7946,15 +7713,13 @@ Creating the Root Filesystem To create the read-only root filesystem, simply add the "read-only-rootfs" feature to your image, normally in one of two ways. The first way is to add the "read-only-rootfs" image feature in the -image's recipe file via the ``IMAGE_FEATURES`` variable: -:: +image's recipe file via the :term:`IMAGE_FEATURES` variable:: IMAGE_FEATURES += "read-only-rootfs" As an alternative, you can add the same feature from within your build directory's ``local.conf`` file with the -associated ``EXTRA_IMAGE_FEATURES`` variable, as in: -:: +associated :term:`EXTRA_IMAGE_FEATURES` variable, as in:: EXTRA_IMAGE_FEATURES = "read-only-rootfs" @@ -8027,7 +7792,7 @@ link to the built library and that library will be pulled into your image along with the new software even if you did not want the library. The :ref:`buildhistory <ref-classes-buildhistory>` -class exists to help you maintain the quality of your build output. You +class helps you maintain the quality of your build output. You can use the class to highlight unexpected and possibly unwanted changes in the build output. When you enable build history, it records information about the contents of each package and image and then @@ -8048,11 +7813,10 @@ Enabling and Disabling Build History ------------------------------------ Build history is disabled by default. To enable it, add the following -``INHERIT`` statement and set the +:term:`INHERIT` statement and set the :term:`BUILDHISTORY_COMMIT` variable to "1" at the end of your ``conf/local.conf`` file found in the -:term:`Build Directory`: -:: +:term:`Build Directory`:: INHERIT += "buildhistory" BUILDHISTORY_COMMIT = "1" @@ -8078,12 +7842,12 @@ Build history information is kept in ``${``\ :term:`TOPDIR`\ ``}/buildhistory`` in the Build Directory as defined by the :term:`BUILDHISTORY_DIR` -variable. The following is an example abbreviated listing: +variable. Here is an example abbreviated listing: .. image:: figures/buildhistory.png :align: center -At the top level, a ``metadata-revs`` file exists that lists the +At the top level, there is a ``metadata-revs`` file that lists the revisions of the repositories for the enabled layers when the build was produced. The rest of the data splits into separate ``packages``, ``images`` and ``sdk`` directories, the contents of which are described @@ -8119,7 +7883,7 @@ The exceptions are ``FILELIST``, which is the actual list of files in the package, and ``PKGSIZE``, which is the total size of files in the package in bytes. -A file also exists that corresponds to the recipe from which the package +There is also a file that corresponds to the recipe from which the package came (e.g. ``buildhistory/packages/i586-poky-linux/busybox/latest``): .. code-block:: none @@ -8134,14 +7898,13 @@ came (e.g. ``buildhistory/packages/i586-poky-linux/busybox/latest``): busybox-staticdev busybox-dev busybox-doc busybox-locale busybox Finally, for those recipes fetched from a version control system (e.g., -Git), a file exists that lists source revisions that are specified in -the recipe and lists the actual revisions used during the build. Listed +Git), there is a file that lists source revisions that are specified in +the recipe and the actual revisions used during the build. Listed and actual revisions might differ when :term:`SRCREV` is set to ${:term:`AUTOREV`}. Here is an example assuming -``buildhistory/packages/qemux86-poky-linux/linux-yocto/latest_srcrev``): -:: +``buildhistory/packages/qemux86-poky-linux/linux-yocto/latest_srcrev``):: # SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" @@ -8150,12 +7913,11 @@ example assuming You can use the ``buildhistory-collect-srcrevs`` command with the ``-a`` option to -collect the stored ``SRCREV`` values from build history and report them +collect the stored :term:`SRCREV` values from build history and report them in a format suitable for use in global configuration (e.g., ``local.conf`` or a distro include file) to override floating -``AUTOREV`` values to a fixed set of revisions. Here is some example -output from this command: -:: +:term:`AUTOREV` values to a fixed set of revisions. Here is some example +output from this command:: $ buildhistory-collect-srcrevs -a # i586-poky-linux @@ -8183,7 +7945,7 @@ output from this command: Here are some notes on using the ``buildhistory-collect-srcrevs`` command: - - By default, only values where the ``SRCREV`` was not hardcoded + - By default, only values where the :term:`SRCREV` was not hardcoded (usually when ``AUTOREV`` is used) are reported. Use the ``-a`` option to see all ``SRCREV`` values. @@ -8270,8 +8032,7 @@ image. If you are just interested in this information and not interested in collecting specific package or SDK information, you can enable writing only image information without any history by adding the following to your ``conf/local.conf`` file found in the -:term:`Build Directory`: -:: +:term:`Build Directory`:: INHERIT += "buildhistory" BUILDHISTORY_COMMIT = "0" @@ -8370,8 +8131,7 @@ interface. To see any changes that have occurred (assuming you have :term:`BUILDHISTORY_COMMIT` = "1"), you can simply use any Git command that allows you to view the history -of a repository. Here is one method: -:: +of a repository. Here is one method:: $ git log -p @@ -8379,10 +8139,9 @@ You need to realize, however, that this method does show changes that are not significant (e.g. a package's size changing by a few bytes). -A command-line tool called ``buildhistory-diff`` does exist, though, +There is a command-line tool called ``buildhistory-diff``, though, that queries the Git repository and prints just the differences that -might be significant in human-readable form. Here is an example: -:: +might be significant in human-readable form. Here is an example:: $ poky/poky/scripts/buildhistory-diff . HEAD^ Changes to images/qemux86_64/glibc/core-image-minimal (files-in-image.txt): @@ -8402,8 +8161,7 @@ might be significant in human-readable form. Here is an example: .. note:: The ``buildhistory-diff`` tool requires the ``GitPython`` - package. Be sure to install it using Pip3 as follows: - :: + package. Be sure to install it using Pip3 as follows:: $ pip3 install GitPython --user @@ -8473,8 +8231,7 @@ In order to run tests, you need to do the following: with sudo. - The package recipe ``qemu-helper-native`` is required to run - this script. Build the package using the following command: - :: + this script. Build the package using the following command:: $ bitbake qemu-helper-native @@ -8519,7 +8276,7 @@ Once you start running the tests, the following happens: tests run. The full boot log is written to ``${WORKDIR}/testimage/qemu_boot_log``. -5. Each test module loads in the order found in ``TEST_SUITES``. You can +5. Each test module loads in the order found in :term:`TEST_SUITES`. You can find the full output of the commands run over SSH in ``${WORKDIR}/testimgage/ssh_target_log``. @@ -8553,10 +8310,10 @@ addresses written into the image, or set the image to use DHCP and have your DHCP server on the test network assign a known IP address based on the MAC address of the device. -In order to run tests on hardware, you need to set ``TEST_TARGET`` to an +In order to run tests on hardware, you need to set :term:`TEST_TARGET` to an appropriate value. For QEMU, you do not have to change anything, the default value is "qemu". For running tests on hardware, the following -options exist: +options are available: - *"simpleremote":* Choose "simpleremote" if you are going to run tests on a target system that is already running the image to be tested and @@ -8602,15 +8359,14 @@ options exist: Selecting SystemdbootTarget ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you did not set ``TEST_TARGET`` to "SystemdbootTarget", then you do +If you did not set :term:`TEST_TARGET` to "SystemdbootTarget", then you do not need any information in this section. You can skip down to the ":ref:`dev-manual/common-tasks:running tests`" section. -If you did set ``TEST_TARGET`` to "SystemdbootTarget", you also need to +If you did set :term:`TEST_TARGET` to "SystemdbootTarget", you also need to perform a one-time setup of your master image by doing the following: -1. *Set EFI_PROVIDER:* Be sure that ``EFI_PROVIDER`` is as follows: - :: +1. *Set EFI_PROVIDER:* Be sure that :term:`EFI_PROVIDER` is as follows:: EFI_PROVIDER = "systemd-boot" @@ -8644,20 +8400,18 @@ perform a one-time setup of your master image by doing the following: 3. *Install image:* Install the image that you just built on the target system. -The final thing you need to do when setting ``TEST_TARGET`` to +The final thing you need to do when setting :term:`TEST_TARGET` to "SystemdbootTarget" is to set up the test image: 1. *Set up your local.conf file:* Make sure you have the following - statements in your ``local.conf`` file: - :: + statements in your ``local.conf`` file:: IMAGE_FSTYPES += "tar.gz" INHERIT += "testimage" TEST_TARGET = "SystemdbootTarget" TEST_TARGET_IP = "192.168.2.3" -2. *Build your test image:* Use BitBake to build the image: - :: +2. *Build your test image:* Use BitBake to build the image:: $ bitbake core-image-sato @@ -8667,12 +8421,11 @@ Power Control For most hardware targets other than "simpleremote", you can control power: -- You can use ``TEST_POWERCONTROL_CMD`` together with - ``TEST_POWERCONTROL_EXTRA_ARGS`` as a command that runs on the host +- You can use :term:`TEST_POWERCONTROL_CMD` together with + :term:`TEST_POWERCONTROL_EXTRA_ARGS` as a command that runs on the host and does power cycling. The test code passes one argument to that command: off, on or cycle (off then on). Here is an example that - could appear in your ``local.conf`` file: - :: + could appear in your ``local.conf`` file:: TEST_POWERCONTROL_CMD = "powercontrol.exp test 10.11.12.1 nuc1" @@ -8688,8 +8441,8 @@ power: .. note:: - You need to customize ``TEST_POWERCONTROL_CMD`` and - ``TEST_POWERCONTROL_EXTRA_ARGS`` for your own setup. The one requirement + You need to customize :term:`TEST_POWERCONTROL_CMD` and + :term:`TEST_POWERCONTROL_EXTRA_ARGS` for your own setup. The one requirement is that it accepts "on", "off", and "cycle" as the last argument. - When no command is defined, it connects to the device over SSH and @@ -8705,8 +8458,7 @@ wish to experiment with automated hardware testing, you can use the the required power action. This script requires either KDialog or Zenity to be installed. To use this script, set the :term:`TEST_POWERCONTROL_CMD` -variable as follows: -:: +variable as follows:: TEST_POWERCONTROL_CMD = "${COREBASE}/scripts/contrib/dialog-power-control" @@ -8728,8 +8480,7 @@ connecting to a remote console server. Regardless of the case, the command simply needs to connect to the serial console and forward that connection to standard input and output as any normal terminal program does. For example, to use the picocom terminal program on serial device -``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows: -:: +``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows:: TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" @@ -8737,8 +8488,7 @@ For local devices where the serial port device disappears when the device reboots, an additional "serdevtry" wrapper script is provided. To use this wrapper, simply prefix the terminal command with -``${COREBASE}/scripts/contrib/serdevtry``: -:: +``${COREBASE}/scripts/contrib/serdevtry``:: TEST_SERIALCONTROL_CMD = "${COREBASE}/scripts/contrib/serdevtry picocom -b 115200 /dev/ttyUSB0" @@ -8752,27 +8502,23 @@ You can start the tests automatically or manually: set the :term:`TESTIMAGE_AUTO` variable to "1" in your ``local.conf`` file in the - :term:`Build Directory`: - :: + :term:`Build Directory`:: TESTIMAGE_AUTO = "1" Next, build your image. If the image successfully builds, the - tests run: - :: + tests run:: bitbake core-image-sato - *Manually running tests:* To manually run the tests, first globally inherit the :ref:`testimage <ref-classes-testimage*>` class - by editing your ``local.conf`` file: - :: + by editing your ``local.conf`` file:: INHERIT += "testimage" - Next, use BitBake to run the tests: - :: + Next, use BitBake to run the tests:: bitbake -c testimage image @@ -8794,14 +8540,14 @@ the ``local.conf`` file as normal. Be sure that tests reside in You can change the set of tests run by appending or overriding :term:`TEST_SUITES` variable in -``local.conf``. Each name in ``TEST_SUITES`` represents a required test -for the image. Test modules named within ``TEST_SUITES`` cannot be +``local.conf``. Each name in :term:`TEST_SUITES` represents a required test +for the image. Test modules named within :term:`TEST_SUITES` cannot be skipped even if a test is not suitable for an image (e.g. running the RPM tests on an image without ``rpm``). Appending "auto" to -``TEST_SUITES`` causes the build system to try to run all tests that are +:term:`TEST_SUITES` causes the build system to try to run all tests that are suitable for the image (i.e. each test module may elect to skip itself). -The order you list tests in ``TEST_SUITES`` is important and influences +The order you list tests in :term:`TEST_SUITES` is important and influences test dependencies. Consequently, tests that depend on other tests should be added after the test on which they depend. For example, since the ``ssh`` test depends on the ``ping`` test, "ssh" needs to come after @@ -8815,18 +8561,15 @@ handling. Here are some things to keep in mind when running tests: -- The default tests for the image are defined as: - :: +- The default tests for the image are defined as:: DEFAULT_TEST_SUITES_pn-image = "ping ssh df connman syslog xorg scp vnc date rpm dnf dmesg" -- Add your own test to the list of the by using the following: - :: +- Add your own test to the list of the by using the following:: TEST_SUITES_append = " mytest" -- Run a specific list of tests as follows: - :: +- Run a specific list of tests as follows:: TEST_SUITES = "test1 test2 test3" @@ -8842,46 +8585,40 @@ test execution off to a scheduler. You can only export tests that are defined in :term:`TEST_SUITES`. If your image is already built, make sure the following are set in your -``local.conf`` file: -:: +``local.conf`` file:: INHERIT += "testexport" TEST_TARGET_IP = "IP-address-for-the-test-target" TEST_SERVER_IP = "IP-address-for-the-test-server" You can then export the tests with the -following BitBake command form: -:: +following BitBake command form:: $ bitbake image -c testexport Exporting the tests places them in the :term:`Build Directory` in ``tmp/testexport/``\ image, which is controlled by the -``TEST_EXPORT_DIR`` variable. +:term:`TEST_EXPORT_DIR` variable. -You can now run the tests outside of the build environment: -:: +You can now run the tests outside of the build environment:: $ cd tmp/testexport/image $ ./runexported.py testdata.json Here is a complete example that shows IP addresses and uses the -``core-image-sato`` image: -:: +``core-image-sato`` image:: INHERIT += "testexport" TEST_TARGET_IP = "192.168.7.2" TEST_SERVER_IP = "192.168.7.1" -Use BitBake to export the tests: -:: +Use BitBake to export the tests:: $ bitbake core-image-sato -c testexport Run the tests outside of -the build environment using the following: -:: +the build environment using the following:: $ cd tmp/testexport/core-image-sato $ ./runexported.py testdata.json @@ -8900,7 +8637,7 @@ layer's ``layer.conf`` file as normal). Just remember the following: - Do not use module names that collide with existing core tests. -- Minimally, an empty ``__init__.py`` file must exist in the runtime +- Minimally, an empty ``__init__.py`` file must be present in the runtime directory. To create a new test, start by copying an existing module (e.g. @@ -8980,7 +8717,7 @@ Class attributes are as follows: Instance Attributes ~~~~~~~~~~~~~~~~~~~ -A single instance attribute exists, which is ``target``. The ``target`` +There is a single instance attribute, which is ``target``. The ``target`` instance attribute is identical to the class attribute of the same name, which is described in the previous section. This attribute exists as both an instance and class attribute so tests can use @@ -9157,14 +8894,12 @@ variables>` did not work out as expected. BitBake's ``-e`` option is used to display variable values after parsing. The following command displays the variable values after the configuration files (i.e. ``local.conf``, ``bblayers.conf``, -``bitbake.conf`` and so forth) have been parsed: -:: +``bitbake.conf`` and so forth) have been parsed:: $ bitbake -e The following command displays variable values after a specific recipe has -been parsed. The variables include those from the configuration as well: -:: +been parsed. The variables include those from the configuration as well:: $ bitbake -e recipename @@ -9187,8 +8922,7 @@ variable flags (varflags) set on the variable. The output can be very helpful during debugging. Variables that are exported to the environment are preceded by -``export`` in the output of ``bitbake -e``. See the following example: -:: +``export`` in the output of ``bitbake -e``. See the following example:: export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86" @@ -9250,8 +8984,7 @@ Following are a few of the available ``oe-pkgdata-util`` subcommands. - ``oe-pkgdata-util find-path path ...``: Lists the names of the packages that contain the given paths. For example, the following tells us that ``/usr/share/man/man1/make.1`` is contained in the - ``make-doc`` package: - :: + ``make-doc`` package:: $ oe-pkgdata-util find-path /usr/share/man/man1/make.1 make-doc: /usr/share/man/man1/make.1 @@ -9260,8 +8993,7 @@ Following are a few of the available ``oe-pkgdata-util`` subcommands. of the recipes that produce the given packages. For more information on the ``oe-pkgdata-util`` command, use the help -facility: -:: +facility:: $ oe-pkgdata-util --help $ oe-pkgdata-util subcommand --help @@ -9274,8 +9006,7 @@ before the one you have specified. Dependency information can help you understand why a recipe is built. To generate dependency information for a recipe, run the following -command: -:: +command:: $ bitbake -g recipename @@ -9305,8 +9036,7 @@ format and can be converted to images (e.g. using the ``dot`` tool from provide useful information. As an example, the ``task-depends.dot`` file contains lines such - as the following: - :: + as the following:: "libxslt.do_configure" -> "libxml2.do_populate_sysroot" @@ -9323,8 +9053,7 @@ format and can be converted to images (e.g. using the ``dot`` tool from displays paths between graph nodes. You can use a different method to view dependency information by using -the following command: -:: +the following command:: $ bitbake -g -u taskexp recipename @@ -9350,8 +9079,7 @@ If you are unsure whether a variable dependency is being picked up automatically for a given task, you can list the variable dependencies BitBake has determined by doing the following: -1. Build the recipe containing the task: -:: +1. Build the recipe containing the task:: $ bitbake recipename @@ -9362,8 +9090,7 @@ BitBake has determined by doing the following: checksum for the task. As an example, for the :ref:`ref-tasks-fetch` task of the ``db`` recipe, the ``sigdata`` file might be found in the following - location: - :: + location:: ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1 @@ -9375,8 +9102,7 @@ BitBake has determined by doing the following: same information as ``sigdata`` files. 3. Run ``bitbake-dumpsig`` on the ``sigdata`` or ``siginfo`` file. Here - is an example: - :: + is an example:: $ bitbake-dumpsig ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1 @@ -9406,8 +9132,7 @@ call ``bitbake-diffsigs`` with just one file, the command behaves like You can also use BitBake to dump out the signature construction information without executing tasks by using either of the following -BitBake command-line options: -:: +BitBake command-line options:: ‐‐dump-signatures=SIGNATURE_HANDLER -S SIGNATURE_HANDLER @@ -9494,8 +9219,7 @@ behavior in most cases is: ``do_fetch``, ``do_unpack``, ``do_patch``, ``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 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: -:: +use the ``-c`` option in BitBake. Here is an example:: $ bitbake matchbox-desktop -c devshell @@ -9520,8 +9244,7 @@ out), then you can use the ``-f`` option. [\ :ref:`nostamp <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ] variable flag is already set for the task. -The following example shows one way you can use the ``-f`` option: -:: +The following example shows one way you can use the ``-f`` option:: $ bitbake matchbox-desktop . @@ -9550,8 +9273,7 @@ Using this option invalidates the given task and then runs the :ref:`ref-tasks-build` task, which is the default task if no task is given, and the tasks on which it depends. You could replace the final two commands in the previous example with -the following single command: -:: +the following single command:: $ bitbake matchbox-desktop -C compile @@ -9575,16 +9297,14 @@ task dependency mechanisms. and build output might not be in the clean state they would be in for a "normal" build, depending on what actions you took. To get rid of such warnings, you can remove the work directory and rebuild the - recipe, as follows: - :: + recipe, as follows:: $ bitbake matchbox-desktop -c clean $ bitbake matchbox-desktop You can view a list of tasks in a given package by running the -``do_listtasks`` task as follows: -:: +``do_listtasks`` task as follows:: $ bitbake matchbox-desktop -c listtasks @@ -9608,8 +9328,7 @@ Building with No Dependencies ----------------------------- To build a specific recipe (``.bb`` file), you can use the following -command form: -:: +command form:: $ bitbake -b somepath/somerecipe.bb @@ -9627,7 +9346,7 @@ Recipe Logging Mechanisms The Yocto Project provides several logging functions for producing debugging output and reporting errors and warnings. For Python -functions, the following logging functions exist. All of these functions +functions, the following logging functions are available. All of these functions log to ``${T}/log.do_``\ `task`, and can also log to standard output (stdout) with the right settings: @@ -9678,8 +9397,7 @@ in the log, use the "debug" loglevel. Following is an example written in Python. The code handles logging for a function that determines the number of tasks needed to be run. See the ":ref:`ref-tasks-listtasks`" -section for additional information: -:: +section for additional information:: python do_listtasks() { bb.debug(2, "Starting to figure out the task list") @@ -9734,8 +9452,8 @@ A parallel ``make`` race occurs when the build consists of several parts that are run simultaneously and a situation occurs when the output or result of one part is not ready for use with a different part of the build that depends on that output. Parallel make races are annoying and -can sometimes be difficult to reproduce and fix. However, some simple -tips and tricks exist that can help you debug and fix them. This section +can sometimes be difficult to reproduce and fix. However, there are some simple +tips and tricks that can help you debug and fix them. This section presents a real-world example of an error encountered on the Yocto Project autobuilder and the process used to fix it. @@ -9840,31 +9558,27 @@ So the first thing to do is build "neard" locally. Before you start the build, set the :term:`PARALLEL_MAKE` variable in your ``local.conf`` file to a high number (e.g. "-j 20"). Using a -high value for ``PARALLEL_MAKE`` increases the chances of the race -condition showing up: -:: +high value for :term:`PARALLEL_MAKE` increases the chances of the race +condition showing up:: $ bitbake neard -Once the local build for "neard" completes, start a ``devshell`` build: -:: +Once the local build for "neard" completes, start a ``devshell`` build:: $ bitbake neard -c devshell For information on how to use a ``devshell``, see the ":ref:`dev-manual/common-tasks:using a development shell`" section. -In the ``devshell``, do the following: -:: +In the ``devshell``, do the following:: $ make clean $ make tools/snep-send.o The ``devshell`` commands cause the failure to clearly -be visible. In this case, a missing dependency exists for the "neard" +be visible. In this case, there is a missing dependency for the ``neard`` Makefile target. Here is some abbreviated, sample output with the -missing dependency clearly visible at the end: -:: +missing dependency clearly visible at the end:: i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/...... . @@ -9885,8 +9599,7 @@ Creating a Patch for the Fix Because there is a missing dependency for the Makefile target, you need to patch the ``Makefile.am`` file, which is generated from -``Makefile.in``. You can use Quilt to create the patch: -:: +``Makefile.in``. You can use Quilt to create the patch:: $ quilt new parallelmake.patch Patch patches/parallelmake.patch is now on top @@ -9898,23 +9611,19 @@ For more information on using Quilt, see the At this point you need to make the edits to ``Makefile.am`` to add the missing dependency. For our example, you have to add the following line -to the file: -:: +to the file:: tools/snep-send.$(OBJEXT): include/near/dbus.h Once you have edited the file, use the ``refresh`` command to create the -patch: -:: +patch:: $ quilt refresh Refreshed patch patches/parallelmake.patch -Once -the patch file exists, you need to add it back to the originating recipe -folder. Here is an example assuming a top-level -:term:`Source Directory` named ``poky``: -:: +Once the patch file is created, you need to add it back to the originating +recipe folder. Here is an example assuming a top-level +:term:`Source Directory` named ``poky``:: $ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard @@ -9922,8 +9631,7 @@ The final thing you need to do to implement the fix in the build is to update the "neard" recipe (i.e. ``neard-0.14.bb``) so that the :term:`SRC_URI` statement includes the patch file. The recipe file is in the folder above the patch. Here -is what the edited ``SRC_URI`` statement would look like: -:: +is what the edited :term:`SRC_URI` statement would look like:: SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \ file://neard.in \ @@ -9932,8 +9640,7 @@ is what the edited ``SRC_URI`` statement would look like: " With the patch complete and moved to the correct folder and the -``SRC_URI`` statement updated, you can exit the ``devshell``: -:: +:term:`SRC_URI` statement updated, you can exit the ``devshell``:: $ exit @@ -9941,16 +9648,14 @@ Testing the Build ~~~~~~~~~~~~~~~~~ With everything in place, you can get back to trying the build again -locally: -:: +locally:: $ bitbake neard This build should succeed. Now you can open up a ``devshell`` again and repeat the clean and make -operations as follows: -:: +operations as follows:: $ bitbake neard -c devshell $ make clean @@ -9997,42 +9702,47 @@ methods you can use: running a debuginfod server and using gdbserver. Using the debuginfod server method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -"debuginfod" from "elfutils" is a way to distribute "debuginfo" files. -Running a "debuginfod" server makes debug symbols readily available, +``debuginfod`` from ``elfutils`` is a way to distribute ``debuginfo`` files. +Running a ``debuginfod`` server makes debug symbols readily available, which means you don't need to download debugging information and the binaries of the process being debugged. You can just fetch debug symbols from the server. -To run a debuginfod server, you need to do the following: +To run a ``debuginfod`` server, you need to do the following: -- Ensure that this variable is set in your ``local.conf`` file: - :: +- Ensure that ``debuginfod`` is present in :term:`DISTRO_FEATURES` + (it already is in ``OpenEmbedded-core`` defaults and ``poky`` reference distribution). + If not, set in your distro config file or in ``local.conf``:: - PACKAGECONFIG_pn-elfutils-native = "debuginfod libdebuginfod" + DISTRO_FEATURES_append = " debuginfod" - This :term:`PACKAGECONFIG` option enables debuginfod and libdebuginfod for - "elfutils-native". + This distro feature enables the server and client library in ``elfutils``, + and enables ``debuginfod`` support in clients (at the moment, ``gdb`` and ``binutils``). -- Run the following commands to set up the "debuginfod" server: - :: +- Run the following commands to launch the ``debuginfod`` server on the host:: $ oe-debuginfod +- To use ``debuginfod`` on the target, you need to know the ip:port where + ``debuginfod`` is listening on the host (port defaults to 8002), and export + that into the shell environment, for example in ``qemu``:: -To use debuginfod on the target, you need the following: + root@qemux86-64:~# export DEBUGINFOD_URLS="http://192.168.7.1:8002/" -- Ensure that this variable is set in your ``local.conf`` file: - :: - - DEBUGINFOD_URLS = "http://localhost:8002/" +- Then debug info fetching should simply work when running the target ``gdb``, + ``readelf`` or ``objdump``, for example:: - This :term:`DEBUGINFOD_URLS` option does the client configuration. + root@qemux86-64:~# gdb /bin/cat + ... + Reading symbols from /bin/cat... + Downloading separate debug info for /bin/cat... + Reading symbols from /home/root/.cache/debuginfod_client/923dc4780cfbc545850c616bffa884b6b5eaf322/debuginfo... - :: +- It's also possible to use ``debuginfod-find`` to just query the server:: - PACKAGECONFIG_pn-gdb = "debuginfod" + root@qemux86-64:~# debuginfod-find debuginfo /bin/ls + /home/root/.cache/debuginfod_client/356edc585f7f82d46f94fcb87a86a3fe2d2e60bd/debuginfo - This :term:`PACKAGECONFIG` option enables "debuginfod" for "gdb". Using the gdbserver method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -10069,8 +9779,7 @@ debugger. 1. *Configure your build system to construct the companion debug filesystem:* - In your ``local.conf`` file, set the following: - :: + In your ``local.conf`` file, set the following:: IMAGE_GEN_DEBUGFS = "1" IMAGE_FSTYPES_DEBUGFS = "tar.bz2" @@ -10090,8 +9799,7 @@ debugger. 2. *Configure the system to include gdbserver in the target filesystem:* Make the following addition in either your ``local.conf`` file or in - an image recipe: - :: + an image recipe:: IMAGE_INSTALL_append = " gdbserver" @@ -10101,29 +9809,25 @@ debugger. 3. *Build the environment:* Use the following command to construct the image and the companion - Debug Filesystem: - :: + Debug Filesystem:: $ bitbake image Build the cross GDB component and make it available for debugging. Build the SDK that matches the image. Building the SDK is best for a production build that can be - used later for debugging, especially during long term maintenance: - :: + used later for debugging, especially during long term maintenance:: $ bitbake -c populate_sdk image Alternatively, you can build the minimal toolchain components that match the target. Doing so creates a smaller than typical SDK and only contains a minimal set of components with which to build simple - test applications, as well as run the debugger: - :: + test applications, as well as run the debugger:: $ bitbake meta-toolchain - A final method is to build Gdb itself within the build system: - :: + A final method is to build Gdb itself within the build system:: $ bitbake gdb-cross-<architecture> @@ -10140,8 +9844,7 @@ debugger. 4. *Set up the* ``debugfs``\ *:* - Run the following commands to set up the ``debugfs``: - :: + Run the following commands to set up the ``debugfs``:: $ mkdir debugfs $ cd debugfs @@ -10180,8 +9883,7 @@ debugger. Documentation <https://www.gnu.org/software/gdb/documentation/>`__. After running gdbserver on the target, you need to run Gdb on the - host and configure it and connect to the target. Use these commands: - :: + host and configure it and connect to the target. Use these commands:: $ cd directory-holding-the-debugfs-directory $ arch-gdb @@ -10212,8 +9914,7 @@ debugger. If the binary is processed through the debug splitting in OpenEmbedded, you should also copy the debug items (i.e. ``.debug`` contents and corresponding ``/usr/src/debug`` files) from the work - directory. Here is an example: - :: + directory. Here is an example:: $ bitbake bash $ bitbake -c devshell bash @@ -10234,25 +9935,21 @@ debug on the target hardware. To support this kind of debugging, you need do the following: - Ensure that GDB is on the target. You can do this by adding "gdb" to - :term:`IMAGE_INSTALL`: - :: + :term:`IMAGE_INSTALL`:: IMAGE_INSTALL_append = " gdb" - Alternatively, you can add "tools-debug" to :term:`IMAGE_FEATURES`: - :: + Alternatively, you can add "tools-debug" to :term:`IMAGE_FEATURES`:: IMAGE_FEATURES_append = " tools-debug" - Ensure that debug symbols are present. You can make sure these - symbols are present by installing ``-dbg``: - :: + symbols are present by installing ``-dbg``:: IMAGE_INSTALL_append = "packagename-dbg" Alternatively, you can do the following to include - all the debug symbols: - :: + all the debug symbols:: IMAGE_FEATURES_append = " dbg-pkgs" @@ -10262,8 +9959,7 @@ To support this kind of debugging, you need do the following: of optimization used by the compiler. For example, when adding the following line to your ``local.conf`` file, you will reduce optimization from :term:`FULL_OPTIMIZATION` of "-O2" to :term:`DEBUG_OPTIMIZATION` - of "-O -fno-omit-frame-pointer": - :: + of "-O -fno-omit-frame-pointer":: DEBUG_BUILD = "1" @@ -10289,14 +9985,14 @@ Here are some other tips that you might find useful: - Removing :term:`TMPDIR` (usually ``tmp/``, within the :term:`Build Directory`) can often fix - temporary build issues. Removing ``TMPDIR`` is usually a relatively + temporary build issues. Removing :term:`TMPDIR` is usually a relatively cheap operation, because task output will be cached in :term:`SSTATE_DIR` (usually ``sstate-cache/``, which is also in the Build Directory). .. note:: - Removing ``TMPDIR`` might be a workaround rather than a fix. + Removing :term:`TMPDIR` might be a workaround rather than a fix. Consequently, trying to determine the underlying cause of an issue before removing the directory is a good idea. @@ -10307,8 +10003,7 @@ Here are some other tips that you might find useful: Using GNU Grep, you can use the following shell function to recursively search through common recipe-related files, skipping binary files, ``.git`` directories, and the Build Directory (assuming - its name starts with "build"): - :: + its name starts with "build"):: g() { grep -Ir \ @@ -10321,8 +10016,7 @@ Here are some other tips that you might find useful: "$@" } - Following are some usage examples: - :: + Following are some usage examples:: $ g FOO # Search recursively for "FOO" $ g -i foo # Search recursively for "foo", ignoring case @@ -10422,7 +10116,7 @@ specific uses. The Yocto Project uses a mailing list and a patch-based workflow that is similar to the Linux kernel but contains important differences. In -general, a mailing list exists through which you can submit patches. You +general, there is a mailing list through which you can submit patches. You should send patches to the appropriate mailing list so that they can be reviewed and merged by the appropriate maintainer. The specific mailing list you need to use depends on the location of the code you are @@ -10581,8 +10275,7 @@ Preparing Changes for Submission specific convention for bug references - any commit that addresses a specific bug should use the following form for the detailed description. Be sure to use the actual bug-tracking ID from - Bugzilla for bug-id: - :: + Bugzilla for bug-id:: Fixes [YOCTO #bug-id] @@ -10608,8 +10301,7 @@ without using the scripts once the steps in provide the command, you must include a revision list or a number of patches as part of the command. For example, either of these two commands takes your most recent single commit and formats it as an - email message in the current directory: - :: + email message in the current directory:: $ git format-patch -1 @@ -10701,8 +10393,7 @@ been followed: 1. *Push Your Commits to a "Contrib" Upstream:* If you have arranged for permissions to push to an upstream contrib repository, push the - change to that repository: - :: + change to that repository:: $ git push upstream_remote_repo local_branch_name @@ -10711,8 +10402,7 @@ been followed: working in a local branch named `your_name`\ ``/README``. The following command pushes your local commits to the ``meta-intel-contrib`` upstream repository and puts the commit in a branch named - `your_name`\ ``/README``: - :: + `your_name`\ ``/README``:: $ git push meta-intel-contrib your_name/README @@ -10729,8 +10419,7 @@ been followed: - *Search by File:* Using :ref:`overview-manual/development-environment:git`, you can enter the following command to bring up a short list of all - commits against a specific file: - :: + commits against a specific file:: git shortlog -- filename @@ -10764,8 +10453,7 @@ been followed: First, create the pull request. For example, the following command runs the script, specifies the upstream repository in the contrib directory into which you pushed the change, and provides a subject - line in the created patch files: - :: + line in the created patch files:: $ poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README" @@ -10778,8 +10466,7 @@ been followed: editing the cover letter, send the pull request. For example, the following command runs the script and specifies the patch directory and email address. In this example, the email address is a mailing - list: - :: + list:: $ poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org @@ -10788,8 +10475,7 @@ been followed: .. note:: For help on using these scripts, simply provide the ``-h`` - argument as follows: - :: + argument as follows:: $ poky/scripts/create-pull-request -h $ poky/scripts/send-pull-request -h @@ -10899,10 +10585,9 @@ build will fail. Specifying the ``LIC_FILES_CHKSUM`` Variable ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The ``LIC_FILES_CHKSUM`` variable contains checksums of the license text +The :term:`LIC_FILES_CHKSUM` variable contains checksums of the license text in the source code for the recipe. Following is an example of how to -specify ``LIC_FILES_CHKSUM``: -:: +specify :term:`LIC_FILES_CHKSUM`:: LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ @@ -10922,11 +10607,10 @@ specify ``LIC_FILES_CHKSUM``: The build system uses the :term:`S` variable as the default directory when searching files listed in -``LIC_FILES_CHKSUM``. The previous example employs the default +:term:`LIC_FILES_CHKSUM`. The previous example employs the default directory. -Consider this next example: -:: +Consider this next example:: LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\ md5=bb14ed3c4cda583abc85401304b5cd4e" @@ -10936,13 +10620,13 @@ The first line locates a file in ``${S}/src/ls.c`` and isolates lines five through 16 as license text. The second line refers to a file in :term:`WORKDIR`. -Note that ``LIC_FILES_CHKSUM`` variable is mandatory for all recipes, -unless the ``LICENSE`` variable is set to "CLOSED". +Note that :term:`LIC_FILES_CHKSUM` variable is mandatory for all recipes, +unless the :term:`LICENSE` variable is set to "CLOSED". Explanation of Syntax ~~~~~~~~~~~~~~~~~~~~~ -As mentioned in the previous section, the ``LIC_FILES_CHKSUM`` variable +As mentioned in the previous section, the :term:`LIC_FILES_CHKSUM` variable lists all the important files that contain the license text for the source code. It is possible to specify a checksum for an entire file, or a specific section of a file (specified by beginning and ending line @@ -10962,7 +10646,7 @@ build, the correct md5 checksum is placed in the build log and can be easily copied to the recipe. There is no limit to how many files you can specify using the -``LIC_FILES_CHKSUM`` variable. Generally, however, every project +:term:`LIC_FILES_CHKSUM` variable. Generally, however, every project requires a few specifications for license tracking. Many projects have a "COPYING" file that stores the license information for all the source code files. This practice allows you to just track the "COPYING" file as @@ -10988,31 +10672,28 @@ are defined on a recipe-by-recipe basis through the :term:`LICENSE_FLAGS` variable definition in the affected recipe. For instance, the ``poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly`` recipe -contains the following statement: -:: +contains the following statement:: LICENSE_FLAGS = "commercial" Here is a slightly more complicated example that contains both an explicit recipe -name and version (after variable expansion): -:: +name and version (after variable expansion):: LICENSE_FLAGS = "license_${PN}_${PV}" In order for a component restricted by a -``LICENSE_FLAGS`` definition to be enabled and included in an image, it +:term:`LICENSE_FLAGS` definition to be enabled and included in an image, it needs to have a matching entry in the global :term:`LICENSE_FLAGS_WHITELIST` variable, which is a variable typically defined in your ``local.conf`` file. For example, to enable the ``poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly`` package, you could add either the string "commercial_gst-plugins-ugly" or the more -general string "commercial" to ``LICENSE_FLAGS_WHITELIST``. See the +general string "commercial" to :term:`LICENSE_FLAGS_WHITELIST`. See the ":ref:`dev-manual/common-tasks:license flag matching`" section for a full -explanation of how ``LICENSE_FLAGS`` matching works. Here is the -example: -:: +explanation of how :term:`LICENSE_FLAGS` matching works. Here is the +example:: LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" @@ -11020,8 +10701,7 @@ Likewise, to additionally enable the package built from the recipe containing ``LICENSE_FLAGS = "license_${PN}_${PV}"``, and assuming that the actual recipe name was ``emgd_1.10.bb``, the following string would enable that package as well as the original ``gst-plugins-ugly`` -package: -:: +package:: LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" @@ -11043,8 +10723,8 @@ License Flag Matching License flag matching allows you to control what recipes the OpenEmbedded build system includes in the build. Fundamentally, the -build system attempts to match ``LICENSE_FLAGS`` strings found in -recipes against ``LICENSE_FLAGS_WHITELIST`` strings found in the +build system attempts to match :term:`LICENSE_FLAGS` strings found in +recipes against :term:`LICENSE_FLAGS_WHITELIST` strings found in the whitelist. A match causes the build system to include a recipe in the build, while failure to find a match causes the build system to exclude a recipe. @@ -11054,14 +10734,14 @@ concepts will help you correctly and effectively use matching. Before a flag defined by a particular recipe is tested against the contents of the whitelist, the expanded string ``_${PN}`` is appended to -the flag. This expansion makes each ``LICENSE_FLAGS`` value +the flag. This expansion makes each :term:`LICENSE_FLAGS` value recipe-specific. After expansion, the string is then matched against the whitelist. Thus, specifying ``LICENSE_FLAGS = "commercial"`` in recipe "foo", for example, results in the string ``"commercial_foo"``. And, to create a match, that string must appear in the whitelist. -Judicious use of the ``LICENSE_FLAGS`` strings and the contents of the -``LICENSE_FLAGS_WHITELIST`` variable allows you a lot of flexibility for +Judicious use of the :term:`LICENSE_FLAGS` strings and the contents of the +:term:`LICENSE_FLAGS_WHITELIST` variable allows you a lot of flexibility for including or excluding recipes based on licensing. For example, you can broaden the matching capabilities by using license flags string subsets in the whitelist. @@ -11073,12 +10753,11 @@ in the whitelist. ``usethispart_1.3``, ``usethispart_1.4``, and so forth). For example, simply specifying the string "commercial" in the whitelist -matches any expanded ``LICENSE_FLAGS`` definition that starts with the +matches any expanded :term:`LICENSE_FLAGS` definition that starts with the string "commercial" such as "commercial_foo" and "commercial_bar", which are the strings the build system automatically generates for hypothetical recipes named "foo" and "bar" assuming those recipes simply -specify the following: -:: +specify the following:: LICENSE_FLAGS = "commercial" @@ -11088,7 +10767,7 @@ only specific recipes into the image, or you can use a string subset that causes a broader range of matches to allow a range of recipes into the image. -This scheme works even if the ``LICENSE_FLAGS`` string already has +This scheme works even if the :term:`LICENSE_FLAGS` string already has ``_${PN}`` appended. For example, the build system turns the license flag "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would match both the general "commercial" and the specific "commercial_1.2_foo" @@ -11114,10 +10793,9 @@ Here are some other scenarios: Other Variables Related to Commercial Licenses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Other helpful variables related to commercial license handling exist and -are defined in the -``poky/meta/conf/distro/include/default-distrovars.inc`` file: -:: +There are other helpful variables related to commercial license handling, +defined in the +``poky/meta/conf/distro/include/default-distrovars.inc`` file:: COMMERCIAL_AUDIO_PLUGINS ?= "" COMMERCIAL_VIDEO_PLUGINS ?= "" @@ -11125,8 +10803,7 @@ are defined in the If you want to enable these components, you can do so by making sure you have statements similar to the following in your ``local.conf`` configuration -file: -:: +file:: COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ gst-plugins-ugly-mpegaudioparse" @@ -11137,15 +10814,14 @@ file: Of course, you could also create a matching whitelist for those components using the more general "commercial" in the whitelist, but -that would also enable all the other packages with ``LICENSE_FLAGS`` -containing "commercial", which you may or may not want: -:: +that would also enable all the other packages with :term:`LICENSE_FLAGS` +containing "commercial", which you may or may not want:: LICENSE_FLAGS_WHITELIST = "commercial" Specifying audio and video plugins as part of the ``COMMERCIAL_AUDIO_PLUGINS`` and ``COMMERCIAL_VIDEO_PLUGINS`` statements -(along with the enabling ``LICENSE_FLAGS_WHITELIST``) includes the +(along with the enabling :term:`LICENSE_FLAGS_WHITELIST`) includes the plugins or components into built images, thus adding support for media formats or components. @@ -11162,7 +10838,7 @@ requirements during a software release. With hundreds of different open source licenses that the Yocto Project tracks, it is difficult to know the requirements of each and every license. However, the requirements of the major FLOSS licenses can begin -to be covered by assuming that three main areas of concern exist: +to be covered by assuming that there are three main areas of concern: - Source code must be provided. @@ -11211,7 +10887,7 @@ accidental release of proprietary software. The Yocto Project provides an :ref:`archiver <ref-classes-archiver>` class to help avoid some of these concerns. -Before you employ ``DL_DIR`` or the ``archiver`` class, you need to +Before you employ :term:`DL_DIR` or the ``archiver`` class, you need to decide how you choose to provide source. The source ``archiver`` class can generate tarballs and SRPMs and can create them with various levels of compliance in mind. @@ -11219,8 +10895,7 @@ of compliance in mind. One way of doing this (but certainly not the only way) is to release just the source as a tarball. You can do this by adding the following to the ``local.conf`` file found in the -:term:`Build Directory`: -:: +:term:`Build Directory`:: INHERIT += "archiver" ARCHIVER_MODE[src] = "original" @@ -11276,8 +10951,7 @@ One requirement that is often overlooked is inclusion of license text. This requirement also needs to be dealt with prior to generating the final image. Some licenses require the license text to accompany the binary. You can achieve this by adding the following to your -``local.conf`` file: -:: +``local.conf`` file:: COPY_LIC_MANIFEST = "1" COPY_LIC_DIRS = "1" @@ -11344,8 +11018,7 @@ thing a development organization might want to consider for end-user convenience is to modify ``meta-poky/conf/bblayers.conf.sample`` to ensure that when the end user utilizes the released build system to build an image, the development organization's layers are included in -the ``bblayers.conf`` file automatically: -:: +the ``bblayers.conf`` file automatically:: # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf # changes incompatibly @@ -11382,7 +11055,7 @@ this function, you have to follow the following steps: 3. Meta-spdxscanner provides several methods within the bbclass to create spdx files. Please choose one that you want to use and enable the spdx task. You have to add some config options in ``local.conf`` file in your :term:`Build - Directory`. The following is an example showing how to generate spdx files + Directory`. Here is an example showing how to generate spdx files during bitbake using the fossology-python.bbclass:: # Select fossology-python.bbclass. @@ -11412,9 +11085,8 @@ package, by using the variable. Using this variable also avoids QA errors when you use a non-common, non-CLOSED license in a recipe. -The following is an example that uses the ``LICENSE.Abilis.txt`` file as -the license from the fetched source: -:: +Here is an example that uses the ``LICENSE.Abilis.txt`` file as +the license from the fetched source:: NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt" @@ -11430,9 +11102,9 @@ portion is integrated with the installed Yocto Project The server receives the information collected and saves it in a database. -A live instance of the error reporting server exists at -https://errors.yoctoproject.org. This server exists so that when -you want to get help with build failures, you can submit all of the +There is a live instance of the error reporting server at +https://errors.yoctoproject.org. +When you want to get help with build failures, you can submit all of the information on the failure easily and then point to the URL in your bug report or send an email to the mailing list. @@ -11457,8 +11129,7 @@ class by adding the following statement to the end of your By default, the error reporting feature stores information in ``${``\ :term:`LOG_DIR`\ ``}/error-report``. However, you can specify a directory to use by adding the following to -your ``local.conf`` file: -:: +your ``local.conf`` file:: ERR_REPORT_DIR = "path" @@ -11467,8 +11138,7 @@ reporting causes the build process to collect the errors and store them in a file as previously described. When the build system encounters an error, it includes a command as part of the console output. You can run the command to send the error file to the server. For example, the -following command sends the errors to an upstream server: -:: +following command sends the errors to an upstream server:: $ send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt @@ -11476,8 +11146,7 @@ In the previous example, the errors are sent to a public database available at https://errors.yoctoproject.org, which is used by the entire community. If you specify a particular server, you can send the errors to a different database. Use the following command for more -information on available options: -:: +information on available options:: $ send-error-report --help @@ -11557,8 +11226,7 @@ Wayland with Kernel Mode Setting (`KMS <https://wiki.archlinux.org/index.php/Kernel_Mode_Setting>`__) support, include the "wayland" flag in the :term:`DISTRO_FEATURES` -statement in your ``local.conf`` file: -:: +statement in your ``local.conf`` file:: DISTRO_FEATURES_append = " wayland" @@ -11573,8 +11241,7 @@ Installing Wayland and Weston To install the Wayland feature into an image, you must include the following :term:`CORE_IMAGE_EXTRA_INSTALL` -statement in your ``local.conf`` file: -:: +statement in your ``local.conf`` file:: CORE_IMAGE_EXTRA_INSTALL += "wayland weston" @@ -11589,14 +11256,12 @@ Alternatively, you can run Weston through the command-line interpretor (CLI), which is better suited for development work. To run Weston under the CLI, you need to do the following after your image is built: -1. Run these commands to export ``XDG_RUNTIME_DIR``: - :: +1. Run these commands to export ``XDG_RUNTIME_DIR``:: mkdir -p /tmp/$USER-weston chmod 0700 /tmp/$USER-weston export XDG_RUNTIME_DIR=/tmp/$USER-weston -2. Launch Weston in the shell: - :: +2. Launch Weston in the shell:: weston diff --git a/poky/documentation/dev-manual/qemu.rst b/poky/documentation/dev-manual/qemu.rst index 92799d6d2..88a63c180 100644 --- a/poky/documentation/dev-manual/qemu.rst +++ b/poky/documentation/dev-manual/qemu.rst @@ -55,16 +55,14 @@ available. Follow these general steps to run QEMU: - If you cloned the ``poky`` repository or you downloaded and unpacked a Yocto Project release tarball, you can source the build - environment script (i.e. :ref:`structure-core-script`): - :: + environment script (i.e. :ref:`structure-core-script`):: $ cd poky $ source oe-init-build-env - If you installed a cross-toolchain, you can run the script that initializes the toolchain. For example, the following commands run - the initialization script from the default ``poky_sdk`` directory: - :: + the initialization script from the default ``poky_sdk`` directory:: . poky_sdk/environment-setup-core2-64-poky-linux @@ -86,8 +84,7 @@ available. Follow these general steps to run QEMU: Extensible Software Development Kit (eSDK) manual for information on how to extract a root filesystem. -4. *Run QEMU:* The basic ``runqemu`` command syntax is as follows: - :: +4. *Run QEMU:* The basic ``runqemu`` command syntax is as follows:: $ runqemu [option ] [...] @@ -222,18 +219,15 @@ using an NFS server. Should you need to start, stop, or restart the NFS share, you can use the following commands: - - The following command starts the NFS share: - :: + - To start the NFS share:: runqemu-export-rootfs start file-system-location - - The following command stops the NFS share: - :: + - To stop the NFS share:: runqemu-export-rootfs stop file-system-location - - The following command restarts the NFS share: - :: + - To restart the NFS share:: runqemu-export-rootfs restart file-system-location @@ -281,7 +275,7 @@ present, the toolchain is also automatically used. .. note:: - Several mechanisms exist that let you connect to the system running + There are several mechanisms to connect to the system running on the QEMU emulator: - QEMU provides a framebuffer interface that makes standard consoles @@ -292,7 +286,7 @@ present, the toolchain is also automatically used. that port to run a console. The connection uses standard IP networking. - - SSH servers exist in some QEMU images. The ``core-image-sato`` + - SSH servers are available in some QEMU images. The ``core-image-sato`` QEMU image has a Dropbear secure shell (SSH) server that runs with the root password disabled. The ``core-image-full-cmdline`` and ``core-image-lsb`` QEMU images have OpenSSH instead of Dropbear. @@ -313,8 +307,7 @@ present, the toolchain is also automatically used. QEMU Command-Line Syntax ======================== -The basic ``runqemu`` command syntax is as follows: -:: +The basic ``runqemu`` command syntax is as follows:: $ runqemu [option ] [...] @@ -325,8 +318,7 @@ timestamp when it needs to look for an image. Minimally, through the use of options, you must provide either a machine name, a virtual machine image (``*wic.vmdk``), or a kernel image (``*.bin``). -Following is the command-line help output for the ``runqemu`` command: -:: +Following is the command-line help output for the ``runqemu`` command:: $ runqemu --help diff --git a/poky/documentation/dev-manual/start.rst b/poky/documentation/dev-manual/start.rst index 84abf4c51..c3276c950 100644 --- a/poky/documentation/dev-manual/start.rst +++ b/poky/documentation/dev-manual/start.rst @@ -36,7 +36,7 @@ particular working environment and set of practices. equipment together and set up your development environment's hardware topology. - The following roles exist: + Here are possible roles: - *Application Developer:* This type of developer does application level work on top of an existing software stack. @@ -99,8 +99,7 @@ particular working environment and set of practices. .. note:: The setup of these services is beyond the scope of this manual. - However, sites such as the following exist that describe how to - perform setup: + However, here are sites describing how to perform setup: - `Gitolite <https://gitolite.com>`__: Information for ``gitolite``. @@ -190,7 +189,7 @@ particular working environment and set of practices. develop locally using their primary development system. 9. *Document Policies and Change Flow:* The Yocto Project uses a - hierarchical structure and a pull model. Scripts exist to create and + hierarchical structure and a pull model. There are scripts to create and send pull requests (i.e. ``create-pull-request`` and ``send-pull-request``). This model is in line with other open source projects where maintainers are responsible for specific areas of the @@ -215,8 +214,8 @@ particular working environment and set of practices. someone else in the community needs them also. 10. *Development Environment Summary:* Aside from the previous steps, - some best practices exist within the Yocto Project development - environment. Consider the following: + here are best practices within the Yocto Project development + environment: - Use :ref:`overview-manual/development-environment:git` as the source control system. @@ -387,36 +386,28 @@ as your Yocto Project build host: software. Follow the instructions for your specific machine and the type of the software you need to install: - - Install `Docker CE for + - Install `Docker Desktop on Windows <https://docs.docker.com/docker-for-windows/install/#install-docker-desktop-on-windows>`__ for Windows build hosts that meet requirements. - - Install `Docker CE for + - Install `Docker Desktop on MacOs <https://docs.docker.com/docker-for-mac/install/#install-and-run-docker-desktop-on-mac>`__ for Mac build hosts that meet requirements. - - Install `Docker Toolbox for - Windows <https://docs.docker.com/toolbox/toolbox_install_windows/>`__ - for Windows build hosts that do not meet Docker requirements. - - - Install `Docker Toolbox for - MacOS <https://docs.docker.com/toolbox/toolbox_install_mac/>`__ - for Mac build hosts that do not meet Docker requirements. - - - Install `Docker CE for - CentOS <https://docs.docker.com/install/linux/docker-ce/centos/>`__ + - Install `Docker Engine on + CentOS <https://docs.docker.com/engine/install/centos/>`__ for Linux build hosts running the CentOS distribution. - - Install `Docker CE for - Debian <https://docs.docker.com/install/linux/docker-ce/debian/>`__ + - Install `Docker Engine on + Debian <https://docs.docker.com/engine/install/debian/>`__ for Linux build hosts running the Debian distribution. - - Install `Docker CE for - Fedora <https://docs.docker.com/install/linux/docker-ce/fedora/>`__ + - Install `Docker Engine for + Fedora <https://docs.docker.com/engine/install/fedora/>`__ for Linux build hosts running the Fedora distribution. - - Install `Docker CE for - Ubuntu <https://docs.docker.com/install/linux/docker-ce/ubuntu/>`__ + - Install `Docker Engine for + Ubuntu <https://docs.docker.com/engine/install/ubuntu/>`__ for Linux build hosts running the Ubuntu distribution. 5. *Optionally Orient Yourself With Docker:* If you are unfamiliar with @@ -486,8 +477,7 @@ your Yocto Project build host: distribution. 3. *Check your Linux distribution is using WSLv2:* Open a Windows - PowerShell and run: - :: + PowerShell and run:: C:\WINDOWS\system32> wsl -l -v NAME STATE VERSION @@ -514,8 +504,7 @@ your Yocto Project build host: 1. *Find the location of your VHDX file:* First you need to find the distro app package directory, to achieve this open a Windows - Powershell as Administrator and run: - :: + Powershell as Administrator and run:: C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName PackageFamilyName @@ -525,8 +514,7 @@ your Yocto Project build host: You should now replace the PackageFamilyName and your user on the following path - to find your VHDX file: - :: + to find your VHDX file:: ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ Mode LastWriteTime Length Name @@ -536,8 +524,7 @@ your Yocto Project build host: ``C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx`` 2. *Optimize your VHDX file:* Open a Windows Powershell as - Administrator to optimize your VHDX file, shutting down WSL first: - :: + Administrator to optimize your VHDX file, shutting down WSL first:: C:\WINDOWS\system32> wsl --shutdown C:\WINDOWS\system32> optimize-vhd -Path C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx -Mode full @@ -619,8 +606,8 @@ of a given component. The recommended method for accessing Yocto Project components is to use Git to clone the upstream repository and work from within that - locally cloned repository. The procedure in this section exists - should you desire a tarball snapshot of any given component. + locally cloned repository. However, this section documents how to + use a tarball snapshot of any given component. Follow these steps to locate and download a particular tarball: @@ -657,13 +644,6 @@ release. Rather than Git repositories, these files represent snapshot tarballs similar to the tarballs located in the Index of Releases described in the ":ref:`dev-manual/start:accessing index of releases`" section. -.. note:: - - The recommended method for accessing Yocto Project components is to - use Git to clone a repository and work from within that local - repository. The procedure in this section exists should you desire a - tarball snapshot of any given component. - 1. *Go to the Yocto Project Website:* Open The :yocto_home:`Yocto Project Website <>` in your browser. @@ -741,8 +721,7 @@ Follow these steps to create a local version of the upstream 2. *Clone the Repository:* The following example command clones the ``poky`` repository and uses the default name "poky" for your local - repository: - :: + repository:: $ git clone git://git.yoctoproject.org/poky Cloning into 'poky'... @@ -763,9 +742,8 @@ Follow these steps to create a local version of the upstream ":ref:`dev-manual/start:checking out by tag in poky`" sections, respectively. Once the local repository is created, you can change to that - directory and check its status. Here, the single "master" branch - exists on your system and by default, it is checked out: - :: + directory and check its status. The ``master`` branch is checked out + by default:: $ cd poky $ git status @@ -826,8 +804,7 @@ and then specifically check out that development branch. 3. *Check out the Branch:* Check out the development branch in which you want to work. For example, to access the files for the Yocto Project - &DISTRO; Release (&DISTRO_NAME;), use the following command: - :: + &DISTRO; Release (&DISTRO_NAME;), use the following command:: $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP; Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin. @@ -839,8 +816,7 @@ and then specifically check out that development branch. The following command displays the branches that are now part of your local poky repository. The asterisk character indicates the branch - that is currently checked out for work: - :: + that is currently checked out for work:: $ git branch master @@ -867,14 +843,12 @@ similar to checking out by branch name except you use tag names. section. 2. *Fetch the Tag Names:* To checkout the branch based on a tag name, - you need to fetch the upstream tags into your local repository: - :: + you need to fetch the upstream tags into your local repository:: $ git fetch --tags $ -3. *List the Tag Names:* You can list the tag names now: - :: +3. *List the Tag Names:* You can list the tag names now:: $ git tag 1.1_M1.final diff --git a/poky/documentation/index.rst b/poky/documentation/index.rst index 6aeeb2197..0fca6ce72 100644 --- a/poky/documentation/index.rst +++ b/poky/documentation/index.rst @@ -38,16 +38,15 @@ Welcome to the Yocto Project Documentation .. toctree:: :maxdepth: 1 - :caption: 'Mega' Manual + :caption: Releases manual + :hidden: - All-in-one 'Mega' Manual <https://docs.yoctoproject.org/singleindex.html> + Release Migration Guides <migration-guides/index> + releases .. toctree:: :maxdepth: 1 - :caption: Manuals/Variable Index + :caption: Documentation Index + :hidden: genindex - Current/Previous Version Specific Manuals <releases> - - - diff --git a/poky/documentation/kernel-dev/advanced.rst b/poky/documentation/kernel-dev/advanced.rst index fb6dfca85..871ec8ae7 100644 --- a/poky/documentation/kernel-dev/advanced.rst +++ b/poky/documentation/kernel-dev/advanced.rst @@ -21,7 +21,7 @@ is the ``yocto-kernel-cache`` Git repository. You can find this repository grouped under the "Yocto Linux Kernel" heading in the :yocto_git:`Yocto Project Source Repositories <>`. -Kernel development tools ("kern-tools") exist also in the Yocto Project +Kernel development tools ("kern-tools") are also available in the Yocto Project Source Repositories under the "Yocto Linux Kernel" heading in the ``yocto-kernel-tools`` Git repository. The recipe that builds these tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in @@ -46,15 +46,15 @@ linux-yocto recipe. Every linux-yocto style recipe must define the :term:`KMACHINE` variable. This -variable is typically set to the same value as the ``MACHINE`` variable, +variable is typically set to the same value as the :term:`MACHINE` variable, which is used by :term:`BitBake`. However, in some cases, the variable might instead refer to the -underlying platform of the ``MACHINE``. +underlying platform of the :term:`MACHINE`. -Multiple BSPs can reuse the same ``KMACHINE`` name if they are built +Multiple BSPs can reuse the same :term:`KMACHINE` name if they are built using the same BSP description. Multiple Corei7-based BSPs could share -the same "intel-corei7-64" value for ``KMACHINE``. It is important to -realize that ``KMACHINE`` is just for kernel mapping, while ``MACHINE`` +the same "intel-corei7-64" value for :term:`KMACHINE`. It is important to +realize that :term:`KMACHINE` is just for kernel mapping, while :term:`MACHINE` is the machine type within a BSP Layer. Even with this distinction, however, these two variables can hold the same value. See the ":ref:`kernel-dev/advanced:bsp descriptions`" section for more information. @@ -66,9 +66,8 @@ to indicate the branch. .. note:: - You can use the ``KBRANCH`` value to define an alternate branch typically - with a machine override as shown here from the ``meta-yocto-bsp`` layer: - :: + You can use the :term:`KBRANCH` value to define an alternate branch typically + with a machine override as shown here from the ``meta-yocto-bsp`` layer:: KBRANCH_edgerouter = "standard/edgerouter" @@ -82,8 +81,8 @@ variables: :term:`LINUX_KERNEL_TYPE` defines the kernel type to be used in assembling the configuration. If -you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to "standard". -Together with ``KMACHINE``, ``LINUX_KERNEL_TYPE`` defines the search +you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to "standard". +Together with :term:`KMACHINE`, :term:`LINUX_KERNEL_TYPE` defines the search arguments used by the kernel tools to find the appropriate description within the kernel Metadata with which to build out the sources and configuration. The linux-yocto recipes define "standard", "tiny", and @@ -91,35 +90,33 @@ configuration. The linux-yocto recipes define "standard", "tiny", and section for more information on kernel types. During the build, the kern-tools search for the BSP description file -that most closely matches the ``KMACHINE`` and ``LINUX_KERNEL_TYPE`` +that most closely matches the :term:`KMACHINE` and :term:`LINUX_KERNEL_TYPE` variables passed in from the recipe. The tools use the first BSP description they find that matches both variables. If the tools cannot find a match, they issue a warning. -The tools first search for the ``KMACHINE`` and then for the -``LINUX_KERNEL_TYPE``. If the tools cannot find a partial match, they -will use the sources from the ``KBRANCH`` and any configuration +The tools first search for the :term:`KMACHINE` and then for the +:term:`LINUX_KERNEL_TYPE`. If the tools cannot find a partial match, they +will use the sources from the :term:`KBRANCH` and any configuration specified in the :term:`SRC_URI`. You can use the :term:`KERNEL_FEATURES` variable to include features (configuration fragments, patches, or both) -that are not already included by the ``KMACHINE`` and -``LINUX_KERNEL_TYPE`` variable combination. For example, to include a -feature specified as "features/netfilter/netfilter.scc", specify: -:: +that are not already included by the :term:`KMACHINE` and +:term:`LINUX_KERNEL_TYPE` variable combination. For example, to include a +feature specified as "features/netfilter/netfilter.scc", specify:: KERNEL_FEATURES += "features/netfilter/netfilter.scc" To include a feature called "cfg/sound.scc" just for the ``qemux86`` machine, -specify: -:: +specify:: KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc" The value of -the entries in ``KERNEL_FEATURES`` are dependent on their location +the entries in :term:`KERNEL_FEATURES` are dependent on their location within the kernel Metadata itself. The examples here are taken from the ``yocto-kernel-cache`` repository. Each branch of this repository contains "features" and "cfg" subdirectories at the top-level. For more @@ -157,8 +154,7 @@ types to form the final description of what will be assembled and built. While the kernel Metadata syntax does not enforce any logical separation of configuration fragments, patches, features or kernel types, best practices dictate a logical separation of these types of Metadata. The -following Metadata file hierarchy is recommended: -:: +following Metadata file hierarchy is recommended:: base/ bsp/ @@ -222,8 +218,7 @@ used with the ``linux-yocto-4.12`` kernel as defined outside of the recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the ``cfg`` directory of the ``yocto-4.12`` branch in the -``yocto-kernel-cache`` Git repository: -:: +``yocto-kernel-cache`` Git repository:: cfg/smp.scc: define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds" @@ -265,8 +260,7 @@ non-hardware fragment. As described in the ":ref:`kernel-dev/common:validating configuration`" section, you can -use the following BitBake command to audit your configuration: -:: +use the following BitBake command to audit your configuration:: $ bitbake linux-yocto -c kernel_configcheck -f @@ -287,8 +281,7 @@ in the ``patches/build`` directory of the ``yocto-4.12`` branch in the ``yocto-kernel-cache`` Git repository. The following listings show the ``build.scc`` file and part of the -``modpost-mask-trivial-warnings.patch`` file: -:: +``modpost-mask-trivial-warnings.patch`` file:: patches/build/build.scc: patch arm-serialize-build-targets.patch @@ -320,7 +313,7 @@ The following listings show the ``build.scc`` file and part of the The description file can include multiple patch statements where each statement handles a single -patch. In the example ``build.scc`` file, five patch statements exist +patch. In the example ``build.scc`` file, there are five patch statements for the five patches in the directory. You can create a typical ``.patch`` file using ``diff -Nurp`` or @@ -334,8 +327,7 @@ Features Features are complex kernel Metadata types that consist of configuration fragments, patches, and possibly other feature description files. As an -example, consider the following generic listing: -:: +example, consider the following generic listing:: features/myfeature.scc define KFEATURE_DESCRIPTION "Enable myfeature" @@ -352,7 +344,7 @@ as how an additional feature description file is included with the Typically, features are less granular than configuration fragments and are more likely than configuration fragments and patches to be the types -of things you want to specify in the ``KERNEL_FEATURES`` variable of the +of things you want to specify in the :term:`KERNEL_FEATURES` variable of the Linux kernel recipe. See the ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier in the manual. @@ -371,15 +363,13 @@ the ``linux-yocto_4.12.bb`` kernel recipe found in ``poky/meta/recipes-kernel/linux``, a :ref:`require <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` directive includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file, -which has the following statement that defines the default kernel type: -:: +which has the following statement that defines the default kernel type:: LINUX_KERNEL_TYPE ??= "standard" Another example would be the real-time kernel (i.e. ``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel -type as follows: -:: +type as follows:: LINUX_KERNEL_TYPE = "preempt-rt" @@ -412,8 +402,7 @@ for Linux Yocto kernels: For any given kernel type, the Metadata is defined by the ``.scc`` (e.g. ``standard.scc``). Here is a partial listing for the ``standard.scc`` file, which is found in the ``ktypes/standard`` directory of the -``yocto-kernel-cache`` Git repository: -:: +``yocto-kernel-cache`` Git repository:: # Include this kernel type fragment to get the standard features and # configuration values. @@ -482,15 +471,13 @@ Description Overview For simplicity, consider the following root BSP layer description files for the BeagleBone board. These files employ both a structure and naming convention for consistency. The naming convention for the file is as -follows: -:: +follows:: bsp_root_name-kernel_type.scc Here are some example root layer BSP filenames for the BeagleBone Board BSP, which is supported by the -Yocto Project: -:: +Yocto Project:: beaglebone-standard.scc beaglebone-preempt-rt.scc @@ -498,8 +485,7 @@ Yocto Project: Each file uses the root name (i.e "beaglebone") BSP name followed by the kernel type. -Examine the ``beaglebone-standard.scc`` file: -:: +Examine the ``beaglebone-standard.scc`` file:: define KMACHINE beaglebone define KTYPE standard @@ -523,18 +509,17 @@ description as meeting the criteria set by the recipe being built. This example supports the "beaglebone" machine for the "standard" kernel and the "arm" architecture. -Be aware that a hard link between the ``KTYPE`` variable and a kernel -type description file does not exist. Thus, if you do not have the +Be aware that there is no hard link between the :term:`KTYPE` variable and a kernel +type description file. Thus, if you do not have the kernel type defined in your kernel Metadata as it is here, you only need to ensure that the :term:`LINUX_KERNEL_TYPE` -variable in the kernel recipe and the ``KTYPE`` variable in the BSP +variable in the kernel recipe and the :term:`KTYPE` variable in the BSP description file match. To separate your kernel policy from your hardware configuration, you include a kernel type (``ktype``), such as "standard". In the previous -example, this is done using the following: -:: +example, this is done using the following:: include ktypes/standard/standard.scc @@ -544,13 +529,11 @@ policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more information. To aggregate common configurations and features specific to the kernel -for `mybsp`, use the following: -:: +for `mybsp`, use the following:: include mybsp.scc -You can see that in the BeagleBone example with the following: -:: +You can see that in the BeagleBone example with the following:: include beaglebone.scc @@ -558,15 +541,13 @@ For information on how to break a complete ``.config`` file into the various configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" section. Finally, if you have any configurations specific to the hardware that -are not in a ``*.scc`` file, you can include them as follows: -:: +are not in a ``*.scc`` file, you can include them as follows:: kconf hardware mybsp-extra.cfg The BeagleBone example does not include these types of configurations. However, the Malta 32-bit board does -("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file: -:: +("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file:: define KMACHINE mti-malta32-le define KMACHINE qemumipsel @@ -623,8 +604,7 @@ found on the machine. This ``minnow.scc`` description file is then included in each of the three "minnow" description files for the supported kernel types (i.e. "standard", "preempt-rt", and "tiny"). Consider the "minnow" description for the "standard" kernel type (i.e. -``minnow-standard.scc``): -:: +``minnow-standard.scc``):: define KMACHINE minnow define KTYPE standard @@ -656,8 +636,7 @@ that defines all enabled hardware for the BSP that is common to all kernel types. Using this command significantly reduces duplication. Now consider the "minnow" description for the "tiny" kernel type (i.e. -``minnow-tiny.scc``): -:: +``minnow-tiny.scc``):: define KMACHINE minnow define KTYPE tiny @@ -678,7 +657,7 @@ Notice again the three critical variables: :term:`KMACHINE`, :term:`KTYPE`, and :term:`KARCH`. Of these variables, only -``KTYPE`` has changed to specify the "tiny" kernel type. +:term:`KTYPE` has changed to specify the "tiny" kernel type. Kernel Metadata Location ======================== @@ -714,14 +693,13 @@ directory hierarchy below a linux-yocto recipe or for a Linux kernel recipe derived by copying and modifying ``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to -a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to +a recipe in your layer, :term:`FILESEXTRAPATHS` is typically set to ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``. See the ":ref:`kernel-dev/common:modifying an existing recipe`" section for more information. Here is an example that shows a trivial tree of kernel Metadata stored -in recipe-space within a BSP layer: -:: +in recipe-space within a BSP layer:: meta-my_bsp_layer/ `-- recipes-kernel @@ -740,12 +718,11 @@ and fetches any files referenced in the ``.scc`` files by the ``include``, ``patch``, or ``kconf`` commands. Because of this, it is necessary to bump the recipe :term:`PR` value when changing the content of files not explicitly listed in the -``SRC_URI``. +:term:`SRC_URI`. If the BSP description is in recipe space, you cannot simply list the -``*.scc`` in the ``SRC_URI`` statement. You need to use the following -form from your kernel append file: -:: +``*.scc`` in the :term:`SRC_URI` statement. You need to use the following +form from your kernel append file:: SRC_URI_append_myplatform = " \ file://myplatform;type=kmeta;destsuffix=myplatform \ @@ -758,9 +735,8 @@ When stored outside of the recipe-space, the kernel Metadata files reside in a separate repository. The OpenEmbedded build system adds the Metadata to the build as a "type=kmeta" repository through the :term:`SRC_URI` variable. As an -example, consider the following ``SRC_URI`` statement from the -``linux-yocto_4.12.bb`` kernel recipe: -:: +example, consider the following :term:`SRC_URI` statement from the +``linux-yocto_4.12.bb`` kernel recipe:: SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \ git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" @@ -768,20 +744,20 @@ example, consider the following ``SRC_URI`` statement from the ``${KMETA}``, in this context, is simply used to name the directory into which the Git fetcher places the Metadata. This behavior is no different -than any multi-repository ``SRC_URI`` statement used in a recipe (e.g. +than any multi-repository :term:`SRC_URI` statement used in a recipe (e.g. see the previous section). You can keep kernel Metadata in a "kernel-cache", which is a directory containing configuration fragments. As with any Metadata kept outside -the recipe-space, you simply need to use the ``SRC_URI`` statement with +the recipe-space, you simply need to use the :term:`SRC_URI` statement with the "type=kmeta" attribute. Doing so makes the kernel Metadata available during the configuration phase. -If you modify the Metadata, you must not forget to update the ``SRCREV`` +If you modify the Metadata, you must not forget to update the :term:`SRCREV` statements in the kernel's recipe. In particular, you need to update the ``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you wish to use. Changing the data in these branches and not updating the -``SRCREV`` statements to match will cause the build to fetch an older +:term:`SRCREV` statements to match will cause the build to fetch an older commit. Organizing Your Source @@ -800,8 +776,8 @@ patches in every kernel you build (i.e. have the patches as part of the lone "master" branch). It is situations like these that give rise to multiple branches used within a Linux kernel sources Git repository. -Repository organization strategies exist that maximize source reuse, -remove redundancy, and logically order your changes. This section +Here are repository organization strategies maximizing source reuse, +removing redundancy, and logically ordering your changes. This section presents strategies for the following cases: - Encapsulating patches in a feature description and only including the @@ -844,14 +820,12 @@ patches into a feature. Once you have a new branch, you can set up your kernel Metadata to use the branch a couple different ways. In the recipe, you can specify the -new branch as the ``KBRANCH`` to use for the board as follows: -:: +new branch as the :term:`KBRANCH` to use for the board as follows:: KBRANCH = "mynewbranch" Another method is to use the ``branch`` command in the BSP -description: -:: +description:: mybsp.scc: define KMACHINE mybsp @@ -865,15 +839,13 @@ description: If you find yourself with numerous branches, you might consider using a hierarchical branching system similar to what the Yocto Linux Kernel Git -repositories use: -:: +repositories use:: common/kernel_type/machine If you had two kernel types, "standard" and "small" for instance, three machines, and common as ``mydir``, the branches in your Git repository -might look like this: -:: +might look like this:: mydir/base mydir/standard/base @@ -905,8 +877,7 @@ that have to be regularly updated. The Yocto Project Linux kernel tools provide for this with the ``git merge`` command. To merge a feature branch into a BSP, insert the ``git merge`` command -after any ``branch`` commands: -:: +after any ``branch`` commands:: mybsp.scc: define KMACHINE mybsp diff --git a/poky/documentation/kernel-dev/common.rst b/poky/documentation/kernel-dev/common.rst index 56217b9d3..de62df5b1 100644 --- a/poky/documentation/kernel-dev/common.rst +++ b/poky/documentation/kernel-dev/common.rst @@ -54,8 +54,7 @@ section: 1. *Initialize the BitBake Environment:* Before building an extensible SDK, you need to initialize the BitBake build environment by sourcing - the build environment script (i.e. :ref:`structure-core-script`): - :: + the build environment script (i.e. :ref:`structure-core-script`):: $ cd poky $ source oe-init-build-env @@ -71,7 +70,7 @@ section: :term:`MACHINE` variable is set to "qemux86-64", which is fine if you are building for the QEMU emulator in 64-bit mode. However, if you are not, you need to set the - ``MACHINE`` variable appropriately in your ``conf/local.conf`` file + :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file found in the :term:`Build Directory` (i.e. ``poky/build`` in this example). @@ -83,16 +82,14 @@ section: In this example we wish to build for qemux86 so we must set the ``MACHINE`` variable to "qemux86" and also add the "kernel-modules". - As described we do this by appending to ``conf/local.conf``: - :: + As described we do this by appending to ``conf/local.conf``:: MACHINE = "qemux86" MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" 3. *Create a Layer for Patches:* You need to create a layer to hold patches created for the kernel image. You can use the - ``bitbake-layers create-layer`` command as follows: - :: + ``bitbake-layers create-layer`` command as follows:: $ cd poky/build $ bitbake-layers create-layer ../../meta-mylayer @@ -116,8 +113,7 @@ section: 4. *Inform the BitBake Build Environment About Your Layer:* As directed when you created your layer, you need to add the layer to the :term:`BBLAYERS` variable in the - ``bblayers.conf`` file as follows: - :: + ``bblayers.conf`` file as follows:: $ cd poky/build $ bitbake-layers add-layer ../../meta-mylayer @@ -125,16 +121,14 @@ section: $ 5. *Build the Extensible SDK:* Use BitBake to build the extensible SDK - specifically for use with images to be run using QEMU: - :: + specifically for use with images to be run using QEMU:: $ cd poky/build $ bitbake core-image-minimal -c populate_sdk_ext Once the build finishes, you can find the SDK installer file (i.e. - ``*.sh`` file) in the following directory: - :: + ``*.sh`` file) in the following directory:: poky/build/tmp/deploy/sdk @@ -143,8 +137,7 @@ section: 6. *Install the Extensible SDK:* Use the following command to install the SDK. For this example, install the SDK in the default - ``poky_sdk`` directory: - :: + ``poky_sdk`` directory:: $ cd poky/build/tmp/deploy/sdk $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh @@ -172,8 +165,7 @@ section: BitBake shell used to build the installer. After opening a new shell, run the SDK environment setup script as - directed by the output from installing the SDK: - :: + directed by the output from installing the SDK:: $ source poky_sdk/environment-setup-i586-poky-linux "SDK environment now set up; additionally you may now run devtool to perform development tasks. @@ -186,8 +178,7 @@ section: 8. *Build the Clean Image:* The final step in preparing to work on the kernel is to build an initial image using ``devtool`` in the new - terminal you just set up and initialized for SDK work: - :: + terminal you just set up and initialized for SDK work:: $ devtool build-image Parsing recipes: 100% |##########################################| Time: 0:00:05 @@ -257,7 +248,7 @@ section: :term:`MACHINE` variable is set to "qemux86-64", which is fine if you are building for the QEMU emulator in 64-bit mode. However, if you are not, you need to set the - ``MACHINE`` variable appropriately in your ``conf/local.conf`` file + :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file found in the :term:`Build Directory` (i.e. ``poky/build`` in this example). @@ -269,16 +260,14 @@ section: In this example we wish to build for qemux86 so we must set the ``MACHINE`` variable to "qemux86" and also add the "kernel-modules". - As described we do this by appending to ``conf/local.conf``: - :: + As described we do this by appending to ``conf/local.conf``:: MACHINE = "qemux86" MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" 3. *Create a Layer for Patches:* You need to create a layer to hold patches created for the kernel image. You can use the - ``bitbake-layers create-layer`` command as follows: - :: + ``bitbake-layers create-layer`` command as follows:: $ cd poky/build $ bitbake-layers create-layer ../../meta-mylayer @@ -301,8 +290,7 @@ section: 4. *Inform the BitBake Build Environment About Your Layer:* As directed when you created your layer, you need to add the layer to the :term:`BBLAYERS` variable in the - ``bblayers.conf`` file as follows: - :: + ``bblayers.conf`` file as follows:: $ cd poky/build $ bitbake-layers add-layer ../../meta-mylayer @@ -350,8 +338,7 @@ section: the ``yocto-4.12`` branch. The following commands show how to create a local copy of the - ``yocto-kernel-cache`` and be in the ``yocto-4.12`` branch: - :: + ``yocto-kernel-cache`` and switch to the ``yocto-4.12`` branch:: $ cd ~ $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12 @@ -394,8 +381,7 @@ following section describes how to create a layer without the aid of tools. These steps assume creation of a layer named ``mylayer`` in your home directory: -1. *Create Structure*: Create the layer's structure: - :: +1. *Create Structure*: Create the layer's structure:: $ mkdir meta-mylayer $ mkdir meta-mylayer/conf @@ -409,8 +395,7 @@ home directory: 2. *Create the Layer Configuration File*: Move to the ``meta-mylayer/conf`` directory and create the ``layer.conf`` file as - follows: - :: + follows:: # We have a conf and classes directory, add to BBPATH BBPATH .= ":${LAYERDIR}" @@ -429,8 +414,7 @@ home directory: ``meta-mylayer/recipes-kernel/linux`` directory and create the kernel's append file. This example uses the ``linux-yocto-4.12`` kernel. Thus, the name of the append file is - ``linux-yocto_4.12.bbappend``: - :: + ``linux-yocto_4.12.bbappend``:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" @@ -483,17 +467,15 @@ The append file should initially extend the :term:`FILESPATH` search path by prepending the directory that contains your files to the :term:`FILESEXTRAPATHS` -variable as follows: -:: +variable as follows:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" The path ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}`` expands to "linux-yocto" in the current directory for this example. If you add any new files that modify the kernel recipe and you have -extended ``FILESPATH`` as described above, you must place the files in -your layer in the following area: -:: +extended :term:`FILESPATH` as described above, you must place the files in +your layer in the following area:: your-layer/recipes-kernel/linux/linux-yocto/ @@ -509,7 +491,7 @@ As an example, consider the following append file used by the BSPs in meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend -The following listing shows the file. Be aware that the actual commit ID +Here are the contents of this file. Be aware that the actual commit ID strings in this example listing might be different than the actual strings in the file from the ``meta-yocto-bsp`` layer upstream. :: @@ -571,7 +553,7 @@ the append file. For example, suppose you had some configuration options in a file called ``network_configs.cfg``. You can place that file inside a directory -named ``linux-yocto`` and then add a ``SRC_URI`` statement such as the +named ``linux-yocto`` and then add a :term:`SRC_URI` statement such as the following to the append file. When the OpenEmbedded build system builds the kernel, the configuration options are picked up and applied. :: @@ -581,9 +563,8 @@ the kernel, the configuration options are picked up and applied. To group related configurations into multiple files, you perform a similar procedure. Here is an example that groups separate configurations specifically for Ethernet and graphics into their own -files and adds the configurations by using a ``SRC_URI`` statement like -the following in your append file: -:: +files and adds the configurations by using a :term:`SRC_URI` statement like +the following in your append file:: SRC_URI += "file://myconfig.cfg \ file://eth.cfg \ @@ -597,7 +578,7 @@ recipe is processed. .. note:: - Other methods exist to accomplish grouping and defining configuration + There are other ways of grouping and defining configuration options. For example, if you are working with a local clone of the kernel repository, you could checkout the kernel's ``meta`` branch, make your changes, and then push the changes to the local bare clone @@ -608,8 +589,8 @@ recipe is processed. In general, however, the Yocto Project maintainers take care of moving the ``SRC_URI``-specified configuration options to the - kernel's ``meta`` branch. Not only is it easier for BSP developers to - not have to worry about putting those configurations in the branch, + kernel's ``meta`` branch. Not only is it easier for BSP developers + not to have to put those configurations in the branch, but having the maintainers do it allows them to apply 'global' knowledge about the kinds of common configuration options multiple BSPs in the tree are typically using. This allows for promotion of @@ -627,8 +608,7 @@ reference them in :term:`SRC_URI` statements. For example, you can apply a three-patch series by adding the following -lines to your linux-yocto ``.bbappend`` file in your layer: -:: +lines to your linux-yocto ``.bbappend`` file in your layer:: SRC_URI += "file://0001-first-change.patch" SRC_URI += "file://0002-second-change.patch" @@ -658,19 +638,27 @@ If you have a complete, working Linux kernel ``.config`` file you want to use for the configuration, as before, copy that file to the appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux`` directory, and rename the copied file to "defconfig". Then, add the -following lines to the linux-yocto ``.bbappend`` file in your layer: -:: +following lines to the linux-yocto ``.bbappend`` file in your layer:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI += "file://defconfig" -The ``SRC_URI`` tells the build system how to search +The :term:`SRC_URI` tells the build system how to search for the file, while the :term:`FILESEXTRAPATHS` extends the :term:`FILESPATH` variable (search directories) to include the ``${PN}`` directory you created to hold the configuration changes. +You can also use a regular ``defconfig`` file, as generated by the +:ref:`ref-tasks-savedefconfig` +task instead of a complete ``.config`` file. This only specifies the +non-default configuration values. You need to additionally set +:term:`KCONFIG_MODE` +in the linux-yocto ``.bbappend`` file in your layer:: + + KCONFIG_MODE = "alldefconfig" + .. note:: The build system applies the configurations from the ``defconfig`` @@ -685,8 +673,7 @@ Generally speaking, the preferred approach is to determine the incremental change you want to make and add that as a configuration fragment. For example, if you want to add support for a basic serial console, create a file named ``8250.cfg`` in the ``${PN}`` directory -with the following content (without indentation): -:: +with the following content (without indentation):: CONFIG_SERIAL_8250=y CONFIG_SERIAL_8250_CONSOLE=y @@ -697,9 +684,8 @@ with the following content (without indentation): CONFIG_SERIAL_CORE_CONSOLE=y Next, include this -configuration fragment and extend the ``FILESPATH`` variable in your -``.bbappend`` file: -:: +configuration fragment and extend the :term:`FILESPATH` variable in your +``.bbappend`` file:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI += "file://8250.cfg" @@ -718,8 +704,7 @@ It might be desirable to have kernel configuration fragment support through a ``defconfig`` file that is pulled from the kernel source tree for the configured machine. By default, the OpenEmbedded build system looks for ``defconfig`` files in the layer used for Metadata, which is -"out-of-tree", and then configures them using the following: -:: +"out-of-tree", and then configures them using the following:: SRC_URI += "file://defconfig" @@ -732,16 +717,14 @@ append files, you can direct the OpenEmbedded build system to use a ``defconfig`` file that is "in-tree". To specify an "in-tree" ``defconfig`` file, use the following statement -form: -:: +form:: KBUILD_DEFCONFIG_KMACHINE ?= "defconfig_file" Here is an example -that assigns the ``KBUILD_DEFCONFIG`` variable based on "raspberrypi2" +that assigns the :term:`KBUILD_DEFCONFIG` variable based on "raspberrypi2" and provides the path to the "in-tree" ``defconfig`` file to be used for -a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset: -:: +a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset:: KBUILD_DEFCONFIG_raspberrypi2 ?= "bcm2709_defconfig" @@ -751,7 +734,7 @@ Aside from modifying your kernel recipe and providing your own a kernel's ``linux-``\ `machine`\ ``.inc`` file). In other words, if the build system detects a statement that identifies an "out-of-tree" ``defconfig`` file, that statement will override your -``KBUILD_DEFCONFIG`` variable. +:term:`KBUILD_DEFCONFIG` variable. See the :term:`KBUILD_DEFCONFIG` @@ -792,15 +775,14 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" section for more information. - Use the following ``devtool`` command to check out the code: - :: + Use the following ``devtool`` command to check out the code:: $ devtool modify linux-yocto .. note:: - During the checkout operation, a bug exists that could cause - errors such as the following to appear: + During the checkout operation, there is a bug that could cause + errors such as the following: .. code-block:: none @@ -819,14 +801,12 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se noted where you can find the source files (e.g. ``poky_sdk/workspace/sources/linux-yocto``). Change to where the kernel source code is before making your edits to the - ``calibrate.c`` file: - :: + ``calibrate.c`` file:: $ cd poky_sdk/workspace/sources/linux-yocto 2. *Edit the source file*: Edit the ``init/calibrate.c`` file to have - the following changes: - :: + the following changes:: void calibrate_delay(void) { @@ -846,8 +826,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se . 3. *Build the Updated Kernel Source:* To build the updated kernel - source, use ``devtool``: - :: + source, use ``devtool``:: $ devtool build linux-yocto @@ -872,8 +851,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se using QEMU to verify your changes: 1. *Boot the image*: Boot the modified image in the QEMU emulator - using this command: - :: + using this command:: $ runqemu qemux86 @@ -891,8 +869,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se 6. *Stage and commit your changes*: Within your eSDK terminal, change your working directory to where you modified the ``calibrate.c`` file - and use these Git commands to stage and commit your changes: - :: + and use these Git commands to stage and commit your changes:: $ cd poky_sdk/workspace/sources/linux-yocto $ git status @@ -921,8 +898,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se image that includes your kernel patches. Execute the following command from your :term:`Build Directory` in the terminal - set up to run BitBake: - :: + set up to run BitBake:: $ cd poky/build $ bitbake core-image-minimal @@ -966,14 +942,12 @@ Section. 1. *Change the working directory*: You need to locate the source files in the local copy of the kernel Git repository. Change to where the kernel source code is before making your edits to the - ``calibrate.c`` file: - :: + ``calibrate.c`` file:: $ cd ~/linux-yocto-4.12/init 2. *Edit the source file*: Edit the ``calibrate.c`` file to have the - following changes: - :: + following changes:: void calibrate_delay(void) { @@ -993,8 +967,7 @@ Section. . 2. *Stage and Commit Your Changes:* Use standard Git commands to stage - and commit the changes you just made: - :: + and commit the changes you just made:: $ git add calibrate.c $ git commit -m "calibrate.c - Added some printk statements" @@ -1009,13 +982,11 @@ Section. updated kernel source files. Add :term:`SRC_URI` and :term:`SRCREV` statements similar - to the following to your ``local.conf``: - :: + to the following to your ``local.conf``:: $ cd poky/build/conf - Add the following to the ``local.conf``: - :: + Add the following to the ``local.conf``:: SRC_URI_pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \ git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" @@ -1031,16 +1002,14 @@ Section. 4. *Build the Image:* With the source modified, your changes staged and committed, and the ``local.conf`` file pointing to the kernel files, - you can now use BitBake to build the image: - :: + you can now use BitBake to build the image:: $ cd poky/build $ bitbake core-image-minimal 5. *Boot the image*: Boot the modified image in the QEMU emulator using this command. When prompted to login to the QEMU console, use "root" - with no password: - :: + with no password:: $ cd poky/build $ runqemu qemux86 @@ -1059,8 +1028,7 @@ Section. 7. *Generate the Patch File:* Once you are sure that your patch works correctly, you can generate a ``*.patch`` file in the kernel source - repository: - :: + repository:: $ cd ~/linux-yocto-4.12/init $ git format-patch -1 @@ -1073,8 +1041,7 @@ Section. ``meta-mylayer``. When the layer was created using the ``yocto-create`` script, no additional hierarchy was created to support patches. Before moving the patch file, you need to add - additional structure to your layer using the following commands: - :: + additional structure to your layer using the following commands:: $ cd ~/meta-mylayer $ mkdir recipes-kernel @@ -1083,8 +1050,7 @@ Section. Once you have created this hierarchy in your layer, you can move the patch file using the - following command: - :: + following command:: $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto @@ -1093,8 +1059,7 @@ Section. the OpenEmbedded build system to find the patch. The append file needs to be in your layer's ``recipes-kernel/linux`` directory and it must be named ``linux-yocto_4.12.bbappend`` and have the following - contents: - :: + contents:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI_append = "file://0001-calibrate.c-Added-some-printk-statements.patch" @@ -1113,8 +1078,7 @@ Section. To build ``core-image-minimal`` again and see the effects of your patch, you can essentially eliminate the temporary source files saved in ``poky/build/tmp/work/...`` and residual effects of the build by entering - the following sequence of commands: - :: + the following sequence of commands:: $ cd poky/build $ bitbake -c cleanall yocto-linux @@ -1160,8 +1124,7 @@ environment, you must do the following: - You must be sure of the state of your build's configuration in the :term:`Source Directory`. -- Your build host must have the following two packages installed: - :: +- Your build host must have the following two packages installed:: libncurses5-dev libtinfo-dev @@ -1169,8 +1132,7 @@ environment, you must do the following: The following commands initialize the BitBake environment, run the :ref:`ref-tasks-kernel_configme` task, and launch ``menuconfig``. These commands assume the Source -Directory's top-level folder is ``poky``: -:: +Directory's top-level folder is ``poky``:: $ cd poky $ source oe-init-build-env @@ -1232,8 +1194,7 @@ the ``.config`` file would be: Within the ``.config`` file, you can see the kernel settings. For example, the following entry shows that symmetric multi-processor -support is not set: -:: +support is not set:: # CONFIG_SMP is not set @@ -1274,8 +1235,7 @@ your layer's ``recipes-kernel/linux`` directory, and rename the copied file to "defconfig" (e.g. ``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then, add the following lines to the linux-yocto ``.bbappend`` file in your -layer: -:: +layer:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI += "file://defconfig" @@ -1323,8 +1283,7 @@ appear in the ``.config`` file, which is in the :term:`Build Directory`. It is simple to create a configuration fragment. One method is to use shell commands. For example, issuing the following from the shell creates a configuration fragment file named ``my_smp.cfg`` that enables -multi-processor support within the kernel: -:: +multi-processor support within the kernel:: $ echo "CONFIG_SMP=y" >> my_smp.cfg @@ -1342,18 +1301,16 @@ To create a configuration fragment using this method, follow these steps: 1. *Complete a Build Through Kernel Configuration:* Complete a build at - least through the kernel configuration task as follows: - :: + least through the kernel configuration task as follows:: $ bitbake linux-yocto -c kernel_configme -f This step ensures that you create a - ``.config`` file from a known state. Because situations exist where + ``.config`` file from a known state. Because there are situations where your build state might become unknown, it is best to run this task prior to starting ``menuconfig``. -2. *Launch menuconfig:* Run the ``menuconfig`` command: - :: +2. *Launch menuconfig:* Run the ``menuconfig`` command:: $ bitbake linux-yocto -c menuconfig @@ -1361,8 +1318,7 @@ steps: to prepare a configuration fragment. The resulting file ``fragment.cfg`` is placed in the ``${``\ :term:`WORKDIR`\ ``}`` - directory: - :: + directory:: $ bitbake linux-yocto -c diffconfig @@ -1387,18 +1343,16 @@ options in a file called ``myconfig.cfg``. If you put that file inside a directory named ``linux-yocto`` that resides in the same directory as the kernel's append file within your layer and then add the following statements to the kernel's append file, those configuration options will -be picked up and applied when the kernel is built: -:: +be picked up and applied when the kernel is built:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI += "file://myconfig.cfg" As mentioned earlier, you can group related configurations into multiple -files and name them all in the ``SRC_URI`` statement as well. For +files and name them all in the :term:`SRC_URI` statement as well. For example, you could group separate configurations specifically for Ethernet and graphics into their own files and add those by using a -``SRC_URI`` statement like the following in your append file: -:: +:term:`SRC_URI` statement like the following in your append file:: SRC_URI += "file://myconfig.cfg \ file://eth.cfg \ @@ -1409,8 +1363,7 @@ Validating Configuration You can use the :ref:`ref-tasks-kernel_configcheck` -task to provide configuration validation: -:: +task to provide configuration validation:: $ bitbake linux-yocto -c kernel_configcheck -f @@ -1537,8 +1490,7 @@ 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: - :: + ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks:: $ bitbake linux-yocto -c kernel_configme -f $ bitbake linux-yocto -c kernel_configcheck -f @@ -1572,8 +1524,7 @@ Expanding Variables Sometimes it is helpful to determine what a variable expands to during a build. You can examine the values of variables by examining the output of the ``bitbake -e`` command. The output is long and is more -easily managed in a text file, which allows for easy searches: -:: +easily managed in a text file, which allows for easy searches:: $ bitbake -e virtual/kernel > some_text_file @@ -1585,20 +1536,18 @@ Working with a "Dirty" Kernel Version String ============================================ If you build a kernel image and the version string has a "+" or a -"-dirty" at the end, uncommitted modifications exist in the kernel's +"-dirty" at the end, it means there are uncommitted modifications in the kernel's source directory. Follow these steps to clean up the version string: 1. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned Git repository (source directory) and use the following Git command - to list the files that have been changed, added, or removed: - :: + to list the files that have been changed, added, or removed:: $ git status 2. *Commit the Changes:* You should commit those changes to the kernel source tree regardless of whether or not you will save, export, or - use the changes: - :: + use the changes:: $ git add $ git commit -s -a -m "getting rid of -dirty" @@ -1633,8 +1582,7 @@ linux-yocto custom recipe (``linux-yocto-custom.bb``) that uses ``kernel.org`` sources and the Yocto Project Linux kernel tools for managing kernel Metadata. You can find this recipe in the ``poky`` Git repository of the Yocto Project :yocto_git:`Source Repository <>` -at: -:: +at:: poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb @@ -1655,8 +1603,7 @@ Here are some basic steps you can use to work with your own sources: ``defconfig`` file or configuration fragment files in your layer. When you use the ``linux-yocto-custom.bb`` recipe, you must specify a configuration. If you do not have a ``defconfig`` file, you can run - the following: - :: + the following:: $ make defconfig @@ -1668,7 +1615,7 @@ Here are some basic steps you can use to work with your own sources: Running the ``make defconfig`` command results in the default configuration for your architecture as defined by your kernel. - However, no guarantee exists that this configuration is valid for + However, there is no guarantee that this configuration is valid for your use case, or that your board will even boot. This is particularly true for non-x86 architectures. @@ -1681,11 +1628,11 @@ Here are some basic steps you can use to work with your own sources: appropriate for your project: - :term:`SRC_URI`: The - ``SRC_URI`` should specify a Git repository that uses one of the + :term:`SRC_URI` should specify a Git repository that uses one of the supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``, - and so forth). The ``SRC_URI`` variable should also specify either + and so forth). The :term:`SRC_URI` variable should also specify either a ``defconfig`` file or some configuration fragment files. The - skeleton recipe provides an example ``SRC_URI`` as a syntax + skeleton recipe provides an example :term:`SRC_URI` as a syntax reference. - :term:`LINUX_VERSION`: @@ -1703,17 +1650,16 @@ Here are some basic steps you can use to work with your own sources: indicate to the OpenEmbedded build system that the recipe has changed. - - :term:`PV`: The default ``PV`` + - :term:`PV`: The default :term:`PV` assignment is typically adequate. It combines the - ``LINUX_VERSION`` with the Source Control Manager (SCM) revision + :term:`LINUX_VERSION` with the Source Control Manager (SCM) revision as derived from the :term:`SRCPV` variable. The combined results are a string with the following - form: - :: + form:: 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 - While lengthy, the extra verbosity in ``PV`` helps ensure you are + While lengthy, the extra verbosity in :term:`PV` helps ensure you are using the exact sources from which you intend to build. - :term:`COMPATIBLE_MACHINE`: @@ -1723,8 +1669,7 @@ Here are some basic steps you can use to work with your own sources: triggers an explicit build failure. You must change it to match a list of the machines that your new recipe supports. For example, to support the ``qemux86`` and ``qemux86-64`` machines, use the - following form: - :: + following form:: COMPATIBLE_MACHINE = "qemux86|qemux86-64" @@ -1807,8 +1752,7 @@ Typically, you will need to set the following variables: Depending on the build system used by the module sources, you might need to make some adjustments. For example, a typical module ``Makefile`` -looks much like the one provided with the ``hello-mod`` template: -:: +looks much like the one provided with the ``hello-mod`` template:: obj-m := hello.o @@ -1829,7 +1773,7 @@ information to build modules. If your module ``Makefile`` uses a different variable, you might want to override the :ref:`ref-tasks-compile` step, or create a patch to the ``Makefile`` to work with the more typical -``KERNEL_SRC`` or ``KERNEL_PATH`` variables. +:term:`KERNEL_SRC` or :term:`KERNEL_PATH` variables. After you have prepared your recipe, you will likely want to include the module in your images. To do this, see the documentation for the @@ -1845,8 +1789,7 @@ them appropriately for your machine configuration file: - :term:`MACHINE_EXTRA_RRECOMMENDS` Modules are often not required for boot and can be excluded from certain -build configurations. The following allows for the most flexibility: -:: +build configurations. The following allows for the most flexibility:: MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" @@ -1895,26 +1838,22 @@ branch. $ git whatchanged origin/standard/base..origin/standard/emenlow -To see short, one line summaries of changes use the ``git log`` command: -:: +To see short, one line summaries of changes use the ``git log`` command:: $ git log --oneline origin/standard/base..origin/standard/emenlow -Use this command to see code differences for the changes: -:: +Use this command to see code differences for the changes:: $ git diff origin/standard/base..origin/standard/emenlow Use this command to see the commit log messages and the text -differences: -:: +differences:: $ git show origin/standard/base..origin/standard/emenlow Use this command to create individual patches for each change. Here is an example that creates patch files for each commit and places them -in your ``Documents`` directory: -:: +in your ``Documents`` directory:: $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow @@ -1923,15 +1862,13 @@ Showing a Particular Feature or Branch Change Tags in the Yocto Project kernel tree divide changes for significant features or branches. The ``git show`` tag command shows changes based -on a tag. Here is an example that shows ``systemtap`` changes: -:: +on a tag. Here is an example that shows ``systemtap`` changes:: $ git show systemtap You can use the ``git branch --contains`` tag command to show the branches that contain a particular feature. This command shows -the branches that contain the ``systemtap`` feature: -:: +the branches that contain the ``systemtap`` feature:: $ git branch --contains systemtap @@ -1949,23 +1886,23 @@ build stops. Kernel features are the last elements processed for configuring and patching the kernel. Therefore, adding features in this manner is a way to enforce specific features are present and enabled without needing to do a full audit of any other layer's additions to the -``SRC_URI`` statement. +:term:`SRC_URI` statement. You add a kernel feature by providing the feature as part of the -``KERNEL_FEATURES`` variable and by providing the path to the feature's +:term:`KERNEL_FEATURES` variable and by providing the path to the feature's ``.scc`` file, which is relative to the root of the kernel Metadata. The OpenEmbedded build system searches all forms of kernel Metadata on the -``SRC_URI`` statement regardless of whether the Metadata is in the +:term:`SRC_URI` statement regardless of whether the Metadata is in the "kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e. part of the kernel recipe). See the ":ref:`kernel-dev/advanced:kernel metadata location`" section for additional information. -When you specify the feature's ``.scc`` file on the ``SRC_URI`` +When you specify the feature's ``.scc`` file on the :term:`SRC_URI` statement, the OpenEmbedded build system adds the directory of that ``.scc`` file along with all its subdirectories to the kernel feature search path. Because subdirectories are searched, you can reference a -single ``.scc`` file in the ``SRC_URI`` statement to reference multiple +single ``.scc`` file in the :term:`SRC_URI` statement to reference multiple kernel features. Consider the following example that adds the "test.scc" feature to the @@ -1973,7 +1910,7 @@ build. 1. *Create the Feature File:* Create a ``.scc`` file and locate it just as you would any other patch file, ``.cfg`` file, or fetcher item you - specify in the ``SRC_URI`` statement. + specify in the :term:`SRC_URI` statement. .. note:: @@ -1986,8 +1923,7 @@ build. searched during the build as potential feature directories. Continuing with the example, suppose the "test.scc" feature you are - adding has a ``test.scc`` file in the following directory: - :: + adding has a ``test.scc`` file in the following directory:: my_recipe | @@ -2001,8 +1937,7 @@ build. a similarly named configuration fragment file ``test.cfg``. 2. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the - recipe's ``SRC_URI`` statement: - :: + recipe's :term:`SRC_URI` statement:: SRC_URI_append = " file://test.scc" @@ -2010,9 +1945,8 @@ build. appended to the existing path. 3. *Specify the Feature as a Kernel Feature:* Use the - ``KERNEL_FEATURES`` statement to specify the feature as a kernel - feature: - :: + :term:`KERNEL_FEATURES` statement to specify the feature as a kernel + feature:: KERNEL_FEATURES_append = " test.scc" diff --git a/poky/documentation/kernel-dev/concepts-appx.rst b/poky/documentation/kernel-dev/concepts-appx.rst index 4b6dbe5ef..cf2e75d85 100644 --- a/poky/documentation/kernel-dev/concepts-appx.rst +++ b/poky/documentation/kernel-dev/concepts-appx.rst @@ -213,7 +213,7 @@ BSP-specific commits. In other words, the divisions of the kernel are transparent and are not relevant to the developer on a day-to-day basis. From the developer's perspective, this path is the "master" branch in Git terms. The developer does not need to be aware of the existence of -any other branches at all. Of course, value exists in the having these +any other branches at all. Of course, it can make sense to have these branches in the tree, should a person decide to explore them. For example, a comparison between two BSPs at either the commit level or at the line-by-line code ``diff`` level is now a trivial operation. @@ -359,8 +359,7 @@ To determine whether or not a given option is "hardware" or "non-hardware", the kernel Metadata in ``yocto-kernel-cache`` contains files that classify individual or groups of options as either hardware or non-hardware. To better show this, consider a situation where the -``yocto-kernel-cache`` contains the following files: -:: +``yocto-kernel-cache`` contains the following files:: yocto-kernel-cache/features/drm-psb/hardware.cfg yocto-kernel-cache/features/kgdb/hardware.cfg @@ -380,8 +379,7 @@ or non-hardware. To better show this, consider a situation where the yocto-kernel-cache/ktypes/base/hardware.kcf yocto-kernel-cache/bsp/qemu-ppc32/hardware.kcf -The following list -provides explanations for the various files: +Here are explanations for the various files: - ``hardware.kcf``: Specifies a list of kernel Kconfig files that contain hardware options only. @@ -400,8 +398,7 @@ provides explanations for the various files: (i.e. ``hardware.kcf`` or ``non-hardware.kcf``). Here is a specific example using the -``kernel-cache/bsp/mti-malta32/hardware.cfg``: -:: +``kernel-cache/bsp/mti-malta32/hardware.cfg``:: CONFIG_SERIAL_8250 CONFIG_SERIAL_8250_CONSOLE diff --git a/poky/documentation/kernel-dev/faq.rst b/poky/documentation/kernel-dev/faq.rst index c2106f81e..f0a7af37b 100644 --- a/poky/documentation/kernel-dev/faq.rst +++ b/poky/documentation/kernel-dev/faq.rst @@ -7,7 +7,7 @@ Kernel Development FAQ Common Questions and Solutions ============================== -The following lists some solutions for common questions. +Here are some solutions for common questions. How do I use my own Linux kernel ``.config`` file? -------------------------------------------------- @@ -57,8 +57,7 @@ These other variables are useful for installing specific modules: For example, set the following in the ``qemux86.conf`` file to include the ``ab123`` kernel modules with images built for the ``qemux86`` -machine: -:: +machine:: MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123" @@ -69,10 +68,9 @@ How do I change the Linux kernel command line? ---------------------------------------------- The Linux kernel command line is -typically specified in the machine config using the ``APPEND`` variable. +typically specified in the machine config using the :term:`APPEND` variable. For example, you can add some helpful debug information doing the -following: -:: +following:: APPEND += "printk.time=y initcall_debug debug" diff --git a/poky/documentation/kernel-dev/intro.rst b/poky/documentation/kernel-dev/intro.rst index 5592f74c8..e406f6e47 100644 --- a/poky/documentation/kernel-dev/intro.rst +++ b/poky/documentation/kernel-dev/intro.rst @@ -66,9 +66,9 @@ from the continual kernel integration and testing performed during development of the Yocto Project. If, instead, you have a very specific Linux kernel source tree and are -unable to align with one of the official Yocto Linux kernel recipes, an -alternative exists by which you can use the Yocto Project Linux kernel -tools with your own kernel sources. +unable to align with one of the official Yocto Linux kernel recipes, +you have a way to use the Yocto Project Linux kernel tools with your +own kernel sources. The remainder of this manual provides instructions for completing specific Linux kernel development tasks. These instructions assume you diff --git a/poky/documentation/kernel-dev/maint-appx.rst b/poky/documentation/kernel-dev/maint-appx.rst index 44c43893e..d968c856f 100644 --- a/poky/documentation/kernel-dev/maint-appx.rst +++ b/poky/documentation/kernel-dev/maint-appx.rst @@ -28,8 +28,7 @@ in the Yocto Project Linux kernel in any clone of the Yocto Project Linux kernel source repository and ``yocto-kernel-cache`` Git trees. For example, the following commands clone the Yocto Project baseline Linux kernel that branches off ``linux.org`` version 4.12 and the -``yocto-kernel-cache``, which contains stores of kernel Metadata: -:: +``yocto-kernel-cache``, which contains stores of kernel Metadata:: $ git clone git://git.yoctoproject.org/linux-yocto-4.12 $ git clone git://git.yoctoproject.org/linux-kernel-cache @@ -42,16 +41,14 @@ section. Once you have cloned the kernel Git repository and the cache of Metadata on your local machine, you can discover the branches that are available -in the repository using the following Git command: -:: +in the repository using the following Git command:: $ git branch -a Checking out a branch allows you to work with a particular Yocto Linux kernel. For example, the following commands check out the "standard/beagleboard" branch of the Yocto Linux kernel repository and -the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository: -:: +the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository:: $ cd ~/linux-yocto-4.12 $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard @@ -107,12 +104,11 @@ patch, or BSP: repository organized under the "Yocto Linux Kernel" heading in the :yocto_git:`Yocto Project Source Repositories <>`. - - Areas pointed to by ``SRC_URI`` statements found in kernel recipes. + - Areas pointed to by :term:`SRC_URI` statements found in kernel recipes. For a typical build, the target of the search is a feature description in an ``.scc`` file whose name follows this format (e.g. - ``beaglebone-standard.scc`` and ``beaglebone-preempt-rt.scc``): - :: + ``beaglebone-standard.scc`` and ``beaglebone-preempt-rt.scc``):: bsp_root_name-kernel_type.scc @@ -179,7 +175,7 @@ Build Strategy Once you have cloned a Yocto Linux kernel repository and the cache repository (``yocto-kernel-cache``) onto your development system, you can consider the compilation phase of kernel development, which is -building a kernel image. Some prerequisites exist that are validated by +building a kernel image. Some prerequisites are validated by the build process before compilation starts: - The :term:`SRC_URI` points to the @@ -198,7 +194,7 @@ the build process before compilation starts: In the previous example, the "yocto-4.12" branch is checked out in the ``yocto-kernel-cache`` repository. -The OpenEmbedded build system makes sure these conditions exist before +The OpenEmbedded build system makes sure these conditions are satisfied before attempting compilation. Other means, however, do exist, such as bootstrapping a BSP. @@ -222,8 +218,7 @@ build process generates a build tree that is separate from your kernel's local Git source repository tree. This build tree has a name that uses the following form, where ``${MACHINE}`` is the metadata name of the machine (BSP) and "kernel_type" is one of the Yocto Project supported -kernel types (e.g. "standard"): -:: +kernel types (e.g. "standard"):: linux-${MACHINE}-kernel_type-build diff --git a/poky/documentation/ref-manual/migration.rst b/poky/documentation/migration-guides/index.rst index a01d4ee14..6304e6318 100644 --- a/poky/documentation/ref-manual/migration.rst +++ b/poky/documentation/migration-guides/index.rst @@ -1,32 +1,34 @@ .. SPDX-License-Identifier: CC-BY-SA-2.0-UK -****************************************** -Migrating to a Newer Yocto Project Release -****************************************** +========================== + Release Migration Guides +========================== -This chapter provides information you can use to migrate work to a newer -Yocto Project release. You can find the same information in the release -notes for a given release. +| + +Each document in this chapter provides information about how +to move to one release of the Yocto Project from the previous one. .. toctree:: migration-general - migration-1.3 - migration-1.4 - migration-1.5 - migration-1.6 - migration-1.7 - migration-1.8 - migration-2.0 - migration-2.1 - migration-2.2 - migration-2.3 - migration-2.4 - migration-2.5 - migration-2.6 - migration-2.7 - migration-3.0 - migration-3.1 - migration-3.2 migration-3.3 + migration-3.2 + migration-3.1 + migration-3.0 + migration-2.7 + migration-2.6 + migration-2.5 + migration-2.4 + migration-2.3 + migration-2.2 + migration-2.1 + migration-2.0 + migration-1.8 + migration-1.7 + migration-1.6 + migration-1.5 + migration-1.4 + migration-1.3 +.. include:: /boilerplate.rst diff --git a/poky/documentation/ref-manual/migration-1.3.rst b/poky/documentation/migration-guides/migration-1.3.rst index 0929f490d..afb868e7c 100644 --- a/poky/documentation/ref-manual/migration-1.3.rst +++ b/poky/documentation/migration-guides/migration-1.3.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-2.0-UK -Moving to the Yocto Project 1.3 Release (danny) -=============================================== +Release 1.3 (danny) +=================== This section provides migration information for moving to the Yocto Project 1.3 Release (codename "danny") from the prior release. @@ -29,7 +29,7 @@ location (either local or remote) and then point to it in :term:`SSTATE_MIRRORS`, you need to append "PATH" to the end of the mirror URL so that the path used by BitBake before the mirror substitution is appended to the path used to access the mirror. -Here is an example: :: +Here is an example:: SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH" @@ -125,7 +125,7 @@ Image recipes that previously included ``apps-console-core`` in :term:`IMAGE_FEATURES` should now include ``splash`` instead to enable the boot-up splash screen. Retaining ``apps-console-core`` will still include the splash screen but generates a -warning. The ``apps-x11-core`` and ``apps-x11-games`` ``IMAGE_FEATURES`` +warning. The ``apps-x11-core`` and ``apps-x11-games`` :term:`IMAGE_FEATURES` features have been removed. .. _migration-1.3-removed-recipes: @@ -181,14 +181,13 @@ Linux Kernel Naming ------------------- The naming scheme for kernel output binaries has been changed to now -include :term:`PE` as part of the filename: -:: +include :term:`PE` as part of the filename:: KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}" -Because the ``PE`` variable is not set by default, these binary files +Because the :term:`PE` variable is not set by default, these binary files could result with names that include two dash characters. Here is an -example: :: +example:: bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin diff --git a/poky/documentation/ref-manual/migration-1.4.rst b/poky/documentation/migration-guides/migration-1.4.rst index f5fac7a2a..3f980915c 100644 --- a/poky/documentation/ref-manual/migration-1.4.rst +++ b/poky/documentation/migration-guides/migration-1.4.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 1.4 Release (dylan) -=============================================== +Release 1.4 (dylan) +=================== This section provides migration information for moving to the Yocto Project 1.4 Release (codename "dylan") from the prior release. @@ -28,7 +28,7 @@ Differences include the following: and uninstall script functions ``pkg_preinst``, ``pkg_postinst``, ``pkg_prerm``, and ``pkg_postrm`` should always have a package name override. For example, use ``RDEPENDS_${PN}`` for the main package - instead of ``RDEPENDS``. BitBake uses more strict checks when it + instead of :term:`RDEPENDS`. BitBake uses more strict checks when it parses recipes. .. _migration-1.4-build-behavior: @@ -40,8 +40,7 @@ Differences include the following: - *Shared State Code:* The shared state code has been optimized to avoid running unnecessary tasks. For example, the following no longer - populates the target sysroot since that is not necessary: - :: + populates the target sysroot since that is not necessary:: $ bitbake -c rootfs some-image @@ -54,14 +53,14 @@ Differences include the following: :term:`SRC_URI`, the build system now uses :term:`FILESOVERRIDES` instead of :term:`OVERRIDES` for the directory names. In - general, the values previously in ``OVERRIDES`` are now in - ``FILESOVERRIDES`` as well. However, if you relied upon an additional - value you previously added to ``OVERRIDES``, you might now need to - add it to ``FILESOVERRIDES`` unless you are already adding it through + general, the values previously in :term:`OVERRIDES` are now in + :term:`FILESOVERRIDES` as well. However, if you relied upon an additional + value you previously added to :term:`OVERRIDES`, you might now need to + add it to :term:`FILESOVERRIDES` unless you are already adding it through the :term:`MACHINEOVERRIDES` or :term:`DISTROOVERRIDES` variables, as appropriate. For more related changes, see the - ":ref:`ref-manual/migration-1.4:variables`" section. + ":ref:`migration-guides/migration-1.4:variables`" section. .. _migration-1.4-proxies-and-fetching-source: @@ -106,7 +105,7 @@ Variables The following variables have changed: -- ``SANITY_TESTED_DISTROS``: This variable now uses a distribution +- :term:`SANITY_TESTED_DISTROS`: This variable now uses a distribution ID, which is composed of the host distributor ID followed by the release. Previously, :term:`SANITY_TESTED_DISTROS` was @@ -115,7 +114,7 @@ The following variables have changed: you are not specifically setting this variable, or if you are specifically setting it to "". -- ``SRC_URI``: The ``${``\ :term:`PN`\ ``}``, +- :term:`SRC_URI`: The ``${``\ :term:`PN`\ ``}``, ``${``\ :term:`PF`\ ``}``, ``${``\ :term:`P`\ ``}``, and ``FILE_DIRNAME`` directories have been dropped from the default value of the @@ -136,8 +135,7 @@ Target Package Management with RPM If runtime package management is enabled and the RPM backend is selected, Smart is now installed for package download, dependency resolution, and upgrades instead of Zypper. For more information on how -to use Smart, run the following command on the target: -:: +to use Smart, run the following command on the target:: smart --help diff --git a/poky/documentation/ref-manual/migration-1.5.rst b/poky/documentation/migration-guides/migration-1.5.rst index c772e51b5..e956d9fff 100644 --- a/poky/documentation/ref-manual/migration-1.5.rst +++ b/poky/documentation/migration-guides/migration-1.5.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 1.5 Release (dora) -============================================== +Release 1.5 (dora) +================== This section provides migration information for moving to the Yocto Project 1.5 Release (codename "dora") from the prior release. @@ -68,7 +68,7 @@ The following changes have been made that relate to BitBake: - ``${``\ :term:`P`\ ``}`` and ``${``\ :term:`PF`\ ``}`` are no longer added to :term:`PROVIDES` by default in ``bitbake.conf``. - These version-specific ``PROVIDES`` items were seldom used. + These version-specific :term:`PROVIDES` items were seldom used. Attempting to use them could result in two versions being built simultaneously rather than just one version due to the way BitBake resolves dependencies. @@ -84,9 +84,9 @@ The following changes have been made to the package QA checks: :term:`WARN_QA` values in your configuration, check that they contain all of the issues that you wish to be reported. Previous Yocto Project versions contained a bug that meant that any - item not mentioned in ``ERROR_QA`` or ``WARN_QA`` would be treated as + item not mentioned in :term:`ERROR_QA` or :term:`WARN_QA` would be treated as a warning. Consequently, several important items were not already in - the default value of ``WARN_QA``. All of the possible QA checks are + the default value of :term:`WARN_QA`. All of the possible QA checks are now documented in the ":ref:`insane.bbclass <ref-classes-insane>`" section. @@ -97,7 +97,7 @@ The following changes have been made to the package QA checks: - If you are using the ``buildhistory`` class, the check for the package version going backwards is now controlled using a standard QA check. - Thus, if you have customized your ``ERROR_QA`` or ``WARN_QA`` values + Thus, if you have customized your :term:`ERROR_QA` or :term:`WARN_QA` values and still wish to have this check performed, you should add "version-going-backwards" to your value for one or the other variables depending on how you wish it to be handled. See the @@ -129,7 +129,7 @@ The following directory changes exist: - When buildhistory is enabled, its output is now written under the :term:`Build Directory` rather than :term:`TMPDIR`. Doing so makes it easier to delete - ``TMPDIR`` and preserve the build history. Additionally, data for + :term:`TMPDIR` and preserve the build history. Additionally, data for produced SDKs is now split by :term:`IMAGE_NAME`. - The ``pkgdata`` directory produced as part of the packaging process @@ -157,20 +157,20 @@ major issue in the way the values are used. The following changes have been made that relate to :term:`IMAGE_FEATURES`: -- The value of ``IMAGE_FEATURES`` is now validated to ensure invalid +- The value of :term:`IMAGE_FEATURES` is now validated to ensure invalid feature items are not added. Some users mistakenly add package names to this variable instead of using :term:`IMAGE_INSTALL` in order to have the package added to the image, which does not work. This change is - intended to catch those kinds of situations. Valid ``IMAGE_FEATURES`` + intended to catch those kinds of situations. Valid :term:`IMAGE_FEATURES` are drawn from ``PACKAGE_GROUP`` definitions, :term:`COMPLEMENTARY_GLOB` and a new - "validitems" varflag on ``IMAGE_FEATURES``. The "validitems" varflag + "validitems" varflag on :term:`IMAGE_FEATURES`. The "validitems" varflag change allows additional features to be added if they are not provided using the previous two mechanisms. -- The previously deprecated "apps-console-core" ``IMAGE_FEATURES`` item - is no longer supported. Add "splash" to ``IMAGE_FEATURES`` if you +- The previously deprecated "apps-console-core" :term:`IMAGE_FEATURES` item + is no longer supported. Add "splash" to :term:`IMAGE_FEATURES` if you wish to have the splash screen enabled, since this is all that apps-console-core was doing. @@ -285,7 +285,7 @@ Following are changes to ``udev``: ``udev-extraconf`` to your image. - ``udev`` no longer brings in ``pciutils-ids`` or ``usbutils-ids`` - through ``RRECOMMENDS``. These are not needed by ``udev`` itself and + through :term:`RRECOMMENDS`. These are not needed by ``udev`` itself and removing them saves around 350KB. .. _migration-1.5-removed-renamed-recipes: diff --git a/poky/documentation/ref-manual/migration-1.6.rst b/poky/documentation/migration-guides/migration-1.6.rst index 4c6afab1f..eea3d1767 100644 --- a/poky/documentation/ref-manual/migration-1.6.rst +++ b/poky/documentation/migration-guides/migration-1.6.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 1.6 Release (daisy) -=============================================== +Release 1.6 (daisy) +=================== This section provides migration information for moving to the Yocto Project 1.6 Release (codename "daisy") from the prior release. @@ -53,8 +53,7 @@ Matching Branch Requirement for Git Fetching When fetching source from a Git repository using :term:`SRC_URI`, BitBake will now validate the :term:`SRCREV` value against the branch. You can specify -the branch using the following form: -:: +the branch using the following form:: SRC_URI = "git://server.name/repository;branch=branchname" @@ -62,7 +61,7 @@ If you do not specify a branch, BitBake looks in the default "master" branch. Alternatively, if you need to bypass this check (e.g. if you are fetching a revision corresponding to a tag that is not on any branch), -you can add ";nobranch=1" to the end of the URL within ``SRC_URI``. +you can add ";nobranch=1" to the end of the URL within :term:`SRC_URI`. .. _migration-1.6-bitbake-deps: @@ -135,9 +134,9 @@ OpenEmbedded build system variables, see the ":doc:`/ref-manual/variables`" Chap :term:`TMPDIR` can no longer be on an NFS mount. NFS does not offer full POSIX locking and inode consistency and can cause -unexpected issues if used to store ``TMPDIR``. +unexpected issues if used to store :term:`TMPDIR`. -The check for this occurs on startup. If ``TMPDIR`` is detected on an +The check for this occurs on startup. If :term:`TMPDIR` is detected on an NFS mount, an error occurs. .. _migration-1.6-variable-changes-PRINC: @@ -207,7 +206,7 @@ functions to call and not arbitrary shell commands: For migration purposes, you can simply wrap shell commands in a shell -function and then call the function. Here is an example: :: +function and then call the function. Here is an example:: my_postprocess_function() { echo "hello" > ${IMAGE_ROOTFS}/hello.txt @@ -248,8 +247,7 @@ the ``autotools`` or ``autotools_stage``\ classes. ``qemu-native`` now builds without SDL-based graphical output support by default. The following additional lines are needed in your -``local.conf`` to enable it: -:: +``local.conf`` to enable it:: PACKAGECONFIG_pn-qemu-native = "sdl" ASSUME_PROVIDED += "libsdl-native" @@ -276,7 +274,7 @@ In addition to ``core-image-basic`` being renamed, Licensing --------- -The top-level ``LICENSE`` file has been changed to better describe the +The top-level :term:`LICENSE` file has been changed to better describe the license of the various components of :term:`OpenEmbedded-Core (OE-Core)`. However, the licensing itself remains unchanged. @@ -286,7 +284,7 @@ recipes point to this file within ``${COREBASE}/LICENSE``) and thus the accompanying checksum must be changed from 3f40d7994397109285ec7b81fdeb3b58 to 4d92cd373abda3937c2bc47fbc49d690. A better alternative is to have -``LIC_FILES_CHKSUM`` point to a file describing the license that is +:term:`LIC_FILES_CHKSUM` point to a file describing the license that is distributed with the source that the recipe is building, if possible, rather than pointing to ``${COREBASE}/LICENSE``. @@ -299,7 +297,7 @@ The "-fpermissive" option has been removed from the default :term:`CFLAGS` value. You need to take action on individual recipes that fail when building with this option. You need to either patch the recipes to fix the issues reported by the compiler, or -you need to add "-fpermissive" to ``CFLAGS`` in the recipes. +you need to add "-fpermissive" to :term:`CFLAGS` in the recipes. .. _migration-1.6-custom-images: diff --git a/poky/documentation/ref-manual/migration-1.7.rst b/poky/documentation/migration-guides/migration-1.7.rst index 9cf467f28..c3a50eec8 100644 --- a/poky/documentation/ref-manual/migration-1.7.rst +++ b/poky/documentation/migration-guides/migration-1.7.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 1.7 Release (dizzy) -=============================================== +Release 1.7 (dizzy) +=================== This section provides migration information for moving to the Yocto Project 1.7 Release (codename "dizzy") from the prior release. @@ -15,8 +15,7 @@ optional features. The method used to set defaults for these options means that existing ``local.conf`` files will need to be modified to append to ``PACKAGECONFIG`` for ``qemu-native`` and ``nativesdk-qemu`` instead of setting it. In other words, to enable graphical output for -QEMU, you should now have these lines in ``local.conf``: -:: +QEMU, you should now have these lines in ``local.conf``:: PACKAGECONFIG_append_pn-qemu-native = " sdl" PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl" @@ -80,8 +79,7 @@ disable the scripts due to the scripts previously requiring error-prone path substitution. Software that links against these libraries using these scripts should use the much more robust ``pkg-config`` instead. The list of recipes changed in this version (and their configuration -scripts) is as follows: -:: +scripts) is as follows:: directfb (directfb-config) freetype (freetype-config) @@ -142,9 +140,9 @@ part of the variable name. This change not only simplifies usage but also allows the values of these variables to be appropriately incorporated into task signatures and thus trigger the appropriate tasks to re-execute when changed. You should replace any references to -``module_autoload_*`` with ``KERNEL_MODULE_AUTOLOAD``, and add any +``module_autoload_*`` with :term:`KERNEL_MODULE_AUTOLOAD`, and add any modules for which ``module_conf_*`` is specified to -``KERNEL_MODULE_PROBECONF``. +:term:`KERNEL_MODULE_PROBECONF`. .. _migration-1.7-qa-check-changes: diff --git a/poky/documentation/ref-manual/migration-1.8.rst b/poky/documentation/migration-guides/migration-1.8.rst index ec2b13879..51a13873e 100644 --- a/poky/documentation/ref-manual/migration-1.8.rst +++ b/poky/documentation/migration-guides/migration-1.8.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 1.8 Release (fido) -============================================== +Release 1.8 (fido) +================== This section provides migration information for moving to the Yocto Project 1.8 Release (codename "fido") from the prior release. @@ -56,7 +56,7 @@ you can now remove them. Additionally, a ``bluetooth`` class has been added to make selection of the appropriate bluetooth support within a recipe a little easier. If you wish to make use of this class in a recipe, add something such as -the following: :: +the following:: inherit bluetooth PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}" @@ -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: :: +``do_shared_workdir`` kernel task, for example:: do_configure[depends] += "virtual/kernel:do_shared_workdir" @@ -131,7 +131,7 @@ One of the improvements is to attempt to run "make clean" during the ``do_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: :: +:term:`CLEANBROKEN` to "1" within the recipe, for example:: CLEANBROKEN = "1" @@ -153,8 +153,8 @@ The following QA Check and Validation Changes have occurred: instead of ``${D}``. - :term:`S` now needs to be set to a valid value within a - recipe. If ``S`` is not set in the recipe, the directory is not - automatically created. If ``S`` does not point to a directory that + recipe. If :term:`S` is not set in the recipe, the directory is not + automatically created. If :term:`S` does not point to a directory that exists at the time the :ref:`ref-tasks-unpack` task finishes, a warning will be shown. diff --git a/poky/documentation/ref-manual/migration-2.0.rst b/poky/documentation/migration-guides/migration-2.0.rst index 9da60dfdc..721785377 100644 --- a/poky/documentation/ref-manual/migration-2.0.rst +++ b/poky/documentation/migration-guides/migration-2.0.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 2.0 Release (jethro) -================================================ +Release 2.0 (jethro) +==================== This section provides migration information for moving to the Yocto Project 2.0 Release (codename "jethro") from the prior release. @@ -25,8 +25,7 @@ and the porting guide at https://gcc.gnu.org/gcc-5/porting_to.html. Alternatively, you can switch back to GCC 4.9 or 4.8 by setting -``GCCVERSION`` in your configuration, as follows: -:: +:term:`GCCVERSION` in your configuration, as follows:: GCCVERSION = "4.9%" @@ -91,8 +90,7 @@ unlikely to require any changes to Metadata. However, these minor changes in behavior exist: - All potential overrides are now visible in the variable history as - seen when you run the following: - :: + seen when you run the following:: $ bitbake -e @@ -200,8 +198,7 @@ changes. Additionally, work directories for old versions of recipes are now pruned. If you wish to disable pruning old work directories, you can set -the following variable in your configuration: -:: +the following variable in your configuration:: SSTATE_PRUNE_OBSOLETEWORKDIR = "0" @@ -247,7 +244,7 @@ The following QA checks have been added: - Added an "invalid-packageconfig" check for any options specified in :term:`PACKAGECONFIG` that do not match any - ``PACKAGECONFIG`` option defined for the recipe. + :term:`PACKAGECONFIG` option defined for the recipe. .. _migration-2.0-miscellaneous: diff --git a/poky/documentation/ref-manual/migration-2.1.rst b/poky/documentation/migration-guides/migration-2.1.rst index 1eb9ab552..6c5ed965d 100644 --- a/poky/documentation/ref-manual/migration-2.1.rst +++ b/poky/documentation/migration-guides/migration-2.1.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 2.1 Release (krogoth) -================================================= +Release 2.1 (krogoth) +===================== This section provides migration information for moving to the Yocto Project 2.1 Release (codename "krogoth") from the prior release. @@ -28,8 +28,8 @@ characters. This practice is now a requirement as BitBake's datastore now assumes lower-case characters in order to give a slight performance boost during parsing. In practical terms, this requirement means that anything that ends up in :term:`OVERRIDES` must now -appear in lower-case characters (e.g. values for ``MACHINE``, -``TARGET_ARCH``, ``DISTRO``, and also recipe names if +appear in lower-case characters (e.g. values for :term:`MACHINE`, +:term:`TARGET_ARCH`, :term:`DISTRO`, and also recipe names if ``_pn-``\ recipename overrides are to be effective). .. _migration-2.1-expand-parameter-to-getvar-and-getvarflag-now-mandatory: @@ -42,8 +42,7 @@ defaulted to False if not specified. Now, however, no default exists so one must be specified. You must change any ``getVar()`` calls that do not specify the final expand parameter to calls that do specify the parameter. You can run the following ``sed`` command at the base of a -layer to make this change: -:: +layer to make this change:: sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *` sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *` @@ -69,7 +68,7 @@ was a historical accident that has required many classes (e.g. to work with sensible build systems. When upgrading to the release, you must edit any recipe that relies upon this old default by either setting ``EXTRA_OEMAKE`` back to "-e MAKEFLAGS=" or by explicitly setting any -required variable value overrides using ``EXTRA_OEMAKE``, which is +required variable value overrides using :term:`EXTRA_OEMAKE`, which is typically only needed when a Makefile sets a default value for a variable that is inappropriate for cross-compilation using the "=" operator rather than the "?=" operator. @@ -180,7 +179,7 @@ The following recipes have been removed in the 2.1 release: - ``python-pygtk``: Recipe became obsolete. - ``adt-installer``: Recipe became obsolete. See the - ":ref:`ref-manual/migration-2.1:adt removed`" section for more information. + ":ref:`migration-guides/migration-2.1:adt removed`" section for more information. .. _migration-2.1-class-changes: @@ -285,8 +284,7 @@ The following changes have been made for the Poky distribution: Any recipe that needs to opt-out of having the "--disable-static" option specified on the configure command line either because it is not a supported option for the configure script or because static - libraries are needed should set the following variable: - :: + libraries are needed should set the following variable:: DISABLE_STATIC = "" @@ -369,8 +367,7 @@ These additional changes exist: - Previously, the following list of packages were removed if package-management was not in :term:`IMAGE_FEATURES`, regardless of any - dependencies: - :: + dependencies:: update-rc.d base-passwd @@ -379,7 +376,7 @@ These additional changes exist: run-postinsts With the Yocto Project 2.1 release, these packages are - only removed if "read-only-rootfs" is in ``IMAGE_FEATURES``, since + only removed if "read-only-rootfs" is in :term:`IMAGE_FEATURES`, since they might still be needed for a read-write image even in the absence of a package manager (e.g. if users need to be added, modified, or removed at runtime). diff --git a/poky/documentation/ref-manual/migration-2.2.rst b/poky/documentation/migration-guides/migration-2.2.rst index 198181a46..d6dacdf34 100644 --- a/poky/documentation/ref-manual/migration-2.2.rst +++ b/poky/documentation/migration-guides/migration-2.2.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 2.2 Release (morty) -=============================================== +Release 2.2 (morty) +=================== This section provides migration information for moving to the Yocto Project 2.2 Release (codename "morty") from the prior release. @@ -144,8 +144,7 @@ The new ``runqemu`` is a Python script. Machine knowledge is no longer hardcoded into ``runqemu``. You can choose to use the ``qemuboot`` configuration file to define the BSP's own arguments and to make it bootable with ``runqemu``. If you use a configuration file, use the -following form: -:: +following form:: image-name-machine.qemuboot.conf @@ -160,8 +159,7 @@ rootfs). QEMU boot arguments can be set in BSP's configuration file and the ``qemuboot`` class will save them to ``qemuboot.conf``. If you want to use ``runqemu`` without a configuration file, use the -following command form: -:: +following command form:: $ runqemu machine rootfs kernel [options] @@ -179,7 +177,7 @@ Supported machines are as follows: Consider the following example, which uses the ``qemux86-64`` machine, provides a -root filesystem, provides an image, and uses the ``nographic`` option: :: +root filesystem, provides an image, and uses the ``nographic`` option:: $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic @@ -241,11 +239,10 @@ to catch recipes that are building software without using the OpenEmbedded :term:`LDFLAGS`. This change could result in seeing some "No GNU_HASH in the elf binary" QA issues when building such recipes. You need to fix these recipes so that they use the expected -``LDFLAGS``. Depending on how the software is built, the build system +:term:`LDFLAGS`. Depending on how the software is built, the build system used by the software (e.g. a Makefile) might need to be patched. However, sometimes making this fix is as simple as adding the following -to the recipe: -:: +to the recipe:: TARGET_CC_ARCH += "${LDFLAGS}" @@ -258,8 +255,7 @@ The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the :term:`KERNEL_IMAGETYPE` variable to create the image's base name. Because the OpenEmbedded build system can now build multiple kernel image types, this part of the kernel image base name as -been removed leaving only the following: -:: +been removed leaving only the following:: KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}" @@ -267,6 +263,17 @@ If you have recipes or classes that use ``KERNEL_IMAGE_BASE_NAME`` directly, you might need to update the references to ensure they continue to work. +.. _migration-2.2-imgdeploydir-replaces-deploy-dir-image-for-most-use-cases: + +``IMGDEPLOYDIR`` Replaces ``DEPLOY_DIR_IMAGE`` for Most Use Cases +----------------------------------------------------------------- + +The :term:`IMGDEPLOYDIR` variable was introduced to allow sstate caching of +image creation results. Image recipes defining custom :term:`IMAGE_CMD` or +doing postprocessing on the generated images need to be adapted to use +``IMGDEPLOYDIR`` instead of :term:`DEPLOY_DIR_IMAGE`. ``IMAGE_MANIFEST`` +creation and symlinking of the most recent image file will fail otherwise. + .. _migration-2.2-bitbake-changes: BitBake Changes @@ -284,7 +291,7 @@ The following changes took place for BitBake: :term:`SRC_URI` parameters to specify these. This change is more in-line with how the other fetchers work for source control systems. Recipes that fetch from Perforce will need to be - updated to use ``SRCREV`` in place of specifying the source revision + updated to use :term:`SRCREV` in place of specifying the source revision within ``SRC_URI``. - Some of BitBake's internal code structures for accessing the recipe @@ -368,7 +375,7 @@ The following recipes have been removed: - ``sato-icon-theme``: Became obsolete. - ``swabber-native``: Swabber has been removed. See the :ref:`entry on - Swabber <ref-manual/migration-2.2:swabber has been removed>`. + Swabber <migration-guides/migration-2.2:swabber has been removed>`. - ``tslib``: No longer needed and has been moved to ``meta-oe``. @@ -394,7 +401,7 @@ The following classes have been removed: - ``sip``: Mostly unused. - ``swabber``: See the :ref:`entry on - Swabber <ref-manual/migration-2.2:swabber has been removed>`. + Swabber <migration-guides/migration-2.2:swabber has been removed>`. .. _migration-2.2-minor-packaging-changes: @@ -426,7 +433,7 @@ The following miscellaneous changes have occurred: :term:`SRCREV` by default when fetching from a Git repository. You can override this in either case to use ``${``\ :term:`AUTOREV`\ ``}`` instead by using the - ``-a`` or ``DASHDASHautorev`` command-line option + ``-a`` or ``--autorev`` command-line option - ``distcc``: GTK+ UI is now disabled by default. diff --git a/poky/documentation/ref-manual/migration-2.3.rst b/poky/documentation/migration-guides/migration-2.3.rst index 0541eb3e7..886d579f9 100644 --- a/poky/documentation/ref-manual/migration-2.3.rst +++ b/poky/documentation/migration-guides/migration-2.3.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 2.3 Release (pyro) -============================================== +Release 2.3 (pyro) +================== This section provides migration information for moving to the Yocto Project 2.3 Release (codename "pyro") from the prior release. @@ -35,7 +35,7 @@ Consider the following: As an example, see the ``dbus`` recipe. You will see that this recipe has a ``pkg_postinst`` that calls ``systemctl`` if "systemd" is in :term:`DISTRO_FEATURES`. In the example, - ``systemd-systemctl-native`` is added to ``PACKAGE_WRITE_DEPS``, + ``systemd-systemctl-native`` is added to :term:`PACKAGE_WRITE_DEPS`, which is also conditional on "systemd" being in ``DISTRO_FEATURES``. - Examine Recipes that Use ``SSTATEPOSTINSTFUNCS``: You need to @@ -114,8 +114,7 @@ Changes to Scripts The following changes to scripts took place: - ``oe-find-native-sysroot``: The usage for the - ``oe-find-native-sysroot`` script has changed to the following: - :: + ``oe-find-native-sysroot`` script has changed to the following:: $ . oe-find-native-sysroot recipe @@ -124,8 +123,7 @@ The following changes to scripts took place: was not necessary to provide the script with the command. - ``oe-run-native``: The usage for the ``oe-run-native`` script has - changed to the following: - :: + changed to the following:: $ oe-run-native native_recipe tool @@ -138,7 +136,7 @@ The following changes to scripts took place: removed because the script was found to be deleting files it should not have, which lead to broken build trees. Rather than trying to delete portions of :term:`TMPDIR` and getting it wrong, - it is recommended that you delete ``TMPDIR`` and have it restored + it is recommended that you delete :term:`TMPDIR` and have it restored from shared state (sstate) on subsequent builds. - ``wipe-sysroot``: The ``wipe-sysroot`` script has been removed as @@ -428,10 +426,10 @@ The following miscellaneous changes have occurred: - If the :term:`DISTRO_VERSION` value contains the value of the :term:`DATE` variable, which is the - default between Poky releases, the ``DATE`` value is explicitly + default between Poky releases, the :term:`DATE` value is explicitly excluded from ``/etc/issue`` and ``/etc/issue.net``, which is displayed at the login prompt, in order to avoid conflicts with - Multilib enabled. Regardless, the ``DATE`` value is inaccurate if the + Multilib enabled. Regardless, the :term:`DATE` value is inaccurate if the ``base-files`` recipe is restored from shared state (sstate) rather than rebuilt. @@ -453,14 +451,11 @@ The following miscellaneous changes have occurred: tools. - The ``USE_LDCONFIG`` variable has been replaced with the "ldconfig" - ``DISTRO_FEATURES`` feature. Distributions that previously set: - :: + :term:`DISTRO_FEATURES` feature. Distributions that previously set:: USE_LDCONFIG = "0" - should now instead use the following: - - :: + should now instead use the following:: DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig" @@ -478,8 +473,7 @@ The following miscellaneous changes have occurred: order to allow module packages from multiple kernel versions to co-exist on a target system. If you wish to return to the previous naming scheme that does not include the version suffix, use the - following: - :: + following:: KERNEL_MODULE_PACKAGE_SUFFIX = "" @@ -500,12 +494,12 @@ The following miscellaneous changes have occurred: information. - All native and nativesdk recipes now use a separate - ``DISTRO_FEATURES`` value instead of sharing the value used by + :term:`DISTRO_FEATURES` value instead of sharing the value used by recipes for the target, in order to avoid unnecessary rebuilds. - The ``DISTRO_FEATURES`` for ``native`` recipes is + The :term:`DISTRO_FEATURES` for ``native`` recipes is :term:`DISTRO_FEATURES_NATIVE` added to - an intersection of ``DISTRO_FEATURES`` and + an intersection of :term:`DISTRO_FEATURES` and :term:`DISTRO_FEATURES_FILTER_NATIVE`. For nativesdk recipes, the corresponding variables are diff --git a/poky/documentation/ref-manual/migration-2.4.rst b/poky/documentation/migration-guides/migration-2.4.rst index 2ba17e0ed..07f2bef62 100644 --- a/poky/documentation/ref-manual/migration-2.4.rst +++ b/poky/documentation/migration-guides/migration-2.4.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 2.4 Release (rocko) -=============================================== +Release 2.4 (rocko) +=================== This section provides migration information for moving to the Yocto Project 2.4 Release (codename "rocko") from the prior release. @@ -63,7 +63,7 @@ occurred: - The ``ionice`` program is now packaged in a separate "util-linux-ionice" package. The main ``util-linux`` package has a - recommended runtime dependency (i.e. ``RRECOMMENDS``) on the + recommended runtime dependency (i.e. :term:`RRECOMMENDS`) on the ``util-linux-ionice`` package. - ``initscripts``: The ``sushell`` program is now packaged in a @@ -71,7 +71,7 @@ occurred: systems to pull ``sushell`` in when ``selinux`` is enabled. The change also eliminates needing to pull in the entire ``initscripts`` package. The main ``initscripts`` package has a runtime dependency - (i.e. ``RDEPENDS``) on the ``sushell`` package when "selinux" is in + (i.e. :term:`RDEPENDS`) on the ``sushell`` package when "selinux" is in ``DISTRO_FEATURES``. - ``glib-2.0``: The ``glib-2.0`` package now has a recommended diff --git a/poky/documentation/ref-manual/migration-2.5.rst b/poky/documentation/migration-guides/migration-2.5.rst index 9ef4b5539..d14580df2 100644 --- a/poky/documentation/ref-manual/migration-2.5.rst +++ b/poky/documentation/migration-guides/migration-2.5.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 2.5 Release (sumo) -============================================== +Release 2.5 (sumo) +================== This section provides migration information for moving to the Yocto Project 2.5 Release (codename "sumo") from the prior release. @@ -138,13 +138,11 @@ The following are BitBake changes: tree" tasks have been removed (e.g. ``fetchall``, ``checkuriall``, and the ``*all`` tasks provided by the ``distrodata`` and ``archiver`` classes). There is a BitBake option to complete this for - any arbitrary task. For example: - :: + any arbitrary task. For example:: bitbake <target> -c fetchall - should now be replaced with: - :: + should now be replaced with:: bitbake <target> --runall=fetch @@ -169,7 +167,7 @@ one of the packages provided by the Python recipe. You can no longer run ``bitbake python-foo`` or have a :term:`DEPENDS` on ``python-foo``, but doing either of the following causes the package to work as -expected: :: +expected:: IMAGE_INSTALL_append = " python-foo" @@ -283,7 +281,7 @@ The following are additional changes: ``IMAGE_FSTYPES``. - Recipes with an unconditional dependency on ``libpam`` are only - buildable with ``pam`` in ``DISTRO_FEATURES``. If the dependency is + buildable with ``pam`` in :term:`DISTRO_FEATURES`. If the dependency is truly optional then it is recommended that the dependency be conditional upon ``pam`` being in ``DISTRO_FEATURES``. diff --git a/poky/documentation/ref-manual/migration-2.6.rst b/poky/documentation/migration-guides/migration-2.6.rst index aeac50980..3216ed5ae 100644 --- a/poky/documentation/ref-manual/migration-2.6.rst +++ b/poky/documentation/migration-guides/migration-2.6.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 2.6 Release (thud) -============================================== +Release 2.6 (thud) +================== This section provides migration information for moving to the Yocto Project 2.6 Release (codename "thud") from the prior release. @@ -110,7 +110,7 @@ upon the older ``*proto`` recipes need to be changed to depend on the newer ``xorgproto`` recipe instead. For names of recipes removed because of this repository change, see the -:ref:`ref-manual/migration-2.6:removed recipes` section. +:ref:`migration-guides/migration-2.6:removed recipes` section. .. _migration-2.6-distutils-distutils3-fetching-dependencies: @@ -156,18 +156,16 @@ Image/Kernel Artifact Naming Changes The following changes have been made: - Name variables (e.g. :term:`IMAGE_NAME`) use a new - ``IMAGE_VERSION_SUFFIX`` variable instead of - :term:`DATETIME`. Using ``IMAGE_VERSION_SUFFIX`` + :term:`IMAGE_VERSION_SUFFIX` variable instead of + :term:`DATETIME`. Using :term:`IMAGE_VERSION_SUFFIX` allows easier and more direct changes. - The ``IMAGE_VERSION_SUFFIX`` variable is set in the ``bitbake.conf`` - configuration file as follows: - :: + The :term:`IMAGE_VERSION_SUFFIX` variable is set in the ``bitbake.conf`` + configuration file as follows:: IMAGE_VERSION_SUFFIX = "-${DATETIME}" -- Several variables have changed names for consistency: - :: +- Several variables have changed names for consistency:: Old Variable Name New Variable Name ======================================================== @@ -214,19 +212,19 @@ The following changes have been made: The :term:`SERIAL_CONSOLE` variable has been functionally replaced by the :term:`SERIAL_CONSOLES` variable for some time. -With the Yocto Project 2.6 release, ``SERIAL_CONSOLE`` has been +With the Yocto Project 2.6 release, :term:`SERIAL_CONSOLE` has been officially deprecated. -``SERIAL_CONSOLE`` will continue to work as before for the 2.6 release. +:term:`SERIAL_CONSOLE` will continue to work as before for the 2.6 release. However, for the sake of future compatibility, it is recommended that -you replace all instances of ``SERIAL_CONSOLE`` with -``SERIAL_CONSOLES``. +you replace all instances of :term:`SERIAL_CONSOLE` with +:term:`SERIAL_CONSOLES`. .. note:: - The only difference in usage is that ``SERIAL_CONSOLES`` + The only difference in usage is that :term:`SERIAL_CONSOLES` expects entries to be separated using semicolons as compared to - ``SERIAL_CONSOLE``, which expects spaces. + :term:`SERIAL_CONSOLE`, which expects spaces. .. _migration-2.6-poky-sets-unknown-configure-option-to-qa-error: @@ -292,8 +290,7 @@ avoids the ``systemd`` recipe from becoming machine-specific for cases where machine-specific configurations need to be applied (e.g. for ``qemu*`` machines). -Currently, the new recipe packages the following files: -:: +Currently, the new recipe packages the following files:: ${sysconfdir}/machine-id ${sysconfdir}/systemd/coredump.conf @@ -390,15 +387,14 @@ QEMU (i.e. "qemu-usermode" is in default). If you wish to disable Python profile-guided optimization regardless of -the value of ``MACHINE_FEATURES``, then ensure that +the value of :term:`MACHINE_FEATURES`, then ensure that :term:`PACKAGECONFIG` for the ``python3`` recipe does not contain "pgo". You could accomplish the latter using the -following at the configuration level: -:: +following at the configuration level:: PACKAGECONFIG_remove_pn-python3 = "pgo" -Alternatively, you can set ``PACKAGECONFIG`` using an append file +Alternatively, you can set :term:`PACKAGECONFIG` using an append file for the ``python3`` recipe. .. _migration-2.6-miscellaneous-changes: @@ -411,8 +407,7 @@ The following miscellaneous changes occurred: - Default to using the Thumb-2 instruction set for armv7a and above. If you have any custom recipes that build software that needs to be built with the ARM instruction set, change the recipe to set the - instruction set as follows: - :: + instruction set as follows:: ARM_INSTRUCTION_SET = "arm" diff --git a/poky/documentation/ref-manual/migration-2.7.rst b/poky/documentation/migration-guides/migration-2.7.rst index 1be4d5d5b..25d92296c 100644 --- a/poky/documentation/ref-manual/migration-2.7.rst +++ b/poky/documentation/migration-guides/migration-2.7.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 2.7 Release (warrior) -================================================= +Release 2.7 (warrior) +===================== This section provides migration information for moving to the Yocto Project 2.7 Release (codename "warrior") from the prior release. @@ -91,7 +91,7 @@ This section provides information about packaging changes. package_name\ ``-src``). If you are currently using ``dbg-pkgs`` in :term:`IMAGE_FEATURES` to bring in debug symbols and you still need the sources, you must now also add - ``src-pkgs`` to ``IMAGE_FEATURES``. Source packages remain in the + ``src-pkgs`` to :term:`IMAGE_FEATURES`. Source packages remain in the target portion of the SDK by default, unless you have set your own value for :term:`SDKIMAGE_FEATURES` that does not include ``src-pkgs``. diff --git a/poky/documentation/ref-manual/migration-3.0.rst b/poky/documentation/migration-guides/migration-3.0.rst index f3d20e2ed..163c6201c 100644 --- a/poky/documentation/ref-manual/migration-3.0.rst +++ b/poky/documentation/migration-guides/migration-3.0.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 3.0 Release (zeus) -============================================== +Release 3.0 (zeus) +================== This section provides migration information for moving to the Yocto Project 3.0 Release (codename "zeus") from the prior release. @@ -184,10 +184,9 @@ The following BitBake changes have occurred. exceptions. Remove this argument in any calls to ``bb.build.exec_func()`` in custom classes or scripts. -- The - :term:`bitbake:BB_SETSCENE_VERIFY_FUNCTION2` - is no longer used. In the unlikely event that you have any references - to it, they should be removed. +- The ``BB_SETSCENE_VERIFY_FUNCTION2`` variable is no longer used. In + the unlikely event that you have any references to it, they should be + removed. - The ``RunQueueExecuteScenequeue`` and ``RunQueueExecuteTasks`` events have been removed since setscene tasks are now executed as part of diff --git a/poky/documentation/ref-manual/migration-3.1.rst b/poky/documentation/migration-guides/migration-3.1.rst index 84d32502e..80b8f6baa 100644 --- a/poky/documentation/ref-manual/migration-3.1.rst +++ b/poky/documentation/migration-guides/migration-3.1.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 3.1 Release (dunfell) -================================================= +Release 3.1 (dunfell) +===================== This section provides migration information for moving to the Yocto Project 3.1 Release (codename "dunfell") from the prior release. @@ -71,8 +71,7 @@ when building a simple image such as core-image-minimal. If you do not need runtime tests enabled for core components, then it is recommended that you remove "ptest" from :term:`DISTRO_FEATURES` to save a significant -amount of build time e.g. by adding the following in your configuration: -:: +amount of build time e.g. by adding the following in your configuration:: DISTRO_FEATURES_remove = "ptest" @@ -179,12 +178,12 @@ parameter instead of the earlier ``name`` which overlapped with the generic ``name`` parameter. All recipes using the npm fetcher will need to be changed as a result. -An example of the new scheme: :: +An example of the new scheme:: SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \ npmsw://${THISDIR}/npm-shrinkwrap.json" -Another example where the sources are fetched from git rather than an npm repository: :: +Another example where the sources are fetched from git rather than an npm repository:: SRC_URI = "git://github.com/foo/bar.git;protocol=https \ npmsw://${THISDIR}/npm-shrinkwrap.json" @@ -261,7 +260,7 @@ Miscellaneous changes --------------------- - The undocumented ``SRC_DISTRIBUTE_LICENSES`` variable has now been - removed in favour of a new ``AVAILABLE_LICENSES`` variable which is + removed in favour of a new :term:`AVAILABLE_LICENSES` variable which is dynamically set based upon license files found in ``${COMMON_LICENSE_DIR}`` and ``${LICENSE_PATH}``. diff --git a/poky/documentation/ref-manual/migration-3.2.rst b/poky/documentation/migration-guides/migration-3.2.rst index 39743af70..a940f2323 100644 --- a/poky/documentation/ref-manual/migration-3.2.rst +++ b/poky/documentation/migration-guides/migration-3.2.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 3.2 Release (gatesgarth) -==================================================== +Release 3.2 (gatesgarth) +======================== This section provides migration information for moving to the Yocto Project 3.2 Release (codename "gatesgarth") from the prior release. @@ -62,10 +62,10 @@ 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, there were errors trying to ``chown root`` for files in this location. Another -example was the ``tcl`` recipe where the source directory ``S`` is set to a +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 structure above that subdirectory. For these types of cases in your own recipes, -extend ``PSEUDO_IGNORE_PATHS`` to cover additional paths that pseudo should not +extend :term:`PSEUDO_IGNORE_PATHS` to cover additional paths that pseudo should not be monitoring. In addition, pseudo's behaviour on mismatches has now been changed - rather @@ -90,12 +90,12 @@ If you have anonymous python or in-line python conditionally adding dependencies in your custom recipes, and you intend for those recipes to work with multilib, then you will need to ensure that ``${MLPREFIX}`` is prefixed on the package names in the dependencies, for example -(from the ``glibc`` recipe): :: +(from the ``glibc`` recipe):: RRECOMMENDS_${PN} = "${@bb.utils.contains('DISTRO_FEATURES', 'ldconfig', '${MLPREFIX}ldconfig', '', d)}" This also applies when conditionally adding packages to :term:`PACKAGES` where -those packages have dependencies, for example (from the ``alsa-plugins`` recipe): :: +those packages have dependencies, for example (from the ``alsa-plugins`` recipe):: PACKAGES += "${@bb.utils.contains('PACKAGECONFIG', 'pulseaudio', 'alsa-plugins-pulseaudio-conf', '', d)}" ... @@ -207,7 +207,7 @@ 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 ``DEPLOYDIR`` being accidentally contaminated by files from previous runs, possibly even with different config, in case of incremental builds. +``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. Most recipes and classes that inherit the ``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. @@ -229,7 +229,7 @@ needs ``/etc/ld.so.conf`` to be present at image build time: When some recipe installs libraries to a non-standard location, and therefore installs in a file in ``/etc/ld.so.conf.d/foo.conf``, we -need ``/etc/ld.so.conf`` containing: :: +need ``/etc/ld.so.conf`` containing:: include /etc/ld.so.conf.d/*.conf diff --git a/poky/documentation/ref-manual/migration-3.3.rst b/poky/documentation/migration-guides/migration-3.3.rst index 4fb51a39d..28857e820 100644 --- a/poky/documentation/ref-manual/migration-3.3.rst +++ b/poky/documentation/migration-guides/migration-3.3.rst @@ -1,5 +1,5 @@ -Moving to the Yocto Project 3.3 Release (hardknott) -=================================================== +Release 3.3 (hardknott) +======================= This section provides migration information for moving to the Yocto Project 3.3 Release (codename "hardknott") from the prior release. diff --git a/poky/documentation/ref-manual/migration-general.rst b/poky/documentation/migration-guides/migration-general.rst index 182482ec4..182482ec4 100644 --- a/poky/documentation/ref-manual/migration-general.rst +++ b/poky/documentation/migration-guides/migration-general.rst diff --git a/poky/documentation/overview-manual/concepts.rst b/poky/documentation/overview-manual/concepts.rst index ada5143b2..642ef15fe 100644 --- a/poky/documentation/overview-manual/concepts.rst +++ b/poky/documentation/overview-manual/concepts.rst @@ -55,8 +55,7 @@ This section briefly introduces BitBake. If you want more information on BitBake, see the :doc:`BitBake User Manual <bitbake:index>`. To see a list of the options BitBake supports, use either of the -following commands: -:: +following commands:: $ bitbake -h $ bitbake --help @@ -66,8 +65,7 @@ The most common usage for BitBake is ``bitbake recipename``, where to as the "target"). The target often equates to the first part of a recipe's filename (e.g. "foo" for a recipe named ``foo_1.3.0-r0.bb``). So, to process the ``matchbox-desktop_1.2.3.bb`` recipe file, you might -type the following: -:: +type the following:: $ bitbake matchbox-desktop @@ -141,7 +139,7 @@ hardware-specific configurations allows you to share other metadata by using a different layer where that metadata might be common across several pieces of hardware. -Many layers exist that work in the Yocto Project development environment. The +There are many layers working in the Yocto Project development environment. The :yocto_home:`Yocto Project Curated Layer Index </software-overview/layers/>` and :oe_layerindex:`OpenEmbedded Layer Index <>` both contain layers from which you can use or leverage. @@ -334,7 +332,7 @@ created by an autobuilder: One useful scenario for using the ``conf/site.conf`` file is to extend your :term:`BBPATH` variable to include the path to a ``conf/site.conf``. Then, when BitBake looks - for Metadata using ``BBPATH``, it finds the ``conf/site.conf`` file + for Metadata using :term:`BBPATH`, it finds the ``conf/site.conf`` file and applies your common configurations found in the file. To override configurations in a particular build directory, alter the similar configurations within that build directory's ``conf/local.conf`` @@ -372,7 +370,7 @@ BitBake's global behavior. This section takes a closer look at the layers the build system uses to further control the build. These layers provide Metadata for the software, machine, and policies. -In general, three types of layer input exists. You can see them below +In general, there are three types of layer input. You can see them below the "User Configuration" box in the `general workflow figure <overview-manual/concepts:openembedded build system concepts>`: @@ -429,8 +427,8 @@ Repositories <>` also shows layers categorized under "Yocto Metadata Layers." .. note:: - Layers exist in the Yocto Project Source Repositories that cannot be - found in the OpenEmbedded Layer Index. These layers are either + There are layers in the Yocto Project Source Repositories that cannot be + found in the OpenEmbedded Layer Index. Such layers are either deprecated or experimental in nature. BitBake uses the ``conf/bblayers.conf`` file, which is part of the user @@ -491,7 +489,7 @@ the machine (``conf/machine/machine.conf``) and, of course, the layer The remainder of the layer is dedicated to specific recipes by function: ``recipes-bsp``, ``recipes-core``, ``recipes-graphics``, -``recipes-kernel``, and so forth. Metadata can exist for multiple +``recipes-kernel``, and so forth. There can be metadata for multiple formfactors, graphics support systems, and so forth. .. note:: @@ -530,13 +528,11 @@ project that is more dynamic or experimental in nature, a project might keep source files in a repository controlled by a Source Control Manager (SCM) such as Git. Pulling source from a repository allows you to control the point in the repository (the revision) from which you want -to build software. Finally, a combination of the two might exist, which -would give the consumer a choice when deciding where to get source -files. +to build software. A combination of the two is also possible. BitBake uses the :term:`SRC_URI` variable to point to source files regardless of their location. Each -recipe must have a ``SRC_URI`` variable that points to the source. +recipe must have a :term:`SRC_URI` variable that points to the source. Another area that plays a significant role in where source files come from is pointed to by the @@ -544,13 +540,13 @@ from is pointed to by the a cache that can hold previously downloaded source. You can also instruct the OpenEmbedded build system to create tarballs from Git repositories, which is not the default behavior, and store them in the -``DL_DIR`` by using the +:term:`DL_DIR` by using the :term:`BB_GENERATE_MIRROR_TARBALLS` variable. -Judicious use of a ``DL_DIR`` directory can save the build system a trip +Judicious use of a :term:`DL_DIR` directory can save the build system a trip across the Internet when looking for files. A good method for using a -download directory is to have ``DL_DIR`` point to an area outside of +download directory is to have :term:`DL_DIR` point to an area outside of your Build Directory. Doing so allows you to safely delete the Build Directory if needed without fear of removing any downloaded source file. @@ -611,7 +607,7 @@ the specific revision from which to build. Source Mirror(s) ~~~~~~~~~~~~~~~~ -Two kinds of mirrors exist: pre-mirrors and regular mirrors. The +There are two kinds of mirrors: pre-mirrors and regular mirrors. The :term:`PREMIRRORS` and :term:`MIRRORS` variables point to these, respectively. BitBake checks pre-mirrors before looking upstream @@ -669,8 +665,8 @@ package files are kept: variables are used, respectively. - :term:`PACKAGE_ARCH`: Defines - architecture-specific sub-folders. For example, packages could exist - for the i586 or qemux86 architectures. + architecture-specific sub-folders. For example, packages could be + available for the i586 or qemux86 architectures. BitBake uses the :ref:`do_package_write_* <ref-tasks-package_write_deb>` @@ -683,8 +679,8 @@ and ":ref:`ref-tasks-package_write_tar`" sections in the Yocto Project Reference Manual for additional information. As an example, consider a scenario where an IPK packaging -manager is being used and package architecture support for both i586 and -qemux86 exist. Packages for the i586 architecture are placed in +manager is being used and there is package architecture support for both +i586 and qemux86. Packages for the i586 architecture are placed in ``build/tmp/deploy/ipk/i586``, while packages for the qemux86 architecture are placed in ``build/tmp/deploy/ipk/qemux86``. @@ -700,7 +696,7 @@ closer look at each of those areas. .. note:: - Separate documentation exists for the BitBake tool. See the + Documentation for the BitBake tool is available separately. See the BitBake User Manual for reference material on BitBake. @@ -751,7 +747,7 @@ Build Directory's hierarchy: architecture of the built package or packages. Depending on the eventual destination of the package or packages (i.e. machine architecture, :term:`Build Host`, SDK, or - specific machine), ``PACKAGE_ARCH`` varies. See the variable's + specific machine), :term:`PACKAGE_ARCH` varies. See the variable's description for details. - :term:`TARGET_OS`: The operating @@ -760,7 +756,7 @@ Build Directory's hierarchy: - :term:`PN`: The name of the recipe used to build the package. This variable can have multiple meanings. - However, when used in the context of input files, ``PN`` represents + However, when used in the context of input files, :term:`PN` represents the name of the recipe. - :term:`WORKDIR`: The location @@ -777,7 +773,7 @@ Build Directory's hierarchy: files for a given recipe. - :term:`BPN`: The name of the recipe - used to build the package. The ``BPN`` variable is a version of + used to build the package. The :term:`BPN` variable is a version of the ``PN`` variable but with common prefixes and suffixes removed. - :term:`PV`: The version of the @@ -785,12 +781,10 @@ Build Directory's hierarchy: .. note:: - In the previous figure, notice that two sample hierarchies exist: one - based on package architecture (i.e. - PACKAGE_ARCH - ) and one based on a machine (i.e. - MACHINE - ). The underlying structures are identical. The differentiator being + In the previous figure, notice that there are two sample hierarchies: + one based on package architecture (i.e. :term:`PACKAGE_ARCH`) + and one based on a machine (i.e. :term:`MACHINE`). + The underlying structures are identical. The differentiator being what the OpenEmbedded build system is using as a build target (e.g. general architecture, a build host, an SDK, or a specific machine). @@ -809,13 +803,13 @@ and the :term:`FILESPATH` variable to locate applicable patch files. Default processing for patch files assumes the files have either -``*.patch`` or ``*.diff`` file types. You can use ``SRC_URI`` parameters +``*.patch`` or ``*.diff`` file types. You can use :term:`SRC_URI` parameters to change the way the build system recognizes patch files. See the :ref:`ref-tasks-patch` task for more information. BitBake finds and applies multiple patches for a single recipe in the -order in which it locates the patches. The ``FILESPATH`` variable +order in which it locates the patches. The :term:`FILESPATH` variable defines the default set of directories that the build system uses to search for patch files. Once found, patches are applied to the recipe's source files, which are located in the @@ -883,12 +877,12 @@ This step in the build process consists of the following tasks: :ref:`ref-tasks-compile` task. Compilation occurs in the directory pointed to by the :term:`B` variable. Realize that the - ``B`` directory is, by default, the same as the + :term:`B` directory is, by default, the same as the :term:`S` directory. - *do_install*: After compilation completes, BitBake executes the :ref:`ref-tasks-install` task. - This task copies files from the ``B`` directory and places them in a + This task copies files from the :term:`B` directory and places them in a holding area pointed to by the :term:`D` variable. Packaging occurs later using files from this holding directory. @@ -934,7 +928,7 @@ the analysis and package splitting process use several areas: - :term:`PKGDATA_DIR`: A shared, global-state directory that holds packaging metadata generated during the packaging process. The packaging process copies metadata from - ``PKGDESTWORK`` to the ``PKGDATA_DIR`` area where it becomes globally + :term:`PKGDESTWORK` to the :term:`PKGDATA_DIR` area where it becomes globally available. - :term:`STAGING_DIR_HOST`: @@ -965,8 +959,7 @@ that part of the build process. .. note:: - Support for creating feeds directly from the - deploy/\* + Support for creating feeds directly from the ``deploy/*`` directories does not exist. Creating such feeds usually requires some kind of feed maintenance mechanism that would upload the new packages into an official package feed (e.g. the Ångström distribution). This @@ -1015,7 +1008,7 @@ actually install: With :term:`IMAGE_ROOTFS` pointing to the location of the filesystem under construction and the -``PACKAGE_INSTALL`` variable providing the final list of packages to +:term:`PACKAGE_INSTALL` variable providing the final list of packages to install, the root file system is created. Package installation is under control of the package manager (e.g. @@ -1064,19 +1057,17 @@ based on the image types specified in the The process turns everything into an image file or a set of image files and can compress the root filesystem image to reduce the overall size of the image. The formats used for the root filesystem depend on the -``IMAGE_FSTYPES`` variable. Compression depends on whether the formats +:term:`IMAGE_FSTYPES` variable. Compression depends on whether the formats support compression. As an example, a dynamically created task when creating a particular -image type would take the following form: -:: +image type would take the following form:: do_image_type So, if the type -as specified by the ``IMAGE_FSTYPES`` were ``ext4``, the dynamically -generated task would be as follows: -:: +as specified by the :term:`IMAGE_FSTYPES` were ``ext4``, the dynamically +generated task would be as follows:: do_image_ext4 @@ -1160,9 +1151,9 @@ checksum <overview-manual/concepts:checksums (signatures)>`. OpenEmbedded. To determine if a task needs to be rerun, BitBake checks if a stamp file -with a matching input checksum exists for the task. If such a stamp file -exists, the task's output is assumed to exist and still be valid. If the -file does not exist, the task is rerun. +with a matching input checksum exists for the task. In this case, +the task's output is assumed to exist and still be valid. Otherwise, +the task is rerun. .. note:: @@ -1180,9 +1171,9 @@ file does not exist, the task is rerun. the sstate cache mechanism adds is a way to cache task output that can then be shared between build machines. -Since ``STAMPS_DIR`` is usually a subdirectory of ``TMPDIR``, removing -``TMPDIR`` will also remove ``STAMPS_DIR``, which means tasks will -properly be rerun to repopulate ``TMPDIR``. +Since :term:`STAMPS_DIR` is usually a subdirectory of :term:`TMPDIR`, removing +:term:`TMPDIR` will also remove :term:`STAMPS_DIR`, which means tasks will +properly be rerun to repopulate :term:`TMPDIR`. If you want some task to always be considered "out of date", you can mark it with the :ref:`nostamp <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>` @@ -1238,14 +1229,14 @@ to run any of the ``do_fetch``, ``do_unpack``, ``do_patch``, 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 nothing exists to -compile or patch. If the ``do_package_write_*`` packages are available +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 handle all these complexities, BitBake runs in two phases. The first is the "setscene" stage. During this stage, BitBake first checks the sstate cache for any targets it is planning to build. BitBake does a -fast check to see if the object exists rather than a complete download. +fast check to see if the object exists rather than doing a complete download. If nothing exists, the second phase, which is the setscene stage, completes and the main build proceeds. @@ -1370,9 +1361,9 @@ can initialize the environment before using the tools. All the output files for an SDK are written to the ``deploy/sdk`` folder inside the :term:`Build Directory` as -shown in the previous figure. Depending on the type of SDK, several -variables exist that help configure these files. The following list -shows the variables associated with an extensible SDK: +shown in the previous figure. Depending on the type of SDK, there are +several variables to configure these files. Here are the variables +associated with an extensible SDK: - :term:`DEPLOY_DIR`: Points to the ``deploy`` directory. @@ -1417,7 +1408,7 @@ This next list, shows the variables associated with a standard SDK: - :term:`TOOLCHAIN_HOST_TASK`: Lists packages that make up the host part of the SDK (i.e. the part - that runs on the ``SDKMACHINE``). When you use + that runs on the :term:`SDKMACHINE`). When you use ``bitbake -c populate_sdk imagename`` to create the SDK, a set of default packages apply. This variable allows you to add more packages. @@ -1471,15 +1462,11 @@ cross-compiler that is used internally within BitBake only. .. note:: - The extensible SDK does not use - gcc-cross-canadian + The extensible SDK does not use ``gcc-cross-canadian`` since this SDK ships a copy of the OpenEmbedded build system and the - sysroot within it contains - gcc-cross - . + sysroot within it contains ``gcc-cross``. -The chain of events that occurs when the standard toolchain is bootstrapped: -:: +The chain of events that occurs when the standard toolchain is bootstrapped:: binutils-cross -> linux-libc-headers -> gcc-cross -> libgcc-initial -> glibc -> libgcc -> gcc-runtime @@ -1528,8 +1515,7 @@ might not be the same machine as the Build Host. can take advantage of pre-built images that ship with the Yocto Project and already contain cross-development toolchain installers. -Here is the bootstrap process for the relocatable toolchain: -:: +Here is the bootstrap process for the relocatable toolchain:: gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian @@ -1583,8 +1569,8 @@ Shared State Cache By design, the OpenEmbedded build system builds everything from scratch unless :term:`BitBake` can determine that parts do not need to be rebuilt. Fundamentally, building from -scratch is attractive as it means all parts are built fresh and no -possibility of stale data exists that can cause problems. When +scratch is attractive as it means all parts are built fresh and there is +no possibility of stale data that can cause problems. When developers hit problems, they typically default back to building from scratch so they have a know state from the start. @@ -1623,9 +1609,9 @@ them if they are deemed to be valid. - The build system does not maintain :term:`PR` information as part of - the shared state packages. Consequently, considerations exist that + the shared state packages. Consequently, there are considerations that affect maintaining shared state feeds. For information on how the - build system works with packages and can track incrementing ``PR`` + build system works with packages and can track incrementing :term:`PR` information, see the ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`" section in the Yocto Project Development Tasks Manual. @@ -1682,8 +1668,8 @@ objective of making native or cross packages relocatable. build host. However, cross packages generate output for the target architecture. -The checksum therefore needs to exclude ``WORKDIR``. The simplistic -approach for excluding the work directory is to set ``WORKDIR`` to some +The checksum therefore needs to exclude :term:`WORKDIR`. The simplistic +approach for excluding the work directory is to set :term:`WORKDIR` to some fixed value and create the checksum for the "run" script. Another problem results from the "run" scripts containing functions that @@ -1693,7 +1679,7 @@ used to prune the "run" scripts down to the minimum set, thereby alleviating this problem and making the "run" scripts much more readable as a bonus. -So far, solutions for shell scripts exist. What about Python tasks? The +So far, there are solutions for shell scripts. What about Python tasks? The same approach applies even though these tasks are more difficult. The process needs to figure out what variables a Python function accesses and what functions it calls. Again, the incremental build solution @@ -1701,10 +1687,9 @@ contains code that first figures out the variable and function dependencies, and then creates a checksum for the data used as the input to the task. -Like the ``WORKDIR`` case, situations exist where dependencies should be +Like the :term:`WORKDIR` case, there can be situations where dependencies should be ignored. For these situations, you can instruct the build process to -ignore a dependency by using a line like the following: -:: +ignore a dependency by using a line like the following:: PACKAGE_ARCHS[vardepsexclude] = "MACHINE" @@ -1714,13 +1699,12 @@ reference it. Equally, there are cases where you need to add dependencies BitBake is not able to find. You can accomplish this by using a line like the -following: -:: +following:: PACKAGE_ARCHS[vardeps] = "MACHINE" This example explicitly -adds the ``MACHINE`` variable as a dependency for ``PACKAGE_ARCHS``. +adds the :term:`MACHINE` variable as a dependency for :term:`PACKAGE_ARCHS`. As an example, consider a case with in-line Python where BitBake is not able to figure out dependencies. When running in debug mode (i.e. using @@ -1740,13 +1724,12 @@ to add is a policy decision. However, the effect is to generate a master checksum that combines the basehash and the hashes of the task's dependencies. -At the code level, a variety of ways exist by which both the basehash +At the code level, there are multiple ways by which both the basehash and the dependent task hashes can be influenced. Within the BitBake configuration file, you can give BitBake some extra information to help it construct the basehash. The following statement effectively results in a list of global variable dependency excludes (i.e. variables never -included in any checksum): -:: +included in any checksum):: BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \\ SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \\ @@ -1771,12 +1754,11 @@ desired. This file defines the two basic signature generators "OEBasicHash". By default, a dummy "noop" signature handler is enabled in BitBake. This means that behavior is unchanged from previous versions. OE-Core uses the "OEBasicHash" signature handler by default -through this setting in the ``bitbake.conf`` file: -:: +through this setting in the ``bitbake.conf`` file:: BB_SIGNATURE_HANDLER ?= "OEBasicHash" -The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same +The "OEBasicHash" :term:`BB_SIGNATURE_HANDLER` is the same as the "OEBasic" version but adds the task hash to the :ref:`stamp files <overview-manual/concepts:stamp files and the rerunning of tasks>`. This results in any metadata change that changes the task hash, automatically causing @@ -1797,7 +1779,7 @@ the build. This information includes: - ``BBHASHDEPS_``\ filename\ ``:``\ taskname: The task dependencies for each task. -- ``BB_TASKHASH``: The hash of the currently running task. +- :term:`BB_TASKHASH`: The hash of the currently running task. Shared State ------------ @@ -1826,8 +1808,7 @@ The Yocto Project team has tried to keep the details of the implementation hidden in ``sstate`` class. From a user's perspective, adding shared state wrapping to a task is as simple as this :ref:`ref-tasks-deploy` example taken -from the :ref:`deploy <ref-classes-deploy>` class: -:: +from the :ref:`deploy <ref-classes-deploy>` class:: DEPLOYDIR = "${WORKDIR}/deploy-${PN}" SSTATETASKS += "do_deploy" @@ -1867,12 +1848,11 @@ The following list explains the previous example: ``do_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 ${``DEPLOY_DIR_IMAGE``} by the ``do_deploy_setscene`` task + directly to ${:term:`DEPLOY_DIR_IMAGE`} by the ``do_deploy_setscene`` task instead, skipping the ``do_deploy`` task. - The following task definition is glue logic needed to make the - previous settings effective: - :: + previous settings effective:: python do_deploy_setscene () { sstate_setscene(d) @@ -1898,8 +1878,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`` - task, use the following: - :: + task, use the following:: do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" @@ -1915,26 +1894,23 @@ The following list explains the previous example: - ``sstate-inputdirs`` and ``sstate-outputdirs`` can also be used with multiple directories. For example, the following declares - ``PKGDESTWORK`` and ``SHLIBWORK`` as shared state input directories, - which populates the shared state cache, and ``PKGDATA_DIR`` and - ``SHLIBSDIR`` as the corresponding shared state output directories: - :: + :term:`PKGDESTWORK` and ``SHLIBWORK`` as shared state input directories, + which populates the shared state cache, and :term:`PKGDATA_DIR` and + ``SHLIBSDIR`` as the corresponding shared state output directories:: do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" - These methods also include the ability to take a lockfile when manipulating shared state directory structures, for cases where file - additions or removals are sensitive: - :: + additions or removals are sensitive:: do_package[sstate-lockfile] = "${PACKAGELOCK}" Behind the scenes, the shared state code works by looking in :term:`SSTATE_DIR` and :term:`SSTATE_MIRRORS` for -shared state files. Here is an example: -:: +shared state files. Here is an example:: SSTATE_MIRRORS ?= "\ file://.\* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ @@ -1946,7 +1922,7 @@ shared state files. Here is an example: subdirectories, where the subdirectory names are based on the first two characters of the hash. If the shared state directory structure for a mirror has the same structure - as ``SSTATE_DIR``, you must specify "PATH" as part of the URI to enable the build + as :term:`SSTATE_DIR`, you must specify "PATH" as part of the URI to enable the build system to map to the appropriate subdirectory. The shared state package validity can be detected just by looking at the @@ -1977,8 +1953,8 @@ Automatically Added Runtime Dependencies The OpenEmbedded build system automatically adds common types of runtime dependencies between packages, which means that you do not need to explicitly declare the packages using -:term:`RDEPENDS`. Three automatic -mechanisms exist (``shlibdeps``, ``pcdeps``, and ``depchains``) that +:term:`RDEPENDS`. There are three automatic +mechanisms (``shlibdeps``, ``pcdeps``, and ``depchains``) that handle shared libraries, package configuration (pkg-config) modules, and ``-dev`` and ``-dbg`` packages, respectively. For other types of runtime dependencies, you must manually declare the dependencies. @@ -1997,7 +1973,7 @@ dependencies, you must manually declare the dependencies. Simultaneously, all executables and shared libraries installed by the recipe are inspected to see what shared libraries they link against. - For each shared library dependency that is found, ``PKGDATA_DIR`` is + For each shared library dependency that is found, :term:`PKGDATA_DIR` is queried to see if some package (likely from a different recipe) contains the shared library. If such a package is found, a runtime dependency is added from the package that depends on the shared @@ -2006,7 +1982,7 @@ dependencies, you must manually declare the dependencies. The automatically added runtime dependency also includes a version restriction. This version restriction specifies that at least the current version of the package that provides the shared library must - be used, as if "package (>= version)" had been added to ``RDEPENDS``. + be used, as if "package (>= version)" had been added to :term:`RDEPENDS`. This forces an upgrade of the package containing the shared library when installing the package that depends on the library, if needed. @@ -2020,14 +1996,14 @@ dependencies, you must manually declare the dependencies. 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 ``PKGDATA_DIR`` by the + mapping is saved globally in :term:`PKGDATA_DIR` by the ``do_packagedata`` task. Simultaneously, all pkg-config modules installed by the recipe are inspected to see what other pkg-config modules they depend on. A module is seen as depending on another module if it contains a "Requires:" line that specifies the other module. For each module - dependency, ``PKGDATA_DIR`` is queried to see if some package + dependency, :term:`PKGDATA_DIR` is queried to see if some package contains the module. If such a package is found, a runtime dependency is added from the package that depends on the module to the package that contains the module. @@ -2067,7 +2043,7 @@ 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 shared-library/module-to-package mapping information will be available -when needed as long as ``DEPENDS`` has been correctly set. +when needed as long as :term:`DEPENDS` has been correctly set. Fakeroot and Pseudo =================== @@ -2116,8 +2092,7 @@ accomplished using fakeroot. under fakeroot. Otherwise, the task cannot run root-only operations, and cannot see the fake file ownership and permissions set by the other task. You need to also add a dependency on - ``virtual/fakeroot-native:do_populate_sysroot``, giving the following: - :: + ``virtual/fakeroot-native:do_populate_sysroot``, giving the following:: fakeroot do_mytask () { ... diff --git a/poky/documentation/overview-manual/development-environment.rst b/poky/documentation/overview-manual/development-environment.rst index a33f89e4f..ab155dc3b 100644 --- a/poky/documentation/overview-manual/development-environment.rst +++ b/poky/documentation/overview-manual/development-environment.rst @@ -71,7 +71,7 @@ section in the Yocto Project Development Tasks Manual. If your development host is going to be a system that runs a Linux -distribution, steps still exist that you must take to prepare the system +distribution, you must still take steps to prepare the system for use with the Yocto Project. You need to be sure that the Linux distribution on the system is one that supports the Yocto Project. You also need to be sure that the correct set of host packages are installed @@ -80,8 +80,8 @@ set up a development host that runs Linux, see the ":ref:`dev-manual/start:setting up a native linux host`" section in the Yocto Project Development Tasks Manual. -Once your development host is set up to use the Yocto Project, several -methods exist for you to do work in the Yocto Project environment: +Once your development host is set up to use the Yocto Project, there +are several ways of working in the Yocto Project environment: - *Command Lines, BitBake, and Shells:* Traditional development in the Yocto Project involves using the :term:`OpenEmbedded Build System`, @@ -271,7 +271,7 @@ files that are being worked on simultaneously by more than one person. All this work is done locally on the development host before anything is pushed to a "contrib" area and examined at the maintainer's level. -A somewhat formal method exists by which developers commit changes and +There is a somewhat formal method by which developers commit changes and push them into the "contrib" area and subsequently request that the maintainer include them into an upstream branch. This process is called "submitting a patch" or "submitting a change." For information on @@ -279,9 +279,9 @@ submitting patches and changes, see the ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`" section in the Yocto Project Development Tasks Manual. -In summary, a single point of entry exists for changes into a "master" +In summary, there is a single point of entry for changes into a "master" or development branch of the Git repository, which is controlled by the -project's maintainer. And, a set of developers exist who independently +project's maintainer. A set of developers independently develop, test, and submit changes to "contrib" areas for the maintainer to examine. The maintainer then chooses which changes are going to become a permanent part of the project. @@ -430,8 +430,7 @@ local working area (also called a branch) that tracks a specific development branch from the upstream source Git repository. in other words, you can define your local Git environment to work on any development branch in the repository. To help illustrate, consider the -following example Git commands: -:: +following example Git commands:: $ cd ~ $ git clone git://git.yoctoproject.org/poky @@ -476,8 +475,7 @@ create and checkout a local working Git branch based on a tag name. When you do this, you get a snapshot of the Git repository that reflects the state of the files when the change was made associated with that tag. The most common use is to checkout a working branch that matches a -specific Yocto Project release. Here is an example: -:: +specific Yocto Project release. Here is an example:: $ cd ~ $ git clone git://git.yoctoproject.org/poky diff --git a/poky/documentation/overview-manual/intro.rst b/poky/documentation/overview-manual/intro.rst index a2afe7756..a8091771f 100644 --- a/poky/documentation/overview-manual/intro.rst +++ b/poky/documentation/overview-manual/intro.rst @@ -12,7 +12,7 @@ introduces the Yocto Project by providing concepts, software overviews, best-known-methods (BKMs), and any other high-level introductory information suitable for a new Yocto Project user. -The following list describes what you can get from this manual: +Here is what you can get from this manual: - :ref:`overview-manual/yp-intro:introducing the yocto project`\ *:* This chapter provides an introduction to the Yocto Project. You will learn diff --git a/poky/documentation/overview-manual/yp-intro.rst b/poky/documentation/overview-manual/yp-intro.rst index fca02e4ce..d20a4ab09 100644 --- a/poky/documentation/overview-manual/yp-intro.rst +++ b/poky/documentation/overview-manual/yp-intro.rst @@ -38,8 +38,7 @@ to the Yocto Project. Features -------- -The following list describes features and advantages of the Yocto -Project: +Here are features and advantages of the Yocto Project: - *Widely Adopted Across the Industry:* Many semiconductor, operating system, software, and service vendors adopt and support the Yocto @@ -137,13 +136,11 @@ Project: Challenges ---------- -The following list presents challenges you might encounter when -developing using the Yocto Project: +Here are challenges you might encounter when developing using the Yocto Project: - *Steep Learning Curve:* The Yocto Project has a steep learning curve and has many different ways to accomplish similar tasks. It can be - difficult to choose how to proceed when varying methods exist by - which to accomplish a given task. + difficult to choose between such ways. - *Understanding What Changes You Need to Make For Your Design Requires Some Research:* Beyond the simple tutorial stage, understanding what @@ -158,7 +155,7 @@ developing using the Yocto Project: workflow <overview-manual/development-environment:the yocto project development environment>` could be confusing if you are used to traditional desktop and server software development. - In a desktop development environment, mechanisms exist to easily pull + In a desktop development environment, there are mechanisms to easily pull and install new packages, which are typically pre-compiled binaries from servers accessible over the Internet. Using the Yocto Project, you must modify your configuration and rebuild to add additional @@ -251,8 +248,7 @@ accomplish this through a recipe that is a BitBake append .. note:: For general information on BSP layer structure, see the - :doc:`/bsp-guide/index` - . + :doc:`/bsp-guide/index`. The :term:`Source Directory` contains both general layers and BSP layers right out of the box. You @@ -292,8 +288,8 @@ associated with the Yocto Project. Development Tools ----------------- -The following list consists of tools that help you develop images and -applications using the Yocto Project: +Here are tools that help you develop images and applications using +the Yocto Project: - *CROPS:* `CROPS <https://github.com/crops/poky-container/>`__ is an open source, cross-platform development framework that leverages @@ -347,8 +343,8 @@ applications using the Yocto Project: Production Tools ---------------- -The following list consists of tools that help production related -activities using the Yocto Project: +Here are tools that help with production related activities using the +Yocto Project: - *Auto Upgrade Helper:* This utility when used in conjunction with the :term:`OpenEmbedded Build System` @@ -432,8 +428,8 @@ activities using the Yocto Project: require system administrator privileges. For example, file ownership or permissions might need to be defined. Pseudo is a tool that you can either use directly or through the environment variable - ``LD_PRELOAD``. Either method allows these operations to succeed as - if system administrator privileges exist even when they do not. + ``LD_PRELOAD``. Either method allows these operations to succeed + even without system administrator privileges. Thanks to Pseudo, the Yocto Project never needs root privileges to build images for your target system. @@ -444,8 +440,7 @@ activities using the Yocto Project: Open-Embedded Build System Components ------------------------------------- -The following list consists of components associated with the -:term:`OpenEmbedded Build System`: +Here are components associated with the :term:`OpenEmbedded Build System`: - *BitBake:* BitBake is a core component of the Yocto Project and is used by the OpenEmbedded build system to build images. While BitBake @@ -511,8 +506,7 @@ section. Packages for Finished Targets ----------------------------- -The following lists components associated with packages for finished -targets: +Here are components associated with packages for finished targets: - *Matchbox:* Matchbox is an Open Source, base environment for the X Window System running on non-desktop, embedded platforms such as @@ -583,8 +577,7 @@ software. This section provides an introduction to the choices or development methods you have when setting up your Build Host. Depending on your particular workflow preference and the type of operating system your -Build Host runs, several choices exist that allow you to use the Yocto -Project. +Build Host runs, you have several choices. .. note:: @@ -794,7 +787,7 @@ Some Basic Terms ================ It helps to understand some basic fundamental terms when learning the -Yocto Project. Although a list of terms exists in the ":doc:`Yocto Project +Yocto Project. Although there is a list of terms in the ":doc:`Yocto Project Terms </ref-manual/terms>`" section of the Yocto Project Reference Manual, this section provides the definitions of some terms helpful for getting started: diff --git a/poky/documentation/poky.yaml b/poky/documentation/poky.yaml index 8ccb359e0..3bfc35b6f 100644 --- a/poky/documentation/poky.yaml +++ b/poky/documentation/poky.yaml @@ -1,12 +1,12 @@ -DISTRO : "3.2.3" -DISTRO_NAME_NO_CAP : "gatesgarth" -DISTRO_NAME : "Gatesgarth" -DISTRO_NAME_NO_CAP_MINUS_ONE : "dunfell" +DISTRO : "3.3.1" +DISTRO_NAME_NO_CAP : "hardknott" +DISTRO_NAME : "Hardknott" +DISTRO_NAME_NO_CAP_MINUS_ONE : "gatesgarth" DISTRO_NAME_NO_CAP_LTS : "dunfell" -YOCTO_DOC_VERSION : "3.2.3" -YOCTO_DOC_VERSION_MINUS_ONE : "3.1.6" -DISTRO_REL_TAG : "yocto-3.2.3" -POKYVERSION : "24.0.3" +YOCTO_DOC_VERSION : "3.3.1" +YOCTO_DOC_VERSION_MINUS_ONE : "3.2.4" +DISTRO_REL_TAG : "yocto-3.3.1" +POKYVERSION : "25.0.1" YOCTO_POKY : "poky-&DISTRO_NAME_NO_CAP;-&POKYVERSION;" YOCTO_DL_URL : "https://downloads.yoctoproject.org" YOCTO_AB_URL : "https://autobuilder.yoctoproject.org" @@ -19,7 +19,8 @@ FEDORA_HOST_PACKAGES_ESSENTIAL : "gawk make wget tar bzip2 gzip python3 unzip pe diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath \ ccache perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue perl-bignum socat \ python3-pexpect findutils which file cpio python python3-pip xz python3-GitPython \ - python3-jinja2 SDL-devel xterm rpcgen mesa-libGL-devel" + python3-jinja2 SDL-devel xterm rpcgen mesa-libGL-devel perl-FindBin perl-File-Compare \ + perl-File-Copy perl-locale" OPENSUSE_HOST_PACKAGES_ESSENTIAL : "python gcc gcc-c++ git chrpath make wget python-xml \ diffstat makeinfo python-curses patch socat python3 python3-curses tar python3-pip \ python3-pexpect xz which python3-Jinja2 Mesa-libEGL1 libSDL-devel xterm rpcgen Mesa-dri-devel diff --git a/poky/documentation/profile-manual/intro.rst b/poky/documentation/profile-manual/intro.rst index 4e1008b05..9c8fa3dbf 100644 --- a/poky/documentation/profile-manual/intro.rst +++ b/poky/documentation/profile-manual/intro.rst @@ -39,12 +39,12 @@ an 'sdk' image e.g. :: $ bitbake core-image-sato-sdk or alternatively by adding 'tools-profile' to the EXTRA_IMAGE_FEATURES line in -your local.conf: :: +your local.conf:: EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile" If you use the 'tools-profile' method, you don't need to build an sdk image - -the tracing and profiling tools will be included in non-sdk images as well e.g.: :: +the tracing and profiling tools will be included in non-sdk images as well e.g.:: $ bitbake core-image-sato @@ -55,7 +55,7 @@ the tracing and profiling tools will be included in non-sdk images as well e.g.: You can prevent that by setting the :term:`INHIBIT_PACKAGE_STRIP` - variable to "1" in your ``local.conf`` when you build the image: :: + variable to "1" in your ``local.conf`` when you build the image:: INHIBIT_PACKAGE_STRIP = "1" @@ -65,11 +65,11 @@ If you've already built a stripped image, you can generate debug packages (xxx-dbg) which you can manually install as needed. To generate debug info for packages, you can add dbg-pkgs to -EXTRA_IMAGE_FEATURES in local.conf. For example: :: +EXTRA_IMAGE_FEATURES in local.conf. For example:: EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile dbg-pkgs" Additionally, in order to generate the right type of debuginfo, we also need to -set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the ``local.conf`` file: :: +set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the ``local.conf`` file:: PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory' diff --git a/poky/documentation/profile-manual/usage.rst b/poky/documentation/profile-manual/usage.rst index c42f5b64b..825290c3f 100644 --- a/poky/documentation/profile-manual/usage.rst +++ b/poky/documentation/profile-manual/usage.rst @@ -48,7 +48,7 @@ For this section, we'll assume you've already performed the basic setup outlined in the ":ref:`profile-manual/intro:General Setup`" section. In particular, you'll get the most mileage out of perf if you profile an -image built with the following in your ``local.conf`` file: :: +image built with the following in your ``local.conf`` file:: INHIBIT_PACKAGE_STRIP = "1" @@ -62,7 +62,7 @@ Basic Perf Usage The perf tool is pretty much self-documenting. To remind yourself of the available commands, simply type 'perf', which will show you basic usage -along with the available perf subcommands: :: +along with the available perf subcommands:: root@crownbay:~# perf @@ -110,7 +110,7 @@ applets in Yocto. :: The quickest and easiest way to get some basic overall data about what's going on for a particular workload is to profile it using 'perf stat'. 'perf stat' basically profiles using a few default counters and displays -the summed counts at the end of the run: :: +the summed counts at the end of the run:: root@crownbay:~# perf stat wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 Connecting to downloads.yoctoproject.org (140.211.169.59:80) @@ -139,7 +139,7 @@ Also, note that 'perf stat' isn't restricted to a fixed set of counters - basically any event listed in the output of 'perf list' can be tallied by 'perf stat'. For example, suppose we wanted to see a summary of all the events related to kernel memory allocation/freeing along with cache -hits and misses: :: +hits and misses:: root@crownbay:~# perf stat -e kmem:* -e cache-references -e cache-misses wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 Connecting to downloads.yoctoproject.org (140.211.169.59:80) @@ -191,7 +191,7 @@ directory. :: To see the results in a 'text-based UI' (tui), simply run 'perf report', which will read the perf.data file in the current working directory and display the results -in an interactive UI: :: +in an interactive UI:: root@crownbay:~# perf report @@ -217,7 +217,7 @@ Before we do that, however, let's try running a different profile, one which shows something a little more interesting. The only difference between the new profile and the previous one is that we'll add the -g option, which will record not just the address of a sampled function, -but the entire callchain to the sampled function as well: :: +but the entire callchain to the sampled function as well:: root@crownbay:~# perf record -g wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 Connecting to downloads.yoctoproject.org (140.211.169.59:80) @@ -293,7 +293,7 @@ busybox binary, which is actually stripped out by the Yocto build system. One way around that is to put the following in your ``local.conf`` file -when you build the image: :: +when you build the image:: INHIBIT_PACKAGE_STRIP = "1" @@ -302,26 +302,26 @@ what can we do to get perf to resolve the symbols? Basically we need to install the debuginfo for the BusyBox package. To generate the debug info for the packages in the image, we can add -``dbg-pkgs`` to :term:`EXTRA_IMAGE_FEATURES` in ``local.conf``. For example: :: +``dbg-pkgs`` to :term:`EXTRA_IMAGE_FEATURES` in ``local.conf``. For example:: EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile dbg-pkgs" Additionally, in order to generate the type of debuginfo that perf understands, we also need to set :term:`PACKAGE_DEBUG_SPLIT_STYLE` -in the ``local.conf`` file: :: +in the ``local.conf`` file:: PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory' Once we've done that, we can install the debuginfo for BusyBox. The debug packages once built can be found in ``build/tmp/deploy/rpm/*`` on the host system. Find the busybox-dbg-...rpm -file and copy it to the target. For example: :: +file and copy it to the target. For example:: [trz@empanada core2]$ scp /home/trz/yocto/crownbay-tracing-dbg/build/tmp/deploy/rpm/core2_32/busybox-dbg-1.20.2-r2.core2_32.rpm root@192.168.1.31: busybox-dbg-1.20.2-r2.core2_32.rpm 100% 1826KB 1.8MB/s 00:01 -Now install the debug rpm on the target: :: +Now install the debug rpm on the target:: root@crownbay:~# rpm -i busybox-dbg-1.20.2-r2.core2_32.rpm @@ -382,7 +382,7 @@ traditional tools can also make use of the expanded possibilities now available to them, and in some cases have, as mentioned previously). We can get a list of the available events that can be used to profile a -workload via 'perf list': :: +workload via 'perf list':: root@crownbay:~# perf list @@ -525,7 +525,7 @@ workload via 'perf list': :: Only a subset of these would be of interest to us when looking at this workload, so let's choose the most likely subsystems (identified by the string before the colon in the Tracepoint events) and do a 'perf stat' -run using only those wildcarded subsystems: :: +run using only those wildcarded subsystems:: root@crownbay:~# perf stat -e skb:* -e net:* -e napi:* -e sched:* -e workqueue:* -e irq:* -e syscalls:* wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 Performance counter stats for 'wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2': @@ -587,7 +587,7 @@ run using only those wildcarded subsystems: :: Let's pick one of these tracepoints -and tell perf to do a profile using it as the sampling event: :: +and tell perf to do a profile using it as the sampling event:: root@crownbay:~# perf record -g -e sched:sched_wakeup wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 @@ -644,14 +644,14 @@ individual steps that go into the higher-level behavior exposed by the coarse-grained profiling data. As a concrete example, we can trace all the events we think might be -applicable to our workload: :: +applicable to our workload:: root@crownbay:~# perf record -g -e skb:* -e net:* -e napi:* -e sched:sched_switch -e sched:sched_wakeup -e irq:* -e syscalls:sys_enter_read -e syscalls:sys_exit_read -e syscalls:sys_enter_write -e syscalls:sys_exit_write wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 We can look at the raw trace output using 'perf script' with no -arguments: :: +arguments:: root@crownbay:~# perf script @@ -735,7 +735,7 @@ two programming language bindings, one for Python and one for Perl. Now that we have the trace data in perf.data, we can use 'perf script -g' to generate a skeleton script with handlers for the read/write -entry/exit events we recorded: :: +entry/exit events we recorded:: root@crownbay:~# perf script -g python generated Python script: perf-script.py @@ -755,7 +755,7 @@ with its parameters. For example: print "skbaddr=%u, len=%u, name=%s\n" % (skbaddr, len, name), We can run that script directly to print all of the events contained in the -perf.data file: :: +perf.data file:: root@crownbay:~# perf script -s perf-script.py @@ -833,7 +833,7 @@ result of all the per-event tallies. For that, we use the special for event_name, count in counts.iteritems(): print "%-40s %10s\n" % (event_name, count) -The end result is a summary of all the events recorded in the trace: :: +The end result is a summary of all the events recorded in the trace:: skb__skb_copy_datagram_iovec 13148 irq__softirq_entry 4796 @@ -877,13 +877,13 @@ To do system-wide profiling or tracing, you typically use the -a flag to 'perf record'. To demonstrate this, open up one window and start the profile using the --a flag (press Ctrl-C to stop tracing): :: +-a flag (press Ctrl-C to stop tracing):: root@crownbay:~# perf record -g -a ^C[ perf record: Woken up 6 times to write data ] [ perf record: Captured and wrote 1.400 MB perf.data (~61172 samples) ] -In another window, run the wget test: :: +In another window, run the wget test:: root@crownbay:~# wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2 Connecting to downloads.yoctoproject.org (140.211.169.59:80) @@ -903,7 +903,7 @@ unresolvable symbols in the expanded Xorg callchain). Note also that we have both kernel and userspace entries in the above snapshot. We can also tell perf to focus on userspace but providing a modifier, in this case 'u', to the 'cycles' hardware counter when we -record a profile: :: +record a profile:: root@crownbay:~# perf record -g -a -e cycles:u ^C[ perf record: Woken up 2 times to write data ] @@ -923,13 +923,13 @@ the entries associated with the libc-xxx.so DSO. :align: center We can also use the system-wide -a switch to do system-wide tracing. -Here we'll trace a couple of scheduler events: :: +Here we'll trace a couple of scheduler events:: root@crownbay:~# perf record -a -e sched:sched_switch -e sched:sched_wakeup ^C[ perf record: Woken up 38 times to write data ] [ perf record: Captured and wrote 9.780 MB perf.data (~427299 samples) ] -We can look at the raw output using 'perf script' with no arguments: :: +We can look at the raw output using 'perf script' with no arguments:: root@crownbay:~# perf script @@ -952,7 +952,7 @@ do with what we're interested in, namely events that schedule 'perf' itself in and out or that wake perf up. We can get rid of those by using the '--filter' option - for each event we specify using -e, we can add a --filter after that to filter out trace events that contain fields with -specific values: :: +specific values:: root@crownbay:~# perf record -a -e sched:sched_switch --filter 'next_comm != perf && prev_comm != perf' -e sched:sched_wakeup --filter 'comm != perf' ^C[ perf record: Woken up 38 times to write data ] @@ -1017,7 +1017,7 @@ perf isn't restricted to the fixed set of static tracepoints listed by 'perf list'. Users can also add their own 'dynamic' tracepoints anywhere in the kernel. For instance, suppose we want to define our own tracepoint on do_fork(). We can do that using the 'perf probe' perf -subcommand: :: +subcommand:: root@crownbay:~# perf probe do_fork Added new event: @@ -1031,7 +1031,7 @@ Adding a new tracepoint via 'perf probe' results in an event with all the expected files and format in /sys/kernel/debug/tracing/events, just the same as for static tracepoints (as discussed in more detail in the trace events subsystem -section: :: +section:: root@crownbay:/sys/kernel/debug/tracing/events/probe/do_fork# ls -al drwxr-xr-x 2 root root 0 Oct 28 11:42 . @@ -1056,7 +1056,7 @@ section: :: print fmt: "(%lx)", REC->__probe_ip We can list all dynamic tracepoints currently in -existence: :: +existence:: root@crownbay:~# perf probe -l probe:do_fork (on do_fork) @@ -1064,13 +1064,13 @@ existence: :: Let's record system-wide ('sleep 30' is a trick for recording system-wide but basically do nothing and then wake -up after 30 seconds): :: +up after 30 seconds):: root@crownbay:~# perf record -g -a -e probe:do_fork sleep 30 [ perf record: Woken up 1 times to write data ] [ perf record: Captured and wrote 0.087 MB perf.data (~3812 samples) ] -Using 'perf script' we can see each do_fork event that fired: :: +Using 'perf script' we can see each do_fork event that fired:: root@crownbay:~# perf script @@ -1163,7 +1163,7 @@ addressed by a Yocto bug: :yocto_bugs:`Bug 3388 - perf: enable man pages for basic 'help' functionality </show_bug.cgi?id=3388>`. The man pages in text form, along with some other files, such as a set -of examples, can be found in the 'perf' directory of the kernel tree: :: +of examples, can be found in the 'perf' directory of the kernel tree:: tools/perf/Documentation @@ -1197,7 +1197,7 @@ Basic ftrace usage 'ftrace' essentially refers to everything included in the /tracing directory of the mounted debugfs filesystem (Yocto follows the standard convention and mounts it at /sys/kernel/debug). Here's a listing of all -the files found in /sys/kernel/debug/tracing on a Yocto system: :: +the files found in /sys/kernel/debug/tracing on a Yocto system:: root@sugarbay:/sys/kernel/debug/tracing# ls README kprobe_events trace @@ -1222,12 +1222,12 @@ the ftrace documentation. We'll start by looking at some of the available built-in tracers. -cat'ing the 'available_tracers' file lists the set of available tracers: :: +cat'ing the 'available_tracers' file lists the set of available tracers:: root@sugarbay:/sys/kernel/debug/tracing# cat available_tracers blk function_graph function nop -The 'current_tracer' file contains the tracer currently in effect: :: +The 'current_tracer' file contains the tracer currently in effect:: root@sugarbay:/sys/kernel/debug/tracing# cat current_tracer nop @@ -1237,7 +1237,7 @@ The above listing of current_tracer shows that the there's actually no tracer currently in effect. echo'ing one of the available_tracers into current_tracer makes the -specified tracer the current tracer: :: +specified tracer the current tracer:: root@sugarbay:/sys/kernel/debug/tracing# echo function > current_tracer root@sugarbay:/sys/kernel/debug/tracing# cat current_tracer @@ -1247,7 +1247,7 @@ The above sets the current tracer to be the 'function tracer'. This tracer traces every function call in the kernel and makes it available as the contents of the 'trace' file. Reading the 'trace' file lists the currently buffered function calls that have been traced by the function -tracer: :: +tracer:: root@sugarbay:/sys/kernel/debug/tracing# cat trace | less @@ -1306,7 +1306,7 @@ great way to learn about how the kernel code works in a dynamic sense. It is a little more difficult to follow the call chains than it needs to be - luckily there's a variant of the function tracer that displays the -callchains explicitly, called the 'function_graph' tracer: :: +callchains explicitly, called the 'function_graph' tracer:: root@sugarbay:/sys/kernel/debug/tracing# echo function_graph > current_tracer root@sugarbay:/sys/kernel/debug/tracing# cat trace | less @@ -1442,7 +1442,7 @@ One especially important directory contained within the /sys/kernel/debug/tracing directory is the 'events' subdirectory, which contains representations of every tracepoint in the system. Listing out the contents of the 'events' subdirectory, we see mainly another set of -subdirectories: :: +subdirectories:: root@sugarbay:/sys/kernel/debug/tracing# cd events root@sugarbay:/sys/kernel/debug/tracing/events# ls -al @@ -1491,7 +1491,7 @@ subdirectories: :: Each one of these subdirectories corresponds to a 'subsystem' and contains yet again more subdirectories, each one of those finally corresponding to a tracepoint. For example, -here are the contents of the 'kmem' subsystem: :: +here are the contents of the 'kmem' subsystem:: root@sugarbay:/sys/kernel/debug/tracing/events# cd kmem root@sugarbay:/sys/kernel/debug/tracing/events/kmem# ls -al @@ -1513,7 +1513,7 @@ here are the contents of the 'kmem' subsystem: :: drwxr-xr-x 2 root root 0 Nov 14 23:19 mm_page_pcpu_drain Let's see what's inside the subdirectory for a -specific tracepoint, in this case the one for kmalloc: :: +specific tracepoint, in this case the one for kmalloc:: root@sugarbay:/sys/kernel/debug/tracing/events/kmem# cd kmalloc root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# ls -al @@ -1529,7 +1529,7 @@ tracepoint describes the event in memory, which is used by the various tracing tools that now make use of these tracepoint to parse the event and make sense of it, along with a 'print fmt' field that allows tools like ftrace to display the event as text. Here's what the format of the -kmalloc event looks like: :: +kmalloc event looks like:: root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# cat format name: kmalloc @@ -1568,20 +1568,20 @@ The 'enable' file in the tracepoint directory is what allows the user (or tools such as trace-cmd) to actually turn the tracepoint on and off. When enabled, the corresponding tracepoint will start appearing in the ftrace 'trace' file -described previously. For example, this turns on the kmalloc tracepoint: :: +described previously. For example, this turns on the kmalloc tracepoint:: root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# echo 1 > enable At the moment, we're not interested in the function tracer or some other tracer that might be in effect, so we first turn it off, but if we do that, we still need to turn tracing on in order to see the -events in the output buffer: :: +events in the output buffer:: root@sugarbay:/sys/kernel/debug/tracing# echo nop > current_tracer root@sugarbay:/sys/kernel/debug/tracing# echo 1 > tracing_on Now, if we look at the 'trace' file, we see nothing -but the kmalloc events we just turned on: :: +but the kmalloc events we just turned on:: root@sugarbay:/sys/kernel/debug/tracing# cat trace | less # tracer: nop @@ -1627,7 +1627,7 @@ but the kmalloc events we just turned on: :: <idle>-0 [000] ..s3 18156.400660: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d554800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC matchbox-termin-1361 [001] ...1 18156.552800: kmalloc: call_site=ffffffff81614050 ptr=ffff88006db34800 bytes_req=576 bytes_alloc=1024 gfp_flags=GFP_KERNEL|GFP_REPEAT -To again disable the kmalloc event, we need to send 0 to the enable file: :: +To again disable the kmalloc event, we need to send 0 to the enable file:: root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# echo 0 > enable @@ -1669,12 +1669,12 @@ a per-CPU graphical display. It directly uses 'trace-cmd' as the plumbing that accomplishes all that underneath the covers (and actually displays the trace-cmd command it uses, as we'll see). -To start a trace using kernelshark, first start kernelshark: :: +To start a trace using kernelshark, first start kernelshark:: root@sugarbay:~# kernelshark Then bring up the 'Capture' dialog by -choosing from the kernelshark menu: :: +choosing from the kernelshark menu:: Capture | Record @@ -1724,12 +1724,12 @@ ftrace Documentation -------------------- The documentation for ftrace can be found in the kernel Documentation -directory: :: +directory:: Documentation/trace/ftrace.txt The documentation for the trace event subsystem can also be found in the kernel -Documentation directory: :: +Documentation directory:: Documentation/trace/events.txt @@ -1784,7 +1784,7 @@ which it extracts from the open syscall's argstr. Normally, to execute this probe, you'd simply install systemtap on the system you want to probe, and directly run the probe on that system e.g. assuming the name of the -file containing the above text is trace_open.stp: :: +file containing the above text is trace_open.stp:: # stap trace_open.stp @@ -1825,7 +1825,7 @@ target, with arguments if necessary. In order to do this from a remote host, however, you need to have access to the build for the image you booted. The 'crosstap' script provides details on how to do this if you run the script on the host without -having done a build: :: +having done a build:: $ crosstap root@192.168.1.88 trace_open.stp @@ -1885,7 +1885,7 @@ Running a Script on a Target ---------------------------- Once you've done that, you should be able to run a systemtap script on -the target: :: +the target:: $ cd /path/to/yocto $ source oe-init-build-env @@ -1903,17 +1903,17 @@ the target: :: You can also run generated QEMU images with a command like 'runqemu qemux86-64' Once you've done that, you can cd to whatever -directory contains your scripts and use 'crosstap' to run the script: :: +directory contains your scripts and use 'crosstap' to run the script:: $ cd /path/to/my/systemap/script $ crosstap root@192.168.7.2 trace_open.stp -If you get an error connecting to the target e.g.: :: +If you get an error connecting to the target e.g.:: $ crosstap root@192.168.7.2 trace_open.stp error establishing ssh connection on remote 'root@192.168.7.2' -Try ssh'ing to the target and see what happens: :: +Try ssh'ing to the target and see what happens:: $ ssh root@192.168.7.2 @@ -2038,7 +2038,7 @@ tracing. Collecting and viewing a trace on the target (inside a shell) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -First, from the host, ssh to the target: :: +First, from the host, ssh to the target:: $ ssh -l root 192.168.1.47 The authenticity of host '192.168.1.47 (192.168.1.47)' can't be established. @@ -2047,30 +2047,30 @@ First, from the host, ssh to the target: :: Warning: Permanently added '192.168.1.47' (RSA) to the list of known hosts. root@192.168.1.47's password: -Once on the target, use these steps to create a trace: :: +Once on the target, use these steps to create a trace:: root@crownbay:~# lttng create Spawning a session daemon Session auto-20121015-232120 created. Traces will be written in /home/root/lttng-traces/auto-20121015-232120 -Enable the events you want to trace (in this case all kernel events): :: +Enable the events you want to trace (in this case all kernel events):: root@crownbay:~# lttng enable-event --kernel --all All kernel events are enabled in channel channel0 -Start the trace: :: +Start the trace:: root@crownbay:~# lttng start Tracing started for session auto-20121015-232120 And then stop the trace after awhile or after running a particular workload that -you want to trace: :: +you want to trace:: root@crownbay:~# lttng stop Tracing stopped for session auto-20121015-232120 -You can now view the trace in text form on the target: :: +You can now view the trace in text form on the target:: root@crownbay:~# lttng view [23:21:56.989270399] (+?.?????????) sys_geteuid: { 1 }, { } @@ -2116,14 +2116,14 @@ You can now view the trace in text form on the target: :: You can now safely destroy the trace session (note that this doesn't delete the trace - it's still there in -~/lttng-traces): :: +~/lttng-traces):: root@crownbay:~# lttng destroy Session auto-20121015-232120 destroyed at /home/root Note that the trace is saved in a directory of the same name as returned by 'lttng create', under the ~/lttng-traces directory (note that you can change this by -supplying your own name to 'lttng create'): :: +supplying your own name to 'lttng create'):: root@crownbay:~# ls -al ~/lttng-traces drwxrwx--- 3 root root 1024 Oct 15 23:21 . @@ -2139,18 +2139,18 @@ generated by the lttng-ust build. The 'hello' test program isn't installed on the rootfs by the lttng-ust build, so we need to copy it over manually. First cd into the build -directory that contains the hello executable: :: +directory that contains the hello executable:: $ cd build/tmp/work/core2_32-poky-linux/lttng-ust/2.0.5-r0/git/tests/hello/.libs -Copy that over to the target machine: :: +Copy that over to the target machine:: $ scp hello root@192.168.1.20: You now have the instrumented lttng 'hello world' test program on the target, ready to test. -First, from the host, ssh to the target: :: +First, from the host, ssh to the target:: $ ssh -l root 192.168.1.47 The authenticity of host '192.168.1.47 (192.168.1.47)' can't be established. @@ -2159,35 +2159,35 @@ First, from the host, ssh to the target: :: Warning: Permanently added '192.168.1.47' (RSA) to the list of known hosts. root@192.168.1.47's password: -Once on the target, use these steps to create a trace: :: +Once on the target, use these steps to create a trace:: root@crownbay:~# lttng create Session auto-20190303-021943 created. Traces will be written in /home/root/lttng-traces/auto-20190303-021943 -Enable the events you want to trace (in this case all userspace events): :: +Enable the events you want to trace (in this case all userspace events):: root@crownbay:~# lttng enable-event --userspace --all All UST events are enabled in channel channel0 -Start the trace: :: +Start the trace:: root@crownbay:~# lttng start Tracing started for session auto-20190303-021943 -Run the instrumented hello world program: :: +Run the instrumented hello world program:: root@crownbay:~# ./hello Hello, World! Tracing... done. And then stop the trace after awhile or after running a particular workload -that you want to trace: :: +that you want to trace:: root@crownbay:~# lttng stop Tracing stopped for session auto-20190303-021943 -You can now view the trace in text form on the target: :: +You can now view the trace in text form on the target:: root@crownbay:~# lttng view [02:31:14.906146544] (+?.?????????) hello:1424 ust_tests_hello:tptest: { cpu_id = 1 }, { intfield = 0, intfield2 = 0x0, longfield = 0, netintfield = 0, netintfieldhex = 0x0, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2, boolfield = 1 } @@ -2199,7 +2199,7 @@ You can now view the trace in text form on the target: :: . You can now safely destroy the trace session (note that this doesn't delete the -trace - it's still there in ~/lttng-traces): :: +trace - it's still there in ~/lttng-traces):: root@crownbay:~# lttng destroy Session auto-20190303-021943 destroyed at /home/root @@ -2244,7 +2244,7 @@ Basic blktrace Usage -------------------- To record a trace, simply run the 'blktrace' command, giving it the name -of the block device you want to trace activity on: :: +of the block device you want to trace activity on:: root@crownbay:~# blktrace /dev/sdc @@ -2265,7 +2265,7 @@ dumps them to userspace for blkparse to merge and sort later). :: Total: 8660 events (dropped 0), 406 KiB data If you examine the files saved to disk, you see multiple files, one per CPU and -with the device name as the first part of the filename: :: +with the device name as the first part of the filename:: root@crownbay:~# ls -al drwxr-xr-x 6 root root 1024 Oct 27 22:39 . @@ -2275,7 +2275,7 @@ with the device name as the first part of the filename: :: To view the trace events, simply invoke 'blkparse' in the directory containing the trace files, giving it the device name that forms the -first part of the filenames: :: +first part of the filenames:: root@crownbay:~# blkparse sdc @@ -2373,7 +2373,7 @@ Live Mode blktrace and blkparse are designed from the ground up to be able to operate together in a 'pipe mode' where the stdout of blktrace can be -fed directly into the stdin of blkparse: :: +fed directly into the stdin of blkparse:: root@crownbay:~# blktrace /dev/sdc -o - | blkparse -i - @@ -2386,7 +2386,7 @@ identify and capture conditions of interest. There's actually another blktrace command that implements the above pipeline as a single command, so the user doesn't have to bother typing -in the above command sequence: :: +in the above command sequence:: root@crownbay:~# btrace /dev/sdc @@ -2401,19 +2401,19 @@ the traced device at all by providing native support for sending all trace data over the network. To have blktrace operate in this mode, start blktrace on the target -system being traced with the -l option, along with the device to trace: :: +system being traced with the -l option, along with the device to trace:: root@crownbay:~# blktrace -l /dev/sdc server: waiting for connections... On the host system, use the -h option to connect to the target system, -also passing it the device to trace: :: +also passing it the device to trace:: $ blktrace -d /dev/sdc -h 192.168.1.43 blktrace: connecting to 192.168.1.43 blktrace: connected! -On the target system, you should see this: :: +On the target system, you should see this:: server: connection from 192.168.1.43 @@ -2424,7 +2424,7 @@ In another shell, execute a workload you want to trace. :: linux-2.6.19.2.tar.b 100% \|*******************************\| 41727k 0:00:00 ETA When it's done, do a Ctrl-C on the host system to stop the -trace: :: +trace:: ^C=== sdc === CPU 0: 7691 events, 361 KiB data @@ -2432,7 +2432,7 @@ trace: :: Total: 11800 events (dropped 0), 554 KiB data On the target system, you should also see a trace summary for the trace -just ended: :: +just ended:: server: end of run for 192.168.1.43:sdc === sdc === @@ -2441,20 +2441,20 @@ just ended: :: Total: 11800 events (dropped 0), 554 KiB data The blktrace instance on the host will -save the target output inside a hostname-timestamp directory: :: +save the target output inside a hostname-timestamp directory:: $ ls -al drwxr-xr-x 10 root root 1024 Oct 28 02:40 . drwxr-sr-x 4 root root 1024 Oct 26 18:24 .. drwxr-xr-x 2 root root 1024 Oct 28 02:40 192.168.1.43-2012-10-28-02:40:56 -cd into that directory to see the output files: :: +cd into that directory to see the output files:: $ ls -l -rw-r--r-- 1 root root 369193 Oct 28 02:44 sdc.blktrace.0 -rw-r--r-- 1 root root 197278 Oct 28 02:44 sdc.blktrace.1 -And run blkparse on the host system using the device name: :: +And run blkparse on the host system using the device name:: $ blkparse sdc @@ -2517,25 +2517,25 @@ userspace tools. To enable tracing for a given device, use /sys/block/xxx/trace/enable, where xxx is the device name. This for example enables tracing for -/dev/sdc: :: +/dev/sdc:: root@crownbay:/sys/kernel/debug/tracing# echo 1 > /sys/block/sdc/trace/enable Once you've selected the device(s) you want -to trace, selecting the 'blk' tracer will turn the blk tracer on: :: +to trace, selecting the 'blk' tracer will turn the blk tracer on:: root@crownbay:/sys/kernel/debug/tracing# cat available_tracers blk function_graph function nop root@crownbay:/sys/kernel/debug/tracing# echo blk > current_tracer -Execute the workload you're interested in: :: +Execute the workload you're interested in:: root@crownbay:/sys/kernel/debug/tracing# cat /media/sdc/testfile.txt And look at the output (note here that we're using 'trace_pipe' instead of trace to capture this trace - this allows us to wait around on the pipe -for data to appear): :: +for data to appear):: root@crownbay:/sys/kernel/debug/tracing# cat trace_pipe cat-3587 [001] d..1 3023.276361: 8,32 Q R 1699848 + 8 [cat] @@ -2554,7 +2554,7 @@ for data to appear): :: cat-3587 [001] d..1 3023.276497: 8,32 m N cfq3587 activate rq, drv=1 cat-3587 [001] d..2 3023.276500: 8,32 D R 1699848 + 8 [cat] -And this turns off tracing for the specified device: :: +And this turns off tracing for the specified device:: root@crownbay:/sys/kernel/debug/tracing# echo 0 > /sys/block/sdc/trace/enable @@ -2572,6 +2572,6 @@ section can be found here: The above manpages, along with manpages for the other blktrace utilities (btt, blkiomon, etc) can be found in the /doc directory of the blktrace -tools git repo: :: +tools git repo:: $ git clone git://git.kernel.dk/blktrace.git diff --git a/poky/documentation/ref-manual/classes.rst b/poky/documentation/ref-manual/classes.rst index 52a50faf6..09878c480 100644 --- a/poky/documentation/ref-manual/classes.rst +++ b/poky/documentation/ref-manual/classes.rst @@ -50,7 +50,7 @@ splitting out of debug symbols during packaging). ``do_package_write_*`` tasks to have different signatures for the machines with different tunings. Additionally, unnecessary rebuilds occur every time an image for a - different ``MACHINE`` is built even when the recipe never changes. + different :term:`MACHINE` is built even when the recipe never changes. By default, all recipes inherit the :ref:`base <ref-classes-base>` and :ref:`package <ref-classes-package>` classes, which enable @@ -110,7 +110,7 @@ It's useful to have some idea of how the tasks defined by the - :ref:`ref-tasks-configure` - Regenerates the configure script (using ``autoreconf``) and then launches it with a standard set of arguments used during cross-compilation. You can pass - additional parameters to ``configure`` through the ``EXTRA_OECONF`` + additional parameters to ``configure`` through the :term:`EXTRA_OECONF` or :term:`PACKAGECONFIG_CONFARGS` variables. @@ -168,8 +168,7 @@ example use for this class. the "subpath" parameter limits the checkout to a specific subpath of the tree. Here is an example where ``${BP}`` is used so that the files are extracted into the subdirectory expected by the default value of - ``S``: - :: + :term:`S`:: SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}" @@ -221,8 +220,7 @@ each recipe you wish to blacklist. Specify the :term:`PN` value as a variable flag (varflag) and provide a reason, which is reported, if the package is requested to be built as the value. For example, if you want to blacklist a recipe called "exoticware", you add -the following to your ``local.conf`` or distribution configuration: -:: +the following to your ``local.conf`` or distribution configuration:: INHERIT += "blacklist" PNBLACKLIST[exoticware] = "Not supported by our organization." @@ -258,7 +256,7 @@ Collecting build statistics is enabled by default through the :term:`USER_CLASSES` variable from your ``local.conf`` file. Consequently, you do not have to do anything to enable the class. However, if you want to disable the class, simply -remove "buildstats" from the ``USER_CLASSES`` list. +remove "buildstats" from the :term:`USER_CLASSES` list. .. _ref-classes-buildstats-summary: @@ -291,21 +289,6 @@ is used during the build process for ``nativesdk``, ``cross``, and ``cross-canadian`` recipes to change ``RPATH`` records within binaries in order to make them relocatable. -.. _ref-classes-clutter: - -``clutter.bbclass`` -=================== - -The ``clutter`` class consolidates the major and minor version naming -and other common items used by Clutter and related recipes. - -.. note:: - - Unlike some other classes related to specific libraries, recipes - building other software that uses Clutter do not need to inherit this - class unless they use the same recipe versioning scheme that the - Clutter and related recipes do. - .. _ref-classes-cmake: ``cmake.bbclass`` @@ -450,7 +433,7 @@ deployed to :term:`DEPLOYDIR`, and use ``addtask`` to add the task at the appropriate place, which is usually after :ref:`ref-tasks-compile` or :ref:`ref-tasks-install`. The class then takes care of -staging the files from ``DEPLOYDIR`` to ``DEPLOY_DIR_IMAGE``. +staging the files from :term:`DEPLOYDIR` to :term:`DEPLOY_DIR_IMAGE`. .. _ref-classes-devshell: @@ -470,8 +453,7 @@ information about using ``devshell``. The ``devupstream`` class uses :term:`BBCLASSEXTEND` to add a variant of the recipe that fetches from an alternative URI (e.g. Git) instead of a -tarball. Following is an example: -:: +tarball. Following is an example:: BBCLASSEXTEND = "devupstream:target" SRC_URI_class-devupstream = "git://git.example.com/example" @@ -481,8 +463,7 @@ Adding the above statements to your recipe creates a variant that has :term:`DEFAULT_PREFERENCE` set to "-1". Consequently, you need to select the variant of the recipe to use it. Any development-specific adjustments can be done by using the -``class-devupstream`` override. Here is an example: -:: +``class-devupstream`` override. Here is an example:: DEPENDS_append_class-devupstream = " gperf-native" do_configure_prepend_class-devupstream() { @@ -493,7 +474,7 @@ The class currently only supports creating a development variant of the target recipe, not ``native`` or ``nativesdk`` variants. -The ``BBCLASSEXTEND`` syntax (i.e. ``devupstream:target``) provides +The :term:`BBCLASSEXTEND` syntax (i.e. ``devupstream:target``) provides support for ``native`` and ``nativesdk`` variants. Consequently, this functionality can be added in a future release. @@ -538,14 +519,13 @@ and to build it, respectively. When your recipe inherits the ``externalsrc`` class, you use the :term:`EXTERNALSRC` and :term:`EXTERNALSRC_BUILD` variables to -ultimately define ``S`` and ``B``. +ultimately define :term:`S` and :term:`B`. By default, this class expects the source code to support recipe builds that use the :term:`B` variable to point to the directory in which the OpenEmbedded build system places the generated objects built -from the recipes. By default, the ``B`` directory is set to the -following, which is separate from the source directory (``S``): -:: +from the recipes. By default, the :term:`B` directory is set to the +following, which is separate from the source directory (:term:`S`):: ${WORKDIR}/${BPN}/{PV}/ @@ -581,8 +561,7 @@ be performed using the useradd class to add user and group configuration to a specific recipe. -Here is an example that uses this class in an image recipe: -:: +Here is an example that uses this class in an image recipe:: inherit extrausers EXTRA_USERS_PARAMS = "\ @@ -595,8 +574,7 @@ Here is an example that uses this class in an image recipe: " Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns -passwords: -:: +passwords:: inherit extrausers EXTRA_USERS_PARAMS = "\ @@ -604,8 +582,7 @@ passwords: useradd -P tester01 tester-sue; \ " -Finally, here is an example that sets the root password to "1876*18": -:: +Finally, here is an example that sets the root password to "1876*18":: inherit extrausers EXTRA_USERS_PARAMS = "\ @@ -712,8 +689,8 @@ introspection. This functionality is only enabled if the .. note:: This functionality is backfilled by default and, if not applicable, - should be disabled through ``DISTRO_FEATURES_BACKFILL_CONSIDERED`` or - ``MACHINE_FEATURES_BACKFILL_CONSIDERED``, respectively. + should be disabled through :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or + :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`, respectively. .. _ref-classes-grub-efi: @@ -861,14 +838,13 @@ using an empty :term:`PARALLEL_MAKE` variable. Inheriting the ``icecc`` class changes all sstate signatures. Consequently, if a development team has a dedicated build system that populates :term:`SSTATE_MIRRORS` and they want to -reuse sstate from ``SSTATE_MIRRORS``, then all developers and the build +reuse sstate from :term:`SSTATE_MIRRORS`, then all developers and the build system need to either inherit the ``icecc`` class or nobody should. At the distribution level, you can inherit the ``icecc`` class to be sure that all builders start with the same sstate signatures. After inheriting the class, you can then disable the feature by setting the -:term:`ICECC_DISABLED` variable to "1" as follows: -:: +:term:`ICECC_DISABLED` variable to "1" as follows:: INHERIT_DISTRO_append = " icecc" ICECC_DISABLED ??= "1" @@ -876,8 +852,7 @@ inheriting the class, you can then disable the feature by setting the This practice makes sure everyone is using the same signatures but also requires individuals that do want to use Icecream to enable the feature -individually as follows in your ``local.conf`` file: -:: +individually as follows in your ``local.conf`` file:: ICECC_DISABLED = "" @@ -891,10 +866,10 @@ First, the root filesystem is created from packages using one of the ``rootfs*.bbclass`` files (depending on the package format used) and then one or more image files are created. -- The ``IMAGE_FSTYPES`` variable controls the types of images to +- The :term:`IMAGE_FSTYPES` variable controls the types of images to generate. -- The ``IMAGE_INSTALL`` variable controls the list of packages to +- The :term:`IMAGE_INSTALL` variable controls the list of packages to install into the image. For information on customizing images, see the @@ -925,8 +900,7 @@ types. By default, the :ref:`image <ref-classes-image>` class automatically enables the ``image_types`` class. The ``image`` class uses the -``IMGCLASSES`` variable as follows: -:: +``IMGCLASSES`` variable as follows:: IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}" IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}" @@ -942,7 +916,7 @@ The ``image_types`` class also handles conversion and compression of images. .. note:: To build a VMware VMDK image, you need to add "wic.vmdk" to - ``IMAGE_FSTYPES``. This would also be similar for Virtual Box Virtual Disk + :term:`IMAGE_FSTYPES`. This would also be similar for Virtual Box Virtual Disk Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. .. _ref-classes-image-live: @@ -968,8 +942,7 @@ during the :ref:`ref-tasks-rootfs` task, which optimizes the size of libraries contained in the image. By default, the class is enabled in the ``local.conf.template`` using -the :term:`USER_CLASSES` variable as follows: -:: +the :term:`USER_CLASSES` variable as follows:: USER_CLASSES ?= "buildstats image-mklibs image-prelink" @@ -984,8 +957,7 @@ the dynamic linking of shared libraries to reduce executable startup time. By default, the class is enabled in the ``local.conf.template`` using -the :term:`USER_CLASSES` variable as follows: -:: +the :term:`USER_CLASSES` variable as follows:: USER_CLASSES ?= "buildstats image-mklibs image-prelink" @@ -1014,16 +986,15 @@ configuration). However, to skip one or more checks in recipes, you should use :term:`INSANE_SKIP`. For example, to skip the check for symbolic link ``.so`` files in the main package of a recipe, add the following to the recipe. You need to realize that the -package name override, in this example ``${PN}``, must be used: -:: +package name override, in this example ``${PN}``, must be used:: INSANE_SKIP_${PN} += "dev-so" Please keep in mind that the QA checks -exist in order to detect real or potential problems in the packaged +are meant to detect real or potential problems in the packaged output. So exercise caution when disabling these checks. -The following list shows the tests you can list with the ``WARN_QA`` and +Here are the tests you can list with the :term:`WARN_QA` and ``ERROR_QA`` variables: - ``already-stripped:`` Checks that produced binaries have not @@ -1099,8 +1070,8 @@ The following list shows the tests you can list with the ``WARN_QA`` and - ``dev-so:`` Checks that the ``.so`` symbolic links are in the ``-dev`` package and not in any of the other packages. In general, these symlinks are only useful for development purposes. Thus, the - ``-dev`` package is the correct location for them. Some very rare - cases do exist for dynamically loaded modules where these symlinks + ``-dev`` package is the correct location for them. In very rare + cases, such as dynamically loaded modules, these symlinks are needed instead in the main package. - ``file-rdeps:`` Checks that file-level dependencies identified by @@ -1152,18 +1123,17 @@ The following list shows the tests you can list with the ``WARN_QA`` and - ``invalid-packageconfig:`` Checks that no undefined features are being added to :term:`PACKAGECONFIG`. For - example, any name "foo" for which the following form does not exist: - :: + example, any name "foo" for which the following form does not exist:: PACKAGECONFIG[foo] = "..." -- ``la:`` Checks ``.la`` files for any ``TMPDIR`` paths. Any ``.la`` +- ``la:`` Checks ``.la`` files for any :term:`TMPDIR` paths. Any ``.la`` file containing these paths is incorrect since ``libtool`` adds the correct sysroot prefix when using the files automatically itself. - ``ldflags:`` Ensures that the binaries were linked with the :term:`LDFLAGS` options provided by the build system. - If this test fails, check that the ``LDFLAGS`` variable is being + If this test fails, check that the :term:`LDFLAGS` variable is being passed to the linker command. - ``libdir:`` Checks for libraries being installed into incorrect @@ -1203,7 +1173,7 @@ The following list shows the tests you can list with the ``WARN_QA`` and invalid characters (i.e. characters other than 0-9, a-z, ., +, and -). -- ``pkgv-undefined:`` Checks to see if the ``PKGV`` variable is +- ``pkgv-undefined:`` Checks to see if the :term:`PKGV` variable is undefined during :ref:`ref-tasks-package`. - ``pkgvarcheck:`` Checks through the variables @@ -1223,8 +1193,8 @@ The following list shows the tests you can list with the ``WARN_QA`` and - ``pn-overrides:`` Checks that a recipe does not have a name (:term:`PN`) value that appears in :term:`OVERRIDES`. If a recipe is named such that - its ``PN`` value matches something already in ``OVERRIDES`` (e.g. - ``PN`` happens to be the same as :term:`MACHINE` or + its :term:`PN` value matches something already in :term:`OVERRIDES` (e.g. + :term:`PN` happens to be the same as :term:`MACHINE` or :term:`DISTRO`), it can have unexpected consequences. For example, assignments such as ``FILES_${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``. @@ -1275,8 +1245,8 @@ The following list shows the tests you can list with the ``WARN_QA`` and .. note:: - If you are not using runtime package management on your target - system, then you do not need to worry about this situation. + This is only relevant when you are using runtime package management + on your target system. - ``xorg-driver-abi:`` Checks that all packages containing Xorg drivers have ABI dependencies. The ``xserver-xorg`` recipe provides @@ -1636,8 +1606,7 @@ a couple different ways: .. note:: When creating a recipe this way, the recipe name must follow this - naming convention: - :: + naming convention:: myrecipe-native.bb @@ -1645,8 +1614,7 @@ a couple different ways: Not using this naming convention can lead to subtle problems caused by existing code that depends on that naming convention. -- Create or modify a target recipe that contains the following: - :: +- Create or modify a target recipe that contains the following:: BBCLASSEXTEND = "native" @@ -1677,8 +1645,7 @@ couple different ways: inherit statement in the recipe after all other inherit statements so that the ``nativesdk`` class is inherited last. -- Create a ``nativesdk`` variant of any recipe by adding the following: - :: +- Create a ``nativesdk`` variant of any recipe by adding the following:: BBCLASSEXTEND = "nativesdk" @@ -1689,13 +1656,12 @@ couple different ways: .. note:: - When creating a recipe, you must follow this naming convention: - :: + When creating a recipe, you must follow this naming convention:: nativesdk-myrecipe.bb - Not doing so can lead to subtle problems because code exists that + Not doing so can lead to subtle problems because there is code that depends on the naming convention. Although applied differently, the ``nativesdk`` class is used with both @@ -1733,10 +1699,10 @@ section in the Yocto Project Development Tasks Manual. ``oelint.bbclass`` ================== -The ``oelint`` class is an obsolete lint checking tool that exists in +The ``oelint`` class is an obsolete lint checking tool available in ``meta/classes`` in the :term:`Source Directory`. -A number of classes exist that could be generally useful in OE-Core but +There are some classes that could be generally useful in OE-Core but are never actually used within OE-Core itself. The ``oelint`` class is one such example. However, being aware of this class can reduce the proliferation of different versions of similar classes across multiple @@ -1753,14 +1719,13 @@ before attempting to fetch it from the upstream specified in :term:`SRC_URI` within each recipe. To use this class, inherit it globally and specify -:term:`SOURCE_MIRROR_URL`. Here is an example: -:: +:term:`SOURCE_MIRROR_URL`. Here is an example:: INHERIT += "own-mirrors" SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" You can specify only a single URL -in ``SOURCE_MIRROR_URL``. +in :term:`SOURCE_MIRROR_URL`. .. _ref-classes-package: @@ -1784,7 +1749,7 @@ package-specific classes: use this class. You can control the list of resulting package formats by using the -``PACKAGE_CLASSES`` variable defined in your ``conf/local.conf`` +:term:`PACKAGE_CLASSES` variable defined in your ``conf/local.conf`` configuration file, which is located in the :term:`Build Directory`. When defining the variable, you can specify one or more package types. Since images are generated from @@ -1805,7 +1770,7 @@ the same or similar package. This comparison takes into account a complete build of the package with all dependencies previously built. The reason for this discrepancy is because the RPM package manager creates and processes more :term:`Metadata` than the IPK package -manager. Consequently, you might consider setting ``PACKAGE_CLASSES`` to +manager. Consequently, you might consider setting :term:`PACKAGE_CLASSES` to "package_ipk" if you are building smaller systems. Before making your package manager decision, however, you should @@ -1887,7 +1852,7 @@ variable in the ``local.conf`` file. .. note:: You cannot specify the ``package_tar`` class first using the - ``PACKAGE_CLASSES`` variable. You must use ``.deb``, ``.ipk``, or ``.rpm`` + :term:`PACKAGE_CLASSES` variable. You must use ``.deb``, ``.ipk``, or ``.rpm`` file formats for your image or SDK. .. _ref-classes-packagedata: @@ -1909,7 +1874,7 @@ This class is enabled by default because it is inherited by the ======================== The ``packagegroup`` class sets default values appropriate for package -group recipes (e.g. ``PACKAGES``, ``PACKAGE_ARCH``, ``ALLOW_EMPTY``, and +group recipes (e.g. :term:`PACKAGES`, :term:`PACKAGE_ARCH`, :term:`ALLOW_EMPTY`, and so forth). It is highly recommended that all package group recipes inherit this class. @@ -2017,8 +1982,7 @@ established and then populates the SDK. After populating the SDK, the contains the cross-compiler and associated tooling, and the target, which contains a target root filesystem that is configured for the SDK usage. These two images reside in :term:`SDK_OUTPUT`, -which consists of the following: -:: +which consists of the following:: ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs @@ -2180,8 +2144,7 @@ installed by ``libtool``. Removing these files results in them being absent from both the sysroot and target packages. If a recipe needs the ``.la`` files to be installed, then the recipe can -override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows: -:: +override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows:: REMOVE_LIBTOOL_LA = "0" @@ -2230,9 +2193,8 @@ modifying and building source code out of the work directory for a recipe, enabling ``rm_work`` will potentially result in your changes to the source being lost. To exclude some recipes from having their work directories deleted by ``rm_work``, you can add the names of the recipe -or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which -can also be set in your ``local.conf`` file. Here is an example: -:: +or recipes you are working on to the :term:`RM_WORK_EXCLUDE` variable, which +can also be set in your ``local.conf`` file. Here is an example:: RM_WORK_EXCLUDE += "busybox glibc" @@ -2346,11 +2308,11 @@ results so these tests can be skipped over but still make the correct values available. The ``meta/site directory`` contains test results sorted into different categories such as architecture, endianness, and the ``libc`` used. Site information provides a list of files containing -data relevant to the current build in the ``CONFIG_SITE`` variable that +data relevant to the current build in the :term:`CONFIG_SITE` variable that Autotools automatically picks up. -The class also provides variables like ``SITEINFO_ENDIANNESS`` and -``SITEINFO_BITS`` that can be used elsewhere in the metadata. +The class also provides variables like :term:`SITEINFO_ENDIANNESS` and +:term:`SITEINFO_BITS` that can be used elsewhere in the metadata. .. _ref-classes-sstate: @@ -2401,7 +2363,7 @@ stages: .. note:: Additionally, a recipe can customize the files further by - declaring a processing function in the ``SYSROOT_PREPROCESS_FUNCS`` + declaring a processing function in the :term:`SYSROOT_PREPROCESS_FUNCS` variable. A shared state (sstate) object is built from these files and the @@ -2443,11 +2405,11 @@ stages: recommended for general use, the files do allow some issues such as user creation and module indexes to be addressed. - Because recipes can have other dependencies outside of ``DEPENDS`` + Because recipes can have other dependencies outside of :term:`DEPENDS` (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``), the sysroot creation function ``extend_recipe_sysroot`` is also added as a pre-function for those tasks whose dependencies are not through - ``DEPENDS`` but operate similarly. + :term:`DEPENDS` but operate similarly. When installing dependencies into the sysroot, the code traverses the dependency graph and processes dependencies in exactly the same way @@ -2531,8 +2493,7 @@ You should set :term:`SYSTEMD_SERVICE` to the name of the service file. You should also use a package name override to indicate the package to which the value applies. If the value applies to the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here -is an example from the connman recipe: -:: +is an example from the connman recipe:: SYSTEMD_SERVICE_${PN} = "connman.service" @@ -2608,8 +2569,7 @@ The tests are commands that run on the target system over ``ssh``. Each test is written in Python and makes use of the ``unittest`` module. The ``testimage.bbclass`` runs tests on an image when called using the -following: -:: +following:: $ bitbake -c testimage image @@ -2628,8 +2588,7 @@ section in the Yocto Project Development Tasks Manual. This class supports running automated tests against software development kits (SDKs). The ``testsdk`` class runs tests on an SDK when called -using the following: -:: +using the following:: $ bitbake -c testsdk image @@ -2684,8 +2643,7 @@ the environment for installed SDKs. The ``typecheck`` class provides support for validating the values of variables set at the configuration level against their defined types. The OpenEmbedded build system allows you to define the type of a -variable using the "type" varflag. Here is an example: -:: +variable using the "type" varflag. Here is an example:: IMAGE_FEATURES[type] = "list" @@ -2695,14 +2653,12 @@ variable using the "type" varflag. Here is an example: ======================== The ``uboot-config`` class provides support for U-Boot configuration for -a machine. Specify the machine in your recipe as follows: -:: +a machine. Specify the machine in your recipe as follows:: UBOOT_CONFIG ??= <default> UBOOT_CONFIG[foo] = "config,images" -You can also specify the machine using this method: -:: +You can also specify the machine using this method:: UBOOT_MACHINE = "config" @@ -2779,8 +2735,8 @@ initialization script on behalf of the package. The OpenEmbedded build system takes care of details such as making sure the script is stopped before a package is removed and started when the package is installed. -Three variables control this class: ``INITSCRIPT_PACKAGES``, -``INITSCRIPT_NAME`` and ``INITSCRIPT_PARAMS``. See the variable links +Three variables control this class: :term:`INITSCRIPT_PACKAGES`, +:term:`INITSCRIPT_NAME` and :term:`INITSCRIPT_PARAMS`. See the variable links for details. .. _ref-classes-useradd: @@ -2834,9 +2790,9 @@ additional information. .. note:: You do not use the ``useradd-staticids`` class directly. You either enable - or disable the class by setting the ``USERADDEXTENSION`` variable. If you + or disable the class by setting the :term:`USERADDEXTENSION` variable. If you enable or disable the class in a configured system, :term:`TMPDIR` might - contain incorrect ``uid`` and ``gid`` values. Deleting the ``TMPDIR`` + contain incorrect ``uid`` and ``gid`` values. Deleting the :term:`TMPDIR` directory will correct this condition. .. _ref-classes-utility-tasks: diff --git a/poky/documentation/ref-manual/devtool-reference.rst b/poky/documentation/ref-manual/devtool-reference.rst index 629aa2ffb..1862c481d 100644 --- a/poky/documentation/ref-manual/devtool-reference.rst +++ b/poky/documentation/ref-manual/devtool-reference.rst @@ -22,8 +22,7 @@ Getting Help The ``devtool`` command line is organized similarly to Git in that it has a number of sub-commands for each function. You can run -``devtool --help`` to see all the commands: -:: +``devtool --help`` to see all the commands:: $ devtool -h NOTE: Starting bitbake server... @@ -79,8 +78,7 @@ has a number of sub-commands for each function. You can run As directed in the general help output, you can get more syntax on a specific command by providing the command name and -using "--help": -:: +using "--help":: $ devtool add --help NOTE: Starting bitbake server... @@ -172,8 +170,7 @@ you. The source files the recipe uses should exist in an external area. The following example creates and adds a new recipe named ``jackson`` to a workspace layer the tool creates. The source code built by the recipes -resides in ``/home/user/sources/jackson``: -:: +resides in ``/home/user/sources/jackson``:: $ devtool add jackson /home/user/sources/jackson @@ -201,8 +198,7 @@ unpacking files from a remote URI. In some cases, you might want to specify a source revision by branch, tag, or commit hash. You can specify these options when using the ``devtool add`` command: -- To specify a source branch, use the ``--srcbranch`` option: - :: +- To specify a source branch, use the ``--srcbranch`` option:: $ devtool add --srcbranch &DISTRO_NAME_NO_CAP; jackson /home/user/sources/jackson @@ -210,8 +206,7 @@ specify these options when using the ``devtool add`` command: branch. - To specify a specific tag or commit hash, use the ``--srcrev`` - option: - :: + option:: $ devtool add --srcrev &DISTRO_REL_TAG; jackson /home/user/sources/jackson $ devtool add --srcrev some_commit_hash /home/user/sources/jackson @@ -269,8 +264,7 @@ The ``devtool modify`` command extracts the source for a recipe, sets it up as a Git repository if the source had not already been fetched from Git, checks out a branch for development, and applies any patches from the recipe as commits on top. You can use the following command to -checkout the source files: -:: +checkout the source files:: $ devtool modify recipe @@ -309,8 +303,7 @@ compile, and test the code. When you are satisfied with the results and you have committed your changes to the Git repository, you can then run the -``devtool update-recipe`` to create the patches and update the recipe: -:: +``devtool update-recipe`` to create the patches and update the recipe:: $ devtool update-recipe recipe @@ -321,8 +314,7 @@ Often, you might want to apply customizations made to your software in your own layer rather than apply them to the original recipe. If so, you can use the ``-a`` or ``--append`` option with the ``devtool update-recipe`` command. These options allow you to specify -the layer into which to write an append file: -:: +the layer into which to write an append file:: $ devtool update-recipe recipe -a base-layer-directory @@ -358,8 +350,7 @@ particular recipe. recipe's latest version tag. As with all ``devtool`` commands, you can get help on the individual -command: -:: +command:: $ devtool check-upgrade-status -h NOTE: Starting bitbake server... @@ -412,8 +403,8 @@ Upgrading a Recipe As software matures, upstream recipes are upgraded to newer versions. As a developer, you need to keep your local recipes up-to-date with the -upstream version releases. Several methods exist by which you can -upgrade recipes. You can read about them in the ":ref:`dev-manual/common-tasks:upgrading recipes`" +upstream version releases. There are several ways of upgrading recipes. +You can read about them in the ":ref:`dev-manual/common-tasks:upgrading recipes`" section of the Yocto Project Development Tasks Manual. This section overviews the ``devtool upgrade`` command. @@ -462,8 +453,7 @@ files have been modified, the command preserves the modified files in a separate "attic" subdirectory under the workspace layer. Here is an example that resets the workspace directory that contains the -``mtr`` recipe: -:: +``mtr`` recipe:: $ devtool reset mtr NOTE: Cleaning sysroot for recipe mtr... @@ -482,8 +472,7 @@ Use the ``devtool build`` command to build your recipe. The When you use the ``devtool build`` command, you must supply the root name of the recipe (i.e. do not provide versions, paths, or extensions). You can use either the "-s" or the "--disable-parallel-make" options to -disable parallel makes during the build. Here is an example: -:: +disable parallel makes during the build. Here is an example:: $ devtool build recipe @@ -499,8 +488,7 @@ device for testing. For proper integration into a final image, you need to edit your custom image recipe appropriately. When you use the ``devtool build-image`` command, you must supply the -name of the image. This command has no command line options: -:: +name of the image. This command has no command line options:: $ devtool build-image image @@ -510,8 +498,7 @@ Deploying Your Software on the Target Machine ============================================= Use the ``devtool deploy-target`` command to deploy the recipe's build -output to the live target machine: -:: +output to the live target machine:: $ devtool deploy-target recipe target @@ -529,8 +516,8 @@ you do, the package manager is bypassed. should never use it to update an image that will be used in production. -Some conditions exist that could prevent a deployed application from -behaving as expected. When both of the following conditions exist, your +Some conditions could prevent a deployed application from +behaving as expected. When both of the following conditions are met, your application has the potential to not behave correctly when run on the target: @@ -541,7 +528,7 @@ target: - The target does not physically have the packages on which the application depends installed. -If both of these conditions exist, your application will not behave as +If both of these conditions are met, your application will not behave as expected. The reason for this misbehavior is because the ``devtool deploy-target`` command does not deploy the packages (e.g. libraries) on which your new application depends. The assumption is that @@ -582,15 +569,13 @@ new workspace layer, it is populated with the ``README`` file and the ``conf`` directory only. The following example creates a new workspace layer in your current -working and by default names the workspace layer "workspace": -:: +working and by default names the workspace layer "workspace":: $ devtool create-workspace You can create a workspace layer anywhere by supplying a pathname with the command. The following command creates a new workspace layer named -"new-workspace": -:: +"new-workspace":: $ devtool create-workspace /home/scottrif/new-workspace @@ -603,15 +588,13 @@ Use the ``devtool status`` command to list the recipes currently in your workspace. Information includes the paths to their respective external source trees. -The ``devtool status`` command has no command-line options: -:: +The ``devtool status`` command has no command-line options:: $ devtool status Following 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: -:: +to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory:: $ devtool status mtr:/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) diff --git a/poky/documentation/ref-manual/faq.rst b/poky/documentation/ref-manual/faq.rst index 64fdfdf75..640ef77d0 100644 --- a/poky/documentation/ref-manual/faq.rst +++ b/poky/documentation/ref-manual/faq.rst @@ -108,10 +108,10 @@ the team can place sources there so builds continue to work. but the package is being marked as machine-specific in all cases, how do I prevent this? -**A:** Set ``SRC_URI_OVERRIDES_PACKAGE_ARCH`` = "0" in the ``.bb`` file +**A:** Set :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` = "0" in the ``.bb`` file but make sure the package is manually marked as machine-specific for the case that needs it. The code that handles -``SRC_URI_OVERRIDES_PACKAGE_ARCH`` is in the +:term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` is in the ``meta/classes/base.bbclass`` file. **Q:** I'm behind a firewall and need to use a proxy server. How do I do @@ -125,7 +125,7 @@ file. Following 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: :: +To use them, remove the comments:: # You can set the default proxies for Wget to use for http, https, and ftp. # They will override the value in the environment. @@ -209,8 +209,7 @@ section in the Yocto Project Development Tasks Manual. **A:** You need to create a form factor file as described in the ":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in the Yocto Project Board Support Packages (BSP) Developer's Guide. Set -the ``HAVE_TOUCHSCREEN`` variable equal to one as follows: -:: +the ``HAVE_TOUCHSCREEN`` variable equal to one as follows:: HAVE_TOUCHSCREEN=1 @@ -224,7 +223,7 @@ to add a BSP-specific netbase that includes an interfaces file. See the the Yocto Project Board Support Packages (BSP) Developer's Guide for information on creating these types of miscellaneous recipe files. -For example, add the following files to your layer: :: +For example, add the following files to your layer:: meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend @@ -251,7 +250,7 @@ size, you need to set various configurations: :term:`IMAGE_ROOTFS_EXTRA_SPACE` variable to add additional free space to the image. The build system adds this space to the image after it determines its - ``IMAGE_ROOTFS_SIZE``. + :term:`IMAGE_ROOTFS_SIZE`. **Q:** Why don't you support directories with spaces in the pathnames? @@ -263,11 +262,11 @@ situation changes, the team will not support spaces in pathnames. **Q:** How do I use an external toolchain? **A:** The toolchain configuration is very flexible and customizable. It -is primarily controlled with the ``TCMODE`` variable. This variable +is primarily controlled with the :term:`TCMODE` variable. This variable controls which ``tcmode-*.inc`` file to include from the ``meta/conf/distro/include`` directory within the :term:`Source Directory`. -The default value of ``TCMODE`` is "default", which tells the +The default value of :term:`TCMODE` is "default", which tells the OpenEmbedded build system to use its internally built toolchain (i.e. ``tcmode-default.inc``). However, other patterns are accepted. In particular, "external-\*" refers to external toolchains. One example is @@ -300,7 +299,7 @@ fail. As an example, you could add a specific server for the build system to attempt before any others by adding something like the following to the -``local.conf`` configuration file: :: +``local.conf`` configuration file:: PREMIRRORS_prepend = "\ git://.*/.* http://www.yoctoproject.org/sources/ \n \ @@ -313,8 +312,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. -Aside from the previous technique, these options also exist: -:: +Here are other options:: BB_NO_NETWORK = "1" @@ -322,17 +320,15 @@ This statement tells BitBake to issue an error instead of trying to access the Internet. This technique is useful if you want to ensure code builds only from local sources. -Here is another technique: -:: +Here is another technique:: BB_FETCH_PREMIRRORONLY = "1" This statement -limits the build system to pulling source from the ``PREMIRRORS`` only. +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 another technique:: BB_GENERATE_MIRROR_TARBALLS = "1" @@ -343,7 +339,7 @@ however, the technique can simply waste time during the build. Finally, consider an example where you are behind an HTTP-only firewall. You could make the following changes to the ``local.conf`` configuration -file as long as the ``PREMIRRORS`` server is current: :: +file as long as the :term:`PREMIRRORS` server is current:: PREMIRRORS_prepend = "\ ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ @@ -353,7 +349,7 @@ file as long as the ``PREMIRRORS`` server is current: :: These changes would cause the build system to successfully fetch source over HTTP and any network accesses to anything other than the -``PREMIRRORS`` would fail. +:term:`PREMIRRORS` would fail. The build system also honors the standard shell environment variables ``http_proxy``, ``ftp_proxy``, ``https_proxy``, and ``all_proxy`` to diff --git a/poky/documentation/ref-manual/features.rst b/poky/documentation/ref-manual/features.rst index 89c06eb65..ded653221 100644 --- a/poky/documentation/ref-manual/features.rst +++ b/poky/documentation/ref-manual/features.rst @@ -10,10 +10,10 @@ can select, and a reference on feature backfilling. Features provide a mechanism for working out which packages should be included in the generated images. Distributions can select which -features they want to support through the ``DISTRO_FEATURES`` variable, +features they want to support through the :term:`DISTRO_FEATURES` variable, which is set or appended to in a distribution's configuration file such as ``poky.conf``, ``poky-tiny.conf``, ``poky-lsb.conf`` and so forth. -Machine features are set in the ``MACHINE_FEATURES`` variable, which is +Machine features are set in the :term:`MACHINE_FEATURES` variable, which is set in the machine configuration file and specifies the hardware features for a given machine. @@ -26,8 +26,7 @@ One method you can use to determine which recipes are checking to see if a particular feature is contained or not is to ``grep`` through the :term:`Metadata` for the feature. Here is an example that discovers the recipes whose build is potentially changed based on a -given feature: -:: +given feature:: $ cd poky $ git grep 'contains.*MACHINE_FEATURES.*feature' @@ -197,7 +196,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. -The following image features are available for all images: +Here are the image features available for all images: - *allow-empty-password:* Allows Dropbear and OpenSSH to accept root logins and logins from accounts having an empty password string. @@ -268,7 +267,7 @@ these valid features is as follows: - *ssh-server-openssh:* Installs the OpenSSH SSH server, which is more full-featured than Dropbear. Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server are present in - ``IMAGE_FEATURES``, then OpenSSH will take precedence and Dropbear + :term:`IMAGE_FEATURES`, then OpenSSH will take precedence and Dropbear will not be installed. - *tools-debug:* Installs debugging tools such as ``strace`` and @@ -324,27 +323,27 @@ Here are two examples to help illustrate feature backfilling: - *The "pulseaudio" distro feature option*: Previously, PulseAudio support was enabled within the Qt and GStreamer frameworks. Because of this, the feature is backfilled and thus enabled for all distros - through the ``DISTRO_FEATURES_BACKFILL`` variable in the + through the :term:`DISTRO_FEATURES_BACKFILL` variable in the ``meta/conf/bitbake.conf`` file. However, your distro needs to disable the feature. You can disable the feature without affecting other existing distro configurations that need PulseAudio support by - adding "pulseaudio" to ``DISTRO_FEATURES_BACKFILL_CONSIDERED`` in + adding "pulseaudio" to :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` in your distro's ``.conf`` file. Adding the feature to this variable - when it also exists in the ``DISTRO_FEATURES_BACKFILL`` variable + when it also exists in the :term:`DISTRO_FEATURES_BACKFILL` variable prevents the build system from adding the feature to your - configuration's ``DISTRO_FEATURES``, effectively disabling the + configuration's :term:`DISTRO_FEATURES`, effectively disabling the feature for that particular distro. - *The "rtc" machine feature option*: Previously, real time clock (RTC) support was enabled for all target devices. Because of this, the feature is backfilled and thus enabled for all machines through the - ``MACHINE_FEATURES_BACKFILL`` variable in the + :term:`MACHINE_FEATURES_BACKFILL` variable in the ``meta/conf/bitbake.conf`` file. However, your target device does not have this capability. You can disable RTC support for your device without affecting other machines that need RTC support by adding the - feature to your machine's ``MACHINE_FEATURES_BACKFILL_CONSIDERED`` + feature to your machine's :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` list in the machine's ``.conf`` file. Adding the feature to this - variable when it also exists in the ``MACHINE_FEATURES_BACKFILL`` + variable when it also exists in the :term:`MACHINE_FEATURES_BACKFILL` variable prevents the build system from adding the feature to your - configuration's ``MACHINE_FEATURES``, effectively disabling RTC + configuration's :term:`MACHINE_FEATURES`, effectively disabling RTC support for that particular machine. diff --git a/poky/documentation/ref-manual/images.rst b/poky/documentation/ref-manual/images.rst index cf5cc1109..c6a7239c7 100644 --- a/poky/documentation/ref-manual/images.rst +++ b/poky/documentation/ref-manual/images.rst @@ -18,8 +18,7 @@ image you want. are going to build an image using non-GPLv3 and similarly licensed components, you must make the following changes in the ``local.conf`` file before using the BitBake command to build the minimal or base - image: - :: + image:: 1. Comment out the EXTRA_IMAGE_FEATURES line 2. Set INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" @@ -27,7 +26,7 @@ image you want. From within the ``poky`` Git repository, you can use the following command to display the list of directories within the :term:`Source Directory` -that contain image recipe files: :: +that contain image recipe files:: $ ls meta*/recipes*/images/*.bb @@ -47,10 +46,6 @@ Following is a list of supported recipes: - ``core-image-base``: A console-only image that fully supports the target device hardware. -- ``core-image-clutter``: An image with support for the Open GL-based - toolkit Clutter, which enables development of rich and animated - graphical user interfaces. - - ``core-image-full-cmdline``: A console-only image with more full-featured Linux system functionality installed. diff --git a/poky/documentation/ref-manual/index.rst b/poky/documentation/ref-manual/index.rst index deb0383cf..5cf10c5c2 100644 --- a/poky/documentation/ref-manual/index.rst +++ b/poky/documentation/ref-manual/index.rst @@ -13,7 +13,6 @@ Yocto Project Reference Manual system-requirements terms release-process - migration structure classes tasks diff --git a/poky/documentation/ref-manual/kickstart.rst b/poky/documentation/ref-manual/kickstart.rst index b87cdc13b..a7443f9ea 100644 --- a/poky/documentation/ref-manual/kickstart.rst +++ b/poky/documentation/ref-manual/kickstart.rst @@ -30,8 +30,7 @@ Command: part or partition ========================== Either of these commands creates a partition on the system and uses the -following syntax: -:: +following syntax:: part [mntpoint] partition [mntpoint] @@ -59,8 +58,7 @@ must also provide one of the ``--ondrive``, ``--ondisk``, or versions of these application are currently excluded. Here is an example that uses "/" as the mountpoint. The command uses -``--ondisk`` to force the partition onto the ``sdb`` disk: -:: +``--ondisk`` to force the partition onto the ``sdb`` disk:: part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 @@ -108,13 +106,15 @@ the ``part`` and ``partition`` commands: - ``--fstype``: Sets the file system type for the partition. Valid values are: - - ``ext4`` + - ``btrfs`` - - ``ext3`` + - ``erofs`` - ``ext2`` - - ``btrfs`` + - ``ext3`` + + - ``ext4`` - ``squashfs`` @@ -212,5 +212,5 @@ supports the following options: - ``--configfile``: Specifies a user-defined configuration file for the bootloader. You can provide a full pathname for the file or a - file that exists in the ``canned-wks`` folder. This option overrides + file located in the ``canned-wks`` folder. This option overrides all other bootloader options. diff --git a/poky/documentation/ref-manual/qa-checks.rst b/poky/documentation/ref-manual/qa-checks.rst index 6cb767d93..a105acc2c 100644 --- a/poky/documentation/ref-manual/qa-checks.rst +++ b/poky/documentation/ref-manual/qa-checks.rst @@ -88,7 +88,7 @@ Errors and Warnings A file-level dependency has been identified from the specified package on the specified files, but there is no explicit corresponding entry in :term:`RDEPENDS`. If - particular files are required at runtime then ``RDEPENDS`` should be + particular files are required at runtime then :term:`RDEPENDS` should be declared in the recipe to ensure the packages providing them are built. @@ -97,14 +97,14 @@ Errors and Warnings - ``<packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps]`` - A runtime dependency exists between the two specified packages, but + There is a runtime dependency between the two specified packages, but there is nothing explicit within the recipe to enable the OpenEmbedded build system to ensure that dependency is satisfied. This condition is usually triggered by an :term:`RDEPENDS` value being added at the packaging stage rather than up front, which is usually automatic based on the contents of the package. In most cases, you should change the recipe - to add an explicit ``RDEPENDS`` for the dependency. + to add an explicit :term:`RDEPENDS` for the dependency. .. _qa-check-dev-so: @@ -152,7 +152,7 @@ Errors and Warnings not explicitly add the ``.debug`` directory to the ``-dbg`` package. If this is the case, add the ``.debug`` directory explicitly to ``FILES_${PN}-dbg``. See :term:`FILES` for additional - information on ``FILES``. + information on :term:`FILES`. .. _qa-check-arch: @@ -221,8 +221,7 @@ Errors and Warnings Typically, the way to solve this performance issue is to add "-fPIC" or "-fpic" to the compiler command-line options. For example, given software that reads :term:`CFLAGS` when you build it, - you could add the following to your recipe: - :: + you could add the following to your recipe:: CFLAGS_append = " -fPIC " @@ -236,12 +235,11 @@ Errors and Warnings This indicates that binaries produced when building the recipe have not been linked with the :term:`LDFLAGS` options - provided by the build system. Check to be sure that the ``LDFLAGS`` + provided by the build system. Check to be sure that the :term:`LDFLAGS` variable is being passed to the linker command. A common workaround - for this situation is to pass in ``LDFLAGS`` using + for this situation is to pass in :term:`LDFLAGS` using :term:`TARGET_CC_ARCH` within the recipe as - follows: - :: + follows:: TARGET_CC_ARCH += "${LDFLAGS}" @@ -265,8 +263,7 @@ Errors and Warnings The ``/usr/share/info/dir`` should not be packaged. Add the following line to your :ref:`ref-tasks-install` task or to your - ``do_install_append`` within the recipe as follows: - :: + ``do_install_append`` within the recipe as follows:: rm ${D}${infodir}/dir @@ -306,7 +303,7 @@ Errors and Warnings - ``<packagename> rdepends on <debug_packagename> [debug-deps]`` - A dependency exists between the specified non-dbg package (i.e. a + There is a dependency between the specified non-dbg package (i.e. a package whose name does not end in ``-dbg``) and a package that is a ``dbg`` package. The ``dbg`` packages contain debug symbols and are brought in using several different methods: @@ -329,7 +326,7 @@ Errors and Warnings - ``<packagename> rdepends on <dev_packagename> [dev-deps]`` - A dependency exists between the specified non-dev package (a package + There is a dependency between the specified non-dev package (a package whose name does not end in ``-dev``) and a package that is a ``dev`` package. The ``dev`` packages contain development headers and are usually brought in using several different methods: @@ -406,7 +403,7 @@ Errors and Warnings If your recipe name does not match this, or you add packages to :term:`PACKAGES` that do not conform to the convention, then you will receive this error. Rename your recipe. Or, - if you have added a non-conforming package name to ``PACKAGES``, + if you have added a non-conforming package name to :term:`PACKAGES`, change the package name appropriately. @@ -434,13 +431,13 @@ Errors and Warnings The specified recipe has a name (:term:`PN`) value that appears in :term:`OVERRIDES`. If a recipe is named - such that its ``PN`` value matches something already in ``OVERRIDES`` - (e.g. ``PN`` happens to be the same as :term:`MACHINE` + such that its :term:`PN` value matches something already in :term:`OVERRIDES` + (e.g. :term:`PN` happens to be the same as :term:`MACHINE` or :term:`DISTRO`), it can have unexpected consequences. For example, assignments such as ``FILES_${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``. - Rename your recipe (or if ``PN`` is being set explicitly, change the - ``PN`` value) so that the conflict does not occur. See + Rename your recipe (or if :term:`PN` is being set explicitly, change the + :term:`PN` value) so that the conflict does not occur. See :term:`FILES` for additional information. @@ -467,7 +464,7 @@ Errors and Warnings This check looks for instances of setting ``DEPENDS_${PN}`` which is erroneous (:term:`DEPENDS` is a recipe-wide variable and thus it is not correct to specify it for a particular package, nor will such - an assignment actually work.) Set ``DEPENDS`` instead. + an assignment actually work.) Set :term:`DEPENDS` instead. .. _qa-check-already-stripped: @@ -502,7 +499,7 @@ Errors and Warnings Package names must appear only once in the :term:`PACKAGES` variable. You might receive this - error if you are attempting to add a package to ``PACKAGES`` that is + error if you are attempting to add a package to :term:`PACKAGES` that is already in the variable's value. @@ -526,7 +523,7 @@ Errors and Warnings in an image later on in the build process. You need to do one of the following: - - Add the files to ``FILES`` for the package you want them to appear + - Add the files to :term:`FILES` for the package you want them to appear in (e.g. ``FILES_${``\ :term:`PN`\ ``}`` for the main package). @@ -675,7 +672,7 @@ Errors and Warnings 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: - Patch to be applied: :: + Patch to be applied:: --- filename +++ filename @@ -687,7 +684,7 @@ Errors and Warnings context line 5 context line 6 - Original source code: :: + Original source code:: different context line 1 different context line 2 @@ -696,7 +693,7 @@ Errors and Warnings different context line 5 different context line 6 - Outcome (after applying patch with fuzz): :: + Outcome (after applying patch with fuzz):: different context line 1 different context line 2 @@ -716,14 +713,14 @@ Errors and Warnings *How to eliminate patch fuzz warnings* Use the ``devtool`` command as explained by the warning. First, unpack the - source into devtool workspace: :: + source into devtool workspace:: devtool modify <recipe> This will apply all of the patches, and create new commits out of them in the workspace - with the patch context updated. - Then, replace the patches in the recipe layer: :: + Then, replace the patches in the recipe layer:: devtool finish --force-patch-refresh <recipe> <layer_path> @@ -756,6 +753,6 @@ how to work with the QA checks, see the .. note:: - Please keep in mind that the QA checks exist in order to detect real + 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. diff --git a/poky/documentation/ref-manual/release-process.rst b/poky/documentation/ref-manual/release-process.rst index 93ab6ed08..ab143f7df 100644 --- a/poky/documentation/ref-manual/release-process.rst +++ b/poky/documentation/ref-manual/release-process.rst @@ -62,8 +62,10 @@ codename are likely to be compatible and thus work together. Releases are given a nominal release version as well but the codename is used in repositories for this reason. You can find information on Yocto -Project releases and codenames at -:yocto_wiki:`/Releases`. +Project releases and codenames at :yocto_wiki:`/Releases`. + +Our :doc:`/migration-guides/index` detail how to migrate from one release of +the Yocto Project to the next. Stable Release Process ====================== @@ -82,14 +84,14 @@ stable release. bug fixes and security fixes only. Policy dictates that features are not backported to a stable release. This policy means generic recipe version upgrades are unlikely to be accepted for backporting. The - exception to this policy occurs when a strong reason exists such as + exception to this policy occurs when there is a strong reason such as the fix happens to also be the preferred upstream approach. Stable release branches have strong maintenance for about a year after their initial release. Should significant issues be found for any release regardless of its age, fixes could be backported to older releases. For issues that are not backported given an older release, -Community LTS trees and branches exist where community members share +Community LTS trees and branches allow community members to share patches for older releases. However, these types of patches do not go through the same release process as do point releases. You can find more information about stable branch maintenance at @@ -164,9 +166,8 @@ repository. .. note:: - You can find all these branches in the Yocto Project - Source Repositories - . + You can find all these branches in the + :ref:`overview-manual/development-environment:yocto project source repositories`. Testing within these public branches ensures in a publicly visible way that all of the main supposed architectures and recipes in OE-Core diff --git a/poky/documentation/ref-manual/resources.rst b/poky/documentation/ref-manual/resources.rst index 663f0d96d..5ffd2b399 100644 --- a/poky/documentation/ref-manual/resources.rst +++ b/poky/documentation/ref-manual/resources.rst @@ -10,7 +10,7 @@ Introduction ============ The Yocto Project team is happy for people to experiment with the Yocto -Project. A number of places exist to find help if you run into +Project. There is a number of places where you can find help if you run into difficulties or find bugs. This presents information about contributing and participating in the Yocto Project. @@ -43,8 +43,7 @@ the Yocto Project itself (e.g. when discovering an issue with some component of the build system that acts contrary to the documentation or your expectations). -A general procedure and guidelines exist for when you use Bugzilla to -submit a bug. For information on how to use Bugzilla to submit a bug +For a general procedure and guidelines on how to use Bugzilla to submit a bug against the Yocto Project, see the following: - The ":ref:`dev-manual/common-tasks:submitting a defect against the yocto project`" @@ -59,7 +58,7 @@ For information on Bugzilla in general, see https://www.bugzilla.org/about/. Mailing lists ============= -A number of mailing lists maintained by the Yocto Project exist as well +There are multiple mailing lists maintained by the Yocto Project as well as related OpenEmbedded mailing lists for discussion, patch submission and announcements. To subscribe to one of the following mailing lists, click on the appropriate URL in the following list and follow the @@ -156,9 +155,8 @@ Here is a list of resources you might find helpful: - :yocto_docs:`Yocto Project Mega-Manual </singleindex.html>`\ *:* This manual is simply a single HTML file comprised of the bulk of the Yocto - Project manuals. The Mega-Manual primarily exists as a vehicle by - which you can easily search for phrases and terms used in the Yocto - Project documentation set. + Project manuals. It makes it easy to search for phrases and terms used + in the Yocto Project documentation set. - :doc:`/profile-manual/index` *:* This manual presents a set of common and generally useful tracing and profiling schemes along with diff --git a/poky/documentation/ref-manual/structure.rst b/poky/documentation/ref-manual/structure.rst index 0f2093a8d..5f00edb06 100644 --- a/poky/documentation/ref-manual/structure.rst +++ b/poky/documentation/ref-manual/structure.rst @@ -38,7 +38,7 @@ usually matches the current stable BitBake release from the BitBake project. BitBake, a :term:`Metadata` interpreter, reads the Yocto Project Metadata and runs the tasks defined by that data. Failures are usually caused by errors in your Metadata and not from BitBake -itself; consequently, most users do not need to worry about BitBake. +itself. When you run the ``bitbake`` command, the main BitBake executable (which resides in the ``bitbake/bin/`` directory) starts. Sourcing the @@ -153,8 +153,7 @@ When you run this script, your Yocto Project environment is set up, a :term:`Build Directory` is created, your working directory becomes the Build Directory, and you are presented with some simple suggestions as to what to do next, including a list of some -possible targets to build. Here is an example: -:: +possible targets to build. Here is an example:: $ source oe-init-build-env @@ -185,8 +184,7 @@ creates the ``build/`` directory in your current working directory. If you provide a Build Directory argument when you ``source`` the script, you direct the OpenEmbedded build system to create a Build Directory of your choice. For example, the following command creates a Build -Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`: -:: +Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`:: $ source oe-init-build-env ~/mybuilds @@ -253,9 +251,9 @@ variables are hard-coded for various reasons but such variables are relatively rare. At a minimum, you would normally edit this file to select the target -``MACHINE``, which package types you wish to use +:term:`MACHINE`, which package types you wish to use (:term:`PACKAGE_CLASSES`), and the location from -which you want to access downloaded files (``DL_DIR``). +which you want to access downloaded files (:term:`DL_DIR`). If ``local.conf`` is not present when you start the build, the OpenEmbedded build system creates it from ``local.conf.sample`` when you @@ -269,8 +267,7 @@ and to ``meta/conf/`` when you are building from the OpenEmbedded-Core environment. Because the script variable points to the source of the ``local.conf.sample`` file, this implies that you can configure your build environment from any layer by setting the variable in the -top-level build environment setup script as follows: -:: +top-level build environment setup script as follows:: TEMPLATECONF=your_layer/conf @@ -282,7 +279,7 @@ file, it uses ``sed`` to substitute final .. note:: You can see how the ``TEMPLATECONF`` variable is used by looking at the - ``scripts/oe-setup-builddir``` script in the :term:`Source Directory`. + ``scripts/oe-setup-builddir`` script in the :term:`Source Directory`. You can find the Yocto Project version of the ``local.conf.sample`` file in the ``meta-poky/conf`` directory. @@ -309,8 +306,7 @@ Project development environment, and to ``meta/conf/`` when you are building from the OpenEmbedded-Core environment. Because the script variable points to the source of the ``bblayers.conf.sample`` file, this implies that you can base your build from any layer by setting the -variable in the top-level build environment setup script as follows: -:: +variable in the top-level build environment setup script as follows:: TEMPLATECONF=your_layer/conf @@ -340,7 +336,7 @@ the build. This directory contains downloaded upstream source tarballs. You can reuse the directory for multiple builds or move the directory to another location. You can control the location of this directory through the -``DL_DIR`` variable. +:term:`DL_DIR` variable. .. _structure-build-sstate-cache: @@ -350,7 +346,7 @@ location. You can control the location of this directory through the This directory contains the shared state cache. You can reuse the directory for multiple builds or move the directory to another location. You can control the location of this directory through the -``SSTATE_DIR`` variable. +:term:`SSTATE_DIR` variable. .. _structure-build-tmp: @@ -463,8 +459,7 @@ image again. If you do accidentally delete files here, you will need to force them to be re-created. In order to do that, you will need to know the target that produced them. For example, these commands rebuild and re-create -the kernel files: -:: +the kernel files:: $ bitbake -c clean virtual/kernel $ bitbake virtual/kernel @@ -515,8 +510,8 @@ should be automatic, and recipes should not directly reference ----------------------- Previous versions of the OpenEmbedded build system used to create a -global shared sysroot per machine along with a native sysroot. Beginning -with the 2.3 version of the Yocto Project, sysroots exist in +global shared sysroot per machine along with a native sysroot. Since +the 2.3 version of the Yocto Project, there are sysroots in recipe-specific :term:`WORKDIR` directories. Thus, the ``build/tmp/sysroots/`` directory is unused. @@ -535,8 +530,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: -:: +Following is an example:: stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do @@ -554,7 +548,7 @@ section in the Yocto Project Overview and Concepts Manual. ------------------ This directory contains general logs that are not otherwise placed using -the package's ``WORKDIR``. Examples of logs are the output from the +the package's :term:`WORKDIR`. Examples of logs are the output from the ``do_check_pkg`` or ``do_distro_check`` tasks. Running a build does not necessarily mean this directory is created. @@ -575,7 +569,7 @@ It is worth considering the structure of a typical work directory. As an example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86`` built within the Yocto Project. For this package, a work directory of ``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred -to as the ``WORKDIR``, is created. Within this directory, the source is +to as the :term:`WORKDIR`, is created. Within this directory, the source is unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt. (See the ":ref:`dev-manual/common-tasks:using quilt in your workflow`" section in the Yocto Project Development Tasks Manual for more information.) Within @@ -583,7 +577,7 @@ the ``linux-qemux86-standard-build`` directory, standard Quilt directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and standard Quilt commands can be used. -There are other directories generated within ``WORKDIR``. The most +There are other directories generated within :term:`WORKDIR`. The most important directory is ``WORKDIR/temp/``, which has log files for each task (``log.do_*.pid``) and contains the scripts BitBake runs for each task (``run.do_*.pid``). The ``WORKDIR/image/`` directory is where "make @@ -607,7 +601,7 @@ constructed using the architecture of the given build (e.g. name, and the version of the recipe (i.e. :term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`). -A number of key subdirectories exist within each recipe work directory: +Here are key subdirectories within each recipe work directory: - ``${WORKDIR}/temp``: Contains the log files of each task executed for this recipe, the "run" files for each executed task, which contain @@ -630,7 +624,7 @@ A number of key subdirectories exist within each recipe work directory: - ``${WORKDIR}/packages-split``: Contains the output of the ``do_package`` task after the output has been split into individual - packages. Subdirectories exist for each individual package created by + packages. There are subdirectories for each individual package created by the recipe. - ``${WORKDIR}/recipe-sysroot``: A directory populated with the target @@ -715,7 +709,7 @@ support for a new machine to the Yocto Project, look in this directory. The contents of this directory controls any distribution-specific configurations. For the Yocto Project, the ``defaultsetup.conf`` is the -main file here. This directory includes the versions and the ``SRCDATE`` +main file here. This directory includes the versions and the :term:`SRCDATE` definitions for applications that are configured here. An example of an alternative configuration might be ``poky-bleeding.conf``. Although this file mainly inherits its configuration from Poky. @@ -789,7 +783,7 @@ system. The tools, however, can also be used on targets. This directory contains non-essential applications that add features compared to the alternatives in core. You might need this directory for -full tool functionality or for Linux Standard Base (LSB) compliance. +full tool functionality. .. _structure-meta-recipes-gnome: @@ -815,14 +809,6 @@ libraries. This directory contains the kernel and generic applications and libraries that have strong kernel dependencies. -.. _structure-meta-recipes-lsb4: - -``meta/recipes-lsb4/`` ----------------------- - -This directory contains recipes specifically added to support the Linux -Standard Base (LSB) version 4.x. - .. _structure-meta-recipes-multimedia: ``meta/recipes-multimedia/`` diff --git a/poky/documentation/ref-manual/system-requirements.rst b/poky/documentation/ref-manual/system-requirements.rst index 80378cedb..e9d995c61 100644 --- a/poky/documentation/ref-manual/system-requirements.rst +++ b/poky/documentation/ref-manual/system-requirements.rst @@ -41,7 +41,7 @@ distributions: - Ubuntu 18.04 (LTS) -- Ubuntu 20.04 +- Ubuntu 20.04 (LTS) - Fedora 30 @@ -66,9 +66,8 @@ distributions: - While the Yocto Project Team attempts to ensure all Yocto Project releases are one hundred percent compatible with each officially - supported Linux distribution, instances might exist where you - encounter a problem while using the Yocto Project on a specific - distribution. + supported Linux distribution, you may still encounter problems + that happen only with a specific distribution. - Yocto Project releases are tested against the stable Linux distributions in the above list. The Yocto Project should work @@ -111,7 +110,7 @@ function. Ubuntu and Debian ----------------- -The following list shows the required packages by function given a +Here are the required packages by function given a supported Ubuntu or Debian Linux distribution: .. note:: @@ -119,9 +118,7 @@ supported Ubuntu or Debian Linux distribution: - If your build system has the ``oss4-dev`` package installed, you might experience QEMU build failures due to the package installing its own custom ``/usr/include/linux/soundcard.h`` on the Debian - system. If you run into this situation, either of the following - solutions exist: - :: + system. If you run into this situation, try either of these solutions:: $ sudo apt-get build-dep qemu $ sudo apt-get remove oss4-dev @@ -132,14 +129,12 @@ supported Ubuntu or Debian Linux distribution: $ sudo pip3 install GitPython pylint==1.9.5 -- *Essentials:* Packages needed to build an image on a headless system: - :: +- *Essentials:* Packages needed to build an image on a headless system:: $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; - *Documentation:* Packages needed if you are going to build out the - Yocto Project documentation manuals: - :: + Yocto Project documentation manuals:: $ sudo apt-get install make python3-pip &PIP3_HOST_PACKAGES_DOC; @@ -153,18 +148,16 @@ supported Ubuntu or Debian Linux distribution: Fedora Packages --------------- -The following list shows the required packages by function given a +Here are the required packages by function given a supported Fedora Linux distribution: - *Essentials:* Packages needed to build an image for a headless - system: - :: + system:: $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; - *Documentation:* Packages needed if you are going to build out the - Yocto Project documentation manuals: - :: + Yocto Project documentation manuals:: $ sudo dnf install make python3-pip which &PIP3_HOST_PACKAGES_DOC; @@ -172,18 +165,16 @@ supported Fedora Linux distribution: openSUSE Packages ----------------- -The following list shows the required packages by function given a +Here are the required packages by function given a supported openSUSE Linux distribution: - *Essentials:* Packages needed to build an image for a headless - system: - :: + system:: $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; - *Documentation:* Packages needed if you are going to build out the - Yocto Project documentation manuals: - :: + Yocto Project documentation manuals:: $ sudo zypper install make python3-pip which &PIP3_HOST_PACKAGES_DOC; @@ -192,12 +183,11 @@ supported openSUSE Linux distribution: CentOS-7 Packages ----------------- -The following list shows the required packages by function given a +Here are the required packages by function given a supported CentOS-7 Linux distribution: - *Essentials:* Packages needed to build an image for a headless - system: - :: + system:: $ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL; @@ -212,8 +202,7 @@ supported CentOS-7 Linux distribution: ``epel-release``. - *Documentation:* Packages needed if you are going to build out the - Yocto Project documentation manuals: - :: + Yocto Project documentation manuals:: $ sudo yum install make python3-pip which &PIP3_HOST_PACKAGES_DOC; @@ -221,12 +210,11 @@ supported CentOS-7 Linux distribution: CentOS-8 Packages ----------------- -The following list shows the required packages by function given a +Here are the required packages by function given a supported CentOS-8 Linux distribution: - *Essentials:* Packages needed to build an image for a headless - system: - :: + system:: $ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL; @@ -244,8 +232,7 @@ supported CentOS-8 Linux distribution: ``epel-release``. - *Documentation:* Packages needed if you are going to build out the - Yocto Project documentation manuals: - :: + Yocto Project documentation manuals:: $ sudo dnf install make python3-pip which &PIP3_HOST_PACKAGES_DOC; @@ -287,8 +274,7 @@ The ``install-buildtools`` script is the easiest of the three methods by which you can get these tools. It downloads a pre-built buildtools installer and automatically installs the tools for you: -1. Execute the ``install-buildtools`` script. Here is an example: - :: +1. Execute the ``install-buildtools`` script. Here is an example:: $ cd poky $ scripts/install-buildtools --without-extended-buildtools \ @@ -302,22 +288,19 @@ installer and automatically installs the tools for you: installation is functional. To avoid the need of ``sudo`` privileges, the ``install-buildtools`` - script will by default tell the installer to install in: - :: + script will by default tell the installer to install in:: /path/to/poky/buildtools If your host development system needs the additional tools provided in the ``buildtools-extended`` tarball, you can instead execute the - ``install-buildtools`` script with the default parameters: - :: + ``install-buildtools`` script with the default parameters:: $ cd poky $ scripts/install-buildtools 2. Source the tools environment setup script by using a command like the - following: - :: + following:: $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux @@ -342,13 +325,11 @@ steps: 1. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/ 2. Execute the installation script. Here is an example for the - traditional installer: - :: + traditional installer:: $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh - Here is an example for the extended installer: - :: + Here is an example for the extended installer:: $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh @@ -357,8 +338,7 @@ steps: ``/home/your-username/buildtools`` 3. Source the tools environment setup script by using a command like the - following: - :: + following:: $ source /home/your_username/buildtools/environment-setup-i586-poky-linux @@ -390,13 +370,11 @@ installer: your build environment with the setup script (:ref:`structure-core-script`). -2. Run the BitBake command to build the tarball: - :: +2. Run the BitBake command to build the tarball:: $ bitbake buildtools-tarball - or run the BitBake command to build the extended tarball: - :: + or run the BitBake command to build the extended tarball:: $ bitbake buildtools-extended-tarball @@ -415,13 +393,11 @@ installer: 4. On the machine that does not meet the requirements, run the ``.sh`` file to install the tools. Here is an example for the traditional - installer: - :: + installer:: $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh - Here is an example for the extended installer: - :: + Here is an example for the extended installer:: $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh @@ -430,8 +406,7 @@ installer: ``/home/your_username/buildtools`` 5. Source the tools environment setup script by using a command like the - following: - :: + following:: $ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux diff --git a/poky/documentation/ref-manual/tasks.rst b/poky/documentation/ref-manual/tasks.rst index 9fe1c296a..970b08394 100644 --- a/poky/documentation/ref-manual/tasks.rst +++ b/poky/documentation/ref-manual/tasks.rst @@ -57,7 +57,7 @@ the current working directory set to ``${``\ :term:`B`\ ``}``. 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 ``CLEANBROKEN`` variable is set to "1", the +file is found or the :term:`CLEANBROKEN` variable is set to "1", the ``do_configure`` task does nothing. .. _ref-tasks-configure_ptest_base: @@ -93,8 +93,7 @@ output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``. The ``do_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: -:: +the following:: addtask deploy after do_compile @@ -103,8 +102,7 @@ Adding ``do_deploy`` after other tasks works the same way. .. note:: You do not need to add ``before do_build`` to the ``addtask`` command - (though it is harmless), because the ``base`` class contains the following: - :: + (though it is harmless), because the ``base`` class contains the following:: do_build[recrdeptask] += "do_deploy" @@ -302,29 +300,26 @@ Patch files, by default, are ``*.patch`` and ``*.diff`` files created and kept in a subdirectory of the directory holding the recipe file. For example, consider the :yocto_git:`bluez5 </poky/tree/meta/recipes-connectivity/bluez5>` -recipe from the OE-Core layer (i.e. ``poky/meta``): -:: +recipe from the OE-Core layer (i.e. ``poky/meta``):: poky/meta/recipes-connectivity/bluez5 -This recipe has two patch files located here: -:: +This recipe has two patch files located here:: poky/meta/recipes-connectivity/bluez5/bluez5 -In the ``bluez5`` recipe, the ``SRC_URI`` statements point to the source +In the ``bluez5`` recipe, the :term:`SRC_URI` statements point to the source and patch files needed to build the package. .. note:: - In the case for the ``bluez5_5.48.bb`` recipe, the ``SRC_URI`` statements + In the case for the ``bluez5_5.48.bb`` recipe, the :term:`SRC_URI` statements are from an include file ``bluez5.inc``. As mentioned earlier, the build system treats files whose file types are ``.patch`` and ``.diff`` as patch files. However, you can use the -"apply=yes" parameter with the ``SRC_URI`` statement to indicate any -file as a patch file: -:: +"apply=yes" parameter with the :term:`SRC_URI` statement to indicate any +file as a patch file:: SRC_URI = " \ git://path_to_repo/some_package \ @@ -334,8 +329,7 @@ file as a patch file: Conversely, if you have a directory full of patch files and you want to exclude some so that the ``do_patch`` task does not apply them during the patch phase, you can use the "apply=no" parameter with the -``SRC_URI`` statement: -:: +:term:`SRC_URI` statement:: SRC_URI = " \ git://path_to_repo/some_package \ @@ -436,7 +430,7 @@ variable also plays a role in where unpacked source files ultimately reside. For more information on how source files are unpacked, see the ":ref:`overview-manual/concepts:source fetching`" section in the Yocto Project Overview and Concepts Manual and also see -the ``WORKDIR`` and ``S`` variable descriptions. +the :term:`WORKDIR` and :term:`S` variable descriptions. Manually Called Tasks ===================== @@ -455,8 +449,7 @@ of the recipe exists upstream and a status of not updated, updated, or unknown. To check the upstream version and status of a recipe, use the following -devtool commands: -:: +devtool commands:: $ devtool latest-version $ devtool check-upgrade-status @@ -467,8 +460,7 @@ chapter for more information on section for information on checking the upgrade status of a recipe. To build the ``checkpkg`` task, use the ``bitbake`` command with the -"-c" option and task name: -:: +"-c" option and task name:: $ bitbake core-image-minimal -c checkpkg @@ -494,8 +486,7 @@ Removes all output files for a target from the :ref:`ref-tasks-install`, and :ref:`ref-tasks-package`). -You can run this task using BitBake as follows: -:: +You can run this task using BitBake as follows:: $ bitbake -c clean recipe @@ -519,8 +510,7 @@ downloaded source files for a target (i.e. the contents of identical to the :ref:`ref-tasks-cleansstate` task with the added removal of downloaded source files. -You can run this task using BitBake as follows: -:: +You can run this task using BitBake as follows:: $ bitbake -c cleanall recipe @@ -540,8 +530,7 @@ target. Essentially, the ``do_cleansstate`` task is identical to the shared state (:ref:`sstate <overview-manual/concepts:shared state cache>`) cache. -You can run this task using BitBake as follows: -:: +You can run this task using BitBake as follows:: $ bitbake -c cleansstate recipe @@ -553,8 +542,7 @@ scratch is guaranteed. The ``do_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: - :: + the "-f" option as follows:: $ bitbake -f -c do_cleansstate target @@ -687,8 +675,7 @@ changes made by the user with other methods (i.e. using (:ref:`ref-tasks-kernel_menuconfig`). Once the file of differences is created, it can be used to create a config fragment that only contains the differences. You can invoke this task -from the command line as follows: -:: +from the command line as follows:: $ bitbake linux-yocto -c diffconfig @@ -718,8 +705,7 @@ Validates the configuration produced by the 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 -following command: -:: +following command:: $ bitbake linux-yocto -c kernel_configcheck -f @@ -750,8 +736,7 @@ tool, which you then use to modify the kernel configuration. .. note:: - You can also invoke this tool from the command line as follows: - :: + You can also invoke this tool from the command line as follows:: $ bitbake linux-yocto -c menuconfig @@ -793,8 +778,7 @@ instead of the default defconfig. The saved defconfig contains the differences between the default defconfig and the changes made by the user using other methods (i.e. the :ref:`ref-tasks-kernel_menuconfig` task. You -can invoke the task using the following command: -:: +can invoke the task using the following command:: $ bitbake linux-yocto -c savedefconfig @@ -839,6 +823,5 @@ sections from a size-sensitive configuration. 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. If these branches do not exist and -:term:`AUTOREV` is not being used, the +branches. Otherwise, if :term:`AUTOREV` is not being used, the ``do_validate_branches`` task fails during the build. diff --git a/poky/documentation/ref-manual/terms.rst b/poky/documentation/ref-manual/terms.rst index 32bb75b27..54469e507 100644 --- a/poky/documentation/ref-manual/terms.rst +++ b/poky/documentation/ref-manual/terms.rst @@ -26,8 +26,7 @@ universal, the list includes them just in case: When you name an append file, you can use the "``%``" wildcard character to allow for matching recipe names. For example, suppose you have an - append file named as follows: - :: + append file named as follows:: busybox_1.21.%.bbappend @@ -98,11 +97,11 @@ universal, the list includes them just in case: .. note:: By default, the Build Directory contains :term:`TMPDIR`, which is a - temporary directory the build system uses for its work. ``TMPDIR`` cannot + temporary directory the build system uses for its work. :term:`TMPDIR` cannot be under NFS. Thus, by default, the Build Directory cannot be under NFS. However, if you need the Build Directory to be under NFS, you can - set this up by setting ``TMPDIR`` in your ``local.conf`` file to use a local - drive. Doing so effectively separates ``TMPDIR`` from :term:`TOPDIR`, which is the + set this up by setting :term:`TMPDIR` in your ``local.conf`` file to use a local + drive. Doing so effectively separates :term:`TMPDIR` from :term:`TOPDIR`, which is the Build Directory. :term:`Build Host` diff --git a/poky/documentation/ref-manual/variables.rst b/poky/documentation/ref-manual/variables.rst index 74ac12bf9..71c2e11d9 100644 --- a/poky/documentation/ref-manual/variables.rst +++ b/poky/documentation/ref-manual/variables.rst @@ -24,8 +24,7 @@ system and gives an overview of their function and contents. ABI extensions are set in the machine include files. For example, the ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the - following extension: - :: + following extension:: ABIEXTENSION = "eabi" @@ -37,8 +36,7 @@ system and gives an overview of their function and contents. requirement on the existence of the package. Like all package-controlling variables, you must always use them in - conjunction with a package name override, as in: - :: + conjunction with a package name override, as in:: ALLOW_EMPTY_${PN} = "1" ALLOW_EMPTY_${PN}-dev = "1" @@ -51,11 +49,9 @@ system and gives an overview of their function and contents. alternatives system to create a different binary naming scheme so the commands can co-exist. - To use the variable, list out the package's commands that also exist - as part of another package. For example, if the ``busybox`` package - has four commands that also exist as part of another package, you - identify them as follows: - :: + To use the variable, list out the package's commands that are also + provided by another package. For example, if the ``busybox`` package + has four such commands, you identify them as follows:: ALTERNATIVE_busybox = "sh sed test bracket" @@ -67,9 +63,8 @@ system and gives an overview of their function and contents. Used by the alternatives system to map duplicated commands to actual locations. For example, if the ``bracket`` command provided by the ``busybox`` package is duplicated through another package, you must - use the ``ALTERNATIVE_LINK_NAME`` variable to specify the actual - location: - :: + use the :term:`ALTERNATIVE_LINK_NAME` variable to specify the actual + location:: ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/[" @@ -78,7 +73,7 @@ system and gives an overview of their function and contents. .. note:: - If ``ALTERNATIVE_LINK_NAME`` is not defined, it defaults to ``${bindir}/name``. + If :term:`ALTERNATIVE_LINK_NAME` is not defined, it defaults to ``${bindir}/name``. For more information on the alternatives system, see the ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" @@ -90,8 +85,7 @@ system and gives an overview of their function and contents. default regardless of the command name or package, a default for specific duplicated commands regardless of the package, or a default for specific commands tied to particular packages. Here are the - available syntax forms: - :: + available syntax forms:: ALTERNATIVE_PRIORITY = "priority" ALTERNATIVE_PRIORITY[name] = "priority" @@ -107,8 +101,7 @@ system and gives an overview of their function and contents. default location for all duplicated commands regardless of the command name or package, a default for specific duplicated commands regardless of the package, or a default for specific commands tied to - particular packages. Here are the available syntax forms: - :: + particular packages. Here are the available syntax forms:: ALTERNATIVE_TARGET = "target" ALTERNATIVE_TARGET[name] = "target" @@ -116,11 +109,11 @@ system and gives an overview of their function and contents. .. note:: - If ``ALTERNATIVE_TARGET`` is not defined, it inherits the value + If :term:`ALTERNATIVE_TARGET` is not defined, it inherits the value from the :term:`ALTERNATIVE_LINK_NAME` variable. - If ``ALTERNATIVE_LINK_NAME`` and ``ALTERNATIVE_TARGET`` are the - same, the target for ``ALTERNATIVE_TARGET`` has "``.{BPN}``" + If :term:`ALTERNATIVE_LINK_NAME` and :term:`ALTERNATIVE_TARGET` are the + same, the target for :term:`ALTERNATIVE_TARGET` has "``.{BPN}``" appended to it. Finally, if the file referenced has not been renamed, the @@ -138,8 +131,8 @@ system and gives an overview of their function and contents. class, this variable identifies a list of distribution features where at least one must be enabled in the current configuration in order for the OpenEmbedded build system to build the recipe. In other words, - if none of the features listed in ``ANY_OF_DISTRO_FEATURES`` - appear in ``DISTRO_FEATURES`` within the current configuration, then + if none of the features listed in :term:`ANY_OF_DISTRO_FEATURES` + appear in :term:`DISTRO_FEATURES` within the current configuration, then the recipe will be skipped, and if the build system attempts to build the recipe then an error will be triggered. @@ -159,8 +152,7 @@ system and gives an overview of their function and contents. determines the type of information used to create a released archive. You can use this variable to create archives of patched source, original source, configured source, and so forth by employing the - following variable flags (varflags): - :: + following variable flags (varflags):: ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files. ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default. @@ -182,7 +174,7 @@ system and gives an overview of their function and contents. attempt to build. Instead, BitBake assumes these recipes have already been built. - In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native + In OpenEmbedded-Core, :term:`ASSUME_PROVIDED` mostly specifies native tools that should not be built. An example is ``git-native``, which when specified, allows for the Git binary from the host to be used rather than building ``git-native``. @@ -193,14 +185,12 @@ system and gives an overview of their function and contents. system. Separate multiple entries using spaces. As an example, use the following form to add an ``shlib`` provider of - shlibname in packagename with the optional version: - :: + shlibname in packagename with the optional version:: shlibname:packagename[_version] Here is an example that adds a shared library named ``libEGL.so.1`` - as being provided by the ``libegl-implementation`` package: - :: + as being provided by the ``libegl-implementation`` package:: ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation" @@ -210,7 +200,7 @@ system and gives an overview of their function and contents. :term:`AUTO_LIBNAME_PKGS` When the :ref:`debian <ref-classes-debian>` class is inherited, - which is the default behavior, ``AUTO_LIBNAME_PKGS`` specifies which + which is the default behavior, :term:`AUTO_LIBNAME_PKGS` specifies which packages should be checked for libraries and renamed according to Debian library package naming. @@ -223,9 +213,8 @@ system and gives an overview of their function and contents. :ref:`syslinux <ref-classes-syslinux>` class checks this variable. :term:`AUTOREV` - When ``SRCREV`` is set to the value of this variable, it specifies to - use the latest source revision in the repository. Here is an example: - :: + When :term:`SRCREV` is set to the value of this variable, it specifies to + use the latest source revision in the repository. Here is an example:: SRCREV = "${AUTOREV}" @@ -235,7 +224,7 @@ system and gives an overview of their function and contents. have a kernel recipe that inherits the :ref:`kernel <ref-classes-kernel>` class and you use the previous statement. In this example, ``${SRCPV}`` does not automatically get - into ``PV``. Consequently, you need to change ``PV`` in your recipe + into :term:`PV`. Consequently, you need to change :term:`PV` in your recipe so that it does contain ``${SRCPV}``. For more information see the @@ -249,8 +238,8 @@ system and gives an overview of their function and contents. .. note:: - It is assumed that all changes to ``COMMON_LICENSE_DIR`` and - ``LICENSE_PATH`` have been done before ``AVAILABLE_LICENSES`` + It is assumed that all changes to :term:`COMMON_LICENSE_DIR` and + :term:`LICENSE_PATH` have been done before :term:`AVAILABLE_LICENSES` is defined (in :ref:`ref-classes-license`). :term:`AVAILTUNES` @@ -286,12 +275,11 @@ system and gives an overview of their function and contents. The directory within the :term:`Build Directory` in which the OpenEmbedded build system places generated objects during a recipe's build process. By default, this directory is the same as the - :term:`S` directory, which is defined as: - :: + :term:`S` directory, which is defined as:: S = "${WORKDIR}/${BP}" - You can separate the (``S``) directory and the directory pointed to + You can separate the (:term:`S`) directory and the directory pointed to by the ``B`` variable. Most Autotools-based recipes support separating these directories. The build system defaults to using separate directories for ``gcc`` and some kernel recipes. @@ -301,15 +289,13 @@ system and gives an overview of their function and contents. packages are packages installed only through the :term:`RRECOMMENDS` variable. You can prevent any of these "recommended" packages from being installed by listing them - with the ``BAD_RECOMMENDATIONS`` variable: - :: + with the :term:`BAD_RECOMMENDATIONS` variable:: BAD_RECOMMENDATIONS = "package_name package_name package_name ..." You can set this variable globally in your ``local.conf`` file or you can attach it to a specific image recipe by using the recipe name - override: - :: + override:: BAD_RECOMMENDATIONS_pn-target_image = "package_name" @@ -319,8 +305,8 @@ system and gives an overview of their function and contents. variable), the OpenEmbedded build system ignores your request and will install the packages to avoid dependency errors. - Support for this variable exists only when using the IPK and RPM - packaging backend. Support does not exist for DEB. + This variable is supported only when using the IPK and RPM + packaging backends. DEB is not supported. See the :term:`NO_RECOMMENDATIONS` and the :term:`PACKAGE_EXCLUDE` variables for related @@ -328,12 +314,12 @@ system and gives an overview of their function and contents. :term:`BASE_LIB` The library directory name for the CPU or Application Binary - Interface (ABI) tune. The ``BASE_LIB`` applies only in the Multilib + Interface (ABI) tune. The :term:`BASE_LIB` applies only in the Multilib context. See the ":ref:`dev-manual/common-tasks:combining multiple versions of library files into one image`" section in the Yocto Project Development Tasks Manual for information on Multilib. - The ``BASE_LIB`` variable is defined in the machine include files in + The :term:`BASE_LIB` variable is defined in the machine include files in the :term:`Source Directory`. If Multilib is not being used, the value defaults to "lib". @@ -346,11 +332,11 @@ system and gives an overview of their function and contents. to use to obtain the required source code. Following are considerations surrounding this variable: - - This host list is only used if ``BB_NO_NETWORK`` is either not set + - This host list is only used if :term:`BB_NO_NETWORK` is either not set or set to "0". - - Limited support for wildcard matching against the beginning of - host names exists. For example, the following setting matches + - There is limited support for wildcard matching against the beginning of + host names. For example, the following setting matches ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``. :: @@ -371,14 +357,14 @@ system and gives an overview of their function and contents. - Attempts to access networks not in the host list cause a failure. - Using ``BB_ALLOWED_NETWORKS`` in conjunction with + Using :term:`BB_ALLOWED_NETWORKS` in conjunction with :term:`PREMIRRORS` is very useful. Adding the host - you want to use to ``PREMIRRORS`` results in the source code being + you want to use to :term:`PREMIRRORS` results in the source code being fetched from an allowed location and avoids raising an error when a host that is not allowed is in a :term:`SRC_URI` statement. This is because the fetcher does not attempt to use the - host listed in ``SRC_URI`` after a successful fetch from the - ``PREMIRRORS`` occurs. + host listed in :term:`SRC_URI` after a successful fetch from the + :term:`PREMIRRORS` occurs. :term:`BB_DANGLINGAPPENDS_WARNONLY` Defines how BitBake handles situations where an append file @@ -394,8 +380,7 @@ system and gives an overview of their function and contents. You can change the default behavior by setting this variable to "1", "yes", or "true" in your ``local.conf`` file, which is located in the - :term:`Build Directory`: Here is an example: - :: + :term:`Build Directory`: Here is an example:: BB_DANGLINGAPPENDS_WARNONLY = "1" @@ -404,7 +389,7 @@ system and gives an overview of their function and contents. you to control the build based on these parameters. Disk space monitoring is disabled by default. To enable monitoring, - add the ``BB_DISKMON_DIRS`` variable to your ``conf/local.conf`` file + add the :term:`BB_DISKMON_DIRS` variable to your ``conf/local.conf`` file found in the :term:`Build Directory`. Use the following form: @@ -444,8 +429,7 @@ system and gives an overview of their function and contents. not specify G, M, or K, Kbytes is assumed by default. Do not use GB, MB, or KB. - Here are some examples: - :: + Here are some examples:: BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" @@ -460,7 +444,7 @@ system and gives an overview of their function and contents. variable, the build system also issue a warning when the disk space in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number of free inodes drops below 100 Kbytes. Subsequent warnings are issued - during intervals as defined by the ``BB_DISKMON_WARNINTERVAL`` + during intervals as defined by the :term:`BB_DISKMON_WARNINTERVAL` variable. The second example stops the build after all currently executing @@ -477,16 +461,15 @@ system and gives an overview of their function and contents. intervals, define the variable in your ``conf/local.conf`` file in the :term:`Build Directory`. - If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you + If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you must also use the :term:`BB_DISKMON_DIRS` variable and define its action as "WARN". During the build, subsequent warnings are issued each time disk space or number of free inodes further reduces by the respective interval. - If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you - do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk - monitoring interval defaults to the following: - :: + If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you + do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk + monitoring interval defaults to the following:: BB_DISKMON_WARNINTERVAL = "50M,5K" @@ -509,8 +492,7 @@ system and gives an overview of their function and contents. G, M, or K for Gbytes, Mbytes, or Kbytes, respectively. You cannot use GB, MB, or KB. - Here is an example: - :: + Here is an example:: BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" BB_DISKMON_WARNINTERVAL = "50M,5K" @@ -539,7 +521,7 @@ system and gives an overview of their function and contents. ``local.conf`` file in the :term:`Build Directory`. Once you have the tarballs containing your source files, you can - clean up your ``DL_DIR`` directory by deleting any Git or other + clean up your :term:`DL_DIR` directory by deleting any Git or other source control work directories. :term:`BB_NUMBER_THREADS` @@ -547,13 +529,13 @@ system and gives an overview of their function and contents. time. The OpenEmbedded build system automatically configures this variable to be equal to the number of cores on the build system. For example, a system with a dual core processor that also uses - hyper-threading causes the ``BB_NUMBER_THREADS`` variable to default + hyper-threading causes the :term:`BB_NUMBER_THREADS` variable to default to "4". For single socket systems (i.e. one CPU), you should not have to override this variable to gain optimal parallelism during builds. However, if you have very large systems that employ multiple physical - CPUs, you might want to make sure the ``BB_NUMBER_THREADS`` variable + CPUs, you might want to make sure the :term:`BB_NUMBER_THREADS` variable is not set higher than "20". For more information on speeding up builds, see the @@ -562,12 +544,11 @@ system and gives an overview of their function and contents. :term:`BB_SERVER_TIMEOUT` Specifies the time (in seconds) after which to unload the BitBake - server due to inactivity. Set ``BB_SERVER_TIMEOUT`` to determine how + server due to inactivity. Set :term:`BB_SERVER_TIMEOUT` to determine how long the BitBake server stays resident between invocations. For example, the following statement in your ``local.conf`` file - instructs the server to be unloaded after 20 seconds of inactivity: - :: + instructs the server to be unloaded after 20 seconds of inactivity:: BB_SERVER_TIMEOUT = "20" @@ -576,30 +557,29 @@ system and gives an overview of their function and contents. :term:`BBCLASSEXTEND` Allows you to extend a recipe so that it builds variants of the - software. Common variants for recipes exist such as "natives" like + software. There are common variants for recipes as "natives" like ``quilt-native``, which is a copy of Quilt built to run on the build system; "crosses" such as ``gcc-cross``, which is a compiler built to run on the build machine but produces binaries that run on the target :term:`MACHINE`; "nativesdk", which targets the SDK - machine instead of ``MACHINE``; and "mulitlibs" in the form + machine instead of :term:`MACHINE`; and "mulitlibs" in the form "``multilib:``\ multilib_name". To build a different variant of the recipe with a minimal amount of - code, it usually is as simple as adding the following to your recipe: - :: + code, it usually is as simple as adding the following to your recipe:: BBCLASSEXTEND =+ "native nativesdk" BBCLASSEXTEND =+ "multilib:multilib_name" .. note:: - Internally, the ``BBCLASSEXTEND`` mechanism generates recipe + Internally, the :term:`BBCLASSEXTEND` mechanism generates recipe variants by rewriting variable values and applying overrides such as ``_class-native``. For example, to generate a native version of a recipe, a :term:`DEPENDS` on "foo" is rewritten to a ``DEPENDS`` on "foo-native". - Even when using ``BBCLASSEXTEND``, the recipe is only parsed once. + Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once. Parsing once adds some limitations. For example, it is not possible to include a different file depending on the variant, since ``include`` statements are processed when the recipe is @@ -625,14 +605,14 @@ system and gives an overview of their function and contents. - effectively letting you control the precedence for the multiple layers. The precedence established through this variable stands regardless of a recipe's version (:term:`PV` variable). For - example, a layer that has a recipe with a higher ``PV`` value but for - which the ``BBFILE_PRIORITY`` is set to have a lower precedence still + example, a layer that has a recipe with a higher :term:`PV` value but for + which the :term:`BBFILE_PRIORITY` is set to have a lower precedence still has a lower precedence. - A larger value for the ``BBFILE_PRIORITY`` variable results in a + A larger value for the :term:`BBFILE_PRIORITY` variable results in a higher precedence. For example, the value 6 has a higher precedence - than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable - is set based on layer dependencies (see the ``LAYERDEPENDS`` variable + than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable + is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable for more information. The default priority, if unspecified for a layer with no dependencies, is the lowest defined priority + 1 (or 1 if no priorities are defined). @@ -655,15 +635,14 @@ system and gives an overview of their function and contents. Activates content when identified layers are present. You identify the layers by the collections that the layers define. - Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files + Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files whose corresponding ``.bb`` file is in a layer that attempts to modify other layers through ``.bbappend`` but does not want to introduce a hard dependency on those other layers. - Use the following form for ``BBFILES_DYNAMIC``: + Use the following form for :term:`BBFILES_DYNAMIC`: collection_name:filename_pattern The following example identifies two - collection names and two filename patterns: - :: + collection names and two filename patterns:: BBFILES_DYNAMIC += " \ clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ @@ -685,14 +664,13 @@ system and gives an overview of their function and contents. :term:`BBINCLUDELOGS_LINES` If :term:`BBINCLUDELOGS` is set, specifies the maximum number of lines from the task log file to print when - reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``, + reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`, the entire log is printed. :term:`BBLAYERS` Lists the layers to enable during the build. This variable is defined in the ``bblayers.conf`` configuration file in the :term:`Build Directory`. - Here is an example: - :: + Here is an example:: BBLAYERS = " \ /home/scottrif/poky/meta \ @@ -707,7 +685,7 @@ system and gives an overview of their function and contents. :term:`BBMASK` Prevents BitBake from processing recipes and recipe append files. - You can use the ``BBMASK`` variable to "hide" these ``.bb`` and + You can use the :term:`BBMASK` variable to "hide" these ``.bb`` and ``.bbappend`` files. BitBake ignores any recipe or recipe append files that match any of the expressions. It is as if BitBake does not see them at all. Consequently, matching files are not parsed or @@ -721,14 +699,13 @@ system and gives an overview of their function and contents. The following example uses a complete regular expression to tell BitBake to ignore all recipe and recipe append files in the - ``meta-ti/recipes-misc/`` directory: - :: + ``meta-ti/recipes-misc/`` directory:: BBMASK = "meta-ti/recipes-misc/" If you want to mask out multiple directories or recipes, you can specify multiple regular expression fragments. This next example - masks out multiple directories and individual recipes: :: + masks out multiple directories and individual recipes:: BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" BBMASK += "/meta-oe/recipes-support/" @@ -746,8 +723,7 @@ system and gives an overview of their function and contents. building targets with multiple configurations. Use this variable in your ``conf/local.conf`` configuration file. Specify a multiconfigname for each configuration file you are using. For - example, the following line specifies three configuration files: - :: + example, the following line specifies three configuration files:: BBMULTICONFIG = "configA configB configC" @@ -756,7 +732,7 @@ system and gives an overview of their function and contents. ``conf/multiconfig`` directory (e.g. build_directory\ ``/conf/multiconfig/configA.conf``). - For information on how to use ``BBMULTICONFIG`` in an environment + For information on how to use :term:`BBMULTICONFIG` in an environment that supports building targets with multiple configurations, see the ":ref:`dev-manual/common-tasks:building images for multiple targets using multiple configurations`" section in the Yocto Project Development Tasks Manual. @@ -768,10 +744,9 @@ system and gives an overview of their function and contents. .. note:: If you run BitBake from a directory outside of the - :term:`Build Directory`, you must be sure to set ``BBPATH`` + :term:`Build Directory`, you must be sure to set :term:`BBPATH` to point to the Build Directory. Set the variable as you would any - environment variable and then run BitBake: - :: + environment variable and then run BitBake:: $ BBPATH = "build_directory" $ export BBPATH @@ -779,18 +754,17 @@ system and gives an overview of their function and contents. :term:`BBSERVER` - If defined in the BitBake environment, ``BBSERVER`` points to the + If defined in the BitBake environment, :term:`BBSERVER` points to the BitBake remote server. Use the following format to export the variable to the BitBake - environment: - :: + environment:: export BBSERVER=localhost:$port - By default, ``BBSERVER`` also appears in + By default, :term:`BBSERVER` also appears in :term:`bitbake:BB_HASHBASE_WHITELIST`. - Consequently, ``BBSERVER`` is excluded from checksum and dependency + Consequently, :term:`BBSERVER` is excluded from checksum and dependency data. :term:`BINCONFIG` @@ -803,8 +777,7 @@ system and gives an overview of their function and contents. replaced. To add multiple scripts, separate them by spaces. Here is an example - from the ``libpng`` recipe: - :: + from the ``libpng`` recipe:: BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config" @@ -818,7 +791,7 @@ system and gives an overview of their function and contents. .. note:: - The ``BINCONFIG_GLOB`` variable uses + The :term:`BINCONFIG_GLOB` variable uses `shell globbing <https://tldp.org/LDP/abs/html/globbingref.html>`__, which is recognition and expansion of wildcards during pattern matching. Shell globbing is very similar to @@ -833,9 +806,8 @@ system and gives an overview of their function and contents. :term:`BP` The base recipe name and version but without any special recipe name - suffix (i.e. ``-native``, ``lib64-``, and so forth). ``BP`` is - comprised of the following: - :: + suffix (i.e. ``-native``, ``lib64-``, and so forth). :term:`BP` is + comprised of the following:: ${BPN}-${PV} @@ -856,23 +828,23 @@ system and gives an overview of their function and contents. :term:`BUILD_ARCH` Specifies the architecture of the build host (e.g. ``i686``). The - OpenEmbedded build system sets the value of ``BUILD_ARCH`` from the + OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the machine name reported by the ``uname`` command. :term:`BUILD_AS_ARCH` Specifies the architecture-specific assembler flags for the build - host. By default, the value of ``BUILD_AS_ARCH`` is empty. + host. By default, the value of :term:`BUILD_AS_ARCH` is empty. :term:`BUILD_CC_ARCH` Specifies the architecture-specific C compiler flags for the build - host. By default, the value of ``BUILD_CC_ARCH`` is empty. + host. By default, the value of :term:`BUILD_CC_ARCH` is empty. :term:`BUILD_CCLD` Specifies the linker command to be used for the build host when the C - compiler is being used as the linker. By default, ``BUILD_CCLD`` + compiler is being used as the linker. By default, :term:`BUILD_CCLD` points to GCC and passes as arguments the value of :term:`BUILD_CC_ARCH`, assuming - ``BUILD_CC_ARCH`` is set. + :term:`BUILD_CC_ARCH` is set. :term:`BUILD_CFLAGS` Specifies the flags to pass to the C compiler when building for the @@ -894,19 +866,19 @@ system and gives an overview of their function and contents. :term:`BUILD_FC` Specifies the Fortran compiler command for the build host. By - default, ``BUILD_FC`` points to Gfortran and passes as arguments the + default, :term:`BUILD_FC` points to Gfortran and passes as arguments the value of :term:`BUILD_CC_ARCH`, assuming - ``BUILD_CC_ARCH`` is set. + :term:`BUILD_CC_ARCH` is set. :term:`BUILD_LD` Specifies the linker command for the build host. By default, - ``BUILD_LD`` points to the GNU linker (ld) and passes as arguments + :term:`BUILD_LD` points to the GNU linker (ld) and passes as arguments the value of :term:`BUILD_LD_ARCH`, assuming - ``BUILD_LD_ARCH`` is set. + :term:`BUILD_LD_ARCH` is set. :term:`BUILD_LD_ARCH` Specifies architecture-specific linker flags for the build host. By - default, the value of ``BUILD_LD_ARCH`` is empty. + default, the value of :term:`BUILD_LD_ARCH` is empty. :term:`BUILD_LDFLAGS` Specifies the flags to pass to the linker when building for the build @@ -931,13 +903,13 @@ system and gives an overview of their function and contents. :term:`BUILD_PREFIX` The toolchain binary prefix used for native recipes. The OpenEmbedded - build system uses the ``BUILD_PREFIX`` value to set the + build system uses the :term:`BUILD_PREFIX` value to set the :term:`TARGET_PREFIX` when building for ``native`` recipes. :term:`BUILD_STRIP` Specifies the command to be used to strip debugging symbols from - binaries produced for the build host. By default, ``BUILD_STRIP`` + binaries produced for the build host. By default, :term:`BUILD_STRIP` points to ``${``\ :term:`BUILD_PREFIX`\ ``}strip``. @@ -950,7 +922,7 @@ system and gives an overview of their function and contents. on :term:`BUILD_ARCH`, :term:`BUILD_VENDOR`, and :term:`BUILD_OS`. You do not need to set the - ``BUILD_SYS`` variable yourself. + :term:`BUILD_SYS` variable yourself. :term:`BUILD_VENDOR` Specifies the vendor name to use when building for the build host. @@ -961,7 +933,7 @@ system and gives an overview of their function and contents. You can define this directory indirectly through the :ref:`structure-core-script` script by passing in a Build Directory path when you run the script. If you run the script and do - not provide a Build Directory path, the ``BUILDDIR`` defaults to + not provide a Build Directory path, the :term:`BUILDDIR` defaults to ``build`` in the current directory. :term:`BUILDHISTORY_COMMIT` @@ -975,25 +947,23 @@ system and gives an overview of their function and contents. you should set this value to "1". By default, the ``buildhistory`` class does not commit the build - history output in a local Git repository: - :: + history output in a local Git repository:: BUILDHISTORY_COMMIT ?= "0" :term:`BUILDHISTORY_COMMIT_AUTHOR` When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` class, this variable specifies the author to use for each Git commit. - In order for the ``BUILDHISTORY_COMMIT_AUTHOR`` variable to work, the + In order for the :term:`BUILDHISTORY_COMMIT_AUTHOR` variable to work, the :term:`BUILDHISTORY_COMMIT` variable must be set to "1". Git requires that the value you provide for the - ``BUILDHISTORY_COMMIT_AUTHOR`` variable takes the form of "name + :term:`BUILDHISTORY_COMMIT_AUTHOR` variable takes the form of "name email@host". Providing an email address or host that is not valid does not produce an error. - By default, the ``buildhistory`` class sets the variable as follows: - :: + By default, the ``buildhistory`` class sets the variable as follows:: BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>" @@ -1003,8 +973,7 @@ system and gives an overview of their function and contents. information is kept. For more information on how the variable works, see the ``buildhistory.class``. - By default, the ``buildhistory`` class sets the directory as follows: - :: + By default, the ``buildhistory`` class sets the directory as follows:: BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory" @@ -1032,8 +1001,7 @@ system and gives an overview of their function and contents. each file staged (i.e. the output of the task). By default, the ``buildhistory`` class enables the following - features: - :: + features:: BUILDHISTORY_FEATURES ?= "image package sdk" @@ -1049,8 +1017,7 @@ system and gives an overview of their function and contents. Consequently, you can include files that might not always be present. By default, the ``buildhistory`` class provides paths to the - following files: - :: + following files:: BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group" @@ -1058,7 +1025,7 @@ system and gives an overview of their function and contents. When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` class, this variable optionally specifies a remote repository to which build history pushes Git changes. In order for - ``BUILDHISTORY_PUSH_REPO`` to work, + :term:`BUILDHISTORY_PUSH_REPO` to work, :term:`BUILDHISTORY_COMMIT` must be set to "1". @@ -1067,8 +1034,7 @@ system and gives an overview of their function and contents. that you have set up manually using ``git remote`` within the local repository. - By default, the ``buildhistory`` class sets the variable as follows: - :: + By default, the ``buildhistory`` class sets the variable as follows:: BUILDHISTORY_PUSH_REPO ?= "" @@ -1100,7 +1066,7 @@ system and gives an overview of their function and contents. Points to the location of the directory that holds build statistics when you use and enable the :ref:`buildstats <ref-classes-buildstats>` class. The - ``BUILDSTATS_BASE`` directory defaults to + :term:`BUILDSTATS_BASE` directory defaults to ``${``\ :term:`TMPDIR`\ ``}/buildstats/``. :term:`BUSYBOX_SPLIT_SUID` @@ -1109,7 +1075,7 @@ system and gives an overview of their function and contents. ``setuid root``, and one for the remaining features (i.e. those that do not require ``setuid root``). - The ``BUSYBOX_SPLIT_SUID`` variable defaults to "1", which results in + The :term:`BUSYBOX_SPLIT_SUID` variable defaults to "1", which results in splitting the output executable file. Set the variable to "0" to get a single output executable file. @@ -1126,7 +1092,7 @@ system and gives an overview of their function and contents. exported to an environment variable and thus made visible to the software being built during the compilation step. - Default initialization for ``CFLAGS`` varies depending on what is + Default initialization for :term:`CFLAGS` varies depending on what is being built: - :term:`TARGET_CFLAGS` when building for the @@ -1152,8 +1118,7 @@ system and gives an overview of their function and contents. ``bitbake.conf`` file. As an example, the following override allows you to install extra - files, but only when building for the target: - :: + files, but only when building for the target:: do_install_append_class-target() { install my-extra-file ${D}${sysconfdir} @@ -1161,18 +1126,17 @@ system and gives an overview of their function and contents. Here is an example where ``FOO`` is set to "native" when building for the build host, and to "other" when not - building for the build host: - :: + building for the build host:: FOO_class-native = "native" FOO = "other" - The underlying mechanism behind ``CLASSOVERRIDE`` is simply + The underlying mechanism behind :term:`CLASSOVERRIDE` is simply that it is included in the default value of :term:`OVERRIDES`. :term:`CLEANBROKEN` - If set to "1" within a recipe, ``CLEANBROKEN`` specifies that the + If set to "1" within a recipe, :term:`CLEANBROKEN` specifies that the ``make clean`` command does not work for the software being built. Consequently, the OpenEmbedded build system will not try to run ``make clean`` during the :ref:`ref-tasks-configure` @@ -1221,7 +1185,7 @@ system and gives an overview of their function and contents. .. note:: - The ``COMPLEMENTARY_GLOB`` variable uses Unix filename pattern matching + The :term:`COMPLEMENTARY_GLOB` variable uses Unix filename pattern matching (`fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__), which is similar to the Unix style pathname pattern expansion (`glob <https://docs.python.org/3/library/glob.html>`__). @@ -1229,14 +1193,13 @@ system and gives an overview of their function and contents. The resulting list of complementary packages is associated with an item that can be added to :term:`IMAGE_FEATURES`. An example usage of - this is the "dev-pkgs" item that when added to ``IMAGE_FEATURES`` + this is the "dev-pkgs" item that when added to :term:`IMAGE_FEATURES` will install -dev packages (containing headers and other development files) for every package in the image. To add a new feature item pointing to a wildcard, use a variable flag to specify the feature item name and use the value to specify the - wildcard. Here is an example: - :: + wildcard. Here is an example:: COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev' @@ -1252,7 +1215,7 @@ system and gives an overview of their function and contents. :term:`CONF_VERSION` Tracks the version of the local configuration file (i.e. - ``local.conf``). The value for ``CONF_VERSION`` increments each time + ``local.conf``). The value for :term:`CONF_VERSION` increments each time ``build/conf/`` compatibility changes. :term:`CONFFILES` @@ -1262,29 +1225,28 @@ system and gives an overview of their function and contents. files you have changed after the original installation and that you now want to remain unchanged are overwritten. In other words, editable files might exist in the package that you do not want reset - as part of the package update process. You can use the ``CONFFILES`` + as part of the package update process. You can use the :term:`CONFFILES` variable to list the files in the package that you wish to prevent the PMS from overwriting during this update process. - To use the ``CONFFILES`` variable, provide a package name override + To use the :term:`CONFFILES` variable, provide a package name override that identifies the resulting package. Then, provide a - space-separated list of files. Here is an example: - :: + space-separated list of files. Here is an example:: CONFFILES_${PN} += "${sysconfdir}/file1 \ ${sysconfdir}/file2 ${sysconfdir}/file3" - A relationship exists between the ``CONFFILES`` and ``FILES`` - variables. The files listed within ``CONFFILES`` must be a subset of - the files listed within ``FILES``. Because the configuration files - you provide with ``CONFFILES`` are simply being identified so that + There is a relationship between the :term:`CONFFILES` and :term:`FILES` + variables. The files listed within :term:`CONFFILES` must be a subset of + the files listed within :term:`FILES`. Because the configuration files + you provide with :term:`CONFFILES` are simply being identified so that the PMS will not overwrite them, it makes sense that the files must - already be included as part of the package through the ``FILES`` + already be included as part of the package through the :term:`FILES` variable. .. note:: - When specifying paths as part of the ``CONFFILES`` variable, it is + When specifying paths as part of the :term:`CONFFILES` variable, it is good practice to use appropriate path variables. For example, ``${sysconfdir}`` rather than ``/etc`` or ``${bindir}`` rather than ``/usr/bin``. You can find a list of these variables at @@ -1297,7 +1259,7 @@ system and gives an overview of their function and contents. variable as an environment variable. By default, the variable is set to null (""). - The ``CONFIG_INITRAMFS_SOURCE`` can be either a single cpio archive + 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 @@ -1325,8 +1287,8 @@ system and gives an overview of their function and contents. :ref:`features_check <ref-classes-features_check>` class, this variable identifies distribution features that would be in conflict should the recipe be built. In other words, if the - ``CONFLICT_DISTRO_FEATURES`` variable lists a feature that also - appears in ``DISTRO_FEATURES`` within the current configuration, then + :term:`CONFLICT_DISTRO_FEATURES` variable lists a feature that also + appears in :term:`DISTRO_FEATURES` within the current configuration, then the recipe will be skipped, and if the build system attempts to build the recipe then an error will be triggered. @@ -1335,16 +1297,16 @@ system and gives an overview of their function and contents. archived by the :ref:`archiver <ref-classes-archiver>` class. In other words, if a license in a recipe's :term:`LICENSE` value is in the value of - ``COPYLEFT_LICENSE_EXCLUDE``, then its source is not archived by the + :term:`COPYLEFT_LICENSE_EXCLUDE`, then its source is not archived by the class. .. note:: - The ``COPYLEFT_LICENSE_EXCLUDE`` variable takes precedence over the + The :term:`COPYLEFT_LICENSE_EXCLUDE` variable takes precedence over the :term:`COPYLEFT_LICENSE_INCLUDE` variable. The default value, which is "CLOSED Proprietary", for - ``COPYLEFT_LICENSE_EXCLUDE`` is set by the + :term:`COPYLEFT_LICENSE_EXCLUDE` is set by the :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which is inherited by the ``archiver`` class. @@ -1352,7 +1314,7 @@ system and gives an overview of their function and contents. A space-separated list of licenses to include in the source archived by the :ref:`archiver <ref-classes-archiver>` class. In other words, if a license in a recipe's :term:`LICENSE` - value is in the value of ``COPYLEFT_LICENSE_INCLUDE``, then its + value is in the value of :term:`COPYLEFT_LICENSE_INCLUDE`, then its source is archived by the class. The default value is set by the @@ -1363,28 +1325,28 @@ system and gives an overview of their function and contents. :term:`COPYLEFT_PN_EXCLUDE` A list of recipes to exclude in the source archived by the :ref:`archiver <ref-classes-archiver>` class. The - ``COPYLEFT_PN_EXCLUDE`` variable overrides the license inclusion and + :term:`COPYLEFT_PN_EXCLUDE` variable overrides the license inclusion and exclusion caused through the :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE` variables, respectively. The default value, which is "" indicating to not explicitly exclude - any recipes by name, for ``COPYLEFT_PN_EXCLUDE`` is set by the + any recipes by name, for :term:`COPYLEFT_PN_EXCLUDE` is set by the :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which is inherited by the ``archiver`` class. :term:`COPYLEFT_PN_INCLUDE` A list of recipes to include in the source archived by the :ref:`archiver <ref-classes-archiver>` class. The - ``COPYLEFT_PN_INCLUDE`` variable overrides the license inclusion and + :term:`COPYLEFT_PN_INCLUDE` variable overrides the license inclusion and exclusion caused through the :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE` variables, respectively. The default value, which is "" indicating to not explicitly include - any recipes by name, for ``COPYLEFT_PN_INCLUDE`` is set by the + any recipes by name, for :term:`COPYLEFT_PN_INCLUDE` is set by the :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which is inherited by the ``archiver`` class. @@ -1394,7 +1356,7 @@ system and gives an overview of their function and contents. Recipe types are ``target``, ``native``, ``nativesdk``, ``cross``, ``crosssdk``, and ``cross-canadian``. - The default value, which is "target*", for ``COPYLEFT_RECIPE_TYPES`` + The default value, which is "target*", for :term:`COPYLEFT_RECIPE_TYPES` is set by the :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which is inherited by the ``archiver`` class. @@ -1408,7 +1370,7 @@ system and gives an overview of their function and contents. .. note:: - The ``COPY_LIC_DIRS`` does not offer a path for adding licenses for + The :term:`COPY_LIC_DIRS` does not offer a path for adding licenses for newly installed packages to an image, which might be most suitable for read-only filesystems that cannot be upgraded. See the :term:`LICENSE_CREATE_PACKAGE` variable for additional information. @@ -1424,7 +1386,7 @@ system and gives an overview of their function and contents. .. note:: - The ``COPY_LIC_MANIFEST`` does not offer a path for adding licenses for + The :term:`COPY_LIC_MANIFEST` does not offer a path for adding licenses for newly installed packages to an image, which might be most suitable for read-only filesystems that cannot be upgraded. See the :term:`LICENSE_CREATE_PACKAGE` variable for additional information. @@ -1444,24 +1406,24 @@ system and gives an overview of their function and contents. Specifies the parent directory of the OpenEmbedded-Core Metadata layer (i.e. ``meta``). - It is an important distinction that ``COREBASE`` points to the parent + It is an important distinction that :term:`COREBASE` points to the parent of this layer and not the layer itself. Consider an example where you have cloned the Poky Git repository and retained the ``poky`` name - for your local copy of the repository. In this case, ``COREBASE`` + for your local copy of the repository. In this case, :term:`COREBASE` points to the ``poky`` folder because it is the parent directory of the ``poky/meta`` layer. :term:`COREBASE_FILES` Lists files from the :term:`COREBASE` directory that should be copied other than the layers listed in the - ``bblayers.conf`` file. The ``COREBASE_FILES`` variable exists for - the purpose of copying metadata from the OpenEmbedded build system + ``bblayers.conf`` file. The :term:`COREBASE_FILES` variable allows + to copy metadata from the OpenEmbedded build system into the extensible SDK. - Explicitly listing files in ``COREBASE`` is needed because it + Explicitly listing files in :term:`COREBASE` is needed because it typically contains build directories and other files that should not normally be copied into the extensible SDK. Consequently, the value - of ``COREBASE_FILES`` is used in order to only copy the files that + of :term:`COREBASE_FILES` is used in order to only copy the files that are actually needed. :term:`CPP` @@ -1473,7 +1435,7 @@ system and gives an overview of their function and contents. variable and thus made visible to the software being built during the compilation step. - Default initialization for ``CPPFLAGS`` varies depending on what is + Default initialization for :term:`CPPFLAGS` varies depending on what is being built: - :term:`TARGET_CPPFLAGS` when building for @@ -1487,12 +1449,12 @@ system and gives an overview of their function and contents. :term:`CROSS_COMPILE` The toolchain binary prefix for the target tools. The - ``CROSS_COMPILE`` variable is the same as the + :term:`CROSS_COMPILE` variable is the same as the :term:`TARGET_PREFIX` variable. .. note:: - The OpenEmbedded build system sets the ``CROSS_COMPILE`` + The OpenEmbedded build system sets the :term:`CROSS_COMPILE` variable only in certain contexts (e.g. when building for kernel and kernel module recipes). @@ -1508,7 +1470,7 @@ system and gives an overview of their function and contents. exported to an environment variable and thus made visible to the software being built during the compilation step. - Default initialization for ``CXXFLAGS`` varies depending on what is + Default initialization for :term:`CXXFLAGS` varies depending on what is being built: - :term:`TARGET_CXXFLAGS` when building for @@ -1524,8 +1486,7 @@ system and gives an overview of their function and contents. The destination directory. The location in the :term:`Build Directory` where components are installed by the :ref:`ref-tasks-install` task. This location defaults - to: - :: + to:: ${WORKDIR}/image @@ -1544,37 +1505,29 @@ system and gives an overview of their function and contents. :term:`DEBIAN_NOAUTONAME` When the :ref:`debian <ref-classes-debian>` class is inherited, - which is the default behavior, ``DEBIAN_NOAUTONAME`` specifies a + which is the default behavior, :term:`DEBIAN_NOAUTONAME` specifies a particular package should not be renamed according to Debian library package naming. You must use the package name as an override when you - set this variable. Here is an example from the ``fontconfig`` recipe: - :: + set this variable. Here is an example from the ``fontconfig`` recipe:: DEBIAN_NOAUTONAME_fontconfig-utils = "1" :term:`DEBIANNAME` When the :ref:`debian <ref-classes-debian>` class is inherited, - which is the default behavior, ``DEBIANNAME`` allows you to override + which is the default behavior, :term:`DEBIANNAME` allows you to override the library name for an individual package. Overriding the library name in these cases is rare. You must use the package name as an override when you set this variable. Here is an example from the - ``dbus`` recipe: - :: + ``dbus`` recipe:: DEBIANNAME_${PN} = "dbus-1" - :term:`DEBUGINFOD_URLS` - Points to the URL of the "debuginfod" server. Such that for every - debugging information lookup, the debuginfod client will query the - server and return the requested information. You set this variable - in your ``local.conf`` file. - :term:`DEBUG_BUILD` Specifies to build packages with debugging information. This - influences the value of the ``SELECTED_OPTIMIZATION`` variable. + influences the value of the :term:`SELECTED_OPTIMIZATION` variable. :term:`DEBUG_OPTIMIZATION` - The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when + The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when compiling a system for debugging. This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe". @@ -1584,19 +1537,19 @@ system and gives an overview of their function and contents. The most common usage of this is variable is to set it to "-1" within a recipe for a development version of a piece of software. Using the variable in this way causes the stable version of the recipe to build - by default in the absence of ``PREFERRED_VERSION`` being used to + by default in the absence of :term:`PREFERRED_VERSION` being used to build the development version. .. note:: - The bias provided by ``DEFAULT_PREFERENCE`` is weak and is overridden + The bias provided by :term:`DEFAULT_PREFERENCE` is weak and is overridden by :term:`BBFILE_PRIORITY` if that variable is different between two layers that contain different versions of the same recipe. :term:`DEFAULTTUNE` The default CPU and Application Binary Interface (ABI) tunings (i.e. the "tune") used by the OpenEmbedded build system. The - ``DEFAULTTUNE`` helps define + :term:`DEFAULTTUNE` helps define :term:`TUNE_FEATURES`. The default tune is either implicitly or explicitly set by the @@ -1610,8 +1563,7 @@ system and gives an overview of their function and contents. needed by the recipe at build time. As an example, consider a recipe ``foo`` that contains the following - assignment: - :: + assignment:: DEPENDS = "bar" @@ -1622,21 +1574,20 @@ system and gives an overview of their function and contents. :ref:`ref-tasks-configure` task for ``foo`` runs. This mechanism is implemented by having ``do_configure`` depend on the :ref:`ref-tasks-populate_sysroot` task of - each recipe listed in ``DEPENDS``, through a + each recipe listed in :term:`DEPENDS`, through a ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` declaration in the :ref:`base <ref-classes-base>` class. .. note:: - It seldom is necessary to reference, for example, ``STAGING_DIR_HOST`` + It seldom is necessary to reference, for example, :term:`STAGING_DIR_HOST` explicitly. The standard classes and build-related variables are configured to automatically use the appropriate staging sysroots. - As another example, ``DEPENDS`` can also be used to add utilities + As another example, :term:`DEPENDS` can also be used to add utilities that run on the build machine during the build. For example, a recipe that makes use of a code generator built by the recipe ``codegen`` - might have the following: - :: + might have the following:: DEPENDS = "codegen-native" @@ -1646,15 +1597,15 @@ system and gives an overview of their function and contents. .. note:: - - ``DEPENDS`` is a list of recipe names. Or, to be more precise, + - :term:`DEPENDS` is a list of recipe names. Or, to be more precise, it is a list of :term:`PROVIDES` names, which usually match recipe names. Putting a package name such as - "foo-dev" in ``DEPENDS`` does not make sense. Use "foo" + "foo-dev" in :term:`DEPENDS` does not make sense. Use "foo" instead, as this will put files from all the packages that make up ``foo``, which includes those from ``foo-dev``, into the sysroot. - - One recipe having another recipe in ``DEPENDS`` does not by + - One recipe having another recipe in :term:`DEPENDS` does not by itself add any runtime dependencies between the packages produced by the two recipes. However, as explained in the ":ref:`overview-manual/concepts:automatically added runtime dependencies`" @@ -1662,12 +1613,12 @@ system and gives an overview of their function and contents. runtime dependencies will often be added automatically, meaning ``DEPENDS`` alone is sufficient for most recipes. - - Counterintuitively, ``DEPENDS`` is often necessary even for + - Counterintuitively, :term:`DEPENDS` is often necessary even for recipes that install precompiled components. For example, if ``libfoo`` is a precompiled library that links against ``libbar``, then linking against ``libfoo`` requires both ``libfoo`` and ``libbar`` to be available in the sysroot. - Without a ``DEPENDS`` from the recipe that installs ``libfoo`` + Without a :term:`DEPENDS` from the recipe that installs ``libfoo`` to the recipe that installs ``libbar``, other recipes might fail to link against ``libfoo``. @@ -1702,13 +1653,12 @@ system and gives an overview of their function and contents. The BitBake configuration file initially defines the ``DEPLOY_DIR_DEB`` variable as a sub-folder of - :term:`DEPLOY_DIR`: - :: + :term:`DEPLOY_DIR`:: DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb" The :ref:`package_deb <ref-classes-package_deb>` class uses the - ``DEPLOY_DIR_DEB`` variable to make sure the + :term:`DEPLOY_DIR_DEB` variable to make sure the :ref:`ref-tasks-package_write_deb` task writes Debian packages into the appropriate folder. For more information on how packaging works, see the @@ -1723,6 +1673,13 @@ system and gives an overview of their function and contents. resides within the :term:`Build Directory` as ``${DEPLOY_DIR}/images/${MACHINE}/``. + It must not be used directly in recipes when deploying files. Instead, + it's only useful when a recipe needs to "read" a file already deployed + by a dependency. So, it should be filled with the contents of + :term:`DEPLOYDIR` by the :ref:`deploy <ref-classes-deploy>` class or + with the contents of :term:`IMGDEPLOYDIR` by the :ref:`image + <ref-classes-image>` class. + For more information on the structure of the Build Directory, see ":ref:`ref-manual/structure:the build directory - \`\`build/\`\``" section. For more detail on the contents of the ``deploy`` directory, see the @@ -1738,13 +1695,12 @@ system and gives an overview of their function and contents. "package_ipk". The BitBake configuration file initially defines this variable as a - sub-folder of :term:`DEPLOY_DIR`: - :: + sub-folder of :term:`DEPLOY_DIR`:: DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk" The :ref:`package_ipk <ref-classes-package_ipk>` class uses the - ``DEPLOY_DIR_IPK`` variable to make sure the + :term:`DEPLOY_DIR_IPK` variable to make sure the :ref:`ref-tasks-package_write_ipk` task writes IPK packages into the appropriate folder. For more information on how packaging works, see the @@ -1759,13 +1715,12 @@ system and gives an overview of their function and contents. "package_rpm". The BitBake configuration file initially defines this variable as a - sub-folder of :term:`DEPLOY_DIR`: - :: + sub-folder of :term:`DEPLOY_DIR`:: DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm" The :ref:`package_rpm <ref-classes-package_rpm>` class uses the - ``DEPLOY_DIR_RPM`` variable to make sure the + :term:`DEPLOY_DIR_RPM` variable to make sure the :ref:`ref-tasks-package_write_rpm` task writes RPM packages into the appropriate folder. For more information on how packaging works, see the @@ -1780,13 +1735,12 @@ system and gives an overview of their function and contents. "package_tar". The BitBake configuration file initially defines this variable as a - sub-folder of :term:`DEPLOY_DIR`: - :: + sub-folder of :term:`DEPLOY_DIR`:: DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar" The :ref:`package_tar <ref-classes-package_tar>` class uses the - ``DEPLOY_DIR_TAR`` variable to make sure the + :term:`DEPLOY_DIR_TAR` variable to make sure the :ref:`ref-tasks-package_write_tar` task writes TAR packages into the appropriate folder. For more information on how packaging works, see the @@ -1795,20 +1749,19 @@ system and gives an overview of their function and contents. :term:`DEPLOYDIR` When inheriting the :ref:`deploy <ref-classes-deploy>` class, the - ``DEPLOYDIR`` points to a temporary work area for deployed files that - is set in the ``deploy`` class as follows: - :: + :term:`DEPLOYDIR` points to a temporary work area for deployed files that + is set in the ``deploy`` class as follows:: DEPLOYDIR = "${WORKDIR}/deploy-${PN}" Recipes inheriting the ``deploy`` class should copy files to be - deployed into ``DEPLOYDIR``, and the class will take care of copying + deployed into :term:`DEPLOYDIR`, and the class will take care of copying them into :term:`DEPLOY_DIR_IMAGE` afterwards. :term:`DESCRIPTION` The package description used by package managers. If not set, - ``DESCRIPTION`` takes the value of the :term:`SUMMARY` + :term:`DESCRIPTION` takes the value of the :term:`SUMMARY` variable. :term:`DISTRO` @@ -1816,27 +1769,26 @@ system and gives an overview of their function and contents. of the distribution, see the :term:`DISTRO_NAME` variable. - The ``DISTRO`` variable corresponds to a distribution configuration + The :term:`DISTRO` variable corresponds to a distribution configuration file whose root name is the same as the variable's argument and whose filename extension is ``.conf``. For example, the distribution configuration file for the Poky distribution is named ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory of the :term:`Source Directory`. - Within that ``poky.conf`` file, the ``DISTRO`` variable is set as - follows: - :: + Within that ``poky.conf`` file, the :term:`DISTRO` variable is set as + follows:: DISTRO = "poky" Distribution configuration files are located in a ``conf/distro`` directory within the :term:`Metadata` that contains the - distribution configuration. The value for ``DISTRO`` must not contain + distribution configuration. The value for :term:`DISTRO` must not contain spaces, and is typically all lower-case. .. note:: - If the ``DISTRO`` variable is blank, a set of default configurations + If the :term:`DISTRO` variable is blank, a set of default configurations are used, which are specified within ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. @@ -1863,11 +1815,11 @@ system and gives an overview of their function and contents. configuration file. In most cases, the presence or absence of a feature in - ``DISTRO_FEATURES`` is translated to the appropriate option supplied + :term:`DISTRO_FEATURES` is translated to the appropriate option supplied to the configure script during the :ref:`ref-tasks-configure` task for recipes that optionally support the feature. For example, specifying "x11" in - ``DISTRO_FEATURES``, causes every piece of software built for the + :term:`DISTRO_FEATURES`, causes every piece of software built for the target that can optionally support X11 to have its X11 support enabled. @@ -1876,8 +1828,8 @@ system and gives an overview of their function and contents. provide with this variable, see the ":ref:`ref-features-distro`" section. :term:`DISTRO_FEATURES_BACKFILL` - Features to be added to ``DISTRO_FEATURES`` if not also present in - ``DISTRO_FEATURES_BACKFILL_CONSIDERED``. + Features to be added to :term:`DISTRO_FEATURES` if not also present in + :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`. This variable is set in the ``meta/conf/bitbake.conf`` file. It is not intended to be user-configurable. It is best to just reference @@ -1886,8 +1838,8 @@ system and gives an overview of their function and contents. for more information. :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` - Features from ``DISTRO_FEATURES_BACKFILL`` that should not be - backfilled (i.e. added to ``DISTRO_FEATURES``) during the build. See + Features from :term:`DISTRO_FEATURES_BACKFILL` that should not be + backfilled (i.e. added to :term:`DISTRO_FEATURES`) during the build. See the ":ref:`ref-features-backfill`" section for more information. :term:`DISTRO_FEATURES_DEFAULT` @@ -1899,15 +1851,14 @@ system and gives an overview of their function and contents. able to reuse the default :term:`DISTRO_FEATURES` options without the need to write out the full set. Here is an example that uses - ``DISTRO_FEATURES_DEFAULT`` from a custom distro configuration file: - :: + :term:`DISTRO_FEATURES_DEFAULT` from a custom distro configuration file:: DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature" :term:`DISTRO_FEATURES_FILTER_NATIVE` Specifies a list of features that if present in the target :term:`DISTRO_FEATURES` value should be - included in ``DISTRO_FEATURES`` when building native recipes. This + included in :term:`DISTRO_FEATURES` when building native recipes. This variable is used in addition to the features filtered using the :term:`DISTRO_FEATURES_NATIVE` variable. @@ -1915,7 +1866,7 @@ system and gives an overview of their function and contents. :term:`DISTRO_FEATURES_FILTER_NATIVESDK` Specifies a list of features that if present in the target :term:`DISTRO_FEATURES` value should be - included in ``DISTRO_FEATURES`` when building nativesdk recipes. This + included in :term:`DISTRO_FEATURES` when building nativesdk recipes. This variable is used in addition to the features filtered using the :term:`DISTRO_FEATURES_NATIVESDK` variable. @@ -1940,16 +1891,15 @@ system and gives an overview of their function and contents. The long name of the distribution. For information on the short name of the distribution, see the :term:`DISTRO` variable. - The ``DISTRO_NAME`` variable corresponds to a distribution + The :term:`DISTRO_NAME` variable corresponds to a distribution configuration file whose root name is the same as the variable's argument and whose filename extension is ``.conf``. For example, the distribution configuration file for the Poky distribution is named ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory of the :term:`Source Directory`. - Within that ``poky.conf`` file, the ``DISTRO_NAME`` variable is set - as follows: - :: + Within that ``poky.conf`` file, the :term:`DISTRO_NAME` variable is set + as follows:: DISTRO_NAME = "Poky (Yocto Project Reference Distro)" @@ -1959,7 +1909,7 @@ system and gives an overview of their function and contents. .. note:: - If the ``DISTRO_NAME`` variable is blank, a set of default + If the :term:`DISTRO_NAME` variable is blank, a set of default configurations are used, which are specified within ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. @@ -1971,10 +1921,10 @@ system and gives an overview of their function and contents. distribution. By default, this list includes the value of :term:`DISTRO`. - You can extend ``DISTROOVERRIDES`` to add extra overrides that should + You can extend :term:`DISTROOVERRIDES` to add extra overrides that should apply to the distribution. - The underlying mechanism behind ``DISTROOVERRIDES`` is simply that it + The underlying mechanism behind :term:`DISTROOVERRIDES` is simply that it is included in the default value of :term:`OVERRIDES`. @@ -1993,13 +1943,13 @@ system and gives an overview of their function and contents. :term:`DL_DIR` The central download directory used by the build process to store - downloads. By default, ``DL_DIR`` gets files suitable for mirroring + downloads. By default, :term:`DL_DIR` gets files suitable for mirroring for everything except Git repositories. If you want tarballs of Git repositories, use the :term:`BB_GENERATE_MIRROR_TARBALLS` variable. - You can set this directory by defining the ``DL_DIR`` variable in the + You can set this directory by defining the :term:`DL_DIR` variable in the ``conf/local.conf`` file. This directory is self-maintaining and you should not have to touch it. By default, the directory is ``downloads`` in the :term:`Build Directory`. @@ -2013,7 +1963,7 @@ system and gives an overview of their function and contents. During a first build, the system downloads many different source code tarballs from various upstream projects. Downloading can take a while, particularly if your network connection is slow. Tarballs are - all stored in the directory defined by ``DL_DIR`` and the build + all stored in the directory defined by :term:`DL_DIR` and the build system looks there first to find source tarballs. .. note:: @@ -2042,7 +1992,7 @@ system and gives an overview of their function and contents. :term:`EFI_PROVIDER` When building bootable images (i.e. where ``hddimg``, ``iso``, or ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the - ``EFI_PROVIDER`` variable specifies the EFI bootloader to use. The + :term:`EFI_PROVIDER` variable specifies the EFI bootloader to use. The default is "grub-efi", but "systemd-boot" can be used instead. See the :ref:`systemd-boot <ref-classes-systemd-boot>` and @@ -2063,10 +2013,9 @@ system and gives an overview of their function and contents. database. By default, the value of this variable is ``${``\ :term:`LOG_DIR`\ ``}/error-report``. - You can set ``ERR_REPORT_DIR`` to the path you want the error + You can set :term:`ERR_REPORT_DIR` to the path you want the error reporting tool to store the debug files as follows in your - ``local.conf`` file: - :: + ``local.conf`` file:: ERR_REPORT_DIR = "path" @@ -2089,13 +2038,12 @@ system and gives an overview of their function and contents. libraries resolver might implicitly define some dependencies between packages. - The ``EXCLUDE_FROM_SHLIBS`` variable is similar to the + The :term:`EXCLUDE_FROM_SHLIBS` variable is similar to the :term:`PRIVATE_LIBS` variable, which excludes a package's particular libraries only and not the whole package. - Use the ``EXCLUDE_FROM_SHLIBS`` variable by setting it to "1" for a - particular package: - :: + Use the :term:`EXCLUDE_FROM_SHLIBS` variable by setting it to "1" for a + particular package:: EXCLUDE_FROM_SHLIBS = "1" @@ -2110,18 +2058,18 @@ system and gives an overview of their function and contents. .. note:: - Recipes added to ``EXCLUDE_FROM_WORLD`` may still be built during a + Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a world build in order to satisfy dependencies of other recipes. Adding - a recipe to ``EXCLUDE_FROM_WORLD`` only ensures that the recipe is not + a recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not explicitly added to the list of build targets in a world build. :term:`EXTENDPE` Used with file and pathnames to create a prefix for a recipe's - version based on the recipe's :term:`PE` value. If ``PE`` - is set and greater than zero for a recipe, ``EXTENDPE`` becomes that - value (e.g if ``PE`` is equal to "1" then ``EXTENDPE`` becomes "1"). - If a recipe's ``PE`` is not set (the default) or is equal to zero, - ``EXTENDPE`` becomes "". + version based on the recipe's :term:`PE` value. If :term:`PE` + is set and greater than zero for a recipe, :term:`EXTENDPE` becomes that + value (e.g if :term:`PE` is equal to "1" then :term:`EXTENDPE` becomes "1"). + If a recipe's :term:`PE` is not set (the default) or is equal to zero, + :term:`EXTENDPE` becomes "". See the :term:`STAMP` variable for an example. @@ -2129,8 +2077,7 @@ system and gives an overview of their function and contents. The full package version specification as it appears on the final packages produced by a recipe. The variable's value is normally used to fix a runtime dependency to the exact same version of another - package in the same recipe: - :: + package in the same recipe:: RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})" @@ -2138,11 +2085,11 @@ system and gives an overview of their function and contents. manager to upgrade these types of packages in lock-step. :term:`EXTERNAL_KERNEL_TOOLS` - When set, the ``EXTERNAL_KERNEL_TOOLS`` variable indicates that these + When set, the :term:`EXTERNAL_KERNEL_TOOLS` variable indicates that these tools are not in the source tree. When kernel tools are available in the tree, they are preferred over - any externally installed tools. Setting the ``EXTERNAL_KERNEL_TOOLS`` + any externally installed tools. Setting the :term:`EXTERNAL_KERNEL_TOOLS` variable tells the OpenEmbedded build system to prefer the installed external tools. See the :ref:`kernel-yocto <ref-classes-kernel-yocto>` class in @@ -2177,7 +2124,7 @@ system and gives an overview of their function and contents. :term:`EXTRA_AUTORECONF` For recipes inheriting the :ref:`autotools <ref-classes-autotools>` - class, you can use ``EXTRA_AUTORECONF`` to specify extra options to + class, you can use :term:`EXTRA_AUTORECONF` to specify extra options to pass to the ``autoreconf`` command that is executed during the :ref:`ref-tasks-configure` task. @@ -2230,8 +2177,7 @@ system and gives an overview of their function and contents. Specifies additional options for the image creation command that has been specified in :term:`IMAGE_CMD`. When setting this variable, use an override for the associated image type. Here is - an example: - :: + an example:: EXTRA_IMAGECMD_ext3 ?= "-i 4096" @@ -2240,7 +2186,7 @@ system and gives an overview of their function and contents. installing into the root filesystem. Sometimes a recipe is required to build the final image but is not - needed in the root filesystem. You can use the ``EXTRA_IMAGEDEPENDS`` + needed in the root filesystem. You can use the :term:`EXTRA_IMAGEDEPENDS` variable to list these recipes and thus specify the dependencies. A typical example is a required bootloader in a machine configuration. @@ -2255,8 +2201,7 @@ system and gives an overview of their function and contents. added to the beginning of the environment variable ``PATH``. As an example, the following prepends "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to - ``PATH``: - :: + ``PATH``:: EXTRANATIVEPATH = "foo bar" @@ -2272,12 +2217,12 @@ system and gives an overview of their function and contents. :term:`EXTRA_OEMAKE` Additional GNU ``make`` options. - Because the ``EXTRA_OEMAKE`` defaults to "", you need to set the + Because the :term:`EXTRA_OEMAKE` defaults to "", you need to set the variable to specify any required GNU options. :term:`PARALLEL_MAKE` and :term:`PARALLEL_MAKEINST` also make use of - ``EXTRA_OEMAKE`` to pass the required flags. + :term:`EXTRA_OEMAKE` to pass the required flags. :term:`EXTRA_OESCONS` When inheriting the :ref:`scons <ref-classes-scons>` class, this @@ -2293,9 +2238,8 @@ system and gives an overview of their function and contents. group configurations to a specific recipe. The set list of commands you can configure using the - ``EXTRA_USERS_PARAMS`` is shown in the ``extrausers`` class. These - commands map to the normal Unix commands of the same names: - :: + :term:`EXTRA_USERS_PARAMS` is shown in the ``extrausers`` class. These + commands map to the normal Unix commands of the same names:: # EXTRA_USERS_PARAMS = "\ # useradd -p '' tester; \ @@ -2320,20 +2264,19 @@ system and gives an overview of their function and contents. :term:`FEATURE_PACKAGES` Defines one or more packages to include in an image when a specific item is included in :term:`IMAGE_FEATURES`. - When setting the value, ``FEATURE_PACKAGES`` should have the name of - the feature item as an override. Here is an example: - :: + When setting the value, :term:`FEATURE_PACKAGES` should have the name of + the feature item as an override. Here is an example:: FEATURE_PACKAGES_widget = "package1 package2" - In this example, if "widget" were added to ``IMAGE_FEATURES``, + In this example, if "widget" were added to :term:`IMAGE_FEATURES`, package1 and package2 would be included in the image. .. note:: - Packages installed by features defined through ``FEATURE_PACKAGES`` + Packages installed by features defined through :term:`FEATURE_PACKAGES` are often package groups. While similarly named, you should not - confuse the ``FEATURE_PACKAGES`` variable with package groups, which + confuse the :term:`FEATURE_PACKAGES` variable with package groups, which are discussed elsewhere in the documentation. :term:`FEED_DEPLOYDIR_BASE_URI` @@ -2342,8 +2285,7 @@ system and gives an overview of their function and contents. OPKG to support runtime package management of IPK packages. You set this variable in your ``local.conf`` file. - Consider the following example: - :: + Consider the following example:: FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir" @@ -2359,11 +2301,10 @@ system and gives an overview of their function and contents. :term:`PACKAGES` variable lists the packages generated by a recipe. - To use the ``FILES`` variable, provide a package name override that + To use the :term:`FILES` variable, provide a package name override that identifies the resulting package. Then, provide a space-separated list of files or paths that identify the files you want included as - part of the resulting package. Here is an example: - :: + part of the resulting package. Here is an example:: FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile" @@ -2375,7 +2316,7 @@ system and gives an overview of their function and contents. syntax. For details on the syntax, see the documentation by following the previous link. - - When specifying paths as part of the ``FILES`` variable, it is + - When specifying paths as part of the :term:`FILES` variable, it is good practice to use appropriate path variables. For example, use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}`` rather than ``/usr/bin``. You can find a list of these @@ -2384,7 +2325,7 @@ system and gives an overview of their function and contents. find the default values of the various ``FILES_*`` variables in this file. - If some of the files you provide with the ``FILES`` variable are + If some of the files you provide with the :term:`FILES` variable are editable and you know they should not be overwritten during the package update process by the Package Management System (PMS), you can identify these files so that the PMS will not overwrite them. See @@ -2394,12 +2335,11 @@ system and gives an overview of their function and contents. :term:`FILES_SOLIBSDEV` Defines the file specification to match :term:`SOLIBSDEV`. In other words, - ``FILES_SOLIBSDEV`` defines the full path name of the development + :term:`FILES_SOLIBSDEV` defines the full path name of the development symbolic link (symlink) for shared libraries on the target platform. The following statement from the ``bitbake.conf`` shows how it is - set: - :: + set:: FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" @@ -2408,13 +2348,12 @@ system and gives an overview of their function and contents. looking for files and patches as it processes recipes and append files. The default directories BitBake uses when it processes recipes are initially defined by the :term:`FILESPATH` - variable. You can extend ``FILESPATH`` variable by using - ``FILESEXTRAPATHS``. + variable. You can extend :term:`FILESPATH` variable by using + :term:`FILESEXTRAPATHS`. Best practices dictate that you accomplish this by using - ``FILESEXTRAPATHS`` from within a ``.bbappend`` file and that you - prepend paths as follows: - :: + :term:`FILESEXTRAPATHS` from within a ``.bbappend`` file and that you + prepend paths as follows:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" @@ -2424,7 +2363,7 @@ system and gives an overview of their function and contents. .. note:: - When extending ``FILESEXTRAPATHS``, be sure to use the immediate + When extending :term:`FILESEXTRAPATHS`, be sure to use the immediate expansion (``:=``) operator. Immediate expansion makes sure that BitBake evaluates :term:`THISDIR` at the time the directive is encountered rather than at some later time when @@ -2436,24 +2375,21 @@ system and gives an overview of their function and contents. are directing BitBake to extend the path by prepending directories to the search path. - Here is another common use: - :: + Here is another common use:: FILESEXTRAPATHS_prepend := "${THISDIR}/files:" In this example, the build system extends the - ``FILESPATH`` variable to include a directory named ``files`` that is + :term:`FILESPATH` variable to include a directory named ``files`` that is in the same directory as the corresponding append file. - This next example specifically adds three paths: - :: + This next example specifically adds three paths:: FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" A final example shows how you can extend the search path and include a :term:`MACHINE`-specific override, which is useful - in a BSP layer: - :: + in a BSP layer:: FILESEXTRAPATHS_prepend_intel-x86-common := "${THISDIR}/${PN}:" @@ -2467,7 +2403,7 @@ system and gives an overview of their function and contents. .. note:: For a layer that supports a single BSP, the override could just be - the value of ``MACHINE``. + the value of :term:`MACHINE`. By prepending paths in ``.bbappend`` files, you allow multiple append files that reside in different layers but are used for the same @@ -2476,7 +2412,7 @@ system and gives an overview of their function and contents. :term:`FILESOVERRIDES` A subset of :term:`OVERRIDES` used by the OpenEmbedded build system for creating - :term:`FILESPATH`. The ``FILESOVERRIDES`` variable + :term:`FILESPATH`. The :term:`FILESOVERRIDES` variable uses overrides to automatically extend the :term:`FILESPATH` variable. For an example of how that works, see the :term:`FILESPATH` variable @@ -2485,14 +2421,13 @@ system and gives an overview of their function and contents. ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" section of the BitBake User Manual. - By default, the ``FILESOVERRIDES`` variable is defined as: - :: + By default, the :term:`FILESOVERRIDES` variable is defined as:: FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}" .. note:: - Do not hand-edit the ``FILESOVERRIDES`` variable. The values match up + Do not hand-edit the :term:`FILESOVERRIDES` variable. The values match up with expected overrides and are used in an expected manner by the build system. @@ -2501,49 +2436,47 @@ system and gives an overview of their function and contents. when searching for patches and files. During the build process, BitBake searches each directory in - ``FILESPATH`` in the specified order when looking for files and + :term:`FILESPATH` in the specified order when looking for files and patches specified by each ``file://`` URI in a recipe's :term:`SRC_URI` statements. - The default value for the ``FILESPATH`` variable is defined in the + The default value for the :term:`FILESPATH` variable is defined in the ``base.bbclass`` class found in ``meta/classes`` in the - :term:`Source Directory`: - :: + :term:`Source Directory`:: FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \ "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" The - ``FILESPATH`` variable is automatically extended using the overrides + :term:`FILESPATH` variable is automatically extended using the overrides from the :term:`FILESOVERRIDES` variable. .. note:: - - Do not hand-edit the ``FILESPATH`` variable. If you want the + - Do not hand-edit the :term:`FILESPATH` variable. If you want the build system to look in directories other than the defaults, - extend the ``FILESPATH`` variable by using the + extend the :term:`FILESPATH` variable by using the :term:`FILESEXTRAPATHS` variable. - - Be aware that the default ``FILESPATH`` directories do not map + - Be aware that the default :term:`FILESPATH` directories do not map to directories in custom layers where append files (``.bbappend``) are used. If you want the build system to find patches or files that reside with your append files, you need - to extend the ``FILESPATH`` variable by using the - ``FILESEXTRAPATHS`` variable. + to extend the :term:`FILESPATH` variable by using the + :term:`FILESEXTRAPATHS` variable. You can take advantage of this searching behavior in useful ways. For - example, consider a case where the following directory structure - exists for general and machine-specific configurations: - :: + example, consider a case where there is the following directory structure + for general and machine-specific configurations:: files/defconfig files/MACHINEA/defconfig files/MACHINEB/defconfig - Also in the example, the ``SRC_URI`` statement contains + Also in the example, the :term:`SRC_URI` statement contains "file://defconfig". Given this scenario, you can set :term:`MACHINE` to "MACHINEA" and cause the build - system to use files from ``files/MACHINEA``. Set ``MACHINE`` to + system to use files from ``files/MACHINEA``. Set :term:`MACHINE` to "MACHINEB" and the build system uses files from ``files/MACHINEB``. Finally, for any machine other than "MACHINEA" and "MACHINEB", the build system uses files from ``files/defconfig``. @@ -2568,7 +2501,7 @@ system and gives an overview of their function and contents. permissions setting table, you should place it in your layer or the distro's layer. - You define the ``FILESYSTEM_PERMS_TABLES`` variable in the + You define the :term:`FILESYSTEM_PERMS_TABLES` variable in the ``conf/local.conf`` file, which is found in the :term:`Build Directory`, to point to your custom ``fs-perms.txt``. You can specify more than a single file permissions @@ -2587,7 +2520,7 @@ system and gives an overview of their function and contents. :term:`FIT_GENERATE_KEYS` Decides whether to generate the keys for signing fitImage if they - don't already exist. The keys are created in ``UBOOT_SIGN_KEYDIR``. + don't already exist. The keys are created in :term:`UBOOT_SIGN_KEYDIR`. The default value is 0. :term:`FIT_HASH_ALG` @@ -2652,7 +2585,7 @@ system and gives an overview of their function and contents. Set the variable to "1" to force the removal of these packages. :term:`FULL_OPTIMIZATION` - The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when + The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when compiling an optimized system. This variable defaults to "-O2 -pipe ${DEBUG_FLAGS}". @@ -2662,16 +2595,14 @@ system and gives an overview of their function and contents. Programming (ROP) attacks much more difficult to execute. By default the ``security_flags.inc`` file enables PIE by setting the - variable as follows: - :: + variable as follows:: GCCPIE ?= "--enable-default-pie" :term:`GCCVERSION` Specifies the default version of the GNU C Compiler (GCC) used for - compilation. By default, ``GCCVERSION`` is set to "8.x" in the - ``meta/conf/distro/include/tcmode-default.inc`` include file: - :: + compilation. By default, :term:`GCCVERSION` is set to "8.x" in the + ``meta/conf/distro/include/tcmode-default.inc`` include file:: GCCVERSION ?= "8.%" @@ -2694,7 +2625,7 @@ system and gives an overview of their function and contents. If you specifically remove the locale ``en_US.UTF-8``, you must set :term:`IMAGE_LINGUAS` appropriately. - You can set ``GLIBC_GENERATE_LOCALES`` in your ``local.conf`` file. + You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file. By default, all locales are generated. :: @@ -2706,8 +2637,7 @@ system and gives an overview of their function and contents. passed to the ``groupadd`` command if you wish to add a group to the system when the package is installed. - Here is an example from the ``dbus`` recipe: - :: + Here is an example from the ``dbus`` recipe:: GROUPADD_PARAM_${PN} = "-r netdev" @@ -2737,7 +2667,7 @@ system and gives an overview of their function and contents. configuration. Use a semi-colon character (``;``) to separate multiple options. - The ``GRUB_OPTS`` variable is optional. See the + The :term:`GRUB_OPTS` variable is optional. See the :ref:`grub-efi <ref-classes-grub-efi>` class for more information on how this variable is used. @@ -2745,7 +2675,7 @@ system and gives an overview of their function and contents. Specifies the timeout before executing the default ``LABEL`` in the GNU GRand Unified Bootloader (GRUB). - The ``GRUB_TIMEOUT`` variable is optional. See the + The :term:`GRUB_TIMEOUT` variable is optional. See the :ref:`grub-efi <ref-classes-grub-efi>` class for more information on how this variable is used. @@ -2779,7 +2709,7 @@ system and gives an overview of their function and contents. Specifies architecture-specific compiler flags that are passed to the C compiler. - Default initialization for ``HOST_CC_ARCH`` varies depending on what + Default initialization for :term:`HOST_CC_ARCH` varies depending on what is being built: - :term:`TARGET_CC_ARCH` when building for the @@ -2799,7 +2729,7 @@ system and gives an overview of their function and contents. "linux-musleabi" values possible. :term:`HOST_PREFIX` - Specifies the prefix for the cross-compile toolchain. ``HOST_PREFIX`` + Specifies the prefix for the cross-compile toolchain. :term:`HOST_PREFIX` is normally the same as :term:`TARGET_PREFIX`. :term:`HOST_SYS` @@ -2828,7 +2758,7 @@ system and gives an overview of their function and contents. A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks. Using this filter helps reduce the possibility of host contamination. If a tool - specified in the value of ``HOSTTOOLS`` is not found on the build + specified in the value of :term:`HOSTTOOLS` is not found on the build host, the OpenEmbedded build system produces an error and the build is not started. @@ -2841,11 +2771,11 @@ system and gives an overview of their function and contents. filter helps reduce the possibility of host contamination. Unlike :term:`HOSTTOOLS`, the OpenEmbedded build system does not produce an error if a tool specified in the value of - ``HOSTTOOLS_NONFATAL`` is not found on the build host. Thus, you can - use ``HOSTTOOLS_NONFATAL`` to filter optional host tools. + :term:`HOSTTOOLS_NONFATAL` is not found on the build host. Thus, you can + use :term:`HOSTTOOLS_NONFATAL` to filter optional host tools. :term:`HOST_VENDOR` - Specifies the name of the vendor. ``HOST_VENDOR`` is normally the + Specifies the name of the vendor. :term:`HOST_VENDOR` is normally the same as :term:`TARGET_VENDOR`. :term:`ICECC_DISABLED` @@ -2855,13 +2785,11 @@ system and gives an overview of their function and contents. section. Setting this variable to "1" in your ``local.conf`` disables the - function: - :: + function:: ICECC_DISABLED ??= "1" - To enable the function, set the variable as follows: - :: + To enable the function, set the variable as follows:: ICECC_DISABLED = "" @@ -2892,12 +2820,12 @@ system and gives an overview of their function and contents. network lag, available memory, and existing machine loads can all affect build time. Consequently, unlike the :term:`PARALLEL_MAKE` variable, there is no - rule-of-thumb for setting ``ICECC_PARALLEL_MAKE`` to achieve optimal + rule-of-thumb for setting :term:`ICECC_PARALLEL_MAKE` to achieve optimal performance. - If you do not set ``ICECC_PARALLEL_MAKE``, the build system does not + If you do not set :term:`ICECC_PARALLEL_MAKE`, the build system does not use it (i.e. the system does not detect and assign the number of - cores as is done with ``PARALLEL_MAKE``). + cores as is done with :term:`PARALLEL_MAKE`). :term:`ICECC_PATH` The location of the ``icecc`` binary. You can set this variable in @@ -2946,8 +2874,7 @@ system and gives an overview of their function and contents. installed name, separate it from the original name with a semi-colon (;). Source files need to be located in :term:`DEPLOY_DIR_IMAGE`. Here are two - examples: - :: + examples:: IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2" IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio" @@ -2956,8 +2883,7 @@ system and gives an overview of their function and contents. this case, the destination file must have the same name as the base name of the source file path. To install files into a directory within the target location, pass its name after a semi-colon (;). - Here are two examples: - :: + Here are two examples:: IMAGE_EFI_BOOT_FILES = "boot/loader/*" IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/" @@ -2982,8 +2908,7 @@ system and gives an overview of their function and contents. installed name, separate it from the original name with a semi-colon (;). Source files need to be located in :term:`DEPLOY_DIR_IMAGE`. Here are two - examples: - :: + examples:: IMAGE_BOOT_FILES = "u-boot.img uImage;kernel" IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}" @@ -2992,8 +2917,7 @@ system and gives an overview of their function and contents. this case, the destination file must have the same name as the base name of the source file path. To install files into a directory within the target location, pass its name after a semi-colon (;). - Here are two examples: - :: + Here are two examples:: IMAGE_BOOT_FILES = "bcm2835-bootfiles/*" IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/" @@ -3014,7 +2938,7 @@ system and gives an overview of their function and contents. this variable to specify the list of classes that register the different types of images the OpenEmbedded build system creates. - The default value for ``IMAGE_CLASSES`` is ``image_types``. You can + The default value for :term:`IMAGE_CLASSES` is ``image_types``. You can set this variable in your ``local.conf`` or in a distribution configuration file. @@ -3026,11 +2950,10 @@ system and gives an overview of their function and contents. type, which corresponds to the value set in :term:`IMAGE_FSTYPES`, (e.g. ``ext3``, ``btrfs``, and so forth). When setting this variable, you should use - an override for the associated type. Here is an example: - :: + an override for the associated type. Here is an example:: - IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \ - --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \ + IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} --faketime \ + --output=${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.jffs2 \ ${EXTRA_IMAGECMD}" You typically do not need to set this variable unless you are adding @@ -3042,7 +2965,7 @@ system and gives an overview of their function and contents. Specifies one or more files that contain custom device tables that are passed to the ``makedevs`` command as part of creating an image. These files list basic device nodes that should be created under - ``/dev`` within the image. If ``IMAGE_DEVICE_TABLES`` is not set, + ``/dev`` within the image. If :term:`IMAGE_DEVICE_TABLES` is not set, ``files/device_table-minimal.txt`` is used, which is located by :term:`BBPATH`. For details on how you should write device table files, see ``meta/files/device_table-minimal.txt`` as an @@ -3070,9 +2993,8 @@ system and gives an overview of their function and contents. :term:`IMAGE_FSTYPES` Specifies the formats the OpenEmbedded build system uses during the build when creating the root filesystem. For example, setting - ``IMAGE_FSTYPES`` as follows causes the build system to create root - filesystems using two formats: ``.ext3`` and ``.tar.bz2``: - :: + :term:`IMAGE_FSTYPES` as follows causes the build system to create root + filesystems using two formats: ``.ext3`` and ``.tar.bz2``:: IMAGE_FSTYPES = "ext3 tar.bz2" @@ -3082,29 +3004,28 @@ system and gives an overview of their function and contents. .. note:: - If an image recipe uses the "inherit image" line and you are - setting ``IMAGE_FSTYPES`` inside the recipe, you must set + setting :term:`IMAGE_FSTYPES` inside the recipe, you must set ``IMAGE_FSTYPES`` prior to using the "inherit image" line. - Due to the way the OpenEmbedded build system processes this variable, you cannot update its contents by using ``_append`` or ``_prepend``. You must use the ``+=`` operator to add one or - more options to the ``IMAGE_FSTYPES`` variable. + more options to the :term:`IMAGE_FSTYPES` variable. :term:`IMAGE_INSTALL` Used by recipes to specify the packages to install into an image through the :ref:`image <ref-classes-image>` class. Use the - ``IMAGE_INSTALL`` variable with care to avoid ordering issues. + :term:`IMAGE_INSTALL` variable with care to avoid ordering issues. - Image recipes set ``IMAGE_INSTALL`` to specify the packages to + Image recipes set :term:`IMAGE_INSTALL` to specify the packages to install into an image through ``image.bbclass``. Additionally, - "helper" classes such as the - :ref:`core-image <ref-classes-core-image>` class exist that can - take lists used with ``IMAGE_FEATURES`` and turn them into - auto-generated entries in ``IMAGE_INSTALL`` in addition to its + there are "helper" classes such as the + :ref:`core-image <ref-classes-core-image>` class which can + take lists used with :term:`IMAGE_FEATURES` and turn them into + auto-generated entries in :term:`IMAGE_INSTALL` in addition to its default contents. - When you use this variable, it is best to use it as follows: - :: + When you use this variable, it is best to use it as follows:: IMAGE_INSTALL_append = " package-name" @@ -3116,24 +3037,24 @@ system and gives an overview of their function and contents. - When working with a :ref:`core-image-minimal-initramfs <ref-manual/images:images>` - image, do not use the ``IMAGE_INSTALL`` variable to specify + 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 - fixed set of packages and not be affected by ``IMAGE_INSTALL``. + 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`" section in the Yocto Project Development Tasks Manual. - - Using ``IMAGE_INSTALL`` with the + - Using :term:`IMAGE_INSTALL` with the :ref:`+= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>` BitBake operator within the ``/conf/local.conf`` file or from within an image recipe is not recommended. Use of this operator in these ways can cause ordering issues. Since - ``core-image.bbclass`` sets ``IMAGE_INSTALL`` to a default + ``core-image.bbclass`` sets :term:`IMAGE_INSTALL` to a default value using the :ref:`?= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>` - operator, using a ``+=`` operation against ``IMAGE_INSTALL`` + operator, using a ``+=`` operation against :term:`IMAGE_INSTALL` results in unexpected behavior when used within ``conf/local.conf``. Furthermore, the same operation from within an image recipe may or may not succeed depending on the @@ -3144,11 +3065,10 @@ system and gives an overview of their function and contents. Specifies the list of locales to install into the image during the root filesystem construction process. The OpenEmbedded build system automatically splits locale files, which are used for localization, - into separate packages. Setting the ``IMAGE_LINGUAS`` variable + into separate packages. Setting the :term:`IMAGE_LINGUAS` variable ensures that any locale packages that correspond to packages already selected for installation into the image are also installed. Here is - an example: - :: + an example:: IMAGE_LINGUAS = "pt-br de-de" @@ -3167,8 +3087,7 @@ system and gives an overview of their function and contents. The name of the output image symlink (which does not include the version part as :term:`IMAGE_NAME` does). The default value is derived using the :term:`IMAGE_BASENAME` and :term:`MACHINE` - variables: - :: + variables:: IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}-${MACHINE}" @@ -3176,19 +3095,17 @@ system and gives an overview of their function and contents. :term:`IMAGE_MANIFEST` The manifest file for the image. This file lists all the installed packages that make up the image. The file contains package - information on a line-per-package basis as follows: - :: + information on a line-per-package basis as follows:: packagename packagearch version - The :ref:`image <ref-classes-image>` class defines the manifest - file as follows: - :: + The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class defines the manifest + file as follows:: - IMAGE_MANIFEST ="${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest" + IMAGE_MANIFEST ="${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.manifest" The location is - derived using the :term:`DEPLOY_DIR_IMAGE` + derived using the :term:`IMGDEPLOYDIR` and :term:`IMAGE_NAME` variables. You can find information on how the image is created in the ":ref:`overview-manual/concepts:image generation`" section in the Yocto Project Overview and Concepts Manual. @@ -3197,8 +3114,7 @@ system and gives an overview of their function and contents. The name of the output image files minus the extension. This variable is derived using the :term:`IMAGE_BASENAME`, :term:`MACHINE`, and :term:`IMAGE_VERSION_SUFFIX` - variables: - :: + variables:: IMAGE_NAME ?= "${IMAGE_BASENAME}-${MACHINE}${IMAGE_VERSION_SUFFIX}" @@ -3213,7 +3129,7 @@ system and gives an overview of their function and contents. Defines a multiplier that the build system applies to the initial image size for cases when the multiplier times the returned disk usage value for the image is greater than the sum of - ``IMAGE_ROOTFS_SIZE`` and ``IMAGE_ROOTFS_EXTRA_SPACE``. The result of + :term:`IMAGE_ROOTFS_SIZE` and :term:`IMAGE_ROOTFS_EXTRA_SPACE`. The result of the multiplier applied to the initial image size creates free disk space in the image as overhead. By default, the build process uses a multiplier of 1.3 for this variable. This default value results in @@ -3222,20 +3138,19 @@ system and gives an overview of their function and contents. post install scripts and the package management system uses disk space inside this overhead area. Consequently, the multiplier does not produce an image with all the theoretical free disk space. See - ``IMAGE_ROOTFS_SIZE`` for information on how the build system + :term:`IMAGE_ROOTFS_SIZE` for information on how the build system determines the overall image size. The default 30% free disk space typically gives the image enough room to boot and allows for basic post installs while still leaving a small amount of free disk space. If 30% free space is inadequate, you can increase the default value. For example, the following setting - gives you 50% free space added to the image: - :: + gives you 50% free space added to the image:: IMAGE_OVERHEAD_FACTOR = "1.5" Alternatively, you can ensure a specific amount of free disk space is - added to the image by using the ``IMAGE_ROOTFS_EXTRA_SPACE`` + added to the image by using the :term:`IMAGE_ROOTFS_EXTRA_SPACE` variable. :term:`IMAGE_PKGTYPE` @@ -3252,10 +3167,10 @@ system and gives an overview of their function and contents. recommended that you do not use it. The :ref:`populate_sdk_* <ref-classes-populate-sdk-*>` and - :ref:`image <ref-classes-image>` classes use the ``IMAGE_PKGTYPE`` + :ref:`image <ref-classes-image>` classes use the :term:`IMAGE_PKGTYPE` for packaging up images and SDKs. - You should not set the ``IMAGE_PKGTYPE`` manually. Rather, the + You should not set the :term:`IMAGE_PKGTYPE` manually. Rather, the variable is set indirectly through the appropriate :ref:`package_* <ref-classes-package>` class using the :term:`PACKAGE_CLASSES` variable. The @@ -3271,8 +3186,7 @@ system and gives an overview of their function and contents. :term:`IMAGE_POSTPROCESS_COMMAND` Specifies a list of functions to call once the OpenEmbedded build system creates the final image output files. You can specify - functions separated by semicolons: - :: + functions separated by semicolons:: IMAGE_POSTPROCESS_COMMAND += "function; ... " @@ -3285,8 +3199,7 @@ system and gives an overview of their function and contents. :term:`IMAGE_PREPROCESS_COMMAND` Specifies a list of functions to call before the OpenEmbedded build system creates the final image output files. You can specify - functions separated by semicolons: - :: + functions separated by semicolons:: IMAGE_PREPROCESS_COMMAND += "function; ... " @@ -3312,19 +3225,17 @@ system and gives an overview of their function and contents. Defines additional free disk space created in the image in Kbytes. By default, this variable is set to "0". This free disk space is added to the image after the build system determines the image size as - described in ``IMAGE_ROOTFS_SIZE``. + described in :term:`IMAGE_ROOTFS_SIZE`. This variable is particularly useful when you want to ensure that a specific amount of free disk space is available on a device after an image is installed and running. For example, to be sure 5 Gbytes of - free disk space is available, set the variable as follows: - :: + free disk space is available, set the variable as follows:: IMAGE_ROOTFS_EXTRA_SPACE = "5242880" For example, the Yocto Project Build Appliance specifically requests - 40 Gbytes of extra space with the line: - :: + 40 Gbytes of extra space with the line:: IMAGE_ROOTFS_EXTRA_SPACE = "41943040" @@ -3335,8 +3246,7 @@ system and gives an overview of their function and contents. the generated image, a requested size for the image, and requested additional free disk space to be added to the image. Programatically, the build system determines the final size of the generated image as - follows: - :: + follows:: if (image-du * overhead) < rootfs-size: internal-rootfs-size = rootfs-size + xspace @@ -3355,8 +3265,7 @@ system and gives an overview of their function and contents. :term:`IMAGE_TYPEDEP` Specifies a dependency from one image type on another. Here is an - example from the :ref:`image-live <ref-classes-image-live>` class: - :: + example from the :ref:`image-live <ref-classes-image-live>` class:: IMAGE_TYPEDEP_live = "ext3" @@ -3377,6 +3286,9 @@ system and gives an overview of their function and contents. - cpio.lzma - cpio.xz - cramfs + - erofs + - erofs-lz4 + - erofs-lz4hc - ext2 - ext2.bz2 - ext2.gz @@ -3419,6 +3331,18 @@ system and gives an overview of their function and contents. desired, and this suffix would then be used consistently across the build artifacts. + :term:`IMGDEPLOYDIR` + When inheriting the :ref:`image <ref-classes-image>` class directly or + through the :ref:`core-image <ref-classes-core-image>` class, the + ``IMGDEPLOYDIR`` points to a temporary work area for deployed files + that is set in the ``image`` class as follows:: + + IMGDEPLOYDIR = "${WORKDIR}/deploy-${PN}-image-complete" + + Recipes inheriting the ``image`` class should copy files to be + deployed into ``IMGDEPLOYDIR``, and the class will take care of + copying them into :term:`DEPLOY_DIR_IMAGE` afterwards. + :term:`INC_PR` Helps define the recipe revision for recipes that share a common ``include`` file. You can think of this variable as part of the @@ -3434,17 +3358,16 @@ system and gives an overview of their function and contents. common functionality are upgraded to a new revision. A more efficient way of dealing with this situation is to set the - ``INC_PR`` variable inside the ``include`` files that the recipes - share and then expand the ``INC_PR`` variable within the recipes to + :term:`INC_PR` variable inside the ``include`` files that the recipes + share and then expand the :term:`INC_PR` variable within the recipes to help define the recipe revision. The following provides an example that shows how to use the - ``INC_PR`` variable given a common ``include`` file that defines the + :term:`INC_PR` variable given a common ``include`` file that defines the variable. Once the variable is defined in the ``include`` file, you - can use the variable to set the ``PR`` values in each recipe. You - will notice that when you set a recipe's ``PR`` you can provide more - granular revisioning by appending values to the ``INC_PR`` variable: - :: + can use the variable to set the :term:`PR` values in each recipe. You + will notice that when you set a recipe's :term:`PR` you can provide more + granular revisioning by appending values to the :term:`INC_PR` variable:: recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1" @@ -3455,7 +3378,7 @@ system and gives an overview of their function and contents. first line of the example establishes the baseline revision to be used for all recipes that use the ``include`` file. The remaining lines in the example are from individual recipes and show how the - ``PR`` value is set. + :term:`PR` value is set. :term:`INCOMPATIBLE_LICENSE` Specifies a space-separated list of license names (as they would @@ -3467,8 +3390,7 @@ system and gives an overview of their function and contents. .. note:: This functionality is only regularly tested using the following - setting: - :: + setting:: INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" @@ -3482,13 +3404,12 @@ system and gives an overview of their function and contents. It is possible to define a list of licenses that are allowed to be used instead of the licenses that are excluded. To do this, define a variable ``COMPATIBLE_LICENSES`` with the names of the licenses - that are allowed. Then define ``INCOMPATIBLE_LICENSE`` as: - :: + that are allowed. Then define :term:`INCOMPATIBLE_LICENSE` as:: INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}" - This will result in ``INCOMPATIBLE_LICENSE`` containing the names of + This will result in :term:`INCOMPATIBLE_LICENSE` containing the names of all licenses from :term:`AVAILABLE_LICENSES` except the ones specified in ``COMPATIBLE_LICENSES``, thus only allowing the latter licenses to be used. @@ -3497,9 +3418,9 @@ system and gives an overview of their function and contents. Causes the named class or classes to be inherited globally. Anonymous functions in the class or classes are not executed for the base configuration and in each individual recipe. The OpenEmbedded build - system ignores changes to ``INHERIT`` in individual recipes. + system ignores changes to :term:`INHERIT` in individual recipes. - For more information on ``INHERIT``, see the + For more information on :term:`INHERIT`, see the :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" section in the Bitbake User Manual. @@ -3508,8 +3429,7 @@ system and gives an overview of their function and contents. unlikely that you want to edit this variable. The default value of the variable is set as follows in the - ``meta/conf/distro/defaultsetup.conf`` file: - :: + ``meta/conf/distro/defaultsetup.conf`` file:: INHERIT_DISTRO ?= "debian devshell sstate license" @@ -3532,9 +3452,8 @@ system and gives an overview of their function and contents. variable. To prevent the build system from splitting out debug information - during packaging, set the ``INHIBIT_PACKAGE_DEBUG_SPLIT`` variable as - follows: - :: + during packaging, set the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable as + follows:: INHIBIT_PACKAGE_DEBUG_SPLIT = "1" @@ -3545,7 +3464,7 @@ system and gives an overview of their function and contents. By default, the OpenEmbedded build system strips binaries and puts the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``. - Consequently, you should not set ``INHIBIT_PACKAGE_STRIP`` when you + Consequently, you should not set :term:`INHIBIT_PACKAGE_STRIP` when you plan to debug in general. :term:`INHIBIT_SYSROOT_STRIP` @@ -3554,7 +3473,7 @@ system and gives an overview of their function and contents. By default, the OpenEmbedded build system strips binaries in the resulting sysroot. When you specifically set the - ``INHIBIT_SYSROOT_STRIP`` variable to "1" in your recipe, you inhibit + :term:`INHIBIT_SYSROOT_STRIP` variable to "1" in your recipe, you inhibit this stripping. If you want to use this variable, include the @@ -3564,11 +3483,11 @@ system and gives an overview of their function and contents. .. note:: - Use of the ``INHIBIT_SYSROOT_STRIP`` variable occurs in rare and + Use of the :term:`INHIBIT_SYSROOT_STRIP` variable occurs in rare and special circumstances. For example, suppose you are building bare-metal firmware by using an external GCC toolchain. Furthermore, - even if the toolchain's binaries are strippable, other files exist - that are needed for the build that are not strippable. + even if the toolchain's binaries are strippable, there are other files + needed for the build that are not strippable. :term:`INITRAMFS_FSTYPES` Defines the format for the output image of an initial RAM filesystem @@ -3586,7 +3505,7 @@ system and gives an overview of their function and contents. :term:`INITRAMFS_IMAGE` Specifies the :term:`PROVIDES` name of an image recipe that is used to build an initial RAM filesystem (initramfs) - image. In other words, the ``INITRAMFS_IMAGE`` variable causes an + 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 @@ -3602,16 +3521,16 @@ 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 ``INITRAMFS_IMAGE`` + the one built to provide the initramfs image, set :term:`INITRAMFS_IMAGE` to "core-image-minimal-initramfs". You can also find more information by referencing the ``meta-poky/conf/local.conf.sample.extended`` configuration file in the Source Directory, the :ref:`image <ref-classes-image>` class, and the :ref:`kernel <ref-classes-kernel>` class to see how to use - the ``INITRAMFS_IMAGE`` variable. + the :term:`INITRAMFS_IMAGE` variable. - If ``INITRAMFS_IMAGE`` is empty, which is the default, then no + If :term:`INITRAMFS_IMAGE` is empty, which is the default, then no initramfs image is built. For more information, you can also see the @@ -3646,21 +3565,19 @@ system and gives an overview of their function and contents. Setting the variable to "1" in a configuration file causes the OpenEmbedded build system to generate a kernel image with the - initramfs specified in ``INITRAMFS_IMAGE`` bundled within: - :: + initramfs specified in :term:`INITRAMFS_IMAGE` bundled within:: INITRAMFS_IMAGE_BUNDLE = "1" By default, the :ref:`kernel <ref-classes-kernel>` class sets this variable to a - null string as follows: - :: + null string as follows:: INITRAMFS_IMAGE_BUNDLE ?= "" .. note:: - You must set the ``INITRAMFS_IMAGE_BUNDLE`` variable in a + You must set the :term:`INITRAMFS_IMAGE_BUNDLE` variable in a configuration file. You cannot set the variable in a recipe file. See the @@ -3672,15 +3589,13 @@ system and gives an overview of their function and contents. :term:`INITRAMFS_LINK_NAME` The link name of the initial RAM filesystem image. This variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as - follows: - :: + follows:: INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}" The value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same - file, has the following value: - :: + file, has the following value:: KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" @@ -3690,14 +3605,12 @@ system and gives an overview of their function and contents. :term:`INITRAMFS_NAME` The base name of the initial RAM filesystem image. This variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as - follows: - :: + follows:: INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}" The value of the :term:`KERNEL_ARTIFACT_NAME` - variable, which is set in the same file, has the following value: - :: + variable, which is set in the same file, has the following value:: KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" @@ -3705,13 +3618,13 @@ system and gives an overview of their function and contents. Indicates list of filesystem images to concatenate and use as an initial RAM disk (``initrd``). - The ``INITRD`` variable is an optional variable used with the + The :term:`INITRD` variable is an optional variable used with the :ref:`image-live <ref-classes-image-live>` class. :term:`INITRD_IMAGE` When building a "live" bootable image (i.e. when :term:`IMAGE_FSTYPES` contains "live"), - ``INITRD_IMAGE`` specifies the image recipe that should be built to + :term:`INITRD_IMAGE` specifies the image recipe that should be built to provide the initial RAM disk image. The default value is "core-image-minimal-initramfs". @@ -3735,8 +3648,7 @@ system and gives an overview of their function and contents. variable. :term:`INITSCRIPT_PARAMS` - Specifies the options to pass to ``update-rc.d``. Here is an example: - :: + Specifies the options to pass to ``update-rc.d``. Here is an example:: INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ." @@ -3746,7 +3658,7 @@ system and gives an overview of their function and contents. The variable's default value is "defaults", which is set in the :ref:`update-rc.d <ref-classes-update-rc.d>` class. - The value in ``INITSCRIPT_PARAMS`` is passed through to the + The value in :term:`INITSCRIPT_PARAMS` is passed through to the ``update-rc.d`` command. For more information on valid parameters, please see the ``update-rc.d`` manual page at https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html @@ -3756,8 +3668,7 @@ system and gives an overview of their function and contents. recipe. For example, to skip the check for symbolic link ``.so`` files in the main package of a recipe, add the following to the recipe. The package name override must be used, which in this example - is ``${PN}``: - :: + is ``${PN}``:: INSANE_SKIP_${PN} += "dev-so" @@ -3766,7 +3677,7 @@ system and gives an overview of their function and contents. :term:`INSTALL_TIMEZONE_FILE` By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file. - Set the ``INSTALL_TIMEZONE_FILE`` variable to "0" at the + Set the :term:`INSTALL_TIMEZONE_FILE` variable to "0" at the configuration level to disable this behavior. :term:`IPK_FEED_URIS` @@ -3798,9 +3709,8 @@ system and gives an overview of their function and contents. Values for this variable are set in the kernel's recipe file and the kernel's append file. For example, if you are using the ``linux-yocto_4.12`` kernel, the kernel recipe file is the - ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. ``KBRANCH`` - is set as follows in that kernel recipe file: - :: + ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. :term:`KBRANCH` + is set as follows in that kernel recipe file:: KBRANCH ?= "standard/base" @@ -3812,15 +3722,14 @@ system and gives an overview of their function and contents. Beaglebone, EdgeRouter, and generic versions of both 32 and 64-bit IA machines (``meta-yocto-bsp``) is named ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend``. - Here are the related statements from that append file: - :: + Here are the related statements from that append file:: KBRANCH_genericx86 = "standard/base" KBRANCH_genericx86-64 = "standard/base" KBRANCH_edgerouter = "standard/edgerouter" KBRANCH_beaglebone = "standard/beaglebone" - The ``KBRANCH`` statements + The :term:`KBRANCH` statements identify the kernel branch to use when building for each supported BSP. @@ -3834,32 +3743,67 @@ system and gives an overview of their function and contents. would place patch files and configuration fragment files (i.e. "out-of-tree"). However, if you want to use a ``defconfig`` file that is part of the kernel tree (i.e. "in-tree"), you can use the - ``KBUILD_DEFCONFIG`` variable and append the + :term:`KBUILD_DEFCONFIG` variable and append the :term:`KMACHINE` variable to point to the ``defconfig`` file. To use the variable, set it in the append file for your kernel recipe - using the following form: - :: + using the following form:: KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file - Here is an example from a "raspberrypi2" ``KMACHINE`` build that uses - a ``defconfig`` file named "bcm2709_defconfig": - :: + Here is an example from a "raspberrypi2" :term:`KMACHINE` build that uses + a ``defconfig`` file named "bcm2709_defconfig":: KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig" - As an alternative, you can use the following within your append file: - :: + As an alternative, you can use the following within your append file:: KBUILD_DEFCONFIG_pn-linux-yocto ?= defconfig_file For more - information on how to use the ``KBUILD_DEFCONFIG`` variable, see the + information on how to use the :term:`KBUILD_DEFCONFIG` variable, see the ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`" section in the Yocto Project Linux Kernel Development Manual. + :term:`KCONFIG_MODE` + When used with the :ref:`kernel-yocto <ref-classes-kernel-yocto>` + class, specifies the kernel configuration values to use for options + not specified in the provided ``defconfig`` file. Valid options are:: + + KCONFIG_MODE = "alldefconfig" + KCONFIG_MODE = "allnoconfig" + + In ``alldefconfig`` mode the options not explicitly specified will be + assigned their Kconfig default value. In ``allnoconfig`` mode the + options not explicitly specified will be disabled in the kernel + config. + + In case :term:`KCONFIG_MODE` is not set the behaviour will depend on where + the ``defconfig`` file is coming from. An "in-tree" ``defconfig`` file + will be handled in ``alldefconfig`` mode, a ``defconfig`` file placed + in ``${WORKDIR}`` through a meta-layer will be handled in + ``allnoconfig`` mode. + + An "in-tree" ``defconfig`` file can be selected via the + :term:`KBUILD_DEFCONFIG` variable. :term:`KCONFIG_MODE` does not need to + be explicitly set. + + A ``defconfig`` file compatible with ``allnoconfig`` mode can be + generated by copying the ``.config`` file from a working Linux kernel + build, renaming it to ``defconfig`` and placing it into the Linux + kernel ``${WORKDIR}`` through your meta-layer. :term:`KCONFIG_MODE` does + not need to be explicitly set. + + A ``defconfig`` file compatible with ``alldefconfig`` mode can be + generated using the + :ref:`ref-tasks-savedefconfig` + task and placed into the Linux kernel ``${WORKDIR}`` through your + meta-layer. Explicitely set :term:`KCONFIG_MODE`:: + + KCONFIG_MODE = "alldefconfig" + + :term:`KERNEL_ALT_IMAGETYPE` Specifies an alternate kernel image type for creation in addition to the kernel image type specified using the @@ -3867,13 +3811,12 @@ system and gives an overview of their function and contents. :term:`KERNEL_ARTIFACT_NAME` Specifies the name of all of the build artifacts. You can change the - name of the artifacts by changing the ``KERNEL_ARTIFACT_NAME`` + name of the artifacts by changing the :term:`KERNEL_ARTIFACT_NAME` variable. - The value of ``KERNEL_ARTIFACT_NAME``, which is set in the + The value of :term:`KERNEL_ARTIFACT_NAME`, which is set in the ``meta/classes/kernel-artifact-names.bbclass`` file, has the - following default value: - :: + following default value:: KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" @@ -3895,7 +3838,7 @@ system and gives an overview of their function and contents. .. note:: - Legacy support exists for specifying the full path to the device + There is legacy support for specifying the full path to the device tree. However, providing just the ``.dtb`` file is preferred. In order to use this variable, the @@ -3905,15 +3848,13 @@ system and gives an overview of their function and contents. :term:`KERNEL_DTB_LINK_NAME` The link name of the kernel device tree binary (DTB). This variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as - follows: - :: + follows:: KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" The value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in - the same file, has the following value: - :: + the same file, has the following value:: KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" @@ -3923,14 +3864,12 @@ system and gives an overview of their function and contents. :term:`KERNEL_DTB_NAME` The base name of the kernel device tree binary (DTB). This variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as - follows: - :: + follows:: KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}" The value of the :term:`KERNEL_ARTIFACT_NAME` - variable, which is set in the same file, has the following value: - :: + variable, which is set in the same file, has the following value:: KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" @@ -3952,21 +3891,20 @@ system and gives an overview of their function and contents. system, the default Board Support Packages (BSPs) :term:`Metadata` is provided through the :term:`KMACHINE` and :term:`KBRANCH` - variables. You can use the ``KERNEL_FEATURES`` variable from within + variables. You can use the :term:`KERNEL_FEATURES` variable from within the kernel recipe or kernel append file to further add metadata for all BSPs or specific BSPs. The metadata you add through this variable includes config fragments and features descriptions, which usually includes patches as well as - config fragments. You typically override the ``KERNEL_FEATURES`` + config fragments. You typically override the :term:`KERNEL_FEATURES` variable for a specific machine. In this way, you can provide validated, but optional, sets of kernel configurations and features. For example, the following example from the ``linux-yocto-rt_4.12`` kernel recipe adds "netfilter" and "taskstats" features to all BSPs as well as "virtio" configurations to all QEMU machines. The last two - statements add specific configurations to targeted machine types: - :: + statements add specific configurations to targeted machine types:: KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc" KERNEL_FEATURES_append = "${KERNEL_EXTRA_FEATURES}" @@ -3977,15 +3915,13 @@ system and gives an overview of their function and contents. :term:`KERNEL_FIT_LINK_NAME` The link name of the kernel flattened image tree (FIT) image. This variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` - file as follows: - :: + file as follows:: KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" The value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same - file, has the following value: - :: + file, has the following value:: KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" @@ -3995,28 +3931,24 @@ system and gives an overview of their function and contents. :term:`KERNEL_FIT_NAME` The base name of the kernel flattened image tree (FIT) image. This variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` - file as follows: - :: + file as follows:: KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}" The value of the :term:`KERNEL_ARTIFACT_NAME` - variable, which is set in the same file, has the following value: - :: + variable, which is set in the same file, has the following value:: KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" :term:`KERNEL_IMAGE_LINK_NAME` The link name for the kernel image. This variable is set in the - ``meta/classes/kernel-artifact-names.bbclass`` file as follows: - :: + ``meta/classes/kernel-artifact-names.bbclass`` file as follows:: KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" The value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same - file, has the following value: - :: + file, has the following value:: KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" @@ -4025,12 +3957,12 @@ system and gives an overview of their function and contents. :term:`KERNEL_IMAGE_MAXSIZE` Specifies the maximum size of the kernel image file in kilobytes. If - ``KERNEL_IMAGE_MAXSIZE`` is set, the size of the kernel image file is + :term:`KERNEL_IMAGE_MAXSIZE` is set, the size of the kernel image file is checked against the set value during the :ref:`ref-tasks-sizecheck` task. The task fails if the kernel image file is larger than the setting. - ``KERNEL_IMAGE_MAXSIZE`` is useful for target devices that have a + :term:`KERNEL_IMAGE_MAXSIZE` is useful for target devices that have a limited amount of space in which the kernel image must be stored. By default, this variable is not set, which means the size of the @@ -4038,15 +3970,13 @@ system and gives an overview of their function and contents. :term:`KERNEL_IMAGE_NAME` The base name of the kernel image. This variable is set in the - ``meta/classes/kernel-artifact-names.bbclass`` file as follows: - :: + ``meta/classes/kernel-artifact-names.bbclass`` file as follows:: KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}" The value of the :term:`KERNEL_ARTIFACT_NAME` variable, - which is set in the same file, has the following value: - :: + which is set in the same file, has the following value:: KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" @@ -4057,7 +3987,7 @@ system and gives an overview of their function and contents. build. If you want to build an alternate kernel image type in addition to that - specified by ``KERNEL_IMAGETYPE``, use the :term:`KERNEL_ALT_IMAGETYPE` + specified by :term:`KERNEL_IMAGETYPE`, use the :term:`KERNEL_ALT_IMAGETYPE` variable. :term:`KERNEL_MODULE_AUTOLOAD` @@ -4068,23 +3998,21 @@ system and gives an overview of their function and contents. This variable replaces the deprecated :term:`module_autoload` variable. - You can use the ``KERNEL_MODULE_AUTOLOAD`` variable anywhere that it + You can use the :term:`KERNEL_MODULE_AUTOLOAD` variable anywhere that it can be recognized by the kernel recipe or by an out-of-tree kernel module recipe (e.g. a machine configuration file, a distribution configuration file, an append file for the recipe, or the recipe itself). - Specify it as follows: - :: + Specify it as follows:: KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3" - Including ``KERNEL_MODULE_AUTOLOAD`` causes the OpenEmbedded build + Including :term:`KERNEL_MODULE_AUTOLOAD` causes the OpenEmbedded build system to populate the ``/etc/modules-load.d/modname.conf`` file with the list of modules to be auto-loaded on boot. The modules appear one-per-line in the file. Here is an example of the most common use - case: - :: + case:: KERNEL_MODULE_AUTOLOAD += "module_name" @@ -4109,7 +4037,7 @@ system and gives an overview of their function and contents. To help maximize compatibility with out-of-tree drivers used to build modules, the OpenEmbedded build system also recognizes and uses the :term:`KERNEL_SRC` variable, which is identical to - the ``KERNEL_PATH`` variable. Both variables are common variables + the :term:`KERNEL_PATH` variable. Both variables are common variables used by external Makefiles to point to the kernel source directory. :term:`KERNEL_SRC` @@ -4123,7 +4051,7 @@ system and gives an overview of their function and contents. To help maximize compatibility with out-of-tree drivers used to build modules, the OpenEmbedded build system also recognizes and uses the :term:`KERNEL_PATH` variable, which is identical - to the ``KERNEL_SRC`` variable. Both variables are common variables + to the :term:`KERNEL_SRC` variable. Both variables are common variables used by external Makefiles to point to the kernel source directory. :term:`KERNEL_VERSION` @@ -4135,10 +4063,10 @@ system and gives an overview of their function and contents. :term:`KERNELDEPMODDEPEND` Specifies whether the data referenced through - :term:`PKGDATA_DIR` is needed or not. The - ``KERNELDEPMODDEPEND`` does not control whether or not that data + :term:`PKGDATA_DIR` is needed or not. + :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 ``KERNELDEPMODDEPEND`` variable in your + use the data, set the :term:`KERNELDEPMODDEPEND` variable in your ``initramfs`` recipe. Setting the variable there when the data is not needed avoids a potential dependency loop. @@ -4146,8 +4074,7 @@ system and gives an overview of their function and contents. Provides a short description of a configuration fragment. You use this variable in the ``.scc`` file that describes a configuration fragment file. Here is the variable used in a file named ``smp.scc`` - to describe SMP being enabled: - :: + to describe SMP being enabled:: define KFEATURE_DESCRIPTION "Enable SMP" @@ -4158,13 +4085,12 @@ system and gives an overview of their function and contents. OpenEmbedded build system understands as ``core2-32-intel-common`` goes by a different name in the Linux Yocto kernel. The kernel understands that machine as ``intel-core2-32``. For cases like these, - the ``KMACHINE`` variable maps the kernel machine name to the + the :term:`KMACHINE` variable maps the kernel machine name to the OpenEmbedded build system machine name. These mappings between different names occur in the Yocto Linux Kernel's ``meta`` branch. As an example take a look in the - ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file: - :: + ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file:: LINUX_VERSION_core2-32-intel-common = "3.19.0" COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}" @@ -4174,7 +4100,7 @@ system and gives an overview of their function and contents. KBRANCH_core2-32-intel-common = "standard/base" KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}" - The ``KMACHINE`` statement says + The :term:`KMACHINE` statement says that the kernel understands the machine name as "intel-core2-32". However, the OpenEmbedded build system understands the machine as "core2-32-intel-common". @@ -4187,7 +4113,7 @@ system and gives an overview of their function and contents. Yocto Project Linux Kernel Development Manual for more information on kernel types. - You define the ``KTYPE`` variable in the + You define the :term:`KTYPE` variable in the :ref:`kernel-dev/advanced:bsp descriptions`. The value you use must match the value used for the :term:`LINUX_KERNEL_TYPE` value used by the @@ -4202,8 +4128,7 @@ system and gives an overview of their function and contents. :term:`LAYERDEPENDS` Lists the layers, separated by spaces, on which this recipe depends. Optionally, you can specify a specific layer version for a dependency - by adding it to the end of the layer name. Here is an example: - :: + by adding it to the end of the layer name. Here is an example:: LAYERDEPENDS_mylayer = "anotherlayer (=3)" @@ -4228,8 +4153,7 @@ system and gives an overview of their function and contents. Optionally, you can specify a specific layer version for a recommendation by adding the version to the end of the layer name. - Here is an example: - :: + Here is an example:: LAYERRECOMMENDS_mylayer = "anotherlayer (=3)" @@ -4242,7 +4166,7 @@ system and gives an overview of their function and contents. :term:`LAYERSERIES_COMPAT` Lists the versions of the :term:`OpenEmbedded-Core (OE-Core)` for which - a layer is compatible. Using the ``LAYERSERIES_COMPAT`` variable + a layer is compatible. Using the :term:`LAYERSERIES_COMPAT` variable allows the layer maintainer to indicate which combinations of the layer and OE-Core can be expected to work. The variable gives the system a way to detect when a layer has not been tested with new @@ -4253,14 +4177,13 @@ system and gives an overview of their function and contents. For the list, use the Yocto Project :yocto_wiki:`Release Name </Releases>` (e.g. &DISTRO_NAME_NO_CAP;). To specify multiple OE-Core versions for the - layer, use a space-separated list: - :: + layer, use a space-separated list:: LAYERSERIES_COMPAT_layer_root_name = "&DISTRO_NAME_NO_CAP; &DISTRO_NAME_NO_CAP_MINUS_ONE;" .. note:: - Setting ``LAYERSERIES_COMPAT`` is required by the Yocto Project + Setting :term:`LAYERSERIES_COMPAT` is required by the Yocto Project Compatible version 2 standard. The OpenEmbedded build system produces a warning if the variable is not set for any given layer. @@ -4284,7 +4207,7 @@ system and gives an overview of their function and contents. to an environment variable and thus made visible to the software being built during the compilation step. - Default initialization for ``LDFLAGS`` varies depending on what is + Default initialization for :term:`LDFLAGS` varies depending on what is being built: - :term:`TARGET_LDFLAGS` when building for the @@ -4325,8 +4248,8 @@ system and gives an overview of their function and contents. - Separate license names using \| (pipe) when there is a choice between licenses. - - Separate license names using & (ampersand) when multiple licenses - exist that cover different parts of the source. + - Separate license names using & (ampersand) when there are + multiple licenses for different parts of the source. - You can use spaces between license names. @@ -4335,8 +4258,7 @@ system and gives an overview of their function and contents. :term:`SPDXLICENSEMAP` flag names defined in ``meta/conf/licenses.conf``. - Here are some examples: - :: + Here are some examples:: LICENSE = "LGPLv2.1 | GPLv3" LICENSE = "MPL-1 & LGPLv2.1" @@ -4353,15 +4275,14 @@ system and gives an overview of their function and contents. situations where components of the output have different licenses. For example, a piece of software whose code is licensed under GPLv2 but has accompanying documentation licensed under the GNU Free - Documentation License 1.2 could be specified as follows: - :: + Documentation License 1.2 could be specified as follows:: LICENSE = "GFDL-1.2 & GPLv2" LICENSE_${PN} = "GPLv2" LICENSE_${PN}-doc = "GFDL-1.2" :term:`LICENSE_CREATE_PACKAGE` - Setting ``LICENSE_CREATE_PACKAGE`` to "1" causes the OpenEmbedded + Setting :term:`LICENSE_CREATE_PACKAGE` to "1" causes the OpenEmbedded build system to create an extra package (i.e. ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add those packages to the @@ -4406,11 +4327,10 @@ system and gives an overview of their function and contents. :term:`LICENSE_PATH` Path to additional licenses used during the build. By default, the - OpenEmbedded build system uses ``COMMON_LICENSE_DIR`` to define the + OpenEmbedded build system uses :term:`COMMON_LICENSE_DIR` to define the directory that holds common license text used during the build. The - ``LICENSE_PATH`` variable allows you to extend that location to other - areas that have additional licenses: - :: + :term:`LICENSE_PATH` variable allows you to extend that location to other + areas that have additional licenses:: LICENSE_PATH += "path-to-additional-common-licenses" @@ -4422,9 +4342,9 @@ system and gives an overview of their function and contents. Yocto Project Linux Kernel Development Manual for more information on kernel types. - If you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to + If you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to "standard". Together with :term:`KMACHINE`, the - ``LINUX_KERNEL_TYPE`` variable defines the search arguments used by + :term:`LINUX_KERNEL_TYPE` variable defines the search arguments used by the kernel tools to find the appropriate description within the kernel :term:`Metadata` with which to build out the sources and configuration. @@ -4434,14 +4354,12 @@ system and gives an overview of their function and contents. being built using the OpenEmbedded build system is based. You define this variable in the kernel recipe. For example, the ``linux-yocto-3.4.bb`` kernel recipe found in - ``meta/recipes-kernel/linux`` defines the variables as follows: - :: + ``meta/recipes-kernel/linux`` defines the variables as follows:: LINUX_VERSION ?= "3.4.24" - The ``LINUX_VERSION`` variable is used to define :term:`PV` - for the recipe: - :: + The :term:`LINUX_VERSION` variable is used to define :term:`PV` + for the recipe:: PV = "${LINUX_VERSION}+git${SRCPV}" @@ -4449,16 +4367,14 @@ system and gives an overview of their function and contents. A string extension compiled into the version string of the Linux kernel built with the OpenEmbedded build system. You define this variable in the kernel recipe. For example, the linux-yocto kernel - recipes all define the variable as follows: - :: + recipes all define the variable as follows:: LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}" Defining this variable essentially sets the Linux kernel configuration item ``CONFIG_LOCALVERSION``, which is visible through the ``uname`` command. Here is an example that shows the extension - assuming it was set as previously shown: - :: + assuming it was set as previously shown:: $ uname -r 3.7.0-rc8-custom @@ -4472,24 +4388,22 @@ system and gives an overview of their function and contents. :term:`MACHINE` Specifies the target device for which the image is built. You define - ``MACHINE`` in the ``local.conf`` file found in the - :term:`Build Directory`. By default, ``MACHINE`` is set to + :term:`MACHINE` in the ``local.conf`` file found in the + :term:`Build Directory`. By default, :term:`MACHINE` is set to "qemux86", which is an x86-based architecture machine to be emulated - using QEMU: - :: + using QEMU:: MACHINE ?= "qemux86" The variable corresponds to a machine configuration file of the same name, through which machine-specific configurations are set. Thus, - when ``MACHINE`` is set to "qemux86" there exists the corresponding - ``qemux86.conf`` machine configuration file, which can be found in + when :term:`MACHINE` is set to "qemux86", the corresponding + ``qemux86.conf`` machine configuration file can be found in the :term:`Source Directory` in ``meta/conf/machine``. The list of machines supported by the Yocto Project as shipped - include the following: - :: + include the following:: MACHINE ?= "qemuarm" MACHINE ?= "qemuarm64" @@ -4509,13 +4423,13 @@ system and gives an overview of their function and contents. .. note:: Adding additional Board Support Package (BSP) layers to your - configuration adds new possible settings for ``MACHINE``. + configuration adds new possible settings for :term:`MACHINE`. :term:`MACHINE_ARCH` Specifies the name of the machine-specific architecture. This variable is set automatically from :term:`MACHINE` or :term:`TUNE_PKGARCH`. You should not hand-edit - the ``MACHINE_ARCH`` variable. + the :term:`MACHINE_ARCH` variable. :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` A list of required machine-specific packages to install as part of @@ -4527,7 +4441,7 @@ system and gives an overview of their function and contents. image. This variable is similar to the - ``MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` variable with the exception + :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` variable with the exception that the image being built has a build dependency on the variable's list of packages. In other words, the image will not build if a file in this list is not found. @@ -4535,8 +4449,7 @@ system and gives an overview of their function and contents. As an example, suppose the machine for which you are building requires ``example-init`` to be run during boot to initialize the hardware. In this case, you would use the following in the machine's - ``.conf`` configuration file: - :: + ``.conf`` configuration file:: MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" @@ -4549,7 +4462,7 @@ system and gives an overview of their function and contents. on ``packagegroup-core-boot``, including the ``core-image-minimal`` image. - This variable is similar to the ``MACHINE_ESSENTIAL_EXTRA_RDEPENDS`` + This variable is similar to the :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` variable with the exception that the image being built does not have a build dependency on the variable's list of packages. In other words, the image will still build if a package in this list is not @@ -4567,8 +4480,7 @@ system and gives an overview of their function and contents. "recommends" relationship so that in the latter case, the build will not fail due to the missing package. To accomplish this, assuming the package for the module was called ``kernel-module-ab123``, you would - use the following in the machine's ``.conf`` configuration file: - :: + use the following in the machine's ``.conf`` configuration file:: MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" @@ -4592,7 +4504,7 @@ system and gives an overview of their function and contents. which does not include the ``core-image-minimal`` or ``core-image-full-cmdline`` images. - The variable is similar to the ``MACHINE_EXTRA_RRECOMMENDS`` variable + The variable is similar to the :term:`MACHINE_EXTRA_RRECOMMENDS` variable with the exception that the image being built has a build dependency on the variable's list of packages. In other words, the image will not build if a file in this list is not found. @@ -4604,8 +4516,7 @@ system and gives an overview of their function and contents. exist, so it is acceptable for the build process to depend upon finding the package. In this case, assuming the package for the firmware was called ``wifidriver-firmware``, you would use the - following in the ``.conf`` file for the machine: - :: + following in the ``.conf`` file for the machine:: MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" @@ -4618,7 +4529,7 @@ system and gives an overview of their function and contents. which does not include the ``core-image-minimal`` or ``core-image-full-cmdline`` images. - This variable is similar to the ``MACHINE_EXTRA_RDEPENDS`` variable + This variable is similar to the :term:`MACHINE_EXTRA_RDEPENDS` variable with the exception that the image being built does not have a build dependency on the variable's list of packages. In other words, the image will build if a file in this list is not found. @@ -4631,8 +4542,7 @@ system and gives an overview of their function and contents. the build to succeed instead of failing as a result of the package not being found. To accomplish this, assuming the package for the module was called ``kernel-module-examplewifi``, you would use the - following in the ``.conf`` file for the machine: - :: + following in the ``.conf`` file for the machine:: MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" @@ -4648,8 +4558,8 @@ system and gives an overview of their function and contents. shipped, see the ":ref:`ref-features-machine`" section. :term:`MACHINE_FEATURES_BACKFILL` - Features to be added to ``MACHINE_FEATURES`` if not also present in - ``MACHINE_FEATURES_BACKFILL_CONSIDERED``. + Features to be added to :term:`MACHINE_FEATURES` if not also present in + :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. This variable is set in the ``meta/conf/bitbake.conf`` file. It is not intended to be user-configurable. It is best to just reference @@ -4658,8 +4568,8 @@ system and gives an overview of their function and contents. section for more information. :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` - Features from ``MACHINE_FEATURES_BACKFILL`` that should not be - backfilled (i.e. added to ``MACHINE_FEATURES``) during the build. See + Features from :term:`MACHINE_FEATURES_BACKFILL` that should not be + backfilled (i.e. added to :term:`MACHINE_FEATURES`) during the build. See the ":ref:`ref-features-backfill`" section for more information. :term:`MACHINEOVERRIDES` @@ -4667,27 +4577,25 @@ system and gives an overview of their function and contents. machine. By default, this list includes the value of :term:`MACHINE`. - You can extend ``MACHINEOVERRIDES`` to add extra overrides that + You can extend :term:`MACHINEOVERRIDES` to add extra overrides that should apply to a machine. For example, all machines emulated in QEMU (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named ``meta/conf/machine/include/qemu.inc`` that prepends the following - override to ``MACHINEOVERRIDES``: - :: + override to :term:`MACHINEOVERRIDES`:: MACHINEOVERRIDES =. "qemuall:" This override allows variables to be overridden for all machines emulated in QEMU, like in the following example from the ``connman-conf`` - recipe: - :: + recipe:: SRC_URI_append_qemuall = " file://wired.config \ file://wired-setup \ " The underlying mechanism behind - ``MACHINEOVERRIDES`` is simply that it is included in the default + :term:`MACHINEOVERRIDES` is simply that it is included in the default value of :term:`OVERRIDES`. :term:`MAINTAINER` @@ -4707,10 +4615,10 @@ system and gives an overview of their function and contents. first tries the local download directory. If that location fails, the build system tries locations defined by :term:`PREMIRRORS`, the upstream source, and then - locations specified by ``MIRRORS`` in that order. + locations specified by :term:`MIRRORS` in that order. Assuming your distribution (:term:`DISTRO`) is "poky", - the default value for ``MIRRORS`` is defined in the + the default value for :term:`MIRRORS` is defined in the ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository. :term:`MLPREFIX` @@ -4718,49 +4626,45 @@ system and gives an overview of their function and contents. special version of a recipe or package (i.e. a Multilib version). The variable is used in places where the prefix needs to be added to or removed from a the name (e.g. the :term:`BPN` variable). - ``MLPREFIX`` gets set when a prefix has been added to ``PN``. + :term:`MLPREFIX` gets set when a prefix has been added to :term:`PN`. .. note:: - The "ML" in ``MLPREFIX`` stands for "MultiLib". This representation is + The "ML" in :term:`MLPREFIX` stands for "MultiLib". This representation is historical and comes from a time when ``nativesdk`` was a suffix rather than a prefix on the recipe name. When ``nativesdk`` was turned - into a prefix, it made sense to set ``MLPREFIX`` for it as well. + into a prefix, it made sense to set :term:`MLPREFIX` for it as well. - To help understand when ``MLPREFIX`` might be needed, consider when + To help understand when :term:`MLPREFIX` might be needed, consider when :term:`BBCLASSEXTEND` is used to provide a ``nativesdk`` version of a recipe in addition to the target version. If that recipe declares build-time dependencies on tasks in other recipes by using :term:`DEPENDS`, then a dependency on "foo" will automatically get rewritten to a dependency on "nativesdk-foo". However, dependencies like the following will not - get rewritten automatically: - :: + get rewritten automatically:: do_foo[depends] += "recipe:do_foo" If you want such a dependency to also get transformed, you can do the - following: - :: + following:: do_foo[depends] += "${MLPREFIX}recipe:do_foo" - module_autoload - This variable has been replaced by the ``KERNEL_MODULE_AUTOLOAD`` + :term:`module_autoload` + This variable has been replaced by the :term:`KERNEL_MODULE_AUTOLOAD` variable. You should replace all occurrences of ``module_autoload`` - with additions to ``KERNEL_MODULE_AUTOLOAD``, for example: - :: + with additions to :term:`KERNEL_MODULE_AUTOLOAD`, for example:: module_autoload_rfcomm = "rfcomm" - should now be replaced with: - :: + should now be replaced with:: KERNEL_MODULE_AUTOLOAD += "rfcomm" See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information. - module_conf + :term:`module_conf` Specifies `modprobe.d <https://linux.die.net/man/5/modprobe.d>`_ syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf`` file. @@ -4773,8 +4677,7 @@ system and gives an overview of their function and contents. :term:`KERNEL_MODULE_AUTOLOAD` variable. - Here is the general syntax: - :: + Here is the general syntax:: module_conf_module_name = "modprobe.d-syntax" @@ -4786,8 +4689,7 @@ system and gives an overview of their function and contents. Including ``module_conf`` causes the OpenEmbedded build system to populate the ``/etc/modprobe.d/modname.conf`` file with ``modprobe.d`` syntax lines. Here is an example that adds the options - ``arg1`` and ``arg2`` to a module named ``mymodule``: - :: + ``arg1`` and ``arg2`` to a module named ``mymodule``:: module_conf_mymodule = "options mymodule arg1=val1 arg2=val2" @@ -4801,15 +4703,13 @@ system and gives an overview of their function and contents. :term:`MODULE_TARBALL_LINK_NAME` The link name of the kernel module tarball. This variable is set in - the ``meta/classes/kernel-artifact-names.bbclass`` file as follows: - :: + the ``meta/classes/kernel-artifact-names.bbclass`` file as follows:: MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" The value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the - same file, has the following value: - :: + same file, has the following value:: KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" @@ -4817,14 +4717,12 @@ system and gives an overview of their function and contents. :term:`MODULE_TARBALL_NAME` The base name of the kernel module tarball. This variable is set in - the ``meta/classes/kernel-artifact-names.bbclass`` file as follows: - :: + the ``meta/classes/kernel-artifact-names.bbclass`` file as follows:: MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}" The value of the :term:`KERNEL_ARTIFACT_NAME` variable, - which is set in the same file, has the following value: - :: + which is set in the same file, has the following value:: KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" @@ -4834,14 +4732,13 @@ system and gives an overview of their function and contents. target systems to be put into different subdirectories of the same output directory. - The default value of this variable is: - :: + The default value of this variable is:: ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS} Some classes (e.g. :ref:`cross-canadian <ref-classes-cross-canadian>`) modify the - ``MULTIMACH_TARGET_SYS`` value. + :term:`MULTIMACH_TARGET_SYS` value. See the :term:`STAMP` variable for an example. See the :term:`STAGING_DIR_TARGET` variable for more information. @@ -4866,23 +4763,21 @@ system and gives an overview of their function and contents. :term:`NO_GENERIC_LICENSE` Avoids QA errors when you use a non-common, non-CLOSED license in a - recipe. Packages exist, such as the linux-firmware package, with many + recipe. There are packages, such as the linux-firmware package, with many licenses that are not in any way common. Also, new licenses are added occasionally to avoid introducing a lot of common license files, which are only applicable to a specific package. - ``NO_GENERIC_LICENSE`` is used to allow copying a license that does + :term:`NO_GENERIC_LICENSE` is used to allow copying a license that does not exist in common licenses. - The following example shows how to add ``NO_GENERIC_LICENSE`` to a - recipe: - :: + The following example shows how to add :term:`NO_GENERIC_LICENSE` to a + recipe:: NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source" - The following is an example that + Here is an example that uses the ``LICENSE.Abilis.txt`` file as the license from the fetched - source: - :: + source:: NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt" @@ -4890,13 +4785,13 @@ system and gives an overview of their function and contents. Prevents installation of all "recommended-only" packages. Recommended-only packages are packages installed only through the :term:`RRECOMMENDS` variable). Setting the - ``NO_RECOMMENDATIONS`` variable to "1" turns this feature on: :: + :term:`NO_RECOMMENDATIONS` variable to "1" turns this feature on:: NO_RECOMMENDATIONS = "1" You can set this variable globally in your ``local.conf`` file or you can attach it to a specific image recipe by using the recipe name - override: :: + override:: NO_RECOMMENDATIONS_pn-target_image = "1" @@ -4912,8 +4807,8 @@ system and gives an overview of their function and contents. functionality, such as kernel modules. It is up to you to add packages with the :term:`IMAGE_INSTALL` variable. - Support for this variable exists only when using the IPK and RPM - packaging backend. Support does not exist for DEB. + This variable is only supported when using the IPK and RPM + packaging backends. DEB is not supported. See the :term:`BAD_RECOMMENDATIONS` and the :term:`PACKAGE_EXCLUDE` variables for @@ -4922,15 +4817,21 @@ system and gives an overview of their function and contents. :term:`NOAUTOPACKAGEDEBUG` Disables auto package from splitting ``.debug`` files. If a recipe requires ``FILES_${PN}-dbg`` to be set manually, the - ``NOAUTOPACKAGEDEBUG`` can be defined allowing you to define the - content of the debug package. For example: - :: + :term:`NOAUTOPACKAGEDEBUG` can be defined allowing you to define the + content of the debug package. For example:: NOAUTOPACKAGEDEBUG = "1" FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*" FILES_${PN}-dbg = "/usr/src/debug/" FILES_${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch" + :term:`NON_MULTILIB_RECIPES` + A list of recipes that should not be built for multilib. OE-Core's + ``multilib.conf`` file defines a reasonable starting point for this + list with:: + + NON_MULTILIB_RECIPES = "grub grub-efi make-mod-scripts ovmf u-boot" + :term:`OBJCOPY` The minimal command and arguments to run ``objcopy``. @@ -4966,7 +4867,7 @@ system and gives an overview of their function and contents. value is "oe-init-build-env". If you use a custom script to set up your build environment, set the - ``OE_INIT_ENV_SCRIPT`` variable to its name. + :term:`OE_INIT_ENV_SCRIPT` variable to its name. :term:`OE_TERMINAL` Controls how the OpenEmbedded build system spawns interactive @@ -4989,7 +4890,7 @@ system and gives an overview of their function and contents. The directory from which the top-level build environment setup script is sourced. The Yocto Project provides a top-level build environment setup script: :ref:`structure-core-script`. When you run this - script, the ``OEROOT`` variable resolves to the directory that + script, the :term:`OEROOT` variable resolves to the directory that contains the script. For additional information on how this variable is used, see the @@ -5009,15 +4910,14 @@ system and gives an overview of their function and contents. A colon-separated list of overrides that currently apply. Overrides are a BitBake mechanism that allows variables to be selectively overridden at the end of parsing. The set of overrides in - ``OVERRIDES`` represents the "state" during building, which includes + :term:`OVERRIDES` represents the "state" during building, which includes the current recipe being built, the machine for which it is being built, and so forth. As an example, if the string "an-override" appears as an element in - the colon-separated list in ``OVERRIDES``, then the following + the colon-separated list in :term:`OVERRIDES`, then the following assignment will override ``FOO`` with the value "overridden" at the - end of parsing: - :: + end of parsing:: FOO_an-override = "overridden" @@ -5026,27 +4926,25 @@ system and gives an overview of their function and contents. section in the BitBake User Manual for more information on the overrides mechanism. - The default value of ``OVERRIDES`` includes the values of the + The default value of :term:`OVERRIDES` includes the values of the :term:`CLASSOVERRIDE`, :term:`MACHINEOVERRIDES`, and :term:`DISTROOVERRIDES` variables. Another important override included by default is ``pn-${PN}``. This override allows variables to be set for a single recipe within configuration - (``.conf``) files. Here is an example: - :: + (``.conf``) files. Here is an example:: FOO_pn-myrecipe = "myrecipe-specific value" .. note:: - An easy way to see what overrides apply is to search for ``OVERRIDES`` + An easy way to see what overrides apply is to search for :term:`OVERRIDES` in the output of the ``bitbake -e`` command. See the ":ref:`dev-manual/common-tasks:viewing variable values`" section in the Yocto Project Development Tasks Manual for more information. :term:`P` - The recipe name and version. ``P`` is comprised of the following: - :: + The recipe name and version. :term:`P` is comprised of the following:: ${PN}-${PV} @@ -5081,9 +4979,8 @@ system and gives an overview of their function and contents. However, if your recipe's output packages are built specific to the target machine rather than generally for the architecture of the - machine, you should set ``PACKAGE_ARCH`` to the value of - :term:`MACHINE_ARCH` in the recipe as follows: - :: + machine, you should set :term:`PACKAGE_ARCH` to the value of + :term:`MACHINE_ARCH` in the recipe as follows:: PACKAGE_ARCH = "${MACHINE_ARCH}" @@ -5091,11 +4988,11 @@ system and gives an overview of their function and contents. Specifies a list of architectures compatible with the target machine. This variable is set automatically and should not normally be hand-edited. Entries are separated using spaces and listed in order - of priority. The default value for ``PACKAGE_ARCHS`` is "all any + of priority. The default value for :term:`PACKAGE_ARCHS` is "all any noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}". :term:`PACKAGE_BEFORE_PN` - Enables easily adding packages to ``PACKAGES`` before ``${PN}`` so + Enables easily adding packages to :term:`PACKAGES` before ``${PN}`` so that those added packages can pick up files that would normally be included in the default package. @@ -5119,8 +5016,7 @@ system and gives an overview of their function and contents. The build system uses only the first argument in the list as the package manager when creating your image or SDK. However, packages will be created using any additional packaging classes you specify. - For example, if you use the following in your ``local.conf`` file: - :: + For example, if you use the following in your ``local.conf`` file:: PACKAGE_CLASSES ?= "package_ipk" @@ -5136,7 +5032,7 @@ system and gives an overview of their function and contents. creating ``*-dbg`` packages to be used with the GNU Project Debugger (GDB). - With the ``PACKAGE_DEBUG_SPLIT_STYLE`` variable, you can control + With the :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable, you can control where debug information, which can include or exclude source files, is stored: @@ -5173,20 +5069,18 @@ system and gives an overview of their function and contents. are using :term:`IMAGE_FEATURES` to install ``dev-pkgs``, you might not want to install all packages from a particular multilib. If you find yourself in this situation, you can - use the ``PACKAGE_EXCLUDE_COMPLEMENTARY`` variable to specify regular + use the :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` variable to specify regular expressions to match the packages you want to exclude. :term:`PACKAGE_EXCLUDE` Lists packages that should not be installed into an image. For - example: - :: + example:: PACKAGE_EXCLUDE = "package_name package_name package_name ..." You can set this variable globally in your ``local.conf`` file or you can attach it to a specific image recipe by using the recipe name - override: - :: + override:: PACKAGE_EXCLUDE_pn-target_image = "package_name" @@ -5198,8 +5092,8 @@ system and gives an overview of their function and contents. an iterative development process to remove specific components from a system. - Support for this variable exists only when using the IPK and RPM - packaging backend. Support does not exist for DEB. + This variable is supported only when using the IPK and RPM + packaging backends. DEB is not supported. See the :term:`NO_RECOMMENDATIONS` and the :term:`BAD_RECOMMENDATIONS` variables for @@ -5213,7 +5107,7 @@ system and gives an overview of their function and contents. :term:`PACKAGE_FEED_ARCHS` Optionally specifies the package architectures used as part of the package feed URIs during the build. When used, the - ``PACKAGE_FEED_ARCHS`` variable is appended to the final package feed + :term:`PACKAGE_FEED_ARCHS` variable is appended to the final package feed URI, which is constructed using the :term:`PACKAGE_FEED_URIS` and :term:`PACKAGE_FEED_BASE_PATHS` @@ -5221,17 +5115,16 @@ system and gives an overview of their function and contents. .. note:: - You can use the ``PACKAGE_FEED_ARCHS`` + You can use the :term:`PACKAGE_FEED_ARCHS` variable to whitelist specific package architectures. If you do not need to whitelist specific architectures, which is a common case, you can omit this variable. Omitting the variable results in all available architectures for the current machine being included into remote package feeds. - Consider the following example where the ``PACKAGE_FEED_URIS``, - ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are - defined in your ``local.conf`` file: - :: + Consider the following example where the :term:`PACKAGE_FEED_URIS`, + :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are + defined in your ``local.conf`` file:: PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ https://example.com/packagerepos/updates" @@ -5253,15 +5146,14 @@ system and gives an overview of their function and contents. :term:`PACKAGE_FEED_BASE_PATHS` Specifies the base path used when constructing package feed URIs. The - ``PACKAGE_FEED_BASE_PATHS`` variable makes up the middle portion of a + :term:`PACKAGE_FEED_BASE_PATHS` variable makes up the middle portion of a package feed URI used by the OpenEmbedded build system. The base path lies between the :term:`PACKAGE_FEED_URIS` and :term:`PACKAGE_FEED_ARCHS` variables. - Consider the following example where the ``PACKAGE_FEED_URIS``, - ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are - defined in your ``local.conf`` file: - :: + Consider the following example where the :term:`PACKAGE_FEED_URIS`, + :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are + defined in your ``local.conf`` file:: PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ https://example.com/packagerepos/updates" @@ -5284,14 +5176,13 @@ system and gives an overview of their function and contents. :term:`PACKAGE_FEED_URIS` Specifies the front portion of the package feed URI used by the OpenEmbedded build system. Each final package feed URI is comprised - of ``PACKAGE_FEED_URIS``, + of :term:`PACKAGE_FEED_URIS`, :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables. - Consider the following example where the ``PACKAGE_FEED_URIS``, - ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are - defined in your ``local.conf`` file: - :: + Consider the following example where the :term:`PACKAGE_FEED_URIS`, + :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are + defined in your ``local.conf`` file:: PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ https://example.com/packagerepos/updates" @@ -5316,7 +5207,7 @@ system and gives an overview of their function and contents. installation into the image. Because the package manager controls actual installation of all - packages, the list of packages passed using ``PACKAGE_INSTALL`` is + packages, the list of packages passed using :term:`PACKAGE_INSTALL` is not the final list of packages that are actually installed. This variable is internal to the image construction code. Consequently, in general, you should use the @@ -5324,7 +5215,7 @@ system and gives an overview of their function and contents. 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, - use the ``PACKAGE_INSTALL`` variable. For information on creating an + 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 in the Yocto Project Development Tasks Manual. @@ -5345,7 +5236,7 @@ system and gives an overview of their function and contents. post-installation or pre-installation script can execute at rootfs creation time rather than on the target but depends on a native tool in order to execute, you need to list the tools in - ``PACKAGE_WRITE_DEPS``. + :term:`PACKAGE_WRITE_DEPS`. For information on running post-installation scripts, see the ":ref:`dev-manual/common-tasks:post-installation scripts`" @@ -5353,11 +5244,10 @@ system and gives an overview of their function and contents. :term:`PACKAGECONFIG` This variable provides a means of enabling or disabling features of a - recipe on a per-recipe basis. ``PACKAGECONFIG`` blocks are defined in + recipe on a per-recipe basis. :term:`PACKAGECONFIG` blocks are defined in recipes when you specify features and then arguments that define feature behaviors. Here is the basic block structure (broken over - multiple lines for readability): - :: + multiple lines for readability):: PACKAGECONFIG ??= "f1 f2 f3 ..." PACKAGECONFIG[f1] = "\ @@ -5382,8 +5272,8 @@ system and gives an overview of their function and contents. :term:`PACKAGECONFIG_CONFARGS`) if the feature is enabled. - 2. Extra arguments that should be added to ``EXTRA_OECONF`` or - ``PACKAGECONFIG_CONFARGS`` if the feature is disabled. + 2. Extra arguments that should be added to :term:`EXTRA_OECONF` or + :term:`PACKAGECONFIG_CONFARGS` if the feature is disabled. 3. Additional build dependencies (:term:`DEPENDS`) that should be added if the feature is enabled. @@ -5395,10 +5285,10 @@ system and gives an overview of their function and contents. (:term:`RRECOMMENDS`) that should be added if the feature is enabled. - 6. Any conflicting (that is, mutually exclusive) ``PACKAGECONFIG`` + 6. Any conflicting (that is, mutually exclusive) :term:`PACKAGECONFIG` settings for this feature. - Consider the following ``PACKAGECONFIG`` block taken from the + Consider the following :term:`PACKAGECONFIG` block taken from the ``librsvg`` recipe. In this example the feature is ``gtk``, which has three arguments that determine the feature's behavior. :: @@ -5408,41 +5298,37 @@ system and gives an overview of their function and contents. The ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is enabled. In this case, ``--with-gtk3`` is added to the configure - script argument list and ``gtk+3`` is added to ``DEPENDS``. On the + script argument list and ``gtk+3`` is added to :term:`DEPENDS`. On the other hand, if the feature is disabled say through a ``.bbappend`` file in another layer, then the second argument ``--without-gtk3`` is added to the configure script instead. - The basic ``PACKAGECONFIG`` structure previously described holds true + The basic :term:`PACKAGECONFIG` structure previously described holds true regardless of whether you are creating a block or changing a block. When creating a block, use the structure inside your recipe. - If you want to change an existing ``PACKAGECONFIG`` block, you can do + If you want to change an existing :term:`PACKAGECONFIG` block, you can do so one of two ways: - *Append file:* Create an append file named recipename\ ``.bbappend`` in your layer and override the value of - ``PACKAGECONFIG``. You can either completely override the - variable: - :: + :term:`PACKAGECONFIG`. You can either completely override the + variable:: PACKAGECONFIG = "f4 f5" - Or, you can just append the variable: - :: + Or, you can just append the variable:: PACKAGECONFIG_append = " f4" - *Configuration file:* This method is identical to changing the block through an append file except you edit your ``local.conf`` or ``mydistro.conf`` file. As with append files previously - described, you can either completely override the variable: - :: + described, you can either completely override the variable:: PACKAGECONFIG_pn-recipename = "f4 f5" - Or, you can just amend the variable: - :: + Or, you can just amend the variable:: PACKAGECONFIG_append_pn-recipename = " f4" @@ -5451,32 +5337,31 @@ system and gives an overview of their function and contents. :term:`PACKAGECONFIG` setting. Classes such as :ref:`autotools <ref-classes-autotools>` and - :ref:`cmake <ref-classes-cmake>` use ``PACKAGECONFIG_CONFARGS`` to - pass ``PACKAGECONFIG`` options to ``configure`` and ``cmake``, - respectively. If you are using ``PACKAGECONFIG`` but not a class that + :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 - ``PACKAGECONFIG_CONFARGS`` appropriately. + :term:`PACKAGECONFIG_CONFARGS` appropriately. :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` For recipes inheriting the :ref:`packagegroup <ref-classes-packagegroup>` class, setting - ``PACKAGEGROUP_DISABLE_COMPLEMENTARY`` to "1" specifies that the + :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` to "1" specifies that the normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth) should not be automatically created by the ``packagegroup`` recipe, which is the default behavior. :term:`PACKAGES` The list of packages the recipe creates. The default value is the - following: - :: + following:: ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} During packaging, the :ref:`ref-tasks-package` task - goes through ``PACKAGES`` and uses the :term:`FILES` + goes through :term:`PACKAGES` and uses the :term:`FILES` variable corresponding to each package to assign files to the - package. If a file matches the ``FILES`` variable for more than one - package in ``PACKAGES``, it will be assigned to the earliest + package. If a file matches the :term:`FILES` variable for more than one + package in :term:`PACKAGES`, it will be assigned to the earliest (leftmost) package. Packages in the variable's list that are empty (i.e. where none of @@ -5488,10 +5373,10 @@ system and gives an overview of their function and contents. :term:`PACKAGES_DYNAMIC` A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes. - ``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it + :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it only states that they should be satisfied. For example, if a hard, runtime dependency (:term:`RDEPENDS`) of another - package is satisfied at build time through the ``PACKAGES_DYNAMIC`` + package is satisfied at build time through the :term:`PACKAGES_DYNAMIC` variable, but a package with the module name is never actually produced, then the other package will be broken. Thus, if you attempt to include that package in an image, you will get a dependency @@ -5501,9 +5386,9 @@ system and gives an overview of their function and contents. Typically, if there is a chance that such a situation can occur and the package that is not created is valid without the dependency being satisfied, then you should use :term:`RRECOMMENDS` - (a soft runtime dependency) instead of ``RDEPENDS``. + (a soft runtime dependency) instead of :term:`RDEPENDS`. - For an example of how to use the ``PACKAGES_DYNAMIC`` variable when + For an example of how to use the :term:`PACKAGES_DYNAMIC` variable when you are splitting packages, see the ":ref:`dev-manual/common-tasks:handling optional module packaging`" section in the Yocto Project Development Tasks Manual. @@ -5527,7 +5412,7 @@ system and gives an overview of their function and contents. .. note:: - In order for ``PARALLEL_MAKE`` to be effective, ``make`` must be + In order for :term:`PARALLEL_MAKE` to be effective, ``make`` must be called with ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy way to ensure this is to use the ``oe_runmake`` function. @@ -5538,7 +5423,7 @@ system and gives an overview of their function and contents. If the software being built experiences dependency issues during the ``do_compile`` task that result in race conditions, you can clear - the ``PARALLEL_MAKE`` variable within the recipe as a workaround. For + 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`" section in the Yocto Project Development Tasks Manual. @@ -5546,7 +5431,7 @@ system and gives an overview of their function and contents. For single socket systems (i.e. one CPU), you should not have to override this variable to gain optimal parallelism during builds. However, if you have very large systems that employ multiple physical - CPUs, you might want to make sure the ``PARALLEL_MAKE`` variable is + CPUs, you might want to make sure the :term:`PARALLEL_MAKE` variable is not set higher than "-j 20". For more information on speeding up builds, see the @@ -5561,14 +5446,14 @@ system and gives an overview of their function and contents. .. note:: - In order for ``PARALLEL_MAKEINST`` to be effective, ``make`` must + In order for :term:`PARALLEL_MAKEINST` to be effective, ``make`` must be called with ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy 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 - clear the ``PARALLEL_MAKEINST`` variable within the recipe as a + 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`" section in the Yocto Project Development Tasks Manual. @@ -5594,8 +5479,7 @@ system and gives an overview of their function and contents. patched, it uses "patch". If you wish to use an alternative patching tool, set the variable in - the recipe using one of the following: - :: + the recipe using one of the following:: PATCHTOOL = "patch" PATCHTOOL = "quilt" @@ -5606,7 +5490,7 @@ system and gives an overview of their function and contents. variable is used to make upgrades possible when the versioning scheme changes in some backwards incompatible way. - ``PE`` is the default value of the :term:`PKGE` variable. + :term:`PE` is the default value of the :term:`PKGE` variable. :term:`PF` Specifies the recipe or package name and includes all version and @@ -5628,7 +5512,7 @@ system and gives an overview of their function and contents. .. note:: - When using the ``PKG`` variable, you must use a package name override. + When using the :term:`PKG` variable, you must use a package name override. For example, when the :ref:`debian <ref-classes-debian>` class renames the output package, it does so by setting @@ -5641,8 +5525,7 @@ system and gives an overview of their function and contents. :term:`PKGD` Points to the destination directory for files to be packaged before they are split into individual packages. This directory defaults to - the following: - :: + the following:: ${WORKDIR}/package @@ -5654,8 +5537,7 @@ system and gives an overview of their function and contents. :ref:`ref-tasks-packagedata` task packages data for each recipe and installs it into this temporary, shared area. This directory defaults to the following, which you should not - change: - :: + change:: ${STAGING_DIR_HOST}/pkgdata @@ -5670,8 +5552,7 @@ system and gives an overview of their function and contents. :term:`PKGDEST` Points to the parent directory for files to be packaged after they have been split into individual packages. This directory defaults to - the following: - :: + the following:: ${WORKDIR}/packages-split @@ -5682,46 +5563,45 @@ system and gives an overview of their function and contents. :term:`PKGDESTWORK` Points to a temporary work area where the :ref:`ref-tasks-package` task saves package metadata. - The ``PKGDESTWORK`` location defaults to the following: - :: + The :term:`PKGDESTWORK` location defaults to the following:: ${WORKDIR}/pkgdata Do not change this default. The :ref:`ref-tasks-packagedata` task copies the - package metadata from ``PKGDESTWORK`` to + package metadata from :term:`PKGDESTWORK` to :term:`PKGDATA_DIR` to make it available globally. :term:`PKGE` - The epoch of the package(s) built by the recipe. By default, ``PKGE`` + The epoch of the package(s) built by the recipe. By default, :term:`PKGE` is set to :term:`PE`. :term:`PKGR` The revision of the package(s) built by the recipe. By default, - ``PKGR`` is set to :term:`PR`. + :term:`PKGR` is set to :term:`PR`. :term:`PKGV` The version of the package(s) built by the recipe. By default, - ``PKGV`` is set to :term:`PV`. + :term:`PKGV` is set to :term:`PV`. :term:`PN` This variable can have two separate functions depending on the context: a recipe name or a resulting package name. - ``PN`` refers to a recipe name in the context of a file used by the + :term:`PN` refers to a recipe name in the context of a file used by the OpenEmbedded build system as input to create a package. The name is normally extracted from the recipe file name. For example, if the - recipe is named ``expat_2.0.1.bb``, then the default value of ``PN`` + recipe is named ``expat_2.0.1.bb``, then the default value of :term:`PN` will be "expat". The variable refers to a package name in the context of a file created or produced by the OpenEmbedded build system. - If applicable, the ``PN`` variable also contains any special suffix + If applicable, the :term:`PN` variable also contains any special suffix or prefix. For example, using ``bash`` to build packages for the native machine, ``PN`` is ``bash-native``. Using ``bash`` to build - packages for the target and for Multilib, ``PN`` would be ``bash`` + packages for the target and for Multilib, :term:`PN` would be ``bash`` and ``lib64-bash``, respectively. :term:`PNBLACKLIST` @@ -5730,18 +5610,16 @@ system and gives an overview of their function and contents. :ref:`blacklist <ref-classes-blacklist>` class, which is inherited globally. - To prevent a recipe from being built, use the ``PNBLACKLIST`` + To prevent a recipe from being built, use the :term:`PNBLACKLIST` variable in your ``local.conf`` file. Here is an example that - prevents ``myrecipe`` from being built: - :: + prevents ``myrecipe`` from being built:: PNBLACKLIST[myrecipe] = "Not supported by our organization." :term:`POPULATE_SDK_POST_HOST_COMMAND` Specifies a list of functions to call once the OpenEmbedded build system has created the host part of the SDK. You can specify - functions separated by semicolons: - :: + functions separated by semicolons:: POPULATE_SDK_POST_HOST_COMMAND += "function; ... " @@ -5753,8 +5631,7 @@ system and gives an overview of their function and contents. :term:`POPULATE_SDK_POST_TARGET_COMMAND` Specifies a list of functions to call once the OpenEmbedded build system has created the target part of the SDK. You can specify - functions separated by semicolons: - :: + functions separated by semicolons:: POPULATE_SDK_POST_TARGET_COMMAND += "function; ... " @@ -5767,30 +5644,30 @@ system and gives an overview of their function and contents. The revision of the recipe. The default value for this variable is "r0". Subsequent revisions of the recipe conventionally have the values "r1", "r2", and so forth. When :term:`PV` increases, - ``PR`` is conventionally reset to "r0". + :term:`PR` is conventionally reset to "r0". .. note:: - The OpenEmbedded build system does not need the aid of ``PR`` + The OpenEmbedded build system does not need the aid of :term:`PR` to know when to rebuild a recipe. The build system uses the task :ref:`input checksums <overview-manual/concepts:checksums (signatures)>` along with the :ref:`stamp <structure-build-tmp-stamps>` and :ref:`overview-manual/concepts:shared state cache` mechanisms. - The ``PR`` variable primarily becomes significant when a package + The :term:`PR` variable primarily becomes significant when a package manager dynamically installs packages on an already built image. In - this case, ``PR``, which is the default value of + this case, :term:`PR`, which is the default value of :term:`PKGR`, helps the package manager distinguish which package is the most recent one in cases where many packages have the - same ``PV`` (i.e. ``PKGV``). A component having many packages with - the same ``PV`` usually means that the packages all install the same - upstream version, but with later (``PR``) version packages including + same :term:`PV` (i.e. :term:`PKGV`). A component having many packages with + the same :term:`PV` usually means that the packages all install the same + upstream version, but with later (:term:`PR`) version packages including packaging fixes. .. note:: - ``PR`` does not need to be increased for changes that do not change the + :term:`PR` does not need to be increased for changes that do not change the package contents or metadata. Because manually managing ``PR`` can be cumbersome and error-prone, @@ -5804,17 +5681,15 @@ system and gives an overview of their function and contents. preferred provider). You should always suffix this variable with the name of the provided item. And, you should define the variable using the preferred recipe's name (:term:`PN`). Here is a common - example: - :: + example:: PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" In the previous example, multiple recipes are providing "virtual/kernel". - The ``PREFERRED_PROVIDER`` variable is set with the name (``PN``) of + 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: - :: + Following are more examples:: PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" PREFERRED_PROVIDER_virtual/libgl ?= "mesa" @@ -5825,9 +5700,9 @@ system and gives an overview of their function and contents. .. note:: - If you use a ``virtual/\*`` item with ``PREFERRED_PROVIDER``, then any + If you use a ``virtual/\*`` item with :term:`PREFERRED_PROVIDER`, then any recipe that :term:`PROVIDES` that item but is not selected (defined) - by ``PREFERRED_PROVIDER`` is prevented from building, which is usually + by :term:`PREFERRED_PROVIDER` is prevented from building, which is usually desirable since this mechanism is designed to select between mutually exclusive alternative providers. @@ -5838,12 +5713,11 @@ system and gives an overview of their function and contents. the first example below), and you should specify the :term:`PV` accordingly (`3.4.0` in the example). - The ``PREFERRED_VERSION`` variable supports limited wildcard use + The :term:`PREFERRED_VERSION` variable supports limited wildcard use through the "``%``" character. You can use the character to match any number of characters, which can be useful when specifying versions that contain long revision numbers that potentially change. Here are - two examples: - :: + two examples:: PREFERRED_VERSION_python = "3.4.0" PREFERRED_VERSION_linux-yocto = "5.0%" @@ -5857,42 +5731,37 @@ system and gives an overview of their function and contents. The specified version is matched against :term:`PV`, which does not necessarily match the version part of the recipe's filename. For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb`` - where ``foo_git.bb`` contains the following assignment: - :: + where ``foo_git.bb`` contains the following assignment:: PV = "1.1+git${SRCPV}" In this case, the correct way to select - ``foo_git.bb`` is by using an assignment such as the following: - :: + ``foo_git.bb`` is by using an assignment such as the following:: PREFERRED_VERSION_foo = "1.1+git%" Compare that previous example - against the following incorrect example, which does not work: - :: + against the following incorrect example, which does not work:: PREFERRED_VERSION_foo = "git" - Sometimes the ``PREFERRED_VERSION`` variable can be set by + Sometimes the :term:`PREFERRED_VERSION` variable can be set by configuration files in a way that is hard to change. You can use :term:`OVERRIDES` to set a machine-specific - override. Here is an example: - :: + override. Here is an example:: PREFERRED_VERSION_linux-yocto_qemux86 = "5.0%" Although not recommended, worst case, you can also use the "forcevariable" override, which is the strongest override possible. - Here is an example: - :: + Here is an example:: PREFERRED_VERSION_linux-yocto_forcevariable = "5.0%" .. note:: The ``\_forcevariable`` override is not handled specially. This override - only works because the default value of ``OVERRIDES`` includes "forcevariable". + only works because the default value of :term:`OVERRIDES` includes "forcevariable". If a recipe with the specified version is not available, a warning message will be shown. See :term:`REQUIRED_VERSION` if you want this @@ -5902,19 +5771,18 @@ system and gives an overview of their function and contents. Specifies additional paths from which the OpenEmbedded build system gets source code. When the build system searches for source code, it first tries the local download directory. If that location fails, the - build system tries locations defined by ``PREMIRRORS``, the upstream + build system tries locations defined by :term:`PREMIRRORS`, the upstream source, and then locations specified by :term:`MIRRORS` in that order. Assuming your distribution (:term:`DISTRO`) is "poky", - the default value for ``PREMIRRORS`` is defined in the + the default value for :term:`PREMIRRORS` is defined in the ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository. Typically, you could add a specific server for the build system to attempt before any others by adding something like the following to the ``local.conf`` configuration file in the - :term:`Build Directory`: - :: + :term:`Build Directory`:: PREMIRRORS_prepend = "\ git://.*/.* http://www.yoctoproject.org/sources/ \n \ @@ -5931,12 +5799,12 @@ system and gives an overview of their function and contents. :term:`PRIORITY` Indicates the importance of a package. - ``PRIORITY`` is considered to be part of the distribution policy + :term:`PRIORITY` is considered to be part of the distribution policy because the importance of any given recipe depends on the purpose for - which the distribution is being produced. Thus, ``PRIORITY`` is not + which the distribution is being produced. Thus, :term:`PRIORITY` is not normally set within recipes. - You can set ``PRIORITY`` to "required", "standard", "extra", and + You can set :term:`PRIORITY` to "required", "standard", "extra", and "optional", which is the default. :term:`PRIVATE_LIBS` @@ -5950,8 +5818,7 @@ system and gives an overview of their function and contents. standard version of the library. Libraries specified in this variable should be specified by their - file name. For example, from the Firefox recipe in meta-browser: - :: + file name. For example, from the Firefox recipe in meta-browser:: PRIVATE_LIBS = "libmozjs.so \ libxpcom.so \ @@ -5967,20 +5834,19 @@ system and gives an overview of their function and contents. :term:`PROVIDES` A list of aliases by which a particular recipe can be known. By - default, a recipe's own ``PN`` is implicitly already in its - ``PROVIDES`` list and therefore does not need to mention that it - provides itself. If a recipe uses ``PROVIDES``, the additional + default, a recipe's own :term:`PN` is implicitly already in its + :term:`PROVIDES` list and therefore does not need to mention that it + provides itself. If a recipe uses :term:`PROVIDES`, the additional aliases are synonyms for the recipe and can be useful for satisfying dependencies of other recipes during the build as specified by - ``DEPENDS``. + :term:`DEPENDS`. - Consider the following example ``PROVIDES`` statement from the recipe - file ``eudev_3.2.9.bb``: - :: + Consider the following example :term:`PROVIDES` statement from the recipe + file ``eudev_3.2.9.bb``:: PROVIDES += "udev" - The ``PROVIDES`` statement + The :term:`PROVIDES` statement results in the "eudev" recipe also being available as simply "udev". .. note:: @@ -5990,12 +5856,12 @@ system and gives an overview of their function and contents. strictly necessary it is recommended to avoid confusion. In addition to providing recipes under alternate names, the - ``PROVIDES`` mechanism is also used to implement virtual targets. A + :term:`PROVIDES` mechanism is also used to implement virtual targets. A virtual target is a name that corresponds to some particular functionality (e.g. a Linux kernel). Recipes that provide the - functionality in question list the virtual target in ``PROVIDES``. + functionality in question list the virtual target in :term:`PROVIDES`. Recipes that depend on the functionality in question can include the - virtual target in ``DEPENDS`` to leave the choice of provider open. + virtual target in :term:`DEPENDS` to leave the choice of provider open. Conventionally, virtual targets have names on the form "virtual/function" (e.g. "virtual/kernel"). The slash is simply part @@ -6013,8 +5879,7 @@ system and gives an overview of their function and contents. 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: - :: + simple as using the following assignment in a configuration file:: VIRTUAL-RUNTIME_dev_manager = "udev" @@ -6024,15 +5889,14 @@ system and gives an overview of their function and contents. The ``conf/local.conf.sample.extended`` configuration file in the :term:`Source Directory` shows how the - ``PRSERV_HOST`` variable is set: - :: + :term:`PRSERV_HOST` variable is set:: PRSERV_HOST = "localhost:0" You must set the variable if you want to automatically start a local :ref:`PR service <dev-manual/common-tasks:working with a pr service>`. You can - set ``PRSERV_HOST`` to other values to use a remote PR service. + set :term:`PRSERV_HOST` to other values to use a remote PR service. :term:`PSEUDO_IGNORE_PATHS` @@ -6054,12 +5918,12 @@ system and gives an overview of their function and contents. :term:`PV` The version of the recipe. The version is normally extracted from the recipe filename. For example, if the recipe is named - ``expat_2.0.1.bb``, then the default value of ``PV`` will be "2.0.1". - ``PV`` is generally not overridden within a recipe unless it is + ``expat_2.0.1.bb``, then the default value of :term:`PV` will be "2.0.1". + :term:`PV` is generally not overridden within a recipe unless it is building an unstable (i.e. development) version from a source code repository (e.g. Git or Subversion). - ``PV`` is the default value of the :term:`PKGV` variable. + :term:`PV` is the default value of the :term:`PKGV` variable. :term:`PYTHON_ABI` When used by recipes that inherit the @@ -6081,18 +5945,17 @@ system and gives an overview of their function and contents. When used by recipes that inherit the `distutils3 <ref-classes-distutils3>`, :ref:`setuptools3 <ref-classes-setuptools3>` classes, specifies the - major Python version being built. For Python 3.x, ``PYTHON_PN`` would + major Python version being built. For Python 3.x, :term:`PYTHON_PN` would be "python3". You do not have to set this variable as the OpenEmbedded build system automatically sets it for you. The variable allows recipes to use common infrastructure such as the - following: - :: + following:: DEPENDS += "${PYTHON_PN}-native" In the previous example, - the version of the dependency is ``PYTHON_PN``. + the version of the dependency is :term:`PYTHON_PN`. :term:`RANLIB` The minimal command and arguments to run ``ranlib``. @@ -6102,8 +5965,7 @@ system and gives an overview of their function and contents. will not be installed if conflicting packages are not first removed. Like all package-controlling variables, you must always use them in - conjunction with a package name override. Here is an example: - :: + conjunction with a package name override. Here is an example:: RCONFLICTS_${PN} = "another_conflicting_package_name" @@ -6111,8 +5973,7 @@ system and gives an overview of their function and contents. specifying versioned dependencies. Although the syntax varies depending on the packaging format, BitBake hides these differences from you. Here is the general syntax to specify versions with the - ``RCONFLICTS`` variable: - :: + :term:`RCONFLICTS` variable:: RCONFLICTS_${PN} = "package (operator version)" @@ -6125,8 +5986,7 @@ system and gives an overview of their function and contents. - >= For example, the following sets up a dependency on version 1.2 or - greater of the package ``foo``: - :: + greater of the package ``foo``:: RCONFLICTS_${PN} = "foo (>= 1.2)" @@ -6135,19 +5995,18 @@ system and gives an overview of their function and contents. packages that must be installed in order for the package to function correctly. As an example, the following assignment declares that the package ``foo`` needs the packages ``bar`` and ``baz`` to be - installed: - :: + installed:: RDEPENDS_foo = "bar baz" The most common types of package runtime dependencies are automatically detected and added. Therefore, - most recipes do not need to set ``RDEPENDS``. For more information, + most recipes do not need to set :term:`RDEPENDS`. For more information, see the ":ref:`overview-manual/concepts:automatically added runtime dependencies`" section in the Yocto Project Overview and Concepts Manual. - The practical effect of the above ``RDEPENDS`` assignment is that + 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. @@ -6158,27 +6017,26 @@ system and gives an overview of their function and contents. also install the packages on which it depends. To ensure that the packages ``bar`` and ``baz`` get built, the - previous ``RDEPENDS`` assignment also causes a task dependency to be + previous :term:`RDEPENDS` assignment also causes a task dependency to be 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 ``baz``. - The names of the packages you list within ``RDEPENDS`` must be the + The names of the packages you list within :term:`RDEPENDS` must be the names of other packages - they cannot be recipe names. Although package names and recipe names usually match, the important point - here is that you are providing package names within the ``RDEPENDS`` + here is that you are providing package names within the :term:`RDEPENDS` variable. For an example of the default list of packages created from a recipe, see the :term:`PACKAGES` variable. - Because the ``RDEPENDS`` variable applies to packages being built, + Because the :term:`RDEPENDS` variable applies to packages being built, you should always use the variable in a form with an attached package name (remember that a single recipe can build multiple packages). For example, suppose you are building a development package that depends on the ``perl`` package. In this case, you would use the following - ``RDEPENDS`` statement: - :: + :term:`RDEPENDS` statement:: RDEPENDS_${PN}-dev += "perl" @@ -6195,20 +6053,19 @@ system and gives an overview of their function and contents. ``${PN}`` when modifying ``RDEPENDS_${PN}-dev``. Use the "+=" operator rather than the "=" operator. - The package names you use with ``RDEPENDS`` must appear as they would - in the ``PACKAGES`` variable. The :term:`PKG` variable + The package names you use with :term:`RDEPENDS` must appear as they would + in the :term:`PACKAGES` variable. The :term:`PKG` variable allows a different name to be used for the final package (e.g. the :ref:`debian <ref-classes-debian>` class uses this to rename packages), but this final package name cannot be used with - ``RDEPENDS``, which makes sense as ``RDEPENDS`` is meant to be + :term:`RDEPENDS`, which makes sense as :term:`RDEPENDS` is meant to be independent of the package format used. BitBake, which the OpenEmbedded build system uses, supports specifying versioned dependencies. Although the syntax varies depending on the packaging format, BitBake hides these differences from you. Here is the general syntax to specify versions with the - ``RDEPENDS`` variable: - :: + :term:`RDEPENDS` variable:: RDEPENDS_${PN} = "package (operator version)" @@ -6224,12 +6081,11 @@ system and gives an overview of their function and contents. .. note:: - You can use ``EXTENDPKGV`` to provide a full package version + You can use :term:`EXTENDPKGV` to provide a full package version specification. For example, the following sets up a dependency on version 1.2 or - greater of the package ``foo``: - :: + greater of the package ``foo``:: RDEPENDS_${PN} = "foo (>= 1.2)" @@ -6246,8 +6102,8 @@ system and gives an overview of their function and contents. class, this variable identifies distribution features that must exist in the current configuration in order for the OpenEmbedded build system to build the recipe. In other words, if the - ``REQUIRED_DISTRO_FEATURES`` variable lists a feature that does not - appear in ``DISTRO_FEATURES`` within the current configuration, then + :term:`REQUIRED_DISTRO_FEATURES` variable lists a feature that does not + appear in :term:`DISTRO_FEATURES` within the current configuration, then the recipe will be skipped, and if the build system attempts to build the recipe then an error will be triggered. @@ -6270,8 +6126,7 @@ system and gives an overview of their function and contents. :term:`ROOT_HOME` Defines the root home directory. By default, this directory is set as - follows in the BitBake configuration file: - :: + follows in the BitBake configuration file:: ROOT_HOME ??= "/home/root" @@ -6284,8 +6139,7 @@ system and gives an overview of their function and contents. You can override the default by setting the variable in any layer or in the ``local.conf`` file. Because the default is set using a "weak" assignment (i.e. "??="), you can use either of the following forms to - define your override: - :: + define your override:: ROOT_HOME = "/root" ROOT_HOME ?= "/root" @@ -6297,14 +6151,13 @@ system and gives an overview of their function and contents. :term:`ROOTFS` Indicates a filesystem image to include as the root filesystem. - The ``ROOTFS`` variable is an optional variable used with the + The :term:`ROOTFS` variable is an optional variable used with the :ref:`image-live <ref-classes-image-live>` class. :term:`ROOTFS_POSTINSTALL_COMMAND` Specifies a list of functions to call after the OpenEmbedded build system has installed packages. You can specify functions separated by - semicolons: - :: + semicolons:: ROOTFS_POSTINSTALL_COMMAND += "function; ... " @@ -6317,8 +6170,7 @@ system and gives an overview of their function and contents. :term:`ROOTFS_POSTPROCESS_COMMAND` Specifies a list of functions to call once the OpenEmbedded build system has created the root filesystem. You can specify functions - separated by semicolons: - :: + separated by semicolons:: ROOTFS_POSTPROCESS_COMMAND += "function; ... " @@ -6333,8 +6185,7 @@ system and gives an overview of their function and contents. system has removed unnecessary packages. When runtime package management is disabled in the image, several packages are removed including ``base-passwd``, ``shadow``, and ``update-alternatives``. - You can specify functions separated by semicolons: - :: + You can specify functions separated by semicolons:: ROOTFS_POSTUNINSTALL_COMMAND += "function; ... " @@ -6347,8 +6198,7 @@ system and gives an overview of their function and contents. :term:`ROOTFS_PREPROCESS_COMMAND` Specifies a list of functions to call before the OpenEmbedded build system has created the root filesystem. You can specify functions - separated by semicolons: - :: + separated by semicolons:: ROOTFS_PREPROCESS_COMMAND += "function; ... " @@ -6362,16 +6212,15 @@ system and gives an overview of their function and contents. A list of package name aliases that a package also provides. These aliases are useful for satisfying runtime dependencies of other packages both during the build and on the target (as specified by - ``RDEPENDS``). + :term:`RDEPENDS`). .. note:: - A package's own name is implicitly already in its ``RPROVIDES`` list. + A package's own name is implicitly already in its :term:`RPROVIDES` list. As with all package-controlling variables, you must always use the variable in conjunction with a package name override. Here is an - example: - :: + example:: RPROVIDES_${PN} = "widget-abi-2" @@ -6380,44 +6229,42 @@ system and gives an overview of their function and contents. built. The package being built does not depend on this list of packages in order to successfully build, but rather uses them for extended usability. To specify runtime dependencies for packages, see - the ``RDEPENDS`` variable. + the :term:`RDEPENDS` variable. - The package manager will automatically install the ``RRECOMMENDS`` + The package manager will automatically install the :term:`RRECOMMENDS` list of packages when installing the built package. However, you can prevent listed packages from being installed by using the :term:`BAD_RECOMMENDATIONS`, :term:`NO_RECOMMENDATIONS`, and :term:`PACKAGE_EXCLUDE` variables. - Packages specified in ``RRECOMMENDS`` need not actually be produced. - However, a recipe must exist that provides each package, either + Packages specified in :term:`RRECOMMENDS` need not actually be produced. + However, there must be a recipe providing each package, either through the :term:`PACKAGES` or :term:`PACKAGES_DYNAMIC` variables or the :term:`RPROVIDES` variable, or an error will occur during the build. If such a recipe does exist and the package is not produced, the build continues without error. - Because the ``RRECOMMENDS`` variable applies to packages being built, + Because the :term:`RRECOMMENDS` variable applies to packages being built, you should always attach an override to the variable to specify the particular package whose usability is being extended. For example, suppose you are building a development package that is extended to support wireless functionality. In this case, you would use the - following: - :: + following:: RRECOMMENDS_${PN}-dev += "wireless_package_name" In the example, the package name (``${PN}-dev``) must appear as it would in - the ``PACKAGES`` namespace before any renaming of the output package + the :term:`PACKAGES` namespace before any renaming of the output package by classes such as ``debian.bbclass``. BitBake, which the OpenEmbedded build system uses, supports specifying versioned recommends. Although the syntax varies depending on the packaging format, BitBake hides these differences from you. Here is the general syntax to specify versions with the - ``RRECOMMENDS`` variable: - :: + :term:`RRECOMMENDS` variable:: RRECOMMENDS_${PN} = "package (operator version)" @@ -6430,8 +6277,7 @@ system and gives an overview of their function and contents. - >= For example, the following sets up a recommend on version 1.2 or - greater of the package ``foo``: - :: + greater of the package ``foo``:: RRECOMMENDS_${PN} = "foo (>= 1.2)" @@ -6440,11 +6286,10 @@ system and gives an overview of their function and contents. this variable to determine which package should be installed to replace other package(s) during an upgrade. In order to also have the other package(s) removed at the same time, you must add the name of - the other package to the ``RCONFLICTS`` variable. + the other package to the :term:`RCONFLICTS` variable. As with all package-controlling variables, you must use this variable - in conjunction with a package name override. Here is an example: - :: + in conjunction with a package name override. Here is an example:: RREPLACES_${PN} = "other_package_being_replaced" @@ -6452,8 +6297,7 @@ system and gives an overview of their function and contents. specifying versioned replacements. Although the syntax varies depending on the packaging format, BitBake hides these differences from you. Here is the general syntax to specify versions with the - ``RREPLACES`` variable: - :: + :term:`RREPLACES` variable:: RREPLACES_${PN} = "package (operator version)" @@ -6466,8 +6310,7 @@ system and gives an overview of their function and contents. - >= For example, the following sets up a replacement using version 1.2 - or greater of the package ``foo``: - :: + or greater of the package ``foo``:: RREPLACES_${PN} = "foo (>= 1.2)" @@ -6478,8 +6321,7 @@ system and gives an overview of their function and contents. As with all package-controlling variables, you must always use this variable in conjunction with a package name override. Here is an - example: - :: + example:: RSUGGESTS_${PN} = "useful_package another_package" @@ -6491,14 +6333,13 @@ system and gives an overview of their function and contents. version. If the source tarball extracts the code to a directory named anything other than ``${BPN}-${PV}``, or if the source code is fetched from an SCM such as Git or Subversion, then you must set - ``S`` in the recipe so that the OpenEmbedded build system knows where + :term:`S` in the recipe so that the OpenEmbedded build system knows where to find the unpacked source. As an example, assume a :term:`Source Directory` top-level folder named ``poky`` and a default Build Directory at ``poky/build``. In this case, the work directory the build system - uses to keep the unpacked recipe for ``db`` is the following: - :: + uses to keep the unpacked recipe for ``db`` is the following:: poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 @@ -6507,9 +6348,8 @@ system and gives an overview of their function and contents. This next example assumes a Git repository. By default, Git repositories are cloned to ``${WORKDIR}/git`` during :ref:`ref-tasks-fetch`. Since this path is different - from the default value of ``S``, you must set it specifically so the - source can be located: - :: + from the default value of :term:`S`, you must set it specifically so the + source can be located:: SRC_URI = "git://path/to/repo.git" S = "${WORKDIR}/git" @@ -6525,7 +6365,7 @@ system and gives an overview of their function and contents. been tested against. Identifiers consist of the host distributor ID followed by the release, as reported by the ``lsb_release`` tool or as read from ``/etc/lsb-release``. Separate the list items with - explicit newline characters (``\n``). If ``SANITY_TESTED_DISTROS`` is + explicit newline characters (``\n``). If :term:`SANITY_TESTED_DISTROS` is not empty and the current value of :term:`NATIVELSBSTRING` does not appear in the list, then the build system reports a warning that indicates the @@ -6536,7 +6376,7 @@ system and gives an overview of their function and contents. set this variable. Instead, use :term:`SDKMACHINE`. :term:`SDK_CUSTOM_TEMPLATECONF` - When building the extensible SDK, if ``SDK_CUSTOM_TEMPLATECONF`` is set to + When building the extensible SDK, if :term:`SDK_CUSTOM_TEMPLATECONF` is set to "1" and a ``conf/templateconf.conf`` file exists in the build directory (:term:`TOPDIR`) then this will be copied into the SDK. @@ -6544,8 +6384,7 @@ system and gives an overview of their function and contents. The directory set up and used by the :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which the SDK is deployed. The ``populate_sdk_base`` class defines - ``SDK_DEPLOY`` as follows: - :: + :term:`SDK_DEPLOY` as follows:: SDK_DEPLOY = "${TMPDIR}/deploy/sdk" @@ -6553,15 +6392,14 @@ system and gives an overview of their function and contents. The parent directory used by the OpenEmbedded build system when creating SDK output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines - the variable as follows: - :: + the variable as follows:: SDK_DIR = "${WORKDIR}/sdk" .. note:: - The ``SDK_DIR`` directory is a temporary directory as it is part of - ``WORKDIR``. The final output directory is :term:`SDK_DEPLOY`. + The :term:`SDK_DIR` directory is a temporary directory as it is part of + :term:`WORKDIR`. The final output directory is :term:`SDK_DEPLOY`. :term:`SDK_EXT_TYPE` Controls whether or not shared state artifacts are copied into the @@ -6579,14 +6417,12 @@ system and gives an overview of their function and contents. The manifest file for the host part of the SDK. This file lists all the installed packages that make up the host part of the SDK. The file contains package information on a line-per-package basis as - follows: - :: + follows:: packagename packagearch version The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class - defines the manifest file as follows: - :: + defines the manifest file as follows:: SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest" @@ -6602,7 +6438,7 @@ system and gives an overview of their function and contents. .. note:: - Enabling the ``SDK_INCLUDE_PKGDATA`` + Enabling the :term:`SDK_INCLUDE_PKGDATA` variable significantly increases build time because all of world needs to be built. Enabling the variable also slightly increases the size of the extensible SDK. @@ -6616,16 +6452,15 @@ system and gives an overview of their function and contents. IDE or from other tools and you do not want to perform additional steps to install the toolchain. - The ``SDK_INCLUDE_TOOLCHAIN`` variable defaults to "0" if - ``SDK_EXT_TYPE`` is set to "minimal", and defaults to "1" if - ``SDK_EXT_TYPE`` is set to "full". + The :term:`SDK_INCLUDE_TOOLCHAIN` variable defaults to "0" if + :term:`SDK_EXT_TYPE` is set to "minimal", and defaults to "1" if + :term:`SDK_EXT_TYPE` is set to "full". :term:`SDK_INHERIT_BLACKLIST` A list of classes to remove from the :term:`INHERIT` value globally within the extensible SDK configuration. The :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the - default value: - :: + default value:: SDK_INHERIT_BLACKLIST ?= "buildhistory icecc" @@ -6645,7 +6480,7 @@ system and gives an overview of their function and contents. build system is running and thus would be potentially problematic within the extensible SDK. - By default, ``SDK_LOCAL_CONF_BLACKLIST`` is set in the + By default, :term:`SDK_LOCAL_CONF_BLACKLIST` is set in the :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and excludes the following variables: @@ -6688,8 +6523,7 @@ system and gives an overview of their function and contents. :term:`DISTRO`, :term:`TCLIBC`, :term:`SDK_ARCH`, :term:`IMAGE_BASENAME`, and - :term:`TUNE_PKGARCH` variables: - :: + :term:`TUNE_PKGARCH` variables:: SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}" @@ -6700,8 +6534,7 @@ system and gives an overview of their function and contents. :term:`SDK_OUTPUT` The location used by the OpenEmbedded build system when creating SDK output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` - class defines the variable as follows: - :: + class defines the variable as follows:: SDK_DIR = "${WORKDIR}/sdk" SDK_OUTPUT = "${SDK_DIR}/image" @@ -6709,7 +6542,7 @@ system and gives an overview of their function and contents. .. note:: - The ``SDK_OUTPUT`` directory is a temporary directory as it is part of + The :term:`SDK_OUTPUT` directory is a temporary directory as it is part of :term:`WORKDIR` by way of :term:`SDK_DIR`. The final output directory is :term:`SDK_DEPLOY`. @@ -6717,7 +6550,7 @@ system and gives an overview of their function and contents. Specifies a list of architectures compatible with the SDK machine. This variable is set automatically and should not normally be hand-edited. Entries are separated using spaces and listed in order - of priority. The default value for ``SDK_PACKAGE_ARCHS`` is "all any + of priority. The default value for :term:`SDK_PACKAGE_ARCHS` is "all any noarch ${SDK_ARCH}-${SDKPKGSUFFIX}". :term:`SDK_POSTPROCESS_COMMAND` @@ -6732,7 +6565,7 @@ system and gives an overview of their function and contents. :term:`SDK_PREFIX` The toolchain binary prefix used for ``nativesdk`` recipes. The - OpenEmbedded build system uses the ``SDK_PREFIX`` value to set the + OpenEmbedded build system uses the :term:`SDK_PREFIX` value to set the :term:`TARGET_PREFIX` when building ``nativesdk`` recipes. The default value is "${SDK_SYS}-". @@ -6746,9 +6579,9 @@ system and gives an overview of their function and contents. - do_deploy Despite the default value of "" for the - ``SDK_RECRDEP_TASKS`` variable, the above four tasks are always added + :term:`SDK_RECRDEP_TASKS` variable, the above four tasks are always added to the SDK. To specify tasks beyond these four, you need to use the - ``SDK_RECRDEP_TASKS`` variable (e.g. you are defining additional + :term:`SDK_RECRDEP_TASKS` variable (e.g. you are defining additional tasks that are needed in order to build :term:`SDK_TARGETS`). @@ -6759,21 +6592,19 @@ system and gives an overview of their function and contents. The OpenEmbedded build system automatically sets this variable based on :term:`SDK_ARCH`, :term:`SDK_VENDOR`, and - :term:`SDK_OS`. You do not need to set the ``SDK_SYS`` + :term:`SDK_OS`. You do not need to set the :term:`SDK_SYS` variable yourself. :term:`SDK_TARGET_MANIFEST` The manifest file for the target part of the SDK. This file lists all the installed packages that make up the target part of the SDK. The file contains package information on a line-per-package basis as - follows: - :: + follows:: packagename packagearch version The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class - defines the manifest file as follows: - :: + defines the manifest file as follows:: SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest" @@ -6785,7 +6616,7 @@ system and gives an overview of their function and contents. standard or extensible SDK installation. The default value is "${PN}" (i.e. the image from which the SDK is built). - The ``SDK_TARGETS`` variable is an internal variable and typically + The :term:`SDK_TARGETS` variable is an internal variable and typically would not be changed. :term:`SDK_TITLE` @@ -6793,13 +6624,12 @@ system and gives an overview of their function and contents. this title is based on the :term:`DISTRO_NAME` or :term:`DISTRO` variable and is set in the :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as - follows: - :: + follows:: SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" For the default distribution "poky", - ``SDK_TITLE`` is set to "Poky (Yocto Project Reference Distro)". + :term:`SDK_TITLE` is set to "Poky (Yocto Project Reference Distro)". For information on how to change this default title, see the ":ref:`sdk-manual/appendix-customizing:changing the extensible sdk installer title`" @@ -6817,8 +6647,7 @@ system and gives an overview of their function and contents. :term:`SDK_VERSION` Specifies the version of the SDK. The Poky distribution configuration file (``/meta-poky/conf/distro/poky.conf``) sets the default - ``SDK_VERSION`` as follows: - :: + :term:`SDK_VERSION` as follows:: SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}" @@ -6831,13 +6660,12 @@ system and gives an overview of their function and contents. default, this directory is based on the :term:`DISTRO` variable and is set in the :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as - follows: - :: + follows:: SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" For the - default distribution "poky", the ``SDKEXTPATH`` is set to "poky_sdk". + default distribution "poky", the :term:`SDKEXTPATH` is set to "poky_sdk". For information on how to change this default directory, see the ":ref:`sdk-manual/appendix-customizing:changing the default sdk installation directory`" @@ -6845,16 +6673,15 @@ system and gives an overview of their function and contents. Extensible Software Development Kit (eSDK) manual. :term:`SDKIMAGE_FEATURES` - Equivalent to ``IMAGE_FEATURES``. However, this variable applies to - the SDK generated from an image using the following command: - :: + Equivalent to :term:`IMAGE_FEATURES`. However, this variable applies to + the SDK generated from an image using the following command:: $ bitbake -c populate_sdk imagename :term:`SDKMACHINE` The machine for which the SDK is built. In other words, the SDK is built such that it runs on the target you specify with the - ``SDKMACHINE`` value. The value points to a corresponding ``.conf`` + :term:`SDKMACHINE` value. The value points to a corresponding ``.conf`` file under ``conf/machine-sdk/``. You can use "i686" and "x86_64" as possible values for this variable. @@ -6866,7 +6693,7 @@ system and gives an overview of their function and contents. .. note:: - You cannot set the ``SDKMACHINE`` + You cannot set the :term:`SDKMACHINE` variable in your distribution configuration file. If you do, the configuration will not take affect. @@ -6891,30 +6718,28 @@ system and gives an overview of their function and contents. building for the target. The flags are passed through the default value of the :term:`TARGET_CFLAGS` variable. - The ``SELECTED_OPTIMIZATION`` variable takes the value of - ``FULL_OPTIMIZATION`` unless ``DEBUG_BUILD`` = "1". If that is the - case, the value of ``DEBUG_OPTIMIZATION`` is used. + The :term:`SELECTED_OPTIMIZATION` variable takes the value of + :term:`FULL_OPTIMIZATION` unless :term:`DEBUG_BUILD` = "1", in which + case the value of :term:`DEBUG_OPTIMIZATION` is used. :term:`SERIAL_CONSOLE` Defines a serial console (TTY) to enable using `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a value that specifies the baud rate followed by the TTY device name - separated by a space. You cannot specify more than one TTY device: - :: + separated by a space. You cannot specify more than one TTY device:: SERIAL_CONSOLE = "115200 ttyS0" .. note:: - The ``SERIAL_CONSOLE`` variable is deprecated. Please use the + The :term:`SERIAL_CONSOLE` variable is deprecated. Please use the :term:`SERIAL_CONSOLES` variable. :term:`SERIAL_CONSOLES` Defines a serial console (TTY) to enable using `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a value that specifies the baud rate followed by the TTY device name - separated by a semicolon. Use spaces to separate multiple devices: - :: + separated by a semicolon. Use spaces to separate multiple devices:: SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" @@ -6924,17 +6749,21 @@ system and gives an overview of their function and contents. ``/proc/console`` before enabling them using getty. This variable allows aliasing in the format: <device>:<alias>. If a device was listed as "sclp_line0" in ``/dev/`` and "ttyS0" was listed in - ``/proc/console``, you would do the following: :: + ``/proc/console``, you would do the following:: SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0" This variable is currently only supported with SysVinit (i.e. not - with systemd). + with systemd). Note that :term:`SERIAL_CONSOLES_CHECK` also requires + ``/etc/inittab`` to be writable when used with SysVinit. This makes it + incompatible with customizations such as the following:: + + EXTRA_IMAGE_FEATURES += "read-only-rootfs" :term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS` A list of recipe dependencies that should not be used to determine signatures of tasks from one recipe when they depend on tasks from - another recipe. For example: :: + another recipe. For example:: SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" @@ -6942,7 +6771,7 @@ system and gives an overview of their function and contents. You can use the special token ``"*"`` on the left-hand side of the dependency to match all recipes except the one on the right-hand - side. Here is an example: :: + side. Here is an example:: SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native" @@ -7021,7 +6850,7 @@ system and gives an overview of their function and contents. :term:`SOURCE_MIRROR_FETCH` When you are fetching files to create a mirror of sources (i.e. - creating a source mirror), setting ``SOURCE_MIRROR_FETCH`` to "1" in + creating a source mirror), setting :term:`SOURCE_MIRROR_FETCH` to "1" in your ``local.conf`` configuration file ensures the source for all recipes are fetched regardless of whether or not a recipe is compatible with the configuration. A recipe is considered @@ -7033,7 +6862,7 @@ system and gives an overview of their function and contents. .. note:: - Do not set the ``SOURCE_MIRROR_FETCH`` + Do not set the :term:`SOURCE_MIRROR_FETCH` variable unless you are creating a source mirror. In other words, do not set the variable during a normal build. @@ -7044,19 +6873,18 @@ system and gives an overview of their function and contents. To use this variable, you must globally inherit the :ref:`own-mirrors <ref-classes-own-mirrors>` class and then provide - the URL to your mirrors. Here is the general syntax: - :: + the URL to your mirrors. Here is the general syntax:: INHERIT += "own-mirrors" SOURCE_MIRROR_URL = "http://example.com/my_source_mirror" .. note:: - You can specify only a single URL in ``SOURCE_MIRROR_URL``. + You can specify only a single URL in :term:`SOURCE_MIRROR_URL`. :term:`SPDXLICENSEMAP` Maps commonly used license names to their SPDX counterparts found in - ``meta/files/common-licenses/``. For the default ``SPDXLICENSEMAP`` + ``meta/files/common-licenses/``. For the default :term:`SPDXLICENSEMAP` mappings, see the ``meta/conf/licenses.conf`` file. For additional information, see the :term:`LICENSE` @@ -7076,8 +6904,7 @@ system and gives an overview of their function and contents. U-Boot recipe. The SPL file type is set to "null" by default in the ``u-boot.inc`` - file as follows: - :: + file as follows:: # Some versions of u-boot build an SPL (Second Program Loader) image that # should be packaged along with the u-boot binary as well as placed in the @@ -7088,7 +6915,7 @@ system and gives an overview of their function and contents. SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}" SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}" - The ``SPL_BINARY`` variable helps form + The :term:`SPL_BINARY` variable helps form various ``SPL_*`` variables used by the OpenEmbedded build system. See the BeagleBone machine configuration example in the @@ -7101,7 +6928,7 @@ system and gives an overview of their function and contents. OpenEmbedded build system which bits to pull in for the build and how to pull them in. For example, if the recipe or append file only needs to fetch a tarball from the Internet, the recipe or append file uses - a single ``SRC_URI`` entry. On the other hand, if the recipe or + a single :term:`SRC_URI` entry. On the other hand, if the recipe or append file needs to fetch a tarball, apply two patches, and include a custom file, the recipe or append file would include four instances of the variable. @@ -7180,8 +7007,8 @@ system and gives an overview of their function and contents. - ``az://`` - Fetches files from an Azure Storage account. - Standard and recipe-specific options for ``SRC_URI`` exist. Here are - standard options: + There are standard and recipe-specific options for :term:`SRC_URI`. Here are + standard ones: - ``apply`` - Whether to apply the patch or not. The default action is to apply the patch. @@ -7199,19 +7026,19 @@ system and gives an overview of their function and contents. :term:`SRCDATE` is equal to or greater than ``mindate``. - - ``maxdate`` - Apply the patch only if ``SRCDATE`` is not later + - ``maxdate`` - Apply the patch only if :term:`SRCDATE` is not later than ``maxdate``. - - ``minrev`` - Apply the patch only if ``SRCREV`` is equal to or + - ``minrev`` - Apply the patch only if :term:`SRCREV` is equal to or greater than ``minrev``. - - ``maxrev`` - Apply the patch only if ``SRCREV`` is not later + - ``maxrev`` - Apply the patch only if :term:`SRCREV` is not later than ``maxrev``. - - ``rev`` - Apply the patch only if ``SRCREV`` is equal to + - ``rev`` - Apply the patch only if :term:`SRCREV` is equal to ``rev``. - - ``notrev`` - Apply the patch only if ``SRCREV`` is not equal to + - ``notrev`` - Apply the patch only if :term:`SRCREV` is not equal to ``rev``. Here are some additional options worth mentioning: @@ -7224,20 +7051,19 @@ system and gives an overview of their function and contents. the Git fetcher is used. - ``subdir`` - Places the file (or extracts its contents) into the - specified subdirectory of ``WORKDIR`` when the local (``file://``) + specified subdirectory of :term:`WORKDIR` when the local (``file://``) fetcher is used. - ``localdir`` - Places the file (or extracts its contents) into - the specified subdirectory of ``WORKDIR`` when the CVS fetcher is + the specified subdirectory of :term:`WORKDIR` when the CVS fetcher is used. - ``subpath`` - Limits the checkout to a specific subpath of the tree when using the Git fetcher is used. - ``name`` - Specifies a name to be used for association with - ``SRC_URI`` checksums or :term:`SRCREV` when you have more than one - file or git repository specified in ``SRC_URI``. For example: - :: + :term:`SRC_URI` checksums or :term:`SRCREV` when you have more than one + file or git repository specified in :term:`SRC_URI`. For example:: SRC_URI = "git://example.com/foo.git;name=first \ git://example.com/bar.git;name=second \ @@ -7254,7 +7080,7 @@ system and gives an overview of their function and contents. :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` By default, the OpenEmbedded build system automatically detects whether ``SRC_URI`` contains files that are machine-specific. If so, - the build system automatically changes ``PACKAGE_ARCH``. Setting this + the build system automatically changes :term:`PACKAGE_ARCH`. Setting this variable to "0" disables this behavior. :term:`SRCDATE` @@ -7266,18 +7092,16 @@ system and gives an overview of their function and contents. Returns the version string of the current package. This string is used to help define the value of :term:`PV`. - The ``SRCPV`` variable is defined in the ``meta/conf/bitbake.conf`` + The :term:`SRCPV` variable is defined in the ``meta/conf/bitbake.conf`` configuration file in the :term:`Source Directory` as - follows: - :: + follows:: SRCPV = "${@bb.fetch2.get_srcrev(d)}" - Recipes that need to define ``PV`` do so with the help of the - ``SRCPV``. For example, the ``ofono`` recipe (``ofono_git.bb``) + Recipes that need to define :term:`PV` do so with the help of the + :term:`SRCPV`. For example, the ``ofono`` recipe (``ofono_git.bb``) located in ``meta/recipes-connectivity`` in the Source Directory - defines ``PV`` as follows: - :: + defines :term:`PV` as follows:: PV = "0.12-git${SRCPV}" @@ -7286,26 +7110,50 @@ system and gives an overview of their function and contents. variable applies to Subversion, Git, Mercurial, and Bazaar only. Note that if you want to build a fixed revision and you want to avoid performing a query on the remote repository every time BitBake parses - your recipe, you should specify a ``SRCREV`` that is a full revision + your recipe, you should specify a :term:`SRCREV` that is a full revision identifier and not just a tag. .. note:: For information on limitations when inheriting the latest revision - of software using ``SRCREV``, see the :term:`AUTOREV` variable + of software using :term:`SRCREV`, see the :term:`AUTOREV` variable description and the ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`" section, which is in the Yocto Project Development Tasks Manual. + :term:`SRCTREECOVEREDTASKS` + A list of tasks that are typically not relevant (and therefore skipped) + when building using the :ref:`externalsrc <ref-classes-externalsrc>` + class. The default value as set in that class file is the set of tasks + that are rarely needed when using external source:: + + SRCTREECOVEREDTASKS ?= "do_patch do_unpack do_fetch" + + The notable exception is when processing external kernel source as + defined in the :ref:`kernel-yocto <ref-classes-kernel-yocto>` + class file (formatted for aesthetics):: + + SRCTREECOVEREDTASKS += "\ + do_validate_branches \ + do_kernel_configcheck \ + do_kernel_checkout \ + do_fetch \ + do_unpack \ + do_patch \ + " + + See the associated :term:`EXTERNALSRC` and :term:`EXTERNALSRC_BUILD` + variables for more information. + :term:`SSTATE_DIR` The directory for the shared state cache. :term:`SSTATE_MIRROR_ALLOW_NETWORK` If set to "1", allows fetches from mirrors that are specified in :term:`SSTATE_MIRRORS` to work even when - fetching from the network is disabled by setting ``BB_NO_NETWORK`` to - "1". Using the ``SSTATE_MIRROR_ALLOW_NETWORK`` variable is useful if - you have set ``SSTATE_MIRRORS`` to point to an internal server for + fetching from the network is disabled by setting :term:`BB_NO_NETWORK` to + "1". Using the :term:`SSTATE_MIRROR_ALLOW_NETWORK` variable is useful if + you have set :term:`SSTATE_MIRRORS` to point to an internal server for your shared state cache, but you want to disable any other fetching from the network. @@ -7323,13 +7171,12 @@ system and gives an overview of their function and contents. When pointing to sstate build artifacts on another machine that uses a different GCC version for native builds, you must configure - ``SSTATE_MIRRORS`` with a regular expression that maps local search + :term:`SSTATE_MIRRORS` with a regular expression that maps local search paths to server paths. The paths need to take into account :term:`NATIVELSBSTRING` set by the :ref:`uninative <ref-classes-uninative>` class. For example, the following maps the local search path ``universal-4.9`` to the - server-provided path server_url_sstate_path: - :: + server-provided path server_url_sstate_path:: SSTATE_MIRRORS ?= "file://universal-4.9/(.*) http://server_url_sstate_path/universal-4.8/\1 \n" @@ -7353,8 +7200,8 @@ system and gives an overview of their function and contents. (sstate) object during the first stage of preparing the sysroots. That object is scanned for hardcoded paths for original installation locations. The list of files that are scanned for paths is controlled - by the ``SSTATE_SCAN_FILES`` variable. Typically, recipes add files - they want to be scanned to the value of ``SSTATE_SCAN_FILES`` rather + by the :term:`SSTATE_SCAN_FILES` variable. Typically, recipes add files + they want to be scanned to the value of :term:`SSTATE_SCAN_FILES` rather than the variable being comprehensively set. The :ref:`sstate <ref-classes-sstate>` class specifies the default list of files. @@ -7416,7 +7263,7 @@ system and gives an overview of their function and contents. .. note:: - Recipes should never write files directly under the ``STAGING_DIR`` + Recipes should never write files directly under the :term:`STAGING_DIR` directory because the OpenEmbedded build system manages the directory automatically. Instead, files should be installed to ``${``\ :term:`D`\ ``}`` within your recipe's :ref:`ref-tasks-install` @@ -7431,7 +7278,7 @@ system and gives an overview of their function and contents. files. Exceptions include ``-native`` recipes, where the ``do_populate_sysroot`` task instead uses :term:`STAGING_DIR_NATIVE`. Depending on - the type of recipe and the build target, ``STAGING_DIR_HOST`` can + the type of recipe and the build target, :term:`STAGING_DIR_HOST` can have the following values: - For recipes building for the target machine, the value is @@ -7449,7 +7296,7 @@ system and gives an overview of their function and contents. standard build environment variables such as :term:`CPPFLAGS` and :term:`CFLAGS` are set up so that both host paths - and ``STAGING_DIR_NATIVE`` are searched for libraries and + and :term:`STAGING_DIR_NATIVE` are searched for libraries and headers using, for example, GCC's ``-isystem`` option. Thus, the emphasis is that the ``STAGING_DIR*`` variables @@ -7457,7 +7304,7 @@ system and gives an overview of their function and contents. :ref:`ref-tasks-configure`, :ref:`ref-tasks-compile`, and :ref:`ref-tasks-install`. Having the real system - root correspond to ``STAGING_DIR_HOST`` makes conceptual sense + root correspond to :term:`STAGING_DIR_HOST` makes conceptual sense for ``-native`` recipes, as they make use of host headers and libraries. @@ -7468,7 +7315,7 @@ system and gives an overview of their function and contents. :term:`STAGING_DIR_TARGET` Specifies the path to the sysroot used for the system for which the component generates code. For components that do not generate code, - which is the majority, ``STAGING_DIR_TARGET`` is set to match + which is the majority, :term:`STAGING_DIR_TARGET` is set to match :term:`STAGING_DIR_HOST`. Some recipes build binaries that can run on the target system but @@ -7477,8 +7324,8 @@ system and gives an overview of their function and contents. primary system is referred to as the "HOST" and the secondary, or different, system is referred to as the "TARGET". Thus, the binaries run on the "HOST" system and generate binaries for the "TARGET" - system. The ``STAGING_DIR_HOST`` variable points to the sysroot used - for the "HOST" system, while ``STAGING_DIR_TARGET`` points to the + system. The :term:`STAGING_DIR_HOST` variable points to the sysroot used + for the "HOST" system, while :term:`STAGING_DIR_TARGET` points to the sysroot used for the "TARGET" system. :term:`STAGING_ETCDIR_NATIVE` @@ -7503,7 +7350,7 @@ system and gives an overview of their function and contents. Points to the directory containing the kernel build artifacts. Recipes building software that needs to access kernel build artifacts (e.g. ``systemtap-uprobes``) can look in the directory specified with - the ``STAGING_KERNEL_BUILDDIR`` variable to find these artifacts + the :term:`STAGING_KERNEL_BUILDDIR` variable to find these artifacts after the kernel has been built. :term:`STAGING_KERNEL_DIR` @@ -7523,9 +7370,8 @@ system and gives an overview of their function and contents. Specifies the base path used to create recipe stamp files. The path to an actual stamp file is constructed by evaluating this string and then appending additional information. Currently, the default - assignment for ``STAMP`` as set in the ``meta/conf/bitbake.conf`` - file is: - :: + assignment for :term:`STAMP` as set in the ``meta/conf/bitbake.conf`` + file is:: STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" @@ -7551,8 +7397,8 @@ system and gives an overview of their function and contents. :term:`SUMMARY` The short (72 characters or less) summary of the binary package for packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default, - ``SUMMARY`` is used to define the - :term:`DESCRIPTION` variable if ``DESCRIPTION`` is + :term:`SUMMARY` is used to define the + :term:`DESCRIPTION` variable if :term:`DESCRIPTION` is not set in the recipe. :term:`SVNDIR` @@ -7562,8 +7408,7 @@ system and gives an overview of their function and contents. :term:`SYSLINUX_DEFAULT_CONSOLE` Specifies the kernel boot default console. If you want to use a console other than the default, set this variable in your recipe as - follows where "X" is the console number you want to use: - :: + follows where "X" is the console number you want to use:: SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" @@ -7582,8 +7427,7 @@ system and gives an overview of their function and contents. Specifies the alternate serial port or turns it off. To turn off serial, set this variable to an empty string in your recipe. The variable's default value is set in the - :ref:`syslinux <ref-classes-syslinux>` class as follows: - :: + :ref:`syslinux <ref-classes-syslinux>` class as follows:: SYSLINUX_SERIAL ?= "0 115200" @@ -7592,8 +7436,7 @@ system and gives an overview of their function and contents. :term:`SYSLINUX_SERIAL_TTY` Specifies the alternate console=tty... kernel boot argument. The variable's default value is set in the - :ref:`syslinux <ref-classes-syslinux>` class as follows: - :: + :ref:`syslinux <ref-classes-syslinux>` class as follows:: SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" @@ -7616,8 +7459,7 @@ system and gives an overview of their function and contents. :term:`SYSROOT_DIRS` Directories that are staged into the sysroot by the :ref:`ref-tasks-populate_sysroot` task. By - default, the following directories are staged: - :: + default, the following directories are staged:: SYSROOT_DIRS = " \ ${includedir} \ @@ -7632,8 +7474,7 @@ system and gives an overview of their function and contents. :ref:`ref-tasks-populate_sysroot` task. You can use this variable to exclude certain subdirectories of directories listed in :term:`SYSROOT_DIRS` from - staging. By default, the following directories are not staged: - :: + staging. By default, the following directories are not staged:: SYSROOT_DIRS_BLACKLIST = " \ ${mandir} \ @@ -7650,8 +7491,7 @@ system and gives an overview of their function and contents. :ref:`ref-tasks-populate_sysroot` task for ``-native`` recipes, in addition to those specified in :term:`SYSROOT_DIRS`. By default, the following - extra directories are staged: - :: + extra directories are staged:: SYSROOT_DIRS_NATIVE = " \ ${bindir} \ @@ -7680,8 +7520,7 @@ system and gives an overview of their function and contents. :term:`SYSTEMD_SERVICE` should start automatically or not. By default, the service is enabled to automatically start at boot time. The default setting is in the - :ref:`systemd <ref-classes-systemd>` class as follows: - :: + :ref:`systemd <ref-classes-systemd>` class as follows:: SYSTEMD_AUTO_ENABLE ??= "enable" @@ -7689,11 +7528,10 @@ system and gives an overview of their function and contents. :term:`SYSTEMD_BOOT_CFG` When :term:`EFI_PROVIDER` is set to - "systemd-boot", the ``SYSTEMD_BOOT_CFG`` variable specifies the + "systemd-boot", the :term:`SYSTEMD_BOOT_CFG` variable specifies the configuration file that should be used. By default, the :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the - ``SYSTEMD_BOOT_CFG`` as follows: - :: + :term:`SYSTEMD_BOOT_CFG` as follows:: SYSTEMD_BOOT_CFG ?= "${:term:`S`}/loader.conf" @@ -7702,12 +7540,11 @@ system and gives an overview of their function and contents. :term:`SYSTEMD_BOOT_ENTRIES` When :term:`EFI_PROVIDER` is set to - "systemd-boot", the ``SYSTEMD_BOOT_ENTRIES`` variable specifies a + "systemd-boot", the :term:`SYSTEMD_BOOT_ENTRIES` variable specifies a list of entry files (``*.conf``) to install that contain one boot entry per file. By default, the :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the - ``SYSTEMD_BOOT_ENTRIES`` as follows: - :: + :term:`SYSTEMD_BOOT_ENTRIES` as follows:: SYSTEMD_BOOT_ENTRIES ?= "" @@ -7716,11 +7553,10 @@ system and gives an overview of their function and contents. :term:`SYSTEMD_BOOT_TIMEOUT` When :term:`EFI_PROVIDER` is set to - "systemd-boot", the ``SYSTEMD_BOOT_TIMEOUT`` variable specifies the + "systemd-boot", the :term:`SYSTEMD_BOOT_TIMEOUT` variable specifies the boot menu timeout in seconds. By default, the :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the - ``SYSTEMD_BOOT_TIMEOUT`` as follows: - :: + :term:`SYSTEMD_BOOT_TIMEOUT` as follows:: SYSTEMD_BOOT_TIMEOUT ?= "10" @@ -7730,15 +7566,14 @@ system and gives an overview of their function and contents. :term:`SYSTEMD_PACKAGES` When inheriting the :ref:`systemd <ref-classes-systemd>` class, this variable locates the systemd unit files when they are not found - in the main recipe's package. By default, the ``SYSTEMD_PACKAGES`` + in the main recipe's package. By default, the :term:`SYSTEMD_PACKAGES` variable is set such that the systemd unit files are assumed to - reside in the recipes main package: - :: + reside in the recipes main package:: SYSTEMD_PACKAGES ?= "${PN}" If these unit files are not in this recipe's main package, you need - to use ``SYSTEMD_PACKAGES`` to list the package or packages in which + to use :term:`SYSTEMD_PACKAGES` to list the package or packages in which the build system can find the systemd unit files. :term:`SYSTEMD_SERVICE` @@ -7747,8 +7582,7 @@ system and gives an overview of their function and contents. When you specify this file in your recipe, use a package name override to indicate the package to which the value applies. Here is - an example from the connman recipe: - :: + an example from the connman recipe:: SYSTEMD_SERVICE_${PN} = "connman.service" @@ -7760,14 +7594,13 @@ system and gives an overview of their function and contents. (allowing login), assuming :term:`USE_VT` is not set to "0". - The default value for ``SYSVINIT_ENABLED_GETTYS`` is "1" (i.e. only + The default value for :term:`SYSVINIT_ENABLED_GETTYS` is "1" (i.e. only run a getty on the first virtual terminal). :term:`T` This variable points to a directory were BitBake places temporary files, which consist mostly of task logs and scripts, when building a - particular recipe. The variable is typically set as follows: - :: + particular recipe. The variable is typically set as follows:: T = "${WORKDIR}/temp" @@ -7775,7 +7608,7 @@ system and gives an overview of their function and contents. BitBake unpacks and builds the recipe. The default ``bitbake.conf`` file sets this variable. - The ``T`` variable is not to be confused with the + The :term:`T` variable is not to be confused with the :term:`TMPDIR` variable, which points to the root of the directory tree where BitBake places the output of an entire build. @@ -7799,29 +7632,28 @@ system and gives an overview of their function and contents. :term:`TARGET_AS_ARCH` Specifies architecture-specific assembler flags for the target - system. ``TARGET_AS_ARCH`` is initialized from + system. :term:`TARGET_AS_ARCH` is initialized from :term:`TUNE_ASARGS` by default in the BitBake - configuration file (``meta/conf/bitbake.conf``): - :: + configuration file (``meta/conf/bitbake.conf``):: TARGET_AS_ARCH = "${TUNE_ASARGS}" :term:`TARGET_CC_ARCH` Specifies architecture-specific C compiler flags for the target - system. ``TARGET_CC_ARCH`` is initialized from + system. :term:`TARGET_CC_ARCH` is initialized from :term:`TUNE_CCARGS` by default. .. note:: It is a common workaround to append :term:`LDFLAGS` to - ``TARGET_CC_ARCH`` in recipes that build software for the target that - would not otherwise respect the exported ``LDFLAGS`` variable. + :term:`TARGET_CC_ARCH` in recipes that build software for the target that + would not otherwise respect the exported :term:`LDFLAGS` variable. :term:`TARGET_CC_KERNEL_ARCH` This is a specific kernel compiler flag for a CPU or Application Binary Interface (ABI) tune. The flag is used rarely and only for cases where a userspace :term:`TUNE_CCARGS` is not - compatible with the kernel compilation. The ``TARGET_CC_KERNEL_ARCH`` + compatible with the kernel compilation. The :term:`TARGET_CC_KERNEL_ARCH` variable allows the kernel (and associated modules) to use a different configuration. See the ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the @@ -7833,8 +7665,8 @@ system and gives an overview of their function and contents. :term:`CFLAGS` is set to the value of this variable by default. - Additionally, the SDK's environment setup script sets the ``CFLAGS`` - variable in the environment to the ``TARGET_CFLAGS`` value so that + Additionally, the SDK's environment setup script sets the :term:`CFLAGS` + variable in the environment to the :term:`TARGET_CFLAGS` value so that executables built using the SDK also have the flags applied. :term:`TARGET_CPPFLAGS` @@ -7844,7 +7676,7 @@ system and gives an overview of their function and contents. value of this variable by default. Additionally, the SDK's environment setup script sets the - ``CPPFLAGS`` variable in the environment to the ``TARGET_CPPFLAGS`` + :term:`CPPFLAGS` variable in the environment to the :term:`TARGET_CPPFLAGS` value so that executables built using the SDK also have the flags applied. @@ -7855,7 +7687,7 @@ system and gives an overview of their function and contents. by default. Additionally, the SDK's environment setup script sets the - ``CXXFLAGS`` variable in the environment to the ``TARGET_CXXFLAGS`` + :term:`CXXFLAGS` variable in the environment to the :term:`TARGET_CXXFLAGS` value so that executables built using the SDK also have the flags applied. @@ -7867,10 +7699,9 @@ system and gives an overview of their function and contents. :term:`TARGET_LD_ARCH` Specifies architecture-specific linker flags for the target system. - ``TARGET_LD_ARCH`` is initialized from + :term:`TARGET_LD_ARCH` is initialized from :term:`TUNE_LDARGS` by default in the BitBake - configuration file (``meta/conf/bitbake.conf``): - :: + configuration file (``meta/conf/bitbake.conf``):: TARGET_LD_ARCH = "${TUNE_LDARGS}" @@ -7882,14 +7713,14 @@ system and gives an overview of their function and contents. Additionally, the SDK's environment setup script sets the :term:`LDFLAGS` variable in the environment to the - ``TARGET_LDFLAGS`` value so that executables built using the SDK also + :term:`TARGET_LDFLAGS` value so that executables built using the SDK also have the flags applied. :term:`TARGET_OS` Specifies the target's operating system. The variable can be set to "linux" for glibc-based systems (GNU C Library) and to "linux-musl" - for musl libc. For ARM/EABI targets, "linux-gnueabi" and - "linux-musleabi" possible values exist. + for musl libc. For ARM/EABI targets, the possible values are + "linux-gnueabi" and "linux-musleabi". :term:`TARGET_PREFIX` Specifies the prefix used for the toolchain binary target tools. @@ -7904,7 +7735,7 @@ system and gives an overview of their function and contents. value of ``BUILD_PREFIX``. - For native SDK recipes (``nativesdk``), the build system sets the - variable to the value of ``SDK_PREFIX``. + variable to the value of :term:`SDK_PREFIX`. :term:`TARGET_SYS` Specifies the system, including the architecture and the operating @@ -7918,7 +7749,7 @@ system and gives an overview of their function and contents. .. note:: - You do not need to set the ``TARGET_SYS`` variable yourself. + You do not need to set the :term:`TARGET_SYS` variable yourself. Consider these two examples: @@ -7949,11 +7780,11 @@ system and gives an overview of their function and contents. In the ``defaultsetup.conf`` file, the default value of ``TCLIBCAPPEND`` is "-${TCLIBC}". However, distros such as poky, which normally only support one ``libc`` variant, set - ``TCLIBCAPPEND`` to "" in their distro configuration file resulting + :term:`TCLIBCAPPEND` to "" in their distro configuration file resulting in no suffix being applied. :term:`TCMODE` - Specifies the toolchain selector. ``TCMODE`` controls the + Specifies the toolchain selector. :term:`TCMODE` controls the characteristics of the generated packages and images by telling the OpenEmbedded build system which toolchain profile to use. By default, the OpenEmbedded build system builds its own internal toolchain. The @@ -7962,7 +7793,7 @@ system and gives an overview of their function and contents. .. note:: - If ``TCMODE`` is set to a value other than "default", then it is your + If :term:`TCMODE` is set to a value other than "default", then it is your responsibility to ensure that the toolchain is compatible with the default toolchain. Using older or newer versions of these components might cause build problems. See the Release Notes for @@ -7972,7 +7803,7 @@ system and gives an overview of their function and contents. page on the Yocto Project website and click on the "RELEASE INFORMATION" link for the appropriate release. - The ``TCMODE`` variable is similar to :term:`TCLIBC`, + The :term:`TCMODE` variable is similar to :term:`TCLIBC`, which controls the variant of the GNU standard C library (``libc``) used during the build process: ``glibc`` or ``musl``. @@ -7998,7 +7829,7 @@ system and gives an overview of their function and contents. the :term:`TEST_EXPORT_ONLY` variable is set to "1". - The ``TEST_EXPORT_DIR`` variable defaults to + The :term:`TEST_EXPORT_DIR` variable defaults to ``"${TMPDIR}/testimage/${PN}"``. :term:`TEST_EXPORT_ONLY` @@ -8008,7 +7839,7 @@ system and gives an overview of their function and contents. :term:`TEST_LOG_DIR` Holds the SSH log and the boot log for QEMU machines. The - ``TEST_LOG_DIR`` variable defaults to ``"${WORKDIR}/testimage"``. + :term:`TEST_LOG_DIR` variable defaults to ``"${WORKDIR}/testimage"``. .. note:: @@ -8028,7 +7859,7 @@ system and gives an overview of their function and contents. For automated hardware testing, specifies additional arguments to pass through to the command specified in :term:`TEST_POWERCONTROL_CMD`. Setting - ``TEST_POWERCONTROL_EXTRA_ARGS`` is optional. You can use it if you + :term:`TEST_POWERCONTROL_EXTRA_ARGS` is optional. You can use it if you wish, for example, to separate the machine-specific and non-machine-specific parts of the arguments. @@ -8051,8 +7882,7 @@ system and gives an overview of their function and contents. program does. For example, to use the Picocom terminal program on serial device - ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows: - :: + ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows:: TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" @@ -8060,7 +7890,7 @@ system and gives an overview of their function and contents. For automated hardware testing, specifies additional arguments to pass through to the command specified in :term:`TEST_SERIALCONTROL_CMD`. Setting - ``TEST_SERIALCONTROL_EXTRA_ARGS`` is optional. You can use it if you + :term:`TEST_SERIALCONTROL_EXTRA_ARGS` is optional. You can use it if you wish, for example, to separate the machine-specific and non-machine-specific parts of the command. @@ -8072,7 +7902,7 @@ system and gives an overview of their function and contents. .. note:: - The ``TEST_SERVER_IP`` variable is only used for a small number of + The :term:`TEST_SERVER_IP` variable is only used for a small number of tests such as the "dnf" test suite, which needs to download packages from ``WORKDIR/oe-rootfs-repo``. @@ -8089,9 +7919,8 @@ system and gives an overview of their function and contents. QEMU. Tests include ``ping``, ``ssh``, ``df`` among others. You can add - your own tests to the list of tests by appending ``TEST_SUITES`` as - follows: - :: + your own tests to the list of tests by appending :term:`TEST_SUITES` as + follows:: TEST_SUITES_append = " mytest" @@ -8110,8 +7939,7 @@ system and gives an overview of their function and contents. another test must appear later in the list than the test on which they depend. For example, if you append the list of tests with two tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on - ``test_A``, then you must order the tests as follows: - :: + ``test_A``, then you must order the tests as follows:: TEST_SUITES = "test_A test_B" @@ -8121,8 +7949,7 @@ system and gives an overview of their function and contents. :term:`TEST_TARGET` Specifies the target controller to use when running tests against a - test image. The default controller to use is "qemu": - :: + test image. The default controller to use is "qemu":: TEST_TARGET = "qemu" @@ -8131,7 +7958,7 @@ system and gives an overview of their function and contents. the controllers by adding a module in the layer's ``/lib/oeqa/controllers`` directory and by inheriting the ``BaseTarget`` class, which is an abstract class that cannot be used - as a value of ``TEST_TARGET``. + as a value of :term:`TEST_TARGET`. You can provide the following arguments with ``TEST_TARGET``: @@ -8156,13 +7983,12 @@ system and gives an overview of their function and contents. section in the Yocto Project Development Tasks Manual. :term:`TEST_TARGET_IP` - The IP address of your hardware under test. The ``TEST_TARGET_IP`` + The IP address of your hardware under test. The :term:`TEST_TARGET_IP` variable has no effect when :term:`TEST_TARGET` is set to "qemu". When you specify the IP address, you can also include a port. Here is - an example: - :: + an example:: TEST_TARGET_IP = "192.168.1.4:2201" @@ -8174,7 +8000,7 @@ system and gives an overview of their function and contents. :term:`TESTIMAGE_AUTO` Automatically runs the series of automated tests for images when an - image is successfully built. Setting ``TESTIMAGE_AUTO`` to "1" causes + image is successfully built. Setting :term:`TESTIMAGE_AUTO` to "1" causes any image that successfully builds to automatically boot under QEMU. Using the variable also adds in dependencies so that any SDK for which testing is requested is automatically built first. @@ -8206,24 +8032,23 @@ system and gives an overview of their function and contents. :term:`TMPDIR` This variable is the base directory the OpenEmbedded build system uses for all build output and intermediate files (other than the - shared state cache). By default, the ``TMPDIR`` variable points to + shared state cache). By default, the :term:`TMPDIR` variable points to ``tmp`` within the :term:`Build Directory`. If you want to establish this directory in a location other than the default, you can uncomment and edit the following statement in the - ``conf/local.conf`` file in the :term:`Source Directory`: - :: + ``conf/local.conf`` file in the :term:`Source Directory`:: #TMPDIR = "${TOPDIR}/tmp" - An example use for this scenario is to set ``TMPDIR`` to a local disk, + An example use for this scenario is to set :term:`TMPDIR` to a local disk, which does not use NFS, while having the Build Directory use NFS. - The filesystem used by ``TMPDIR`` must have standard filesystem + The filesystem used by :term:`TMPDIR` must have standard filesystem semantics (i.e. mixed-case files are unique, POSIX file locking, and persistent inodes). Due to various issues with NFS and bugs in some implementations, NFS does not meet this minimum requirement. - Consequently, ``TMPDIR`` cannot be on NFS. + Consequently, :term:`TMPDIR` cannot be on NFS. :term:`TOOLCHAIN_HOST_TASK` This variable lists packages the OpenEmbedded build system uses when @@ -8231,8 +8056,7 @@ system and gives an overview of their function and contents. packages specified by this variable are part of the toolchain set that runs on the :term:`SDKMACHINE`, and each package should usually have the prefix ``nativesdk-``. For example, - consider the following command when building an SDK: - :: + consider the following command when building an SDK:: $ bitbake -c populate_sdk imagename @@ -8253,8 +8077,7 @@ system and gives an overview of their function and contents. :term:`TOOLCHAIN_OUTPUTNAME` This variable defines the name used for the toolchain output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets - the ``TOOLCHAIN_OUTPUTNAME`` variable as follows: - :: + the :term:`TOOLCHAIN_OUTPUTNAME` variable as follows:: TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" @@ -8290,7 +8113,7 @@ system and gives an overview of their function and contents. variable is used where the architecture is needed in a value where underscores are not allowed, for example within package filenames. In this case, dash characters replace any underscore characters used in - ``TARGET_ARCH``. + :term:`TARGET_ARCH`. Do not edit this variable. @@ -8299,19 +8122,18 @@ system and gives an overview of their function and contents. ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses this value to setup configuration. - ``TUNE_ARCH`` definitions are specific to a given architecture. The + :term:`TUNE_ARCH` definitions are specific to a given architecture. The definitions can be a single static definition, or can be dynamically adjusted. You can see details for a given CPU family by looking at the architecture's ``README`` file. For example, the ``meta/conf/machine/include/mips/README`` file in the :term:`Source Directory` provides information for - ``TUNE_ARCH`` specific to the ``mips`` architecture. + :term:`TUNE_ARCH` specific to the ``mips`` architecture. - ``TUNE_ARCH`` is tied closely to + :term:`TUNE_ARCH` is tied closely to :term:`TARGET_ARCH`, which defines the target machine's architecture. The BitBake configuration file - (``meta/conf/bitbake.conf``) sets ``TARGET_ARCH`` as follows: - :: + (``meta/conf/bitbake.conf``) sets :term:`TARGET_ARCH` as follows:: TARGET_ARCH = "${TUNE_ARCH}" @@ -8329,12 +8151,11 @@ system and gives an overview of their function and contents. :term:`TUNE_ASARGS` Specifies architecture-specific assembler flags for the target system. The set of flags is based on the selected tune features. - ``TUNE_ASARGS`` is set using the tune include files, which are + :term:`TUNE_ASARGS` is set using the tune include files, which are typically under ``meta/conf/machine/include/`` and are influenced through :term:`TUNE_FEATURES`. For example, the ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags - for the x86 architecture as follows: - :: + for the x86 architecture as follows:: TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" @@ -8347,7 +8168,7 @@ system and gives an overview of their function and contents. :term:`TUNE_CCARGS` Specifies architecture-specific C compiler flags for the target system. The set of flags is based on the selected tune features. - ``TUNE_CCARGS`` is set using the tune include files, which are + :term:`TUNE_CCARGS` is set using the tune include files, which are typically under ``meta/conf/machine/include/`` and are influenced through :term:`TUNE_FEATURES`. @@ -8367,8 +8188,7 @@ system and gives an overview of their function and contents. are not conflicting and that they are supported. The BitBake configuration file (``meta/conf/bitbake.conf``) defines - ``TUNE_FEATURES`` as follows: - :: + :term:`TUNE_FEATURES` as follows:: TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}" @@ -8377,12 +8197,11 @@ system and gives an overview of their function and contents. :term:`TUNE_LDARGS` Specifies architecture-specific linker flags for the target system. The set of flags is based on the selected tune features. - ``TUNE_LDARGS`` is set using the tune include files, which are + :term:`TUNE_LDARGS` is set using the tune include files, which are typically under ``meta/conf/machine/include/`` and are influenced through :term:`TUNE_FEATURES`. For example, the ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags - for the x86 architecture as follows: - :: + for the x86 architecture as follows:: TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}" @@ -8395,27 +8214,25 @@ system and gives an overview of their function and contents. :term:`TUNE_PKGARCH` The package architecture understood by the packaging system to define the architecture, ABI, and tuning of output packages. The specific - tune is defined using the "_tune" override as follows: - :: + tune is defined using the "_tune" override as follows:: TUNE_PKGARCH_tune-tune = "tune" These tune-specific package architectures are defined in the machine include files. Here is an example of the "core2-32" tuning as used in - the ``meta/conf/machine/include/tune-core2.inc`` file: - :: + the ``meta/conf/machine/include/tune-core2.inc`` file:: TUNE_PKGARCH_tune-core2-32 = "core2-32" :term:`TUNEABI` An underlying Application Binary Interface (ABI) used by a particular tuning in a given toolchain layer. Providers that use prebuilt - libraries can use the ``TUNEABI``, + libraries can use the :term:`TUNEABI`, :term:`TUNEABI_OVERRIDE`, and :term:`TUNEABI_WHITELIST` variables to check compatibility of tunings against their selection of libraries. - If ``TUNEABI`` is undefined, then every tuning is allowed. See the + If :term:`TUNEABI` is undefined, then every tuning is allowed. See the :ref:`sanity <ref-classes-sanity>` class to see how the variable is used. @@ -8423,7 +8240,7 @@ system and gives an overview of their function and contents. If set, the OpenEmbedded system ignores the :term:`TUNEABI_WHITELIST` variable. Providers that use prebuilt libraries can use the - ``TUNEABI_OVERRIDE``, ``TUNEABI_WHITELIST``, and + :term:`TUNEABI_OVERRIDE`, :term:`TUNEABI_WHITELIST`, and :term:`TUNEABI` variables to check compatibility of a tuning against their selection of libraries. @@ -8432,9 +8249,9 @@ system and gives an overview of their function and contents. :term:`TUNEABI_WHITELIST` A whitelist of permissible :term:`TUNEABI` values. If - ``TUNEABI_WHITELIST`` is not set, all tunes are allowed. Providers - that use prebuilt libraries can use the ``TUNEABI_WHITELIST``, - :term:`TUNEABI_OVERRIDE`, and ``TUNEABI`` + :term:`TUNEABI_WHITELIST` is not set, all tunes are allowed. Providers + that use prebuilt libraries can use the :term:`TUNEABI_WHITELIST`, + :term:`TUNEABI_OVERRIDE`, and :term:`TUNEABI` variables to check compatibility of a tuning against their selection of libraries. @@ -8449,8 +8266,7 @@ system and gives an overview of their function and contents. the :term:`Source Directory`. Here is an example from the ``meta/conf/machine/include/mips/arch-mips.inc`` include file that lists the "o32" and "n64" features as conflicting with the "n32" - feature: - :: + feature:: TUNECONFLICTS[n32] = "o32 n64" @@ -8459,8 +8275,7 @@ system and gives an overview of their function and contents. feature. The specified feature is stored as a flag. Valid features are specified in the machine include files (e.g. ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example - from that file: - :: + from that file:: TUNEVALID[bigendian] = "Enable big-endian mode." @@ -8481,43 +8296,42 @@ system and gives an overview of their function and contents. UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config" In this example, "sd" is selected as the configuration of the possible four for the - ``UBOOT_MACHINE``. The "sd" configuration defines - "mx6qsabreauto_config" as the value for ``UBOOT_MACHINE``, while the + :term:`UBOOT_MACHINE`. The "sd" configuration defines + "mx6qsabreauto_config" as the value for :term:`UBOOT_MACHINE`, while the "sdcard" specifies the ``IMAGE_FSTYPES`` to use for the U-Boot image. - For more information on how the ``UBOOT_CONFIG`` is handled, see the + For more information on how the :term:`UBOOT_CONFIG` is handled, see the :ref:`uboot-config <ref-classes-uboot-config>` class. :term:`UBOOT_DTB_LOADADDRESS` Specifies the load address for the dtb image used by U-Boot. During FIT - image creation, the ``UBOOT_DTB_LOADADDRESS`` variable is used in + image creation, the :term:`UBOOT_DTB_LOADADDRESS` variable is used in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the load address to be used in creating the dtb sections of Image Tree Source for the FIT image. :term:`UBOOT_DTBO_LOADADDRESS` Specifies the load address for the dtbo image used by U-Boot. During FIT - image creation, the ``UBOOT_DTBO_LOADADDRESS`` variable is used in + image creation, the :term:`UBOOT_DTBO_LOADADDRESS` variable is used in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the load address to be used in creating the dtbo sections of Image Tree Source for the FIT image. :term:`UBOOT_ENTRYPOINT` Specifies the entry point for the U-Boot image. During U-Boot image - creation, the ``UBOOT_ENTRYPOINT`` variable is passed as a + creation, the :term:`UBOOT_ENTRYPOINT` variable is passed as a command-line parameter to the ``uboot-mkimage`` utility. :term:`UBOOT_LOADADDRESS` Specifies the load address for the U-Boot image. During U-Boot image - creation, the ``UBOOT_LOADADDRESS`` variable is passed as a + creation, the :term:`UBOOT_LOADADDRESS` variable is passed as a command-line parameter to the ``uboot-mkimage`` utility. :term:`UBOOT_LOCALVERSION` Appends a string to the name of the local version of the U-Boot image. For example, assuming the version of the U-Boot image built was "2013.10", the full version string reported by U-Boot would be - "2013.10-yocto" given the following statement: - :: + "2013.10-yocto" given the following statement:: UBOOT_LOCALVERSION = "-yocto" @@ -8561,7 +8375,7 @@ system and gives an overview of their function and contents. :term:`UBOOT_RD_ENTRYPOINT` Specifies the entrypoint for the RAM disk image. During FIT image creation, the - ``UBOOT_RD_ENTRYPOINT`` variable is used + :term:`UBOOT_RD_ENTRYPOINT` variable is used in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the entrypoint to be used in creating the Image Tree Source for the FIT image. @@ -8569,7 +8383,7 @@ system and gives an overview of their function and contents. :term:`UBOOT_RD_LOADADDRESS` Specifies the load address for the RAM disk image. During FIT image creation, the - ``UBOOT_RD_LOADADDRESS`` variable is used + :term:`UBOOT_RD_LOADADDRESS` variable is used in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the load address to be used in creating the Image Tree Source for the FIT image. @@ -8607,20 +8421,19 @@ system and gives an overview of their function and contents. configure options are simply not passed to the configure script (e.g. should be removed from :term:`EXTRA_OECONF` or :term:`PACKAGECONFIG_CONFARGS`). - However, common options, for example, exist that are passed to all - configure scripts at a class level that might not be valid for some - configure scripts. It follows that no benefit exists in seeing a - warning about these options. For these cases, the options are added - to ``UNKNOWN_CONFIGURE_WHITELIST``. + However, there are common options that are passed to all + configure scripts at a class level, but might not be valid for some + configure scripts. Therefore warnings about these options are useless. + For these cases, the options are added to :term:`UNKNOWN_CONFIGURE_WHITELIST`. The configure arguments check that uses - ``UNKNOWN_CONFIGURE_WHITELIST`` is part of the + :term:`UNKNOWN_CONFIGURE_WHITELIST` is part of the :ref:`insane <ref-classes-insane>` class and is only enabled if the recipe inherits the :ref:`autotools <ref-classes-autotools>` class. :term:`UPDATERCPN` For recipes inheriting the - :ref:`update-rc.d <ref-classes-update-rc.d>` class, ``UPDATERCPN`` + :ref:`update-rc.d <ref-classes-update-rc.d>` class, :term:`UPDATERCPN` specifies the package that contains the initscript that is enabled. The default value is "${PN}". Given that almost all recipes that @@ -8634,7 +8447,7 @@ system and gives an overview of their function and contents. OpenEmbedded build system determines the latest upstream version by picking the latest tag from the list of all repository tags. - You can use the ``UPSTREAM_CHECK_GITTAGREGEX`` variable to provide a + You can use the :term:`UPSTREAM_CHECK_GITTAGREGEX` variable to provide a regular expression to filter only the relevant tags should the default filter not work correctly. :: @@ -8642,7 +8455,7 @@ system and gives an overview of their function and contents. UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex" :term:`UPSTREAM_CHECK_REGEX` - Use the ``UPSTREAM_CHECK_REGEX`` variable to specify a different + Use the :term:`UPSTREAM_CHECK_REGEX` variable to specify a different regular expression instead of the default one when the package checking system is parsing the page found using :term:`UPSTREAM_CHECK_URI`. @@ -8656,7 +8469,7 @@ system and gives an overview of their function and contents. the source code is provided from tarballs, the latest version is determined by fetching the directory listing where the tarball is and attempting to find a later tarball. When this approach does not work, - you can use ``UPSTREAM_CHECK_URI`` to provide a different URI that + you can use :term:`UPSTREAM_CHECK_URI` to provide a different URI that contains the link to the latest tarball. :: @@ -8664,8 +8477,8 @@ system and gives an overview of their function and contents. :term:`USE_DEVFS` Determines if ``devtmpfs`` is used for ``/dev`` population. The - default value used for ``USE_DEVFS`` is "1" when no value is - specifically set. Typically, you would set ``USE_DEVFS`` to "0" for a + default value used for :term:`USE_DEVFS` is "1" when no value is + specifically set. Typically, you would set :term:`USE_DEVFS` to "0" for a statically populated ``/dev`` directory. See the ":ref:`dev-manual/common-tasks:selecting a device manager`" section in @@ -8680,8 +8493,8 @@ system and gives an overview of their function and contents. virtual terminals in order to enable logging in through those terminals. - The default value used for ``USE_VT`` is "1" when no default value is - specifically set. Typically, you would set ``USE_VT`` to "0" in the + The default value used for :term:`USE_VT` is "1" when no default value is + specifically set. Typically, you would set :term:`USE_VT` to "0" in the machine configuration file for machines that do not have a graphical display attached and therefore do not need virtual terminal functionality. @@ -8691,8 +8504,7 @@ system and gives an overview of their function and contents. OpenEmbedded build system to enable extra features (e.g. ``buildstats``, ``image-mklibs``, and so forth). - The default list is set in your ``local.conf`` file: - :: + The default list is set in your ``local.conf`` file:: USER_CLASSES ?= "buildstats image-mklibs image-prelink" @@ -8709,11 +8521,10 @@ system and gives an overview of their function and contents. The default behavior for the build system is to dynamically apply ``uid`` and ``gid`` values. Consequently, the - ``USERADD_ERROR_DYNAMIC`` variable is by default not set. If you plan + :term:`USERADD_ERROR_DYNAMIC` variable is by default not set. If you plan on using statically assigned ``gid`` and ``uid`` values, you should - set the ``USERADD_ERROR_DYNAMIC`` variable in your ``local.conf`` - file as follows: - :: + set the :term:`USERADD_ERROR_DYNAMIC` variable in your ``local.conf`` + file as follows:: USERADD_ERROR_DYNAMIC = "error" @@ -8727,7 +8538,7 @@ system and gives an overview of their function and contents. .. note:: There is a difference in behavior between setting - ``USERADD_ERROR_DYNAMIC`` to ``error`` and setting it to ``warn``. + :term:`USERADD_ERROR_DYNAMIC` to ``error`` and setting it to ``warn``. When it is set to ``warn``, the build system will report a warning for every undefined ``uid`` and ``gid`` in any recipe. But when it is set to ``error``, it will only report errors for recipes that are actually @@ -8743,8 +8554,7 @@ system and gives an overview of their function and contents. When applying static group identification (``gid``) values, the OpenEmbedded build system looks in :term:`BBPATH` for a ``files/group`` file and then applies those ``uid`` values. Set the - variable as follows in your ``local.conf`` file: - :: + variable as follows in your ``local.conf`` file:: USERADD_GID_TABLES = "files/group" @@ -8761,14 +8571,13 @@ system and gives an overview of their function and contents. You must set this variable if the recipe inherits the class. For example, the following enables adding a user for the main package in - a recipe: - :: + a recipe:: USERADD_PACKAGES = "${PN}" .. note:: - It follows that if you are going to use the ``USERADD_PACKAGES`` + It follows that if you are going to use the :term:`USERADD_PACKAGES` variable, you need to set one or more of the :term:`USERADD_PARAM`, :term:`GROUPADD_PARAM`, or :term:`GROUPMEMS_PARAM` variables. @@ -8778,8 +8587,7 @@ system and gives an overview of their function and contents. the ``useradd`` command if you add a user to the system when the package is installed. - Here is an example from the ``dbus`` recipe: - :: + Here is an example from the ``dbus`` recipe:: USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \ --no-create-home --shell /bin/false \ @@ -8797,8 +8605,7 @@ system and gives an overview of their function and contents. When applying static user identification (``uid``) values, the OpenEmbedded build system looks in :term:`BBPATH` for a ``files/passwd`` file and then applies those ``uid`` values. Set the - variable as follows in your ``local.conf`` file: - :: + variable as follows in your ``local.conf`` file:: USERADD_UID_TABLES = "files/passwd" @@ -8833,7 +8640,7 @@ system and gives an overview of their function and contents. Specifies the persistence of the target's ``/var/log`` directory, which is used to house postinstall target log files. - By default, ``VOLATILE_LOG_DIR`` is set to "yes", which means the + By default, :term:`VOLATILE_LOG_DIR` is set to "yes", which means the file is not persistent. You can override this setting by setting the variable to "no" to make the log directory persistent. @@ -8855,22 +8662,21 @@ system and gives an overview of their function and contents. :term:`WKS_FILE_DEPENDS` When placed in the recipe that builds your image, this variable lists - build-time dependencies. The ``WKS_FILE_DEPENDS`` variable is only + build-time dependencies. The :term:`WKS_FILE_DEPENDS` variable is only applicable when Wic images are active (i.e. when :term:`IMAGE_FSTYPES` contains entries related to Wic). If your recipe does not create Wic images, the variable has no effect. - The ``WKS_FILE_DEPENDS`` variable is similar to the + The :term:`WKS_FILE_DEPENDS` variable is similar to the :term:`DEPENDS` variable. When you use the variable in your recipe that builds the Wic image, dependencies you list in the - ``WKS_FILE_DEPENDS`` variable are added to the ``DEPENDS`` variable. + :term:`WKS_FILE_DEPENDS` variable are added to the :term:`DEPENDS` variable. - With the ``WKS_FILE_DEPENDS`` variable, you have the possibility to + 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: - :: + Following is an example:: WKS_FILE_DEPENDS = "some-native-tool" @@ -8884,8 +8690,7 @@ system and gives an overview of their function and contents. :term:`TMPDIR` directory structure and is specific to the recipe being built and the system for which it is being built. - The ``WORKDIR`` directory is defined as follows: - :: + The :term:`WORKDIR` directory is defined as follows:: ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} @@ -8904,8 +8709,7 @@ system and gives an overview of their function and contents. ``qemux86-poky-linux`` machine target system. Furthermore, suppose your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work directory the build system uses to build the package would be as - follows: - :: + follows:: poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 @@ -8916,6 +8720,6 @@ system and gives an overview of their function and contents. indirectly, includes "x11-base" in :term:`IMAGE_FEATURES`. - The default value of ``XSERVER``, if not specified in the machine + The default value of :term:`XSERVER`, if not specified in the machine configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev". diff --git a/poky/documentation/releases.rst b/poky/documentation/releases.rst index 6a65b9fb3..890cd037f 100644 --- a/poky/documentation/releases.rst +++ b/poky/documentation/releases.rst @@ -1,20 +1,28 @@ .. SPDX-License-Identifier: CC-BY-SA-2.0-UK -========================= - Current Release Manuals -========================= +=========================== + Supported Release Manuals +=========================== + +****************************** +Release Series 3.3 (hardknott) +****************************** + +- :yocto_docs:`3.3 Documentation </3.3>` +- :yocto_docs:`3.3.1 Documentation </3.3.1>` ******************************* -3.2 'gatesgarth' Release Series +Release Series 3.2 (gatesgarth) ******************************* - :yocto_docs:`3.2 Documentation </3.2>` - :yocto_docs:`3.2.1 Documentation </3.2.1>` - :yocto_docs:`3.2.2 Documentation </3.2.2>` - :yocto_docs:`3.2.3 Documentation </3.2.3>` +- :yocto_docs:`3.2.4 Documentation </3.2.4>` **************************** -3.1 'dunfell' Release Series +Release Series 3.1 (dunfell) **************************** - :yocto_docs:`3.1 Documentation </3.1>` @@ -24,13 +32,15 @@ - :yocto_docs:`3.1.4 Documentation </3.1.4>` - :yocto_docs:`3.1.5 Documentation </3.1.5>` - :yocto_docs:`3.1.6 Documentation </3.1.6>` +- :yocto_docs:`3.1.7 Documentation </3.1.7>` +- :yocto_docs:`3.1.8 Documentation </3.1.8>` ========================== - Previous Release Manuals + Outdated Release Manuals ========================== ************************* -3.0 'zeus' Release Series +Release Series 3.0 (zeus) ************************* - :yocto_docs:`3.0 Documentation </3.0>` @@ -40,7 +50,7 @@ - :yocto_docs:`3.0.4 Documentation </3.0.4>` **************************** -2.7 'warrior' Release Series +Release Series 2.7 (warrior) **************************** - :yocto_docs:`2.7 Documentation </2.7>` @@ -50,7 +60,7 @@ - :yocto_docs:`2.7.4 Documentation </2.7.4>` ************************* -2.6 'thud' Release Series +Release Series 2.6 (thud) ************************* - :yocto_docs:`2.6 Documentation </2.6>` @@ -60,16 +70,16 @@ - :yocto_docs:`2.6.4 Documentation </2.6.4>` ************************* -2.5 'sumo' Release Series +Release Series 2.5 (sumo) ************************* - :yocto_docs:`2.5 Documentation </2.5>` - :yocto_docs:`2.5.1 Documentation </2.5.1>` - :yocto_docs:`2.5.2 Documentation </2.5.2>` - :yocto_docs:`2.5.3 Documentation </2.5.3>` - + ************************** -2.4 'rocko' Release Series +Release Series 2.4 (rocko) ************************** - :yocto_docs:`2.4 Documentation </2.4>` @@ -79,7 +89,7 @@ - :yocto_docs:`2.4.4 Documentation </2.4.4>` ************************* -2.3 'pyro' Release Series +Release Series 2.3 (pyro) ************************* - :yocto_docs:`2.3 Documentation </2.3>` @@ -89,7 +99,7 @@ - :yocto_docs:`2.3.4 Documentation </2.3.4>` ************************** -2.2 'morty' Release Series +Release Series 2.2 (morty) ************************** - :yocto_docs:`2.2 Documentation </2.2>` @@ -98,7 +108,7 @@ - :yocto_docs:`2.2.3 Documentation </2.2.3>` **************************** -2.1 'krogoth' Release Series +Release Series 2.1 (krogoth) **************************** - :yocto_docs:`2.1 Documentation </2.1>` @@ -107,7 +117,7 @@ - :yocto_docs:`2.1.3 Documentation </2.1.3>` *************************** -2.0 'jethro' Release Series +Release Series 2.0 (jethro) *************************** - :yocto_docs:`1.9 Documentation </1.9>` @@ -117,7 +127,7 @@ - :yocto_docs:`2.0.3 Documentation </2.0.3>` ************************* -1.8 'fido' Release Series +Release Series 1.8 (fido) ************************* - :yocto_docs:`1.8 Documentation </1.8>` @@ -125,7 +135,7 @@ - :yocto_docs:`1.8.2 Documentation </1.8.2>` ************************** -1.7 'dizzy' Release Series +Release Series 1.7 (dizzy) ************************** - :yocto_docs:`1.7 Documentation </1.7>` @@ -134,16 +144,16 @@ - :yocto_docs:`1.7.3 Documentation </1.7.3>` ************************** -1.6 'daisy' Release Series +Release Series 1.6 (daisy) ************************** - :yocto_docs:`1.6 Documentation </1.6>` - :yocto_docs:`1.6.1 Documentation </1.6.1>` - :yocto_docs:`1.6.2 Documentation </1.6.2>` - :yocto_docs:`1.6.3 Documentation </1.6.3>` - + ************************* -1.5 'dora' Release Series +Release Series 1.5 (dora) ************************* - :yocto_docs:`1.5 Documentation </1.5>` @@ -153,7 +163,7 @@ - :yocto_docs:`1.5.4 Documentation </1.5.4>` ************************** -1.4 'dylan' Release Series +Release Series 1.4 (dylan) ************************** - :yocto_docs:`1.4 Documentation </1.4>` @@ -162,9 +172,9 @@ - :yocto_docs:`1.4.3 Documentation </1.4.3>` - :yocto_docs:`1.4.4 Documentation </1.4.4>` - :yocto_docs:`1.4.5 Documentation </1.4.5>` - + ************************** -1.3 'danny' Release Series +Release Series 1.3 (danny) ************************** - :yocto_docs:`1.3 Documentation </1.3>` @@ -172,7 +182,7 @@ - :yocto_docs:`1.3.2 Documentation </1.3.2>` *************************** -1.2 'denzil' Release Series +Release Series 1.2 (denzil) *************************** - :yocto_docs:`1.2 Documentation </1.2>` @@ -180,7 +190,7 @@ - :yocto_docs:`1.2.2 Documentation </1.2.2>` *************************** -1.1 'edison' Release Series +Release Series 1.1 (edison) *************************** - :yocto_docs:`1.1 Documentation </1.1>` @@ -188,7 +198,7 @@ - :yocto_docs:`1.1.2 Documentation </1.1.2>` **************************** -1.0 'bernard' Release Series +Release Series 1.0 (bernard) **************************** - :yocto_docs:`1.0 Documentation </1.0>` @@ -196,7 +206,7 @@ - :yocto_docs:`1.0.2 Documentation </1.0.2>` **************************** -0.9 'laverne' Release Series +Release Series 0.9 (laverne) **************************** - :yocto_docs:`0.9 Documentation </0.9>` diff --git a/poky/documentation/sdk-manual/appendix-customizing-standard.rst b/poky/documentation/sdk-manual/appendix-customizing-standard.rst index 90b634529..9bc70cf55 100644 --- a/poky/documentation/sdk-manual/appendix-customizing-standard.rst +++ b/poky/documentation/sdk-manual/appendix-customizing-standard.rst @@ -17,10 +17,10 @@ and variables control the set of packages adding to the SDK. If you want to add individual packages to the toolchain that runs on the -host, simply add those packages to the ``TOOLCHAIN_HOST_TASK`` variable. +host, simply add those packages to the :term:`TOOLCHAIN_HOST_TASK` variable. Similarly, if you want to add packages to the default set that is part of the toolchain that runs on the target, add the packages to the -``TOOLCHAIN_TARGET_TASK`` variable. +:term:`TOOLCHAIN_TARGET_TASK` variable. Adding API Documentation to the Standard SDK ============================================ diff --git a/poky/documentation/sdk-manual/appendix-customizing.rst b/poky/documentation/sdk-manual/appendix-customizing.rst index 8e7115046..44f4334c2 100644 --- a/poky/documentation/sdk-manual/appendix-customizing.rst +++ b/poky/documentation/sdk-manual/appendix-customizing.rst @@ -35,13 +35,13 @@ build system applies them against ``local.conf`` and ``auto.conf``: - Variables listed in :term:`SDK_LOCAL_CONF_WHITELIST` are included. Including a variable in the value of - ``SDK_LOCAL_CONF_WHITELIST`` overrides either of the previous two + :term:`SDK_LOCAL_CONF_WHITELIST` overrides either of the previous two filters. The default value is blank. - Classes inherited globally with :term:`INHERIT` that are listed in :term:`SDK_INHERIT_BLACKLIST` - are disabled. Using ``SDK_INHERIT_BLACKLIST`` to disable these + are disabled. Using :term:`SDK_INHERIT_BLACKLIST` to disable these classes is the typical method to disable classes that are problematic or unnecessary in the SDK context. The default value blacklists the :ref:`buildhistory <ref-classes-buildhistory>` @@ -57,8 +57,7 @@ Adjusting the Extensible SDK to Suit Your Build Host's Setup ============================================================ In most cases, the extensible SDK defaults should work with your :term:`Build -Host`'s setup. -However, some cases exist for which you might consider making +Host`'s setup. However, there are cases when you might consider making adjustments: - If your SDK configuration inherits additional classes using the @@ -75,11 +74,9 @@ adjustments: is set using the "?=" operator. Consequently, you will need to either define the entire list by using the "=" operator, or you will need to append a value using either "_append" or the "+=" - operator. You can learn more about these operators in the " - Basic Syntax - " section of the BitBake User Manual. - - . + operator. You can learn more about these operators in the + ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`" + section of the BitBake User Manual. - If you have classes or recipes that add additional tasks to the standard build flow (i.e. the tasks execute as the recipe builds as @@ -96,7 +93,7 @@ adjustments: - Disable the tasks if they are added by a class and you do not need the functionality the class provides in the extensible SDK. To - disable the tasks, add the class to the ``SDK_INHERIT_BLACKLIST`` + disable the tasks, add the class to the :term:`SDK_INHERIT_BLACKLIST` variable as described in the previous section. - Generally, you want to have a shared state mirror set up so users of @@ -129,8 +126,7 @@ adjustments: .. note:: You must also reflect this change in the value used for the - COREBASE_FILES - variable as previously described. + :term:`COREBASE_FILES` variable as previously described. Changing the Extensible SDK Installer Title =========================================== @@ -143,27 +139,25 @@ section. By default, this title is derived from :term:`DISTRO_NAME` when it is -set. If the ``DISTRO_NAME`` variable is not set, the title is derived +set. If the :term:`DISTRO_NAME` variable is not set, the title is derived from the :term:`DISTRO` variable. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` -class defines the default value of the ``SDK_TITLE`` variable as -follows: -:: +class defines the default value of the :term:`SDK_TITLE` variable as +follows:: SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" -While several ways exist to change this variable, an efficient method is +While there are several ways of changing this variable, an efficient method is to set the variable in your distribution's configuration file. Doing so creates an SDK installer title that applies across your distribution. As an example, assume you have your own layer for your distribution named "meta-mydistro" and you are using the same type of file hierarchy as does the default "poky" distribution. If so, you could update the -``SDK_TITLE`` variable in the +:term:`SDK_TITLE` variable in the ``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following -form: -:: +form:: SDK_TITLE = "your_title" @@ -194,8 +188,7 @@ the installed SDKs to update the installed SDKs by using the 3. Build the extensible SDK normally (i.e., use the ``bitbake -c populate_sdk_ext`` imagename command). -4. Publish the SDK using the following command: - :: +4. Publish the SDK using the following command:: $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory @@ -218,26 +211,24 @@ installation directory for the SDK is based on the :term:`SDKEXTPATH` variables from within the :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` -class as follows: -:: +class as follows:: SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" You can change this default installation directory by specifically setting the -``SDKEXTPATH`` variable. +:term:`SDKEXTPATH` variable. -While a number of ways exist through which you can set this variable, +While there are several ways of setting this variable, the method that makes the most sense is to set the variable in your distribution's configuration file. Doing so creates an SDK installer default directory that applies across your distribution. As an example, assume you have your own layer for your distribution named "meta-mydistro" and you are using the same type of file hierarchy as does the default "poky" distribution. If so, you could update the -``SDKEXTPATH`` variable in the +:term:`SDKEXTPATH` variable in the ``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following -form: -:: +form:: SDKEXTPATH = "some_path_for_your_installed_sdk" @@ -272,13 +263,11 @@ source, you need to do a number of things: 3. Set the appropriate configuration so that the produced SDK knows how to find the configuration. The variable you need to set is - :term:`SSTATE_MIRRORS`: - :: + :term:`SSTATE_MIRRORS`:: SSTATE_MIRRORS = "file://.* http://example.com/some_path/sstate-cache/PATH" - You can set the - ``SSTATE_MIRRORS`` variable in two different places: + You can set the :term:`SSTATE_MIRRORS` variable in two different places: - If the mirror value you are setting is appropriate to be set for both the OpenEmbedded build system that is actually building the @@ -287,23 +276,21 @@ source, you need to do a number of things: side, and its contents will not interfere with the build), then you can set the variable in your ``local.conf`` or custom distro configuration file. You can then "whitelist" the variable through - to the SDK by adding the following: - :: + to the SDK by adding the following:: SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS" - - Alternatively, if you just want to set the ``SSTATE_MIRRORS`` + - Alternatively, if you just want to set the :term:`SSTATE_MIRRORS` variable's value for the SDK alone, create a ``conf/sdk-extra.conf`` file either in your :term:`Build Directory` or within any - layer and put your ``SSTATE_MIRRORS`` setting within that file. + layer and put your :term:`SSTATE_MIRRORS` setting within that file. .. note:: This second option is the safest option should you have any doubts as to which method to use when setting - SSTATE_MIRRORS - . + :term:`SSTATE_MIRRORS` Minimizing the Size of the Extensible SDK Installer Download ============================================================ @@ -313,8 +300,7 @@ everything needed to reconstruct the image for which the SDK was built. This bundling can lead to an SDK installer file that is a Gigabyte or more in size. If the size of this file causes a problem, you can build an SDK that has just enough in it to install and provide access to the -``devtool command`` by setting the following in your configuration: -:: +``devtool command`` by setting the following in your configuration:: SDK_EXT_TYPE = "minimal" @@ -336,14 +322,13 @@ information enables the ``devtool search`` command to return useful results. To facilitate this wider range of information, you would need to set the -following: -:: +following:: SDK_INCLUDE_PKGDATA = "1" See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information. -Setting the ``SDK_INCLUDE_PKGDATA`` variable as shown causes the "world" +Setting the :term:`SDK_INCLUDE_PKGDATA` variable as shown causes the "world" target to be built so that information for all of the recipes included within it are available. Having these recipes available increases build time significantly and increases the size of the SDK installer by 30-80 @@ -360,15 +345,15 @@ in most cases. If you set SDK_EXT_TYPE to "minimal", then providing a shared state mirror is mandatory so - that items can be installed as needed. See the " - Providing Additional Installable Extensible SDK Content - " section for more information. + that items can be installed as needed. See the + :ref:`sdk-manual/appendix-customizing:providing additional installable extensible sdk content` + section for more information. You can explicitly control whether or not to include the toolchain when you build an SDK by setting the :term:`SDK_INCLUDE_TOOLCHAIN` variable to "1". In particular, it is useful to include the toolchain -when you have set ``SDK_EXT_TYPE`` to "minimal", which by default, +when you have set :term:`SDK_EXT_TYPE` to "minimal", which by default, excludes the toolchain. Also, it is helpful if you are building a small SDK for use with an IDE or some other tool where you do not want to take extra steps to install a toolchain. diff --git a/poky/documentation/sdk-manual/appendix-obtain.rst b/poky/documentation/sdk-manual/appendix-obtain.rst index 3c1dc52d1..fc6b8b9d5 100644 --- a/poky/documentation/sdk-manual/appendix-obtain.rst +++ b/poky/documentation/sdk-manual/appendix-obtain.rst @@ -25,8 +25,7 @@ Follow these steps to locate and hand-install the toolchain: download the installer appropriate for your build host, target hardware, and image type. - The installer files (``*.sh``) follow this naming convention: - :: + The installer files (``*.sh``) follow this naming convention:: poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh @@ -55,15 +54,13 @@ Follow these steps to locate and hand-install the toolchain: For example, if your build host is a 64-bit x86 system and you need an extended SDK for a 64-bit core2 target, go into the ``x86_64`` - folder and download the following installer: - :: + folder and download the following installer:: poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh 4. *Run the Installer:* Be sure you have execution privileges and run the installer. Following is an example from the ``Downloads`` - directory: - :: + directory:: $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh @@ -132,8 +129,7 @@ build the SDK installer. Follow these steps: using to build the installer. If SDKMACHINE is not set appropriately, the build fails and provides an error - message similar to the following: - :: + message similar to the following:: The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64). @@ -142,10 +138,11 @@ build the SDK installer. Follow these steps: 6. *Build the SDK Installer:* To build the SDK installer for a standard SDK and populate the SDK image, use the following command form. Be - sure to replace image with an image (e.g. "core-image-sato"): $ - bitbake image -c populate_sdk You can do the same for the extensible - SDK using this command form: - :: + sure to replace ``image`` with an image (e.g. "core-image-sato"):: + + $ bitbake image -c populate_sdk + + You can do the same for the extensible SDK using this command form:: $ bitbake image -c populate_sdk_ext @@ -170,8 +167,7 @@ build the SDK installer. Follow these steps: libc-staticdev" 7. *Run the Installer:* You can now run the SDK installer from - ``tmp/deploy/sdk`` in the Build Directory. Following is an example: - :: + ``tmp/deploy/sdk`` in the Build Directory. Following is an example:: $ cd poky/build/tmp/deploy/sdk $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh @@ -211,8 +207,7 @@ Follow these steps to extract the root filesystem: which you can use with QEMU directly. The pre-built root filesystem image files follow these naming - conventions: - :: + conventions:: core-image-profile-arch.tar.bz2 @@ -233,8 +228,7 @@ Follow these steps to extract the root filesystem: For example, if you plan on using a BeagleBone device as your target hardware and your image is a ``core-image-sato-sdk`` image, you can - download the following file: - :: + download the following file:: core-image-sato-sdk-beaglebone-yocto.tar.bz2 @@ -246,8 +240,7 @@ Follow these steps to extract the root filesystem: installed the toolchain (e.g. ``poky_sdk``). Following is an example based on the toolchain installed in the - ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section: - :: + ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section:: $ source poky_sdk/environment-setup-core2-64-poky-linux @@ -258,12 +251,11 @@ Follow these steps to extract the root filesystem: from a previously built root filesystem image that was downloaded from the :yocto_dl:`Index of Releases </releases/yocto/yocto-&DISTRO;/machines/>`. This command extracts the root filesystem into the ``core2-64-sato`` - directory: - :: + directory:: $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato - You could now point to the target sysroot at ``beablebone-sato``. + You could now point to the target sysroot at ``beaglebone-sato``. Installed Standard SDK Directory Structure ========================================== diff --git a/poky/documentation/sdk-manual/extensible.rst b/poky/documentation/sdk-manual/extensible.rst index baa432ef3..5520a0718 100644 --- a/poky/documentation/sdk-manual/extensible.rst +++ b/poky/documentation/sdk-manual/extensible.rst @@ -15,9 +15,8 @@ hardware, and ease integration into the rest of the .. note:: For a side-by-side comparison of main features supported for an - extensible SDK as compared to a standard SDK, see the " - Introduction - " section. + extensible SDK as compared to a standard SDK, see the + :ref:`sdk-manual/intro:introduction` section. In addition to the functionality available through ``devtool``, you can alternatively make use of the toolchain directly, for example from @@ -59,8 +58,7 @@ The names of the tarball installer scripts are such that a string representing the host system appears first in the filename and then is immediately followed by a string representing the target architecture. An extensible SDK has the string "-ext" as part of the name. Following -is the general form: -:: +is the general form:: poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh @@ -83,17 +81,16 @@ is the general form: For example, the following SDK installer is for a 64-bit development host system and a i586-tuned target architecture based off -the SDK for ``core-image-sato`` and using the current &DISTRO; snapshot: -:: +the SDK for ``core-image-sato`` and using the current &DISTRO; snapshot:: poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh .. note:: As an alternative to downloading an SDK, you can build the SDK - installer. For information on building the installer, see the " - Building an SDK Installer - " section. + installer. For information on building the installer, see the + :ref:`sdk-manual/appendix-obtain:building an sdk installer` + section. The SDK and toolchains are self-contained and by default are installed into the ``poky_sdk`` folder in your home directory. You can choose to @@ -150,8 +147,7 @@ begin with the string "``environment-setup``" and include as part of their name the tuned target architecture. As an example, the following commands set the working directory to where the SDK was installed and then source the environment setup script. In this example, the setup -script is for an IA-based target machine using i586 tuning: -:: +script is for an IA-based target machine using i586 tuning:: $ cd /home/scottrif/poky_sdk $ source environment-setup-core2-64-poky-linux @@ -197,7 +193,7 @@ all the commands. devtool quick reference. -Three ``devtool`` subcommands exist that provide entry-points into +Three ``devtool`` subcommands provide entry-points into development: - *devtool add*: Assists in adding new software to be built. @@ -258,8 +254,7 @@ command: to be extracted. In this situation, the source code is extracted to the default workspace - you do not want the files in some specific location outside of the workspace. Thus, everything you - need will be located in the workspace: - :: + need will be located in the workspace:: $ devtool add recipe fetchuri @@ -280,28 +275,26 @@ command: devtool always creates a Git repository locally during the extraction. - Furthermore, the first positional argument srctree in this case + Furthermore, the first positional argument ``srctree`` in this case identifies where the ``devtool add`` command will locate the extracted code outside of the workspace. You need to specify an - empty directory: - :: + empty directory:: $ devtool add recipe srctree fetchuri In summary, the source code is pulled from fetchuri and extracted into the - location defined by srctree as a local Git repository. + location defined by ``srctree`` as a local Git repository. Within workspace, ``devtool`` creates a recipe named recipe along with an associated append file. - *Right*: The right scenario in the figure represents a situation - where the srctree has been previously prepared outside of the + where the ``srctree`` has been previously prepared outside of the ``devtool`` workspace. The following command provides a new recipe name and identifies - the existing source tree location: - :: + the existing source tree location:: $ devtool add recipe srctree @@ -317,8 +310,7 @@ command: 2. *Edit the Recipe*: You can use ``devtool edit-recipe`` to open up the editor as defined by the ``$EDITOR`` environment variable and modify - the file: - :: + the file:: $ devtool edit-recipe recipe @@ -338,8 +330,7 @@ command: On the other hand, if you want an image to contain the recipe's packages from the workspace for immediate deployment onto a device (e.g. for testing purposes), you can use the ``devtool build-image`` - command: - :: + command:: $ devtool build-image image @@ -435,8 +426,7 @@ command: outside the workspace (i.e. ``meta-``\ layername). The following command identifies the recipe and, by default, - extracts the source files: - :: + extracts the source files:: $ devtool modify recipe @@ -446,9 +436,9 @@ command: locate the source code and any local patch files from other developers. - With this scenario, no srctree argument exists. Consequently, the + With this scenario, there is no ``srctree`` argument. Consequently, the default behavior of the ``devtool modify`` command is to extract - the source files pointed to by the ``SRC_URI`` statements into a + the source files pointed to by the :term:`SRC_URI` statements into a local Git structure. Furthermore, the location for the extracted source is the default area within the ``devtool`` workspace. The result is that the command sets up both the source code and an @@ -456,7 +446,7 @@ command: original location. Additionally, if you have any non-patch local files (i.e. files - referred to with ``file://`` entries in ``SRC_URI`` statement + referred to with ``file://`` entries in :term:`SRC_URI` statement excluding ``*.patch/`` or ``*.diff``), these files are copied to an ``oe-local-files`` folder under the newly created source tree. Copying the files here gives you a convenient area from which you @@ -474,8 +464,7 @@ command: The following command tells ``devtool`` the recipe with which to work and, in this case, identifies a local area for the extracted source files that exists outside of the default ``devtool`` - workspace: - :: + workspace:: $ devtool modify recipe srctree @@ -487,29 +476,28 @@ command: devtool command. - As with all extractions, the command uses the recipe's ``SRC_URI`` + As with all extractions, the command uses the recipe's :term:`SRC_URI` statements to locate the source files and any associated patch files. Non-patch files are copied to an ``oe-local-files`` folder under the newly created source tree. Once the files are located, the command by default extracts them - into srctree. + into ``srctree``. Within workspace, ``devtool`` creates an append file for the recipe. The recipe remains in its original location but the source - files are extracted to the location you provide with srctree. + files are extracted to the location you provide with ``srctree``. - *Right*: The right scenario in the figure represents a situation - where the source tree (srctree) already exists locally as a + where the source tree (``srctree``) already exists locally as a previously extracted Git structure outside of the ``devtool`` workspace. In this example, the recipe also exists elsewhere locally in its own layer. The following command tells ``devtool`` the recipe with which to work, uses the "-n" option to indicate source does not need to be - extracted, and uses srctree to point to the previously extracted - source files: - :: + extracted, and uses ``srctree`` to point to the previously extracted + source files:: $ devtool modify -n recipe srctree @@ -532,8 +520,7 @@ command: depends on what you are going to do with the new code. If you need to eventually move the build output to the target - hardware, use the following ``devtool`` command: - :: + hardware, use the following ``devtool`` command:: $ devtool build recipe @@ -556,8 +543,7 @@ command: development machine. You can deploy your build output to that target hardware by using the - ``devtool deploy-target`` command: - :: + ``devtool deploy-target`` command:: $ devtool deploy-target recipe target @@ -617,11 +603,11 @@ counterparts. .. note:: Several methods exist by which you can upgrade recipes - - devtool upgrade + ``devtool upgrade`` happens to be one. You can read about all the methods by which you - can upgrade recipes in the " - Upgrading Recipes - " section of the Yocto Project Development Tasks Manual. + can upgrade recipes in the + :ref:`dev-manual/common-tasks:upgrading recipes` section + of the Yocto Project Development Tasks Manual. The ``devtool upgrade`` command is flexible enough to allow you to specify source code revision and versioning schemes, extract code into @@ -651,8 +637,7 @@ The following diagram shows the common development flow used with the A common situation is where third-party software has undergone a revision so that it has been upgraded. The recipe you have access to is likely in your own layer. Thus, you need to upgrade the recipe to - use the newer version of the software: - :: + use the newer version of the software:: $ devtool upgrade -V version recipe @@ -660,8 +645,9 @@ The following diagram shows the common development flow used with the code into the ``sources`` directory in the :ref:`devtool-the-workspace-layer-structure`. If you want the code extracted to any other location, you need to - provide the srctree positional argument with the command as follows: - $ devtool upgrade -V version recipe srctree + provide the ``srctree`` positional argument with the command as follows:: + + $ devtool upgrade -V version recipe srctree .. note:: @@ -669,18 +655,18 @@ The following diagram shows the common development flow used with the don't use "-V", the command upgrades the recipe to the latest version. - If the source files pointed to by the ``SRC_URI`` statement in the + If the source files pointed to by the :term:`SRC_URI` statement in the recipe are in a Git repository, you must provide the "-S" option and specify a revision for the software. - Once ``devtool`` locates the recipe, it uses the ``SRC_URI`` variable + Once ``devtool`` locates the recipe, it uses the :term:`SRC_URI` variable to locate the source code and any local patch files from other developers. The result is that the command sets up the source code, the new version of the recipe, and an append file all within the workspace. Additionally, if you have any non-patch local files (i.e. files - referred to with ``file://`` entries in ``SRC_URI`` statement + referred to with ``file://`` entries in :term:`SRC_URI` statement excluding ``*.patch/`` or ``*.diff``), these files are copied to an ``oe-local-files`` folder under the newly created source tree. Copying the files here gives you a convenient area from which you can @@ -688,9 +674,9 @@ The following diagram shows the common development flow used with the are incorporated into the build the next time you build the software just as are other changes you might have made to the source. -2. *Resolve any Conflicts created by the Upgrade*: Conflicts could exist - due to the software being upgraded to a new version. Conflicts occur - if your recipe specifies some patch files in ``SRC_URI`` that +2. *Resolve any Conflicts created by the Upgrade*: Conflicts could happen + after upgrading the software to a new version. Conflicts occur + if your recipe specifies some patch files in :term:`SRC_URI` that conflict with changes made in the new version of the software. For such cases, you need to resolve the conflicts by editing the source and following the normal ``git rebase`` conflict resolution process. @@ -703,16 +689,14 @@ The following diagram shows the common development flow used with the depends on what you are going to do with the new code. If you need to eventually move the build output to the target - hardware, use the following ``devtool`` command: - :: + hardware, use the following ``devtool`` command:: $ devtool build recipe On the other hand, if you want an image to contain the recipe's packages from the workspace for immediate deployment onto a device (e.g. for testing purposes), you can use the ``devtool build-image`` - command: - :: + command:: $ devtool build-image image @@ -828,8 +812,7 @@ name and version, just the name, or just the version as part of the command line. Sometimes the name or version determined from the source tree might be -incorrect. For such a case, you must reset the recipe: -:: +incorrect. For such a case, you must reset the recipe:: $ devtool reset -n recipename @@ -849,12 +832,11 @@ result from naming not being recognized or because the dependency simply is not available. For cases where the dependency is not available, you must use the ``devtool add`` command to add an additional recipe that satisfies the dependency. Once you add that recipe, you need to update -the ``DEPENDS`` variable in the original recipe to include the new +the :term:`DEPENDS` variable in the original recipe to include the new recipe. If you need to add runtime dependencies, you can do so by adding the -following to your recipe: -:: +following to your recipe:: RDEPENDS_${PN} += "dependency1 dependency2 ..." @@ -879,7 +861,7 @@ license. If so, the command sets the :term:`LICENSE` value accordingly. You should double-check the value added by the command against the documentation or source files for the software you are building and, if -necessary, update that ``LICENSE`` value. +necessary, update that :term:`LICENSE` value. The ``devtool add`` command also sets the :term:`LIC_FILES_CHKSUM` @@ -887,16 +869,16 @@ value to point to all files that appear to be license-related. Realize that license statements often appear in comments at the top of source files or within the documentation. In such cases, the command does not recognize those license statements. Consequently, you might need to -amend the ``LIC_FILES_CHKSUM`` variable to point to one or more of those -comments if present. Setting ``LIC_FILES_CHKSUM`` is particularly +amend the :term:`LIC_FILES_CHKSUM` variable to point to one or more of those +comments if present. Setting :term:`LIC_FILES_CHKSUM` is particularly important for third-party software. The mechanism attempts to ensure correct licensing should you upgrade the recipe to a newer upstream version in future. Any change in licensing is detected and you receive an error prompting you to check the license text again. If the ``devtool add`` command cannot determine licensing information, -``devtool`` sets the ``LICENSE`` value to "CLOSED" and leaves the -``LIC_FILES_CHKSUM`` value unset. This behavior allows you to continue +``devtool`` sets the :term:`LICENSE` value to "CLOSED" and leaves the +:term:`LIC_FILES_CHKSUM` value unset. This behavior allows you to continue with development even though the settings are unlikely to be correct in all cases. You should check the documentation or source files for the software you are building to determine the actual license. @@ -922,12 +904,12 @@ mind: hardcoding tools within the toolchain such as ``gcc`` and ``g++``. - The environment in which Make runs is set up with various standard - variables for compilation (e.g. ``CC``, ``CXX``, and so forth) in a + variables for compilation (e.g. :term:`CC`, :term:`CXX`, and so forth) in a similar manner to the environment set up by the SDK's environment setup script. One easy way to see these variables is to run the ``devtool build`` command on the recipe and then look in - ``oe-logs/run.do_compile``. Towards the top of this file, a list of - environment variables exists that are being set. You can take + ``oe-logs/run.do_compile``. Towards the top of this file, there is + a list of environment variables that are set. You can take advantage of these variables within the Makefile. - If the Makefile sets a default for a variable using "=", that default @@ -938,8 +920,7 @@ mind: the command line, add the variable setting to :term:`EXTRA_OEMAKE` or :term:`PACKAGECONFIG_CONFARGS` - within the recipe. Here is an example using ``EXTRA_OEMAKE``: - :: + within the recipe. Here is an example using :term:`EXTRA_OEMAKE`:: EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" @@ -972,7 +953,7 @@ following methods when you run ``devtool add``: Specifying the name like this produces a recipe that only builds for the build host. -- Specify the "DASHDASHalso-native" option with the ``devtool add`` +- Specify the "--also-native" option with the ``devtool add`` command. Specifying this option creates a recipe file that still builds for the target but also creates a variant with a "-native" suffix that builds for the build host. @@ -983,7 +964,7 @@ following methods when you run ``devtool add``: that builds code for the target, you can typically accomplish this by building the native and target parts separately rather than within the same compilation process. Realize though that with the - "DASHDASHalso-native" option, you can add the tool using just one + "--also-native" option, you can add the tool using just one recipe file. Adding Node.js Modules @@ -993,8 +974,7 @@ You can use the ``devtool add`` command two different ways to add Node.js modules: 1) Through ``npm`` and, 2) from a repository or local source. -Use the following form to add Node.js modules through ``npm``: -:: +Use the following form to add Node.js modules through ``npm``:: $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1" @@ -1018,8 +998,7 @@ these behaviors ensure the reproducibility and integrity of the build. As mentioned earlier, you can also add Node.js modules directly from a repository or local source tree. To add modules this way, use -``devtool add`` in the following form: -:: +``devtool add`` in the following form:: $ devtool add https://github.com/diversario/node-ssdp @@ -1058,8 +1037,8 @@ If you look at the contents of a recipe, you will see that the recipe does not include complete instructions for building the software. Instead, common functionality is encapsulated in classes inherited with the ``inherit`` directive. This technique leaves the recipe to describe -just the things that are specific to the software being built. A -:ref:`base <ref-classes-base>` class exists that +just the things that are specific to the software being built. There is +a :ref:`base <ref-classes-base>` class that is implicitly inherited by all recipes and provides the functionality that most recipes typically need. @@ -1107,21 +1086,21 @@ extras specified by :term:`EXTRA_OECONF` or :term:`PACKAGECONFIG_CONFARGS` set within the recipe. If you wish to pass additional options, add them -to ``EXTRA_OECONF`` or ``PACKAGECONFIG_CONFARGS``. Other supported build +to :term:`EXTRA_OECONF` or :term:`PACKAGECONFIG_CONFARGS`. Other supported build tools have similar variables (e.g. :term:`EXTRA_OECMAKE` for CMake, :term:`EXTRA_OESCONS` for Scons, and so forth). If you need to pass anything on the ``make`` -command line, you can use ``EXTRA_OEMAKE`` or the +command line, you can use :term:`EXTRA_OEMAKE` or the :term:`PACKAGECONFIG_CONFARGS` variables to do so. You can use the ``devtool configure-help`` command to help you set the arguments listed in the previous paragraph. The command determines the exact options being passed, and shows them to you along with any custom -arguments specified through ``EXTRA_OECONF`` or -``PACKAGECONFIG_CONFARGS``. If applicable, the command also shows you -the output of the configure script's "DASHDASHhelp" option as a +arguments specified through :term:`EXTRA_OECONF` or +:term:`PACKAGECONFIG_CONFARGS`. If applicable, the command also shows you +the output of the configure script's "--help" option as a reference. Sharing Files Between Recipes @@ -1131,9 +1110,9 @@ Recipes often need to use files provided by other recipes on the :term:`Build Host`. For example, an application linking to a common library needs access to the library itself and its associated headers. The way this access is accomplished -within the extensible SDK is through the sysroot. One sysroot exists per +within the extensible SDK is through the sysroot. There is one sysroot per "machine" for which the SDK is being built. In practical terms, this -means a sysroot exists for the target machine, and a sysroot exists for +means there is a sysroot for the target machine, and a sysroot for the build host. Recipes should never write files directly into the sysroot. Instead, @@ -1172,16 +1151,16 @@ the ``oe-workdir/packages-split`` directory, which contains a subdirectory for each package. Apart from some advanced cases, the :term:`PACKAGES` and :term:`FILES` variables controls -splitting. The ``PACKAGES`` variable lists all of the packages to be -produced, while the ``FILES`` variable specifies which files to include +splitting. The :term:`PACKAGES` variable lists all of the packages to be +produced, while the :term:`FILES` variable specifies which files to include in each package by using an override to specify the package. For example, ``FILES_${PN}`` specifies the files to go into the main package (i.e. the main package has the same name as the recipe and ``${``\ :term:`PN`\ ``}`` evaluates to the -recipe name). The order of the ``PACKAGES`` value is significant. For -each installed file, the first package whose ``FILES`` value matches the -file is the package into which the file goes. Defaults exist for both -the ``PACKAGES`` and ``FILES`` variables. Consequently, you might find +recipe name). The order of the :term:`PACKAGES` value is significant. For +each installed file, the first package whose :term:`FILES` value matches the +file is the package into which the file goes. Both the :term:`PACKAGES` and +:term:`FILES` variables have default values. Consequently, you might find you do not even need to set these variables in your recipe unless the software the recipe is building installs files into non-standard locations. @@ -1196,15 +1175,13 @@ need to restore the original files that existed prior to running the ``devtool deploy-target`` command. Because the ``devtool deploy-target`` command backs up any files it overwrites, you can use the ``devtool undeploy-target`` command to restore those files and remove -any other files the recipe deployed. Consider the following example: -:: +any other files the recipe deployed. Consider the following example:: $ devtool undeploy-target lighttpd root@192.168.7.2 If you have deployed multiple applications, you can remove them all using the "-a" option -thus restoring the target device to its original state: -:: +thus restoring the target device to its original state:: $ devtool undeploy-target -a root@192.168.7.2 @@ -1235,28 +1212,25 @@ populated on-demand. Sometimes you must explicitly install extra items into the SDK. If you need these extra items, you can first search for the items using the ``devtool search`` command. For example, suppose you need to link to libGL but you are not sure which recipe provides libGL. -You can use the following command to find out: -:: +You can use the following command to find out:: $ devtool search libGL mesa A free implementation of the OpenGL API Once you know the recipe -(i.e. ``mesa`` in this example), you can install it: -:: +(i.e. ``mesa`` in this example), you can install it:: $ devtool sdk-install mesa By default, the ``devtool sdk-install`` command assumes the item is available in pre-built form from your SDK provider. If the item is not available and it is acceptable to build the item from -source, you can add the "-s" option as follows: -:: +source, you can add the "-s" option as follows:: $ devtool sdk-install -s mesa It is important to remember that building the item from source takes significantly longer than installing the pre-built artifact. Also, -if no recipe exists for the item you want to add to the SDK, you must +if there is no recipe for the item you want to add to the SDK, you must instead add the item using the ``devtool add`` command. Applying Updates to an Installed Extensible SDK @@ -1266,8 +1240,7 @@ If you are working with an installed extensible SDK that gets occasionally updated (e.g. a third-party SDK), then you will need to manually "pull down" the updates into the installed SDK. -To update your installed SDK, use ``devtool`` as follows: -:: +To update your installed SDK, use ``devtool`` as follows:: $ devtool sdk-update diff --git a/poky/documentation/sdk-manual/intro.rst b/poky/documentation/sdk-manual/intro.rst index d966efea7..2f94aaf87 100644 --- a/poky/documentation/sdk-manual/intro.rst +++ b/poky/documentation/sdk-manual/intro.rst @@ -8,8 +8,8 @@ eSDK Introduction ================= Welcome to the Yocto Project Application Development and the Extensible -Software Development Kit (eSDK) manual. This manual provides information -that explains how to use both the Yocto Project extensible and standard +Software Development Kit (eSDK) manual. This manual +explains how to use both the Yocto Project extensible and standard SDKs to develop applications and images. .. note:: @@ -25,12 +25,13 @@ SDKs to develop applications and images. All SDKs consist of the following: - *Cross-Development Toolchain*: This toolchain contains a compiler, - debugger, and various miscellaneous tools. + debugger, and various associated tools. - *Libraries, Headers, and Symbols*: The libraries, headers, and - symbols are specific to the image (i.e. they match the image). + symbols are specific to the image (i.e. they match the image + against which the SDK was built). -- *Environment Setup Script*: This ``*.sh`` file, once run, sets up the +- *Environment Setup Script*: This ``*.sh`` file, once sourced, sets up the cross-development environment by defining variables and preparing for SDK use. @@ -48,14 +49,14 @@ time since that path cannot be dynamically altered. This is the reason for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext`` archives. -Another feature for the SDKs is that only one set of cross-compiler +Another feature of the SDKs is that only one set of cross-compiler toolchain binaries are produced for any given architecture. This feature takes advantage of the fact that the target hardware can be passed to ``gcc`` as a set of compiler options. Those options are set up by the environment script and contained in variables such as :term:`CC` and :term:`LD`. This reduces the space needed -for the tools. Understand, however, that every target still needs a +for the tools. Understand, however, that every target still needs its own sysroot because those binaries are target-specific. The SDK development environment consists of the following: @@ -118,8 +119,8 @@ The Cross-Development Toolchain The :term:`Cross-Development Toolchain` consists of a cross-compiler, cross-linker, and cross-debugger that are used to -develop user-space applications for targeted hardware. Additionally, for -an extensible SDK, the toolchain also has built-in ``devtool`` +develop user-space applications for targeted hardware; in addition, +the extensible SDK comes with built-in ``devtool`` functionality. This toolchain is created by running a SDK installer script or through a :term:`Build Directory` that is based on your metadata configuration or extension for your targeted device. The @@ -138,21 +139,19 @@ The QEMU Emulator ----------------- The QEMU emulator allows you to simulate your hardware while running -your application or image. QEMU is not part of the SDK but is made -available a number of different ways: +your application or image. QEMU is not part of the SDK but is +automatically installed and available if you have done any one of +the following: -- If you have cloned the ``poky`` Git repository to create a - :term:`Source Directory` and you have - sourced the environment setup script, QEMU is installed and - automatically available. +- cloned the ``poky`` Git repository to create a + :term:`Source Directory` and sourced the environment setup script. -- If you have downloaded a Yocto Project release and unpacked it to - create a Source Directory and you have sourced the environment setup - script, QEMU is installed and automatically available. +- downloaded a Yocto Project release and unpacked it to + create a Source Directory and sourced the environment setup + script. -- If you have installed the cross-toolchain tarball and you have - sourced the toolchain's setup environment script, QEMU is also - installed and automatically available. +- installed the cross-toolchain tarball and + sourced the toolchain's setup environment script. SDK Development Model ===================== @@ -202,10 +201,9 @@ You just need to follow these general steps: .. note:: - To use the root filesystem in QEMU, you need to extract it. See - the " - Extracting the Root Filesystem - " section for information on how to extract the root filesystem. + To use the root filesystem in QEMU, you need to extract it. See the + ":ref:`sdk-manual/appendix-obtain:extracting the root filesystem`" + section for information on how to do this extraction. 3. *Develop and Test your Application:* At this point, you have the tools to develop your application. If you need to separately install @@ -216,5 +214,5 @@ You just need to follow these general steps: within the Yocto Project. The remainder of this manual describes how to use the extensible and -standard SDKs. Information also exists in appendix form that describes +standard SDKs. There is also information in appendix form describing how you can build, install, and modify an SDK. diff --git a/poky/documentation/sdk-manual/using.rst b/poky/documentation/sdk-manual/using.rst index 62967f557..301627812 100644 --- a/poky/documentation/sdk-manual/using.rst +++ b/poky/documentation/sdk-manual/using.rst @@ -11,9 +11,8 @@ standard SDK. .. note:: For a side-by-side comparison of main features supported for a - standard SDK as compared to an extensible SDK, see the " - Introduction - " section. + standard SDK as compared to an extensible SDK, see the + ":ref:`sdk-manual/intro:introduction`" section. You can use a standard SDK to work on Makefile and Autotools-based projects. See the @@ -49,7 +48,7 @@ the Index of Releases. Toolchains are available for several 32-bit and 64-bit architectures with the ``x86_64`` directories, respectively. The toolchains the Yocto Project provides are based off the ``core-image-sato`` and ``core-image-minimal`` images and contain -libraries appropriate for developing against that image. +libraries appropriate for developing against the corresponding image. The names of the tarball installer scripts are such that a string representing the host system appears first in the filename and then is @@ -77,17 +76,16 @@ immediately followed by a string representing the target architecture. For example, the following SDK installer is for a 64-bit development host system and a i586-tuned target architecture based off -the SDK for ``core-image-sato`` and using the current DISTRO snapshot: -:: +the SDK for ``core-image-sato`` and using the current DISTRO snapshot:: poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh .. note:: As an alternative to downloading an SDK, you can build the SDK - installer. For information on building the installer, see the " - Building an SDK Installer - " section. + installer. For information on building the installer, see the + ":ref:`sdk-manual/appendix-obtain:building an sdk installer`" + section. The SDK and toolchains are self-contained and by default are installed into the ``poky_sdk`` folder in your home directory. You can choose to @@ -141,8 +139,7 @@ begin with the string "``environment-setup``" and include as part of their name the tuned target architecture. As an example, the following commands set the working directory to where the SDK was installed and then source the environment setup script. In this example, the setup -script is for an IA-based target machine using i586 tuning: -:: +script is for an IA-based target machine using i586 tuning:: $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux diff --git a/poky/documentation/sdk-manual/working-projects.rst b/poky/documentation/sdk-manual/working-projects.rst index f880cbe0d..276daa9bb 100644 --- a/poky/documentation/sdk-manual/working-projects.rst +++ b/poky/documentation/sdk-manual/working-projects.rst @@ -45,16 +45,14 @@ project: respectively. Use the following command to create an empty README file, which is - required by GNU Coding Standards: - :: + required by GNU Coding Standards:: $ touch README Create the remaining three files as follows: - - ``hello.c``: - :: + - ``hello.c``:: #include <stdio.h> @@ -63,8 +61,7 @@ project: printf("Hello World!\n"); } - - ``configure.ac``: - :: + - ``configure.ac``:: AC_INIT(hello,0.1) AM_INIT_AUTOMAKE([foreign]) @@ -72,8 +69,7 @@ project: AC_CONFIG_FILES(Makefile) AC_OUTPUT - - ``Makefile.am``: - :: + - ``Makefile.am``:: bin_PROGRAMS = hello hello_SOURCES = hello.c @@ -87,8 +83,7 @@ project: which is followed by the string "poky-linux". For this example, the command sources a script from the default SDK installation directory that uses the 32-bit Intel x86 Architecture and the &DISTRO; Yocto - Project release: - :: + Project release:: $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux @@ -113,8 +108,7 @@ project: the cross-compiler. The :term:`CONFIGURE_FLAGS` environment variable provides the minimal arguments for GNU - configure: - :: + configure:: $ ./configure ${CONFIGURE_FLAGS} @@ -127,14 +121,12 @@ project: ``armv5te-poky-linux-gnueabi``. You will notice that the name of the script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the following command works to update your project and rebuild it using - the appropriate cross-toolchain tools: - :: + the appropriate cross-toolchain tools:: $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir 5. *Make and Install the Project:* These two commands generate and - install the project into the destination directory: - :: + install the project into the destination directory:: $ make $ make install DESTDIR=./tmp @@ -143,9 +135,8 @@ project: To learn about environment variables established when you run the cross-toolchain environment setup script and how they are used or - overridden when the Makefile, see the " - Makefile-Based Projects - " section. + overridden by the Makefile, see the + :ref:`sdk-manual/working-projects:makefile-based projects` section. This next command is a simple way to verify the installation of your project. Running the command prints the architecture on which the @@ -157,8 +148,7 @@ project: 6. *Execute Your Project:* To execute the project, you would need to run it on your target hardware. If your target hardware happens to be - your build host, you could run the project as follows: - :: + your build host, you could run the project as follows:: $ ./tmp/usr/local/bin/hello @@ -203,8 +193,7 @@ regarding variable behavior: .. note:: Regardless of how you set your variables, if you use the "-e" option - with ``make``, the variables from the SDK setup script take precedence: - :: + with ``make``, the variables from the SDK setup script take precedence:: $ make -e target @@ -226,8 +215,7 @@ Running the SDK setup script for a 64-bit build host and an i586-tuned target architecture for a ``core-image-sato`` image using the current &DISTRO; Yocto Project release and then echoing that variable shows the value -established through the script: -:: +established through the script:: $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux $ echo ${CC} @@ -252,8 +240,7 @@ example: Create the three files as follows: - - ``main.c``: - :: + - ``main.c``:: #include "module.h" void sample_func(); @@ -263,14 +250,12 @@ example: return 0; } - - ``module.h``: - :: + - ``module.h``:: #include <stdio.h> void sample_func(); - - ``module.c``: - :: + - ``module.c``:: #include "module.h" void sample_func() @@ -288,17 +273,15 @@ example: which is followed by the string "poky-linux". For this example, the command sources a script from the default SDK installation directory that uses the 32-bit Intel x86 Architecture and the &DISTRO_NAME; Yocto - Project release: - :: + Project release:: $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux 3. *Create the Makefile:* For this example, the Makefile contains - two lines that can be used to set the ``CC`` variable. One line is + two lines that can be used to set the :term:`CC` variable. One line is identical to the value that is set when you run the SDK environment - setup script, and the other line sets ``CC`` to "gcc", the default - GNU compiler on the build host: - :: + setup script, and the other line sets :term:`CC` to "gcc", the default + GNU compiler on the build host:: # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux # CC="gcc" @@ -314,9 +297,8 @@ example: 4. *Make the Project:* Use the ``make`` command to create the binary output file. Because variables are commented out in the Makefile, the - value used for ``CC`` is the value set when the SDK environment setup - file was run: - :: + value used for :term:`CC` is the value set when the SDK environment setup + file was run:: $ make i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c @@ -324,10 +306,10 @@ example: i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin From the results of the previous command, you can see that - the compiler used was the compiler established through the ``CC`` + the compiler used was the compiler established through the :term:`CC` variable defined in the setup script. - You can override the ``CC`` environment variable with the same + You can override the :term:`CC` environment variable with the same variable as set from the Makefile by uncommenting the line in the Makefile and running ``make`` again. :: @@ -351,8 +333,7 @@ example: variable as part of the command line. Go into the Makefile and re-insert the comment character so that running ``make`` uses the established SDK compiler. However, when you run ``make``, use a - command-line argument to set ``CC`` to "gcc": - :: + command-line argument to set :term:`CC` to "gcc":: $ make clean rm -rf *.o @@ -376,8 +357,7 @@ example: environment variable. In this last case, edit Makefile again to use the "gcc" compiler but - then use the "-e" option on the ``make`` command line: - :: + then use the "-e" option on the ``make`` command line:: $ make clean rm -rf *.o @@ -402,8 +382,7 @@ example: Makefile. 5. *Execute Your Project:* To execute the project (i.e. ``target_bin``), - use the following command: - :: + use the following command:: $ ./target_bin Hello World! diff --git a/poky/documentation/sphinx-static/switchers.js b/poky/documentation/sphinx-static/switchers.js index 7a4edc9e7..301c2315a 100644 --- a/poky/documentation/sphinx-static/switchers.js +++ b/poky/documentation/sphinx-static/switchers.js @@ -2,9 +2,10 @@ 'use strict'; var all_versions = { - 'dev': 'dev (3.3)', - '3.2.3': '3.2.3', - '3.1.6': '3.1.6', + 'dev': 'dev (3.4)', + '3.3.1': '3.3.1', + '3.2.4': '3.2.4', + '3.1.8': '3.1.8', '3.0.4': '3.0.4', '2.7.4': '2.7.4', }; diff --git a/poky/documentation/test-manual/index.rst b/poky/documentation/test-manual/index.rst index e2198c4c3..4c590a6aa 100644 --- a/poky/documentation/test-manual/index.rst +++ b/poky/documentation/test-manual/index.rst @@ -13,6 +13,8 @@ Yocto Project Test Environment Manual intro test-process understand-autobuilder + reproducible-builds + yocto-project-compatible history .. include:: /boilerplate.rst diff --git a/poky/documentation/test-manual/reproducible-builds.rst b/poky/documentation/test-manual/reproducible-builds.rst new file mode 100644 index 000000000..e13583c0b --- /dev/null +++ b/poky/documentation/test-manual/reproducible-builds.rst @@ -0,0 +1,135 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +******************* +Reproducible Builds +******************* + +================ +How we define it +================ + +The Yocto Project defines reproducibility as where a given input build +configuration will give the same binary output regardless of when it is built +(now or in 5 years time), regardless of the path on the filesystem the build is +run in, and regardless of the distro and tools on the underlying host system the +build is running on. + +============== +Why it matters +============== + +The project aligns with the `Reproducible Builds project +<https://reproducible-builds.org/>`_, which shares information about why +reproducibility matters. The primary focus of the project is the ability to +detect security issues being introduced. However, from a Yocto Project +perspective, it is also hugely important that our builds are deterministic. When +you build a given input set of metadata, we expect you to get consistent output. +This has always been a key focus but, :yocto_docs:`since release 3.1 ("dunfell") +</ref-manual/migration-3.1.html#reproducible-builds-now-enabled-by-default>`, +it is now true down to the binary level including timestamps. + +For example, at some point in the future life of a product, you find that you +need to rebuild to add a security fix. If this happens, only the components that +have been modified should change at the binary level. This would lead to much +easier and clearer bounds on where validation is needed. + +This also gives an additional benefit to the project builds themselves, our hash +equivalence for :ref:`Shared State <overview-manual/concepts:Shared State>` +object reuse works much more effectively when the binary output remains the +same. + +.. note:: + + We strongly advise you to make sure your project builds reproducibly + before finalizing your production images. It would be too late if you + only address this issue when the first updates are required. + +=================== +How we implement it +=================== + +There are many different aspects to build reproducibility, but some particular +things we do within the build system to ensure reproducibility include: + +- Adding mappings to the compiler options to ensure debug filepaths are mapped + to consistent target compatible paths. This is done through the + ``DEBUG_PREFIX_MAP`` variable which sets the ``-fmacro-prefix-map`` and + ``-fdebug-prefix-map`` compiler options correctly to map to target paths. +- Being explicit about recipe dependencies and their configuration (no floating + configure options or host dependencies creeping in). In particular this means + making sure :term:`PACKAGECONFIG` coverage covers configure options which may + otherwise try and auto-detect host dependencies. +- Using recipe specific sysroots to isolate recipes so they only see their + dependencies. These are visible as ``recipe-sysroot`` and + ``recipe-sysroot-native`` directories within the :term:`WORKDIR` of a given + recipe and are populated only with the dependencies a recipe has. +- Build images from a reduced package set: only packages from recipes the image + depends upon. +- Filtering the tools available from the host's ``PATH`` to only a specific set + of tools, set using the :term:`HOSTTOOLS` variable. + +========================================= +Can we prove the project is reproducible? +========================================= + +Yes, we can prove it and we regularly test this on the Autobuilder. At the +time of writing (release 3.3, "hardknott"), :term:`OpenEmbedded-Core (OE-Core)` +is 100% reproducible for all its recipes (i.e. world builds) apart from the Go +language and Ruby documentation packages. Unfortunately, the current +implementation of the Go language has fundamental reproducibility problems as +it always depends upon the paths it is built in. + +.. note:: + + Only BitBake and :term:`OpenEmbedded-Core (OE-Core)`, which is the ``meta`` + layer in Poky, guarantee complete reproducibility. The moment you add + another layer, this warranty is voided, because of additional configuration + files, ``bbappend`` files, overridden classes, etc. + +To run our automated selftest, as we use in our CI on the Autobuilder, you can +run:: + + oe-selftest -r reproducible.ReproducibleTests.test_reproducible_builds + +This defaults to including a ``world`` build so, if other layers are added, it would +also run the tests for recipes in the additional layers. The first build will be +run using :ref:`Shared State <overview-manual/concepts:Shared State>` if +available, the second build explicitly disables +:ref:`Shared State <overview-manual/concepts:Shared State>` and builds on the +specific host the build is running on. This means we can test reproducibility +builds between different host distributions over time on the Autobuilder. + +If ``OEQA_DEBUGGING_SAVED_OUTPUT`` is set, any differing packages will be saved +here. The test is also able to run the ``diffoscope`` command on the output to +generate HTML files showing the differences between the packages, to aid +debugging. On the Autobuilder, these appear under +https://autobuilder.yocto.io/pub/repro-fail/ in the form ``oe-reproducible + +<date> + <random ID>``, e.g. ``oe-reproducible-20200202-1lm8o1th``. + +The project's current reproducibility status can be seen at +:yocto_home:`/reproducible-build-results/` + +You can also check the reproducibility status on supported host distributions: + +- CentOS: :yocto_ab:`/typhoon/#/builders/reproducible-centos` +- Debian: :yocto_ab:`/typhoon/#/builders/reproducible-debian` +- Fedora: :yocto_ab:`/typhoon/#/builders/reproducible-fedora` +- Ubuntu: :yocto_ab:`/typhoon/#/builders/reproducible-ubuntu` + +=============================== +Can I test my layer or recipes? +=============================== + +Once again, you can run a ``world`` test using the +:ref:`oe-selftest <ref-manual/release-process:Testing and Quality Assurance>` +command provided above. This functionality is implemented +in :oe_git:`meta/lib/oeqa/selftest/cases/reproducible.py +</openembedded-core/tree/meta/lib/oeqa/selftest/cases/reproducible.py>`. + +You could subclass the test and change ``targets`` to a different target. + +You may also change ``sstate_targets`` which would allow you to "pre-cache" some +set of recipes before the test, meaning they are excluded from reproducibility +testing. As a practical example, you could set ``sstate_targets`` to +``core-image-sato``, then setting ``targets`` to ``core-image-sato-sdk`` would +run reproducibility tests only on the targets belonging only to ``core-image-sato-sdk``. diff --git a/poky/documentation/test-manual/yocto-project-compatible.rst b/poky/documentation/test-manual/yocto-project-compatible.rst new file mode 100644 index 000000000..a7897469f --- /dev/null +++ b/poky/documentation/test-manual/yocto-project-compatible.rst @@ -0,0 +1,124 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +************************ +Yocto Project Compatible +************************ + +============ +Introduction +============ + +After the introduction of layers to OpenEmbedded, it quickly became clear +that while some layers were popular and worked well, others developed a +reputation for being "problematic". Those were layers which didn't +interoperate well with others and tended to assume they controlled all +the aspects of the final output. This usually isn't intentional but happens +because such layers are often created by developers with a particular focus +(e.g. a company's :term:`BSP<Board Support Package (BSP)>`) whilst the end +users have a different one (e.g. integrating that +:term:`BSP<Board Support Package (BSP)>` into a product). + +As a result of noticing such patterns and friction between layers, the project +developed the "Yocto Project Compatible" badge program, allowing layers +following the best known practises to be marked as being widely compatible +with other ones. This takes the form of a set of "yes/no" binary answer +questions where layers can declare if they meet the appropriate criteria. +In the second version of the program, a script was added to make validation +easier and clearer, the script is called ``yocto-check-layer`` and is +available in :term:`OpenEmbedded-Core (OE-Core)`. + +See :ref:`dev-manual/common-tasks:making sure your layer is compatible with yocto project` +for details. + +======== +Benefits +======== + +:ref:`overview-manual/yp-intro:the yocto project layer model` is powerful +and flexible: it gives users the ultimate power to change pretty much any +aspect of the system but as with most things, power comes with responsibility. +The Yocto Project would like to see people able to mix and match BSPs with +distro configs or software stacks and be able to merge succesfully. +Over time, the project identified characteristics in layers that allow them +to operate well together. "anti-patterns" were also found, preventing layers +from working well together. + +The intent of the compatibility program is simple: if the layer passes the +compatibility tests, it is considered "well behaved" and should operate +and cooperate well with other compatible layers. + +The benefits of compatibility can be seen from multiple different user and +member perspectives. From a hardware perspective +(a :ref:`overview-manual/concepts:bsp layer`), compatibility means the +hardware can be used in many different products and use cases without +impacting the software stacks being run with it. For a company developing +a product, compatibility gives you a specification / standard you can +require in a contract and then know it will have certain desired +characteristics for interoperability. It also puts constraints on how invasive +the code bases are into the rest of the system, meaning that multiple +different separate hardware support layers can coexist (e.g. for multiple +product lines from different hardware manufacturers). This can also make it +easier for one or more parties to upgrade those system components for security +purposes during the lifecycle of a product. + +================== +Validating a layer +================== + +The badges are available to members of the Yocto Project (as member benefit) +and to open source projects run on a non-commercial basis. However, anyone can +answer the questions and run the script. + +The project encourages all layer maintainers to review the questions and the +output from the script against their layer, as the way some layers are +constructed often has unintended consequences. The questions and the script +are designed to highlight known issues which are often easy to solve. This +makes layers easier to use and therefore more popular. + +It is intended that over time, the tests will evolve as new best known +practices are identified, and as new interoperability issues are found, +unnecessarily restricting layer interoperability. If anyone becomes aware of +either type, please let the project know through the +:yocto_home:`technical calls </public-virtual-meetings/>`, +the :yocto_home:`mailing lists </community/mailing-lists/>` +or through the :oe_wiki:`Technical Steering Committee (TSC) </TSC>`. +The TSC is responsible for the technical criteria used by the program. + +Layers are divided into three types: + +- :ref:`"BSP" or "hardware support"<overview-manual/concepts:bsp layer>` + layers contain support for particular pieces of hardware. This includes + kernel and boot loader configuration, and any recipes for firmware or + kernel modules needed for the hardware. Such layers usually correspond + to a :term:`MACHINE` setting. + +- :ref:`"distro" layers<overview-manual/concepts:distro layer>` defined + as layers providing configuration options and settings such as the + choice of init system, compiler and optimisation options, and + configuration and choices of software components. This would usually + correspond to a :term:`DISTRO` setting. + +- "software" layers are usually recipes. A layer might target a + particular graphical UI or software stack component. + +Here are key best practices the program tries to encourage: + +- A layer should clearly show who maintains it, and who change + submissions and bug reports should be sent to. + +- Where multiple types of functionality are present, the layer should + be internally divided into sublayers to separate these components. + That's because some users may only need one of them and separability + is a key best practice. + +- Adding a layer to a build should not modify that build, unless the + user changes a configuration setting to activate the layer, by selecting + a :term:`MACHINE`, a :term:`DISTRO` or a :term:`DISTRO_FEATURES` setting. + +The project does test the compatibility status of the core project layers on +its :doc:`Autobuilder </test-manual/understand-autobuilder>`. + +The official form to submit compatibility requests with is at +:yocto_home:`/ecosystem/branding/compatible-registration/`. +Applicants can display the badge they get when their application is successful. + diff --git a/poky/documentation/toaster-manual/reference.rst b/poky/documentation/toaster-manual/reference.rst index 3d4efe92d..c0d02ff9a 100644 --- a/poky/documentation/toaster-manual/reference.rst +++ b/poky/documentation/toaster-manual/reference.rst @@ -9,8 +9,8 @@ concepts and have some basic command reference material available. This final chapter provides conceptual information on layer sources, releases, and JSON configuration files. Also provided is a quick look at some useful ``manage.py`` commands that are Toaster-specific. -Information on ``manage.py`` commands does exist across the Web and the -information in this manual by no means attempts to provide a command +Information on ``manage.py`` commands is available across the Web and +this manual by no means attempts to provide a command comprehensive reference. Layer Source @@ -32,9 +32,8 @@ through a `REST <https://en.wikipedia.org/wiki/Representational_state_transfer>`__ API, store the information about the layers in the Toaster database, and then show the information to users. Users are then able to view that -information and build layers from Toaster itself without worrying about -cloning or editing the BitBake layers configuration file -``bblayers.conf``. +information and build layers from Toaster itself without having to +clone or edit the BitBake layers configuration file ``bblayers.conf``. Tying a layer source into Toaster is convenient when you have many custom layers that need to be built on a regular basis by a community of @@ -187,7 +186,7 @@ Configuring the Workflow ------------------------ The ``bldcontrol/management/commands/checksettings.py`` file controls -workflow configuration. The following steps outline the process to +workflow configuration. Here is the process to initially populate this database. 1. The default project settings are set from @@ -238,7 +237,7 @@ The following example sets "name" to "CUSTOM_XML_ONLY" and its value to Understanding Fixture File Format --------------------------------- -The following is an overview of the file format used by the +Here is an overview of the file format used by the ``oe-core.xml``, ``poky.xml``, and ``custom.xml`` files. The following subsections describe each of the sections in the fixture @@ -408,7 +407,7 @@ To get the status of pending builds, use the following call:: Be sure to provide values for host and port. The output is a JSON file that itemizes all builds in progress. This file includes the time in seconds since each respective build started as well as the progress of the cloning, parsing, -and task execution. The following is sample output for a build in progress: +and task execution. Here is sample output for a build in progress: .. code-block:: JSON @@ -441,8 +440,8 @@ call:: http://host:port/toastergui/api/builds Be sure to provide values for host and port. The output is a JSON file that -itemizes all complete builds, and includes build summary information. The -following is sample output for a completed build: +itemizes all complete builds, and includes build summary information. Here +is sample output for a completed build: .. code-block:: JSON @@ -480,7 +479,7 @@ Completed query. See the ":ref:`toaster-manual/reference:checking status of buil section for more information. The output is a JSON file that itemizes the specific build and includes -build summary information. The following is sample output for a specific +build summary information. Here is sample output for a specific build: .. code-block:: JSON @@ -509,7 +508,7 @@ Useful Commands =============== In addition to the web user interface and the scripts that start and -stop Toaster, command-line commands exist through the ``manage.py`` +stop Toaster, command-line commands are available through the ``manage.py`` management script. You can find general documentation on ``manage.py`` at the `Django <https://docs.djangoproject.com/en/2.2/topics/settings/>`__ diff --git a/poky/documentation/toaster-manual/setup-and-use.rst b/poky/documentation/toaster-manual/setup-and-use.rst index 8f0ec9449..4f71b5841 100644 --- a/poky/documentation/toaster-manual/setup-and-use.rst +++ b/poky/documentation/toaster-manual/setup-and-use.rst @@ -625,7 +625,7 @@ To specify ``bash`` 3.2.48 as the version to build, enter :scale: 75% After clicking the "Add variable" button, the settings for -``PREFERRED_VERSION`` are added to the bottom of the BitBake variables +:term:`PREFERRED_VERSION` are added to the bottom of the BitBake variables list. With these settings, the OpenEmbedded build system builds the desired version of the recipe rather than the default version: diff --git a/poky/documentation/transitioning-to-a-custom-environment.rst b/poky/documentation/transitioning-to-a-custom-environment.rst index abbd74ca1..f0035bd3a 100644 --- a/poky/documentation/transitioning-to-a-custom-environment.rst +++ b/poky/documentation/transitioning-to-a-custom-environment.rst @@ -47,7 +47,7 @@ Transitioning to a custom environment for systems development #. **Based on the layers you've chosen, make needed changes in your configuration**. For instance, you've chosen a machine type and added in the corresponding BSP - layer. You'll then need to change the value of the ``MACHINE`` variable in your + layer. You'll then need to change the value of the :term:`MACHINE` variable in your configuration file (build/local.conf) to point to that same machine type. There could be other layer-specific settings you need to change as well. Each layer has a ``README`` document that you can look at for this type of |