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

sphinx: ref-manual links fixes and many other cleanups to import

Browse Source 
(From yocto-docs rev: d079e418d5a81610e1f06a7a6ca45dd040c1402e)

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Richard Purdie
2020-09-14 22:48:44 +02:00
parent d313d972bf
commit 292598164a
16 changed files with 4883 additions and 3436 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -4,9 +4,9 @@
FAQ
***
**Q:** How does Poky differ from `OpenEmbedded <&OE_HOME_URL;>`__?
**Q:** How does Poky differ from `OpenEmbedded <http://www.openembedded.org/>`__?
**A:** The term "`Poky <#>`__" refers to the specific reference build
**A:** The term ``Poky`` refers to the specific reference build
system that the Yocto Project provides. Poky is based on
:term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the
generic term used here for the build system is the "OpenEmbedded build
@@ -44,11 +44,10 @@ steps on how to update your build tools.
**A:** Support for an additional board is added by creating a Board
Support Package (BSP) layer for it. For more information on how to
create a BSP layer, see the "`Understanding and Creating
Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__"
section in the Yocto Project Development Tasks Manual and the `Yocto
Project Board Support Package (BSP) Developer's
Guide <&YOCTO_DOCS_BSP_URL;>`__.
create a BSP layer, see the
":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
section in the Yocto Project Development Tasks Manual and the
:doc:`../bsp-guide/bsp-guide`.
Usually, if the board is not completely exotic, adding support in the
Yocto Project is fairly straightforward.
@@ -73,8 +72,8 @@ device.
**Q:** How do I add my package to the Yocto Project?
**A:** To add a package, you need to create a BitBake recipe. For
information on how to create a BitBake recipe, see the "`Writing a New
Recipe <&YOCTO_DOCS_DEV_URL;#new-recipe-writing-a-new-recipe>`__"
information on how to create a BitBake recipe, see the
":ref:`dev-manual/dev-manual-common-tasks:writing a new recipe`"
section in the Yocto Project Development Tasks Manual.
**Q:** Do I have to reflash my entire board with a new Yocto Project
@@ -126,12 +125,18 @@ file.
Following is the applicable code for setting various proxy types in the
``.wgetrc`` file. By default, these settings are disabled with comments.
To use them, remove the comments: # You can set the default proxies for
Wget to use for http, https, and ftp. # They will override the value in
the environment. #https_proxy = http://proxy.yoyodyne.com:18023/
#http_proxy = http://proxy.yoyodyne.com:18023/ #ftp_proxy =
http://proxy.yoyodyne.com:18023/ # If you do not want to use proxy at
all, set this to off. #use_proxy = on The Yocto Project also includes a
To use them, remove the comments: ::
# You can set the default proxies for Wget to use for http, https, and ftp.
# They will override the value in the environment.
#https_proxy = http://proxy.yoyodyne.com:18023/
#http_proxy = http://proxy.yoyodyne.com:18023/
#ftp_proxy = http://proxy.yoyodyne.com:18023/
# If you do not want to use proxy at all, set this to off.
#use_proxy = on
The Yocto Project also includes a
``meta-poky/conf/site.conf.sample`` file that shows how to configure CVS
and Git proxy servers if needed. For more information on setting up
various proxy types and configuring proxy servers, see the
@@ -167,8 +172,12 @@ always been traced back to hardware or virtualization issues.
**A:** If you get an error message that indicates GNU ``libiconv`` is
not in use but ``iconv.h`` has been included from ``libiconv``, you need
to check to see if you have a previously installed version of the header
file in ``/usr/local/include``. #error GNU libiconv not in use but
included iconv.h is from libiconv If you find a previously installed
file in ``/usr/local/include``.
::
#error GNU libiconv not in use but included iconv.h is from libiconv
If you find a previously installed
file, you should either uninstall it or temporarily rename it and try
the build again.
@@ -189,20 +198,21 @@ and also any configuration information about how that package was
configured and built.
You can find more information on licensing in the
"`Licensing <&YOCTO_DOCS_OM_URL;#licensing>`__" section in the Yocto
Project Overview and Concepts Manual and also in the "`Maintaining Open
Source License Compliance During Your Product's
Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__"
":ref:`overview-manual/overview-manual-development-environment:licensing`"
section in the Yocto
Project Overview and Concepts Manual and also in the
":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
section in the Yocto Project Development Tasks Manual.
**Q:** How do I disable the cursor on my touchscreen device?
**A:** You need to create a form factor file as described in the
"`Miscellaneous BSP-Specific Recipe
Files <&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes>`__" section in
":ref:`bsp-filelayout-misc-recipes`" section in
the Yocto Project Board Support Packages (BSP) Developer's Guide. Set
the ``HAVE_TOUCHSCREEN`` variable equal to one as follows:
HAVE_TOUCHSCREEN=1
::
HAVE_TOUCHSCREEN=1
**Q:** How do I make sure connected network interfaces are brought up by
default?
@@ -210,14 +220,14 @@ default?
**A:** The default interfaces file provided by the netbase recipe does
not automatically bring up network interfaces. Therefore, you will need
to add a BSP-specific netbase that includes an interfaces file. See the
"`Miscellaneous BSP-Specific Recipe
Files <&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes>`__" section in
":ref:`bsp-filelayout-misc-recipes`" section in
the Yocto Project Board Support Packages (BSP) Developer's Guide for
information on creating these types of miscellaneous recipe files.
For example, add the following files to your layer:
meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
For example, add the following files to your layer: ::
meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
**Q:** How do I create images with more free space?
@@ -260,7 +270,7 @@ controls which ``tcmode-*.inc`` file to include from the
The default value of ``TCMODE`` is "default", which tells the
OpenEmbedded build system to use its internally built toolchain (i.e.
``tcmode-default.inc``). However, other patterns are accepted. In
particular, "external-*" refers to external toolchains. One example is
particular, "external-\*" refers to external toolchains. One example is
the Sourcery G++ Toolchain. The support for this toolchain resides in
the separate ``meta-sourcery`` layer at
http://github.com/MentorEmbedded/meta-sourcery/.
@@ -290,11 +300,13 @@ fail.
As an example, you could add a specific server for the build system to
attempt before any others by adding something like the following to the
``local.conf`` configuration file: PREMIRRORS_prepend = "\\ git://.*/.\*
http://www.yoctoproject.org/sources/ \\n \\ ftp://.*/.\*
http://www.yoctoproject.org/sources/ \\n \\ http://.*/.\*
http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\*
http://www.yoctoproject.org/sources/ \\n"
``local.conf`` configuration file: ::
PREMIRRORS_prepend = "\
git://.*/.* http://www.yoctoproject.org/sources/ \n \
ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
http://.*/.* http://www.yoctoproject.org/sources/ \n \
https://.*/.* http://www.yoctoproject.org/sources/ \n"
These changes cause the build system to intercept Git, FTP, HTTP, and
HTTPS requests and direct them to the ``http://`` sources mirror. You
@@ -302,25 +314,43 @@ can use ``file://`` URLs to point to local directories or network shares
as well.
Aside from the previous technique, these options also exist:
BB_NO_NETWORK = "1" This statement tells BitBake to issue an error
::
BB_NO_NETWORK = "1"
This statement tells BitBake to issue an error
instead of trying to access the Internet. This technique is useful if
you want to ensure code builds only from local sources.
Here is another technique: BB_FETCH_PREMIRRORONLY = "1" This statement
Here is another technique:
::
BB_FETCH_PREMIRRORONLY = "1"
This statement
limits the build system to pulling source from the ``PREMIRRORS`` only.
Again, this technique is useful for reproducing builds.
Here is another technique: BB_GENERATE_MIRROR_TARBALLS = "1" This
Here is another technique:
::
BB_GENERATE_MIRROR_TARBALLS = "1"
This
statement tells the build system to generate mirror tarballs. This
technique is useful if you want to create a mirror server. If not,
however, the technique can simply waste time during the build.
Finally, consider an example where you are behind an HTTP-only firewall.
You could make the following changes to the ``local.conf`` configuration
file as long as the ``PREMIRRORS`` server is current: PREMIRRORS_prepend
= "\\ ftp://.*/.\* http://www.yoctoproject.org/sources/ \\n \\
http://.*/.\* http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\*
http://www.yoctoproject.org/sources/ \\n" BB_FETCH_PREMIRRORONLY = "1"
file as long as the ``PREMIRRORS`` server is current: ::
PREMIRRORS_prepend = "\
ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
http://.*/.* http://www.yoctoproject.org/sources/ \n \
https://.*/.* http://www.yoctoproject.org/sources/ \n"
BB_FETCH_PREMIRRORONLY = "1"
These changes would cause the build system to successfully fetch source
over HTTP and any network accesses to anything other than the
``PREMIRRORS`` would fail.
@@ -384,18 +414,21 @@ that program is never installed directly to the build machine's root
file system. Consequently, the build system uses paths within the Build
Directory for ``DESTDIR``, ``bindir`` and related variables. To better
understand this, consider the following two paths where the first is
relatively normal and the second is not:
relatively normal and the second is not: ::
/home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
1.2.8-r0/sysroot-destdir/usr/bin
/home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
build/tmp/sysroots/x86_64-linux/usr/bin
.. note::
Due to these lengthy examples, the paths are artificially broken
across lines for readability.
/home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
1.2.8-r0/sysroot-destdir/usr/bin
/home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
build/tmp/sysroots/x86_64-linux/usr/bin Even if the paths look unusual,
Even if the paths look unusual,
they both are correct - the first for a target and the second for a
native recipe. These paths are a consequence of the ``DESTDIR``
mechanism and while they appear strange, they are correct and in

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

File diff suppressed because it is too large Load Diff

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

@@ -47,7 +47,7 @@ splitting out of debug symbols during packaging).
even if the recipes do not produce architecture-specific output.
Configuring such recipes for all architectures causes the
```do_package_write_*`` <#ref-tasks-package_write_deb>`__ tasks to
```do_package_write_*`` tasks to
have different signatures for the machines with different tunings.
Additionally, unnecessary rebuilds occur every time an image for a
different ``MACHINE`` is built even when the recipe never changes.
@@ -67,9 +67,8 @@ inherit the ``allarch`` class.
The ``archiver`` class supports releasing source code and other
materials with the binaries.
For more details on the source archiver, see the "`Maintaining Open
Source License Compliance During Your Product's
Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__"
For more details on the source archiver, see the
":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
section in the Yocto Project Development Tasks Manual. You can also see
the :term:`ARCHIVER_MODE` variable for information
about the variable flags (varflags) that help control archive creation.
@@ -86,8 +85,8 @@ standardization. This class defines a set of tasks (e.g. ``configure``,
``compile`` and so forth) that work for all Autotooled packages. It
should usually be enough to define a few standard variables and then
simply ``inherit autotools``. These classes can also work with software
that emulates Autotools. For more information, see the "`Autotooled
Package <&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package>`__" section
that emulates Autotools. For more information, see the
":ref:`new-recipe-autotooled-package`" section
in the Yocto Project Development Tasks Manual.
By default, the ``autotools*`` classes use out-of-tree builds (i.e.
@@ -177,7 +176,7 @@ example use for this class.
::
SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}"
See the "
Fetchers
@@ -229,8 +228,10 @@ value as a variable flag (varflag) and provide a reason, which is
reported, if the package is requested to be built as the value. For
example, if you want to blacklist a recipe called "exoticware", you add
the following to your ``local.conf`` or distribution configuration:
INHERIT += "blacklist" PNBLACKLIST[exoticware] = "Not supported by our
organization."
::
INHERIT += "blacklist"
PNBLACKLIST[exoticware] = "Not supported by our organization."
.. _ref-classes-buildhistory:
@@ -240,8 +241,8 @@ organization."
The ``buildhistory`` class records a history of build output metadata,
which can be used to detect possible regressions as well as used for
analysis of the build output. For more information on using Build
History, see the "`Maintaining Build Output
Quality <&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality>`__"
History, see the
":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`"
section in the Yocto Project Development Tasks Manual.
.. _ref-classes-buildstats:
@@ -411,8 +412,7 @@ cross-compilation tools.
The ``cross-canadian`` class provides support for the recipes that build
the Canadian Cross-compilation tools for SDKs. See the
"`Cross-Development Toolchain
Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__"
":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`"
section in the Yocto Project Overview and Concepts Manual for more
discussion on these cross-compilation tools.
@@ -423,8 +423,7 @@ discussion on these cross-compilation tools.
The ``crosssdk`` class provides support for the recipes that build the
cross-compilation tools used for building SDKs. See the
"`Cross-Development Toolchain
Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__"
":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`"
section in the Yocto Project Overview and Concepts Manual for more
discussion on these cross-compilation tools.
@@ -465,8 +464,7 @@ staging the files from ``DEPLOYDIR`` to ``DEPLOY_DIR_IMAGE``.
====================
The ``devshell`` class adds the ``do_devshell`` task. Distribution
policy dictates whether to include this class. See the "`Using a
Development Shell <&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell>`__"
policy dictates whether to include this class. See the ":ref:`platdev-appdev-devshell`"
section in the Yocto Project Development Tasks Manual for more
information about using ``devshell``.
@@ -478,16 +476,26 @@ information about using ``devshell``.
The ``devupstream`` class uses
:term:`BBCLASSEXTEND` to add a variant of the
recipe that fetches from an alternative URI (e.g. Git) instead of a
tarball. Following is an example: BBCLASSEXTEND = "devupstream:target"
SRC_URI_class-devupstream = "git://git.example.com/example"
SRCREV_class-devupstream = "abcd1234" Adding the above statements to
your recipe creates a variant that has
tarball. Following is an example:
::
BBCLASSEXTEND = "devupstream:target"
SRC_URI_class-devupstream = "git://git.example.com/example"
SRCREV_class-devupstream = "abcd1234"
Adding the above statements to your recipe creates a variant that has
:term:`DEFAULT_PREFERENCE` set to "-1".
Consequently, you need to select the variant of the recipe to use it.
Any development-specific adjustments can be done by using the
``class-devupstream`` override. Here is an example:
DEPENDS_append_class-devupstream = " gperf-native"
do_configure_prepend_class-devupstream() { touch ${S}/README } The class
::
DEPENDS_append_class-devupstream = " gperf-native"
do_configure_prepend_class-devupstream() {
touch ${S}/README
}
The class
currently only supports creating a development variant of the target
recipe, not ``native`` or ``nativesdk`` variants.
@@ -587,15 +595,19 @@ that use the :term:`B` variable to point to the directory in
which the OpenEmbedded build system places the generated objects built
from the recipes. By default, the ``B`` directory is set to the
following, which is separate from the source directory (``S``):
${WORKDIR}/${BPN}/{PV}/ See these variables for more information:
::
${WORKDIR}/${BPN}/{PV}/
See these variables for more information:
:term:`WORKDIR`, :term:`BPN`, and
:term:`PV`,
For more information on the ``externalsrc`` class, see the comments in
``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`.
For information on how to use the
``externalsrc`` class, see the "`Building Software from an External
Source <&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source>`__"
``externalsrc`` class, see the
":ref:`dev-manual/dev-manual-common-tasks:building software from an external source`"
section in the Yocto Project Development Tasks Manual.
.. _ref-classes-extrausers:
@@ -619,15 +631,36 @@ be performed using the
useradd
class to add user and group configuration to a specific recipe.
Here is an example that uses this class in an image recipe: inherit
extrausers EXTRA_USERS_PARAMS = "\\ useradd -p '' tester; \\ groupadd
developers; \\ userdel nobody; \\ groupdel -g video; \\ groupmod -g 1020
developers; \\ usermod -s /bin/sh tester; \\ " Here is an example that
adds two users named "tester-jim" and "tester-sue" and assigns
passwords: inherit extrausers EXTRA_USERS_PARAMS = "\\ useradd -P
tester01 tester-jim; \\ useradd -P tester01 tester-sue; \\ " Finally,
here is an example that sets the root password to "1876*18": inherit
extrausers EXTRA_USERS_PARAMS = "\\ usermod -P 1876*18 root; \\ "
Here is an example that uses this class in an image recipe:
::
inherit extrausers
EXTRA_USERS_PARAMS = "\
useradd -p '' tester; \
groupadd developers; \
userdel nobody; \
groupdel -g video; \
groupmod -g 1020 developers; \
usermod -s /bin/sh tester; \
"
Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns
passwords:
::
inherit extrausers
EXTRA_USERS_PARAMS = "\
useradd -P tester01 tester-jim; \
useradd -P tester01 tester-sue; \
"
Finally, here is an example that sets the root password to "1876*18":
::
inherit extrausers
EXTRA_USERS_PARAMS = "\
usermod -P 1876*18 root; \
"
.. _ref-classes-fontcache:
@@ -837,8 +870,7 @@ provided by the recipe ``icecc-create-env-native.bb``.
.. note::
This script is a modified version and not the one that comes with
icecc
.
icecc.
If you do not want the Icecream distributed compile support to apply to
specific recipes or classes, you can effectively "blacklist" them by
@@ -863,10 +895,18 @@ At the distribution level, you can inherit the ``icecc`` class to be
sure that all builders start with the same sstate signatures. After
inheriting the class, you can then disable the feature by setting the
:term:`ICECC_DISABLED` variable to "1" as follows:
INHERIT_DISTRO_append = " icecc" ICECC_DISABLED ??= "1" This practice
::
INHERIT_DISTRO_append = " icecc"
ICECC_DISABLED ??= "1"
This practice
makes sure everyone is using the same signatures but also requires
individuals that do want to use Icecream to enable the feature
individually as follows in your ``local.conf`` file: ICECC_DISABLED = ""
individually as follows in your ``local.conf`` file:
::
ICECC_DISABLED = ""
.. _ref-classes-image:
@@ -884,11 +924,11 @@ then one or more image files are created.
- The ``IMAGE_INSTALL`` variable controls the list of packages to
install into the image.
For information on customizing images, see the "`Customizing
Images <&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage>`__" section
For information on customizing images, see the
":ref:`usingpoky-extend-customimage`" section
in the Yocto Project Development Tasks Manual. For information on how
images are created, see the
"`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__" section in the
":ref:`images-dev-environment`" section in the
Yocto Project Overview and Concpets Manual.
.. _ref-classes-image-buildinfo:
@@ -912,19 +952,19 @@ types.
By default, the :ref:`image <ref-classes-image>` class automatically
enables the ``image_types`` class. The ``image`` class uses the
``IMGCLASSES`` variable as follows: IMGCLASSES =
"rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}" IMGCLASSES +=
"${@['populate_sdk_base', 'populate_sdk_ext']['linux' in
d.getVar("SDK_OS")]}" IMGCLASSES +=
"${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg',
'image-live', '', d)}" IMGCLASSES +=
"${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container',
'', d)}" IMGCLASSES += "image_types_wic" IMGCLASSES +=
"rootfs-postcommands" IMGCLASSES += "image-postinst-intercepts" inherit
${IMGCLASSES}
``IMGCLASSES`` variable as follows:
::
The ``image_types`` class also handles conversion and compression of
images.
IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}"
IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}"
IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}"
IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}"
IMGCLASSES += "image_types_wic"
IMGCLASSES += "rootfs-postcommands"
IMGCLASSES += "image-postinst-intercepts"
inherit ${IMGCLASSES}
The ``image_types`` class also handles conversion and compression of images.
.. note::
@@ -957,7 +997,9 @@ the size of libraries contained in the image.
By default, the class is enabled in the ``local.conf.template`` using
the :term:`USER_CLASSES` variable as follows:
USER_CLASSES ?= "buildstats image-mklibs image-prelink"
::
USER_CLASSES ?= "buildstats image-mklibs image-prelink"
.. _ref-classes-image-prelink:
@@ -971,7 +1013,9 @@ time.
By default, the class is enabled in the ``local.conf.template`` using
the :term:`USER_CLASSES` variable as follows:
USER_CLASSES ?= "buildstats image-mklibs image-prelink"
::
USER_CLASSES ?= "buildstats image-mklibs image-prelink"
.. _ref-classes-insane:
@@ -1000,32 +1044,36 @@ should use :term:`INSANE_SKIP`. For example, to skip
the check for symbolic link ``.so`` files in the main package of a
recipe, add the following to the recipe. You need to realize that the
package name override, in this example ``${PN}``, must be used:
INSANE_SKIP_${PN} += "dev-so" Please keep in mind that the QA checks
::
INSANE_SKIP_${PN} += "dev-so"
Please keep in mind that the QA checks
exist in order to detect real or potential problems in the packaged
output. So exercise caution when disabling these checks.
The following list shows the tests you can list with the ``WARN_QA`` and
``ERROR_QA`` variables:
- *``already-stripped:``* Checks that produced binaries have not
- ``already-stripped:`` Checks that produced binaries have not
already been stripped prior to the build system extracting debug
symbols. It is common for upstream software projects to default to
stripping debug symbols for output binaries. In order for debugging
to work on the target using ``-dbg`` packages, this stripping must be
disabled.
- *``arch:``* Checks the Executable and Linkable Format (ELF) type, bit
- ``arch:`` Checks the Executable and Linkable Format (ELF) type, bit
size, and endianness of any binaries to ensure they match the target
architecture. This test fails if any binaries do not match the type
since there would be an incompatibility. The test could indicate that
the wrong compiler or compiler options have been used. Sometimes
software, like bootloaders, might need to bypass this check.
- *``buildpaths:``* Checks for paths to locations on the build host
- ``buildpaths:`` Checks for paths to locations on the build host
inside the output files. Currently, this test triggers too many false
positives and thus is not normally enabled.
- *``build-deps:``* Determines if a build-time dependency that is
- ``build-deps:`` Determines if a build-time dependency that is
specified through :term:`DEPENDS`, explicit
:term:`RDEPENDS`, or task-level dependencies exists
to match any runtime dependency. This determination is particularly
@@ -1045,20 +1093,20 @@ The following list shows the tests you can list with the ``WARN_QA`` and
``initscripts`` recipe is actually built and thus the
``initscripts-functions`` package is made available.
- *``compile-host-path:``* Checks the
- ``compile-host-path:`` Checks the
:ref:`ref-tasks-compile` log for indications that
paths to locations on the build host were used. Using such paths
might result in host contamination of the build output.
- *``debug-deps:``* Checks that all packages except ``-dbg`` packages
- ``debug-deps:`` Checks that all packages except ``-dbg`` packages
do not depend on ``-dbg`` packages, which would cause a packaging
bug.
- *``debug-files:``* Checks for ``.debug`` directories in anything but
- ``debug-files:`` Checks for ``.debug`` directories in anything but
the ``-dbg`` package. The debug files should all be in the ``-dbg``
package. Thus, anything packaged elsewhere is incorrect packaging.
- *``dep-cmp:``* Checks for invalid version comparison statements in
- ``dep-cmp:`` Checks for invalid version comparison statements in
runtime dependency relationships between packages (i.e. in
:term:`RDEPENDS`,
:term:`RRECOMMENDS`,
@@ -1069,22 +1117,22 @@ The following list shows the tests you can list with the ``WARN_QA`` and
comparisons might trigger failures or undesirable behavior when
passed to the package manager.
- *``desktop:``* Runs the ``desktop-file-validate`` program against any
- ``desktop:`` Runs the ``desktop-file-validate`` program against any
``.desktop`` files to validate their contents against the
specification for ``.desktop`` files.
- *``dev-deps:``* Checks that all packages except ``-dev`` or
- ``dev-deps:`` Checks that all packages except ``-dev`` or
``-staticdev`` packages do not depend on ``-dev`` packages, which
would be a packaging bug.
- *``dev-so:``* Checks that the ``.so`` symbolic links are in the
- ``dev-so:`` Checks that the ``.so`` symbolic links are in the
``-dev`` package and not in any of the other packages. In general,
these symlinks are only useful for development purposes. Thus, the
``-dev`` package is the correct location for them. Some very rare
cases do exist for dynamically loaded modules where these symlinks
are needed instead in the main package.
- *``file-rdeps:``* Checks that file-level dependencies identified by
- ``file-rdeps:`` Checks that file-level dependencies identified by
the OpenEmbedded build system at packaging time are satisfied. For
example, a shell script might start with the line ``#!/bin/bash``.
This line would translate to a file dependency on ``/bin/bash``. Of
@@ -1097,10 +1145,10 @@ The following list shows the tests you can list with the ``WARN_QA`` and
:term:`RDEPENDS` exist to handle any file-level
dependency detected in packaged files.
- *``files-invalid:``* Checks for :term:`FILES` variable
- ``files-invalid:`` Checks for :term:`FILES` variable
values that contain "//", which is invalid.
- *``host-user-contaminated:``* Checks that no package produced by the
- ``host-user-contaminated:`` Checks that no package produced by the
recipe contains any files outside of ``/home`` with a user or group
ID that matches the user running BitBake. A match usually indicates
that the files are being installed with an incorrect UID/GID, since
@@ -1108,16 +1156,16 @@ The following list shows the tests you can list with the ``WARN_QA`` and
see the section describing the
:ref:`ref-tasks-install` task.
- *``incompatible-license:``* Report when packages are excluded from
- ``incompatible-license:`` Report when packages are excluded from
being created due to being marked with a license that is in
:term:`INCOMPATIBLE_LICENSE`.
- *``install-host-path:``* Checks the
- ``install-host-path:`` Checks the
:ref:`ref-tasks-install` log for indications that
paths to locations on the build host were used. Using such paths
might result in host contamination of the build output.
- *``installed-vs-shipped:``* Reports when files have been installed
- ``installed-vs-shipped:`` Reports when files have been installed
within ``do_install`` but have not been included in any package by
way of the :term:`FILES` variable. Files that do not
appear in any package cannot be present in an image later on in the
@@ -1125,67 +1173,69 @@ The following list shows the tests you can list with the ``WARN_QA`` and
installed at all. These files can be deleted at the end of
``do_install`` if the files are not needed in any package.
- *``invalid-chars:``* Checks that the recipe metadata variables
- ``invalid-chars:`` Checks that the recipe metadata variables
:term:`DESCRIPTION`,
:term:`SUMMARY`, :term:`LICENSE`, and
:term:`SECTION` do not contain non-UTF-8 characters.
Some package managers do not support such characters.
- *``invalid-packageconfig:``* Checks that no undefined features are
- ``invalid-packageconfig:`` Checks that no undefined features are
being added to :term:`PACKAGECONFIG`. For
example, any name "foo" for which the following form does not exist:
PACKAGECONFIG[foo] = "..."
::
- *``la:``* Checks ``.la`` files for any ``TMPDIR`` paths. Any ``.la``
PACKAGECONFIG[foo] = "..."
- ``la:`` Checks ``.la`` files for any ``TMPDIR`` paths. Any ``.la``
file containing these paths is incorrect since ``libtool`` adds the
correct sysroot prefix when using the files automatically itself.
- *``ldflags:``* Ensures that the binaries were linked with the
- ``ldflags:`` Ensures that the binaries were linked with the
:term:`LDFLAGS` options provided by the build system.
If this test fails, check that the ``LDFLAGS`` variable is being
passed to the linker command.
- *``libdir:``* Checks for libraries being installed into incorrect
- ``libdir:`` Checks for libraries being installed into incorrect
(possibly hardcoded) installation paths. For example, this test will
catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is
"lib32". Another example is when recipes install
``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib".
- *``libexec:``* Checks if a package contains files in
- ``libexec:`` Checks if a package contains files in
``/usr/libexec``. This check is not performed if the ``libexecdir``
variable has been set explicitly to ``/usr/libexec``.
- *``packages-list:``* Checks for the same package being listed
- ``packages-list:`` Checks for the same package being listed
multiple times through the :term:`PACKAGES` variable
value. Installing the package in this manner can cause errors during
packaging.
- *``perm-config:``* Reports lines in ``fs-perms.txt`` that have an
- ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an
invalid format.
- *``perm-line:``* Reports lines in ``fs-perms.txt`` that have an
- ``perm-line:`` Reports lines in ``fs-perms.txt`` that have an
invalid format.
- *``perm-link:``* Reports lines in ``fs-perms.txt`` that specify
- ``perm-link:`` Reports lines in ``fs-perms.txt`` that specify
'link' where the specified target already exists.
- *``perms:``* Currently, this check is unused but reserved.
- ``perms:`` Currently, this check is unused but reserved.
- *``pkgconfig:``* Checks ``.pc`` files for any
- ``pkgconfig:`` Checks ``.pc`` files for any
: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.
- *``pkgname:``* Checks that all packages in
- ``pkgname:`` Checks that all packages in
:term:`PACKAGES` have names that do not contain
invalid characters (i.e. characters other than 0-9, a-z, ., +, and
-).
- *``pkgv-undefined:``* Checks to see if the ``PKGV`` variable is
- ``pkgv-undefined:`` Checks to see if the ``PKGV`` variable is
undefined during :ref:`ref-tasks-package`.
- *``pkgvarcheck:``* Checks through the variables
- ``pkgvarcheck:`` Checks through the variables
:term:`RDEPENDS`,
:term:`RRECOMMENDS`,
:term:`RSUGGESTS`,
@@ -1199,7 +1249,7 @@ The following list shows the tests you can list with the ``WARN_QA`` and
unnecessarily complicate dependencies of other packages within the
same recipe or have other unintended consequences.
- *``pn-overrides:``* Checks that a recipe does not have a name
- ``pn-overrides:`` Checks that a recipe does not have a name
(:term:`PN`) value that appears in
:term:`OVERRIDES`. If a recipe is named such that
its ``PN`` value matches something already in ``OVERRIDES`` (e.g.
@@ -1208,43 +1258,43 @@ The following list shows the tests you can list with the ``WARN_QA`` and
For example, assignments such as ``FILES_${PN} = "xyz"`` effectively
turn into ``FILES = "xyz"``.
- *``rpaths:``* Checks for rpaths in the binaries that contain build
- ``rpaths:`` Checks for rpaths in the binaries that contain build
system paths such as ``TMPDIR``. If this test fails, bad ``-rpath``
options are being passed to the linker commands and your binaries
have potential security issues.
- *``split-strip:``* Reports that splitting or stripping debug symbols
- ``split-strip:`` Reports that splitting or stripping debug symbols
from binaries has failed.
- *``staticdev:``* Checks for static library files (``*.a``) in
- ``staticdev:`` Checks for static library files (``*.a``) in
non-``staticdev`` packages.
- *``symlink-to-sysroot:``* Checks for symlinks in packages that point
- ``symlink-to-sysroot:`` Checks for symlinks in packages that point
into :term:`TMPDIR` on the host. Such symlinks will
work on the host, but are clearly invalid when running on the target.
- *``textrel:``* Checks for ELF binaries that contain relocations in
- ``textrel:`` Checks for ELF binaries that contain relocations in
their ``.text`` sections, which can result in a performance impact at
runtime. See the explanation for the
```ELF binary`` <#qa-issue-textrel>`__ message for more information
regarding runtime performance issues.
- *``unlisted-pkg-lics:``* Checks that all declared licenses applying
- ``unlisted-pkg-lics:`` Checks that all declared licenses applying
for a package are also declared on the recipe level (i.e. any license
in ``LICENSE_*`` should appear in :term:`LICENSE`).
- *``useless-rpaths:``* Checks for dynamic library load paths (rpaths)
- ``useless-rpaths:`` Checks for dynamic library load paths (rpaths)
in the binaries that by default on a standard system are searched by
the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will
not cause any breakage, they do waste space and are unnecessary.
- *``var-undefined:``* Reports when variables fundamental to packaging
- ``var-undefined:`` Reports when variables fundamental to packaging
(i.e. :term:`WORKDIR`,
:term:`DEPLOY_DIR`, :term:`D`,
:term:`PN`, and :term:`PKGD`) are undefined
during :ref:`ref-tasks-package`.
- *``version-going-backwards:``* If Build History is enabled, reports
- ``version-going-backwards:`` If Build History is enabled, reports
when a package being written out has a lower version than the
previously written package under the same name. If you are placing
output packages into a feed and upgrading packages on a target system
@@ -1257,7 +1307,7 @@ The following list shows the tests you can list with the ``WARN_QA`` and
If you are not using runtime package management on your target
system, then you do not need to worry about this situation.
- *``xorg-driver-abi:``* Checks that all packages containing Xorg
- ``xorg-driver-abi:`` Checks that all packages containing Xorg
drivers have ABI dependencies. The ``xserver-xorg`` recipe provides
driver ABI names. All drivers should depend on the ABI versions that
they have been built against. Driver recipes that include
@@ -1293,9 +1343,8 @@ packages such as ``kernel-vmlinux``.
The ``kernel`` class contains logic that allows you to embed an initial
RAM filesystem (initramfs) image when you build the kernel image. For
information on how to build an initramfs, see the "`Building an Initial
RAM Filesystem (initramfs)
Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" section in
information on how to build an initramfs, see the
":ref:`building-an-initramfs-image`" section in
the Yocto Project Development Tasks Manual.
Various other classes are used by the ``kernel`` and ``module`` classes
@@ -1545,8 +1594,7 @@ and implements the :ref:`ref-tasks-compile` and
everything needed to build and package a kernel module.
For general information on out-of-tree Linux kernel modules, see the
"`Incorporating Out-of-Tree
Modules <&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules>`__"
":ref:`kernel-dev/kernel-dev-common:incorporating out-of-tree modules`"
section in the Yocto Project Linux Kernel Development Manual.
.. _ref-classes-module-base:
@@ -1569,9 +1617,8 @@ The ``multilib*`` classes provide support for building libraries with
different target optimizations or target architectures and installing
them side-by-side in the same image.
For more information on using the Multilib feature, see the "`Combining
Multiple Versions of Library Files into One
Image <&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image>`__"
For more information on using the Multilib feature, see the
":ref:`combining-multiple-versions-library-files-into-one-image`"
section in the Yocto Project Development Tasks Manual.
.. _ref-classes-native:
@@ -1597,14 +1644,18 @@ a couple different ways:
naming convention:
::
myrecipe-native.bb
myrecipe-native.bb
Not using this naming convention can lead to subtle problems
caused by existing code that depends on that naming convention.
- Create or modify a target recipe that contains the following:
:term:`BBCLASSEXTEND` = "native" Inside the
::
BBCLASSEXTEND = "native"
Inside the
recipe, use ``_class-native`` and ``_class-target`` overrides to
specify any functionality specific to the respective native or target
case.
@@ -1632,7 +1683,11 @@ couple different ways:
that the ``nativesdk`` class is inherited last.
- Create a ``nativesdk`` variant of any recipe by adding the following:
:term:`BBCLASSEXTEND` = "nativesdk" Inside the
::
BBCLASSEXTEND = "nativesdk"
Inside the
recipe, use ``_class-nativesdk`` and ``_class-target`` overrides to
specify any functionality specific to the respective SDK machine or
target case.
@@ -1643,7 +1698,7 @@ couple different ways:
::
nativesdk-myrecipe.bb
Not doing so can lead to subtle problems because code exists that
depends on the naming convention.
@@ -1675,9 +1730,8 @@ package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__.
npm://
fetcher to have dependencies fetched and packaged automatically.
For information on how to create NPM packages, see the "`Creating Node
Package Manager (NPM)
Packages <&YOCTO_DOCS_DEV_URL;#creating-node-package-manager-npm-packages>`__"
For information on how to create NPM packages, see the
":ref:`dev-manual/dev-manual-common-tasks:creating node package manager (npm) packages`"
section in the Yocto Project Development Tasks Manual.
.. _ref-classes-oelint:
@@ -1706,8 +1760,12 @@ before attempting to fetch it from the upstream specified in
To use this class, inherit it globally and specify
:term:`SOURCE_MIRROR_URL`. Here is an example:
INHERIT += "own-mirrors" SOURCE_MIRROR_URL =
"http://example.com/my-source-mirror" You can specify only a single URL
::
INHERIT += "own-mirrors"
SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
You can specify only a single URL
in ``SOURCE_MIRROR_URL``.
.. _ref-classes-package:
@@ -1742,9 +1800,8 @@ first class listed in this variable is used for image generation.
If you take the optional step to set up a repository (package feed) on
the development host that can be used by DNF, you can install packages
from the feed while you are running the image on the target (i.e.
runtime installation of packages). For more information, see the "`Using
Runtime Package
Management <&YOCTO_DOCS_DEV_URL;#using-runtime-package-management>`__"
runtime installation of packages). For more information, see the
":ref:`dev-manual/dev-manual-common-tasks:using runtime package management`"
section in the Yocto Project Development Tasks Manual.
The package-specific class you choose can affect build-time performance
@@ -1774,9 +1831,9 @@ consider some further things about using RPM:
You can find additional information on the effects of the package class
at these two Yocto Project mailing list links:
- `https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html <&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html>`__
- https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html
- `https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html <&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html>`__
- https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html
.. _ref-classes-package_deb:
@@ -1870,9 +1927,8 @@ group recipes (e.g. ``PACKAGES``, ``PACKAGE_ARCH``, ``ALLOW_EMPTY``, and
so forth). It is highly recommended that all package group recipes
inherit this class.
For information on how to use this class, see the "`Customizing Images
Using Custom Package
Groups <&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks>`__"
For information on how to use this class, see the
":ref:`usingpoky-extend-customimage-customtasks`"
section in the Yocto Project Development Tasks Manual.
Previously, this class was called the ``task`` class.
@@ -1937,8 +1993,7 @@ files.
The ``populate_sdk`` class provides support for SDK-only recipes. For
information on advantages gained when building a cross-development
toolchain using the :ref:`ref-tasks-populate_sdk`
task, see the "`Building an SDK
Installer <&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer>`__"
task, see the ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`"
section in the Yocto Project Application Development and the Extensible
Software Development Kit (eSDK) manual.
@@ -1950,19 +2005,19 @@ Software Development Kit (eSDK) manual.
The ``populate_sdk_*`` classes support SDK creation and consist of the
following classes:
- *``populate_sdk_base``:* The base class supporting SDK creation under
- ``populate_sdk_base``: The base class supporting SDK creation under
all package managers (i.e. DEB, RPM, and opkg).
- *``populate_sdk_deb``:* Supports creation of the SDK given the Debian
- ``populate_sdk_deb``: Supports creation of the SDK given the Debian
package manager.
- *``populate_sdk_rpm``:* Supports creation of the SDK given the RPM
- ``populate_sdk_rpm``: Supports creation of the SDK given the RPM
package manager.
- *``populate_sdk_ipk``:* Supports creation of the SDK given the opkg
- ``populate_sdk_ipk``: Supports creation of the SDK given the opkg
(IPK format) package manager.
- *``populate_sdk_ext``:* Supports extensible SDK creation under all
- ``populate_sdk_ext``: Supports extensible SDK creation under all
package managers.
The ``populate_sdk_base`` class inherits the appropriate
@@ -1977,8 +2032,10 @@ contains the cross-compiler and associated tooling, and the target,
which contains a target root filesystem that is configured for the SDK
usage. These two images reside in :term:`SDK_OUTPUT`,
which consists of the following:
${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs
${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs
::
${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs
${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs
Finally, the base populate SDK class creates the toolchain environment
setup script, the tarball of the SDK, and the installer.
@@ -1989,13 +2046,12 @@ These classes are inherited by and used with the ``populate_sdk_base``
class.
For more information on the cross-development toolchain generation, see
the "`Cross-Development Toolchain
Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__"
the ":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`"
section in the Yocto Project Overview and Concepts Manual. For
information on advantages gained when building a cross-development
toolchain using the :ref:`ref-tasks-populate_sdk`
task, see the "`Building an SDK
Installer <&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer>`__"
task, see the
":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`"
section in the Yocto Project Application Development and the Extensible
Software Development Kit (eSDK) manual.
@@ -2034,8 +2090,8 @@ The ``primport`` class provides functionality for importing
``prserv.bbclass``
==================
The ``prserv`` class provides functionality for using a `PR
service <&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service>`__ in order to
The ``prserv`` class provides functionality for using a :ref:`PR
service <dev-manual/dev-manual-common-tasks:working with a pr service>` in order to
automatically manage the incrementing of the :term:`PR`
variable for each recipe.
@@ -2054,11 +2110,10 @@ runtime tests for recipes that build software that provides these tests.
This class is intended to be inherited by individual recipes. However,
the class' functionality is largely disabled unless "ptest" appears in
:term:`DISTRO_FEATURES`. See the "`Testing
Packages With
ptest <&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest>`__" section in
the Yocto Project Development Tasks Manual for more information on
ptest.
:term:`DISTRO_FEATURES`. See the
":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`"
section in the Yocto Project Development Tasks Manual for more information
on ptest.
.. _ref-classes-ptest-gnome:
@@ -2068,10 +2123,9 @@ ptest.
Enables package tests (ptests) specifically for GNOME packages, which
have tests intended to be executed with ``gnome-desktop-testing``.
For information on setting up and running ptests, see the "`Testing
Packages With
ptest <&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest>`__" section in
the Yocto Project Development Tasks Manual.
For information on setting up and running ptests, see the
":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`"
section in the Yocto Project Development Tasks Manual.
.. _ref-classes-python-dir:
@@ -2142,7 +2196,9 @@ absent from both the sysroot and target packages.
If a recipe needs the ``.la`` files to be installed, then the recipe can
override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows:
REMOVE_LIBTOOL_LA = "0"
::
REMOVE_LIBTOOL_LA = "0"
.. note::
@@ -2155,9 +2211,9 @@ REMOVE_LIBTOOL_LA = "0"
``report-error.bbclass``
========================
The ``report-error`` class supports enabling the `error reporting
tool <&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool>`__, which
allows you to submit build error information to a central database.
The ``report-error`` class supports enabling the :ref:`error reporting
tool <dev-manual/dev-manual-common-tasks:using the error reporting tool>`",
which allows you to submit build error information to a central database.
The class collects debug information for recipe, recipe version, task,
machine, distro, build system, target system, host distro, branch,
@@ -2182,14 +2238,20 @@ preserves these files for inspection and possible debugging purposes. If
you would rather have these files deleted to save disk space as the
build progresses, you can enable ``rm_work`` by adding the following to
your ``local.conf`` file, which is found in the :term:`Build Directory`.
INHERIT += "rm_work" If you are
::
INHERIT += "rm_work"
If you are
modifying and building source code out of the work directory for a
recipe, enabling ``rm_work`` will potentially result in your changes to
the source being lost. To exclude some recipes from having their work
directories deleted by ``rm_work``, you can add the names of the recipe
or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which
can also be set in your ``local.conf`` file. Here is an example:
RM_WORK_EXCLUDE += "busybox glibc"
::
RM_WORK_EXCLUDE += "busybox glibc"
.. _ref-classes-rootfs*:
@@ -2219,8 +2281,7 @@ The root filesystem is created from packages using one of the
:term:`PACKAGE_CLASSES` variable.
For information on how root filesystem images are created, see the
"`Image
Generation <&YOCTO_DOCS_OM_URL;#image-generation-dev-environment>`__"
:ref:`image-generation-dev-environment`"
section in the Yocto Project Overview and Concepts Manual.
.. _ref-classes-sanity:
@@ -2339,9 +2400,9 @@ The ``sstate`` class provides support for Shared State (sstate). By
default, the class is enabled through the
:term:`INHERIT_DISTRO` variable's default value.
For more information on sstate, see the "`Shared State
Cache <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__" section in the Yocto
Project Overview and Concepts Manual.
For more information on sstate, see the
":ref:`overview-manual/overview-manual-concepts:shared state cache`"
section in the Yocto Project Overview and Concepts Manual.
.. _ref-classes-staging:
@@ -2510,14 +2571,17 @@ You should set :term:`SYSTEMD_SERVICE` to the
name of the service file. You should also use a package name override to
indicate the package to which the value applies. If the value applies to
the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here
is an example from the connman recipe: SYSTEMD_SERVICE_${PN} =
"connman.service" Services are set up to start on boot automatically
is an example from the connman recipe:
::
SYSTEMD_SERVICE_${PN} = "connman.service"
Services are set up to start on boot automatically
unless you have set
:term:`SYSTEMD_AUTO_ENABLE` to "disable".
For more information on ``systemd``, see the "`Selecting an
Initialization
Manager <&YOCTO_DOCS_DEV_URL;#selecting-an-initialization-manager>`__"
For more information on ``systemd``, see the
":ref:`dev-manual/dev-manual-common-tasks:selecting an initialization manager`"
section in the Yocto Project Development Tasks Manual.
.. _ref-classes-systemd-boot:
@@ -2593,13 +2657,17 @@ The tests are commands that run on the target system over ``ssh``. Each
test is written in Python and makes use of the ``unittest`` module.
The ``testimage.bbclass`` runs tests on an image when called using the
following: $ bitbake -c testimage image The ``testimage-auto`` class
following:
::
$ bitbake -c testimage image
The ``testimage-auto`` class
runs tests on an image after the image is constructed (i.e.
:term:`TESTIMAGE_AUTO` must be set to "1").
For information on how to enable, run, and create new tests, see the
"`Performing Automated Runtime
Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__"
":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
section in the Yocto Project Development Tasks Manual.
.. _ref-classes-testsdk:
@@ -2609,7 +2677,10 @@ section in the Yocto Project Development Tasks Manual.
This class supports running automated tests against software development
kits (SDKs). The ``testsdk`` class runs tests on an SDK when called
using the following: $ bitbake -c testsdk image
using the following:
::
$ bitbake -c testsdk image
.. note::
@@ -2682,7 +2753,9 @@ The ``typecheck`` class provides support for validating the values of
variables set at the configuration level against their defined types.
The OpenEmbedded build system allows you to define the type of a
variable using the "type" varflag. Here is an example:
IMAGE_FEATURES[type] = "list"
::
IMAGE_FEATURES[type] = "list"
.. _ref-classes-uboot-config:
@@ -2690,11 +2763,18 @@ IMAGE_FEATURES[type] = "list"
========================
The ``uboot-config`` class provides support for U-Boot configuration for
a machine. Specify the machine in your recipe as follows: UBOOT_CONFIG
??= <default> UBOOT_CONFIG[foo] = "config,images" You can also specify
the machine using this method: UBOOT_MACHINE = "config" See the
:term:`UBOOT_CONFIG` and
:term:`UBOOT_MACHINE` variables for additional
a machine. Specify the machine in your recipe as follows:
::
UBOOT_CONFIG ??= <default>
UBOOT_CONFIG[foo] = "config,images"
You can also specify the machine using this method:
::
UBOOT_MACHINE = "config"
See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional
information.
.. _ref-classes-uninative:

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

@@ -11,8 +11,7 @@ is a key part of the extensible SDK.
This chapter provides a Quick Reference for the ``devtool`` command. For
more information on how to apply the command when using the extensible
SDK, see the "`Using the Extensible
SDK <&YOCTO_DOCS_SDK_URL;#sdk-extensible>`__" chapter in the Yocto
SDK, see the ":doc:`../sdk-manual/sdk-extensible`" chapter in the Yocto
Project Application Development and the Extensible Software Development
Kit (eSDK) manual.
@@ -23,66 +22,99 @@ Getting Help
The ``devtool`` command line is organized similarly to Git in that it
has a number of sub-commands for each function. You can run
``devtool --help`` to see all the commands: $ devtool -h NOTE: Starting
bitbake server... usage: devtool [--basepath BASEPATH] [--bbpath BBPATH]
[-d] [-q] [--color COLOR] [-h] <subcommand> ... OpenEmbedded development
tool options: --basepath BASEPATH Base directory of SDK / build
directory --bbpath BBPATH Explicitly specify the BBPATH, rather than
getting it from the metadata -d, --debug Enable debug output -q, --quiet
Print only errors --color COLOR Colorize output (where COLOR is auto,
always, never) -h, --help show this help message and exit subcommands:
Beginning work on a recipe: add Add a new recipe modify Modify the
source for an existing recipe upgrade Upgrade an existing recipe Getting
information: status Show workspace status search Search available
recipes latest-version Report the latest version of an existing recipe
check-upgrade-status Report upgradability for multiple (or all) recipes
Working on a recipe in the workspace: build Build a recipe rename Rename
a recipe file in the workspace edit-recipe Edit a recipe file
find-recipe Find a recipe file configure-help Get help on configure
script options update-recipe Apply changes from external source tree to
recipe reset Remove a recipe from your workspace finish Finish working
on a recipe in your workspace Testing changes on target: deploy-target
Deploy recipe output files to live target machine undeploy-target
Undeploy recipe output files in live target machine build-image Build
image including workspace recipe packages Advanced: create-workspace Set
up workspace in an alternative location export Export workspace into a
tar archive import Import exported tar archive into workspace extract
Extract the source for an existing recipe sync Synchronize the source
tree for an existing recipe Use devtool <subcommand> --help to get help
on a specific command As directed in the general help output, you can
``devtool --help`` to see all the commands:
::
$ devtool -h
NOTE: Starting bitbake server...
usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q] [--color COLOR] [-h] <subcommand> ...
OpenEmbedded development tool
options:
--basepath BASEPATH Base directory of SDK / build directory
--bbpath BBPATH Explicitly specify the BBPATH, rather than getting it from the metadata
-d, --debug Enable debug output
-q, --quiet Print only errors
--color COLOR Colorize output (where COLOR is auto, always, never)
-h, --help show this help message and exit
subcommands:
Beginning work on a recipe:
add Add a new recipe
modify Modify the source for an existing recipe
upgrade Upgrade an existing recipe
Getting information:
status Show workspace status
latest-version Report the latest version of an existing recipe
check-upgrade-status Report upgradability for multiple (or all) recipes
search Search available recipes
Working on a recipe in the workspace:
build Build a recipe
rename Rename a recipe file in the workspace
edit-recipe Edit a recipe file
find-recipe Find a recipe file
configure-help Get help on configure script options
update-recipe Apply changes from external source tree to recipe
reset Remove a recipe from your workspace
finish Finish working on a recipe in your workspace
Testing changes on target:
deploy-target Deploy recipe output files to live target machine
undeploy-target Undeploy recipe output files in live target machine
build-image Build image including workspace recipe packages
Advanced:
create-workspace Set up workspace in an alternative location
extract Extract the source for an existing recipe
sync Synchronize the source tree for an existing recipe
menuconfig Alter build-time configuration for a recipe
import Import exported tar archive into workspace
export Export workspace into a tar archive
other:
selftest-reverse Reverse value (for selftest)
pluginfile Print the filename of this plugin
bbdir Print the BBPATH directory of this plugin
count How many times have this plugin been registered.
multiloaded How many times have this plugin been initialized
Use devtool <subcommand> --help to get help on a specific command
As directed in the general help output, you can
get more syntax on a specific command by providing the command name and
using "--help": $ devtool add --help NOTE: Starting bitbake server...
usage: devtool add [-h] [--same-dir \| --no-same-dir] [--fetch URI]
[--fetch-dev] [--version VERSION] [--no-git] [--srcrev SRCREV \|
--autorev] [--srcbranch SRCBRANCH] [--binary] [--also-native]
[--src-subdir SUBDIR] [--mirrors] [--provides PROVIDES] [recipename]
[srctree] [fetchuri] Adds a new recipe to the workspace to build a
specified source tree. Can optionally fetch a remote URI and unpack it
to create the source tree. arguments: recipename Name for new recipe to
add (just name - no version, path or extension). If not specified, will
attempt to auto-detect it. srctree Path to external source tree. If not
specified, a subdirectory of /home/scottrif/poky/build/workspace/sources
will be used. fetchuri Fetch the specified URI and extract it to create
the source tree options: -h, --help show this help message and exit
--same-dir, -s Build in same directory as source --no-same-dir Force
build in a separate build directory --fetch URI, -f URI Fetch the
specified URI and extract it to create the source tree (deprecated -
pass as positional argument instead) --fetch-dev For npm, also fetch
devDependencies --version VERSION, -V VERSION Version to use within
recipe (PV) --no-git, -g If fetching source, do not set up source tree
as a git repository --srcrev SRCREV, -S SRCREV Source revision to fetch
if fetching from an SCM such as git (default latest) --autorev, -a When
fetching from a git repository, set SRCREV in the recipe to a floating
revision instead of fixed --srcbranch SRCBRANCH, -B SRCBRANCH Branch in
source repository if fetching from an SCM such as git (default master)
--binary, -b Treat the source tree as something that should be installed
verbatim (no compilation, same directory structure). Useful with binary
packages e.g. RPMs. --also-native Also add native variant (i.e. support
building recipe for the build host as well as the target machine)
--src-subdir SUBDIR Specify subdirectory within source tree to use
--mirrors Enable PREMIRRORS and MIRRORS for source tree fetching
(disable by default). --provides PROVIDES, -p PROVIDES Specify an alias
for the item provided by the recipe. E.g. virtual/libgl
using "--help":
::
$ devtool add --help
NOTE: Starting bitbake server...
usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI] [--npm-dev] [--version VERSION] [--no-git] [--srcrev SRCREV | --autorev] [--srcbranch SRCBRANCH] [--binary] [--also-native] [--src-subdir SUBDIR] [--mirrors]
[--provides PROVIDES]
[recipename] [srctree] [fetchuri]
Adds a new recipe to the workspace to build a specified source tree. Can optionally fetch a remote URI and unpack it to create the source tree.
arguments:
recipename Name for new recipe to add (just name - no version, path or extension). If not specified, will attempt to auto-detect it.
srctree Path to external source tree. If not specified, a subdirectory of /media/build1/poky/build/workspace/sources will be used.
fetchuri Fetch the specified URI and extract it to create the source tree
options:
-h, --help show this help message and exit
--same-dir, -s Build in same directory as source
--no-same-dir Force build in a separate build directory
--fetch URI, -f URI Fetch the specified URI and extract it to create the source tree (deprecated - pass as positional argument instead)
--npm-dev For npm, also fetch devDependencies
--version VERSION, -V VERSION
Version to use within recipe (PV)
--no-git, -g If fetching source, do not set up source tree as a git repository
--srcrev SRCREV, -S SRCREV
Source revision to fetch if fetching from an SCM such as git (default latest)
--autorev, -a When fetching from a git repository, set SRCREV in the recipe to a floating revision instead of fixed
--srcbranch SRCBRANCH, -B SRCBRANCH
Branch in source repository if fetching from an SCM such as git (default master)
--binary, -b Treat the source tree as something that should be installed verbatim (no compilation, same directory structure). Useful with binary packages e.g. RPMs.
--also-native Also add native variant (i.e. support building recipe for the build host as well as the target machine)
--src-subdir SUBDIR Specify subdirectory within source tree to use
--mirrors Enable PREMIRRORS and MIRRORS for source tree fetching (disable by default).
--provides PROVIDES, -p PROVIDES
Specify an alias for the item provided by the recipe. E.g. virtual/libgl
.. _devtool-the-workspace-layer-structure:
@@ -99,22 +131,35 @@ The following figure shows the workspace structure:
:align: center
:scale: 70%
attic - A directory created if devtool believes it must preserve
anything when you run "devtool reset". For example, if you run "devtool
add", make changes to the recipe, and then run "devtool reset", devtool
takes notice that the file has been changed and moves it into the attic
should you still want the recipe. README - Provides information on what
is in workspace layer and how to manage it. .devtool_md5 - A checksum
file used by devtool. appends - A directory that contains \*.bbappend
files, which point to external source. conf - A configuration directory
that contains the layer.conf file. recipes - A directory containing
recipes. This directory contains a folder for each directory added whose
name matches that of the added recipe. devtool places the recipe.bb file
within that sub-directory. sources - A directory containing a working
copy of the source files used when building the recipe. This is the
default directory used as the location of the source tree when you do
not provide a source tree path. This directory contains a folder for
each set of source files matched to a corresponding recipe.
::
attic - A directory created if devtool believes it must preserve
anything when you run "devtool reset". For example, if you
run "devtool add", make changes to the recipe, and then
run "devtool reset", devtool takes notice that the file has
been changed and moves it into the attic should you still
want the recipe.
README - Provides information on what is in workspace layer and how to
manage it.
.devtool_md5 - A checksum file used by devtool.
appends - A directory that contains *.bbappend files, which point to
external source.
conf - A configuration directory that contains the layer.conf file.
recipes - A directory containing recipes. This directory contains a
folder for each directory added whose name matches that of the
added recipe. devtool places the recipe.bb file
within that sub-directory.
sources - A directory containing a working copy of the source files used
when building the recipe. This is the default directory used
as the location of the source tree when you do not provide a
source tree path. This directory contains a folder for each
set of source files matched to a corresponding recipe.
.. _devtool-adding-a-new-recipe-to-the-workspace:
@@ -127,8 +172,10 @@ you. The source files the recipe uses should exist in an external area.
The following example creates and adds a new recipe named ``jackson`` to
a workspace layer the tool creates. The source code built by the recipes
resides in ``/home/user/sources/jackson``: $ devtool add jackson
/home/user/sources/jackson
resides in ``/home/user/sources/jackson``:
::
$ devtool add jackson /home/user/sources/jackson
If you add a recipe and the workspace layer does not exist, the command
creates the layer and populates it as described in "`The Workspace Layer
@@ -145,35 +192,38 @@ external source tree.
that these packages exist on the target hardware before attempting to
run your application. If dependent packages (e.g. libraries) do not
exist on the target, your application, when run, will fail to find
those functions. For more information, see the "
Deploying Your Software on the Target Machine
" section.
those functions. For more information, see the
":ref:`ref-manual/ref-devtool-reference:deploying your software on the target machine`"
section.
By default, ``devtool add`` uses the latest revision (i.e. master) when
unpacking files from a remote URI. In some cases, you might want to
specify a source revision by branch, tag, or commit hash. You can
specify these options when using the ``devtool add`` command:
- To specify a source branch, use the ``--srcbranch`` option: $ devtool
add --srcbranch DISTRO_NAME_NO_CAP jackson /home/user/sources/jackson
- To specify a source branch, use the ``--srcbranch`` option:
::
$ devtool add --srcbranch DISTRO_NAME_NO_CAP jackson /home/user/sources/jackson
In the previous example, you are checking out the DISTRO_NAME_NO_CAP
branch.
- To specify a specific tag or commit hash, use the ``--srcrev``
option: $ devtool add --srcrev DISTRO_REL_TAG jackson
/home/user/sources/jackson $ devtool add --srcrev some_commit_hash
/home/user/sources/jackson The previous examples check out the
option:
::
$ devtool add --srcrev DISTRO_REL_TAG jackson /home/user/sources/jackson
$ devtool add --srcrev some_commit_hash /home/user/sources/jackson
The previous examples check out the
DISTRO_REL_TAG tag and the commit associated with the
some_commit_hash hash.
.. note::
If you prefer to use the latest revision every time the recipe is
built, use the options
--autorev
or
-a
.
built, use the options --autorev or -a.
.. _devtool-extracting-the-source-for-an-existing-recipe:
@@ -219,8 +269,12 @@ The ``devtool modify`` command extracts the source for a recipe, sets it
up as a Git repository if the source had not already been fetched from
Git, checks out a branch for development, and applies any patches from
the recipe as commits on top. You can use the following command to
checkout the source files: $ devtool modify recipe Using the above
command form, ``devtool`` uses the existing recipe's
checkout the source files:
::
$ devtool modify recipe
Using the above command form, ``devtool`` uses the existing recipe's
: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".
@@ -255,16 +309,24 @@ compile, and test the code.
When you are satisfied with the results and you have committed your
changes to the Git repository, you can then run the
``devtool update-recipe`` to create the patches and update the recipe: $
devtool update-recipe recipe If you run the ``devtool update-recipe``
``devtool update-recipe`` to create the patches and update the recipe:
::
$ devtool update-recipe recipe
If you run the ``devtool update-recipe``
without committing your changes, the command ignores the changes.
Often, you might want to apply customizations made to your software in
your own layer rather than apply them to the original recipe. If so, you
can use the ``-a`` or ``--append`` option with the
``devtool update-recipe`` command. These options allow you to specify
the layer into which to write an append file: $ devtool update-recipe
recipe -a base-layer-directory The ``*.bbappend`` file is created at the
the layer into which to write an append file:
::
$ devtool update-recipe recipe -a base-layer-directory
The ``*.bbappend`` file is created at the
appropriate path within the specified layer directory, which may or may
not be in your ``bblayers.conf`` file. If an append file already exists,
the command updates it appropriately.
@@ -287,7 +349,7 @@ particular recipe.
.. note::
- For the ``oe-core`` layer, recipe maintainers come from the
```maintainers.inc`http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/distro/include/maintainers.inc
`maintainers.inc <http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/distro/include/maintainers.inc>`_
file.
- If the recipe is using the :ref:`bitbake:git-fetcher`
@@ -296,14 +358,21 @@ particular recipe.
recipe's latest version tag.
As with all ``devtool`` commands, you can get help on the individual
command: $ devtool check-upgrade-status -h NOTE: Starting bitbake
server... usage: devtool check-upgrade-status [-h] [--all] [recipe
[recipe ...]] Prints a table of recipes together with versions currently
provided by recipes, and latest upstream versions, when there is a later
version available arguments: recipe Name of the recipe to report (omit
to report upgrade info for all recipes) options: -h, --help show this
help message and exit --all, -a Show all recipes, not just recipes
needing upgrade
command:
::
$ devtool check-upgrade-status -h
NOTE: Starting bitbake server...
usage: devtool check-upgrade-status [-h] [--all] [recipe [recipe ...]]
Prints a table of recipes together with versions currently provided by recipes, and latest upstream versions, when there is a later version available
arguments:
recipe Name of the recipe to report (omit to report upgrade info for all recipes)
options:
-h, --help show this help message and exit
--all, -a Show all recipes, not just recipes needing upgrade
Unless you provide a specific recipe name on the command line, the
command checks all recipes in all configured layers.
@@ -317,21 +386,18 @@ satisfied.
.. note::
When a reason for not upgrading displays, the reason is usually
written into the recipe using the
RECIPE_NO_UPDATE_REASON
variable. See the
base-passwd.bb
recipe for an example.
written into the recipe using the RECIPE_NO_UPDATE_REASON
variable. See the base-passwd.bb recipe for an example.
$ devtool check-upgrade-status ... NOTE: acpid 2.0.30 2.0.31 Ross Burton
<ross.burton@intel.com> NOTE: u-boot-fw-utils 2018.11 2019.01 Marek
Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff
NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com>
d3689267f92c5956e09cc7d1baa4700141662bff . . . NOTE: base-passwd 3.5.29
3.5.45 Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to:
Version 3.5.38 requires cdebconf for update-passwd utility NOTE: busybox
1.29.2 1.30.0 Andrej Valek <andrej.valek@siemens.com> NOTE: dbus-test
1.12.10 1.12.12 Chen Qi <Qi.Chen@windriver.com>
::
$ devtool check-upgrade-status ...
NOTE: acpid 2.0.30 2.0.31 Ross Burton <ross.burton@intel.com>
NOTE: u-boot-fw-utils 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff
NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff . . .
NOTE: base-passwd 3.5.29 3.5.45 Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to: Version 3.5.38 requires cdebconf for update-passwd utility
NOTE: busybox 1.29.2 1.30.0 Andrej Valek <andrej.valek@siemens.com>
NOTE: dbus-test 1.12.10 1.12.12 Chen Qi <Qi.Chen@windriver.com>
.. _devtool-upgrading-a-recipe:
@@ -341,17 +407,13 @@ Upgrading a Recipe
As software matures, upstream recipes are upgraded to newer versions. As
a developer, you need to keep your local recipes up-to-date with the
upstream version releases. Several methods exist by which you can
upgrade recipes. You can read about them in the "`Upgrading
Recipes <&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes>`__" section of the
Yocto Project Development Tasks Manual. This section overviews the
``devtool upgrade`` command.
upgrade recipes. You can read about them in the ":ref:`gs-upgrading-recipes`"
section of the Yocto Project Development Tasks Manual. This section
overviews the ``devtool upgrade`` command.
.. note::
Before you upgrade a recipe, you can check on its upgrade status. See
the "
Checking on the Upgrade Status of a Recipe
" for more information.
Before you upgrade a recipe, you can check on its upgrade status. See
the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" section
for more information.
The ``devtool upgrade`` command upgrades an existing recipe to a more
recent version of the recipe upstream. The command puts the upgraded
@@ -369,14 +431,11 @@ revision to which you want to upgrade (i.e. the
:term:`SRCREV`), whether or not to apply patches, and so
forth.
You can read more on the ``devtool upgrade`` workflow in the "`Use
``devtool upgrade`` to Create a Version of the Recipe that Supports a
Newer Version of the
Software <&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software>`__"
You can read more on the ``devtool upgrade`` workflow in the
":ref:`sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software`"
section in the Yocto Project Application Development and the Extensible
Software Development Kit (eSDK) manual. You can also see an example of
how to use ``devtool upgrade`` in the "`Using
``devtool upgrade`` <&YOCTO_DOCS_DEV_URL;#gs-using-devtool-upgrade>`__"
how to use ``devtool upgrade`` in the ":ref:`gs-using-devtool-upgrade`"
section in the Yocto Project Development Tasks Manual.
.. _devtool-resetting-a-recipe:
@@ -397,10 +456,13 @@ files have been modified, the command preserves the modified files in a
separate "attic" subdirectory under the workspace layer.
Here is an example that resets the workspace directory that contains the
``mtr`` recipe: $ devtool reset mtr NOTE: Cleaning sysroot for recipe
mtr... NOTE: Leaving source tree
/home/scottrif/poky/build/workspace/sources/mtr as-is; if you no longer
need it then please delete it manually $
``mtr`` recipe:
::
$ devtool reset mtr
NOTE: Cleaning sysroot for recipe mtr...
NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no longer need it then please delete it manually
$
.. _devtool-building-your-recipe:
@@ -414,8 +476,10 @@ Use the ``devtool build`` command to build your recipe. The
When you use the ``devtool build`` command, you must supply the root
name of the recipe (i.e. do not provide versions, paths, or extensions).
You can use either the "-s" or the "--disable-parallel-make" options to
disable parallel makes during the build. Here is an example: $ devtool
build recipe
disable parallel makes during the build. Here is an example:
::
$ devtool build recipe
.. _devtool-building-your-image:
@@ -429,8 +493,10 @@ device for testing. For proper integration into a final image, you need
to edit your custom image recipe appropriately.
When you use the ``devtool build-image`` command, you must supply the
name of the image. This command has no command line options: $ devtool
build-image image
name of the image. This command has no command line options:
::
$ devtool build-image image
.. _devtool-deploying-your-software-on-the-target-machine:
@@ -438,7 +504,11 @@ Deploying Your Software on the Target Machine
=============================================
Use the ``devtool deploy-target`` command to deploy the recipe's build
output to the live target machine: $ devtool deploy-target recipe target
output to the live target machine:
::
$ devtool deploy-target recipe target
The target is the address of the target machine, which must be running
an SSH server (i.e. ``user@hostname[:destdir]``).
@@ -485,8 +555,13 @@ Removing Your Software from the Target Machine
Use the ``devtool undeploy-target`` command to remove deployed build
output from the target machine. For the ``devtool undeploy-target``
command to work, you must have previously used the
```devtool deploy-target`` <#devtool-deploying-your-software-on-the-target-machine>`__
command. $ devtool undeploy-target recipe target The target is the
":ref:`devtool deploy-target <ref-manual/ref-devtool-reference:deploying your software on the target machine>`"
command.
::
$ devtool undeploy-target recipe target
The target is the
address of the target machine, which must be running an SSH server (i.e.
``user@hostname``).
@@ -501,12 +576,17 @@ new workspace layer, it is populated with the ``README`` file and the
``conf`` directory only.
The following example creates a new workspace layer in your current
working and by default names the workspace layer "workspace": $ devtool
create-workspace
working and by default names the workspace layer "workspace":
::
$ devtool create-workspace
You can create a workspace layer anywhere by supplying a pathname with
the command. The following command creates a new workspace layer named
"new-workspace": $ devtool create-workspace /home/scottrif/new-workspace
"new-workspace":
::
$ devtool create-workspace /home/scottrif/new-workspace
.. _devtool-get-the-status-of-the-recipes-in-your-workspace:
@@ -517,13 +597,19 @@ Use the ``devtool status`` command to list the recipes currently in your
workspace. Information includes the paths to their respective external
source trees.
The ``devtool status`` command has no command-line options: $ devtool
status Following is sample output after using
```devtool add`` <#devtool-adding-a-new-recipe-to-the-workspace>`__ to
create and add the ``mtr_0.86.bb`` recipe to the ``workspace``
directory: $ devtool status mtr:
/home/scottrif/poky/build/workspace/sources/mtr
(/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) $
The ``devtool status`` command has no command-line options:
::
$ devtool status
Following is sample output after using
:ref:`devtool add <ref-manual/ref-devtool-reference:adding a new recipe to the workspace layer>`
to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory:
::
$ devtool status mtr
:/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
$
.. _devtool-search-for-available-target-recipes:

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

@@ -26,8 +26,11 @@ One method you can use to determine which recipes are checking to see if
a particular feature is contained or not is to ``grep`` through the
:term:`Metadata` for the feature. Here is an example that
discovers the recipes whose build is potentially changed based on a
given feature: $ cd poky $ git grep
'contains.*MACHINE_FEATURES.*feature'
given feature:
::
$ cd poky
$ git grep 'contains.*MACHINE_FEATURES.*feature'
.. _ref-features-machine:
@@ -115,8 +118,7 @@ metadata:
- *api-documentation:* Enables generation of API documentation during
recipe builds. The resulting documentation is added to SDK tarballs
when the ``bitbake -c populate_sdk`` command is used. See the
"`Adding API Documentation to the Standard
SDK <&YOCTO_DOCS_SDK_URL;#adding-api-documentation-to-the-standard-sdk>`__"
":ref:`sdk-manual/sdk-appendix-customizing-standard:adding api documentation to the standard sdk`"
section in the Yocto Project Application Development and the
Extensible Software Development Kit (eSDK) manual.
@@ -154,8 +156,7 @@ metadata:
- *ptest:* Enables building the package tests where supported by
individual recipes. For more information on package tests, see the
"`Testing Packages With
ptest <&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest>`__" section
":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`" section
in the Yocto Project Development Tasks Manual.
- *smbfs:* Include SMB networks client support (for mounting
@@ -237,8 +238,8 @@ The following image features are available for all images:
- *ptest-pkgs:* Installs ptest packages for all ptest-enabled recipes.
- *read-only-rootfs:* Creates an image whose root filesystem is
read-only. See the "`Creating a Read-Only Root
Filesystem <&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem>`__"
read-only. See the
":ref:`dev-manual/dev-manual-common-tasks:creating a read-only root filesystem`"
section in the Yocto Project Development Tasks Manual for more
information.
@@ -263,8 +264,7 @@ these valid features is as follows:
- *perf:* Installs profiling tools such as ``perf``, ``systemtap``, and
``LTTng``. For general information on user-space tools, see the
`Yocto Project Application Development and the Extensible Software
Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual.
:doc:`../sdk-manual/sdk-manual` manual.
- *ssh-server-dropbear:* Installs the Dropbear minimal SSH server.
@@ -275,12 +275,10 @@ these valid features is as follows:
will not be installed.
- *tools-debug:* Installs debugging tools such as ``strace`` and
``gdb``. For information on GDB, see the "`Debugging With the GNU
Project Debugger (GDB)
Remotely <&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug>`__" section
``gdb``. For information on GDB, see the
":ref:`platdev-gdb-remotedebug`" section
in the Yocto Project Development Tasks Manual. For information on
tracing and profiling, see the `Yocto Project Profiling and Tracing
Manual <&YOCTO_DOCS_PROF_URL;>`__.
tracing and profiling, see the :doc:`../profile-manual/profile-manual`.
- *tools-sdk:* Installs a full SDK that runs on the device.

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

@@ -24,12 +24,13 @@ image you want.
1. Comment out the EXTRA_IMAGE_FEATURES line
2. Set INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
From within the ``poky`` Git repository, you can use the following
command to display the list of directories within the :term:`Source Directory`
that contain image recipe files: $ ls
meta*/recipes*/images/*.bb
that contain image recipe files: ::
$ ls meta*/recipes*/images/*.bb
Following is a list of supported recipes:
@@ -121,9 +122,8 @@ Following is a list of supported recipes:
automated runtime testing. Provides a "known good" image that is
deployed to a separate partition so that you can boot into it and use
it to deploy a second image to be tested. You can find more
information about runtime testing in the "`Performing Automated
Runtime
Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__"
information about runtime testing in the
":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
section in the Yocto Project Development Tasks Manual.
- ``core-image-testmaster-initramfs``: A RAM-based Initial Root
@@ -132,8 +132,8 @@ Following is a list of supported recipes:
- ``core-image-weston``: A very basic Wayland image with a terminal.
This image provides the Wayland protocol libraries and the reference
Weston compositor. For more information, see the "`Using Wayland and
Weston <&YOCTO_DOCS_DEV_URL;#dev-using-wayland-and-weston>`__"
Weston compositor. For more information, see the
":ref:`dev-manual/dev-manual-common-tasks:using wayland and weston`"
section in the Yocto Project Development Tasks Manual.
- ``core-image-x11``: A very basic X11 image with a terminal.

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

@@ -30,7 +30,13 @@ Command: part or partition
==========================
Either of these commands creates a partition on the system and uses the
following syntax: part [mntpoint] partition [mntpoint] If you do not
following syntax:
::
part [mntpoint]
partition [mntpoint]
If you do not
provide mntpoint, Wic creates a partition but does not mount it.
The ``mntpoint`` is where the partition is mounted and must be in one of
@@ -62,20 +68,19 @@ Here is an example that uses "/" as the mountpoint. The command uses
Here is a list that describes other supported options you can use with
the ``part`` and ``partition`` commands:
- *``--size``:* The minimum partition size in MBytes. Specify an
- ``--size``: The minimum partition size in MBytes. Specify an
integer value such as 500. Do not append the number with "MB". You do
not need this option if you use ``--source``.
- *``--fixed-size``:* The exact partition size in MBytes. You cannot
- ``--fixed-size``: The exact partition size in MBytes. You cannot
specify with ``--size``. An error occurs when assembling the disk
image if the partition data is larger than ``--fixed-size``.
- *``--source``:* This option is a Wic-specific option that names the
- ``--source``: This option is a Wic-specific option that names the
source of the data that populates the partition. The most common
value for this option is "rootfs", but you can use any value that
maps to a valid source plugin. For information on the source plugins,
see the "`Using the Wic Plugins
Interface <&YOCTO_DOCS_DEV_URL;#wic-using-the-wic-plugin-interface>`__"
see the ":ref:`dev-manual/dev-manual-common-tasks:using the wic plugin interface`"
section in the Yocto Project Development Tasks Manual.
If you use ``--source rootfs``, Wic creates a partition as large as
@@ -98,10 +103,10 @@ the ``part`` and ``partition`` commands:
creates an empty partition. Consequently, you must use the ``--size``
option to specify the size of the empty partition.
- *``--ondisk`` or ``--ondrive``:* Forces the partition to be created
- ``--ondisk`` or ``--ondrive``: Forces the partition to be created
on a particular disk.
- *``--fstype``:* Sets the file system type for the partition. Valid
- ``--fstype``: Sets the file system type for the partition. Valid
values are:
- ``ext4``
@@ -116,66 +121,66 @@ the ``part`` and ``partition`` commands:
- ``swap``
- *``--fsoptions``:* Specifies a free-form string of options to be used
- ``--fsoptions``: Specifies a free-form string of options to be used
when mounting the filesystem. This string is copied into the
``/etc/fstab`` file of the installed system and should be enclosed in
quotes. If not specified, the default string is "defaults".
- *``--label label``:* Specifies the label to give to the filesystem to
- ``--label label``: Specifies the label to give to the filesystem to
be made on the partition. If the given label is already in use by
another filesystem, a new label is created for the partition.
- *``--active``:* Marks the partition as active.
- ``--active``: Marks the partition as active.
- *``--align (in KBytes)``:* This option is a Wic-specific option that
- ``--align (in KBytes)``: This option is a Wic-specific option that
says to start partitions on boundaries given x KBytes.
- *``--no-table``:* This option is a Wic-specific option. Using the
- ``--no-table``: This option is a Wic-specific option. Using the
option reserves space for the partition and causes it to become
populated. However, the partition is not added to the partition
table.
- *``--exclude-path``:* This option is a Wic-specific option that
- ``--exclude-path``: This option is a Wic-specific option that
excludes the given relative path from the resulting image. This
option is only effective with the rootfs source plugin.
- *``--extra-space``:* This option is a Wic-specific option that adds
- ``--extra-space``: This option is a Wic-specific option that adds
extra space after the space filled by the content of the partition.
The final size can exceed the size specified by the ``--size``
option. The default value is 10 Mbytes.
- *``--overhead-factor``:* This option is a Wic-specific option that
- ``--overhead-factor``: This option is a Wic-specific option that
multiplies the size of the partition by the option's value. You must
supply a value greater than or equal to "1". The default value is
"1.3".
- *``--part-name``:* This option is a Wic-specific option that
- ``--part-name``: This option is a Wic-specific option that
specifies a name for GPT partitions.
- *``--part-type``:* This option is a Wic-specific option that
- ``--part-type``: This option is a Wic-specific option that
specifies the partition type globally unique identifier (GUID) for
GPT partitions. You can find the list of partition type GUIDs at
http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs.
- *``--use-uuid``:* This option is a Wic-specific option that causes
- ``--use-uuid``: This option is a Wic-specific option that causes
Wic to generate a random GUID for the partition. The generated
identifier is used in the bootloader configuration to specify the
root partition.
- *``--uuid``:* This option is a Wic-specific option that specifies the
- ``--uuid``: This option is a Wic-specific option that specifies the
partition UUID.
- *``--fsuuid``:* This option is a Wic-specific option that specifies
- ``--fsuuid``: This option is a Wic-specific option that specifies
the filesystem UUID. You can generate or modify
: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.
- *``--system-id``:* This option is a Wic-specific option that
- ``--system-id``: This option is a Wic-specific option that
specifies the partition system ID, which is a one byte long,
hexadecimal parameter with or without the 0x prefix.
- *``--mkfs-extraopts``:* This option specifies additional options to
- ``--mkfs-extraopts``: This option specifies additional options to
pass to the ``mkfs`` utility. Some default options for certain
filesystems do not take effect. See Wic's help on kickstart (i.e.
``wic help kickstart``).
@@ -195,13 +200,13 @@ supports the following options:
command essentially provides a means of modifying bootloader
configuration.
- *``--timeout``:* Specifies the number of seconds before the
- ``--timeout``: Specifies the number of seconds before the
bootloader times out and boots the default option.
- *``--append``:* Specifies kernel parameters. These parameters will be
- ``--append``: Specifies kernel parameters. These parameters will be
added to the syslinux ``APPEND`` or ``grub`` kernel command line.
- *``--configfile``:* Specifies a user-defined configuration file for
- ``--configfile``: Specifies a user-defined configuration file for
the bootloader. You can provide a full pathname for the file or a
file that exists in the ``canned-wks`` folder. This option overrides
all other bootloader options.

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

@@ -209,7 +209,10 @@ Errors and Warnings
Typically, the way to solve this performance issue is to add "-fPIC"
or "-fpic" to the compiler command-line options. For example, given
software that reads :term:`CFLAGS` when you build it,
you could add the following to your recipe: CFLAGS_append = " -fPIC "
you could add the following to your recipe:
::
CFLAGS_append = " -fPIC "
For more information on text relocations at runtime, see
http://www.akkadia.org/drepper/textrelocs.html.
@@ -224,7 +227,10 @@ Errors and Warnings
variable is being passed to the linker command. A common workaround
for this situation is to pass in ``LDFLAGS`` using
:term:`TARGET_CC_ARCH` within the recipe as
follows: TARGET_CC_ARCH += "${LDFLAGS}"
follows:
::
TARGET_CC_ARCH += "${LDFLAGS}"
 
@@ -244,10 +250,11 @@ Errors and Warnings
The ``/usr/share/info/dir`` should not be packaged. Add the following
line to your :ref:`ref-tasks-install` task or to your
``do_install_append`` within the recipe as follows: rm
${D}${infodir}/dir
``do_install_append`` within the recipe as follows:
::
 
rm ${D}${infodir}/dir
 
- ``Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot]``

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

@@ -17,8 +17,13 @@ month cadence roughly timed each April and October of the year.
Following are examples of some major YP releases with their codenames
also shown. See the "`Major Release
Codenames <#major-release-codenames>`__" section for information on
codenames used with major releases. 2.2 (Morty) 2.1 (Krogoth) 2.0
(Jethro) While the cadence is never perfect, this timescale facilitates
codenames used with major releases.
- 2.2 (Morty)
- 2.1 (Krogoth)
- 2.0 (Jethro)
While the cadence is never perfect, this timescale facilitates
regular releases that have strong QA cycles while not overwhelming users
with too many new releases. The cadence is predictable and avoids many
major holidays in various geographies.
@@ -26,7 +31,13 @@ major holidays in various geographies.
The Yocto project delivers minor (point) releases on an unscheduled
basis and are usually driven by the accumulation of enough significant
fixes or enhancements to the associated major release. Following are
some example past point releases: 2.1.1 2.1.2 2.2.1 The point release
some example past point releases:
- 2.1.1
- 2.1.2
- 2.2.1
The point release
indicates a point in the major release branch where a full QA cycle and
release process validates the content of the new branch.
@@ -39,9 +50,8 @@ 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 :term:`Metadata` with the same
the :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`.
The concept is that branches of :term:`Metadata` with the same
codename are likely to be compatible and thus work together.
.. note::
@@ -95,9 +105,8 @@ provide the Yocto Project team a way to ensure a release is validated.
Additionally, because the test strategies are visible to you as a
developer, you can validate your projects. This section overviews the
available test infrastructure used in the Yocto Project. For information
on how to run available tests on your projects, see the "`Performing
Automated Runtime
Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__"
on how to run available tests on your projects, see the
":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
section in the Yocto Project Development Tasks Manual.
The QA/testing infrastructure is woven into the project to the point
@@ -119,12 +128,12 @@ consists of the following pieces:
- :ref:`testimage.bbclass <ref-classes-testimage*>`: This class
performs runtime testing of images after they are built. The tests
are usually used with `QEMU <&YOCTO_DOCS_DEV_URL;#dev-manual-qemu>`__
are usually used with :doc:`QEMU <../dev-manual/dev-manual-qemu>`
to boot the images and check the combined runtime result boot
operation and functions. However, the test can also use the IP
address of a machine to test.
- ```ptest`` <&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest>`__:
- :ref:`ptest <dev-manual/dev-manual-common-tasks:testing packages with ptest>`:
Runs tests against packages produced during the build for a given
piece of software. The test allows the packages to be be run within a
target image.
@@ -147,7 +156,7 @@ effort has been made to automate the tests so that more people can use
them and the Yocto Project development team can run them faster and more
efficiently.
The Yocto Project's main Autobuilder (``autobuilder.yoctoproject.org``)
The Yocto Project's main Autobuilder (https://autobuilder.yoctoproject.org/)
publicly tests each Yocto Project release's code in the
:term:`OpenEmbedded-Core (OE-Core)`, Poky, and BitBake repositories. The testing
occurs for both the current state of the "master" branch and also for

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

@@ -11,8 +11,8 @@ describes the Source Directory and gives information about those files
and directories.
For information on how to establish a local Source Directory on your
development system, see the "`Locating Yocto Project Source
Files <&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files>`__"
development system, see the
":ref:`dev-manual/dev-manual-start:locating yocto project source files`"
section in the Yocto Project Development Tasks Manual.
.. note::
@@ -42,7 +42,7 @@ itself; consequently, most users do not need to worry about BitBake.
When you run the ``bitbake`` command, the main BitBake executable (which
resides in the ``bitbake/bin/`` directory) starts. Sourcing the
environment setup script (i.e. ````` <#structure-core-script>`__) places
environment setup script (i.e. :ref:`structure-core-script`) places
the ``scripts/`` and ``bitbake/bin/`` directories (in that order) into
the shell's ``PATH`` environment variable.
@@ -59,14 +59,14 @@ generated by the OpenEmbedded build system in its standard configuration
where the source tree is combined with the output. The :term:`Build Directory`
is created initially when you ``source``
the OpenEmbedded build environment setup script (i.e.
````` <#structure-core-script>`__).
:ref:`structure-core-script`).
It is also possible to place output and configuration files in a
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
"````` <#structure-core-script>`__" section.
":ref:`structure-core-script`" section.
.. _handbook:
@@ -103,9 +103,8 @@ metadata to define the Poky reference distribution.
-------------------
This directory contains the Yocto Project reference hardware Board
Support Packages (BSPs). For more information on BSPs, see the `Yocto
Project Board Support Package (BSP) Developer's
Guide <&YOCTO_DOCS_BSP_URL;>`__.
Support Packages (BSPs). For more information on BSPs, see the
:doc:`../bsp-guide/bsp-guide`.
.. _structure-meta-selftest:
@@ -131,7 +130,7 @@ This directory contains template recipes for BSP and kernel development.
This directory contains various integration scripts that implement extra
functionality in the Yocto Project environment (e.g. QEMU scripts). The
````` <#structure-core-script>`__ script prepends this directory to the
:ref:`structure-core-script` script prepends this directory to the
shell's ``PATH`` environment variable.
The ``scripts`` directory has useful scripts that assist in contributing
@@ -154,18 +153,30 @@ When you run this script, your Yocto Project environment is set up, a
:term:`Build Directory` is created, your working
directory becomes the Build Directory, and you are presented with some
simple suggestions as to what to do next, including a list of some
possible targets to build. Here is an example: $ source
oe-init-build-env ### Shell environment set up for builds. ### You can
now run 'bitbake <target>' Common targets are: core-image-minimal
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
possible targets to build. Here is an example:
::
$ source oe-init-build-env
### Shell environment set up for builds. ###
You can now run 'bitbake <target>'
Common targets are:
core-image-minimal
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 :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
Directory <&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory>`__"
See the
":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`"
section in the Yocto Project Development Tasks Manual for more
information.
@@ -175,11 +186,14 @@ you provide a Build Directory argument when you ``source`` the script,
you direct the OpenEmbedded build system to create a Build Directory of
your choice. For example, the following command creates a Build
Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`:
$ source OE_INIT_FILE ~/mybuilds The
OpenEmbedded build system uses the template configuration files, which
::
$ source OE_INIT_FILE ~/mybuilds
The OpenEmbedded build system uses the template configuration files, which
are found by default in the ``meta-poky/conf/`` directory in the Source
Directory. See the "`Creating a Custom Template Configuration
Directory <&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory>`__"
Directory. See the
":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`"
section in the Yocto Project Development Tasks Manual for more
information.
@@ -207,7 +221,7 @@ The Build Directory - ``build/``
The OpenEmbedded build system creates the :term:`Build Directory`
when you run the build environment setup
script ````` <#structure-core-script>`__. If you do not give the Build
script :ref:`structure-core-script`. If you do not give the Build
Directory a specific name when you run the setup script, the name
defaults to ``build/``.
@@ -223,8 +237,7 @@ The OpenEmbedded build system creates this directory when you enable
build history via the ``buildhistory`` class file. The directory
organizes build information into image, packages, and SDK
subdirectories. For information on the build history feature, see the
"`Maintaining Build Output
Quality <&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality>`__"
":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`"
section in the Yocto Project Development Tasks Manual.
.. _structure-build-conf-local.conf:
@@ -248,7 +261,7 @@ which you want to access downloaded files (``DL_DIR``).
If ``local.conf`` is not present when you start the build, the
OpenEmbedded build system creates it from ``local.conf.sample`` when you
``source`` the top-level build environment setup script
````` <#structure-core-script>`__.
:ref:`structure-core-script`.
The source ``local.conf.sample`` file used depends on the
``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/``
@@ -258,7 +271,11 @@ environment. Because the script variable points to the source of the
``local.conf.sample`` file, this implies that you can configure your
build environment from any layer by setting the variable in the
top-level build environment setup script as follows:
TEMPLATECONF=your_layer/conf Once the build process gets the sample
::
TEMPLATECONF=your_layer/conf
Once the build process gets the sample
file, it uses ``sed`` to substitute final
``${``\ :term:`OEROOT`\ ``}`` values for all
``##OEROOT##`` values.
@@ -283,7 +300,7 @@ file, it uses ``sed`` to substitute final
----------------------------
This configuration file defines
`layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__,
:ref:`layers <dev-manual/dev-manual-common-tasks:understanding and creating layers>`,
which are directory trees, traversed (or walked) by BitBake. The
``bblayers.conf`` file uses the :term:`BBLAYERS`
variable to list the layers BitBake tries to find.
@@ -291,7 +308,7 @@ variable to list the layers BitBake tries to find.
If ``bblayers.conf`` is not present when you start the build, the
OpenEmbedded build system creates it from ``bblayers.conf.sample`` when
you ``source`` the top-level build environment setup script (i.e.
````` <#structure-core-script>`__).
:ref:`structure-core-script`).
As with the ``local.conf`` file, the source ``bblayers.conf.sample``
file used depends on the ``$TEMPLATECONF`` script variable, which
@@ -301,10 +318,12 @@ building from the OpenEmbedded-Core environment. Because the script
variable points to the source of the ``bblayers.conf.sample`` file, this
implies that you can base your build from any layer by setting the
variable in the top-level build environment setup script as follows:
TEMPLATECONF=your_layer/conf Once the build process gets the sample
file, it uses ``sed`` to substitute final
``${``\ :term:`OEROOT`\ ``}`` values for all
``##OEROOT##`` values.
::
TEMPLATECONF=your_layer/conf
Once the build process gets the sample file, it uses ``sed`` to substitute final
``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values.
.. note::
@@ -395,9 +414,8 @@ This directory contains any "end result" output from the OpenEmbedded
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
"`Application Development
SDK <&YOCTO_DOCS_OM_URL;#sdk-dev-environment>`__" sections in the Yocto
":ref:`images-dev-environment`" and
":ref:`sdk-dev-environment`" sections in the Yocto
Project Overview and Concepts Manual.
.. _structure-build-tmp-deploy-deb:
@@ -434,9 +452,8 @@ This directory receives package licensing information. For example, the
directory contains sub-directories for ``bash``, ``busybox``, and
``glibc`` (among others) that in turn contain appropriate ``COPYING``
license files with other licensing information. For information on
licensing, see the "`Maintaining Open Source License Compliance During
Your Product's
Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__"
licensing, see the
":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
section in the Yocto Project Development Tasks Manual.
.. _structure-build-tmp-deploy-images:
@@ -461,8 +478,11 @@ image again.
If you do accidentally delete files here, you will need to force them to
be re-created. In order to do that, you will need to know the target
that produced them. For example, these commands rebuild and re-create
the kernel files: $ bitbake -c clean virtual/kernel $ bitbake
virtual/kernel
the kernel files:
::
$ bitbake -c clean virtual/kernel
$ bitbake virtual/kernel
.. _structure-build-tmp-deploy-sdk:
@@ -472,8 +492,7 @@ virtual/kernel
The OpenEmbedded build system creates this directory to hold toolchain
installer scripts which, when executed, install the sysroot that matches
your target hardware. You can find out more about these installers in
the "`Building an SDK
Installer <&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer>`__"
the ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`"
section in the Yocto Project Application Development and the Extensible
Software Development Kit (eSDK) manual.
@@ -540,8 +559,8 @@ the files in the directory are empty of data, BitBake uses the filenames
and timestamps for tracking purposes.
For information on how BitBake uses stamp files to determine if a task
should be rerun, see the "`Stamp Files and the Rerunning of
Tasks <&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks>`__"
should be rerun, see the
":ref:`overview-manual/overview-manual-concepts:stamp files and the rerunning of tasks`"
section in the Yocto Project Overview and Concepts Manual.
.. _structure-build-tmp-log:
@@ -573,8 +592,7 @@ built within the Yocto Project. For this package, a work directory of
``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred
to as the ``WORKDIR``, is created. Within this directory, the source is
unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt.
(See the "`Using Quilt in Your
Workflow <&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow>`__" section in
(See the ":ref:`using-a-quilt-workflow`" section in
the Yocto Project Development Tasks Manual for more information.) Within
the ``linux-qemux86-standard-build`` directory, standard Quilt
directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and

181
documentation/ref-manual/ref-system-requirements.rst
View File

@@ -14,18 +14,15 @@ descriptions, and so forth as needed during the course of using the
Yocto Project.
For introductory information on the Yocto Project, see the
:yocto_home:`Yocto Project Website <>` and the "`Yocto Project
Development
Environment <&YOCTO_DOCS_OM_URL;#overview-development-environment>`__"
:yocto_home:`Yocto Project Website <>` and the
":ref:`overview-manual/overview-manual-development-environment:the yocto project development environment`"
chapter in the Yocto Project Overview and Concepts Manual.
If you want to use the Yocto Project to quickly build an image without
having to understand concepts, work through the `Yocto Project Quick
Build <&YOCTO_DOCS_BRIEF_URL;>`__ document. You can find "how-to"
information in the `Yocto Project Development Tasks
Manual <&YOCTO_DOCS_DEV_URL;>`__. You can find Yocto Project overview
and conceptual information in the `Yocto Project Overview and Concepts
Manual <&YOCTO_DOCS_OM_URL;>`__.
having to understand concepts, work through the
:doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document. You can find "how-to"
information in the :doc:`../dev-manual/dev-manual`. You can find Yocto Project overview
and conceptual information in the :doc:`../overview-manual/overview-manual`.
.. note::
@@ -95,12 +92,11 @@ distributions:
WSLv2, if you still decide to use WSL please upgrade to WSLv2.
- If you encounter problems, please go to `Yocto Project
Bugzilla <&YOCTO_BUGZILLA_URL;>`__ and submit a bug. We are
Bugzilla <http://bugzilla.yoctoproject.org>`__ and submit a bug. We are
interested in hearing about your experience. For information on
how to submit a bug, see the Yocto Project
:yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>`
and the "`Submitting a Defect Against the Yocto
Project <&YOCTO_DOCS_DEV_URL;#submitting-a-defect-against-the-yocto-project>`__"
and the ":ref:`dev-manual/dev-manual-common-tasks:submitting a defect against the yocto project`"
section in the Yocto Project Development Tasks Manual.
@@ -126,19 +122,28 @@ supported Ubuntu or Debian Linux distribution:
might experience QEMU build failures due to the package installing
its own custom ``/usr/include/linux/soundcard.h`` on the Debian
system. If you run into this situation, either of the following
solutions exist: $ sudo apt-get build-dep qemu $ sudo apt-get
remove oss4-dev
solutions exist:
::
$ sudo apt-get build-dep qemu
$ sudo apt-get remove oss4-dev
- For Debian-8, ``python3-git`` and ``pylint3`` are no longer
available via ``apt-get``. $ sudo pip3 install GitPython
pylint==1.9.5
available via ``apt-get``.
::
$ sudo pip3 install GitPython pylint==1.9.5
- *Essentials:* Packages needed to build an image on a headless system:
$ sudo apt-get install UBUNTU_HOST_PACKAGES_ESSENTIAL
::
$ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
- *Documentation:* Packages needed if you are going to build out the
Yocto Project documentation manuals: $ sudo apt-get install make
xsltproc docbook-utils fop dblatex xmlto
Yocto Project documentation manuals:
::
$ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
Fedora Packages
---------------
@@ -147,12 +152,17 @@ The following list shows the required packages by function given a
supported Fedora Linux distribution:
- *Essentials:* Packages needed to build an image for a headless
system: $ sudo dnf install FEDORA_HOST_PACKAGES_ESSENTIAL
system:
::
$ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
- *Documentation:* Packages needed if you are going to build out the
Yocto Project documentation manuals: $ sudo dnf install
docbook-style-dsssl docbook-style-xsl \\ docbook-dtds docbook-utils
fop libxslt dblatex xmlto
Yocto Project documentation manuals:
::
$ sudo dnf install docbook-style-dsssl docbook-style-xsl \
docbook-dtds docbook-utils fop libxslt dblatex xmlto
openSUSE Packages
-----------------
@@ -161,7 +171,10 @@ The following list shows the required packages by function given a
supported openSUSE Linux distribution:
- *Essentials:* Packages needed to build an image for a headless
system: $ sudo zypper install OPENSUSE_HOST_PACKAGES_ESSENTIAL
system:
::
$ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
- *Documentation:* Packages needed if you are going to build out the
Yocto Project documentation manuals: $ sudo zypper install dblatex
@@ -174,7 +187,10 @@ The following list shows the required packages by function given a
supported CentOS-7 Linux distribution:
- *Essentials:* Packages needed to build an image for a headless
system: $ sudo yum install CENTOS7_HOST_PACKAGES_ESSENTIAL
system:
::
$ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL;
.. note::
@@ -187,9 +203,11 @@ supported CentOS-7 Linux distribution:
``epel-release``.
- *Documentation:* Packages needed if you are going to build out the
Yocto Project documentation manuals: $ sudo yum install
docbook-style-dsssl docbook-style-xsl \\ docbook-dtds docbook-utils
fop libxslt dblatex xmlto
Yocto Project documentation manuals:
::
$ sudo yum install docbook-style-dsssl docbook-style-xsl \
docbook-dtds docbook-utils fop libxslt dblatex xmlto
CentOS-8 Packages
-----------------
@@ -198,7 +216,10 @@ The following list shows the required packages by function given a
supported CentOS-8 Linux distribution:
- *Essentials:* Packages needed to build an image for a headless
system: $ sudo dnf install CENTOS8_HOST_PACKAGES_ESSENTIAL
system:
::
$ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL;
.. note::
@@ -214,9 +235,11 @@ supported CentOS-8 Linux distribution:
``epel-release``.
- *Documentation:* Packages needed if you are going to build out the
Yocto Project documentation manuals: $ sudo dnf install
docbook-style-dsssl docbook-style-xsl \\ docbook-dtds docbook-utils
fop libxslt dblatex xmlto
Yocto Project documentation manuals:
::
$ sudo dnf install docbook-style-dsssl docbook-style-xsl \\
docbook-dtds docbook-utils fop libxslt dblatex xmlto
Required Git, tar, Python and gcc Versions
==========================================
@@ -251,10 +274,14 @@ The ``install-buildtools`` script is the easiest of the three methods by
which you can get these tools. It downloads a pre-built buildtools
installer and automatically installs the tools for you:
1. Execute the ``install-buildtools`` script. Here is an example: $ cd
poky $ scripts/install-buildtools --without-extended-buildtools \\
--base-url https://downloads.yoctoproject.org/releases/yocto \\ --release yocto-DISTRO \\
--installer-version DISTRO
1. Execute the ``install-buildtools`` script. Here is an example:
::
$ cd poky
$ scripts/install-buildtools --without-extended-buildtools \
--base-url https://downloads.yoctoproject.org/releases/yocto \
--release yocto-&DISTRO; \
--installer-version &DISTRO;
During execution, the buildtools tarball will be downloaded, the
checksum of the download will be verified, the installer will be run
@@ -263,17 +290,25 @@ installer and automatically installs the tools for you:
To avoid the need of ``sudo`` privileges, the ``install-buildtools``
script will by default tell the installer to install in:
/path/to/poky/buildtools
::
/path/to/poky/buildtools
If your host development system needs the additional tools provided
in the ``buildtools-extended`` tarball, you can instead execute the
``install-buildtools`` script with the default parameters: $ cd poky
$ scripts/install-buildtools
``install-buildtools`` script with the default parameters:
::
$ cd poky
$ scripts/install-buildtools
2. Source the tools environment setup script by using a command like the
following: $ source
/path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux Of
course, you need to supply your installation directory and be sure to
following:
::
$ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux
Of course, you need to supply your installation directory and be sure to
use the right file (i.e. i586 or x86_64).
After you have sourced the setup script, the tools are added to
@@ -290,21 +325,30 @@ Downloading a Pre-Built ``buildtools`` Tarball
Downloading and running a pre-built buildtools installer is the easiest
of the two methods by which you can get these tools:
1. Locate and download the ``*.sh`` at
` <&YOCTO_RELEASE_DL_URL;/buildtools/>`__.
1. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/
2. Execute the installation script. Here is an example for the
traditional installer: $ sh
~/Downloads/x86_64-buildtools-nativesdk-standalone-DISTRO.sh Here is
an example for the extended installer: $ sh
~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-DISTRO.sh
traditional installer:
::
$ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-DISTRO.sh
Here is an example for the extended installer:
::
$ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-DISTRO.sh
During execution, a prompt appears that allows you to choose the
installation directory. For example, you could choose the following:
/home/your-username/buildtools
3. Source the tools environment setup script by using a command like the
following: $ source
/home/your_username/buildtools/environment-setup-i586-poky-linux Of
following:
::
$ source /home/your_username/buildtools/environment-setup-i586-poky-linux
Of
course, you need to supply your installation directory and be sure to
use the right file (i.e. i585 or x86-64).
@@ -330,11 +374,17 @@ installer:
1. On the machine that is able to run BitBake, be sure you have set up
your build environment with the setup script
(````` <#structure-core-script>`__).
(:ref:`structure-core-script`).
2. Run the BitBake command to build the tarball: $ bitbake
buildtools-tarball or run the BitBake command to build the extended
tarball: $ bitbake buildtools-extended-tarball
2. Run the BitBake command to build the tarball:
::
$ bitbake buildtools-tarball
or run the BitBake command to build the extended tarball:
::
$ bitbake buildtools-extended-tarball
.. note::
@@ -355,18 +405,27 @@ installer:
4. On the machine that does not meet the requirements, run the ``.sh``
file to install the tools. Here is an example for the traditional
installer: $ sh
~/Downloads/x86_64-buildtools-nativesdk-standalone-DISTRO.sh Here is
an example for the extended installer: $ sh
~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-DISTRO.sh
installer:
::
$ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
Here is an example for the extended installer:
::
$ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
During execution, a prompt appears that allows you to choose the
installation directory. For example, you could choose the following:
/home/your_username/buildtools
5. Source the tools environment setup script by using a command like the
following: $ source
/home/your_username/buildtools/environment-setup-x86_64-poky-linux Of
course, you need to supply your installation directory and be sure to
following:
::
$ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux
Of course, you need to supply your installation directory and be sure to
use the right file (i.e. i586 or x86_64).
After you have sourced the setup script, the tools are added to

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

