Tasks

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

Normal Recipe Build Tasks The following sections describe normal tasks associated with building a recipe. For more information on tasks and dependencies, see the "Tasks" and "Dependencies" sections in the BitBake User Manual.

<filename>do_build</filename> The default task for all recipes. This task depends on all other normal tasks required to build a recipe.

<filename>do_compile</filename> Compiles the source code. This task runs with the current working directory set to ${B}. The default behavior of this task is to run the oe_runmake function if a makefile (Makefile, makefile, or GNUmakefile) is found. If no such file is found, the do_compile task does nothing.

<filename>do_compile_ptest_base</filename> Compiles the runtime test suite included in the software being built.

<filename>do_configure</filename> 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 ${B}. The default behavior of this task is to run oe_runmake clean if a makefile (Makefile, makefile, or GNUmakefile) is found and CLEANBROKEN is not set to "1". If no such file is found or the CLEANBROKEN variable is set to "1", the do_configure task does nothing.

<filename>do_configure_ptest_base</filename> Configures the runtime test suite included in the software being built.

<filename>do_deploy</filename> Writes output files that are to be deployed to ${DEPLOY_DIR_IMAGE}. The task runs with the current working directory set to ${B}. Recipes implementing this task should inherit the deploy class and should write the output to ${DEPLOYDIR}, which is not to be confused with ${DEPLOY_DIR}. The deploy class sets up do_deploy as a shared state (sstate) task that can be accelerated through sstate use. The sstate mechanism takes care of copying the output from ${DEPLOYDIR} to ${DEPLOY_DIR_IMAGE}. Caution Do not write the output directly to ${DEPLOY_DIR_IMAGE}, as this causes the sstate mechanism to malfunction. The do_deploy task is not added as a task by default and consequently needs to be added manually. If you want the task to run after do_compile, you can add it by doing the following: addtask deploy after do_compile Adding do_deploy after other tasks works the same way. You do not need to add before do_build to the addtask command (though it is harmless), because the base class contains the following: do_build[recrdeptask] += "do_deploy" See the "Dependencies" section in the BitBake User Manual for more information. If the do_deploy task re-executes, any previous output is removed (i.e. "cleaned").

<filename>do_distrodata</filename> Provides information about the recipe. The distrodata task is included as part of the distrodata class. To build the distrodata task, use the bitbake command with the "-c" option and task name: $ bitbake core-image-minimal -c distrodata By default, the results are stored in $LOG_DIR (e.g. $BUILD_DIR/tmp/log).

<filename>do_fetch</filename> Fetches the source code. This task uses the SRC_URI variable and the argument's prefix to determine the correct fetcher module.

<filename>do_image</filename> Starts the image generation process. The do_image task runs after the OpenEmbedded build system has run the do_rootfs task during which packages are identified for installation into the image and the root filesystem is created, complete with post-processing. The do_image task performs pre-processing on the image through the IMAGE_PREPROCESS_COMMAND and dynamically generates supporting do_image_* tasks as needed. For more information on image creation, see the "Image Generation" section in the Yocto Project Overview and Concepts Manual.

<filename>do_image_complete</filename> Completes the image generation process. The do_image_complete task runs after the OpenEmbedded build system has run the do_image task during which image pre-processing occurs and through dynamically generated do_image_* tasks the image is constructed. The do_image_complete task performs post-processing on the image through the IMAGE_POSTPROCESS_COMMAND. For more information on image creation, see the "Image Generation" section in the Yocto Project Overview and Concepts Manual.

<filename>do_install</filename> Copies files that are to be packaged into the holding area ${D}. This task runs with the current working directory set to ${B}, which is the compilation directory. The do_install task, as well as other tasks that either directly or indirectly depend on the installed files (e.g. do_package, do_package_write_*, and do_rootfs), run under fakeroot. Caution 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 cp command, can preserve the UID and/or GID of the original file, which is usually not what you want. The host-user-contaminated QA check checks for files that probably have the wrong ownership. Safe methods for installing files include the following: The install utility. This utility is the preferred method. The cp command with the "--no-preserve=ownership" option. The tar command with the "--no-same-owner" option. See the bin_package.bbclass file in the meta/classes directory of the Source Directory for an example.

<filename>do_install_ptest_base</filename> Copies the runtime test suite files from the compilation directory to a holding area.

