mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-03-19 13:49:41 +01:00
Code Issues Packages Projects Releases Wiki Activity

sphinx: fix internal links

Browse Source 
Many of the internal links were not converted probably from DocBook
using pandoc. After looking at the various patterns, the follow series
of 'naive' Python regexp were used to perform some additional
automatic conversion.

Also, since we rely on built-in glossary, all links to terms need to
use the sphinx :term: syntax.

This commit is generated using the following Python series of regexp:

   line = re.sub("`+(\w+)`* <(\&YOCTO_DOCS_REF_URL;)?#var-\\1>`__",
                 ":term:`\\1`",
                 line)

   line = re.sub("`+do_([a-z_]+)`* <(\&YOCTO_DOCS_REF_URL;)?#ref-tasks-\\1>`__",
                 ":ref:`ref-tasks-\\1`",
                 line)

   line = re.sub("`+([a-z_\-\*\.]+).bbclass`* <(\&YOCTO_DOCS_REF_URL;)?#ref-classes-\\1>`__",
                 ":ref:`\\1.bbclass <ref-classes-\\1>`",
                 line)

   line = re.sub("`+([a-z_\-\*\.]+)`* <(\&YOCTO_DOCS_REF_URL;)?#ref-classes-\\1>`__",
                 ":ref:`\\1 <ref-classes-\\1>`",
                 line)

   line = re.sub("`Source Directory <(\&YOCTO_DOCS_REF_URL;)?#source-directory>`__",
                 ":term:`Source Directory`",
                 line)

   line = re.sub("`Build Directory <(\&YOCTO_DOCS_REF_URL;)?#build-directory>`__",
                 ":term:`Build Directory`",
                 line)

   line = re.sub("`Metadata <(\&YOCTO_DOCS_REF_URL;)?#metadata>`__",
                 ":term:`Metadata`",
                 line)

   line = re.sub("`BitBake <(\&YOCTO_DOCS_REF_URL;)?#bitbake-term>`__",
                 ":term:`BitBake`",
                 line)

   line = re.sub("`Images <(\&YOCTO_DOCS_REF_URL;)?#ref-images>`__",
                 ":ref:`ref-manual/ref-images:Images`",
                 line)

   line = re.sub("`Classes <(\&YOCTO_DOCS_REF_URL;)?#ref-classes>`__",
                 ":ref:`ref-manual/ref-classes:Classes`",
                 line)

   line = re.sub("`workspace <(\&YOCTO_DOCS_REF_URL;)?#devtool-the-workspace-layer-structure>`__",
                 ":ref:`devtool-the-workspace-layer-structure`",
                 line)

   line = re.sub("`Open-?Embedded b?B?uild s?S?ystem <(\&YOCTO_DOCS_REF_URL;)?#build-system-term>`__",
                 ":term:`OpenEmbedded Build System`",
                 line)

   line = re.sub("`(OpenEmbedded-Core )?(\(?OE-Core\)? )?<(\&YOCTO_DOCS_REF_URL;)?#oe-core>`__",
                 ":term:`OpenEmbedded-Core (OE-Core)`",
                 line)

It won't catch multiline strings, but it catches a very large number
of occurences!

(From yocto-docs rev: 3f537d17de5b1fb76ba3bee196481984a4826378)

Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Nicolas Dechesne
2020-07-24 16:27:54 +02:00
committed by Richard Purdie
parent 4cd953989d
commit c473fa2292
42 changed files with 2221 additions and 2221 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
documentation/adt-manual/adt-command.rst
View File

@@ -85,7 +85,7 @@ Follow these steps to create a simple Autotools-based project:
7. *Cross-compile the project:* This command compiles the project using
the cross-compiler. The
```CONFIGURE_FLAGS`` <&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS>`__
:term:`CONFIGURE_FLAGS`
environment variable provides the minimal arguments for GNU
configure: $ ./configure ${CONFIGURE_FLAGS}
@@ -146,13 +146,13 @@ subject to general ``make`` rules.
To illustrate this, consider the following four cross-toolchain
environment variables:
`CC <&YOCTO_DOCS_REF_URL;#var-CC>`__\ =i586-poky-linux-gcc -m32
:term:`CC`\ =i586-poky-linux-gcc -m32
-march=i586 --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux
`LD <&YOCTO_DOCS_REF_URL;#var-LD>`__\ =i586-poky-linux-ld
:term:`LD`\ =i586-poky-linux-ld
--sysroot=/opt/poky/1.8/sysroots/i586-poky-linux
`CFLAGS <&YOCTO_DOCS_REF_URL;#var-CFLAGS>`__\ =-O2 -pipe -g
:term:`CFLAGS`\ =-O2 -pipe -g
-feliminate-unused-debug-types
`CXXFLAGS <&YOCTO_DOCS_REF_URL;#var-CXXFLAGS>`__\ =-O2 -pipe -g
:term:`CXXFLAGS`\ =-O2 -pipe -g
-feliminate-unused-debug-types Now, consider the following three cases:
- *Case 1 - No Variables Set in the ``Makefile``:* Because these

2
documentation/adt-manual/adt-package.rst
View File

@@ -38,7 +38,7 @@ Configuring the PMS
===================
Whichever PMS you are using, you need to be sure that the
```PACKAGE_CLASSES`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES>`__
:term:`PACKAGE_CLASSES`
variable in the ``conf/local.conf`` file is set to reflect that system.
The first value you choose for the variable specifies the package file
format for the root filesystem at sysroot. Additional values specify

66
documentation/adt-manual/adt-prepare.rst
View File

@@ -284,7 +284,7 @@ Follow these steps to generate the toolchain into the Build Directory:
Directory <&YOCTO_DOCS_DEV_URL;#source-directory>`__.
2. *Check your Local Configuration File:* At this point, you should be
sure that the ```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__
sure that the :term:`MACHINE`
variable in the ``local.conf`` file found in the ``conf`` directory
of the Build Directory is set for the target architecture. Comments
within the ``local.conf`` file list the values you can use for the
@@ -345,45 +345,45 @@ setup script for a 64-bit IA-based architecture installed in the default
installation directory would be the following:
YOCTO_ADTPATH_DIR/environment-setup-x86_64-poky-linux When you run the
setup script, many environment variables are defined:
```SDKTARGETSYSROOT`` <&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT>`__ -
:term:`SDKTARGETSYSROOT` -
The path to the sysroot used for cross-compilation
```PKG_CONFIG_PATH`` <&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH>`__ - The
:term:`PKG_CONFIG_PATH` - The
path to the target pkg-config files
```CONFIG_SITE`` <&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE>`__ - A GNU
:term:`CONFIG_SITE` - A GNU
autoconf site file preconfigured for the target
```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__ - The minimal command and
:term:`CC` - The minimal command and
arguments to run the C compiler
```CXX`` <&YOCTO_DOCS_REF_URL;#var-CXX>`__ - The minimal command and
:term:`CXX` - The minimal command and
arguments to run the C++ compiler
```CPP`` <&YOCTO_DOCS_REF_URL;#var-CPP>`__ - The minimal command and
:term:`CPP` - The minimal command and
arguments to run the C preprocessor
```AS`` <&YOCTO_DOCS_REF_URL;#var-AS>`__ - The minimal command and
arguments to run the assembler ```LD`` <&YOCTO_DOCS_REF_URL;#var-LD>`__
:term:`AS` - The minimal command and
arguments to run the assembler :term:`LD`
- The minimal command and arguments to run the linker
```GDB`` <&YOCTO_DOCS_REF_URL;#var-GDB>`__ - The minimal command and
:term:`GDB` - The minimal command and
arguments to run the GNU Debugger
```STRIP`` <&YOCTO_DOCS_REF_URL;#var-STRIP>`__ - The minimal command and
:term:`STRIP` - The minimal command and
arguments to run 'strip', which strips symbols
```RANLIB`` <&YOCTO_DOCS_REF_URL;#var-RANLIB>`__ - The minimal command
:term:`RANLIB` - The minimal command
and arguments to run 'ranlib'
```OBJCOPY`` <&YOCTO_DOCS_REF_URL;#var-OBJCOPY>`__ - The minimal command
:term:`OBJCOPY` - The minimal command
and arguments to run 'objcopy'
```OBJDUMP`` <&YOCTO_DOCS_REF_URL;#var-OBJDUMP>`__ - The minimal command
and arguments to run 'objdump' ```AR`` <&YOCTO_DOCS_REF_URL;#var-AR>`__
:term:`OBJDUMP` - The minimal command
and arguments to run 'objdump' :term:`AR`
- The minimal command and arguments to run 'ar'
```NM`` <&YOCTO_DOCS_REF_URL;#var-NM>`__ - The minimal command and
:term:`NM` - The minimal command and
arguments to run 'nm'
```TARGET_PREFIX`` <&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX>`__ - The
:term:`TARGET_PREFIX` - The
toolchain binary prefix for the target tools
```CROSS_COMPILE`` <&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE>`__ - The
:term:`CROSS_COMPILE` - The
toolchain binary prefix for the target tools
```CONFIGURE_FLAGS`` <&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS>`__ - The
:term:`CONFIGURE_FLAGS` - The
minimal arguments for GNU configure
```CFLAGS`` <&YOCTO_DOCS_REF_URL;#var-CFLAGS>`__ - Suggested C flags
```CXXFLAGS`` <&YOCTO_DOCS_REF_URL;#var-CXXFLAGS>`__ - Suggested C++
flags ```LDFLAGS`` <&YOCTO_DOCS_REF_URL;#var-LDFLAGS>`__ - Suggested
:term:`CFLAGS` - Suggested C flags
:term:`CXXFLAGS` - Suggested C++
flags :term:`LDFLAGS` - Suggested
linker flags when you use CC to link
```CPPFLAGS`` <&YOCTO_DOCS_REF_URL;#var-CPPFLAGS>`__ - Suggested
:term:`CPPFLAGS` - Suggested
preprocessor flags
Securing Kernel and Filesystem Images
@@ -411,7 +411,7 @@ that you can use unaltered in the QEMU emulator. These kernel images
reside in the release area - ` <&YOCTO_MACHINES_DL_URL;>`__ and are
ideal for experimentation using Yocto Project. For information on the
image types you can build using the OpenEmbedded build system, see the
"`Images <&YOCTO_DOCS_REF_URL;#ref-images>`__" chapter in the Yocto
":ref:`ref-manual/ref-images:Images`" chapter in the Yocto
Project Reference Manual.
If you are planning on developing against your image and you are not
@@ -434,7 +434,7 @@ this by including the ``eclipse-debug`` image feature.
To include the ``eclipse-debug`` image feature, modify your
``local.conf`` file in the `Build
Directory <&YOCTO_DOCS_DEV_URL;#build-directory>`__ so that the
```EXTRA_IMAGE_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES>`__
:term:`EXTRA_IMAGE_FEATURES`
variable includes the "eclipse-debug" feature. After modifying the
configuration file, you can rebuild the image. Once the image is
rebuilt, the ``tcf-agent`` will be included in the image and is launched
@@ -513,8 +513,8 @@ Another feature is that only one set of cross-canadian toolchain
binaries are produced per 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 ```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__
and ```LD`` <&YOCTO_DOCS_REF_URL;#var-LD>`__. This reduces the space
contained in variables such as :term:`CC`
and :term:`LD`. This reduces the space
needed for the tools. Understand, however, that a sysroot is still
needed for every target since those binaries are target-specific.
@@ -524,9 +524,9 @@ environment setup script (i.e.
```oe-init-build-env-memres`` <&YOCTO_DOCS_REF_URL;#structure-memres-core-script>`__)
located in the Source Directory and you must make sure your
``conf/local.conf`` variables are correct. In particular, you need to be
sure the ```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__ variable
sure the :term:`MACHINE` variable
matches the architecture for which you are building and that the
```SDKMACHINE`` <&YOCTO_DOCS_REF_URL;#var-SDKMACHINE>`__ variable is
:term:`SDKMACHINE` variable is
correctly set if you are building a toolchain designed to run on an
architecture that differs from your current development host machine
(i.e. the build machine).
@@ -565,10 +565,10 @@ follows:
- Make sure you add the layer that contains the toolchain to your
``bblayers.conf`` file through the
```BBLAYERS`` <&YOCTO_DOCS_REF_URL;#var-BBLAYERS>`__ variable.
:term:`BBLAYERS` variable.
- Set the
```EXTERNAL_TOOLCHAIN`` <&YOCTO_DOCS_REF_URL;#var-EXTERNAL_TOOLCHAIN>`__
:term:`EXTERNAL_TOOLCHAIN`
variable in your ``local.conf`` file to the location in which you
installed the toolchain.
@@ -577,7 +577,7 @@ Mentor Graphics Sourcery G++ Toolchain. You can see information on how
to use that particular layer in the ``README`` file at
` <http://github.com/MentorEmbedded/meta-sourcery/>`__. You can find
further information by reading about the
```TCMODE`` <&YOCTO_DOCS_REF_URL;#var-TCMODE>`__ variable in the Yocto
:term:`TCMODE` variable in the Yocto
Project Reference Manual's variable glossary.
.. _using-pre-built:
@@ -712,7 +712,7 @@ core-image-profile-qemuarch.ext3 core-image-profile-qemuarch.tar.bz2
Where: profile is the filesystem image's profile: lsb, lsb-dev, lsb-sdk,
lsb-qt3, minimal, minimal-dev, sato, sato-dev, or sato-sdk. For
information on these types of image profiles, see the
"`Images <&YOCTO_DOCS_REF_URL;#ref-images>`__" chapter in the Yocto
":ref:`ref-manual/ref-images:Images`" chapter in the Yocto
Project Reference Manual. arch is a string representing the target
architecture: x86, x86-64, ppc, mips, or arm.

2
documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.rst
View File

