diff options
Diffstat (limited to 'poky/documentation/ref-manual/ref-tasks.xml')
| -rw-r--r-- | poky/documentation/ref-manual/ref-tasks.xml | 1155 |
1 files changed, 1155 insertions, 0 deletions
diff --git a/poky/documentation/ref-manual/ref-tasks.xml b/poky/documentation/ref-manual/ref-tasks.xml new file mode 100644 index 0000000000..e6cf68670b --- /dev/null +++ b/poky/documentation/ref-manual/ref-tasks.xml @@ -0,0 +1,1155 @@ +<!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>${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-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 + "<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-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 + "<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> + 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-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-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 +--> |