mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-05-09 17:39:31 +00:00
Code Issues 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
documentation/ref-manual/faq.rst
+8 -8
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
documentation/ref-manual/migration.rst
+254 -254
View File
File diff suppressed because it is too large Load Diff
documentation/ref-manual/ref-classes.rst
+258 -258
View File
File diff suppressed because it is too large Load Diff
documentation/ref-manual/ref-devtool-reference.rst
+5 -5
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.
documentation/ref-manual/ref-features.rst
+15 -15
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:
documentation/ref-manual/ref-images.rst
+1 -1
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
documentation/ref-manual/ref-kickstart.rst
+1 -1
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.
documentation/ref-manual/ref-qa-checks.rst
+66 -66
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::
documentation/ref-manual/ref-release-process.rst
+5 -5
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
documentation/ref-manual/ref-structure.rst
+29 -29
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
documentation/ref-manual/ref-tasks.rst
+63 -63
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.
documentation/ref-manual/ref-terms.rst
+8 -8
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
documentation/ref-manual/ref-variables.rst
+668 -668
View File
File diff suppressed because it is too large Load Diff
documentation/ref-manual/resources.rst
+2 -2
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