1093 lines
43 KiB
XML
1093 lines
43 KiB
XML
<!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; ] >
|
|
|
|
<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>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}</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-distrodata'>
|
|
<title><filename>do_distrodata</filename></title>
|
|
|
|
<para>
|
|
Provides information about the recipe.
|
|
</para>
|
|
|
|
<para>
|
|
The <filename>distrodata</filename> task is included as part of the
|
|
<link linkend='ref-classes-distrodata'><filename>distrodata</filename></link>
|
|
class.
|
|
</para>
|
|
|
|
<para>
|
|
To build the <filename>distrodata</filename> task, use the
|
|
<filename>bitbake</filename> command with the "-c" option and
|
|
task name:
|
|
<literallayout class='monospaced'>
|
|
$ bitbake core-image-minimal -c distrodata
|
|
</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-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
|
|
fetcher 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
|
|
"<link linkend='image-generation-dev-environment'>Image Generation</link>"
|
|
section.
|
|
</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-rootfs'><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
|
|
"<link linkend='image-generation-dev-environment'>Image Generation</link>"
|
|
section.
|
|
</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
|
|
<link linkend='fakeroot-and-pseudo'>fakeroot</link>.
|
|
<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='ref-classes-insane'><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
|
|
"<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
|
|
section.
|
|
</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
|
|
"<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
|
|
section.
|
|
</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
|
|
"<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
|
|
section.
|
|
</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
|
|
"<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
|
|
section.
|
|
</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
|
|
"<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
|
|
section.
|
|
</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.
|
|
See the
|
|
"<link linkend='patching-dev-environment'>Patching</link>"
|
|
section for more information.
|
|
</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
|
|
"<link linkend='sdk-generation-dev-environment'>SDK Generation</link>"
|
|
section 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-rm_work_all'>
|
|
<title><filename>do_rm_work_all</filename></title>
|
|
|
|
<para>
|
|
Top-level task for removing work files after the build system has
|
|
finished with them.
|
|
</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
|
|
"<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
|
|
section and 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>
|
|
The <filename>checkpkg</filename> task is included as part of the
|
|
<link linkend='ref-classes-distrodata'><filename>distrodata</filename></link>
|
|
class.
|
|
</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-checkuriall'>
|
|
<title><filename>do_checkuriall</filename></title>
|
|
|
|
<para>
|
|
Validates the
|
|
<link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
|
|
value for all recipes required to build a target.
|
|
</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.
|
|
<link linkend='ref-tasks-patch'><filename>do_unpack</filename></link>,
|
|
<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
|
|
<link linkend='shared-state-cache'>sstate</link>) 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
|
|
(<link linkend='shared-state-cache'>sstate</link>) 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
|
|
(<link linkend='shared-state-cache'>sstate</link>)
|
|
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
|
|
(<link linkend='shared-state-cache'>sstate</link>) 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-fetchall'>
|
|
<title><filename>do_fetchall</filename></title>
|
|
|
|
<para>
|
|
Fetches all remote sources required to build a target.
|
|
</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
|
|
<link linkend='package-feeds-dev-environment'>Package Feeds</link>
|
|
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
|
|
"<link linkend='image-generation-dev-environment'>Image Generation</link>"
|
|
section 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-TEST_IMAGE'><filename>TEST_IMAGE</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 <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
|
|
-->
|