@@ -257,7 +257,7 @@ Follow these steps to add a hardware layer:
support hardware from Altera, which is owned by Intel.
3. *Change the Configuration to Build for a Specific Machine:* The
```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__ variable in 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
configurations are used:

76
documentation/bsp-guide/bsp.rst
View File

@@ -73,7 +73,7 @@ section in the Yocto Project Development Tasks Manual.
The BSP layer's base directory (``meta-bsp_root_name``) is the root
directory of that Layer. This directory is what you add to the
```BBLAYERS`` <&YOCTO_DOCS_REF_URL;#var-BBLAYERS>`__ variable in the
:term:`BBLAYERS` variable in the
``conf/bblayers.conf`` file found in your `Build
Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__, which is
established after you run the OpenEmbedded build environment setup
@@ -466,7 +466,7 @@ This file provides information on where to locate the BSP source files
used to build the images (if any) that reside in
``meta-bsp_root_name/binary``. Images in the ``binary`` would be images
released with the BSP. The information in the ``README.sources`` file
also helps you find the `Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__
also helps you find the :term:`Metadata`
used to generate the images that ship with the BSP.
.. note::
@@ -532,7 +532,7 @@ BBFILE_PATTERN_raspberrypi := "^${LAYERDIR}/"
BBFILE_PRIORITY_raspberrypi = "9" # Additional license directories.
LICENSE_PATH += "${LAYERDIR}/files/custom-licenses" . . .
This file simply makes `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__
This file simply makes :term:`BitBake`
aware of the recipes and configuration directories. The file must exist
so that the OpenEmbedded build system can recognize the BSP.
@@ -549,10 +549,10 @@ in the BSP into a format that the build system can understand. Each BSP
Layer requires at least one machine file. If the BSP supports multiple
machines, multiple machine configuration files can exist. These
filenames correspond to the values to which users have set the
```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__ variable.
:term:`MACHINE` variable.
These files define things such as the kernel package to use
(```PREFERRED_PROVIDER`` <&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER>`__
(:term:`PREFERRED_PROVIDER`
of
`virtual/kernel <&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers>`__),
the hardware drivers to include in different types of images, any
@@ -565,7 +565,7 @@ optimization flags, which are carefully chosen to give best performance
on a given processor.
Tuning files are found in the ``meta/conf/machine/include`` directory
within the `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__.
within the :term:`Source Directory`.
For example, many ``tune-*`` files (e.g. ``tune-arm1136jf-s.inc``,
``tune-1586-nlp.inc``, and so forth) reside in the
``poky/meta/conf/machine/include`` directory.
@@ -599,7 +599,7 @@ DISPLAY_ORIENTATION=0 DISPLAY_DPI=133
according to the formfactor configuration file that is installed by
the main formfactor recipe
``meta/recipes-bsp/formfactor/formfactor_0.0.bb``, which is found in
the `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__.
the :term:`Source Directory`.
.. _bsp-filelayout-recipes-graphics:
@@ -639,9 +639,9 @@ located in the BSP Layer for your target device (e.g. the
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
```PREFERRED_PROVIDER`` <&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER>`__
:term:`PREFERRED_PROVIDER`
and
```PREFERRED_VERSION`` <&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION>`__
:term:`PREFERRED_VERSION`
statements as follows: PREFERRED_PROVIDER_virtual/kernel ?=
"linux-yocto" PREFERRED_VERSION_linux-yocto ?= "4.4%"
@@ -796,7 +796,7 @@ workflow.
The build process supports several types of images to satisfy
different needs. See the
"`Images <&YOCTO_DOCS_REF_URL;#ref-images>`__" chapter in the Yocto
":ref:`ref-manual/ref-images:Images`" chapter in the Yocto
Project Reference Manual for information on supported images.
Requirements and Recommendations for Released BSPs
@@ -1038,7 +1038,7 @@ also supports several other machines:
The
```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__
:term:`FILESEXTRAPATHS`
variable in the append files extends the search path the build system
uses to find files during the build. Consequently, for this example
you need to have the ``files`` directory in the same location as your
@@ -1090,11 +1090,11 @@ satisfy the licensing requirements for an encumbered BSP. The following
list describes them in order of preference:
1. *Use
the*\ ```LICENSE_FLAGS`` <&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS>`__\ *Variable
the*\ :term:`LICENSE_FLAGS`\ *Variable
to Define the Recipes that Have Commercial or Other Types of
Specially-Licensed Packages:* For each of those recipes, you can
specify a matching license string in a ``local.conf`` variable named
```LICENSE_FLAGS_WHITELIST`` <&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST>`__.
:term:`LICENSE_FLAGS_WHITELIST`.
Specifying the matching license string signifies that you agree to
the license. Thus, the build system can build the corresponding
recipe and include the component in the image. See the "`Enabling
@@ -1266,12 +1266,12 @@ Project Reference Manual.
"virtual/xserver" is "xserver-xorg", which exists in
``poky/meta/recipes-graphics/xorg-xserver``.
- ```XSERVER`` <&YOCTO_DOCS_REF_URL;#var-XSERVER>`__: The packages that
- :term:`XSERVER`: The packages that
should be installed to provide an X server and drivers for the
machine. In this example, the "xserver-xorg" and
"xf86-video-modesetting" are installed.
- ```MACHINE_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS>`__:
- :term:`MACHINE_EXTRA_RRECOMMENDS`:
A list of machine-dependent packages not essential for booting the
image. Thus, the build does not fail if the packages do not exist.
However, the packages are required for a fully-featured image.
@@ -1283,14 +1283,14 @@ Project Reference Manual.
variables exist that help you configure a particular piece of
hardware.
- ```EXTRA_IMAGEDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGEDEPENDS>`__:
- :term:`EXTRA_IMAGEDEPENDS`:
Recipes to build that do not provide packages for installing into the
root filesystem but building the image depends on the recipes.
Sometimes a recipe is required to build the final image but is not
needed in the root filesystem. In this case, the U-Boot recipe must
be built for the image.
- ```DEFAULTTUNE`` <&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE>`__: Machines
- :term:`DEFAULTTUNE`: Machines
use tunings to optimize machine, CPU, and application performance.
These features, which are collectively known as "tuning features",
exist in the `OpenEmbedded-Core
@@ -1306,31 +1306,31 @@ Project Reference Manual.
conf/machine/include/tune-cortexa8.inc
file provides many tuning possibilities.
- ```IMAGE_FSTYPES`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES>`__: The
- :term:`IMAGE_FSTYPES`: The
formats the OpenEmbedded build system uses during the build when
creating the root filesystem. In this example, four types of images
are supported.
- ```EXTRA_IMAGECMD`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGECMD>`__:
- :term:`EXTRA_IMAGECMD`:
Specifies additional options for image creation commands. In this
example, the "-lnp " option is used when creating the
`JFFS2 <https://en.wikipedia.org/wiki/JFFS2>`__ image.
- ```WKS_FILE`` <&YOCTO_DOCS_REF_URL;#var-WKS_FILE>`__: The location of
- :term:`WKS_FILE`: The location of
the `Wic kickstart <&YOCTO_DOCS_REF_URL;#ref-kickstart>`__ file used
by the OpenEmbedded build system to create a partitioned image
(image.wic).
- ```IMAGE_INSTALL`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL>`__:
- :term:`IMAGE_INSTALL`:
Specifies packages to install into an image through the
```image`` <&YOCTO_DOCS_REF_URL;#ref-classes-image>`__ class. Recipes
:ref:`image <ref-classes-image>` class. Recipes
use the ``IMAGE_INSTALL`` variable.
- ``do_image_wic[depends]``: A task that is constructed during the
build. In this example, the task depends on specific tools in order
to create the sysroot when buiding a Wic image.
- ```SERIAL_CONSOLES`` <&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES>`__:
- :term:`SERIAL_CONSOLES`:
Defines a serial console (TTY) to enable using getty. In this case,
the baud rate is "115200" and the device name is "ttyO0".
@@ -1344,21 +1344,21 @@ Project Reference Manual.
Defines the version of the recipe used to build the kernel, which is
"5.0" in this case.
- ```KERNEL_IMAGETYPE`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE>`__:
- :term:`KERNEL_IMAGETYPE`:
The type of kernel to build for the device. In this case, the
OpenEmbedded build system creates a "zImage" image type.
- ```KERNEL_DEVICETREE`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_DEVICETREE>`__:
- :term:`KERNEL_DEVICETREE`:
The names of the generated Linux kernel device trees (i.e. the
``*.dtb``) files. All the device trees for the various BeagleBone
devices are included.
- ```KERNEL_EXTRA_ARGS`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_EXTRA_ARGS>`__:
- :term:`KERNEL_EXTRA_ARGS`:
Additional ``make`` command-line arguments the OpenEmbedded build
system passes on when compiling the kernel. In this example,
"LOADADDR=${UBOOT_ENTRYPOINT}" is passed as a command-line argument.
- ```SPL_BINARY`` <&YOCTO_DOCS_REF_URL;#var-SPL_BINARY>`__: Defines the
- :term:`SPL_BINARY`: Defines the
Secondary Program Loader (SPL) binary type. In this case, the SPL
binary is set to "MLO", which stands for Multimedia card LOader.
@@ -1377,25 +1377,25 @@ Project Reference Manual.
example, a U-Boot image is required to boot the BeagleBone device.
See the following variables for more information:
- ```UBOOT_SUFFIX`` <&YOCTO_DOCS_REF_URL;#var-UBOOT_SUFFIX>`__:
- :term:`UBOOT_SUFFIX`:
Points to the generated U-Boot extension.
- ```UBOOT_MACHINE`` <&YOCTO_DOCS_REF_URL;#var-UBOOT_MACHINE>`__:
- :term:`UBOOT_MACHINE`:
Specifies the value passed on the make command line when building
a U-Boot image.
- ```UBOOT_ENTRYPOINT`` <&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT>`__:
- :term:`UBOOT_ENTRYPOINT`:
Specifies the entry point for the U-Boot image.
- ```UBOOT_LOADADDRESS`` <&YOCTO_DOCS_REF_URL;#var-UBOOT_LOADADDRESS>`__:
- :term:`UBOOT_LOADADDRESS`:
Specifies the load address for the U-Boot image.
- ```MACHINE_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES>`__:
- :term:`MACHINE_FEATURES`:
Specifies the list of hardware features the BeagleBone device is
capable of supporting. In this case, the device supports "usbgadget
usbhost vfat alsa".
- ```IMAGE_BOOT_FILES`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_BOOT_FILES>`__:
- :term:`IMAGE_BOOT_FILES`:
Files installed into the device's boot partition when preparing the
image using the Wic tool with the ``bootimg-partition`` or
``bootimg-efi`` source plugin.
@@ -1435,21 +1435,21 @@ appended with the "beaglebone-yocto" string. The OpenEmbedded build
system uses these statements to override similar statements in the
kernel recipe:
- ```KBRANCH`` <&YOCTO_DOCS_REF_URL;#var-KBRANCH>`__: Identifies the
- :term:`KBRANCH`: Identifies the
kernel branch that is validated, patched, and configured during the
build.
- ```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__: Identifies the
- :term:`KMACHINE`: Identifies the
machine name as known by the kernel, which is sometimes a different
name than what is known by the OpenEmbedded build system.
- ```SRCREV`` <&YOCTO_DOCS_REF_URL;#var-SRCREV>`__: Identifies the
- :term:`SRCREV`: Identifies the
revision of the source code used to build the image.
- ```COMPATIBLE_MACHINE`` <&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE>`__:
- :term:`COMPATIBLE_MACHINE`:
A regular expression that resolves to one or more target machines
with which the recipe is compatible.
- ```LINUX_VERSION`` <&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION>`__: The
- :term:`LINUX_VERSION`: The
Linux version from kernel.org used by the OpenEmbedded build system
to build the kernel image.

768
documentation/dev-manual/dev-manual-common-tasks.rst
View File

File diff suppressed because it is too large Load Diff

2
documentation/dev-manual/dev-manual-qemu.rst
View File

@@ -75,7 +75,7 @@ available. Follow these general steps to run QEMU:
- If you have previously built an image for QEMU (e.g. ``qemux86``,
``qemuarm``, and so forth), then the artifacts are in place in
your `Build Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__.
your :term:`Build Directory`.
- If you have not built an image, you can go to the
`machines/qemu <&YOCTO_MACHINES_DL_URL;>`__ area and download a

4
documentation/dev-manual/dev-manual-start.rst
View File

@@ -75,7 +75,7 @@ particular working environment and set of practices.
development environment.
4. *Use Git as Your Source Control Manager (SCM):* Keeping your
`Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__ (i.e. recipes,
:term:`Metadata` (i.e. recipes,
configuration files, classes, and so forth) and any software you are
developing under the control of an SCM system that is compatible
with the OpenEmbedded build system is advisable. Of all of the SCMs
@@ -248,7 +248,7 @@ particular working environment and set of practices.
for related upstream Yocto Project Git repositories.
- Set up the directory for the shared state cache
(```SSTATE_DIR`` <&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR>`__) where
(:term:`SSTATE_DIR`) where
it makes sense. For example, set up the sstate cache on a system
used by developers in the same organization and share the same
source directories on their machines.

54
documentation/kernel-dev/kernel-dev-advanced.rst
View File

@@ -11,7 +11,7 @@ Overview
In addition to supporting configuration fragments and patches, the Yocto
Project kernel tools also support rich
`Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__ that you can use to define
:term:`Metadata` that you can use to define
complex policies and Board Support Package (BSP) support. The purpose of
the Metadata and the tools that manage it is to help you manage the
complexity of the configuration and sources used to support multiple
@@ -27,7 +27,7 @@ Kernel development tools ("kern-tools") exist also 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
the `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ (e.g.
the :term:`Source Directory` (e.g.
``poky``).
Using Kernel Metadata in a Recipe
@@ -49,9 +49,9 @@ linux-yocto recipe.
file) is said to be a "linux-yocto style" recipe.
Every linux-yocto style recipe must define the
```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__ variable. This
:term:`KMACHINE` variable. This
variable is typically set to the same value as the ``MACHINE`` variable,
which is used by `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__.
which is used by :term:`BitBake`.
However, in some cases, the variable might instead refer to the
underlying platform of the ``MACHINE``.
@@ -65,7 +65,7 @@ Descriptions <#bsp-descriptions>`__ section for more information.
Every linux-yocto style recipe must also indicate the Linux kernel
source repository branch used to build the Linux kernel. The
```KBRANCH`` <&YOCTO_DOCS_REF_URL;#var-KBRANCH>`__ variable must be set
:term:`KBRANCH` variable must be set
to indicate the branch.
.. note::
@@ -84,7 +84,7 @@ to indicate the branch.
The linux-yocto style recipes can optionally define the following
variables: KERNEL_FEATURES LINUX_KERNEL_TYPE
```LINUX_KERNEL_TYPE`` <&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE>`__
: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
@@ -103,10 +103,10 @@ 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
specified in the ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__.
specified in the :term:`SRC_URI`.
You can use the
```KERNEL_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES>`__
: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
@@ -185,7 +185,7 @@ contain "features" as far as the kernel tools are concerned.
Paths used in kernel Metadata files are relative to base, which is
either
```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__ if
:term:`FILESEXTRAPATHS` if
you are creating Metadata in `recipe-space <#recipe-space-metadata>`__,
or the top level of
```yocto-kernel-cache`` <&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/>`__
@@ -218,7 +218,7 @@ fragment files in the "`Creating Configuration
Fragments <#creating-config-fragments>`__" section.
Within the ``smp.scc`` file, the
```KFEATURE_DESCRIPTION`` <&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION>`__
:term:`KFEATURE_DESCRIPTION`
statement provides a short description of the fragment. Higher level
kernel tools use this description.
@@ -312,7 +312,7 @@ non-hardware configuration fragments with patches you want to use when
building a Linux kernel of a specific type (e.g. a real-time kernel).
Syntactically, kernel types are no different than features as described
in the "`Features <#features>`__" section. The
```LINUX_KERNEL_TYPE`` <&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE>`__
:term:`LINUX_KERNEL_TYPE`
variable in the kernel recipe selects the kernel type. For example, in
the ``linux-yocto_4.12.bb`` kernel recipe found in
``poky/meta/recipes-kernel/linux``, a
@@ -432,9 +432,9 @@ ktypes/standard/standard.scc branch beaglebone include beaglebone.scc #
default policy for standard kernels include
features/latencytop/latencytop.scc include
features/profiling/profiling.scc Every top-level BSP description file
should define the ```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__,
```KTYPE`` <&YOCTO_DOCS_REF_URL;#var-KTYPE>`__, and
```KARCH`` <&YOCTO_DOCS_REF_URL;#var-KARCH>`__ variables. These
should define the :term:`KMACHINE`,
:term:`KTYPE`, and
:term:`KARCH` variables. These
variables allow the OpenEmbedded build system to identify the
description as meeting the criteria set by the recipe being built. This
example supports the "beaglebone" machine for the "standard" kernel and
@@ -444,7 +444,7 @@ 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
kernel type defined in your kernel Metadata as it is here, you only need
to ensure that the
```LINUX_KERNEL_TYPE`` <&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE>`__
:term:`LINUX_KERNEL_TYPE`
variable in the kernel recipe and the ``KTYPE`` variable in the BSP
description file match.
@@ -529,9 +529,9 @@ with the most basic functionality of the system as defined in the base
"minnow" description file.
Notice again the three critical variables:
```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__,
```KTYPE`` <&YOCTO_DOCS_REF_URL;#var-KTYPE>`__, and
```KARCH`` <&YOCTO_DOCS_REF_URL;#var-KARCH>`__. Of these variables, only
:term:`KMACHINE`,
:term:`KTYPE`, and
:term:`KARCH`. Of these variables, only
``KTYPE`` has changed to specify the "tiny" kernel type.
Kernel Metadata Location
@@ -564,12 +564,12 @@ Recipe-Space Metadata
When stored in recipe-space, the kernel Metadata files reside in a
directory hierarchy below
```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__. For
:term:`FILESEXTRAPATHS`. For
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
``${``\ ```THISDIR`` <&YOCTO_DOCS_REF_URL;#var-THISDIR>`__\ ``}/${``\ ```PN`` <&YOCTO_DOCS_REF_URL;#var-PN>`__\ ``}``.
``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``.
See the "`Modifying an Existing
Recipe <#modifying-an-existing-recipe>`__" section for more information.
@@ -582,10 +582,10 @@ When the Metadata is stored in recipe-space, you must take steps to
ensure BitBake has the necessary information to decide what files to
fetch and when they need to be fetched again. It is only necessary to
specify the ``.scc`` files on the
```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__. BitBake parses them
:term:`SRC_URI`. BitBake parses them
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 ```PR`` <&YOCTO_DOCS_REF_URL;#var-PR>`__
necessary to bump the recipe :term:`PR`
value when changing the content of files not explicitly listed in the
``SRC_URI``.
@@ -600,7 +600,7 @@ Metadata Outside the Recipe-Space
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
```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ variable. As an
:term:`SRC_URI` variable. As an
example, consider the following ``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};
@@ -742,10 +742,10 @@ within an SCC description file (``.scc``):
"ref" if specified.
- ``define``: Defines variables, such as
```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__,
```KTYPE`` <&YOCTO_DOCS_REF_URL;#var-KTYPE>`__,
```KARCH`` <&YOCTO_DOCS_REF_URL;#var-KARCH>`__, and
```KFEATURE_DESCRIPTION`` <&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION>`__.
:term:`KMACHINE`,
:term:`KTYPE`,
:term:`KARCH`, and
:term:`KFEATURE_DESCRIPTION`.
- ``include SCC_FILE``: Includes an SCC file in the current file. The
file is parsed as if you had inserted it inline.

134
documentation/kernel-dev/kernel-dev-common.rst
View File

@@ -72,7 +72,7 @@ section:
"poky".
2. *Prepare Your ``local.conf`` File:* By default, the
```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__ variable is set to
: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
@@ -82,7 +82,7 @@ section:
Also, since you are preparing to work on the kernel image, you need
to set the
```MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS>`__
:term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
variable to include kernel modules.
In this example we wish to build for qemux86 so we must set the
@@ -115,7 +115,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
```BBLAYERS`` <&YOCTO_DOCS_REF_URL;#var-BBLAYERS>`__ variable in the
:term:`BBLAYERS` variable in the
``bblayers.conf`` file as follows: $ cd ~/poky/build $ bitbake-layers
add-layer ../../meta-mylayer NOTE: Starting bitbake server... $
@@ -236,7 +236,7 @@ section:
"poky".
2. *Prepare Your ``local.conf`` File:* By default, the
```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__ variable is set to
: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
@@ -246,7 +246,7 @@ section:
Also, since you are preparing to work on the kernel image, you need
to set the
```MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS>`__
:term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
variable to include kernel modules.
In this example we wish to build for qemux86 so we must set the
@@ -279,7 +279,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
```BBLAYERS`` <&YOCTO_DOCS_REF_URL;#var-BBLAYERS>`__ variable in the
:term:`BBLAYERS` variable in the
``bblayers.conf`` file as follows: $ cd ~/poky/build $ bitbake-layers
add-layer ../../meta-mylayer NOTE: Starting bitbake server ... $
@@ -343,7 +343,7 @@ Creating and Preparing a Layer
If you are going to be modifying kernel recipes, it is recommended that
you create and prepare your own layer in which to do your work. Your
layer contains its own `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__
layer contains its own :term:`BitBake`
append files (``.bbappend``) and provides a convenient mechanism to
create your own recipe files (``.bb``) as well as store and use kernel
patch files. For background information on working with layers, see the
@@ -393,8 +393,8 @@ home directory:
"${THISDIR}/${PN}:" SRC_URI_append = " file://patch-file-one"
SRC_URI_append = " file://patch-file-two" SRC_URI_append = "
file://patch-file-three" The
```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__
and ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statements
:term:`FILESEXTRAPATHS`
and :term:`SRC_URI` statements
enable the OpenEmbedded build system to find patch files. For more
information on using append files, see the "`Using .bbappend Files in
Your Layer <&YOCTO_DOCS_DEV_URL;#using-bbappend-files>`__" section in
@@ -406,7 +406,7 @@ Modifying an Existing Recipe
In many cases, you can customize an existing linux-yocto recipe to meet
the needs of your project. Each release of the Yocto Project provides a
few Linux kernel recipes from which you can choose. These are located in
the `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ in
the :term:`Source Directory` in
``meta/recipes-kernel/linux``.
Modifying an existing recipe can consist of the following:
@@ -431,12 +431,12 @@ modifying the ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` recipe,
the append file will typically be located as follows within your custom
layer: your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend The
append file should initially extend the
```FILESPATH`` <&YOCTO_DOCS_REF_URL;#var-FILESPATH>`__ search path by
:term:`FILESPATH` search path by
prepending the directory that contains your files to the
```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__
:term:`FILESEXTRAPATHS`
variable as follows: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" The
path
``${``\ ```THISDIR`` <&YOCTO_DOCS_REF_URL;#var-THISDIR>`__\ ``}/${``\ ```PN`` <&YOCTO_DOCS_REF_URL;#var-PN>`__\ ``}``
``${``\ :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
@@ -472,16 +472,16 @@ COMPATIBLE_MACHINE_beaglebone = "beaglebone" LINUX_VERSION_genericx86 =
= "4.12.10" LINUX_VERSION_beaglebone = "4.12.10" This append file
contains statements used to support several BSPs that ship with the
Yocto Project. The file defines machines using the
```COMPATIBLE_MACHINE`` <&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE>`__
:term:`COMPATIBLE_MACHINE`
variable and uses the
```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__ variable to ensure
:term:`KMACHINE` variable to ensure
the machine name used by the OpenEmbedded build system maps to the
machine name used by the Linux Yocto kernel. The file also uses the
optional ```KBRANCH`` <&YOCTO_DOCS_REF_URL;#var-KBRANCH>`__ variable to
optional :term:`KBRANCH` variable to
ensure the build process uses the appropriate kernel branch.
Although this particular example does not use it, the
```KERNEL_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES>`__
:term:`KERNEL_FEATURES`
variable could be used to enable features specific to the kernel. The
append file points to specific commits in the `Source
Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ Git repository and
@@ -497,7 +497,7 @@ accomplish this definition by putting the configurations in a file or a
set of files inside a directory located at the same level as your
kernel's append file and having the same name as the kernel's main
recipe file. With all these conditions met, simply reference those files
in the ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statement in
in the :term:`SRC_URI` statement in
the append file.
For example, suppose you had some configuration options in a file called
@@ -515,7 +515,7 @@ the following in your append file: SRC_URI += "file://myconfig.cfg \\
file://eth.cfg \\ file://gfx.cfg"
Another variable you can use in your kernel recipe append file is the
```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__
:term:`FILESEXTRAPATHS`
variable. When you use this statement, you are extending the locations
used by the OpenEmbedded system to look for files and patches as the
recipe is processed.
@@ -546,9 +546,9 @@ Applying Patches
If you have a single patch or a small series of patches that you want to
apply to the Linux kernel source, you can do so just as you would with
any other recipe. You first copy the patches to the path added to
```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__ in
:term:`FILESEXTRAPATHS` in
your ``.bbappend`` file as described in the previous section, and then
reference them in ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__
reference them in :term:`SRC_URI`
statements.
For example, you can apply a three-patch series by adding the following
@@ -572,7 +572,7 @@ Changing the Configuration
You can make wholesale or incremental changes to the final ``.config``
file used for the eventual Linux kernel configuration by including a
``defconfig`` file and by specifying configuration fragments in the
```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ to be applied to that
:term:`SRC_URI` to be applied to that
file.
If you have a complete, working Linux kernel ``.config`` file you want
@@ -583,8 +583,8 @@ 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
for the file, while the
```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__
extends the ```FILESPATH`` <&YOCTO_DOCS_REF_URL;#var-FILESPATH>`__
:term:`FILESEXTRAPATHS`
extends the :term:`FILESPATH`
variable (search directories) to include the ``${PN}`` directory you
created to hold the configuration changes.
@@ -631,7 +631,7 @@ looks for ``defconfig`` files in the layer used for Metadata, which is
``defconfig`` files in your layer but would rather allow users to use
the default configuration from the kernel tree and still be able to add
configuration fragments to the
```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ through, for example,
:term:`SRC_URI` through, for example,
append files, you can direct the OpenEmbedded build system to use a
``defconfig`` file that is "in-tree".
@@ -651,7 +651,7 @@ build system detects a statement that identifies an "out-of-tree"
``KBUILD_DEFCONFIG`` variable.
See the
```KBUILD_DEFCONFIG`` <&YOCTO_DOCS_REF_URL;#var-KBUILD_DEFCONFIG>`__
:term:`KBUILD_DEFCONFIG`
variable description for more information.
Using ``devtool`` to Patch the Kernel
@@ -844,8 +844,8 @@ Section.
addition to your ``local.conf`` file specifying to use
"kernel-modules" and the "qemux86" machine, it must also point to the
updated kernel source files. Add
```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ and
```SRCREV`` <&YOCTO_DOCS_REF_URL;#var-SRCREV>`__ statements similar
:term:`SRC_URI` and
:term:`SRCREV` statements similar
to the following to your ``local.conf``: $ cd ~/poky/build/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;
@@ -907,8 +907,8 @@ Section.
contents: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI_append = "
file://0001-calibrate.c-Added-some-printk-statements.patch" The
```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__
and ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statements
:term:`FILESEXTRAPATHS`
and :term:`SRC_URI` statements
enable the OpenEmbedded build system to find the patch file.
For more information on append files and patches, see the "`Creating
@@ -968,16 +968,16 @@ environment, you must do the following:
- Because you launch ``menuconfig`` using BitBake, you must be sure to
set up your environment by running the
````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__ script found in
the `Build Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__.
the :term:`Build Directory`.
- You must be sure of the state of your build's configuration in the
`Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__.
:term:`Source Directory`.
- Your build host must have the following two packages installed:
libncurses5-dev libtinfo-dev
The following commands initialize the BitBake environment, run the
```do_kernel_configme`` <&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme>`__
:ref:`ref-tasks-kernel_configme`
task, and launch ``menuconfig``. These commands assume the Source
Directory's top-level folder is ``~/poky``: $ cd poky $ source
oe-init-build-env $ bitbake linux-yocto -c kernel_configme -f $ bitbake
@@ -1089,17 +1089,17 @@ which the OpenEmbedded build system can draw to create the final
To create a ``defconfig``, start with a complete, working Linux kernel
``.config`` file. Copy that file to the appropriate
``${``\ ```PN`` <&YOCTO_DOCS_REF_URL;#var-PN>`__\ ``}`` directory in
``${``\ :term:`PN`\ ``}`` directory in
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: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI +=
"file://defconfig" The
```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ tells the build
:term:`SRC_URI` tells the build
system how to search for the file, while the
```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__
extends the ```FILESPATH`` <&YOCTO_DOCS_REF_URL;#var-FILESPATH>`__
:term:`FILESEXTRAPATHS`
extends the :term:`FILESPATH`
variable (search directories) to include the ``${PN}`` directory you
created to hold the configuration changes.
@@ -1179,7 +1179,7 @@ steps:
3. *Create the Configuration Fragment:* Run the ``diffconfig`` command
to prepare a configuration fragment. The resulting file
``fragment.cfg`` is placed in the
``${``\ ```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__\ ``}``
``${``\ :term:`WORKDIR`\ ``}``
directory: $ bitbake linux-yocto -c diffconfig
The ``diffconfig`` command creates a file that is a list of Linux kernel
@@ -1196,7 +1196,7 @@ information on how to use the output as a configuration fragment.
Where do you put your configuration fragment files? You can place these
files in an area pointed to by
```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ as directed by your
:term:`SRC_URI` as directed by your
``bblayers.conf`` file, which is located in your layer. The OpenEmbedded
build system picks up the configuration and adds it to the kernel's
configuration. For example, suppose you had a set of configuration
@@ -1219,7 +1219,7 @@ Validating Configuration
------------------------
You can use the
```do_kernel_configcheck`` <&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck>`__
:ref:`ref-tasks-kernel_configcheck`
task to provide configuration validation: $ bitbake linux-yocto -c
kernel_configcheck -f Running this task produces warnings for when a
requested configuration does not appear in the final ``.config`` file or
@@ -1268,9 +1268,9 @@ The output describes the various problems that you can encounter along
with where to find the offending configuration items. You can use the
information in the logs to adjust your configuration files and then
repeat the
```do_kernel_configme`` <&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme>`__
:ref:`ref-tasks-kernel_configme`
and
```do_kernel_configcheck`` <&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck>`__
:ref:`ref-tasks-kernel_configcheck`
tasks until they produce no warnings.
For more information on how to use the ``menuconfig`` tool, see the
@@ -1395,7 +1395,7 @@ If you cannot work with one of the Linux kernel versions supported by
existing linux-yocto recipes, you can still make use of the Yocto
Project Linux kernel tooling by working with your own sources. When you
use your own sources, you will not be able to leverage the existing
kernel `Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__ and stabilization
kernel :term:`Metadata` and stabilization
work of the linux-yocto sources. However, you will be able to manage
your own Metadata in the same format as the linux-yocto sources.
Maintaining format compatibility facilitates converging with linux-yocto
@@ -1428,7 +1428,7 @@ Here are some basic steps you can use to work with your own sources:
the following: $ make defconfig After running the command, copy the
resulting ``.config`` file to the ``files`` directory in your layer
as "defconfig" and then add it to the
```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ variable in the
:term:`SRC_URI` variable in the
recipe.
Running the ``make defconfig`` command results in the default
@@ -1445,7 +1445,7 @@ Here are some basic steps you can use to work with your own sources:
4. *Edit the Recipe:* Edit the following variables in your recipe as
appropriate for your project:
- ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__: The
- :term:`SRC_URI`: The
``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
@@ -1453,32 +1453,32 @@ Here are some basic steps you can use to work with your own sources:
skeleton recipe provides an example ``SRC_URI`` as a syntax
reference.
- ```LINUX_VERSION`` <&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION>`__:
- :term:`LINUX_VERSION`:
The Linux kernel version you are using (e.g. "4.12").
- ```LINUX_VERSION_EXTENSION`` <&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION>`__:
- :term:`LINUX_VERSION_EXTENSION`:
The Linux kernel ``CONFIG_LOCALVERSION`` that is compiled into the
resulting kernel and visible through the ``uname`` command.
- ```SRCREV`` <&YOCTO_DOCS_REF_URL;#var-SRCREV>`__: The commit ID
- :term:`SRCREV`: The commit ID
from which you want to build.
- ```PR`` <&YOCTO_DOCS_REF_URL;#var-PR>`__: Treat this variable the
- :term:`PR`: Treat this variable the
same as you would in any other recipe. Increment the variable to
indicate to the OpenEmbedded build system that the recipe has
changed.
- ```PV`` <&YOCTO_DOCS_REF_URL;#var-PV>`__: The default ``PV``
- :term:`PV`: The default ``PV``
assignment is typically adequate. It combines the
``LINUX_VERSION`` with the Source Control Manager (SCM) revision
as derived from the ```SRCPV`` <&YOCTO_DOCS_REF_URL;#var-SRCPV>`__
as derived from the :term:`SRCPV`
variable. The combined results are a string with the following
form:
3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
While lengthy, the extra verbosity in ``PV`` helps ensure you are
using the exact sources from which you intend to build.
- ```COMPATIBLE_MACHINE`` <&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE>`__:
- :term:`COMPATIBLE_MACHINE`:
A list of the machines supported by your new recipe. This variable
in the example recipe is set by default to a regular expression
that matches only the empty string, "(^$)". This default setting
@@ -1546,13 +1546,13 @@ or other files necessary for building the module that do not come with
the sources. Finally, update the recipe as needed for the module.
Typically, you will need to set the following variables:
- ```DESCRIPTION`` <&YOCTO_DOCS_REF_URL;#var-DESCRIPTION>`__
- :term:`DESCRIPTION`
- ```LICENSE*`` <&YOCTO_DOCS_REF_URL;#var-LICENSE>`__
- ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__
- :term:`SRC_URI`
- ```PV`` <&YOCTO_DOCS_REF_URL;#var-PV>`__
- :term:`PV`
Depending on the build system used by the module sources, you might need
to make some adjustments. For example, a typical module ``Makefile``
@@ -1561,14 +1561,14 @@ looks much like the one provided with the ``hello-mod`` template: obj-m
modules_install: $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install ...
The important point to note here is the
```KERNEL_SRC`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC>`__ variable. The
```module`` <&YOCTO_DOCS_REF_URL;#ref-classes-module>`__ class sets this
:term:`KERNEL_SRC` variable. The
:ref:`module <ref-classes-module>` class sets this
variable and the
```KERNEL_PATH`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH>`__ variable to
:term:`KERNEL_PATH` variable to
``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build
information to build modules. If your module ``Makefile`` uses a
different variable, you might want to override the
```do_compile`` <&YOCTO_DOCS_REF_URL;#ref-tasks-compile>`__ step, or
:ref:`ref-tasks-compile` step, or
create a patch to the ``Makefile`` to work with the more typical
``KERNEL_SRC`` or ``KERNEL_PATH`` variables.
@@ -1577,13 +1577,13 @@ module in your images. To do this, see the documentation for the
following variables in the Yocto Project Reference Manual and set one of
them appropriately for your machine configuration file:
- ```MACHINE_ESSENTIAL_EXTRA_RDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS>`__
- :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
- ```MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS>`__
- :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
- ```MACHINE_EXTRA_RDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS>`__
- :term:`MACHINE_EXTRA_RDEPENDS`
- ```MACHINE_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS>`__
- :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:
@@ -1592,8 +1592,8 @@ derived by appending the module filename without the ``.ko`` extension
to the string "kernel-module-".
Because the variable is
```RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS>`__ and not a
```RDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-RDEPENDS>`__ variable, the build
:term:`RRECOMMENDS` and not a
:term:`RDEPENDS` variable, the build
will not fail if this module is not available to include in the image.
Inspecting Changes and Commits
@@ -1661,9 +1661,9 @@ Adding Recipe-Space Kernel Features
You can add kernel features in the
`recipe-space <#recipe-space-metadata>`__ by using the
```KERNEL_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES>`__
:term:`KERNEL_FEATURES`
variable and by specifying the feature's ``.scc`` file path in the
```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statement. When you
:term:`SRC_URI` statement. When you
add features using this method, the OpenEmbedded build system checks to
be sure the features are present. If the features are not present, the
build stops. Kernel features are the last elements processed for

2
documentation/kernel-dev/kernel-dev-concepts-appx.rst
View File

@@ -313,7 +313,7 @@ The temporary kernel source files resulting from a build using BitBake
have a particular hierarchy. When you build the kernel on your
development system, all files needed for the build are taken from the
source repositories pointed to by the
```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ variable and gathered
:term:`SRC_URI` variable and gathered
in a temporary work area where they are subsequently used to create the
unique kernel. Thus, in a sense, the process constructs a local source
tree specific to your kernel from which to generate the new kernel

10
documentation/kernel-dev/kernel-dev-faq.rst
View File

@@ -28,12 +28,12 @@ append file to override metadata. How do I install a specific kernel
module? Linux kernel modules are packaged individually. To ensure a
specific kernel module is included in an image, include it in the
appropriate machine
```RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS>`__ variable.
:term:`RRECOMMENDS` variable.
These other variables are useful for installing specific modules:
```MACHINE_ESSENTIAL_EXTRA_RDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS>`__
```MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS>`__
```MACHINE_EXTRA_RDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS>`__
```MACHINE_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS>`__
:term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
:term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
:term:`MACHINE_EXTRA_RDEPENDS`
:term:`MACHINE_EXTRA_RRECOMMENDS`
For example, set the following in the ``qemux86.conf`` file to include
the ``ab123`` kernel modules with images built for the ``qemux86``
machine: MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123" For more

2
documentation/kernel-dev/kernel-dev-intro.rst
View File

@@ -13,7 +13,7 @@ Regardless of how you intend to make use of the Yocto Project, chances
are you will work with the Linux kernel. This manual describes how to
set up your build host to support kernel development, introduces the
kernel development process, provides background information on the Yocto
Linux kernel `Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__, describes
Linux kernel :term:`Metadata`, describes
common tasks you can perform using the kernel tools, shows you how to
use the kernel Metadata needed to work with the kernel inside the Yocto
Project, and provides insight into how the Yocto Project team develops

4
documentation/kernel-dev/kernel-dev-maint-appx.rst
View File

@@ -111,7 +111,7 @@ patch, or BSP:
4. *Append Extra Features:* Extra features are appended to the top-level
feature description. These features can come from the
```KERNEL_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES>`__
:term:`KERNEL_FEATURES`
variable in recipes.
5. *Locate, Expand, and Append Each Feature:* Each extra feature is
@@ -172,7 +172,7 @@ can consider the compilation phase of kernel development, which is
building a kernel image. Some prerequisites exist that are validated by
the build process before compilation starts:
- The ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ points to the
- The :term:`SRC_URI` points to the
kernel Git repository.
- A BSP build branch with Metadata exists in the ``yocto-kernel-cache``

342
documentation/overview-manual/overview-manual-concepts.rst
View File

@@ -14,9 +14,9 @@ explained.
Yocto Project Components
========================
The `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__ task executor
The :term:`BitBake` task executor
together with various types of configuration files form the
`OpenEmbedded-Core <&YOCTO_DOCS_REF_URL;#oe-core>`__. This section
:term:`OpenEmbedded-Core (OE-Core)`. This section
overviews these components by describing their use and how they
interact.
@@ -50,7 +50,7 @@ BitBake
BitBake is the tool at the heart of the `OpenEmbedded build
system <&YOCTO_DOCS_REF_URL;#build-system-term>`__ and is responsible
for parsing the `Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__, generating
for parsing the :term:`Metadata`, generating
a list of tasks from it, and then executing those tasks.
This section briefly introduces BitBake. If you want more information on
@@ -107,7 +107,7 @@ Classes
Class files (``.bbclass``) contain information that is useful to share
between recipes files. An example is the
```autotools`` <&YOCTO_DOCS_REF_URL;#ref-classes-autotools>`__ class,
:ref:`autotools <ref-classes-autotools>` class,
which contains common settings for any application that Autotools uses.
The "`Classes <&YOCTO_DOCS_REF_URL;#ref-classes>`__" chapter in the
Yocto Project Reference Manual provides details about classes and how to
@@ -187,7 +187,7 @@ In general, the build's workflow consists of several functional areas:
- *Source Files:* Upstream releases, local projects, and SCMs.
- *Build System:* Processes under the control of
`BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__. This block expands
:term:`BitBake`. This block expands
on how BitBake fetches source, applies patches, completes
compilation, analyzes output for package generation, creates and
tests packages, generates images, and generates cross-development
@@ -253,7 +253,7 @@ source the build environment setup script.
Because the Poky repository is fundamentally an aggregation of existing
repositories, some users might be familiar with running the ```` script
in the context of separate
`OpenEmbedded-Core <&YOCTO_DOCS_REF_URL;#oe-core>`__ and BitBake
:term:`OpenEmbedded-Core (OE-Core)` and BitBake
repositories rather than a single Poky repository. This discussion
assumes the script is executed from within a cloned or unpacked version
of Poky.
@@ -281,29 +281,29 @@ script, see the
in the ``meta-poky`` layer:
- *Target Machine Selection:* Controlled by the
```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__ variable.
:term:`MACHINE` variable.
- *Download Directory:* Controlled by the
```DL_DIR`` <&YOCTO_DOCS_REF_URL;#var-DL_DIR>`__ variable.
:term:`DL_DIR` variable.
- *Shared State Directory:* Controlled by the
```SSTATE_DIR`` <&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR>`__ variable.
:term:`SSTATE_DIR` variable.
- *Build Output:* Controlled by the
```TMPDIR`` <&YOCTO_DOCS_REF_URL;#var-TMPDIR>`__ variable.
:term:`TMPDIR` variable.
- *Distribution Policy:* Controlled by the
```DISTRO`` <&YOCTO_DOCS_REF_URL;#var-DISTRO>`__ variable.
:term:`DISTRO` variable.
- *Packaging Format:* Controlled by the
```PACKAGE_CLASSES`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES>`__
:term:`PACKAGE_CLASSES`
variable.
- *SDK Target Architecture:* Controlled by the
```SDKMACHINE`` <&YOCTO_DOCS_REF_URL;#var-SDKMACHINE>`__ variable.
:term:`SDKMACHINE` variable.
- *Extra Image Packages:* Controlled by the
```EXTRA_IMAGE_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES>`__
:term:`EXTRA_IMAGE_FEATURES`
variable.
.. note::
@@ -334,11 +334,11 @@ created by an autobuilder:
you had several build environments and they shared some common
features. You can set these default build properties here. A good
example is perhaps the packaging format to use through the
```PACKAGE_CLASSES`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES>`__
:term:`PACKAGE_CLASSES`
variable.
One useful scenario for using the ``conf/site.conf`` file is to
extend your ```BBPATH`` <&YOCTO_DOCS_REF_URL;#var-BBPATH>`__ variable
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
and applies your common configurations found in the file. To override
@@ -543,18 +543,18 @@ 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.
BitBake uses the ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__
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.
Another area that plays a significant role in where source files come
from is pointed to by the
```DL_DIR`` <&YOCTO_DOCS_REF_URL;#var-DL_DIR>`__ variable. This area is
:term:`DL_DIR` variable. This area is
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
```BB_GENERATE_MIRROR_TARBALLS`` <&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS>`__
:term:`BB_GENERATE_MIRROR_TARBALLS`
variable.
Judicious use of a ``DL_DIR`` directory can save the build system a trip
@@ -588,7 +588,7 @@ user checks in items (e.g. a local directory containing a development
source tree used by the group).
The canonical method through which to include a local project is to use
the ```externalsrc`` <&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc>`__
the :ref:`externalsrc <ref-classes-externalsrc>`
class to include that local project. You use either the ``local.conf``
or a recipe's append file to override or set the recipe to point to the
local directory on your disk to pull in the whole source tree.
@@ -602,8 +602,8 @@ Another place from which the build system can get source files is with
`fetchers <&YOCTO_DOCS_BB_URL;#bb-fetchers>`__ employing various Source
Control Managers (SCMs) such as Git or Subversion. In such cases, a
repository is cloned or checked out. The
```do_fetch`` <&YOCTO_DOCS_REF_URL;#ref-tasks-fetch>`__ task inside
BitBake uses the ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__
:ref:`ref-tasks-fetch` task inside
BitBake uses the :term:`SRC_URI`
variable and the argument's prefix to determine the correct fetcher
module.
@@ -617,19 +617,19 @@ module.
variable in the Yocto Project Reference Manual.
When fetching a repository, BitBake uses the
```SRCREV`` <&YOCTO_DOCS_REF_URL;#var-SRCREV>`__ variable to determine
:term:`SRCREV` variable to determine
the specific revision from which to build.
Source Mirror(s)
~~~~~~~~~~~~~~~~
Two kinds of mirrors exist: pre-mirrors and regular mirrors. The
```PREMIRRORS`` <&YOCTO_DOCS_REF_URL;#var-PREMIRRORS>`__ and
```MIRRORS`` <&YOCTO_DOCS_REF_URL;#var-MIRRORS>`__ variables point to
:term:`PREMIRRORS` and
:term:`MIRRORS` variables point to
these, respectively. BitBake checks pre-mirrors before looking upstream
for any source files. Pre-mirrors are appropriate when you have a shared
directory that is not a directory defined by the
```DL_DIR`` <&YOCTO_DOCS_REF_URL;#var-DL_DIR>`__ variable. A Pre-mirror
:term:`DL_DIR` variable. A Pre-mirror
typically points to a shared directory that is local to your
organization.
@@ -657,10 +657,10 @@ the build system. Here is a more detailed look at the area:
Package feeds are an intermediary step in the build process. The
OpenEmbedded build system provides classes to generate different package
types, and you specify which classes to enable through the
```PACKAGE_CLASSES`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES>`__
:term:`PACKAGE_CLASSES`
variable. Before placing the packages into package feeds, the build
process validates them with generated output quality assurance checks
through the ```insane`` <&YOCTO_DOCS_REF_URL;#ref-classes-insane>`__
through the :ref:`insane <ref-classes-insane>`
class.
The package feed area resides in the Build Directory. The directory the
@@ -670,19 +670,19 @@ the "Package Feeds" box in the illustration and note the information to
the right of that area. In particular, the following defines where
package files are kept:
- ```DEPLOY_DIR`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR>`__: Defined as
- :term:`DEPLOY_DIR`: Defined as
``tmp/deploy`` in the Build Directory.
- ``DEPLOY_DIR_*``: Depending on the package manager used, the package
type sub-folder. Given RPM, IPK, or DEB packaging and tarball
creation, the
```DEPLOY_DIR_RPM`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_RPM>`__,
```DEPLOY_DIR_IPK`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IPK>`__,
```DEPLOY_DIR_DEB`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_DEB>`__, or
```DEPLOY_DIR_TAR`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_TAR>`__,
:term:`DEPLOY_DIR_RPM`,
:term:`DEPLOY_DIR_IPK`,
:term:`DEPLOY_DIR_DEB`, or
:term:`DEPLOY_DIR_TAR`,
variables are used, respectively.
- ```PACKAGE_ARCH`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH>`__: Defines
- :term:`PACKAGE_ARCH`: Defines
architecture-specific sub-folders. For example, packages could exist
for the i586 or qemux86 architectures.
@@ -690,11 +690,11 @@ BitBake uses the
```do_package_write_*`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb>`__
tasks to generate packages and place them into the package holding area
(e.g. ``do_package_write_ipk`` for IPK packages). See the
"```do_package_write_deb`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb>`__",
"```do_package_write_ipk`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_ipk>`__",
"```do_package_write_rpm`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_rpm>`__",
":ref:`ref-tasks-package_write_deb`",
":ref:`ref-tasks-package_write_ipk`",
":ref:`ref-tasks-package_write_rpm`",
and
"```do_package_write_tar`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_tar>`__"
":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
@@ -708,7 +708,7 @@ BitBake
-------
The OpenEmbedded build system uses
`BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__ to produce images and
:term:`BitBake` to produce images and
Software Development Kits (SDKs). You can see from the `general workflow
figure <#general-workflow-figure>`__, the BitBake area consists of
several functional areas. This section takes a closer look at each of
@@ -731,8 +731,8 @@ code:
.. image:: figures/source-fetching.png
:align: center
The ```do_fetch`` <&YOCTO_DOCS_REF_URL;#ref-tasks-fetch>`__ and
```do_unpack`` <&YOCTO_DOCS_REF_URL;#ref-tasks-unpack>`__ tasks fetch
The :ref:`ref-tasks-fetch` and
:ref:`ref-tasks-unpack` tasks fetch
the source files and unpack them into the `Build
Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__.
@@ -756,17 +756,17 @@ Directory, see the
the Yocto Project Reference Manual.
Each recipe has an area in the Build Directory where the unpacked source
code resides. The ```S`` <&YOCTO_DOCS_REF_URL;#var-S>`__ variable points
code resides. The :term:`S` variable points
to this area for a recipe's unpacked source code. The name of that
directory for any given recipe is defined from several different
variables. The preceding figure and the following list describe the
Build Directory's hierarchy:
- ```TMPDIR`` <&YOCTO_DOCS_REF_URL;#var-TMPDIR>`__: The base directory
- :term:`TMPDIR`: The base directory
where the OpenEmbedded build system performs all its work during the
build. The default base directory is the ``tmp`` directory.
- ```PACKAGE_ARCH`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH>`__: The
- :term:`PACKAGE_ARCH`: The
architecture of the built package or packages. Depending on the
eventual destination of the package or packages (i.e. machine
architecture, `build
@@ -774,33 +774,33 @@ Build Directory's hierarchy:
specific machine), ``PACKAGE_ARCH`` varies. See the variable's
description for details.
- ```TARGET_OS`` <&YOCTO_DOCS_REF_URL;#var-TARGET_OS>`__: The operating
- :term:`TARGET_OS`: The operating
system of the target device. A typical value would be "linux" (e.g.
"qemux86-poky-linux").
- ```PN`` <&YOCTO_DOCS_REF_URL;#var-PN>`__: The name of the recipe used
- :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
the the name of the recipe.
- ```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__: The location
- :term:`WORKDIR`: The location
where the OpenEmbedded build system builds a recipe (i.e. does the
work to create the package).
- ```PV`` <&YOCTO_DOCS_REF_URL;#var-PV>`__: The version of the
- :term:`PV`: The version of the
recipe used to build the package.
- ```PR`` <&YOCTO_DOCS_REF_URL;#var-PR>`__: The revision of the
- :term:`PR`: The revision of the
recipe used to build the package.
- ```S`` <&YOCTO_DOCS_REF_URL;#var-S>`__: Contains the unpacked source
- :term:`S`: Contains the unpacked source
files for a given recipe.
- ```BPN`` <&YOCTO_DOCS_REF_URL;#var-BPN>`__: The name of the recipe
- :term:`BPN`: The name of the recipe
used to build the package. The ``BPN`` variable is a version of
the ``PN`` variable but with common prefixes and suffixes removed.
- ```PV`` <&YOCTO_DOCS_REF_URL;#var-PV>`__: The version of the
- :term:`PV`: The version of the
recipe used to build the package.
.. note::
@@ -825,15 +825,15 @@ and applies them to the source files:
.. image:: figures/patching.png
:align: center
The ```do_patch`` <&YOCTO_DOCS_REF_URL;#ref-tasks-patch>`__ task uses a
recipe's ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statements
and the ```FILESPATH`` <&YOCTO_DOCS_REF_URL;#var-FILESPATH>`__ variable
The :ref:`ref-tasks-patch` task uses a
recipe's :term:`SRC_URI` statements
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
to change the way the build system recognizes patch files. See the
```do_patch`` <&YOCTO_DOCS_REF_URL;#ref-tasks-patch>`__ task for more
:ref:`ref-tasks-patch` task for more
information.
BitBake finds and applies multiple patches for a single recipe in the
@@ -841,7 +841,7 @@ order in which it locates the patches. The ``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
```S`` <&YOCTO_DOCS_REF_URL;#var-S>`__ directory.
:term:`S` directory.
For more information on how the source directories are created, see the
"`Source Fetching <#source-fetching-dev-environment>`__" section. For
@@ -871,13 +871,13 @@ to a holding area (staged) in preparation for packaging:
This step in the build process consists of the following tasks:
- ```do_prepare_recipe_sysroot`` <&YOCTO_DOCS_REF_URL;#ref-tasks-prepare_recipe_sysroot>`__:
- :ref:`ref-tasks-prepare_recipe_sysroot`:
This task sets up the two sysroots in
``${``\ ```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__\ ``}``
``${``\ :term:`WORKDIR`\ ``}``
(i.e. ``recipe-sysroot`` and ``recipe-sysroot-native``) so that
during the packaging phase the sysroots can contain the contents of
the
```do_populate_sysroot`` <&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot>`__
:ref:`ref-tasks-populate_sysroot`
tasks of the recipes on which the recipe containing the tasks
depends. A sysroot exists for both the target and for the native
binaries, which run on the host system.
@@ -889,32 +889,32 @@ This step in the build process consists of the following tasks:
configure itself depending on the target for which it is being built.
The configurations handled by the
```do_configure`` <&YOCTO_DOCS_REF_URL;#ref-tasks-configure>`__ task
:ref:`ref-tasks-configure` task
are specific to configurations for the source code being built by the
recipe.
If you are using the
```autotools`` <&YOCTO_DOCS_REF_URL;#ref-classes-autotools>`__ class,
:ref:`autotools <ref-classes-autotools>` class,
you can add additional configuration options by using the
```EXTRA_OECONF`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF>`__ or
```PACKAGECONFIG_CONFARGS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS>`__
:term:`EXTRA_OECONF` or
:term:`PACKAGECONFIG_CONFARGS`
variables. For information on how this variable works within that
class, see the
```autotools`` <&YOCTO_DOCS_REF_URL;#ref-classes-autotools>`__ class
:ref:`autotools <ref-classes-autotools>` class
`here <&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/autotools.bbclass>`__.
- *``do_compile``*: Once a configuration task has been satisfied,
BitBake compiles the source using the
```do_compile`` <&YOCTO_DOCS_REF_URL;#ref-tasks-compile>`__ task.
:ref:`ref-tasks-compile` task.
Compilation occurs in the directory pointed to by the
```B`` <&YOCTO_DOCS_REF_URL;#var-B>`__ variable. Realize that the
:term:`B` variable. Realize that the
``B`` directory is, by default, the same as the
```S`` <&YOCTO_DOCS_REF_URL;#var-S>`__ directory.
:term:`S` directory.
- *``do_install``*: After compilation completes, BitBake executes the
```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ task.
:ref:`ref-tasks-install` task.
This task copies files from the ``B`` directory and places them in a
holding area pointed to by the ```D`` <&YOCTO_DOCS_REF_URL;#var-D>`__
holding area pointed to by the :term:`D`
variable. Packaging occurs later using files from this holding
directory.
@@ -929,10 +929,10 @@ analyzes the results and splits the output into packages:
.. image:: figures/analysis-for-package-splitting.png
:align: center
The ```do_package`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package>`__ and
```do_packagedata`` <&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata>`__
The :ref:`ref-tasks-package` and
:ref:`ref-tasks-packagedata`
tasks combine to analyze the files found in the
```D`` <&YOCTO_DOCS_REF_URL;#var-D>`__ directory and split them into
:term:`D` directory and split them into
subsets based on available packages and files. Analysis involves the
following as well as other items: splitting out debugging symbols,
looking at shared library dependencies between packages, and looking at
@@ -940,46 +940,46 @@ package relationships.
The ``do_packagedata`` task creates package metadata based on the
analysis such that the build system can generate the final packages. The
```do_populate_sysroot`` <&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot>`__
:ref:`ref-tasks-populate_sysroot`
task stages (copies) a subset of the files installed by the
```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ task into
:ref:`ref-tasks-install` task into
the appropriate sysroot. Working, staged, and intermediate results of
the analysis and package splitting process use several areas:
- ```PKGD`` <&YOCTO_DOCS_REF_URL;#var-PKGD>`__: The destination
- :term:`PKGD`: The destination
directory (i.e. ``package``) for packages before they are split into
individual packages.
- ```PKGDESTWORK`` <&YOCTO_DOCS_REF_URL;#var-PKGDESTWORK>`__: A
- :term:`PKGDESTWORK`: A
temporary work area (i.e. ``pkgdata``) used by the ``do_package``
task to save package metadata.
- ```PKGDEST`` <&YOCTO_DOCS_REF_URL;#var-PKGDEST>`__: The parent
- :term:`PKGDEST`: The parent
directory (i.e. ``packages-split``) for packages after they have been
split.
- ```PKGDATA_DIR`` <&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR>`__: A shared,
- :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
available.
- ```STAGING_DIR_HOST`` <&YOCTO_DOCS_REF_URL;#var-STAGING_DIR_HOST>`__:
- :term:`STAGING_DIR_HOST`:
The path for the sysroot for the system on which a component is built
to run (i.e. ``recipe-sysroot``).
- ```STAGING_DIR_NATIVE`` <&YOCTO_DOCS_REF_URL;#var-STAGING_DIR_NATIVE>`__:
- :term:`STAGING_DIR_NATIVE`:
The path for the sysroot used when building components for the build
host (i.e. ``recipe-sysroot-native``).
- ```STAGING_DIR_TARGET`` <&YOCTO_DOCS_REF_URL;#var-STAGING_DIR_TARGET>`__:
- :term:`STAGING_DIR_TARGET`:
The path for the sysroot used when a component that is built to
execute on a system and it generates code for yet another machine
(e.g. cross-canadian recipes).
The ```FILES`` <&YOCTO_DOCS_REF_URL;#var-FILES>`__ variable defines the
The :term:`FILES` variable defines the
files that go into each package in
```PACKAGES`` <&YOCTO_DOCS_REF_URL;#var-PACKAGES>`__. If you want
:term:`PACKAGES`. If you want
details on how this is accomplished, you can look at
```package.bbclass`` <&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/package.bbclass>`__.
@@ -1013,36 +1013,36 @@ system uses BitBake to generate the root filesystem image:
The image generation process consists of several stages and depends on
several tasks and variables. The
```do_rootfs`` <&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs>`__ task creates
:ref:`ref-tasks-rootfs` task creates
the root filesystem (file and directory structure) for an image. This
task uses several key variables to help create the list of packages to
actually install:
- ```IMAGE_INSTALL`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL>`__: Lists
- :term:`IMAGE_INSTALL`: Lists
out the base set of packages from which to install from the Package
Feeds area.
- ```PACKAGE_EXCLUDE`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE>`__:
- :term:`PACKAGE_EXCLUDE`:
Specifies packages that should not be installed into the image.
- ```IMAGE_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES>`__:
- :term:`IMAGE_FEATURES`:
Specifies features to include in the image. Most of these features
map to additional packages for installation.
- ```PACKAGE_CLASSES`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES>`__:
- :term:`PACKAGE_CLASSES`:
Specifies the package backend (e.g. RPM, DEB, or IPK) to use and
consequently helps determine where to locate packages within the
Package Feeds area.
- ```IMAGE_LINGUAS`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_LINGUAS>`__:
- :term:`IMAGE_LINGUAS`:
Determines the language(s) for which additional language support
packages are installed.
- ```PACKAGE_INSTALL`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL>`__:
- :term:`PACKAGE_INSTALL`:
The final list of packages passed to the package manager for
installation into the image.
With ```IMAGE_ROOTFS`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_ROOTFS>`__
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
install, the root file system is created.
@@ -1069,27 +1069,27 @@ root filesystem image. This file lists out, line-by-line, the installed
packages. The manifest file is useful for the
```testimage`` <&YOCTO_DOCS_REF_URL;#ref-classes-testimage*>`__ class,
for example, to determine whether or not to run specific tests. See the
```IMAGE_MANIFEST`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_MANIFEST>`__
:term:`IMAGE_MANIFEST`
variable for additional information.
Optimizing processes that are run across the image include ``mklibs``,
``prelink``, and any other post-processing commands as defined by the
```ROOTFS_POSTPROCESS_COMMAND`` <&YOCTO_DOCS_REF_URL;#var-ROOTFS_POSTPROCESS_COMMAND>`__
:term:`ROOTFS_POSTPROCESS_COMMAND`
variable. The ``mklibs`` process optimizes the size of the libraries,
while the ``prelink`` process optimizes the dynamic linking of shared
libraries to reduce start up time of executables.
After the root filesystem is built, processing begins on the image
through the ```do_image`` <&YOCTO_DOCS_REF_URL;#ref-tasks-image>`__
through the :ref:`ref-tasks-image`
task. The build system runs any pre-processing commands as defined by
the
```IMAGE_PREPROCESS_COMMAND`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_PREPROCESS_COMMAND>`__
:term:`IMAGE_PREPROCESS_COMMAND`
variable. This variable specifies a list of functions to call before the
build system creates the final image output files.
The build system dynamically creates ``do_image_*`` tasks as needed,
based on the image types specified in the
```IMAGE_FSTYPES`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES>`__ variable.
:term:`IMAGE_FSTYPES` variable.
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
@@ -1105,7 +1105,7 @@ The final task involved in image creation is the
```do_image_complete`` <&YOCTO_DOCS_REF_URL;#ref-tasks-image-complete>`__
task. This task completes the image by applying any image post
processing as defined through the
```IMAGE_POSTPROCESS_COMMAND`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_POSTPROCESS_COMMAND>`__
:term:`IMAGE_POSTPROCESS_COMMAND`
variable. The variable specifies a list of functions to call once the
build system has created the final image output files.
@@ -1143,9 +1143,9 @@ the extensible SDK (eSDK):
Like image generation, the SDK script process consists of several stages
and depends on many variables. The
```do_populate_sdk`` <&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sdk>`__
:ref:`ref-tasks-populate_sdk`
and
```do_populate_sdk_ext`` <&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sdk_ext>`__
:ref:`ref-tasks-populate_sdk_ext`
tasks use these key variables to help create the list of packages to
actually install. For information on the variables listed in the figure,
see the "`Application Development SDK <#sdk-dev-environment>`__"
@@ -1155,7 +1155,7 @@ The ``do_populate_sdk`` task helps create the standard SDK and handles
two parts: a target part and a host part. The target part is the part
built for the target hardware and includes libraries and headers. The
host part is the part of the SDK that runs on the
```SDKMACHINE`` <&YOCTO_DOCS_REF_URL;#var-SDKMACHINE>`__.
:term:`SDKMACHINE`.
The ``do_populate_sdk_ext`` task helps create the extensible SDK and
handles host and target parts differently than its counter part does for
@@ -1173,9 +1173,9 @@ Stamp Files and the Rerunning of Tasks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For each task that completes successfully, BitBake writes a stamp file
into the ```STAMPS_DIR`` <&YOCTO_DOCS_REF_URL;#var-STAMPS_DIR>`__
into the :term:`STAMPS_DIR`
directory. The beginning of the stamp file's filename is determined by
the ```STAMP`` <&YOCTO_DOCS_REF_URL;#var-STAMP>`__ variable, and the end
the :term:`STAMP` variable, and the end
of the name consists of the task's name and current `input
checksum <#overview-checksums>`__.
@@ -1202,8 +1202,8 @@ file does not exist, the task is rerun.
However, you should realize that stamp files only serve as a marker
that some work has been done and that these files do not record task
output. The actual task output would usually be somewhere in
```TMPDIR`` <&YOCTO_DOCS_REF_URL;#var-TMPDIR>`__ (e.g. in some
recipe's ```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__.) What
:term:`TMPDIR` (e.g. in some
recipe's :term:`WORKDIR`.) What
the sstate cache mechanism adds is a way to cache task output that
can then be shared between build machines.
@@ -1244,16 +1244,16 @@ locations as needed. In some cases, it makes sense to have a setscene
task variant (e.g. generating package files in the
```do_package_write_*`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb>`__
task). In other cases, it does not make sense (e.g. a
```do_patch`` <&YOCTO_DOCS_REF_URL;#ref-tasks-patch>`__ task or a
```do_unpack`` <&YOCTO_DOCS_REF_URL;#ref-tasks-unpack>`__ task) since
:ref:`ref-tasks-patch` task or a
:ref:`ref-tasks-unpack` task) since
the work involved would be equal to or greater than the underlying task.
In the build system, the common tasks that have setscene variants are
```do_package`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package>`__,
:ref:`ref-tasks-package`,
``do_package_write_*``,
```do_deploy`` <&YOCTO_DOCS_REF_URL;#ref-tasks-deploy>`__,
```do_packagedata`` <&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata>`__, and
```do_populate_sysroot`` <&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot>`__.
:ref:`ref-tasks-deploy`,
:ref:`ref-tasks-packagedata`, and
:ref:`ref-tasks-populate_sysroot`.
Notice that these tasks represent most of the tasks whose output is an
end result.
@@ -1321,14 +1321,14 @@ The build process writes images out to the `Build
Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__ inside the
``tmp/deploy/images/machine/`` folder as shown in the figure. This
folder contains any files expected to be loaded on the target device.
The ```DEPLOY_DIR`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR>`__ variable
The :term:`DEPLOY_DIR` variable
points to the ``deploy`` directory, while the
```DEPLOY_DIR_IMAGE`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IMAGE>`__
:term:`DEPLOY_DIR_IMAGE`
variable points to the appropriate directory containing images for the
current configuration.
- kernel-image: A kernel binary file. The
```KERNEL_IMAGETYPE`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE>`__
:term:`KERNEL_IMAGETYPE`
variable determines the naming scheme for the kernel image file.
Depending on this variable, the file could begin with a variety of
naming strings. The ``deploy/images/``\ machine directory can contain
@@ -1336,7 +1336,7 @@ current configuration.
- root-filesystem-image: Root filesystems for the target device (e.g.
``*.ext3`` or ``*.bz2`` files). The
```IMAGE_FSTYPES`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES>`__
:term:`IMAGE_FSTYPES`
variable determines the root filesystem image type. The
``deploy/images/``\ machine directory can contain multiple root
filesystems for the machine.
@@ -1344,7 +1344,7 @@ current configuration.
- kernel-modules: Tarballs that contain all the modules built for the
kernel. Kernel module tarballs exist for legacy purposes and can be
suppressed by setting the
```MODULE_TARBALL_DEPLOY`` <&YOCTO_DOCS_REF_URL;#var-MODULE_TARBALL_DEPLOY>`__
:term:`MODULE_TARBALL_DEPLOY`
variable to "0". The ``deploy/images/``\ machine directory can
contain multiple kernel module tarballs for the machine.
@@ -1401,72 +1401,72 @@ can initialize the environment before using the tools.
Software Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual.
All the output files for an SDK are written to the ``deploy/sdk`` folder
inside the `Build Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__ as
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:
- ```DEPLOY_DIR`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR>`__: Points to
- :term:`DEPLOY_DIR`: Points to
the ``deploy`` directory.
- ```SDK_EXT_TYPE`` <&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE>`__:
- :term:`SDK_EXT_TYPE`:
Controls whether or not shared state artifacts are copied into the
extensible SDK. By default, all required shared state artifacts are
copied into the SDK.
- ```SDK_INCLUDE_PKGDATA`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA>`__:
- :term:`SDK_INCLUDE_PKGDATA`:
Specifies whether or not packagedata is included in the extensible
SDK for all recipes in the "world" target.
- ```SDK_INCLUDE_TOOLCHAIN`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN>`__:
- :term:`SDK_INCLUDE_TOOLCHAIN`:
Specifies whether or not the toolchain is included when building the
extensible SDK.
- ```SDK_LOCAL_CONF_WHITELIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST>`__:
- :term:`SDK_LOCAL_CONF_WHITELIST`:
A list of variables allowed through from the build system
configuration into the extensible SDK configuration.
- ```SDK_LOCAL_CONF_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST>`__:
- :term:`SDK_LOCAL_CONF_BLACKLIST`:
A list of variables not allowed through from the build system
configuration into the extensible SDK configuration.
- ```SDK_INHERIT_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST>`__:
- :term:`SDK_INHERIT_BLACKLIST`:
A list of classes to remove from the
```INHERIT`` <&YOCTO_DOCS_REF_URL;#var-INHERIT>`__ value globally
:term:`INHERIT` value globally
within the extensible SDK configuration.
This next list, shows the variables associated with a standard SDK:
- ```DEPLOY_DIR`` <&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR>`__: Points to
- :term:`DEPLOY_DIR`: Points to
the ``deploy`` directory.
- ```SDKMACHINE`` <&YOCTO_DOCS_REF_URL;#var-SDKMACHINE>`__: Specifies
- :term:`SDKMACHINE`: Specifies
the architecture of the machine on which the cross-development tools
are run to create packages for the target hardware.
- ```SDKIMAGE_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-SDKIMAGE_FEATURES>`__:
- :term:`SDKIMAGE_FEATURES`:
Lists the features to include in the "target" part of the SDK.
- ```TOOLCHAIN_HOST_TASK`` <&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_HOST_TASK>`__:
- :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
``bitbake -c populate_sdk imagename`` to create the SDK, a set of
default packages apply. This variable allows you to add more
packages.
- ```TOOLCHAIN_TARGET_TASK`` <&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK>`__:
- :term:`TOOLCHAIN_TARGET_TASK`:
Lists packages that make up the target part of the SDK (i.e. the part
built for the target hardware).
- ```SDKPATH`` <&YOCTO_DOCS_REF_URL;#var-SDKPATH>`__: Defines the
- :term:`SDKPATH`: Defines the
default SDK installation path offered by the installation script.
- ```SDK_HOST_MANIFEST`` <&YOCTO_DOCS_REF_URL;#var-SDK_HOST_MANIFEST>`__:
- :term:`SDK_HOST_MANIFEST`:
Lists all the installed packages that make up the host part of the
SDK. This variable also plays a minor role for extensible SDK
development as well. However, it is mainly used for the standard SDK.
- ```SDK_TARGET_MANIFEST`` <&YOCTO_DOCS_REF_URL;#var-SDK_TARGET_MANIFEST>`__:
- :term:`SDK_TARGET_MANIFEST`:
Lists all the installed packages that make up the target part of the
SDK. This variable also plays a minor role for extensible SDK
development as well. However, it is mainly used for the standard SDK.
@@ -1497,7 +1497,7 @@ toolchain construction and use.
Most of the work occurs on the Build Host. This is the machine used to
build images and generally work within the the Yocto Project
environment. When you run
`BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__ to create an image, the
:term:`BitBake` to create an image, the
OpenEmbedded build system uses the host ``gcc`` compiler to bootstrap a
cross-compiler named ``gcc-cross``. The ``gcc-cross`` compiler is what
BitBake uses to compile source files when creating the target image. You
@@ -1558,11 +1558,11 @@ relocatable SDK used to develop applications. When you run the
installer, it installs the toolchain, which contains the development
tools (e.g., ``gcc-cross-canadian``, ``binutils-cross-canadian``, and
other ``nativesdk-*`` tools), which are tools native to the SDK (i.e.
native to ```SDK_ARCH`` <&YOCTO_DOCS_REF_URL;#var-SDK_ARCH>`__), you
native to :term:`SDK_ARCH`), you
need to cross-compile and test your software. The figure shows the
commands you use to easily build out this toolchain. This
cross-development toolchain is built to execute on the
```SDKMACHINE`` <&YOCTO_DOCS_REF_URL;#var-SDKMACHINE>`__, which might or
:term:`SDKMACHINE`, which might or
might not be the same machine as the Build Host.
.. note::
@@ -1603,7 +1603,7 @@ glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian
(i.e. it is designed to run on the build host).
- ``gcc-cross-canadian``: The final relocatable cross-compiler. When
run on the ```SDKMACHINE`` <&YOCTO_DOCS_REF_URL;#var-SDKMACHINE>`__,
run on the :term:`SDKMACHINE`,
this tool produces executable code that runs on the target device.
Only one cross-canadian compiler is produced per architecture since
they can be targeted at different processor optimizations using
@@ -1623,7 +1623,7 @@ Shared State Cache
==================
By design, the OpenEmbedded build system builds everything from scratch
unless `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__ can determine
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
@@ -1664,7 +1664,7 @@ them if they are deemed to be valid.
.. note::
- The build system does not maintain
```PR`` <&YOCTO_DOCS_REF_URL;#var-PR>`__ information as part of
:term:`PR` information as part of
the shared state packages. Consequently, considerations exist that
affect maintaining shared state feeds. For information on how the
build system works with packages and can track incrementing ``PR``
@@ -1695,8 +1695,8 @@ works on a per-task basis rather than a per-recipe basis. You might
wonder why using a per-task basis is preferred over a per-recipe basis.
To help explain, consider having the IPK packaging backend enabled and
then switching to DEB. In this case, the
```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ and
```do_package`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package>`__ task outputs
:ref:`ref-tasks-install` and
:ref:`ref-tasks-package` task outputs
are still valid. However, with a per-recipe approach, the build would
not include the ``.deb`` files. Consequently, you would have to
invalidate the whole build and rerun it. Rerunning everything is not the
@@ -1720,7 +1720,7 @@ you a good idea of when the task's data changes.
To complicate the problem, there are things that should not be included
in the checksum. First, there is the actual specific build path of a
given task - the ```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__. It
given task - the :term:`WORKDIR`. It
does not matter if the work directory changes because it should not
affect the output for target packages. Also, the build process has the
objective of making native or cross packages relocatable.
@@ -1755,9 +1755,9 @@ Like the ``WORKDIR`` case, situations exist 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:
PACKAGE_ARCHS[vardepsexclude] = "MACHINE" This example ensures that the
```PACKAGE_ARCHS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCHS>`__ variable
:term:`PACKAGE_ARCHS` variable
does not depend on the value of
```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__, even if it does
:term:`MACHINE`, even if it does
reference it.
Equally, there are cases where you need to add dependencies BitBake is
@@ -1795,9 +1795,9 @@ STAGING_DIR_TARGET COREBASE PRSERV_HOST \\ PRSERV_DUMPDIR
PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \\ CCACHE_DIR
EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" The
previous example excludes
```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__ since that variable
:term:`WORKDIR` since that variable
is actually constructed as a path within
```TMPDIR`` <&YOCTO_DOCS_REF_URL;#var-TMPDIR>`__, which is on the
:term:`TMPDIR`, which is on the
whitelist.
The rules for deciding which hashes of dependent tasks to include
@@ -1806,7 +1806,7 @@ accomplished with a Python function. The code in
``meta/lib/oe/sstatesig.py`` shows two examples of this and also
illustrates how you can insert your own policy into the system if so
desired. This file defines the two basic signature generators
`OE-Core <&YOCTO_DOCS_REF_URL;#oe-core>`__ uses: "OEBasic" and
:term:`OpenEmbedded-Core (OE-Core)` uses: "OEBasic" and
"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
@@ -1816,7 +1816,7 @@ as the "OEBasic" version but adds the task hash to the `stamp
files <#stamp-files-and-the-rerunning-of-tasks>`__. This results in any
metadata change that changes the task hash, automatically causing the
task to be run again. This removes the need to bump
```PR`` <&YOCTO_DOCS_REF_URL;#var-PR>`__ values, and changes to metadata
:term:`PR` values, and changes to metadata
automatically ripple across the build.
It is also worth noting that the end result of these signature
@@ -1842,7 +1842,7 @@ half the problem of supporting a shared state. The other half of the
problem is being able to use checksum information during the build and
being able to reuse or rebuild specific components.
The ```sstate`` <&YOCTO_DOCS_REF_URL;#ref-classes-sstate>`__ class is a
The :ref:`sstate <ref-classes-sstate>` class is a
relatively generic implementation of how to "capture" a snapshot of a
given task. The idea is that the build process does not care about the
source of a task's output. Output could be freshly built or it could be
@@ -1850,18 +1850,18 @@ downloaded and unpacked from somewhere. In other words, the build
process does not need to worry about its origin.
Two types of output exist. One type is just about creating a directory
in ```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__. A good example is
in :term:`WORKDIR`. A good example is
the output of either
```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ or
```do_package`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package>`__. The other
:ref:`ref-tasks-install` or
:ref:`ref-tasks-package`. The other
type of output occurs when a set of data is merged into a shared
directory tree such as the sysroot.
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
```do_deploy`` <&YOCTO_DOCS_REF_URL;#ref-tasks-deploy>`__ example taken
from the ```deploy`` <&YOCTO_DOCS_REF_URL;#ref-classes-deploy>`__ class:
:ref:`ref-tasks-deploy` example taken
from the :ref:`deploy <ref-classes-deploy>` class:
DEPLOYDIR = "${WORKDIR}/deploy-${PN}" SSTATETASKS += "do_deploy"
do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" python
@@ -1871,9 +1871,9 @@ do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] =
- Adding "do_deploy" to ``SSTATETASKS`` adds some required
sstate-related processing, which is implemented in the
```sstate`` <&YOCTO_DOCS_REF_URL;#ref-classes-sstate>`__ class, to
:ref:`sstate <ref-classes-sstate>` class, to
before and after the
```do_deploy`` <&YOCTO_DOCS_REF_URL;#ref-tasks-deploy>`__ task.
:ref:`ref-tasks-deploy` task.
- The ``do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"`` declares that
``do_deploy`` places its output in ``${DEPLOYDIR}`` when run normally
@@ -1965,8 +1965,8 @@ do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] =
"${PACKAGELOCK}"
Behind the scenes, the shared state code works by looking in
```SSTATE_DIR`` <&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR>`__ and
```SSTATE_MIRRORS`` <&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS>`__ for
:term:`SSTATE_DIR` and
:term:`SSTATE_MIRRORS` for
shared state files. Here is an example: SSTATE_MIRRORS ?= "\\ file://.\*
http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \\n \\
file://.\* file:///some/local/dir/sstate/PATH"
@@ -1998,7 +1998,7 @@ tasks on which it is dependent are not executed.
As a real world example, the aim is when building an IPK-based image,
only the
```do_package_write_ipk`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_ipk>`__
:ref:`ref-tasks-package_write_ipk`
tasks would have their shared state packages fetched and extracted.
Since the sysroot is not used, it would never get extracted. This is
another reason why a task-based approach is preferred over a
@@ -2011,22 +2011,22 @@ 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
```RDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-RDEPENDS>`__. Three automatic
:term:`RDEPENDS`. Three automatic
mechanisms exist (``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.
- ``shlibdeps``: During the
```do_package`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package>`__ task of
:ref:`ref-tasks-package` task of
each recipe, all shared libraries installed by the recipe are
located. For each shared library, the package that contains the
shared library is registered as providing the shared library. More
specifically, the package is registered as providing the
`soname <https://en.wikipedia.org/wiki/Soname>`__ of the library. The
resulting shared-library-to-package mapping is saved globally in
```PKGDATA_DIR`` <&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR>`__ by the
```do_packagedata`` <&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata>`__
:term:`PKGDATA_DIR` by the
:ref:`ref-tasks-packagedata`
task.
Simultaneously, all executables and shared libraries installed by the
@@ -2047,7 +2047,7 @@ dependencies, you must manually declare the dependencies.
If you want to avoid a package being registered as providing a
particular shared library (e.g. because the library is for internal
use only), then add the library to
```PRIVATE_LIBS`` <&YOCTO_DOCS_REF_URL;#var-PRIVATE_LIBS>`__ inside
:term:`PRIVATE_LIBS` inside
the package's recipe.
- ``pcdeps``: During the ``do_package`` task of each recipe, all
@@ -2082,7 +2082,7 @@ dependencies, you must manually declare the dependencies.
need for a dependency between the packages.
The dependencies added by ``depchains`` are in the form of
```RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS>`__.
:term:`RRECOMMENDS`.
.. note::
@@ -2101,11 +2101,11 @@ dependencies, you must manually declare the dependencies.
To ensure that the dependency chain is never broken, ``-dev`` and
``-dbg`` packages are always generated by default, even if the
packages turn out to be empty. See the
```ALLOW_EMPTY`` <&YOCTO_DOCS_REF_URL;#var-ALLOW_EMPTY>`__ variable
:term:`ALLOW_EMPTY` variable
for more information.
The ``do_package`` task depends on the ``do_packagedata`` task of each
recipe in ```DEPENDS`` <&YOCTO_DOCS_REF_URL;#var-DEPENDS>`__ through use
recipe in :term:`DEPENDS` through use
of a ``[``\ ```deptask`` <&YOCTO_DOCS_BB_URL;#variable-flags>`__\ ``]``
declaration, which guarantees that the required
shared-library/module-to-package mapping information will be available
@@ -2116,15 +2116,15 @@ Fakeroot and Pseudo
Some tasks are easier to implement when allowed to perform certain
operations that are normally reserved for the root user (e.g.
```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__,
:ref:`ref-tasks-install`,
```do_package_write*`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb>`__,
```do_rootfs`` <&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs>`__, and
:ref:`ref-tasks-rootfs`, and
```do_image*`` <&YOCTO_DOCS_REF_URL;#ref-tasks-image>`__). For example,
the ``do_install`` task benefits from being able to set the UID and GID
of installed files to arbitrary values.
One approach to allowing tasks to perform root-only operations would be
to require `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__ to run as
to require :term:`BitBake` to run as
root. However, this method is cumbersome and has security issues. The
approach that is actually used is to run tasks that benefit from root
privileges in a "fake" root environment. Within this environment, the
@@ -2148,7 +2148,7 @@ which results in the illusion of running as root. To keep track of
"fake" file ownership and permissions resulting from operations that
require root permissions, Pseudo uses an SQLite 3 database. This
database is stored in
``${``\ ```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__\ ``}/pseudo/files.db``
``${``\ :term:`WORKDIR`\ ``}/pseudo/files.db``
for individual recipes. Storing the database in a file as opposed to in
memory gives persistence between tasks and builds, which is not
accomplished using fakeroot.

6
documentation/overview-manual/overview-manual-development-environment.rst
View File

@@ -149,7 +149,7 @@ Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth. From the
interface, you can click on any particular item in the "Name" column and
see the URL at the bottom of the page that you need to clone a Git
repository for that particular item. Having a local Git repository of
the `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__, which
the :term:`Source Directory`, which
is usually named "poky", allows you to make changes, contribute to the
history, and ultimately enhance the Yocto Project's tools, Board Support
Packages, and so forth.
@@ -636,7 +636,7 @@ find information on the GNU GPL
When you build an image using the Yocto Project, the build process uses
a known list of licenses to ensure compliance. You can find this list in
the `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ at
the :term:`Source Directory` at
``meta/files/common-licenses``. Once the build completes, the list of
all licenses found and used during that build are kept in the `Build
Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__ at
@@ -660,7 +660,7 @@ that conform to the Open Source Definition (OSD).
You can find a list of the combined SPDX and OSI licenses that the Yocto
Project uses in the ``meta/files/common-licenses`` directory in your
`Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__.
:term:`Source Directory`.
For information that can help you maintain compliance with various open
source licensing during the lifecycle of a product created using the

20
documentation/overview-manual/overview-manual-yp-intro.rst
View File

@@ -260,7 +260,7 @@ accomplish this through a recipe that is a BitBake append
Yocto Project Board Support Packages (BSP) Developer's Guide
.
The `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__
The :term:`Source Directory`
contains both general layers and BSP layers right out of the box. You
can easily identify layers that ship with a Yocto Project release in the
Source Directory by their names. Layers typically have names that begin
@@ -461,7 +461,7 @@ Open-Embedded Build System Components
-------------------------------------
The following list consists of components associated with the
`OpenEmbedded build system <&YOCTO_DOCS_REF_URL;#build-system-term>`__:
: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
@@ -508,7 +508,7 @@ Reference Distribution (Poky)
-----------------------------
Poky is the Yocto Project reference distribution. It contains the
`Open-Embedded build system <&YOCTO_DOCS_REF_URL;#build-system-term>`__
:term:`OpenEmbedded Build System`
(BitBake and OE-Core) as well as a set of metadata to get you started
building your own distribution. See the
`figure <#what-is-the-yocto-project>`__ in "What is the Yocto Project?"
@@ -618,7 +618,7 @@ Project.
- *Native Linux Host:* By far the best option for a Build Host. A
system running Linux as its native operating system allows you to
develop software by directly using the
`BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__ tool. You can
:term:`BitBake` tool. You can
accomplish all aspects of development from a familiar shell of a
supported Linux distribution.
@@ -684,9 +684,9 @@ Reference Embedded Distribution (Poky)
"Poky", which is pronounced *Pock*-ee, is the name of the Yocto
Project's reference distribution or Reference OS Kit. Poky contains the
`OpenEmbedded Build System <&YOCTO_DOCS_REF_URL;#build-system-term>`__
(`BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__ and
`OpenEmbedded-Core <&YOCTO_DOCS_REF_URL;#oe-core>`__) as well as a set
:term:`OpenEmbedded Build System`
(:term:`BitBake` and
:term:`OpenEmbedded-Core (OE-Core)`) as well as a set
of `metadata <&YOCTO_DOCS_REF_URL;#metadata>`__ to get you started
building your own distro. In other words, Poky is a base specification
of the functionality needed for a typical embedded system as well as the
@@ -923,9 +923,9 @@ helpful for getting started:
Another point worth noting is that historically within the Yocto
Project, recipes were referred to as packages - thus, the existence
of several BitBake variables that are seemingly mis-named, (e.g.
```PR`` <&YOCTO_DOCS_REF_URL;#var-PR>`__,
```PV`` <&YOCTO_DOCS_REF_URL;#var-PV>`__, and
```PE`` <&YOCTO_DOCS_REF_URL;#var-PE>`__).
:term:`PR`,
:term:`PV`, and
:term:`PE`).
- *Poky:* Poky is a reference embedded distribution and a reference
test configuration. Poky provides the following:

4
documentation/profile-manual/profile-manual-intro.rst
View File

@@ -51,7 +51,7 @@ well e.g.: $ bitbake core-image-sato
it packages, which makes it difficult to use some of the tools.
You can prevent that by setting the
```INHIBIT_PACKAGE_STRIP`` <&YOCTO_DOCS_REF_URL;#var-INHIBIT_PACKAGE_STRIP>`__
:term:`INHIBIT_PACKAGE_STRIP`
variable to "1" in your ``local.conf`` when you build the image:
INHIBIT_PACKAGE_STRIP = "1" The above setting will noticeably increase
@@ -64,6 +64,6 @@ To generate debug info for packages, you can add dbg-pkgs to
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
```PACKAGE_DEBUG_SPLIT_STYLE`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_DEBUG_SPLIT_STYLE>`__
:term:`PACKAGE_DEBUG_SPLIT_STYLE`
in the ``local.conf`` file: PACKAGE_DEBUG_SPLIT_STYLE =
'debug-file-directory'

6
documentation/profile-manual/profile-manual-usage.rst
View File

@@ -50,7 +50,7 @@ outlined in the 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:
`INHIBIT_PACKAGE_STRIP <&YOCTO_DOCS_REF_URL;#var-INHIBIT_PACKAGE_STRIP>`__
:term:`INHIBIT_PACKAGE_STRIP`
= "1"
perf runs on the target system for the most part. You can archive
@@ -246,7 +246,7 @@ system.
One way around that is to put the following in your ``local.conf`` file
when you build the image:
`INHIBIT_PACKAGE_STRIP <&YOCTO_DOCS_REF_URL;#var-INHIBIT_PACKAGE_STRIP>`__
:term:`INHIBIT_PACKAGE_STRIP`
= "1" However, we already have an image with the binaries stripped, so
what can we do to get perf to resolve the symbols? Basically we need to
install the debuginfo for the busybox package.
@@ -256,7 +256,7 @@ dbg-pkgs to 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
```PACKAGE_DEBUG_SPLIT_STYLE`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_DEBUG_SPLIT_STYLE>`__
:term:`PACKAGE_DEBUG_SPLIT_STYLE`
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

16
documentation/ref-manual/faq.rst
View File

@@ -8,7 +8,7 @@ FAQ
**A:** The term "`Poky <#>`__" refers to the specific reference build
system that the Yocto Project provides. Poky is based on
`OE-Core <#oe-core>`__ and `BitBake <#bitbake-term>`__. Thus, the
:term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the
generic term used here for the build system is the "OpenEmbedded build
system." Development in the Yocto Project using Poky is closely tied to
OpenEmbedded, with changes always being merged to OE-Core or BitBake
@@ -29,7 +29,7 @@ steps on how to update your build tools.
**A:** There are three areas that help with stability;
- The Yocto Project team keeps `OE-Core <#oe-core>`__ small and
- The Yocto Project team keeps :term:`OpenEmbedded-Core (OE-Core)` small and
focused, containing around 830 recipes as opposed to the thousands
available in other OpenEmbedded community layers. Keeping it small
makes it easy to test and maintain.
@@ -227,19 +227,19 @@ meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
size, you need to set various configurations:
- *Image Size:* The OpenEmbedded build system uses the
```IMAGE_ROOTFS_SIZE`` <#var-IMAGE_ROOTFS_SIZE>`__ variable to define
:term:`IMAGE_ROOTFS_SIZE` variable to define
the size of the image in Kbytes. The build system determines the size
by taking into account the initial root filesystem size before any
modifications such as requested size for the image and any requested
additional free disk space to be added to the image.
- *Overhead:* Use the
```IMAGE_OVERHEAD_FACTOR`` <#var-IMAGE_OVERHEAD_FACTOR>`__ variable
:term:`IMAGE_OVERHEAD_FACTOR` variable
to define the multiplier that the build system applies to the initial
image size, which is 1.3 by default.
- *Additional Free Space:* Use the
```IMAGE_ROOTFS_EXTRA_SPACE`` <#var-IMAGE_ROOTFS_EXTRA_SPACE>`__
: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``.
@@ -281,8 +281,8 @@ environments if HTTP transport is available.
When the build system searches for source code, it first tries the local
download directory. If that location fails, Poky tries
```PREMIRRORS`` <#var-PREMIRRORS>`__, the upstream source, and then
```MIRRORS`` <#var-MIRRORS>`__ in that order.
:term:`PREMIRRORS`, the upstream source, and then
:term:`MIRRORS` in that order.
Assuming your distribution is "poky", the OpenEmbedded build system uses
the Yocto Project source ``PREMIRRORS`` by default for SCM-based
@@ -409,7 +409,7 @@ my recipe is installing to the wrong place, or I am getting permissions
errors during the do_install task in my recipe! What is wrong?
**A:** This situation results when a build system does not recognize the
environment variables supplied to it by `BitBake <#bitbake-term>`__. The
environment variables supplied to it by :term:`BitBake`. The
incident that prompted this FAQ entry involved a Makefile that used an
environment variable named ``BINDIR`` instead of the more standard
variable ``bindir``. The makefile's hardcoded default value of

508
documentation/ref-manual/migration.rst
View File

File diff suppressed because it is too large Load Diff

516
documentation/ref-manual/ref-classes.rst
View File

File diff suppressed because it is too large Load Diff

10
documentation/ref-manual/ref-devtool-reference.rst
View File

@@ -217,7 +217,7 @@ 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: $ devtool modify recipe Using the above
command form, ``devtool`` uses the existing recipe's
```SRC_URI`` <#var-SRC_URI>`__ statement to locate the upstream source,
:term:`SRC_URI` statement to locate the upstream source,
extracts the source into the default sources location in the workspace.
The default development branch used is "devtool".
@@ -360,9 +360,9 @@ When you use the ``devtool upgrade`` command, you must supply the root
name of the recipe (i.e. no version, paths, or extensions), and you must
supply the directory to which you want the source extracted. Additional
command options let you control things such as the version number to
which you want to upgrade (i.e. the ```PV`` <#var-PV>`__), the source
which you want to upgrade (i.e. the :term:`PV`), the source
revision to which you want to upgrade (i.e. the
```SRCREV`` <#var-SRCREV>`__), whether or not to apply patches, and so
:term:`SRCREV`), whether or not to apply patches, and so
forth.
You can read more on the ``devtool upgrade`` workflow in the "`Use
@@ -439,7 +439,7 @@ The target is the address of the target machine, which must be running
an SSH server (i.e. ``user@hostname[:destdir]``).
This command deploys all files installed during the
```do_install`` <#ref-tasks-install>`__ task. Furthermore, you do not
:ref:`ref-tasks-install` task. Furthermore, you do not
need to have package management enabled within the target machine. If
you do, the package manager is bypassed.
@@ -492,7 +492,7 @@ Creating the Workspace Layer in an Alternative Location
=======================================================
Use the ``devtool create-workspace`` command to create a new workspace
layer in your `Build Directory <#build-directory>`__. When you create a
layer in your :term:`Build Directory`. When you create a
new workspace layer, it is populated with the ``README`` file and the
``conf`` directory only.

30
documentation/ref-manual/ref-features.rst
View File

@@ -24,7 +24,7 @@ included if the distribution itself does not support them.
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
`Metadata <#metadata>`__ for the feature. Here is an example that
:term:`Metadata` for the feature. Here is an example that
discovers the recipes whose build is potentially changed based on a
given feature: $ cd poky $ git grep
'contains.*MACHINE_FEATURES.*feature'
@@ -35,12 +35,12 @@ Machine Features
================
The items below are features you can use with
```MACHINE_FEATURES`` <#var-MACHINE_FEATURES>`__. Features do not have a
:term:`MACHINE_FEATURES`. Features do not have a
one-to-one correspondence to packages, and they can go beyond simply
controlling the installation of a package or packages. Sometimes a
feature can influence how certain recipes are built. For example, a
feature might determine whether a particular configure option is
specified within the ```do_configure`` <#ref-tasks-configure>`__ task
specified within the :ref:`ref-tasks-configure` task
for a particular recipe.
This feature list only represents features as shipped with the Yocto
@@ -92,18 +92,18 @@ Distro Features
===============
The items below are features you can use with
```DISTRO_FEATURES`` <#var-DISTRO_FEATURES>`__ to enable features across
:term:`DISTRO_FEATURES` to enable features across
your distribution. Features do not have a one-to-one correspondence to
packages, and they can go beyond simply controlling the installation of
a package or packages. In most cases, the presence or absence of a
feature translates to the appropriate option supplied to the configure
script during the ```do_configure`` <#ref-tasks-configure>`__ task for
script during the :ref:`ref-tasks-configure` task for
the recipes that optionally support the feature.
Some distro features are also machine features. These select features
make sense to be controlled both at the machine and distribution
configuration level. See the
```COMBINED_FEATURES`` <#var-COMBINED_FEATURES>`__ variable for more
:term:`COMBINED_FEATURES` variable for more
information.
This list only represents features as shipped with the Yocto Project
@@ -189,8 +189,8 @@ Image Features
==============
The contents of images generated by the OpenEmbedded build system can be
controlled by the ```IMAGE_FEATURES`` <#var-IMAGE_FEATURES>`__ and
```EXTRA_IMAGE_FEATURES`` <#var-EXTRA_IMAGE_FEATURES>`__ variables that
controlled by the :term:`IMAGE_FEATURES` and
:term:`EXTRA_IMAGE_FEATURES` variables that
you typically configure in your image recipes. Through these variables,
you can add several different predefined packages such as development
utilities or packages with debug information needed to investigate
@@ -254,7 +254,7 @@ The following image features are available for all images:
a given image.
Some image features are available only when you inherit the
```core-image`` <#ref-classes-core-image>`__ class. The current list of
:ref:`core-image <ref-classes-core-image>` class. The current list of
these valid features is as follows:
- *hwcodecs:* Installs hardware acceleration codecs.
@@ -299,8 +299,8 @@ Feature Backfilling
===================
Sometimes it is necessary in the OpenEmbedded build system to extend
```MACHINE_FEATURES`` <#var-MACHINE_FEATURES>`__ or
```DISTRO_FEATURES`` <#var-DISTRO_FEATURES>`__ to control functionality
:term:`MACHINE_FEATURES` or
:term:`DISTRO_FEATURES` to control functionality
that was previously enabled and not able to be disabled. For these
cases, we need to add an additional feature item to appear in one of
these variables, but we do not want to force developers who have
@@ -310,8 +310,8 @@ Thus, the OpenEmbedded build system has a mechanism to automatically
"backfill" these added features into existing distro or machine
configurations. You can see the list of features for which this is done
by finding the
```DISTRO_FEATURES_BACKFILL`` <#var-DISTRO_FEATURES_BACKFILL>`__ and
```MACHINE_FEATURES_BACKFILL`` <#var-MACHINE_FEATURES_BACKFILL>`__
:term:`DISTRO_FEATURES_BACKFILL` and
:term:`MACHINE_FEATURES_BACKFILL`
variables in the ``meta/conf/bitbake.conf`` file.
Because such features are backfilled by default into all configurations
@@ -319,9 +319,9 @@ as described in the previous paragraph, developers who wish to disable
the new features need to be able to selectively prevent the backfilling
from occurring. They can do this by adding the undesired feature or
features to the
```DISTRO_FEATURES_BACKFILL_CONSIDERED`` <#var-DISTRO_FEATURES_BACKFILL_CONSIDERED>`__
:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
or
```MACHINE_FEATURES_BACKFILL_CONSIDERED`` <#var-MACHINE_FEATURES_BACKFILL_CONSIDERED>`__
:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`
variables for distro features and machine features respectively.
Here are two examples to help illustrate feature backfilling:

2
documentation/ref-manual/ref-images.rst
View File

@@ -86,7 +86,7 @@ Following is a list of supported recipes:
has the Minimal RAM-based Initial Root Filesystem (initramfs) as part
of the kernel, which allows the system to find the first “init”
program more efficiently. See the
```PACKAGE_INSTALL`` <#var-PACKAGE_INSTALL>`__ variable for
:term:`PACKAGE_INSTALL` variable for
additional information helpful when working with initramfs images.
- ``core-image-minimal-mtdutils``: A ``core-image-minimal`` image that

2
documentation/ref-manual/ref-kickstart.rst
View File

@@ -167,7 +167,7 @@ the ``part`` and ``partition`` commands:
- *``--fsuuid``:* This option is a Wic-specific option that specifies
the filesystem UUID. You can generate or modify
```WKS_FILE`` <#var-WKS_FILE>`__ with this option if a preconfigured
:term:`WKS_FILE` with this option if a preconfigured
filesystem UUID is added to the kernel command line in the bootloader
configuration before you run Wic.

132
documentation/ref-manual/ref-qa-checks.rst
View File

@@ -28,7 +28,7 @@ error form along with an explanation.
.. note::
- At the end of each message, the name of the associated QA test (as
listed in the "```insane.bbclass`` <#ref-classes-insane>`__"
listed in the ":ref:`insane.bbclass <ref-classes-insane>`"
section) appears within square brackets.
- As mentioned, this list of error and warning messages is for QA
@@ -56,10 +56,10 @@ Errors and Warnings
The specified binary produced by the recipe contains dynamic library
load paths (rpaths) that contain build system paths such as
```TMPDIR`` <#var-TMPDIR>`__, which are incorrect for the target and
:term:`TMPDIR`, which are incorrect for the target and
could potentially be a security issue. Check for bad ``-rpath``
options being passed to the linker in your
```do_compile`` <#ref-tasks-compile>`__ log. Depending on the build
:ref:`ref-tasks-compile` log. Depending on the build
system used by the software being built, there might be a configure
option to disable rpath usage completely within the build of the
software.
@@ -82,7 +82,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 ```RDEPENDS`` <#var-RDEPENDS>`__. If
corresponding entry in :term:`RDEPENDS`. If
particular files are required at runtime then ``RDEPENDS`` should be
declared in the recipe to ensure the packages providing them are
built.
@@ -95,7 +95,7 @@ Errors and Warnings
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
```RDEPENDS`` <#var-RDEPENDS>`__ value being added at the packaging
: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.
@@ -107,8 +107,8 @@ Errors and Warnings
Symlink ``.so`` files are for development only, and should therefore
go into the ``-dev`` package. This situation might occur if you add
``*.so*`` rather than ``*.so.*`` to a non-dev package. Change
```FILES`` <#var-FILES>`__ (and possibly
```PACKAGES`` <#var-PACKAGES>`__) such that the specified ``.so``
:term:`FILES` (and possibly
:term:`PACKAGES`) such that the specified ``.so``
file goes into an appropriate ``-dev`` package.
 
@@ -116,8 +116,8 @@ Errors and Warnings
- ``non -staticdev package contains static .a library: <packagename> path '<path>' [staticdev]``
Static ``.a`` library files should go into a ``-staticdev`` package.
Change ```FILES`` <#var-FILES>`__ (and possibly
```PACKAGES`` <#var-PACKAGES>`__) such that the specified ``.a`` file
Change :term:`FILES` (and possibly
:term:`PACKAGES`) such that the specified ``.a`` file
goes into an appropriate ``-staticdev`` package.
 
@@ -130,7 +130,7 @@ Errors and Warnings
"lib32". Another example is when recipes install
``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib". False
positives occasionally exist. For these cases add "libdir" to
```INSANE_SKIP`` <#var-INSANE_SKIP>`__ for the package.
:term:`INSANE_SKIP` for the package.
 
@@ -141,7 +141,7 @@ Errors and Warnings
occur if you add a path which contains a ``.debug`` directory and do
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 ```FILES`` <#var-FILES>`__ for additional
``FILES_${PN}-dbg``. See :term:`FILES` for additional
information on ``FILES``.
 
@@ -158,8 +158,8 @@ Errors and Warnings
the error for is firmware that is not intended to be executed within
the target operating system or is intended to run on a separate
processor within the device, you can add "arch" to
```INSANE_SKIP`` <#var-INSANE_SKIP>`__ for the package. Another
option is to check the ```do_compile`` <#ref-tasks-compile>`__ log
:term:`INSANE_SKIP` for the package. Another
option is to check the :ref:`ref-tasks-compile` log
and verify that the compiler options being used are correct.
 
@@ -176,8 +176,8 @@ Errors and Warnings
the error for is firmware that is not intended to be executed within
the target operating system or is intended to run on a separate
processor within the device, you can add "arch" to
```INSANE_SKIP`` <#var-INSANE_SKIP>`__ for the package. Another
option is to check the ```do_compile`` <#ref-tasks-compile>`__ log
:term:`INSANE_SKIP` for the package. Another
option is to check the :ref:`ref-tasks-compile` log
and verify that the compiler options being used are correct.
 
@@ -194,8 +194,8 @@ Errors and Warnings
the error for is firmware that is not intended to be executed within
the target operating system or is intended to run on a separate
processor within the device, you can add "arch" to
```INSANE_SKIP`` <#var-INSANE_SKIP>`__ for the package. Another
option is to check the ```do_compile`` <#ref-tasks-compile>`__ log
:term:`INSANE_SKIP` for the package. Another
option is to check the :ref:`ref-tasks-compile` log
and verify that the compiler options being used are correct.
 
@@ -208,7 +208,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 ```CFLAGS`` <#var-CFLAGS>`__ when you build it,
software that reads :term:`CFLAGS` when you build it,
you could add the following to your recipe: CFLAGS_append = " -fPIC "
For more information on text relocations at runtime, see
@@ -219,11 +219,11 @@ Errors and Warnings
- ``No GNU_HASH in the elf binary: '<file>' [ldflags]``
This indicates that binaries produced when building the recipe have
not been linked with the ```LDFLAGS`` <#var-LDFLAGS>`__ options
not been linked with the :term:`LDFLAGS` options
provided by the build system. Check to be sure that the ``LDFLAGS``
variable is being passed to the linker command. A common workaround
for this situation is to pass in ``LDFLAGS`` using
```TARGET_CC_ARCH`` <#var-TARGET_CC_ARCH>`__ within the recipe as
:term:`TARGET_CC_ARCH` within the recipe as
follows: TARGET_CC_ARCH += "${LDFLAGS}"
 
@@ -243,7 +243,7 @@ Errors and Warnings
- ``The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]``
The ``/usr/share/info/dir`` should not be packaged. Add the following
line to your ```do_install`` <#ref-tasks-install>`__ task or to your
line to your :ref:`ref-tasks-install` task or to your
``do_install_append`` within the recipe as follows: rm
${D}${infodir}/dir
@@ -251,7 +251,7 @@ Errors and Warnings
- ``Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot]``
The specified symlink points into ```TMPDIR`` <#var-TMPDIR>`__ on the
The specified symlink points into :term:`TMPDIR` on the
host. Such symlinks will work on the host. However, they are clearly
invalid when running on the target. You should either correct the
symlink to use a relative path or remove the symlink.
@@ -260,7 +260,7 @@ Errors and Warnings
- ``<file> failed sanity test (workdir) in path <path> [la]``
The specified ``.la`` file contains ```TMPDIR`` <#var-TMPDIR>`__
The specified ``.la`` file contains :term:`TMPDIR`
paths. Any ``.la`` file containing these paths is incorrect since
``libtool`` adds the correct sysroot prefix when using the files
automatically itself.
@@ -270,7 +270,7 @@ Errors and Warnings
- ``<file> failed sanity test (tmpdir) in path <path> [pkgconfig]``
The specified ``.pc`` file contains
```TMPDIR`` <#var-TMPDIR>`__\ ``/``\ ```WORKDIR`` <#var-WORKDIR>`__
:term:`TMPDIR`\ ``/``\ :term:`WORKDIR`
paths. Any ``.pc`` file containing these paths is incorrect since
``pkg-config`` itself adds the correct sysroot prefix when the files
are accessed.
@@ -285,9 +285,9 @@ Errors and Warnings
brought in using several different methods:
- Using the ``dbg-pkgs``
```IMAGE_FEATURES`` <#var-IMAGE_FEATURES>`__ value.
:term:`IMAGE_FEATURES` value.
- Using ```IMAGE_INSTALL`` <#var-IMAGE_INSTALL>`__.
- Using :term:`IMAGE_INSTALL`.
- As a dependency of another ``dbg`` package that was brought in
using one of the above methods.
@@ -295,7 +295,7 @@ Errors and Warnings
The dependency might have been automatically added because the
``dbg`` package erroneously contains files that it should not contain
(e.g. a non-symlink ``.so`` file) or it might have been added
manually (e.g. by adding to ```RDEPENDS`` <#var-RDEPENDS>`__).
manually (e.g. by adding to :term:`RDEPENDS`).
 
