generic-poky/documentation/ref-manual/ref-tasks.xml

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

<chapter id='ref-tasks'>
<title>Tasks</title>

<para>
    Tasks are units of execution for BitBake.
    Recipes (<filename>.bb</filename> files) use tasks to complete
    configuring, compiling, and packaging software.
    This chapter provides a reference of the tasks defined in the
    OpenEmbedded build system.
</para>

<section id='normal-recipe-build-tasks'>
    <title>Normal Recipe Build Tasks</title>

    <para>
        The following sections describe normal tasks associated with building
        a recipe.
    </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 in the compilation directory, which is pointed
            to by the
            <link linkend='var-B'><filename>B</filename></link> variable.
        </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.
        </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 the deploy
            directory, which is defined by the
            <link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link>
            variable.
        </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.
            Unpacked source files reside in the
            <link linkend='var-S'><filename>S</filename></link> directory.
        </para>
    </section>

    <section id='ref-tasks-install'>
        <title><filename>do_install</filename></title>

        <para>
            Copies files from the compilation directory, which is defined by
            the
            <link linkend='var-B'><filename>B</filename></link> variable,
            to a holding area defined by the
            <link linkend='var-D'><filename>D</filename></link> variable.
        </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 and splits it into subsets
            based on available packages and files.
        </para>
    </section>

    <section id='ref-tasks-package_index'>
        <title><filename>do_package_index</filename></title>

        <para>
            Creates or updates the index in the
            <link linkend='package-feeds-dev-environment'>Package Feeds</link>
            area.
        </para>
    </section>

    <section id='ref-tasks-package_write_deb'>
        <title><filename>do_package_write_deb</filename></title>

        <para>
            Creates the actual DEB packages and places them in the
            <link linkend='package-feeds-dev-environment'>Package Feeds</link>
            area.
        </para>
    </section>

    <section id='ref-tasks-package_write_ipk'>
        <title><filename>do_package_write_ipk</filename></title>

        <para>
            Creates the actual IPK packages and places them in the
            <link linkend='package-feeds-dev-environment'>Package Feeds</link>
            area.
        </para>
    </section>

    <section id='ref-tasks-package_write_rpm'>
        <title><filename>do_package_write_rpm</filename></title>

        <para>
            Creates the actual RPM packages and places them in the
            <link linkend='package-feeds-dev-environment'>Package Feeds</link>
            area.
        </para>
    </section>

    <section id='ref-tasks-package_write_tar'>
        <title><filename>do_package_write_tar</filename></title>

        <para>
            Creates tar archives for packages and places them in the
            <link linkend='package-feeds-dev-environment'>Package Feeds</link>
            area.
        </para>
    </section>

    <section id='ref-tasks-packagedata'>
        <title><filename>do_packagedata</filename></title>

        <para>
            Creates package metadata used by the build system to generate the
            final packages.
        </para>
    </section>

    <section id='ref-tasks-patch'>
        <title><filename>do_patch</filename></title>

        <para>
            Locates patch files and applies them to the source code.
            See the
            "<link linkend='patching-dev-environment'>Patching</link>"
            section for more information.
        </para>
    </section>

    <section id='ref-tasks-populate_lic'>
        <title><filename>do_populate_lic</filename></title>

        <para>
            Writes license information for the recipe that is collected later
            when the image is constructed.
        </para>
    </section>

    <section id='ref-tasks-populate_sdk'>
        <title><filename>do_populate_sdk</filename></title>

        <para>
            Creates the file and directory structure for an installable SDK.
            See the
            "<link linkend='sdk-generation-dev-environment'>SDK Generation</link>"
            section for more information.
        </para>
    </section>

    <section id='ref-tasks-populate_sysroot'>
        <title><filename>do_populate_sysroot</filename></title>

        <para>
            Copies a subset of files installed by the
            <link linkend='ref-tasks-install'><filename>do_install</filename></link>
            task into the sysroot in order to make them available to other
            recipes.
        </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.
            For more information on fetching and unpacking source files, see the
            "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
            section.
        </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-checkuri'>
        <title><filename>do_checkuri</filename></title>

        <para>
            Validates the
            <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
            value.
        </para>
    </section>

    <section id='ref-tasks-checkuriall'>
        <title><filename>do_checkuriall</filename></title>

        <para>
            Validates the
            <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
            value for all recipes required to build a target.
        </para>
    </section>

    <section id='ref-tasks-clean'>
        <title><filename>do_clean</filename></title>

        <para>
            Removes all output files for a target.
        </para>
    </section>

    <section id='ref-tasks-cleanall'>
        <title><filename>do_cleanall</filename></title>

        <para>
            Removes all output files, shared state
            (<link linkend='shared-state-cache'>sstate</link>) cache, and
            downloaded source files for a target.
        </para>
    </section>

    <section id='ref-tasks-cleansstate'>
        <title><filename>do_cleansstate</filename></title>

        <para>
            Removes all output files and shared state
            (<link linkend='shared-state-cache'>sstate</link>)
            cache for a target.
        </para>
    </section>

    <section id='ref-tasks-fetchall'>
        <title><filename>do_fetchall</filename></title>

        <para>
            Fetches all remote sources required to build a target.
        </para>
    </section>

    <section id='ref-tasks-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 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>

