blob: 5b09b3f2e89b8aaa63fd6aae442923254a9cc436 [file] [log] [blame]
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
<chapter id='ref-tasks'>
<title>Tasks</title>
<para>
Tasks are units of execution for BitBake.
Recipes (<filename>.bb</filename> files) use tasks to complete
configuring, compiling, and packaging software.
This chapter provides a reference of the tasks defined in the
OpenEmbedded build system.
</para>
<section id='normal-recipe-build-tasks'>
<title>Normal Recipe Build Tasks</title>
<para>
The following sections describe normal tasks associated with building
a recipe.
For more information on tasks and dependencies, see the
"<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and
"<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
sections in the BitBake User Manual.
</para>
<section id='ref-tasks-build'>
<title><filename>do_build</filename></title>
<para>
The default task for all recipes.
This task depends on all other normal tasks
required to build a recipe.
</para>
</section>
<section id='ref-tasks-compile'>
<title><filename>do_compile</filename></title>
<para>
Compiles the source code.
This task runs with the current working directory set
to
<filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>.
</para>
<para>
The default behavior of this task is to run the
<filename>oe_runmake</filename> function if a makefile
(<filename>Makefile</filename>, <filename>makefile</filename>,
or <filename>GNUmakefile</filename>) is found.
If no such file is found, the <filename>do_compile</filename>
task does nothing.
</para>
</section>
<section id='ref-tasks-compile_ptest_base'>
<title><filename>do_compile_ptest_base</filename></title>
<para>
Compiles the runtime test suite included in the software being
built.
</para>
</section>
<section id='ref-tasks-configure'>
<title><filename>do_configure</filename></title>
<para>
Configures the source by enabling and disabling any build-time and
configuration options for the software being built.
The task runs with the current working directory set to
<filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>.
</para>
<para>
The default behavior of this task is to run
<filename>oe_runmake clean</filename> if a makefile
(<filename>Makefile</filename>, <filename>makefile</filename>,
or <filename>GNUmakefile</filename>) is found and
<link linkend='var-CLEANBROKEN'><filename>CLEANBROKEN</filename></link>
is not set to "1".
If no such file is found or the <filename>CLEANBROKEN</filename>
variable is set to "1", the <filename>do_configure</filename>
task does nothing.
</para>
</section>
<section id='ref-tasks-configure_ptest_base'>
<title><filename>do_configure_ptest_base</filename></title>
<para>
Configures the runtime test suite included in the software being
built.
</para>
</section>
<section id='ref-tasks-deploy'>
<title><filename>do_deploy</filename></title>
<para>
Writes output files that are to be deployed to
<filename>${</filename><link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link><filename>}</filename>.
The task runs with the current working directory set to
<filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>.
</para>
<para>
Recipes implementing this task should inherit the
<link linkend='ref-classes-deploy'><filename>deploy</filename></link>
class and should write the output to
<filename>${</filename><link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link><filename>}</filename>,
which is not to be confused with <filename>${DEPLOY_DIR}</filename>.
The <filename>deploy</filename> class sets up
<filename>do_deploy</filename> as a shared state (sstate) task that
can be accelerated through sstate use.
The sstate mechanism takes care of copying the output from
<filename>${DEPLOYDIR}</filename> to
<filename>${DEPLOY_DIR_IMAGE}</filename>.
<note>
<title>Caution</title>
Do not write the output directly to
<filename>${DEPLOY_DIR_IMAGE}</filename>, as this causes
the sstate mechanism to malfunction.
</note>
</para>
<para>
The <filename>do_deploy</filename> task is not added as a task
by default and consequently needs to be added manually.
If you want the task to run after
<link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
you can add it by doing the following:
<literallayout class='monospaced'>
addtask deploy after do_compile
</literallayout>
Adding <filename>do_deploy</filename> after other tasks works the
same way.
<note>
You do not need to add <filename>before do_build</filename>
to the <filename>addtask</filename> command (though it is
harmless), because the
<link linkend='ref-classes-base'><filename>base</filename></link>
class contains the following:
<literallayout class='monospaced'>
do_build[recrdeptask] += "do_deploy"
</literallayout>
See the
"<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
section in the BitBake User Manual for more information.
</note>
</para>
<para>
If the <filename>do_deploy</filename> task re-executes, any
previous output is removed (i.e. "cleaned").
</para>
</section>
<section id='ref-tasks-fetch'>
<title><filename>do_fetch</filename></title>
<para>
Fetches the source code.
This task uses the
<link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
variable and the argument's prefix to determine the correct
<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>fetcher</ulink>
module.
</para>
</section>
<section id='ref-tasks-image'>
<title><filename>do_image</filename></title>
<para>
Starts the image generation process.
The <filename>do_image</filename> task runs after the
OpenEmbedded build system has run the
<link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
task during which packages are identified for installation into
the image and the root filesystem is created, complete with
post-processing.
</para>
<para>
The <filename>do_image</filename> task performs pre-processing
on the image through the
<link linkend='var-IMAGE_PREPROCESS_COMMAND'><filename>IMAGE_PREPROCESS_COMMAND</filename></link>
and dynamically generates supporting
<filename>do_image_*</filename> tasks as needed.
</para>
<para>
For more information on image creation, see the
"<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
<section id='ref-tasks-image-complete'>
<title><filename>do_image_complete</filename></title>
<para>
Completes the image generation process.
The <filename>do_image_complete</filename> task runs after the
OpenEmbedded build system has run the
<link linkend='ref-tasks-image'><filename>do_image</filename></link>
task during which image pre-processing occurs and through
dynamically generated <filename>do_image_*</filename> tasks the
image is constructed.
</para>
<para>
The <filename>do_image_complete</filename> task performs
post-processing on the image through the
<link linkend='var-IMAGE_POSTPROCESS_COMMAND'><filename>IMAGE_POSTPROCESS_COMMAND</filename></link>.
</para>
<para>
For more information on image creation, see the
"<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
<section id='ref-tasks-install'>
<title><filename>do_install</filename></title>
<para>
Copies files that are to be packaged into the holding area
<filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>.
This task runs with the current working directory set to
<filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>,
which is the compilation directory.
The <filename>do_install</filename> task, as well as other tasks
that either directly or indirectly depend on the installed files
(e.g.
<link linkend='ref-tasks-package'><filename>do_package</filename></link>,
<link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>,
and
<link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>),
run under
<ulink url='&YOCTO_DOCS_OM_URL;#fakeroot-and-pseudo'>fakeroot</ulink>.
<note>
<title>Caution</title>
<para>
When installing files, be careful not to set the owner and
group IDs of the installed files to unintended values.
Some methods of copying files, notably when using the
recursive <filename>cp</filename> command, can preserve the
UID and/or GID of the original file, which is usually not
what you want.
The
<link linkend='insane-host-user-contaminated'><filename>host-user-contaminated</filename></link>
QA check checks for files that probably have the wrong
ownership.
</para>
<para>
Safe methods for installing files include the following:
<itemizedlist>
<listitem><para>
The <filename>install</filename> utility.
This utility is the preferred method.
</para></listitem>
<listitem><para>
The <filename>cp</filename> command with the
"--no-preserve=ownership" option.
</para></listitem>
<listitem><para>
The <filename>tar</filename> command with the
"--no-same-owner" option.
See the <filename>bin_package.bbclass</filename>
file in the <filename>meta/classes</filename>
directory of the
<link linkend='source-directory'>Source Directory</link>
for an example.
</para></listitem>
</itemizedlist>
</para>
</note>
</para>
</section>
<section id='ref-tasks-install_ptest_base'>
<title><filename>do_install_ptest_base</filename></title>
<para>
Copies the runtime test suite files from the compilation directory
to a holding area.
</para>
</section>
<section id='ref-tasks-package'>
<title><filename>do_package</filename></title>
<para>
Analyzes the content of the holding area
<filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
and splits the content into subsets based on available packages
and files.
This task makes use of the
<link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
and
<link linkend='var-FILES'><filename>FILES</filename></link>
variables.
</para>
<para>
The <filename>do_package</filename> task, in conjunction with the
<link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
task, also saves some important package metadata.
For additional information, see the
<link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link>
variable and the
"<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
<section id='ref-tasks-package_qa'>
<title><filename>do_package_qa</filename></title>
<para>
Runs QA checks on packaged files.
For more information on these checks, see the
<link linkend='ref-classes-insane'><filename>insane</filename></link>
class.
</para>
</section>
<section id='ref-tasks-package_write_deb'>
<title><filename>do_package_write_deb</filename></title>
<para>
Creates Debian packages (i.e. <filename>*.deb</filename> files) and
places them in the
<filename>${</filename><link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link><filename>}</filename>
directory in the package feeds area.
For more information, see the
"<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
<section id='ref-tasks-package_write_ipk'>
<title><filename>do_package_write_ipk</filename></title>
<para>
Creates IPK packages (i.e. <filename>*.ipk</filename> files) and
places them in the
<filename>${</filename><link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link><filename>}</filename>
directory in the package feeds area.
For more information, see the
"<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
<section id='ref-tasks-package_write_rpm'>
<title><filename>do_package_write_rpm</filename></title>
<para>
Creates RPM packages (i.e. <filename>*.rpm</filename> files) and
places them in the
<filename>${</filename><link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link><filename>}</filename>
directory in the package feeds area.
For more information, see the
"<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
<section id='ref-tasks-package_write_tar'>
<title><filename>do_package_write_tar</filename></title>
<para>
Creates tarballs and places them in the
<filename>${</filename><link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link><filename>}</filename>
directory in the package feeds area.
For more information, see the
"<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
<section id='ref-tasks-packagedata'>
<title><filename>do_packagedata</filename></title>
<para>
Saves package metadata generated by the
<link linkend='ref-tasks-package'><filename>do_package</filename></link>
task in
<link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
to make it available globally.
</para>
</section>
<section id='ref-tasks-patch'>
<title><filename>do_patch</filename></title>
<para>
Locates patch files and applies them to the source code.
</para>
<para>
After fetching and unpacking source files, the build system
uses the recipe's
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
statements to locate and apply patch files to the source code.
<note>
The build system uses the
<ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
variable to determine the default set of directories when
searching for patches.
</note>
Patch files, by default, are <filename>*.patch</filename> and
<filename>*.diff</filename> files created and kept in a
subdirectory of the directory holding the recipe file.
For example, consider the
<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-connectivity/bluez5'><filename>bluez5</filename></ulink>
recipe from the OE-Core layer (i.e.
<filename>poky/meta</filename>):
<literallayout class='monospaced'>
poky/meta/recipes-connectivity/bluez5
</literallayout>
This recipe has two patch files located here:
<literallayout class='monospaced'>
poky/meta/recipes-connectivity/bluez5/bluez5
</literallayout>
</para>
<para>
In the <filename>bluez5</filename> recipe, the
<filename>SRC_URI</filename> statements point to the source and
patch files needed to build the package.
<note>
In the case for the <filename>bluez5_5.48.bb</filename>
recipe, the <filename>SRC_URI</filename> statements are from an
include file <filename>bluez5.inc</filename>.
</note>
</para>
<para>
As mentioned earlier, the build system treats files whose file
types are <filename>.patch</filename> and
<filename>.diff</filename> as patch files.
However, you can use the "apply=yes" parameter with the
<filename>SRC_URI</filename> statement to indicate any file as a
patch file:
<literallayout class='monospaced'>
SRC_URI = " \
git://<replaceable>path_to_repo</replaceable>/<replaceable>some_package</replaceable> \
file://<replaceable>file</replaceable>;apply=yes \
"
</literallayout>
</para>
<para>
Conversely, if you have a directory full of patch files and you
want to exclude some so that the <filename>do_patch</filename>
task does not apply them during the patch phase, you can use
the "apply=no" parameter with the <filename>SRC_URI</filename>
statement:
<literallayout class='monospaced'>
SRC_URI = " \
git://<replaceable>path_to_repo</replaceable>/<replaceable>some_package</replaceable> \
file://<replaceable>path_to_lots_of_patch_files</replaceable> \
file://<replaceable>path_to_lots_of_patch_files</replaceable>/<replaceable>patch_file5</replaceable>;apply=no \
"
</literallayout>
In the previous example, assuming all the files in the directory
holding the patch files end with either <filename>.patch</filename>
or <filename>.diff</filename>, every file would be applied as a
patch by default except for the
<replaceable>patch_file5</replaceable> patch.
</para>
<para>
You can find out more about the patching process in the
"<ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>Patching</ulink>"
section in the Yocto Project Overview and Concepts Manual and the
"<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code'>Patching Code</ulink>"
section in the Yocto Project Development Tasks Manual.
</para>
</section>
<section id='ref-tasks-populate_lic'>
<title><filename>do_populate_lic</filename></title>
<para>
Writes license information for the recipe that is collected later
when the image is constructed.
</para>
</section>
<section id='ref-tasks-populate_sdk'>
<title><filename>do_populate_sdk</filename></title>
<para>
Creates the file and directory structure for an installable SDK.
See the
"<ulink url='&YOCTO_DOCS_OM_URL;#sdk-generation-dev-environment'>SDK Generation</ulink>"
section in the Yocto Project Overview and Concepts Manual for more
information.
</para>
</section>
<section id='ref-tasks-populate_sysroot'>
<title><filename>do_populate_sysroot</filename></title>
<para>
Stages (copies) a subset of the files installed by the
<link linkend='ref-tasks-install'><filename>do_install</filename></link>
task into the appropriate sysroot.
For information on how to access these files from other recipes,
see the
<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR*</filename></link>
variables.
Directories that would typically not be needed by other recipes at
build time (e.g. <filename>/etc</filename>) are not copied by
default.
</para>
<para>
For information on what directories are copied by default, see the
<link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS*</filename></link>
variables.
You can change these variables inside your recipe if you need
to make additional (or fewer) directories available to other
recipes at build time.
</para>
<para>
The <filename>do_populate_sysroot</filename> task is a
shared state (sstate) task, which means that the task can
be accelerated through sstate use.
Realize also that if the task is re-executed, any previous output
is removed (i.e. "cleaned").
</para>
</section>
<section id='ref-tasks-prepare_recipe_sysroot'>
<title><filename>do_prepare_recipe_sysroot</filename></title>
<para>
Installs the files into the individual recipe specific sysroots
(i.e. <filename>recipe-sysroot</filename> and
<filename>recipe-sysroot-native</filename> under
<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}</filename>
based upon the dependencies specified by
<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>).
See the
"<link linkend='ref-classes-staging'><filename>staging</filename></link>"
class for more information.
</para>
</section>
<section id='ref-tasks-rm_work'>
<title><filename>do_rm_work</filename></title>
<para>
Removes work files after the OpenEmbedded build system has
finished with them.
You can learn more by looking at the
"<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"
section.
</para>
</section>
<section id='ref-tasks-unpack'>
<title><filename>do_unpack</filename></title>
<para>
Unpacks the source code into a working directory pointed to
by
<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}</filename>.
The
<link linkend='var-S'><filename>S</filename></link> variable also
plays a role in where unpacked source files ultimately reside.
For more information on how source files are unpacked, see the
"<ulink url='&YOCTO_DOCS_OM_URL;#source-fetching-dev-environment'>Source Fetching</ulink>"
section in the Yocto Project Overview and Concepts Manual and also
see the <filename>WORKDIR</filename> and
<filename>S</filename> variable descriptions.
</para>
</section>
</section>
<section id='manually-called-tasks'>
<title>Manually Called Tasks</title>
<para>
These tasks are typically manually triggered (e.g. by using the
<filename>bitbake -c</filename> command-line option):
</para>
<section id='ref-tasks-checkpkg'>
<title><filename>do_checkpkg</filename></title>
<para>
Provides information about the recipe including its upstream
version and status.
The upstream version and status reveals whether or not a version
of the recipe exists upstream and a status of not updated, updated,
or unknown.
</para>
<para>
To check the upstream version and status of a recipe, use the
following devtool commands:
<literallayout class='monospaced'>
$ devtool latest-version
$ devtool check-upgrade-status
</literallayout>
See the
"<link linkend='ref-devtool-reference'><filename>devtool</filename> Quick Reference</link>"
chapter for more information on <filename>devtool</filename>.
See the
"<ulink url='&YOCTO_DOCS_REF_URL;#devtool-checking-on-the-upgrade-status-of-a-recipe'>Checking on the Upgrade Status of a Recipe</ulink>"
section for information on checking the upgrade status of a recipe.
</para>
<para>
To build the <filename>checkpkg</filename> task, use the
<filename>bitbake</filename> command with the "-c" option and
task name:
<literallayout class='monospaced'>
$ bitbake core-image-minimal -c checkpkg
</literallayout>
By default, the results are stored in
<link linkend='var-LOG_DIR'><filename>$LOG_DIR</filename></link>
(e.g. <filename>$BUILD_DIR/tmp/log</filename>).
</para>
</section>
<section id='ref-tasks-checkuri'>
<title><filename>do_checkuri</filename></title>
<para>
Validates the
<link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
value.
</para>
</section>
<section id='ref-tasks-clean'>
<title><filename>do_clean</filename></title>
<para>
Removes all output files for a target from the
<link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link>
task forward (i.e. <filename>do_unpack</filename>,
<link linkend='ref-tasks-configure'><filename>do_configure</filename></link>,
<link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
<link linkend='ref-tasks-install'><filename>do_install</filename></link>,
and
<link linkend='ref-tasks-package'><filename>do_package</filename></link>).
</para>
<para>
You can run this task using BitBake as follows:
<literallayout class='monospaced'>
$ bitbake -c clean <replaceable>recipe</replaceable>
</literallayout>
</para>
<para>
Running this task does not remove the
<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate</ulink>
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 use the
<link linkend='ref-tasks-cleansstate'><filename>do_cleansstate</filename></link>
task instead (i.e. <filename>bitbake -c cleansstate</filename> <replaceable>recipe</replaceable>).
</para>
</section>
<section id='ref-tasks-cleanall'>
<title><filename>do_cleanall</filename></title>
<para>
Removes all output files, shared state
(<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate</ulink>)
cache, and downloaded source files for a target (i.e. the contents
of
<link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>).
Essentially, the <filename>do_cleanall</filename> task is
identical to the
<link linkend='ref-tasks-cleansstate'><filename>do_cleansstate</filename></link>
task with the added removal of downloaded source files.
</para>
<para>
You can run this task using BitBake as follows:
<literallayout class='monospaced'>
$ bitbake -c cleanall <replaceable>recipe</replaceable>
</literallayout>
</para>
<para>
Typically, you would not normally use the
<filename>cleanall</filename> task.
Do so only if you want to start fresh with the
<link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>
task.
</para>
</section>
<section id='ref-tasks-cleansstate'>
<title><filename>do_cleansstate</filename></title>
<para>
Removes all output files and shared state
(<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate</ulink>)
cache for a target.
Essentially, the <filename>do_cleansstate</filename> task is
identical to the
<link linkend='ref-tasks-clean'><filename>do_clean</filename></link>
task with the added removal of shared state
(<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate</ulink>)
cache.
</para>
<para>
You can run this task using BitBake as follows:
<literallayout class='monospaced'>
$ bitbake -c cleansstate <replaceable>recipe</replaceable>
</literallayout>
</para>
<para>
When you run the <filename>do_cleansstate</filename> task,
the OpenEmbedded build system no longer uses any
sstate.
Consequently, building the recipe from scratch is guaranteed.
<note>
The <filename>do_cleansstate</filename> task cannot remove
sstate from a remote sstate mirror.
If you need to build a target from scratch using remote
mirrors, use the "-f" option as follows:
<literallayout class='monospaced'>
$ bitbake -f -c do_cleansstate <replaceable>target</replaceable>
</literallayout>
</note>
</para>
</section>
<section id='ref-tasks-devpyshell'>
<title><filename>do_devpyshell</filename></title>
<para>
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
"<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devpyshell'>Using a Development Python Shell</ulink>"
section in the Yocto Project Development Tasks Manual for more
information about using <filename>devpyshell</filename>.
</para>
</section>
<section id='ref-tasks-devshell'>
<title><filename>do_devshell</filename></title>
<para>
Starts a shell whose environment is set up for
development, debugging, or both.
See the
"<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>"
section in the Yocto Project Development Tasks Manual for more
information about using <filename>devshell</filename>.
</para>
</section>
<section id='ref-tasks-listtasks'>
<title><filename>do_listtasks</filename></title>
<para>
Lists all defined tasks for a target.
</para>
</section>
<section id='ref-tasks-package_index'>
<title><filename>do_package_index</filename></title>
<para>
Creates or updates the index in the
<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>
area.
<note>
This task is not triggered with the
<filename>bitbake -c</filename> command-line option as
are the other tasks in this section.
Because this task is specifically for the
<filename>package-index</filename> recipe,
you run it using
<filename>bitbake package-index</filename>.
</note>
</para>
</section>
</section>
<section id='image-related-tasks'>
<title>Image-Related Tasks</title>
<para>
The following tasks are applicable to image recipes.
</para>
<section id='ref-tasks-bootimg'>
<title><filename>do_bootimg</filename></title>
<para>
Creates a bootable live image.
See the
<link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
variable for additional information on live image types.
</para>
</section>
<section id='ref-tasks-bundle_initramfs'>
<title><filename>do_bundle_initramfs</filename></title>
<para>
Combines an initial RAM disk (initramfs) image and kernel
together to form a single image.
The
<link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link>
variable has some more information about these types of images.
</para>
</section>
<section id='ref-tasks-rootfs'>
<title><filename>do_rootfs</filename></title>
<para>
Creates the root filesystem (file and directory structure) for an
image.
See the
"<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
section in the Yocto Project Overview and Concepts Manual for more
information on how the root filesystem is created.
</para>
</section>
<section id='ref-tasks-testimage'>
<title><filename>do_testimage</filename></title>
<para>
Boots an image and performs runtime tests within the image.
For information on automatically testing images, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
section in the Yocto Project Development Tasks Manual.
</para>
</section>
<section id='ref-tasks-testimage_auto'>
<title><filename>do_testimage_auto</filename></title>
<para>
Boots an image and performs runtime tests within the image
immediately after it has been built.
This task is enabled when you set
<link linkend='var-TESTIMAGE_AUTO'><filename>TESTIMAGE_AUTO</filename></link>
equal to "1".
</para>
<para>
For information on automatically testing images, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
section in the Yocto Project Development Tasks Manual.
</para>
</section>
</section>
<section id='kernel-related-tasks'>
<title>Kernel-Related Tasks</title>
<para>
The following tasks are applicable to kernel recipes.
Some of these tasks (e.g. the
<link linkend='ref-tasks-menuconfig'><filename>do_menuconfig</filename></link>
task) are also applicable to recipes that use
Linux kernel style configuration such as the BusyBox recipe.
</para>
<section id='ref-tasks-compile_kernelmodules'>
<title><filename>do_compile_kernelmodules</filename></title>
<para>
Runs the step that builds the kernel modules (if needed).
Building a kernel consists of two steps: 1) the kernel
(<filename>vmlinux</filename>) is built, and 2) the modules
are built (i.e. <filename>make modules</filename>).
</para>
</section>
<section id='ref-tasks-diffconfig'>
<title><filename>do_diffconfig</filename></title>
<para>
When invoked by the user, this task creates a file containing the
differences between the original config as produced by
<link linkend='ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></link>
task and the changes made by the user with other methods
(i.e. using
(<link linkend='ref-tasks-kernel_menuconfig'><filename>do_kernel_menuconfig</filename></link>).
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:
<literallayout class='monospaced'>
$ bitbake linux-yocto -c diffconfig
</literallayout>
For more information, see the
"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>"
section in the Yocto Project Linux Kernel Development Manual.
</para>
</section>
<section id='ref-tasks-kernel_checkout'>
<title><filename>do_kernel_checkout</filename></title>
<para>
Converts the newly unpacked kernel source into a form with which
the OpenEmbedded build system can work.
Because the kernel source can be fetched in several different ways,
the <filename>do_kernel_checkout</filename> task makes sure that
subsequent tasks are given a clean working tree copy of the kernel
with the correct branches checked out.
</para>
</section>
<section id='ref-tasks-kernel_configcheck'>
<title><filename>do_kernel_configcheck</filename></title>
<para>
Validates the configuration produced by the
<link linkend='ref-tasks-kernel_menuconfig'><filename>do_kernel_menuconfig</filename></link>
task.
The <filename>do_kernel_configcheck</filename> task produces
warnings when a requested configuration does not appear in the
final <filename>.config</filename> 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:
<literallayout class='monospaced'>
$ bitbake linux-yocto -c kernel_configcheck -f
</literallayout>
For more information, see the
"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#validating-configuration'>Validating Configuration</ulink>"
section in the Yocto Project Linux Kernel Development Manual.
</para>
</section>
<section id='ref-tasks-kernel_configme'>
<title><filename>do_kernel_configme</filename></title>
<para>
After the kernel is patched by the
<link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
task, the <filename>do_kernel_configme</filename> task assembles
and merges all the kernel config fragments into a merged
configuration that can then be passed to the kernel configuration
phase proper.
This is also the time during which user-specified defconfigs
are applied if present, and where configuration modes such as
<filename>--allnoconfig</filename> are applied.
</para>
</section>
<section id='ref-tasks-kernel_menuconfig'>
<title><filename>do_kernel_menuconfig</filename></title>
<para>
Invoked by the user to manipulate the
<filename>.config</filename> file used to build a linux-yocto
recipe.
This task starts the Linux kernel configuration tool, which you
then use to modify the kernel configuration.
<note>
You can also invoke this tool from the command line as
follows:
<literallayout class='monospaced'>
$ bitbake linux-yocto -c menuconfig
</literallayout>
</note>
See the
"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>"
section in the Yocto Project Linux Kernel Development Manual
for more information on this configuration tool.
</para>
</section>
<section id='ref-tasks-kernel_metadata'>
<title><filename>do_kernel_metadata</filename></title>
<para>
Collects all the features required for a given kernel build,
whether the features come from
<link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
or from Git repositories.
After collection, the <filename>do_kernel_metadata</filename> task
processes the features into a series of config fragments and
patches, which can then be applied by subsequent tasks such as
<link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
and
<link linkend='ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></link>.
</para>
</section>
<section id='ref-tasks-menuconfig'>
<title><filename>do_menuconfig</filename></title>
<para>
Runs <filename>make menuconfig</filename> for the kernel.
For information on <filename>menuconfig</filename>, see the
"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#using-menuconfig'>Using&nbsp;&nbsp;<filename>menuconfig</filename></ulink>"
section in the Yocto Project Linux Kernel Development Manual.
</para>
</section>
<section id='ref-tasks-savedefconfig'>
<title><filename>do_savedefconfig</filename></title>
<para>
When invoked by the user, creates a defconfig file that can be
used instead of the default defconfig.
The saved defconfig contains the differences between the default
defconfig and the changes made by the user using other methods
(i.e. the
<link linkend='ref-tasks-kernel_menuconfig'><filename>do_kernel_menuconfig</filename></link>
task.
You can invoke the task using the following command:
<literallayout class='monospaced'>
$ bitbake linux-yocto -c savedefconfig
</literallayout>
</para>
</section>
<section id='ref-tasks-shared_workdir'>
<title><filename>do_shared_workdir</filename></title>
<para>
After the kernel has been compiled but before the kernel modules
have been compiled, this task copies files required for module
builds and which are generated from the kernel build into the
shared work directory.
With these copies successfully copied, the
<link linkend='ref-tasks-compile_kernelmodules'><filename>do_compile_kernelmodules</filename></link>
task can successfully build the kernel modules in the next step
of the build.
</para>
</section>
<section id='ref-tasks-sizecheck'>
<title><filename>do_sizecheck</filename></title>
<para>
After the kernel has been built, this task checks the size of the
stripped kernel image against
<link linkend='var-KERNEL_IMAGE_MAXSIZE'><filename>KERNEL_IMAGE_MAXSIZE</filename></link>.
If that variable was set and the size of the stripped kernel
exceeds that size, the kernel build produces a warning to that
effect.
</para>
</section>
<section id='ref-tasks-strip'>
<title><filename>do_strip</filename></title>
<para>
If
<filename>KERNEL_IMAGE_STRIP_EXTRA_SECTIONS</filename> is defined,
this task strips the sections named in that variable from
<filename>vmlinux</filename>.
This stripping is typically used to remove nonessential sections
such as <filename>.comment</filename> sections from a
size-sensitive configuration.
</para>
</section>
<section id='ref-tasks-validate_branches'>
<title><filename>do_validate_branches</filename></title>
<para>
After the kernel is unpacked but before it is patched, this task
makes sure that the machine and metadata branches as specified
by the <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
variables actually exist on the specified branches.
If these branches do not exist and
<link linkend='var-AUTOREV'><filename>AUTOREV</filename></link>
is not being used, the <filename>do_validate_branches</filename>
task fails during the build.
</para>
</section>
</section>
<section id='miscellaneous-tasks'>
<title>Miscellaneous Tasks</title>
<para>
The following sections describe miscellaneous tasks.
</para>
<section id='ref-tasks-spdx'>
<title><filename>do_spdx</filename></title>
<para>
A build stage that takes the source code and scans it on a remote
FOSSOLOGY server in order to produce an SPDX document.
This task applies only to the
<link linkend='ref-classes-spdx'><filename>spdx</filename></link>
class.
</para>
</section>
</section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->