<filename>do_package</filename> Analyzes the content of the holding area ${D} and splits the content into subsets based on available packages and files. This task makes use of the PACKAGES and FILES variables. The do_package task, in conjunction with the do_packagedata task, also saves some important package metadata. For additional information, see the PKGDESTWORK variable and the "Automatically Added Runtime Dependencies" section in the Yocto Project Overview and Concepts Manual.

<filename>do_package_qa</filename> Runs QA checks on packaged files. For more information on these checks, see the insane class.

<filename>do_package_write_deb</filename> Creates Debian packages (i.e. *.deb files) and places them in the ${DEPLOY_DIR_DEB} directory in the package feeds area. For more information, see the "Package Feeds" section in the Yocto Project Overview and Concepts Manual.

<filename>do_package_write_ipk</filename> Creates IPK packages (i.e. *.ipk files) and places them in the ${DEPLOY_DIR_IPK} directory in the package feeds area. For more information, see the "Package Feeds" section in the Yocto Project Overview and Concepts Manual.

<filename>do_package_write_rpm</filename> Creates RPM packages (i.e. *.rpm files) and places them in the ${DEPLOY_DIR_RPM} directory in the package feeds area. For more information, see the "Package Feeds" section in the Yocto Project Overview and Concepts Manual.

<filename>do_package_write_tar</filename> Creates tarballs and places them in the ${DEPLOY_DIR_TAR} directory in the package feeds area. For more information, see the "Package Feeds" section in the Yocto Project Overview and Concepts Manual.

<filename>do_packagedata</filename> Saves package metadata generated by the do_package task in PKGDATA_DIR to make it available globally.

<filename>do_patch</filename> Locates patch files and applies them to the source code. See the "Patching" section in the Yocto Project Overview and Concepts Manual and the "Patching Code"" section in the Yocto Project Development Tasks Manual for more information.

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

<filename>do_populate_sdk</filename> Creates the file and directory structure for an installable SDK. See the "SDK Generation" section in the Yocto Project Overview and Concepts Manual for more information.

<filename>do_populate_sysroot</filename> Stages (copies) a subset of the files installed by the do_install task into the appropriate sysroot. For information on how to access these files from other recipes, see the STAGING_DIR* variables. Directories that would typically not be needed by other recipes at build time (e.g. /etc) are not copied by default. For information on what directories are copied by default, see the SYSROOT_DIRS* 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. The do_populate_sysroot 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").

<filename>do_prepare_recipe_sysroot</filename> Installs the files into the individual recipe specific sysroots (i.e. recipe-sysroot and recipe-sysroot-native under ${WORKDIR} based upon the dependencies specified by DEPENDS). See the "staging" class for more information.

<filename>do_rm_work</filename> Removes work files after the OpenEmbedded build system has finished with them. You can learn more by looking at the "rm_work.bbclass" section.

<filename>do_rm_work_all</filename> Top-level task for removing work files after the build system has finished with them.

<filename>do_unpack</filename> Unpacks the source code into a working directory pointed to by ${WORKDIR}. The S variable also plays a role in where unpacked source files ultimately reside. For more information on how source files are unpacked, see the "Source Fetching" section in the Yocto Project Overview and Concepts Manual and also see the WORKDIR and S variable descriptions.

Manually Called Tasks These tasks are typically manually triggered (e.g. by using the bitbake -c command-line option):

<filename>do_checkpkg</filename> 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. The checkpkg task is included as part of the distrodata class. To build the checkpkg task, use the bitbake command with the "-c" option and task name: $ bitbake core-image-minimal -c checkpkg By default, the results are stored in $LOG_DIR (e.g. $BUILD_DIR/tmp/log).

<filename>do_checkuri</filename> Validates the SRC_URI value.

<filename>do_clean</filename> Removes all output files for a target from the do_unpack task forward (i.e. do_unpack, do_configure, do_compile, do_install, and do_package). You can run this task using BitBake as follows: $ bitbake -c clean recipe Running this task does not remove the sstate 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 do_cleansstate task instead (i.e. bitbake -c cleansstate recipe).

<filename>do_cleanall</filename> Removes all output files, shared state (sstate) cache, and downloaded source files for a target (i.e. the contents of DL_DIR). Essentially, the do_cleanall task is identical to the do_cleansstate task with the added removal of downloaded source files. You can run this task using BitBake as follows: $ bitbake -c cleanall recipe Typically, you would not normally use the cleanall task. Do so only if you want to start fresh with the do_fetch task.