@@ -307,9 +307,9 @@ Errors and Warnings
usually brought in using several different methods:
- Using the ``dev-pkgs``
```IMAGE_FEATURES`` <#var-IMAGE_FEATURES>`__ value.
:term:`IMAGE_FEATURES` value.
- Using ```IMAGE_INSTALL`` <#var-IMAGE_INSTALL>`__.
- Using :term:`IMAGE_INSTALL`.
- As a dependency of another ``dev`` package that was brought in
using one of the above methods.
@@ -317,19 +317,19 @@ Errors and Warnings
The dependency might have been automatically added (because the
``dev`` package erroneously contains files that it should not have
(e.g. a non-symlink ``.so`` file) or it might have been added
manually (e.g. by adding to ```RDEPENDS`` <#var-RDEPENDS>`__).
manually (e.g. by adding to :term:`RDEPENDS`).
 
- ``<var>_<packagename> is invalid: <comparison> (<value>) only comparisons <, =, >, <=, and >= are allowed [dep-cmp]``
If you are adding a versioned dependency relationship to one of the
dependency variables (```RDEPENDS`` <#var-RDEPENDS>`__,
```RRECOMMENDS`` <#var-RRECOMMENDS>`__,
```RSUGGESTS`` <#var-RSUGGESTS>`__,
```RPROVIDES`` <#var-RPROVIDES>`__,
```RREPLACES`` <#var-RREPLACES>`__, or
```RCONFLICTS`` <#var-RCONFLICTS>`__), you must only use the named
dependency variables (:term:`RDEPENDS`,
:term:`RRECOMMENDS`,
:term:`RSUGGESTS`,
:term:`RPROVIDES`,
:term:`RREPLACES`, or
:term:`RCONFLICTS`), you must only use the named
comparison operators. Change the versioned dependency values you are
adding to match those listed in the message.
@@ -337,7 +337,7 @@ Errors and Warnings
- ``<recipename>: The compile log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [compile-host-path]``
The log for the ```do_compile`` <#ref-tasks-compile>`__ task
The log for the :ref:`ref-tasks-compile` task
indicates that paths on the host were searched for files, which is
not appropriate when cross-compiling. Look for "is unsafe for
cross-compilation" or "CROSS COMPILE Badness" in the specified log
@@ -347,7 +347,7 @@ Errors and Warnings
- ``<recipename>: The install log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [install-host-path]``
The log for the ```do_install`` <#ref-tasks-install>`__ task
The log for the :ref:`ref-tasks-install` task
indicates that paths on the host were searched for files, which is
not appropriate when cross-compiling. Look for "is unsafe for
cross-compilation" or "CROSS COMPILE Badness" in the specified log
@@ -357,7 +357,7 @@ Errors and Warnings
- ``This autoconf log indicates errors, it looked at host include and/or library paths while determining system capabilities. Rerun configure task after fixing this. The path was '<path>'``
The log for the ```do_configure`` <#ref-tasks-configure>`__ task
The log for the :ref:`ref-tasks-configure` task
indicates that paths on the host were searched for files, which is
not appropriate when cross-compiling. Look for "is unsafe for
cross-compilation" or "CROSS COMPILE Badness" in the specified log
@@ -371,7 +371,7 @@ Errors and Warnings
enforced by the package manager itself) is to require that package
names are all lower case and to allow a restricted set of characters.
If your recipe name does not match this, or you add packages to
```PACKAGES`` <#var-PACKAGES>`__ that do not conform to the
: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``,
change the package name appropriately.
@@ -388,38 +388,38 @@ Errors and Warnings
upstream build documentation, the ``./configure --help`` output, and
the upstream change log or release notes. Once you have worked out
what the appropriate change is, you can update
```EXTRA_OECONF`` <#var-EXTRA_OECONF>`__,
```PACKAGECONFIG_CONFARGS`` <#var-PACKAGECONFIG_CONFARGS>`__, or the
individual ```PACKAGECONFIG`` <#var-PACKAGECONFIG>`__ option values
:term:`EXTRA_OECONF`,
:term:`PACKAGECONFIG_CONFARGS`, or the
individual :term:`PACKAGECONFIG` option values
accordingly.
 
