Revert "poky: subtree update:b23aa6b753..ad30a6d470"
This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.
This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.
Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c
diff --git a/poky/documentation/ref-manual/ref-tasks.xml b/poky/documentation/ref-manual/ref-tasks.xml
new file mode 100644
index 0000000..5b09b3f
--- /dev/null
+++ b/poky/documentation/ref-manual/ref-tasks.xml
@@ -0,0 +1,1131 @@
+<!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 <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
+-->