<filename>do_cleansstate</filename> Removes all output files and shared state (sstate) cache for a target. Essentially, the do_cleansstate task is identical to the do_clean task with the added removal of shared state (sstate) cache. You can run this task using BitBake as follows: $ bitbake -c cleansstate recipe When you run the do_cleansstate task, the OpenEmbedded build system no longer uses any sstate. Consequently, building the recipe from scratch is guaranteed. The do_cleansstate 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: $ bitbake -f -c do_cleansstate target

<filename>do_devpyshell</filename> 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 "Using a Development Python Shell" section in the Yocto Project Development Tasks Manual for more information about using devpyshell.

<filename>do_devshell</filename> Starts a shell whose environment is set up for development, debugging, or both. See the "Using a Development Shell" section in the Yocto Project Development Tasks Manual for more information about using devshell.

<filename>do_listtasks</filename> Lists all defined tasks for a target.

<filename>do_package_index</filename> Creates or updates the index in the Package Feeds area. This task is not triggered with the bitbake -c command-line option as are the other tasks in this section. Because this task is specifically for the package-index recipe, you run it using bitbake package-index.

Kernel-Related Tasks The following tasks are applicable to kernel recipes. Some of these tasks (e.g. the do_menuconfig task) are also applicable to recipes that use Linux kernel style configuration such as the BusyBox recipe.

<filename>do_compile_kernelmodules</filename> Runs the step that builds the kernel modules (if needed). Building a kernel consists of two steps: 1) the kernel (vmlinux) is built, and 2) the modules are built (i.e. make modules).

<filename>do_diffconfig</filename> When invoked by the user, this task creates a file containing the differences between the original config as produced by do_kernel_configme task and the changes made by the user with other methods (i.e. using (do_kernel_menuconfig). 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: $ bitbake linux-yocto -c diffconfig For more information, see the "Creating Configuration Fragments" section in the Yocto Project Linux Kernel Development Manual.

<filename>do_kernel_checkout</filename> 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 do_kernel_checkout task makes sure that subsequent tasks are given a clean working tree copy of the kernel with the correct branches checked out.

<filename>do_kernel_configcheck</filename> Validates the configuration produced by the do_kernel_menuconfig task. The do_kernel_configcheck task produces warnings when a requested configuration does not appear in the final .config 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: $ bitbake linux-yocto -c kernel_configcheck -f For more information, see the "Validating Configuration" section in the Yocto Project Linux Kernel Development Manual.

<filename>do_kernel_configme</filename> After the kernel is patched by the do_patch task, the do_kernel_configme 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 --allnoconfig are applied.

<filename>do_kernel_menuconfig</filename> Invoked by the user to manipulate the .config 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. You can also invoke this tool from the command line as follows: $ bitbake linux-yocto -c menuconfig See the "Using menuconfig" section in the Yocto Project Linux Kernel Development Manual for more information on this configuration tool.

<filename>do_kernel_metadata</filename> Collects all the features required for a given kernel build, whether the features come from SRC_URI or from Git repositories. After collection, the do_kernel_metadata task processes the features into a series of config fragments and patches, which can then be applied by subsequent tasks such as do_patch and do_kernel_configme.

<filename>do_menuconfig</filename> Runs make menuconfig for the kernel. For information on menuconfig, see the "Using menuconfig" section in the Yocto Project Linux Kernel Development Manual.

<filename>do_savedefconfig</filename> 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 do_kernel_menuconfig task. You can invoke the task using the following command: $ bitbake linux-yocto -c savedefconfig

<filename>do_shared_workdir</filename> 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 do_compile_kernelmodules task can successfully build the kernel modules in the next step of the build.

<filename>do_sizecheck</filename> After the kernel has been built, this task checks the size of the stripped kernel image against KERNEL_IMAGE_MAXSIZE. If that variable was set and the size of the stripped kernel exceeds that size, the kernel build produces a warning to that effect.

<filename>do_strip</filename> If KERNEL_IMAGE_STRIP_EXTRA_SECTIONS is defined, this task strips the sections named in that variable from vmlinux. This stripping is typically used to remove nonessential sections such as .comment sections from a size-sensitive configuration.

<filename>do_validate_branches</filename> After the kernel is unpacked but before it is patched, this task makes sure that the machine and metadata branches as specified by the SRCREV variables actually exist on the specified branches. If these branches do not exist and AUTOREV is not being used, the do_validate_branches task fails during the build.

Miscellaneous Tasks The following sections describe miscellaneous tasks.

<filename>do_spdx</filename> 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 spdx class.