<section id='image-related-tasks'>
    <title>Image-Related Tasks</title>

    <para>
        The following tasks are applicable to image recipes.
    </para>

    <section id='ref-tasks-bootimg'>
        <title><filename>do_bootimg</filename></title>

        <para>
            Creates a bootable live image.
            See the
            <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
            variable for additional information on live image types.
        </para>
    </section>

    <section id='ref-tasks-bundle_initramfs'>
        <title><filename>do_bundle_initramfs</filename></title>

        <para>
            Combines an initial RAM disk (initramfs) image and kernel
            together to form a single image.
            The
            <link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link>
            variable has some more information about these types of images.
        </para>
    </section>

    <section id='ref-tasks-rootfs'>
        <title><filename>do_rootfs</filename></title>

        <para>
            Creates the root filesystem (file and directory structure) for an
            image.
            See the
            "<link linkend='image-generation-dev-environment'>Image Generation</link>"
            section for more information on how the root filesystem is created.
        </para>
    </section>

    <section id='ref-tasks-testimage'>
        <title><filename>do_testimage</filename></title>

        <para>
            Boots an image and performs runtime tests within the image.
        </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.
        </para>
    </section>

    <section id='ref-tasks-vmdkimg'>
        <title><filename>do_vmdkimg</filename></title>

        <para>
            Creates a <filename>.vmdk</filename> image for use with
            <ulink url='http://www.vmware.com/'>VMware</ulink>
            and compatible virtual machine hosts.
        </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>
            Compiles loadable modules for the Linux kernel.
        </para>
    </section>

    <section id='ref-tasks-diffconfig'>
        <title><filename>do_diffconfig</filename></title>

        <para>
            Compares the old and new config files after running the
            <link linkend='ref-tasks-menuconfig'><filename>do_menuconfig</filename></link>
            task for the kernel.
        </para>
    </section>

    <section id='ref-tasks-kernel_checkout'>
        <title><filename>do_kernel_checkout</filename></title>

        <para>
            Checks out source/meta branches for a linux-yocto style kernel.
        </para>
    </section>

    <section id='ref-tasks-kernel_configcheck'>
        <title><filename>do_kernel_configcheck</filename></title>

        <para>
            Validates the kernel configuration for a linux-yocto style kernel.
        </para>
    </section>

    <section id='ref-tasks-kernel_configme'>
        <title><filename>do_kernel_configme</filename></title>

        <para>
            Assembles the kernel configuration for a linux-yocto style kernel.
        </para>
    </section>

    <section id='ref-tasks-kernel_link_vmlinux'>
        <title><filename>do_kernel_link_vmlinux</filename></title>

        <para>
            Creates a symbolic link in
            <filename>arch/$arch/boot</filename> for vmlinux kernel
            images.
        </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_DEV_URL;#using-menuconfig'>Using&nbsp;&nbsp;<filename>menuconfig</filename></ulink>"
            section in the Yocto Project Development Manual.
        </para>
    </section>

    <section id='ref-tasks-savedefconfig'>
        <title><filename>do_savedefconfig</filename></title>

        <para>
            Creates a minimal Linux kernel configuration file.
        </para>
    </section>

    <section id='ref-tasks-sizecheck'>
        <title><filename>do_sizecheck</filename></title>

        <para>
            Checks the size of the kernel image against
            <filename>KERNEL_IMAGE_MAXSIZE</filename> when set.
        </para>
    </section>

    <section id='ref-tasks-strip'>
        <title><filename>do_strip</filename></title>

        <para>
            Strips unneeded sections out of the Linux kernel image.
        </para>
    </section>

    <section id='ref-tasks-uboot_mkimage'>
        <title><filename>do_uboot_mkimage</filename></title>

        <para>
            Creates a uImage file from the kernel for the U-Boot bootloader.
        </para>
    </section>

    <section id='ref-tasks-validate_branches'>
        <title><filename>do_validate_branches</filename></title>

        <para>
            Ensures that the source, metadata (or both) branches are on the
            locations specified by their
            <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
            values for a linux-yocto style kernel.
        </para>
    </section>
</section>

<section id='miscellaneous-tasks'>
    <title>Miscellaneous Tasks</title>

    <para>
        The following sections describe miscellaneous tasks.
    </para>

    <section id='ref-tasks-generate_qt_config_file'>
        <title><filename>do_generate_qt_config_file</filename></title>

        <para>
            Writes a <filename>qt.conf</filename> configuration
            file used for building a Qt-based application.
        </para>
    </section>

    <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
-->