- ``Recipe <recipefile> has PN of "<recipename>" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]``
The specified recipe has a name (```PN`` <#var-PN>`__) value that
appears in ```OVERRIDES`` <#var-OVERRIDES>`__. If a recipe is named
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 ```MACHINE`` <#var-MACHINE>`__
or ```DISTRO`` <#var-DISTRO>`__), it can have unexpected
(e.g. ``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
```FILES`` <#var-FILES>`__ for additional information.
:term:`FILES` for additional information.
 
- ``<recipefile>: Variable <variable> is set as not being package specific, please fix this. [pkgvarcheck]``
Certain variables (```RDEPENDS`` <#var-RDEPENDS>`__,
```RRECOMMENDS`` <#var-RRECOMMENDS>`__,
```RSUGGESTS`` <#var-RSUGGESTS>`__,
```RCONFLICTS`` <#var-RCONFLICTS>`__,
```RPROVIDES`` <#var-RPROVIDES>`__,
```RREPLACES`` <#var-RREPLACES>`__, ```FILES`` <#var-FILES>`__,
Certain variables (:term:`RDEPENDS`,
:term:`RRECOMMENDS`,
:term:`RSUGGESTS`,
:term:`RCONFLICTS`,
:term:`RPROVIDES`,
:term:`RREPLACES`, :term:`FILES`,
``pkg_preinst``, ``pkg_postinst``, ``pkg_prerm``, ``pkg_postrm``, and
```ALLOW_EMPTY`` <#var-ALLOW_EMPTY>`__) should always be set specific
:term:`ALLOW_EMPTY`) should always be set specific
to a package (i.e. they should be set with a package name override
such as ``RDEPENDS_${PN} = "value"`` rather than
``RDEPENDS = "value"``). If you receive this error, correct any
@@ -456,7 +456,7 @@ Errors and Warnings
- ``<packagename> is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]``
Package names must appear only once in the
```PACKAGES`` <#var-PACKAGES>`__ variable. You might receive this
:term:`PACKAGES` variable. You might receive this
error if you are attempting to add a package to ``PACKAGES`` that is
already in the variable's value.
@@ -465,7 +465,7 @@ Errors and Warnings
- ``FILES variable for package <packagename> contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]``
The string "//" is invalid in a Unix path. Correct all occurrences
where this string appears in a ```FILES`` <#var-FILES>`__ variable so
where this string appears in a :term:`FILES` variable so
that there is only a single "/".
 
