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