@@ -109,7 +109,7 @@ after other tasks works the same way.
::
do_build[recrdeptask] += "do_deploy"
See the "
Dependencies
@@ -143,8 +143,7 @@ The ``do_image`` task performs pre-processing on the image through the
:term:`IMAGE_PREPROCESS_COMMAND` and
dynamically generates supporting ``do_image_*`` tasks as needed.
For more information on image creation, see the "`Image
Generation <&YOCTO_DOCS_OM_URL;#image-generation-dev-environment>`__"
For more information on image creation, see the ":ref:`image-generation-dev-environment`"
section in the Yocto Project Overview and Concepts Manual.
.. _ref-tasks-image-complete:
@@ -162,8 +161,8 @@ The ``do_image_complete`` task performs post-processing on the image
through the
:term:`IMAGE_POSTPROCESS_COMMAND`.
For more information on image creation, see the "`Image
Generation <&YOCTO_DOCS_OM_URL;#image-generation-dev-environment>`__"
For more information on image creation, see the
":ref:`image-generation-dev-environment`"
section in the Yocto Project Overview and Concepts Manual.
.. _ref-tasks-install:
@@ -176,10 +175,9 @@ Copies files that are to be packaged into the holding area
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.
:ref:`ref-tasks-package`,
```do_package_write_*`` <#ref-tasks-package_write_deb>`__, and
:ref:`ref-tasks-package`, ``do_package_write_*``, and
:ref:`ref-tasks-rootfs`), run under
`fakeroot <&YOCTO_DOCS_OM_URL;#fakeroot-and-pseudo>`__.
:ref:`fakeroot <overview-manual/overview-manual-concepts:fakeroot and pseudo>`.
.. note::
@@ -187,9 +185,8 @@ that either directly or indirectly depend on the installed files (e.g.
of the installed files to unintended values. Some methods of copying
files, notably when using the recursive ``cp`` command, can preserve
the UID and/or GID of the original file, which is usually not what
you want. The
```host-user-contaminated`` <#insane-host-user-contaminated>`__ QA
check checks for files that probably have the wrong ownership.
you want. The ``host-user-contaminated`` QA check checks for files
that probably have the wrong ownership.
Safe methods for installing files include the following:
@@ -223,9 +220,8 @@ variables.
The ``do_package`` task, in conjunction with the
:ref:`ref-tasks-packagedata` task, also saves some
important package metadata. For additional information, see the
:term:`PKGDESTWORK` variable and the "`Automatically
Added Runtime
Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__"
:term:`PKGDESTWORK` variable and the
":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`"
section in the Yocto Project Overview and Concepts Manual.
.. _ref-tasks-package_qa:
@@ -243,8 +239,8 @@ see the :ref:`insane <ref-classes-insane>` class.
Creates Debian packages (i.e. ``*.deb`` files) and places them in the
``${``\ :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 package feeds area. For more information, see the
":ref:`package-feeds-dev-environment`" section in
the Yocto Project Overview and Concepts Manual.
.. _ref-tasks-package_write_ipk:
@@ -254,8 +250,8 @@ the Yocto Project Overview and Concepts Manual.
Creates IPK packages (i.e. ``*.ipk`` files) and places them in the
``${``\ :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 package feeds area. For more information, see the
":ref:`package-feeds-dev-environment`" section in
the Yocto Project Overview and Concepts Manual.
.. _ref-tasks-package_write_rpm:
@@ -265,8 +261,8 @@ the Yocto Project Overview and Concepts Manual.
Creates RPM packages (i.e. ``*.rpm`` files) and places them in the
``${``\ :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 package feeds area. For more information, see the
":ref:`package-feeds-dev-environment`" section in
the Yocto Project Overview and Concepts Manual.
.. _ref-tasks-package_write_tar:
@@ -276,8 +272,8 @@ the Yocto Project Overview and Concepts Manual.
Creates tarballs and places them in the
``${``\ :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 package feeds area. For more information, see the
":ref:`package-feeds-dev-environment`" section in
the Yocto Project Overview and Concepts Manual.
.. _ref-tasks-packagedata:
@@ -312,8 +308,14 @@ and kept in a subdirectory of the directory holding the recipe file. For
example, consider the
:yocto_git:`bluez5 </cgit/cgit.cgi/poky/tree/meta/recipes-connectivity/bluez5>`
recipe from the OE-Core layer (i.e. ``poky/meta``):
poky/meta/recipes-connectivity/bluez5 This recipe has two patch files
located here: poky/meta/recipes-connectivity/bluez5/bluez5
::
poky/meta/recipes-connectivity/bluez5
This recipe has two patch files located here:
::
poky/meta/recipes-connectivity/bluez5/bluez5
In the ``bluez5`` recipe, the ``SRC_URI`` statements point to the source
and patch files needed to build the package.
@@ -331,23 +333,35 @@ and patch files needed to build the package.
As mentioned earlier, the build system treats files whose file types are
``.patch`` and ``.diff`` as patch files. However, you can use the
"apply=yes" parameter with the ``SRC_URI`` statement to indicate any
file as a patch file: SRC_URI = " \\ git://path_to_repo/some_package \\
file://file;apply=yes \\ "
file as a patch file:
::
SRC_URI = " \\
git://path_to_repo/some_package \\
file://file;apply=yes \\
"
Conversely, if you have a directory full of patch files and you want to
exclude some so that the ``do_patch`` task does not apply them during
the patch phase, you can use the "apply=no" parameter with the
``SRC_URI`` statement: SRC_URI = " \\ git://path_to_repo/some_package \\
file://path_to_lots_of_patch_files \\
file://path_to_lots_of_patch_files/patch_file5;apply=no \\ " In the
``SRC_URI`` statement:
::
SRC_URI = " \
git://path_to_repo/some_package \
file://path_to_lots_of_patch_files \
file://path_to_lots_of_patch_files/patch_file5;apply=no \
"
In the
previous example, assuming all the files in the directory holding the
patch files end with either ``.patch`` or ``.diff``, every file would be
applied as a patch by default except for the patch_file5 patch.
You can find out more about the patching process in the
"`Patching <&YOCTO_DOCS_OM_URL;#patching-dev-environment>`__" section in
the Yocto Project Overview and Concepts Manual and the "`Patching
Code <&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code>`__" section in the
":ref:`patching-dev-environment`" section in
the Yocto Project Overview and Concepts Manual and the
":ref:`new-recipe-patching-code`" section in the
Yocto Project Development Tasks Manual.
.. _ref-tasks-populate_lic:
@@ -364,8 +378,7 @@ the image is constructed.
-------------------
Creates the file and directory structure for an installable SDK. See the
"`SDK
Generation <&YOCTO_DOCS_OM_URL;#sdk-generation-dev-environment>`__"
":ref:`sdk-generation-dev-environment`"
section in the Yocto Project Overview and Concepts Manual for more
information.
@@ -420,8 +433,7 @@ Unpacks the source code into a working directory pointed to by
``${``\ :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
Fetching <&YOCTO_DOCS_OM_URL;#source-fetching-dev-environment>`__"
":ref:`source-fetching-dev-environment`"
section in the Yocto Project Overview and Concepts Manual and also see
the ``WORKDIR`` and ``S`` variable descriptions.
@@ -442,16 +454,24 @@ of the recipe exists upstream and a status of not updated, updated, or
unknown.
To check the upstream version and status of a recipe, use the following
devtool commands: $ devtool latest-version $ devtool
check-upgrade-status See the "```devtool`` Quick
Reference <#ref-devtool-reference>`__" chapter for more information on
``devtool``. See the "`Checking on the Upgrade Status of a
Recipe <&YOCTO_DOCS_REF_URL;#devtool-checking-on-the-upgrade-status-of-a-recipe>`__"
devtool commands:
::
$ devtool latest-version
$ devtool check-upgrade-status
See the ":ref:`ref-manual/ref-devtool-reference:\`\`devtool\`\` quick reference`"
chapter for more information on
``devtool``. See the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`"
section for information on checking the upgrade status of a recipe.
To build the ``checkpkg`` task, use the ``bitbake`` command with the
"-c" option and task name: $ bitbake core-image-minimal -c checkpkg By
default, the results are stored in :term:`$LOG_DIR <LOG_DIR>` (e.g.
"-c" option and task name:
::
$ bitbake core-image-minimal -c checkpkg
By default, the results are stored in :term:`$LOG_DIR <LOG_DIR>` (e.g.
``$BUILD_DIR/tmp/log``).
.. _ref-tasks-checkuri:
@@ -473,11 +493,13 @@ Removes all output files for a target from the
:ref:`ref-tasks-install`, and
:ref:`ref-tasks-package`).
You can run this task using BitBake as follows: $ bitbake -c clean
recipe
You can run this task using BitBake as follows:
::
$ bitbake -c clean recipe
Running this task does not remove the
`sstate <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__ cache files.
:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>` cache files.
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
@@ -490,14 +512,16 @@ use the :ref:`ref-tasks-cleansstate` task instead
---------------
Removes all output files, shared state
(`sstate <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__) cache, and
(:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`) cache, and
downloaded source files for a target (i.e. the contents of
:term:`DL_DIR`). Essentially, the ``do_cleanall`` task is
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
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 :ref:`ref-tasks-fetch`
@@ -509,14 +533,16 @@ task.
------------------
Removes all output files and shared state
(`sstate <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__) cache for a
(:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`) cache for a
target. Essentially, the ``do_cleansstate`` task is identical to the
:ref:`ref-tasks-clean` task with the added removal of
shared state (`sstate <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__)
shared state (`:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`)
cache.
You can run this task using BitBake as follows: $ bitbake -c cleansstate
recipe
You can run this task using BitBake as follows:
::
$ bitbake -c cleansstate recipe
When you run the ``do_cleansstate`` task, the OpenEmbedded build system
no longer uses any sstate. Consequently, building the recipe from
@@ -531,8 +557,8 @@ scratch is guaranteed.
as follows:
::
$ bitbake -f -c do_cleansstate target
$ bitbake -f -c do_cleansstate target
.. _ref-tasks-devpyshell:
@@ -542,9 +568,7 @@ scratch is guaranteed.
Starts a shell in which an interactive Python interpreter allows you to
interact with the BitBake build environment. From within this shell, you
can directly examine and set bits from the data store and execute
functions as if within the BitBake environment. See the "`Using a
Development Python
Shell <&YOCTO_DOCS_DEV_URL;#platdev-appdev-devpyshell>`__" section in
functions as if within the BitBake environment. See the ":ref:`platdev-appdev-devpyshell`" section in
the Yocto Project Development Tasks Manual for more information about
using ``devpyshell``.
@@ -554,8 +578,7 @@ using ``devpyshell``.
---------------
Starts a shell whose environment is set up for development, debugging,
or both. See the "`Using a Development
Shell <&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell>`__" section in the
or both. See the ":ref:`platdev-appdev-devshell`" section in the
Yocto Project Development Tasks Manual for more information about using
``devshell``.
@@ -571,8 +594,7 @@ Lists all defined tasks for a target.
``do_package_index``
--------------------
Creates or updates the index in the `Package
Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__ area.
Creates or updates the index in the `:ref:`package-feeds-dev-environment` area.
.. note::
@@ -615,8 +637,7 @@ has some more information about these types of images.
-------------
Creates the root filesystem (file and directory structure) for an image.
See the "`Image
Generation <&YOCTO_DOCS_OM_URL;#image-generation-dev-environment>`__"
See the ":ref:`image-generation-dev-environment`"
section in the Yocto Project Overview and Concepts Manual for more
information on how the root filesystem is created.
@@ -626,9 +647,8 @@ information on how the root filesystem is created.
----------------
Boots an image and performs runtime tests within the image. For
information on automatically testing images, see the "`Performing
Automated Runtime
Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__"
information on automatically testing images, see the
":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
section in the Yocto Project Development Tasks Manual.
.. _ref-tasks-testimage_auto:
@@ -640,9 +660,8 @@ Boots an image and performs runtime tests within the image immediately
after it has been built. This task is enabled when you set
:term:`TESTIMAGE_AUTO` equal to "1".
For information on automatically testing images, see the "`Performing
Automated Runtime
Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__"
For information on automatically testing images, see the
":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
section in the Yocto Project Development Tasks Manual.
Kernel-Related Tasks
@@ -674,9 +693,13 @@ changes made by the user with other methods (i.e. using
(:ref:`ref-tasks-kernel_menuconfig`). Once the
file of differences is created, it can be used to create a config
fragment that only contains the differences. You can invoke this task
from the command line as follows: $ bitbake linux-yocto -c diffconfig
For more information, see the "`Creating Configuration
Fragments <&YOCTO_DOCS_KERNEL_DEV_URL;#creating-config-fragments>`__"
from the command line as follows:
::
$ bitbake linux-yocto -c diffconfig
For more information, see the
":ref:`kernel-dev/kernel-dev-common:creating configuration fragments`"
section in the Yocto Project Linux Kernel Development Manual.
.. _ref-tasks-kernel_checkout:
@@ -701,9 +724,13 @@ Validates the configuration produced by the
configuration does not appear in the final ``.config`` file or when you
override a policy configuration in a hardware configuration fragment.
You can run this task explicitly and view the output by using the
following command: $ bitbake linux-yocto -c kernel_configcheck -f For
more information, see the "`Validating
Configuration <&YOCTO_DOCS_KERNEL_DEV_URL;#validating-configuration>`__"
following command:
::
$ bitbake linux-yocto -c kernel_configcheck -f
For more information, see the
":ref:`kernel-dev/kernel-dev-common:validating configuration`"
section in the Yocto Project Linux Kernel Development Manual.
.. _ref-tasks-kernel_configme:
@@ -733,10 +760,9 @@ tool, which you then use to modify the kernel configuration.
::
$ bitbake linux-yocto -c menuconfig
See the "`Using
``menuconfig`` <&YOCTO_DOCS_KERNEL_DEV_URL;#using-menuconfig>`__"
See the ":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``"
section in the Yocto Project Linux Kernel Development Manual for more
information on this configuration tool.
@@ -760,7 +786,7 @@ which can then be applied by subsequent tasks such as
Runs ``make menuconfig`` for the kernel. For information on
``menuconfig``, see the
"`Using  ``menuconfig`` <&YOCTO_DOCS_KERNEL_DEV_URL;#using-menuconfig>`__"
":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``"
section in the Yocto Project Linux Kernel Development Manual.
.. _ref-tasks-savedefconfig:
@@ -773,8 +799,10 @@ instead of the default defconfig. The saved defconfig contains the
differences between the default defconfig and the changes made by the
user using other methods (i.e. the
:ref:`ref-tasks-kernel_menuconfig` task. You
can invoke the task using the following command: $ bitbake linux-yocto
-c savedefconfig
can invoke the task using the following command:
::
$ bitbake linux-yocto -c savedefconfig
.. _ref-tasks-shared_workdir:

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

@@ -26,7 +26,12 @@ universal, the list includes them just in case:
When you name an append file, you can use the "``%``" wildcard character
to allow for matching recipe names. For example, suppose you have an
append file named as follows: busybox_1.21.%.bbappend That append file
append file named as follows:
::
busybox_1.21.%.bbappend
That append file
would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So,
the append file would match any of the following recipe names:
@@ -68,11 +73,11 @@ universal, the list includes them just in case:
examples assume your :term:`Source Directory` is named ``poky``:
- Create the Build Directory inside your Source Directory and let
the name of the Build Directory default to ``build``:
the name of the Build Directory default to ``build``:
.. code-block:: shell
$ cd $HOME/poky
$ cd $HOME/poky
$ source oe-init-build-env
- Create the Build Directory inside your home directory and
@@ -80,18 +85,18 @@ universal, the list includes them just in case:
.. code-block:: shell
$ cd $HOME
$ cd $HOME
$ source poky/oe-init-build-env test-builds
- Provide a directory path and specifically name the Build
Directory. Any intermediate folders in the pathname must exist.
This next example creates a Build Directory named
``YP-POKYVERSION`` in your home directory within the existing
directory ``mybuilds``:
directory ``mybuilds``:
.. code-block:: shell
$ cd $HOME
$ cd $HOME
$ source $HOME/poky/oe-init-build-env $HOME/mybuilds/YP-POKYVERSION
.. note::
@@ -349,8 +354,9 @@ universal, the list includes them just in case:
While it is not recommended that you use tarball expansion to set up
the Source Directory, if you do, the top-level directory name of the
Source Directory is derived from the Yocto Project release tarball.
For example, downloading and unpacking ```` results in a Source
Directory whose root folder is named ````.
For example, downloading and unpacking
:yocto_dl:`releases/yocto/&DISTRO_REL_TAG;/&YOCTO_POKY;.tar.bz2`
results in a Source Directory whose root folder is named ``poky``.
It is important to understand the differences between the Source
Directory created by unpacking a released tarball as compared to
@@ -366,8 +372,8 @@ universal, the list includes them just in case:
repository.
For more information on concepts related to Git repositories,
branches, and tags, see the "`Repositories, Tags, and
Branches <&YOCTO_DOCS_OM_URL;#repositories-tags-and-branches>`__"
branches, and tags, see the
":ref:`overview-manual/overview-manual-development-environment:repositories, tags, and branches`"
section in the Yocto Project Overview and Concepts Manual.
Task
@@ -381,7 +387,7 @@ universal, the list includes them just in case:
The interface enables you to
configure and run your builds. Information about builds is collected
and stored in a database. For information on Toaster, see the
`Toaster User Manual <&YOCTO_DOCS_TOAST_URL;>`__.
:doc:`../toaster-manual/toaster-manual`.
Upstream
A reference to source code or repositories that are not

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

File diff suppressed because it is too large Load Diff

88
documentation/ref-manual/ref-varlocality.rst
View File

@@ -25,23 +25,23 @@ Distribution (Distro)
This section lists variables whose configuration context is the
distribution, or distro.
- ``DISTRO``
- :term:`DISTRO`
- ``DISTRO_NAME``
- :term:`DISTRO_NAME`
- ``DISTRO_VERSION``
- :term:`DISTRO_VERSION`
- ``MAINTAINER``
- :term:`MAINTAINER`
- ``PACKAGE_CLASSES``
- :term:`PACKAGE_CLASSES`
- ``TARGET_OS``
- :term:`TARGET_OS`
- ``TARGET_FPU``
- :term:`TARGET_FPU`
- ``TCMODE``
- :term:`TCMODE`
- ``TCLIBC``
- :term:`TCLIBC`
.. _ref-varlocality-config-machine:
@@ -50,23 +50,23 @@ Machine
This section lists variables whose configuration context is the machine.
- ``TARGET_ARCH``
- :term:`TARGET_ARCH`
- ``SERIAL_CONSOLES``
- :term:`SERIAL_CONSOLES`
- ``PACKAGE_EXTRA_ARCHS``
- :term:`PACKAGE_EXTRA_ARCHS`
- ``IMAGE_FSTYPES``
- :term:`IMAGE_FSTYPES`
- ``MACHINE_FEATURES``
- :term:`MACHINE_FEATURES`
- ``MACHINE_EXTRA_RDEPENDS``
- :term:`MACHINE_EXTRA_RDEPENDS`
- ``MACHINE_EXTRA_RRECOMMENDS``
- :term:`MACHINE_EXTRA_RRECOMMENDS`
- ``MACHINE_ESSENTIAL_EXTRA_RDEPENDS``
- :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
- ``MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS``
- :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
.. _ref-varlocality-config-local:
@@ -76,23 +76,23 @@ Local
This section lists variables whose configuration context is the local
configuration through the ``local.conf`` file.
- ``DISTRO``
- :term:`DISTRO`
- ``MACHINE``
- :term:`MACHINE`
- ``DL_DIR``
- :term:`DL_DIR`
- ``BBFILES``
- :term:`BBFILES`
- ``EXTRA_IMAGE_FEATURES``
- :term:`EXTRA_IMAGE_FEATURES`
- ``PACKAGE_CLASSES``
- :term:`PACKAGE_CLASSES`
- ``BB_NUMBER_THREADS``
- :term:`BB_NUMBER_THREADS`
- ``BBINCLUDELOGS``
- :term:`BBINCLUDELOGS`
- ``ENABLE_BINARY_LOCALE_GENERATION``
- :term:`ENABLE_BINARY_LOCALE_GENERATION`
.. _ref-varlocality-recipes:
@@ -109,11 +109,11 @@ Required
This section lists variables that are required for recipes.
- ``LICENSE``
- :term:`LICENSE`
- ``LIC_FILES_CHKSUM``
- :term:`LIC_FILES_CHKSUM`
- ``SRC_URI`` - used in recipes that fetch local or remote files.
- :term:`SRC_URI` - used in recipes that fetch local or remote files.
.. _ref-varlocality-recipe-dependencies:
@@ -122,15 +122,15 @@ Dependencies
This section lists variables that define recipe dependencies.
- ``DEPENDS``
- :term:`DEPENDS`
- ``RDEPENDS``
- :term:`RDEPENDS`
- ``RRECOMMENDS``
- :term:`RRECOMMENDS`
- ``RCONFLICTS``
- :term:`RCONFLICTS`
- ``RREPLACES``
- :term:`RREPLACES`
.. _ref-varlocality-recipe-paths:
@@ -139,11 +139,11 @@ Paths
This section lists variables that define recipe paths.
- ``WORKDIR``
- :term:`WORKDIR`
- ``S``
- :term:`S`
- ``FILES``
- :term:`FILES`
.. _ref-varlocality-recipe-build:
@@ -153,14 +153,14 @@ Extra Build Information
This section lists variables that define extra build information for
recipes.
- ``DEFAULT_PREFERENCE``
- :term:`DEFAULT_PREFERENCE`
- ``EXTRA_OECMAKE``
- :term:`EXTRA_OECMAKE`
- ``EXTRA_OECONF``
- :term:`EXTRA_OECONF`
- ``EXTRA_OEMAKE``
- :term:`EXTRA_OEMAKE`
- ``PACKAGECONFIG_CONFARGS``
- :term:`PACKAGECONFIG_CONFARGS`
- ``PACKAGES``
- :term:`PACKAGES`

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

@@ -23,8 +23,7 @@ The Yocto Project gladly accepts contributions. You can submit changes
to the project either by creating and sending pull requests, or by
submitting patches through email. For information on how to do both as
well as information on how to identify the maintainer for each area of
code, see the "`Submitting a Change to the Yocto
Project <&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change>`__" section in the
code, see the ":ref:`how-to-submit-a-change`" section in the
Yocto Project Development Tasks Manual.
.. _resources-bugtracker:
@@ -48,8 +47,7 @@ A general procedure and guidelines exist for when you use Bugzilla to
submit a bug. For information on how to use Bugzilla to submit a bug
against the Yocto Project, see the following:
- The "`Submitting a Defect Against the Yocto
Project <&YOCTO_DOCS_DEV_URL;#submitting-a-defect-against-the-yocto-project>`__"
- The ":ref:`dev-manual/dev-manual-common-tasks:submitting a defect against the yocto project`"
section in the Yocto Project Development Tasks Manual.
- The Yocto Project :yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>`
@@ -67,22 +65,22 @@ and announcements. To subscribe to one of the following mailing lists,
click on the appropriate URL in the following list and follow the
instructions:
- ` <&YOCTO_LISTS_URL;/listinfo/yocto>`__ - General Yocto Project
- https://lists.yoctoproject.org/g/yocto - General Yocto Project
discussion mailing list.
- ` <&OE_LISTS_URL;/listinfo/openembedded-core>`__ - Discussion mailing
- https://lists.openembedded.org/g/openembedded-core - Discussion mailing
list about OpenEmbedded-Core (the core metadata).
- ` <&OE_LISTS_URL;/listinfo/openembedded-devel>`__ - Discussion
- https://lists.openembedded.org/g/openembedded-devel - Discussion
mailing list about OpenEmbedded.
- ` <&OE_LISTS_URL;/listinfo/bitbake-devel>`__ - Discussion mailing
- https://lists.openembedded.org/g/bitbake-devel - Discussion mailing
list about the :term:`BitBake` build tool.
- ` <&YOCTO_LISTS_URL;/listinfo/poky>`__ - Discussion mailing list
- https://lists.yoctoproject.org/g/poky - Discussion mailing list
about `Poky <#poky>`__.
- ` <&YOCTO_LISTS_URL;/listinfo/yocto-announce>`__ - Mailing list to
- https://lists.yoctoproject.org/g/yocto-announce - Mailing list to
receive official Yocto Project release and milestone announcements.
For more Yocto Project-related mailing lists, see the
@@ -115,7 +113,7 @@ Here is a list of resources you might find helpful:
planning, release engineering, QA & automation, a reference site map,
and other resources related to the Yocto Project.
- `OpenEmbedded <&OE_HOME_URL;>`__\ *:* The build system used by the
- `OpenEmbedded <http://www.openembedded.org/>`__\ *:* The build system used by the
Yocto Project. This project is the upstream, generic, embedded
distribution from which the Yocto Project derives its build system
(Poky) and to which it contributes.
@@ -127,53 +125,47 @@ Here is a list of resources you might find helpful:
guide to the BitBake tool. If you want information on BitBake, see
this manual.
- `Yocto Project Quick Build <&YOCTO_DOCS_BRIEF_URL;>`__\ *:* This
- :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` *:* This
short document lets you experience building an image using the Yocto
Project without having to understand any concepts or details.
- `Yocto Project Overview and Concepts
Manual <&YOCTO_DOCS_OM_URL;>`__\ *:* This manual provides overview
- :doc:`../overview-manual/overview-manual` *:* This manual provides overview
and conceptual information about the Yocto Project.
- `Yocto Project Development Tasks
Manual <&YOCTO_DOCS_DEV_URL;>`__\ *:* This manual is a "how-to" guide
- :doc:`../dev-manual/dev-manual` *:* This manual is a "how-to" guide
that presents procedures useful to both application and system
developers who use the Yocto Project.
- `Yocto Project Application Development and the Extensible Software
Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__\ *manual:* This
- :doc:`../sdk-manual/sdk-manual` *manual :* This
guide provides information that lets you get going with the standard
or extensible SDK. An SDK, with its cross-development toolchains,
allows you to develop projects inside or outside of the Yocto Project
environment.
- `Yocto Project Board Support Package (BSP) Developer's
Guide <&YOCTO_DOCS_BSP_URL;>`__\ *:* This guide defines the structure
- :doc:`../bsp-guide/bsp` *:* This guide defines the structure
for BSP components. Having a commonly understood structure encourages
standardization.
- `Yocto Project Linux Kernel Development
Manual <&YOCTO_DOCS_KERNEL_DEV_URL;>`__\ *:* This manual describes
- :doc:`../kernel-dev/kernel-dev` *:* This manual describes
how to work with Linux Yocto kernels as well as provides a bit of
conceptual information on the construction of the Yocto Linux kernel
tree.
- `Yocto Project Reference Manual <&YOCTO_DOCS_REF_URL;>`__\ *:* This
- :doc:`../ref-manual/ref-manual` *:* This
manual provides reference material such as variable, task, and class
descriptions.
- `Yocto Project Mega-Manual <&YOCTO_DOCS_MM_URL;>`__\ *:* This manual
- `Yocto Project Mega-Manual <https://docs.yoctoproject.org/singleindex.html>`__\ *:* This manual
is simply a single HTML file comprised of the bulk of the Yocto
Project manuals. The Mega-Manual primarily exists as a vehicle by
which you can easily search for phrases and terms used in the Yocto
Project documentation set.
- `Yocto Project Profiling and Tracing
Manual <&YOCTO_DOCS_PROF_URL;>`__\ *:* This manual presents a set of
- :doc:`../profile-manual/profile-manual` *:* This manual presents a set of
common and generally useful tracing and profiling schemes along with
their applications (as appropriate) to each tool.
- `Toaster User Manual <&YOCTO_DOCS_TOAST_URL;>`__\ *:* This manual
- :doc:`../toaster-manual/toaster-manual` *:* 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 :term:`OpenEmbedded Build System`, which uses
@@ -188,7 +180,7 @@ Here is a list of resources you might find helpful:
the Yocto Project website and click on the "RELEASE INFORMATION" link
for the appropriate release.
- `Bugzilla <&YOCTO_BUGZILLA_URL;>`__\ *:* The bug tracking application
- `Bugzilla <https://bugzilla.yoctoproject.org>`__\ *:* The bug tracking application
the Yocto Project uses. If you find problems with the Yocto Project,
you should report them using this application.