@@ -473,14 +473,14 @@ Errors and Warnings
- ``<recipename>: Files/directories were installed but not shipped in any package [installed-vs-shipped]``
Files have been installed within the
```do_install`` <#ref-tasks-install>`__ task but have not been
included in any package by way of the ```FILES`` <#var-FILES>`__
:ref:`ref-tasks-install` task but have not been
included in any package by way of the :term:`FILES`
variable. Files that do not appear in any package cannot be present
in an image later on in the build process. You need to do one of the
following:
- Add the files to ``FILES`` for the package you want them to appear
in (e.g. ``FILES_${``\ ```PN`` <#var-PN>`__\ ``}`` for the main
in (e.g. ``FILES_${``\ :term:`PN`\ ``}`` for the main
package).
- Delete the files at the end of the ``do_install`` task if the
@@ -496,15 +496,15 @@ Errors and Warnings
message might indicate that a private version of a library is being
erroneously picked up as the provider for a common library. If that
is the case, you should add the library's ``.so`` file name to
```PRIVATE_LIBS`` <#var-PRIVATE_LIBS>`__ in the recipe that provides
:term:`PRIVATE_LIBS` in the recipe that provides
the private version of the library.
- ``LICENSE_<packagename> includes licenses (<licenses>) that are not listed in LICENSE [unlisted-pkg-lics]``
The ```LICENSE`` <#var-LICENSE>`__ of the recipe should be a superset
The :term:`LICENSE` of the recipe should be a superset
of all the licenses of all packages produced by this recipe. In other
words, any license in ``LICENSE_*`` should also appear in
```LICENSE`` <#var-LICENSE>`__.
:term:`LICENSE`.
 
@@ -513,11 +513,11 @@ Configuring and Disabling QA Checks
You can configure the QA checks globally so that specific check failures
either raise a warning or an error message, using the
```WARN_QA`` <#var-WARN_QA>`__ and ```ERROR_QA`` <#var-ERROR_QA>`__
:term:`WARN_QA` and :term:`ERROR_QA`
variables, respectively. You can also disable checks within a particular
recipe using ```INSANE_SKIP`` <#var-INSANE_SKIP>`__. For information on
recipe using :term:`INSANE_SKIP`. For information on
how to work with the QA checks, see the
"```insane.bbclass`` <#ref-classes-insane>`__" section.
":ref:`insane.bbclass <ref-classes-insane>`" section.
.. note::

10
documentation/ref-manual/ref-release-process.rst
View File

@@ -41,7 +41,7 @@ Major Release Codenames
Each major release receives a codename that identifies the release in
the `Yocto Project Source
Repositories <&YOCTO_DOCS_OM_URL;#yocto-project-repositories>`__. The
concept is that branches of `Metadata <#metadata>`__ with the same
concept is that branches of :term:`Metadata` with the same
codename are likely to be compatible and thus work together.
.. note::
@@ -107,12 +107,12 @@ consists of the following pieces:
- ``bitbake-selftest``: A standalone command that runs unit tests on
key pieces of BitBake and its fetchers.
- ```sanity.bbclass`` <#ref-classes-sanity>`__: This automatically
- :ref:`sanity.bbclass <ref-classes-sanity>`: This automatically
included class checks the build environment for missing tools (e.g.
``gcc``) or common misconfigurations such as
```MACHINE`` <#var-MACHINE>`__ set incorrectly.
:term:`MACHINE` set incorrectly.
- ```insane.bbclass`` <#ref-classes-insane>`__: This class checks the
- :ref:`insane.bbclass <ref-classes-insane>`: This class checks the
generated output from builds for sanity. For example, if building for
an ARM target, did the build produce ARM binaries. If, for example,
the build produced PPC binaries then there is a problem.
@@ -149,7 +149,7 @@ efficiently.
The Yocto Project's main Autobuilder (``autobuilder.yoctoproject.org``)
publicly tests each Yocto Project release's code in the
`OE-Core <#oe-core>`__, Poky, and BitBake repositories. The testing
:term:`OpenEmbedded-Core (OE-Core)`, Poky, and BitBake repositories. The testing
occurs for both the current state of the "master" branch and also for
submitted patches. Testing for submitted patches usually occurs in the
"ross/mut" branch in the ``poky-contrib`` repository (i.e. the

58
documentation/ref-manual/ref-structure.rst
View File

@@ -4,7 +4,7 @@
Source Directory Structure
**************************
The `Source Directory <#source-directory>`__ consists of numerous files,
The :term:`Source Directory` consists of numerous files,
directories and subdirectories; understanding their locations and
contents is key to using the Yocto Project effectively. This chapter
describes the Source Directory and gives information about those files
@@ -36,7 +36,7 @@ Directory <#source-directory>`__.
This directory includes a copy of BitBake for ease of use. The copy
usually matches the current stable BitBake release from the BitBake
project. BitBake, a `Metadata <#metadata>`__ interpreter, reads the
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.
@@ -63,7 +63,7 @@ the OpenEmbedded build environment setup script (i.e.
````` <#structure-core-script>`__).
It is also possible to place output and configuration files in a
directory separate from the `Source Directory <#source-directory>`__ by
directory separate from the :term:`Source Directory` by
providing a directory name when you ``source`` the setup script. For
information on separating output from your local Source Directory files
(commonly described as an "out of tree" build), see the
@@ -152,7 +152,7 @@ BitBake commands. The script uses other scripts within the ``scripts``
directory to do the bulk of the work.
When you run this script, your Yocto Project environment is set up, a
`Build Directory <#build-directory>`__ is created, your working
: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: $ source
@@ -162,7 +162,7 @@ core-image-sato meta-toolchain meta-ide-support You can also run
generated qemu images with a command like 'runqemu qemux86-64' The
default output of the ``oe-init-build-env`` script is from the
``conf-notes.txt`` file, which is found in the ``meta-poky`` directory
within the `Source Directory <#source-directory>`__. If you design a
within the :term:`Source Directory`. If you design a
custom distribution, you can include your own version of this
configuration file to mention the targets defined by your distribution.
See the "`Creating a Custom Template Configuration
@@ -213,7 +213,7 @@ Directory a specific name when you run the setup script, the name
defaults to ``build/``.
For subsequent parsing and processing, the name of the Build directory
is available via the ```TOPDIR`` <#var-TOPDIR>`__ variable.
is available via the :term:`TOPDIR` variable.
.. _structure-build-buildhistory:
@@ -243,7 +243,7 @@ relatively rare.
At a minimum, you would normally edit this file to select the target
``MACHINE``, which package types you wish to use
(```PACKAGE_CLASSES`` <#var-PACKAGE_CLASSES>`__), and the location from
(:term:`PACKAGE_CLASSES`), and the location from
which you want to access downloaded files (``DL_DIR``).
If ``local.conf`` is not present when you start the build, the
@@ -261,7 +261,7 @@ build environment from any layer by setting the variable in the
top-level build environment setup script as follows:
TEMPLATECONF=your_layer/conf Once the build process gets the sample
file, it uses ``sed`` to substitute final
``${``\ ```OEROOT`` <#var-OEROOT>`__\ ``}`` values for all
``${``\ :term:`OEROOT`\ ``}`` values for all
``##OEROOT##`` values.
.. note::
@@ -286,7 +286,7 @@ file, it uses ``sed`` to substitute final
This configuration file defines
`layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__,
which are directory trees, traversed (or walked) by BitBake. The
``bblayers.conf`` file uses the ```BBLAYERS`` <#var-BBLAYERS>`__
``bblayers.conf`` file uses the :term:`BBLAYERS`
variable to list the layers BitBake tries to find.
If ``bblayers.conf`` is not present when you start the build, the
@@ -304,7 +304,7 @@ implies that you can base your build from any layer by setting the
variable in the top-level build environment setup script as follows:
TEMPLATECONF=your_layer/conf Once the build process gets the sample
file, it uses ``sed`` to substitute final
``${``\ ```OEROOT`` <#var-OEROOT>`__\ ``}`` values for all
``${``\ :term:`OEROOT`\ ``}`` values for all
``##OEROOT##`` values.
.. note::
@@ -355,7 +355,7 @@ You can control the location of this directory through the
--------------
The OpenEmbedded build system creates and uses this directory for all
the build system's output. The ```TMPDIR`` <#var-TMPDIR>`__ variable
the build system's output. The :term:`TMPDIR` variable
points to this directory.
BitBake creates this directory if it does not exist. As a last resort,
@@ -393,7 +393,7 @@ cache is reused. If the file has changed, it is reparsed.
---------------------
This directory contains any "end result" output from the OpenEmbedded
build process. The ```DEPLOY_DIR`` <#var-DEPLOY_DIR>`__ variable points
build process. The :term:`DEPLOY_DIR` variable points
to this directory. For more detail on the contents of the ``deploy``
directory, see the
"`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__" and
@@ -497,11 +497,11 @@ another.
----------------------------------
This directory is the location of the sysroot contents that the task
```do_prepare_recipe_sysroot`` <#ref-tasks-prepare_recipe_sysroot>`__
:ref:`ref-tasks-prepare_recipe_sysroot`
links or copies into the recipe-specific sysroot for each recipe listed
in ```DEPENDS`` <#var-DEPENDS>`__. Population of this directory is
in :term:`DEPENDS`. Population of this directory is
handled through shared state, while the path is specified by the
```COMPONENTS_DIR`` <#var-COMPONENTS_DIR>`__ variable. Apart from a few
:term:`COMPONENTS_DIR` variable. Apart from a few
unusual circumstances, handling of the ``sysroots-components`` directory
should be automatic, and recipes should not directly reference
``build/tmp/sysroots-components``.
@@ -514,7 +514,7 @@ 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 DISTRO version of the Yocto Project, sysroots exist in
recipe-specific ```WORKDIR`` <#var-WORKDIR>`__ directories. Thus, the
recipe-specific :term:`WORKDIR` directories. Thus, the
``build/tmp/sysroots/`` directory is unused.
.. note::
@@ -566,7 +566,7 @@ directory. For example, the source for a particular package is unpacked,
patched, configured and compiled all within its own work directory.
Within the work directory, organization is based on the package group
and version for which the source is being compiled as defined by the
```WORKDIR`` <#var-WORKDIR>`__.
:term:`WORKDIR`.
It is worth considering the structure of a typical work directory. As an
example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86``
@@ -599,12 +599,12 @@ As described earlier in the
"```build/tmp/sysroots/`` <#structure-build-tmp-sysroots>`__" section,
beginning with the DISTRO release of the Yocto Project, the OpenEmbedded
build system builds each recipe in its own work directory (i.e.
```WORKDIR`` <#var-WORKDIR>`__). The path to the work directory is
:term:`WORKDIR`). The path to the work directory is
constructed using the architecture of the given build (e.g.
```TUNE_PKGARCH`` <#var-TUNE_PKGARCH>`__,
```MACHINE_ARCH`` <#var-MACHINE_ARCH>`__, or "allarch"), the recipe
:term:`TUNE_PKGARCH`,
:term:`MACHINE_ARCH`, or "allarch"), the recipe
name, and the version of the recipe (i.e.
```PE`` <#var-PE>`__\ ``:``\ ```PV`` <#var-PV>`__\ ``-``\ ```PR`` <#var-PR>`__).
:term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`).
A number of key subdirectories exist within each recipe work directory:
@@ -614,17 +614,17 @@ A number of key subdirectories exist within each recipe work directory:
which tasks were executed.
- ``${WORKDIR}/image``: Contains the output of the
```do_install`` <#ref-tasks-install>`__ task, which corresponds to
the ``${``\ ```D`` <#var-D>`__\ ``}`` variable in that task.
:ref:`ref-tasks-install` task, which corresponds to
the ``${``\ :term:`D`\ ``}`` variable in that task.
- ``${WORKDIR}/pseudo``: Contains the pseudo database and log for any
tasks executed under pseudo for the recipe.
- ``${WORKDIR}/sysroot-destdir``: Contains the output of the
```do_populate_sysroot`` <#ref-tasks-populate_sysroot>`__ task.
:ref:`ref-tasks-populate_sysroot` task.
- ``${WORKDIR}/package``: Contains the output of the
```do_package`` <#ref-tasks-package>`__ task before the output is
:ref:`ref-tasks-package` task before the output is
split into individual packages.
- ``${WORKDIR}/packages-split``: Contains the output of the
@@ -645,7 +645,7 @@ A number of key subdirectories exist within each recipe work directory:
- ``${WORKDIR}/build``: This subdirectory applies only to recipes that
support builds where the source is separate from the build artifacts.
The OpenEmbedded build system uses this directory as a separate build
directory (i.e. ``${``\ ```B`` <#var-B>`__\ ``}``).
directory (i.e. ``${``\ :term:`B`\ ``}``).
.. _structure-build-work-shared:
@@ -662,7 +662,7 @@ recipes. In practice, this is only used for ``gcc`` and its variants
The Metadata - ``meta/``
========================
As mentioned previously, `Metadata <#metadata>`__ is the core of the
As mentioned previously, :term:`Metadata` is the core of the
Yocto Project. Metadata has several important subdivisions:
.. _structure-meta-classes:
@@ -681,7 +681,7 @@ generation or packaging also have their specific class files such as
``image.bbclass``, ``rootfs_*.bbclass`` and ``package*.bbclass``.
For reference information on classes, see the
"`Classes <#ref-classes>`__" chapter.
":ref:`ref-manual/ref-classes:Classes`" chapter.
.. _structure-meta-conf:
@@ -726,7 +726,7 @@ file mainly inherits its configuration from Poky.
The OpenEmbedded build system searches this directory for configuration
files that correspond to the value of
```SDKMACHINE`` <#var-SDKMACHINE>`__. By default, 32-bit and 64-bit x86
:term:`SDKMACHINE`. By default, 32-bit and 64-bit x86
files ship with the Yocto Project that support some SDK hosts. However,
it is possible to extend that support to other SDK hosts by adding
additional configuration files in this subdirectory within another

126
documentation/ref-manual/ref-tasks.rst
View File

@@ -32,7 +32,7 @@ tasks required to build a recipe.
--------------
Compiles the source code. This task runs with the current working
directory set to ``${``\ ```B`` <#var-B>`__\ ``}``.
directory set to ``${``\ :term:`B`\ ``}``.
The default behavior of this task is to run the ``oe_runmake`` function
if a makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found.
@@ -52,11 +52,11 @@ Compiles the runtime test suite included in the software being built.
Configures the source by enabling and disabling any build-time and
configuration options for the software being built. The task runs with
the current working directory set to ``${``\ ```B`` <#var-B>`__\ ``}``.
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
```CLEANBROKEN`` <#var-CLEANBROKEN>`__ is not set to "1". If no such
:term:`CLEANBROKEN` is not set to "1". If no such
file is found or the ``CLEANBROKEN`` variable is set to "1", the
``do_configure`` task does nothing.
@@ -73,13 +73,13 @@ Configures the runtime test suite included in the software being built.
-------------
Writes output files that are to be deployed to
``${``\ ```DEPLOY_DIR_IMAGE`` <#var-DEPLOY_DIR_IMAGE>`__\ ``}``. The
``${``\ :term:`DEPLOY_DIR_IMAGE`\ ``}``. The
task runs with the current working directory set to
``${``\ ```B`` <#var-B>`__\ ``}``.
``${``\ :term:`B`\ ``}``.
Recipes implementing this task should inherit the
```deploy`` <#ref-classes-deploy>`__ class and should write the output
to ``${``\ ```DEPLOYDIR`` <#var-DEPLOYDIR>`__\ ``}``, which is not to be
:ref:`deploy <ref-classes-deploy>` class and should write the output
to ``${``\ :term:`DEPLOYDIR`\ ``}``, which is not to be
confused with ``${DEPLOY_DIR}``. The ``deploy`` class sets up
``do_deploy`` as a shared state (sstate) task that can be accelerated
through sstate use. The sstate mechanism takes care of copying the
@@ -93,7 +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 ```do_compile`` <#ref-tasks-compile>`__, you can add it by doing
after :ref:`ref-tasks-compile`, you can add it by doing
the following: addtask deploy after do_compile Adding ``do_deploy``
after other tasks works the same way.
@@ -124,7 +124,7 @@ If the ``do_deploy`` task re-executes, any previous output is removed
------------
Fetches the source code. This task uses the
```SRC_URI`` <#var-SRC_URI>`__ variable and the argument's prefix to
:term:`SRC_URI` variable and the argument's prefix to
determine the correct `fetcher <&YOCTO_DOCS_BB_URL;#bb-fetchers>`__
module.
@@ -135,12 +135,12 @@ module.
Starts the image generation process. The ``do_image`` task runs after
the OpenEmbedded build system has run the
```do_rootfs`` <#ref-tasks-rootfs>`__ task during which packages are
:ref:`ref-tasks-rootfs` task during which packages are
identified for installation into the image and the root filesystem is
created, complete with post-processing.
The ``do_image`` task performs pre-processing on the image through the
```IMAGE_PREPROCESS_COMMAND`` <#var-IMAGE_PREPROCESS_COMMAND>`__ and
:term:`IMAGE_PREPROCESS_COMMAND` and
dynamically generates supporting ``do_image_*`` tasks as needed.
For more information on image creation, see the "`Image
@@ -154,13 +154,13 @@ section in the Yocto Project Overview and Concepts Manual.
Completes the image generation process. The ``do_image_complete`` task
runs after the OpenEmbedded build system has run the
```do_image`` <#ref-tasks-image>`__ task during which image
:ref:`ref-tasks-image` task during which image
pre-processing occurs and through dynamically generated ``do_image_*``
tasks the image is constructed.
The ``do_image_complete`` task performs post-processing on the image
through the
```IMAGE_POSTPROCESS_COMMAND`` <#var-IMAGE_POSTPROCESS_COMMAND>`__.
:term:`IMAGE_POSTPROCESS_COMMAND`.
For more information on image creation, see the "`Image
Generation <&YOCTO_DOCS_OM_URL;#image-generation-dev-environment>`__"
@@ -172,13 +172,13 @@ section in the Yocto Project Overview and Concepts Manual.
--------------
Copies files that are to be packaged into the holding area
``${``\ ```D`` <#var-D>`__\ ``}``. This task runs with the current
working directory set to ``${``\ ```B`` <#var-B>`__\ ``}``, which is the
``${``\ :term:`D`\ ``}``. This task runs with the current
working directory set to ``${``\ :term:`B`\ ``}``, which is the
compilation directory. The ``do_install`` task, as well as other tasks
that either directly or indirectly depend on the installed files (e.g.
```do_package`` <#ref-tasks-package>`__,
:ref:`ref-tasks-package`,
```do_package_write_*`` <#ref-tasks-package_write_deb>`__, and
```do_rootfs`` <#ref-tasks-rootfs>`__), run under
:ref:`ref-tasks-rootfs`), run under
`fakeroot <&YOCTO_DOCS_OM_URL;#fakeroot-and-pseudo>`__.
.. note::
@@ -199,7 +199,7 @@ that either directly or indirectly depend on the installed files (e.g.
- The ``tar`` command with the "--no-same-owner" option. See the
``bin_package.bbclass`` file in the ``meta/classes`` directory of
the `Source Directory <#source-directory>`__ for an example.
the :term:`Source Directory` for an example.
.. _ref-tasks-install_ptest_base:
@@ -215,15 +215,15 @@ holding area.
--------------
Analyzes the content of the holding area
``${``\ ```D`` <#var-D>`__\ ``}`` and splits the content into subsets
``${``\ :term:`D`\ ``}`` and splits the content into subsets
based on available packages and files. This task makes use of the
```PACKAGES`` <#var-PACKAGES>`__ and ```FILES`` <#var-FILES>`__
:term:`PACKAGES` and :term:`FILES`
variables.
The ``do_package`` task, in conjunction with the
```do_packagedata`` <#ref-tasks-packagedata>`__ task, also saves some
:ref:`ref-tasks-packagedata` task, also saves some
important package metadata. For additional information, see the
```PKGDESTWORK`` <#var-PKGDESTWORK>`__ variable and the "`Automatically
:term:`PKGDESTWORK` variable and the "`Automatically
Added Runtime
Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__"
section in the Yocto Project Overview and Concepts Manual.
@@ -234,7 +234,7 @@ section in the Yocto Project Overview and Concepts Manual.
-----------------
Runs QA checks on packaged files. For more information on these checks,
see the ```insane`` <#ref-classes-insane>`__ class.
see the :ref:`insane <ref-classes-insane>` class.
.. _ref-tasks-package_write_deb:
@@ -242,7 +242,7 @@ see the ```insane`` <#ref-classes-insane>`__ class.
------------------------
Creates Debian packages (i.e. ``*.deb`` files) and places them in the
``${``\ ```DEPLOY_DIR_DEB`` <#var-DEPLOY_DIR_DEB>`__\ ``}`` directory in
``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory in
the package feeds area. For more information, see the "`Package
Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section in
the Yocto Project Overview and Concepts Manual.
@@ -253,7 +253,7 @@ the Yocto Project Overview and Concepts Manual.
------------------------
Creates IPK packages (i.e. ``*.ipk`` files) and places them in the
``${``\ ```DEPLOY_DIR_IPK`` <#var-DEPLOY_DIR_IPK>`__\ ``}`` directory in
``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory in
the package feeds area. For more information, see the "`Package
Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section in
the Yocto Project Overview and Concepts Manual.
@@ -264,7 +264,7 @@ the Yocto Project Overview and Concepts Manual.
------------------------
Creates RPM packages (i.e. ``*.rpm`` files) and places them in the
``${``\ ```DEPLOY_DIR_RPM`` <#var-DEPLOY_DIR_RPM>`__\ ``}`` directory in
``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory in
the package feeds area. For more information, see the "`Package
Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section in
the Yocto Project Overview and Concepts Manual.
@@ -275,7 +275,7 @@ the Yocto Project Overview and Concepts Manual.
------------------------
Creates tarballs and places them in the
``${``\ ```DEPLOY_DIR_TAR`` <#var-DEPLOY_DIR_TAR>`__\ ``}`` directory in
``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory in
the package feeds area. For more information, see the "`Package
Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section in
the Yocto Project Overview and Concepts Manual.
@@ -286,8 +286,8 @@ the Yocto Project Overview and Concepts Manual.
------------------
Saves package metadata generated by the
```do_package`` <#ref-tasks-package>`__ task in
```PKGDATA_DIR`` <#var-PKGDATA_DIR>`__ to make it available globally.
:ref:`ref-tasks-package` task in
:term:`PKGDATA_DIR` to make it available globally.
.. _ref-tasks-patch:
@@ -297,7 +297,7 @@ Saves package metadata generated by the
Locates patch files and applies them to the source code.
After fetching and unpacking source files, the build system uses the
recipe's ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statements
recipe's :term:`SRC_URI` statements
to locate and apply patch files to the source code.
.. note::
@@ -375,7 +375,7 @@ information.
-----------------------
Stages (copies) a subset of the files installed by the
```do_install`` <#ref-tasks-install>`__ task into the appropriate
:ref:`ref-tasks-install` task into the appropriate
sysroot. For information on how to access these files from other
recipes, see the ```STAGING_DIR*`` <#var-STAGING_DIR_HOST>`__ variables.
Directories that would typically not be needed by other recipes at build
@@ -398,9 +398,9 @@ that if the task is re-executed, any previous output is removed (i.e.
Installs the files into the individual recipe specific sysroots (i.e.
``recipe-sysroot`` and ``recipe-sysroot-native`` under
``${``\ ```WORKDIR`` <#var-WORKDIR>`__\ ``}`` based upon the
dependencies specified by ```DEPENDS`` <#var-DEPENDS>`__). See the
"```staging`` <#ref-classes-staging>`__" class for more information.
``${``\ :term:`WORKDIR`\ ``}`` based upon the
dependencies specified by :term:`DEPENDS`). See the
":ref:`staging <ref-classes-staging>`" class for more information.
.. _ref-tasks-rm_work:
@@ -417,7 +417,7 @@ them. You can learn more by looking at the
-------------
Unpacks the source code into a working directory pointed to by
``${``\ ```WORKDIR`` <#var-WORKDIR>`__\ ``}``. The ```S`` <#var-S>`__
``${``\ :term:`WORKDIR`\ ``}``. The :term:`S`
variable also plays a role in where unpacked source files ultimately
reside. For more information on how source files are unpacked, see the
"`Source
@@ -459,7 +459,7 @@ default, the results are stored in ```$LOG_DIR`` <#var-LOG_DIR>`__ (e.g.
``do_checkuri``
---------------
Validates the ```SRC_URI`` <#var-SRC_URI>`__ value.
Validates the :term:`SRC_URI` value.
.. _ref-tasks-clean:
@@ -467,11 +467,11 @@ Validates the ```SRC_URI`` <#var-SRC_URI>`__ value.
------------
Removes all output files for a target from the
```do_unpack`` <#ref-tasks-unpack>`__ task forward (i.e. ``do_unpack``,
```do_configure`` <#ref-tasks-configure>`__,
```do_compile`` <#ref-tasks-compile>`__,
```do_install`` <#ref-tasks-install>`__, and
```do_package`` <#ref-tasks-package>`__).
:ref:`ref-tasks-unpack` task forward (i.e. ``do_unpack``,
:ref:`ref-tasks-configure`,
:ref:`ref-tasks-compile`,
:ref:`ref-tasks-install`, and
:ref:`ref-tasks-package`).
You can run this task using BitBake as follows: $ bitbake -c clean
recipe
@@ -481,7 +481,7 @@ Running this task does not remove the
Consequently, if no changes have been made and the recipe is rebuilt
after cleaning, output files are simply restored from the sstate cache.
If you want to remove the sstate cache files for the recipe, you need to
use the ```do_cleansstate`` <#ref-tasks-cleansstate>`__ task instead
use the :ref:`ref-tasks-cleansstate` task instead
(i.e. ``bitbake -c cleansstate`` recipe).
.. _ref-tasks-cleanall:
@@ -492,15 +492,15 @@ use the ```do_cleansstate`` <#ref-tasks-cleansstate>`__ task instead
Removes all output files, shared state
(`sstate <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__) cache, and
downloaded source files for a target (i.e. the contents of
```DL_DIR`` <#var-DL_DIR>`__). Essentially, the ``do_cleanall`` task is
identical to the ```do_cleansstate`` <#ref-tasks-cleansstate>`__ task
:term:`DL_DIR`). Essentially, the ``do_cleanall`` task is
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: $ bitbake -c cleanall
recipe
Typically, you would not normally use the ``cleanall`` task. Do so only
if you want to start fresh with the ```do_fetch`` <#ref-tasks-fetch>`__
if you want to start fresh with the :ref:`ref-tasks-fetch`
task.
.. _ref-tasks-cleansstate:
@@ -511,7 +511,7 @@ task.
Removes all output files and shared state
(`sstate <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__) cache for a
target. Essentially, the ``do_cleansstate`` task is identical to the
```do_clean`` <#ref-tasks-clean>`__ task with the added removal of
:ref:`ref-tasks-clean` task with the added removal of
shared state (`sstate <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__)
cache.
@@ -596,7 +596,7 @@ The following tasks are applicable to image recipes.
--------------
Creates a bootable live image. See the
```IMAGE_FSTYPES`` <#var-IMAGE_FSTYPES>`__ variable for additional
:term:`IMAGE_FSTYPES` variable for additional
information on live image types.
.. _ref-tasks-bundle_initramfs:
@@ -606,7 +606,7 @@ information on live image types.
Combines an initial RAM disk (initramfs) image and kernel together to
form a single image. The
```CONFIG_INITRAMFS_SOURCE`` <#var-CONFIG_INITRAMFS_SOURCE>`__ variable
:term:`CONFIG_INITRAMFS_SOURCE` variable
has some more information about these types of images.
.. _ref-tasks-rootfs:
@@ -638,7 +638,7 @@ section in the Yocto Project Development Tasks Manual.
Boots an image and performs runtime tests within the image immediately
after it has been built. This task is enabled when you set
```TESTIMAGE_AUTO`` <#var-TESTIMAGE_AUTO>`__ equal to "1".
:term:`TESTIMAGE_AUTO` equal to "1".
For information on automatically testing images, see the "`Performing
Automated Runtime
@@ -649,7 +649,7 @@ Kernel-Related Tasks
====================
The following tasks are applicable to kernel recipes. Some of these
tasks (e.g. the ```do_menuconfig`` <#ref-tasks-menuconfig>`__ task) are
tasks (e.g. the :ref:`ref-tasks-menuconfig` task) are
also applicable to recipes that use Linux kernel style configuration
such as the BusyBox recipe.
@@ -669,9 +669,9 @@ kernel consists of two steps: 1) the kernel (``vmlinux``) is built, and
When invoked by the user, this task creates a file containing the
differences between the original config as produced by
```do_kernel_configme`` <#ref-tasks-kernel_configme>`__ task and the
:ref:`ref-tasks-kernel_configme` task and the
changes made by the user with other methods (i.e. using
(```do_kernel_menuconfig`` <#ref-tasks-kernel_menuconfig>`__). Once the
(: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: $ bitbake linux-yocto -c diffconfig
@@ -696,7 +696,7 @@ kernel with the correct branches checked out.
-------------------------
Validates the configuration produced by the
```do_kernel_menuconfig`` <#ref-tasks-kernel_menuconfig>`__ task. The
:ref:`ref-tasks-kernel_menuconfig` task. The
``do_kernel_configcheck`` task produces warnings when a requested
configuration does not appear in the final ``.config`` file or when you
override a policy configuration in a hardware configuration fragment.
@@ -711,7 +711,7 @@ section in the Yocto Project Linux Kernel Development Manual.
``do_kernel_configme``
----------------------
After the kernel is patched by the ```do_patch`` <#ref-tasks-patch>`__
After the kernel is patched by the :ref:`ref-tasks-patch`
task, the ``do_kernel_configme`` task assembles and merges all the
kernel config fragments into a merged configuration that can then be
passed to the kernel configuration phase proper. This is also the time
@@ -746,12 +746,12 @@ information on this configuration tool.
----------------------
Collects all the features required for a given kernel build, whether the
features come from ```SRC_URI`` <#var-SRC_URI>`__ or from Git
features come from :term:`SRC_URI` or from Git
repositories. After collection, the ``do_kernel_metadata`` task
processes the features into a series of config fragments and patches,
which can then be applied by subsequent tasks such as
```do_patch`` <#ref-tasks-patch>`__ and
```do_kernel_configme`` <#ref-tasks-kernel_configme>`__.
:ref:`ref-tasks-patch` and
:ref:`ref-tasks-kernel_configme`.
.. _ref-tasks-menuconfig:
@@ -772,7 +772,7 @@ When invoked by the user, creates a defconfig file that can be used
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
```do_kernel_menuconfig`` <#ref-tasks-kernel_menuconfig>`__ task. You
:ref:`ref-tasks-kernel_menuconfig` task. You
can invoke the task using the following command: $ bitbake linux-yocto
-c savedefconfig
@@ -785,7 +785,7 @@ After the kernel has been compiled but before the kernel modules have
been compiled, this task copies files required for module builds and
which are generated from the kernel build into the shared work
directory. With these copies successfully copied, the
```do_compile_kernelmodules`` <#ref-tasks-compile_kernelmodules>`__ task
:ref:`ref-tasks-compile_kernelmodules` task
can successfully build the kernel modules in the next step of the build.
.. _ref-tasks-sizecheck:
@@ -795,7 +795,7 @@ can successfully build the kernel modules in the next step of the build.
After the kernel has been built, this task checks the size of the
stripped kernel image against
```KERNEL_IMAGE_MAXSIZE`` <#var-KERNEL_IMAGE_MAXSIZE>`__. If that
:term:`KERNEL_IMAGE_MAXSIZE`. If that
variable was set and the size of the stripped kernel exceeds that size,
the kernel build produces a warning to that effect.
@@ -816,9 +816,9 @@ 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
```SRCREV`` <#var-SRCREV>`__ variables actually exist on the specified
:term:`SRCREV` variables actually exist on the specified
branches. If these branches do not exist and
```AUTOREV`` <#var-AUTOREV>`__ is not being used, the
:term:`AUTOREV` is not being used, the
``do_validate_branches`` task fails during the build.
Miscellaneous Tasks
@@ -833,4 +833,4 @@ The following sections describe miscellaneous tasks.
A build stage that takes the source code and scans it on a remote
FOSSOLOGY server in order to produce an SPDX document. This task applies
only to the ```spdx`` <#ref-classes-spdx>`__ class.
only to the :ref:`spdx <ref-classes-spdx>` class.

16
documentation/ref-manual/ref-terms.rst
View File

@@ -113,7 +113,7 @@ universal, the list includes them just in case:
Files that provide for logic encapsulation and inheritance so that
commonly used patterns can be defined once and then easily used in
multiple recipes. For reference information on the Yocto Project classes,
see the "`Classes <#ref-classes>`__" chapter. Class files end with the
see the ":ref:`ref-manual/ref-classes:Classes`" chapter. Class files end with the
``.bbclass`` filename extension.
Configuration File
@@ -200,7 +200,7 @@ universal, the list includes them just in case:
Metadata
A key element of the Yocto Project is the Metadata that
is used to construct a Linux distribution and is contained in the
files that the `OpenEmbedded build system <#build-system-term>`__
files that the :term:`OpenEmbedded Build System`
parses when building an image. In general, Metadata includes recipes,
configuration files, and other information that refers to the build
instructions themselves, as well as the data used to control what
@@ -233,7 +233,7 @@ universal, the list includes them just in case:
OpenEmbedded Build System
The build system specific to the Yocto
Project. The OpenEmbedded build system is based on another project
known as "Poky", which uses `BitBake <#bitbake-term>`__ as the task
known as "Poky", which uses :term:`BitBake` as the task
executor. Throughout the Yocto Project documentation set, the
OpenEmbedded build system is sometimes referred to simply as "the
build system". If other build systems, such as a host or target build
@@ -262,8 +262,8 @@ universal, the list includes them just in case:
Another point worth noting is that historically within the Yocto
Project, recipes were referred to as packages - thus, the existence
of several BitBake variables that are seemingly mis-named, (e.g.
```PR`` <#var-PR>`__, ```PV`` <#var-PV>`__, and
```PE`` <#var-PE>`__).
:term:`PR`, :term:`PV`, and
:term:`PE`).
Package Groups
Arbitrary groups of software Recipes. You use
@@ -373,9 +373,9 @@ universal, the list includes them just in case:
Task
A unit of execution for BitBake (e.g.
```do_compile`` <#ref-tasks-compile>`__,
```do_fetch`` <#ref-tasks-fetch>`__,
```do_patch`` <#ref-tasks-patch>`__, and so forth).
:ref:`ref-tasks-compile`,
:ref:`ref-tasks-fetch`,
:ref:`ref-tasks-patch`, and so forth).
Toaster
A web interface to the Yocto Project's `OpenEmbedded Build

1336
documentation/ref-manual/ref-variables.rst
View File

File diff suppressed because it is too large Load Diff

4
documentation/ref-manual/resources.rst
View File

@@ -79,7 +79,7 @@ instructions:
mailing list about OpenEmbedded.
- ` <&OE_LISTS_URL;/listinfo/bitbake-devel>`__ - Discussion mailing
list about the `BitBake <#bitbake-term>`__ build tool.
list about the :term:`BitBake` build tool.
- ` <&YOCTO_LISTS_URL;/listinfo/poky>`__ - Discussion mailing list
about `Poky <#poky>`__.
@@ -179,7 +179,7 @@ Here is a list of resources you might find helpful:
- `Toaster User Manual <&YOCTO_DOCS_TOAST_URL;>`__\ *:* This manual
introduces and describes how to set up and use Toaster. Toaster is an
Application Programming Interface (API) and web-based interface to
the `OpenEmbedded Build System <#build-system-term>`__, which uses
the :term:`OpenEmbedded Build System`, which uses
BitBake, that reports build information.
- `FAQ <&YOCTO_WIKI_URL;/wiki/FAQ>`__\ *:* A list of commonly asked

6
documentation/sdk-manual/sdk-appendix-customizing-standard.rst
View File

@@ -11,9 +11,9 @@ Adding Individual Packages to the Standard SDK
When you build a standard SDK using the ``bitbake -c populate_sdk``, a
default set of packages is included in the resulting SDK. The
```TOOLCHAIN_HOST_TASK`` <&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_HOST_TASK>`__
:term:`TOOLCHAIN_HOST_TASK`
and
```TOOLCHAIN_TARGET_TASK`` <&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK>`__
:term:`TOOLCHAIN_TARGET_TASK`
variables control the set of packages adding to the SDK.
If you want to add individual packages to the toolchain that runs on the
@@ -28,7 +28,7 @@ Adding API Documentation to the Standard SDK
You can include API documentation as well as any other documentation
provided by recipes with the standard SDK by adding "api-documentation"
to the
```DISTRO_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES>`__
:term:`DISTRO_FEATURES`
variable: DISTRO_FEATURES_append = " api-documentation" Setting this
variable as shown here causes the OpenEmbedded build system to build the
documentation and then include it in the standard SDK.

50
documentation/sdk-manual/sdk-appendix-customizing.rst
View File

@@ -22,7 +22,7 @@ build system applies them against ``local.conf`` and ``auto.conf``:
host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__.
- Variables listed in
```SDK_LOCAL_CONF_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST>`__
:term:`SDK_LOCAL_CONF_BLACKLIST`
are excluded. These variables are not allowed through from the
OpenEmbedded build system configuration into the extensible SDK
configuration. Typically, these variables are specific to the machine
@@ -30,23 +30,23 @@ build system applies them against ``local.conf`` and ``auto.conf``:
of the extensible SDK configuration.
For a list of the variables excluded by default, see the
```SDK_LOCAL_CONF_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST>`__
:term:`SDK_LOCAL_CONF_BLACKLIST`
in the glossary of the Yocto Project Reference Manual.
- Variables listed in
```SDK_LOCAL_CONF_WHITELIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST>`__
:term:`SDK_LOCAL_CONF_WHITELIST`
are included. Including a variable in the value of
``SDK_LOCAL_CONF_WHITELIST`` overrides either of the previous two
filters. The default value is blank.
- Classes inherited globally with
```INHERIT`` <&YOCTO_DOCS_REF_URL;#var-INHERIT>`__ that are listed in
```SDK_INHERIT_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST>`__
:term:`INHERIT` that are listed in
:term:`SDK_INHERIT_BLACKLIST`
are disabled. Using ``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
```buildhistory`` <&YOCTO_DOCS_REF_URL;#ref-classes-buildhistory>`__
and ```icecc`` <&YOCTO_DOCS_REF_URL;#ref-classes-icecc>`__ classes.
:ref:`buildhistory <ref-classes-buildhistory>`
and :ref:`icecc <ref-classes-icecc>` classes.
Additionally, the contents of ``conf/sdk-extra.conf``, when present, are
appended to the end of ``conf/local.conf`` within the produced SDK,
@@ -63,10 +63,10 @@ However, some cases exist for which you might consider making
adjustments:
- If your SDK configuration inherits additional classes using the
```INHERIT`` <&YOCTO_DOCS_REF_URL;#var-INHERIT>`__ variable and you
:term:`INHERIT` variable and you
do not need or want those classes enabled in the SDK, you can
blacklist them by adding them to the
```SDK_INHERIT_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST>`__
:term:`SDK_INHERIT_BLACKLIST`
variable as described in the fourth bullet of the previous section.
.. note::
@@ -93,7 +93,7 @@ adjustments:
state cache) or ensuring the tasks are able to be produced quickly
from a task that is a shared state task, add the task name to the
value of
```SDK_RECRDEP_TASKS`` <&YOCTO_DOCS_REF_URL;#var-SDK_RECRDEP_TASKS>`__.
:term:`SDK_RECRDEP_TASKS`.
- 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
@@ -109,24 +109,24 @@ adjustments:
- If you want users of the SDK to be able to easily update the SDK, you
need to set the
```SDK_UPDATE_URL`` <&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL>`__
:term:`SDK_UPDATE_URL`
variable. For more information, see the "`Providing Updates to the
Extensible SDK After
Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__"
section.
- If you have adjusted the list of files and directories that appear in
```COREBASE`` <&YOCTO_DOCS_REF_URL;#var-COREBASE>`__ (other than
:term:`COREBASE` (other than
layers that are enabled through ``bblayers.conf``), then you must
list these files in
```COREBASE_FILES`` <&YOCTO_DOCS_REF_URL;#var-COREBASE_FILES>`__ so
:term:`COREBASE_FILES` so
that the files are copied into the SDK.
- If your OpenEmbedded build system setup uses a different environment
setup script other than
````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__, then you must
set
```OE_INIT_ENV_SCRIPT`` <&YOCTO_DOCS_REF_URL;#var-OE_INIT_ENV_SCRIPT>`__
:term:`OE_INIT_ENV_SCRIPT`
to point to the environment setup script you use.
.. note::
@@ -139,15 +139,15 @@ Changing the Extensible SDK Installer Title
===========================================
You can change the displayed title for the SDK installer by setting the
```SDK_TITLE`` <&YOCTO_DOCS_REF_URL;#var-SDK_TITLE>`__ variable and then
:term:`SDK_TITLE` variable and then
rebuilding the the SDK installer. For information on how to build an SDK
installer, see the "`Building an SDK
Installer <#sdk-building-an-sdk-installer>`__" section.
By default, this title is derived from
```DISTRO_NAME`` <&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME>`__ when it is
:term:`DISTRO_NAME` when it is
set. If the ``DISTRO_NAME`` variable is not set, the title is derived
from the ```DISTRO`` <&YOCTO_DOCS_REF_URL;#var-DISTRO>`__ variable.
from the :term:`DISTRO` variable.
The
```populate_sdk_base`` <&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*>`__
@@ -181,7 +181,7 @@ the installed SDKs to update the installed SDKs by using the
to host the directory. This directory must contain the published SDK.
2. Set the
```SDK_UPDATE_URL`` <&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL>`__
:term:`SDK_UPDATE_URL`
variable to point to the corresponding HTTP or HTTPS URL. Setting
this variable causes any SDK built to default to that URL and thus,
the user does not have to pass the URL to the ``devtool sdk-update``
@@ -209,8 +209,8 @@ Changing the Default SDK Installation Directory
When you build the installer for the Extensible SDK, the default
installation directory for the SDK is based on the
```DISTRO`` <&YOCTO_DOCS_REF_URL;#var-DISTRO>`__ and
```SDKEXTPATH`` <&YOCTO_DOCS_REF_URL;#var-SDKEXTPATH>`__ variables from
:term:`DISTRO` and
:term:`SDKEXTPATH` variables from
within the
```populate_sdk_base`` <&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*>`__
class as follows: SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" You can
@@ -248,7 +248,7 @@ source, you need to do a number of things:
- Build the "world" target and set
``EXCLUDE_FROM_WORLD_pn-``\ recipename for the recipes you do not
want built. See the
```EXCLUDE_FROM_WORLD`` <&YOCTO_DOCS_REF_URL;#var-EXCLUDE_FROM_WORLD>`__
:term:`EXCLUDE_FROM_WORLD`
variable for additional information.
2. Expose the ``sstate-cache`` directory produced by the build.
@@ -259,7 +259,7 @@ 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
```SSTATE_MIRRORS`` <&YOCTO_DOCS_REF_URL;#var-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:
@@ -297,7 +297,7 @@ 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:
SDK_EXT_TYPE = "minimal" Setting
```SDK_EXT_TYPE`` <&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE>`__ to
:term:`SDK_EXT_TYPE` to
"minimal" produces an SDK installer that is around 35 Mbytes in size,
which downloads and installs quickly. You need to realize, though, that
the minimal installer does not install any libraries or tools out of the
@@ -315,7 +315,7 @@ results.
To facilitate this wider range of information, you would need to set the
following: SDK_INCLUDE_PKGDATA = "1" See the
```SDK_INCLUDE_PKGDATA`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA>`__
:term:`SDK_INCLUDE_PKGDATA`
variable for additional information.
Setting the ``SDK_INCLUDE_PKGDATA`` variable as shown causes the "world"
@@ -341,7 +341,7 @@ in most cases.
You can explicitly control whether or not to include the toolchain when
you build an SDK by setting the
```SDK_INCLUDE_TOOLCHAIN`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN>`__
: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,
excludes the toolchain. Also, it is helpful if you are building a small

8
documentation/sdk-manual/sdk-appendix-obtain.rst
View File

@@ -95,14 +95,14 @@ build the SDK installer. Follow these steps:
4. *Make Sure You Are Building an Installer for the Correct Machine:*
Check to be sure that your
```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__ variable in the
:term:`MACHINE` variable in the
``local.conf`` file in your Build Directory matches the architecture
for which you are building.
5. *Make Sure Your SDK Machine is Correctly Set:* If you are building a
toolchain designed to run on an architecture that differs from your
current development host machine (i.e. the build host), be sure that
the ```SDKMACHINE`` <&YOCTO_DOCS_REF_URL;#var-SDKMACHINE>`__ variable
the :term:`SDKMACHINE` variable
in the ``local.conf`` file in your Build Directory is correctly set.
.. note::
@@ -138,7 +138,7 @@ build the SDK installer. Follow these steps:
binaries. If you want to use the toolchain to build these types
of libraries, you need to be sure your SDK has the appropriate
static development libraries. Use the
```TOOLCHAIN_TARGET_TASK`` <&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK>`__
:term:`TOOLCHAIN_TARGET_TASK`
variable inside your ``local.conf`` file before building the
SDK installer. Doing so ensures that the eventual SDK
installation process installs the appropriate library packages
@@ -189,7 +189,7 @@ Follow these steps to extract the root filesystem:
filesystem image's profile: lsb, lsb-dev, lsb-sdk, minimal,
minimal-dev, minimal-initramfs, sato, sato-dev, sato-sdk,
sato-sdk-ptest. For information on these types of image profiles, see
the "`Images <&YOCTO_DOCS_REF_URL;#ref-images>`__" chapter in the
the ":ref:`ref-manual/ref-images:Images`" chapter in the
Yocto Project Reference Manual. arch is a string representing the
target architecture: beaglebone-yocto, beaglebone-yocto-lsb,
edgerouter, edgerouter-lsb, genericx86, genericx86-64,

64
documentation/sdk-manual/sdk-extensible.rst
View File

@@ -148,8 +148,8 @@ SDK environment now set up; additionally you may now run devtool to
perform development tasks. Run devtool --help for further details.
Running the setup script defines many environment variables needed in
order to use the SDK (e.g. ``PATH``,
```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__,
```LD`` <&YOCTO_DOCS_REF_URL;#var-LD>`__, and so forth). If you want to
:term:`CC`,
:term:`LD`, and so forth). If you want to
see all the environment variables the script exports, examine the
installation file itself.
@@ -215,7 +215,7 @@ Use ``devtool add`` to Add an Application
The ``devtool add`` command generates a new recipe based on existing
source code. This command takes advantage of the
`workspace <&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure>`__
:ref:`devtool-the-workspace-layer-structure`
layer that many ``devtool`` commands use. The command is flexible enough
to allow you to extract source code into both the workspace or a
separate local Git repository and to use existing code that does not
@@ -397,7 +397,7 @@ command:
The following command identifies the recipe and, by default,
extracts the source files: $ devtool modify recipe Once
``devtool``\ locates the recipe, ``devtool`` uses the recipe's
```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statements to
:term:`SRC_URI` statements to
locate the source code and any local patch files from other
developers.
@@ -569,7 +569,7 @@ counterparts.
The ``devtool upgrade`` command is flexible enough to allow you to
specify source code revision and versioning schemes, extract code into
or out of the ``devtool``
`workspace <&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure>`__,
:ref:`devtool-the-workspace-layer-structure`,
and work with any source file forms that the
`fetchers <&YOCTO_DOCS_BB_URL;#bb-fetchers>`__ support.
@@ -584,7 +584,7 @@ The following diagram shows the common development flow used with the
workspace.
- The source files for the new release exist in the same location
pointed to by ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__
pointed to by :term:`SRC_URI`
in the recipe (e.g. a tarball with the new version number in the
name, or as a different revision in the upstream Git repository).
@@ -594,7 +594,7 @@ The following diagram shows the common development flow used with the
use the newer version of the software: $ devtool upgrade -V version
recipe By default, the ``devtool upgrade`` command extracts source
code into the ``sources`` directory in the
`workspace <&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure>`__.
: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
@@ -773,7 +773,7 @@ Dependency Detection and Mapping
The ``devtool add`` command attempts to detect build-time dependencies
and map them to other recipes in the system. During this mapping, the
command fills in the names of those recipes as part of the
```DEPENDS`` <&YOCTO_DOCS_REF_URL;#var-DEPENDS>`__ variable within the
:term:`DEPENDS` variable within the
recipe. If a dependency cannot be mapped, ``devtool`` places a comment
in the recipe indicating such. The inability to map a dependency can
result from naming not being recognized or because the dependency simply
@@ -807,13 +807,13 @@ License Detection
The ``devtool add`` command attempts to determine if the software you
are adding is able to be distributed under a common, open-source
license. If so, the command sets the
```LICENSE`` <&YOCTO_DOCS_REF_URL;#var-LICENSE>`__ value accordingly.
: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.
The ``devtool add`` command also sets the
```LIC_FILES_CHKSUM`` <&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM>`__
:term:`LIC_FILES_CHKSUM`
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
@@ -842,7 +842,7 @@ open-source software. Unfortunately, Makefiles are often not written
with cross-compilation in mind. Thus, ``devtool add`` often cannot do
very much to ensure that these Makefiles build correctly. It is very
common, for example, to explicitly call ``gcc`` instead of using the
```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__ variable. Usually, in a
:term:`CC` variable. Usually, in a
cross-compilation environment, ``gcc`` is the compiler for the build
host and the cross-compiler is named something similar to
``arm-poky-linux-gnueabi-gcc`` and might require arguments (e.g. to
@@ -869,8 +869,8 @@ mind:
sets the default using the "?=" operator, or you can alternatively
force the value on the ``make`` command line. To force the value on
the command line, add the variable setting to
```EXTRA_OEMAKE`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE>`__ or
```PACKAGECONFIG_CONFARGS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS>`__
:term:`EXTRA_OEMAKE` or
:term:`PACKAGECONFIG_CONFARGS`
within the recipe. Here is an example using ``EXTRA_OEMAKE``:
EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" In the above example,
single quotes are used around the variable settings as the values are
@@ -951,7 +951,7 @@ repository or local source tree. To add modules this way, use
https://github.com/diversario/node-ssdp In this example, ``devtool``
fetches the specified Git repository, detects the code as Node.js code,
fetches dependencies using ``npm``, and sets
```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ accordingly.
:term:`SRC_URI` accordingly.
.. _sdk-working-with-recipes:
@@ -976,8 +976,8 @@ build progresses as follows:
For recipes in the workspace, fetching and unpacking is disabled as the
source tree has already been prepared and is persistent. Each of these
build steps is defined as a function (task), usually with a "do_" prefix
(e.g. ```do_fetch`` <&YOCTO_DOCS_REF_URL;#ref-tasks-fetch>`__,
```do_unpack`` <&YOCTO_DOCS_REF_URL;#ref-tasks-unpack>`__, and so
(e.g. :ref:`ref-tasks-fetch`,
:ref:`ref-tasks-unpack`, and so
forth). These functions are typically shell scripts but can instead be
written in Python.
@@ -986,7 +986,7 @@ 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
```base`` <&YOCTO_DOCS_REF_URL;#ref-classes-base>`__ class exists that
:ref:`base <ref-classes-base>` class exists that
is implicitly inherited by all recipes and provides the functionality
that most recipes typically need.
@@ -1011,9 +1011,9 @@ links created within the source tree:
useful:
- ``image/``: Contains all of the files installed during the
```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ stage.
:ref:`ref-tasks-install` stage.
Within a recipe, this directory is referred to by the expression
``${``\ ```D`` <&YOCTO_DOCS_REF_URL;#var-D>`__\ ``}``.
``${``\ :term:`D`\ ``}``.
- ``sysroot-destdir/``: Contains a subset of files installed within
``do_install`` that have been put into the shared sysroot. For
@@ -1035,16 +1035,16 @@ Setting Configure Arguments
If the software your recipe is building uses GNU autoconf, then a fixed
set of arguments is passed to it to enable cross-compilation plus any
extras specified by
```EXTRA_OECONF`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF>`__ or
```PACKAGECONFIG_CONFARGS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS>`__
: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
tools have similar variables (e.g.
```EXTRA_OECMAKE`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE>`__ for
CMake, ```EXTRA_OESCONS`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS>`__
: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
```PACKAGECONFIG_CONFARGS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS>`__
:term:`PACKAGECONFIG_CONFARGS`
variables to do so.
You can use the ``devtool configure-help`` command to help you set the
@@ -1071,8 +1071,8 @@ the build host.
Recipes should never write files directly into the sysroot. Instead,
files should be installed into standard locations during the
```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ task within
the ``${``\ ```D`` <&YOCTO_DOCS_REF_URL;#var-D>`__\ ``}`` directory. A
:ref:`ref-tasks-install` task within
the ``${``\ :term:`D`\ ``}`` directory. A
subset of these files automatically goes into the sysroot. The reason
for this limitation is that almost all files that go into the sysroot
are cataloged in manifests in order to ensure they can be removed later
@@ -1090,9 +1090,9 @@ the target device, it is important to understand packaging because the
contents of the image are expressed in terms of packages and not
recipes.
During the ```do_package`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package>`__
During the :ref:`ref-tasks-package`
task, files installed during the
```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ task are
:ref:`ref-tasks-install` task are
split into one main package, which is almost always named the same as
the recipe, and into several other packages. This separation exists
because not all of those installed files are useful in every image. For
@@ -1105,14 +1105,14 @@ package splitting as well.
After building a recipe, you can see where files have gone by looking in
the ``oe-workdir/packages-split`` directory, which contains a
subdirectory for each package. Apart from some advanced cases, the
```PACKAGES`` <&YOCTO_DOCS_REF_URL;#var-PACKAGES>`__ and
```FILES`` <&YOCTO_DOCS_REF_URL;#var-FILES>`__ variables controls
: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
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
``${``\ ```PN`` <&YOCTO_DOCS_REF_URL;#var-PN>`__\ ``}`` evaluates to the
``${``\ :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
@@ -1190,7 +1190,7 @@ manually "pull down" the updates into the installed SDK.
To update your installed SDK, use ``devtool`` as follows: $ devtool
sdk-update The previous command assumes your SDK provider has set the
default update URL for you through the
```SDK_UPDATE_URL`` <&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL>`__
:term:`SDK_UPDATE_URL`
variable as described in the "`Providing Updates to the Extensible SDK
After
Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__"

10
documentation/sdk-manual/sdk-intro.rst
View File

@@ -56,8 +56,8 @@ 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
```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__ and
```LD`` <&YOCTO_DOCS_REF_URL;#var-LD>`__. This reduces the space needed
:term:`CC` and
:term:`LD`. This reduces the space needed
for the tools. Understand, however, that every target still needs a
sysroot because those binaries are target-specific.
@@ -66,7 +66,7 @@ The SDK development environment consists of the following:
- The self-contained SDK, which is an architecture-specific
cross-toolchain and matching sysroots (target and native) all built
by the OpenEmbedded build system (e.g. the SDK). The toolchain and
sysroots are based on a `Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__
sysroots are based on a :term:`Metadata`
configuration and extensions, which allows you to cross-develop on
the host machine for the target hardware. Additionally, the
extensible SDK contains the ``devtool`` functionality.
@@ -107,9 +107,9 @@ when considering which to build:
+-----------------------+-----------------------+-----------------------+
\* Extensible SDK contains the toolchain and debugger if
```SDK_EXT_TYPE`` <&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE>`__ is "full"
:term:`SDK_EXT_TYPE` is "full"
or
```SDK_INCLUDE_TOOLCHAIN`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN>`__
:term:`SDK_INCLUDE_TOOLCHAIN`
is "1", which is the default. \*\* Sysroot is managed through the use of
``devtool``. Thus, it is less likely that you will corrupt your SDK
sysroot when you try to add additional libraries. \**\* You can add

4
documentation/sdk-manual/sdk-working-projects.rst
View File

@@ -79,7 +79,7 @@ project:
4. *Cross-Compile the Project:* This command compiles the project using
the cross-compiler. The
```CONFIGURE_FLAGS`` <&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS>`__
:term:`CONFIGURE_FLAGS`
environment variable provides the minimal arguments for GNU
configure: $ ./configure ${CONFIGURE_FLAGS} For an Autotools-based
project, you can use the cross-toolchain by just passing the
@@ -167,7 +167,7 @@ demonstrates these variable behaviors.
In a new shell environment variables are not established for the SDK
until you run the setup script. For example, the following commands show
a null value for the compiler variable (i.e.
```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__). $ echo ${CC} $ Running the
:term:`CC`). $ echo ${CC} $ 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

14
documentation/test-manual/test-manual-intro.rst
View File

@@ -95,8 +95,8 @@ The Autobuilder tests different elements of the project by using
thefollowing types of tests:
- *Build Testing:* Tests whether specific configurations build by
varying ```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__,
```DISTRO`` <&YOCTO_DOCS_REF_URL;#var-DISTRO>`__, other configuration
varying :term:`MACHINE`,
:term:`DISTRO`, other configuration
options, and the specific target images being built (or world). Used
to trigger builds of all the different test configurations on the
Autobuilder. Builds usually cover many different targets for
@@ -105,7 +105,7 @@ thefollowing types of tests:
Autobuilder tests literally hundreds of configurations and targets.
- *Sanity Checks During the Build Process:* Tests initiated through
the ```insane`` <&YOCTO_DOCS_REF_URL;#ref-classes-insane>`__
the :ref:`insane <ref-classes-insane>`
class. These checks ensure the output of the builds are correct.
For example, does the ELF architecture in the generated binaries
match the target system? ARM binaries would not work in a MIPS
@@ -133,9 +133,9 @@ thefollowing types of tests:
- *Image Testing:* Image tests initiated through the following command:
$ bitbake image -c testimage The tests utilize the
```testimage*`` <&YOCTO_DOCS_REF_URL;#ref-classes-testimage*>`__
:ref:`testimage* <ref-classes-testimage*>`
classes and the
```do_testimage`` <&YOCTO_DOCS_REF_URL;#ref-tasks-testimage>`__ task.
:ref:`ref-tasks-testimage` task.
- *Layer Testing:* The Autobuilder has the possibility to test whether
specific layers work with the test of the system. The layers tested
@@ -152,7 +152,7 @@ thefollowing types of tests:
- *SDK Testing:* Image tests initiated through the following command: $
bitbake image -c testsdk The tests utilize the
```testsdk`` <&YOCTO_DOCS_REF_URL;#ref-classes-testsdk>`__ class and
:ref:`testsdk <ref-classes-testsdk>` class and
the ``do_testsdk`` task.
- *Unit Testing:* Unit tests on various components of the system run
@@ -236,7 +236,7 @@ Tests map into the codebase as follows:
``meta/lib/oeqa/runtime/cases/``.
- You need to set the
```IMAGE_CLASSES`` <&YOCTO_DOCS_REF_URL;#var-IMAGE_CLASSES>`__
:term:`IMAGE_CLASSES`
variable as follows: IMAGE_CLASSES += "testimage"
- Run the tests using the following command form: $ bitbake image -c

2
documentation/toaster-manual/toaster-manual-reference.rst
View File

@@ -244,7 +244,7 @@ Defining the Default Distro and Other Values
This section defines the default distro value for new projects. By
default, it reserves the first Toaster Setting record "1". The following
demonstrates how to set the project default value for
```DISTRO`` <&YOCTO_DOCS_REF_URL;#var-DISTRO>`__: <!-- Set the project
:term:`DISTRO`: <!-- Set the project
default value for DISTRO --> <object model="orm.toastersetting" pk="1">
<field type="CharField" name="name">DEFCONF_DISTRO</field> <field
type="CharField" name="value">poky</field> </object> You can override

4
documentation/toaster-manual/toaster-manual-setup-and-use.rst
View File

@@ -132,7 +132,7 @@ superuser by following these steps:
command: $ export PATH=$PATH:$HOME/.local/bin
2. From the directory containing the Toaster database, which by default
is the `Build Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__,
is the :term:`Build Directory`,
invoke the ``createsuperuser`` command from ``manage.py``: $ cd
~/poky/build $ ../bitbake/lib/toaster/manage.py createsuperuser
@@ -482,7 +482,7 @@ For the ``bash`` case, version 4.3.30-r0 is built by default.
Unfortunately, Toaster as it exists, is not able to override the default
recipe version. If you would like to build bash 3.2.48, you need to set
the
```PREFERRED_VERSION`` <&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION>`__
:term:`PREFERRED_VERSION`
variable. You can do so from Toaster, using the "Add variable" form,
which is available in the "BitBake variables" page of the project
configuration section as shown in the following screen: