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

### `do_build`

The default task for all recipes. This task depends on all other normal tasks required to build a recipe.

### `do_compile`

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.

### `do_compile_ptest_base`

Compiles the runtime test suite included in the software being built.

### `do_configure`

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.

### `do_configure_ptest_base`

Configures the runtime test suite included in the software being built.

### `do_deploy`

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").

### `do_distrodata`

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`).

### `do_fetch`

Fetches the source code. This task uses the `SRC_URI` variable and the argument's prefix to determine the correct fetcher module.

### `do_image`

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.

### `do_image_complete`

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.

### `do_install`

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.

### `do_install_ptest_base`

Copies the runtime test suite files from the compilation directory to a holding area.

### `do_package`

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.

### `do_package_qa`

Runs QA checks on packaged files. For more information on these checks, see the `insane` class.

### `do_package_write_deb`

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.

### `do_package_write_ipk`

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.

### `do_package_write_rpm`

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.

### `do_package_write_tar`

Creates tarballs and places them in the `${` `DEPLOY_DIR_TAR` `}` directory in the package feeds area. For more information, see the "Package Feeds" section.

### `do_packagedata`

Saves package metadata generated by the `do_package` task in `PKGDATA_DIR` to make it available globally.

### `do_patch`

Locates patch files and applies them to the source code. See the "Patching" section for more information.

### `do_populate_lic`

Writes license information for the recipe that is collected later when the image is constructed.

### `do_populate_sdk`

Creates the file and directory structure for an installable SDK. See the "SDK Generation" section for more information.

### `do_populate_sysroot`

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").

### `do_rm_work`

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

### `do_rm_work_all`

Top-level task for removing work files after the build system has finished with them.

### `do_unpack`

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 and 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):

### `do_checkpkg`

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`).

### `do_checkuri`

Validates the `SRC_URI` value.

### `do_checkuriall`

Validates the `SRC_URI` value for all recipes required to build a target.

### `do_clean`

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

### `do_cleanall`

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.

### `do_cleansstate`

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

### `do_devpyshell`

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 Manual for more information about using `devpyshell`.

### `do_devshell`

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 Manual for more information about using `devshell`.

### `do_fetchall`

Fetches all remote sources required to build a target.

### `do_listtasks`

Lists all defined tasks for a target.

### `do_package_index`

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

## Image-Related Tasks

The following tasks are applicable to image recipes.

### `do_bootimg`

Creates a bootable live image. See the `IMAGE_FSTYPES` variable for additional information on live image types.

### `do_bundle_initramfs`

Combines an initial RAM disk (initramfs) image and kernel together to form a single image. The `CONFIG_INITRAMFS_SOURCE` variable has some more information about these types of images.

### `do_rootfs`

Creates the root filesystem (file and directory structure) for an image. See the "Image Generation" section for more information on how the root filesystem is created.

### `do_testimage`

Boots an image and performs runtime tests within the image. For information on automatically testing images, see the "Performing Automated Runtime Testing" section in the Yocto Project Development Manual.

### `do_testimage_auto`

Boots an image and performs runtime tests within the image immediately after it has been built. This task is enabled when you set `TEST_IMAGE` equal to "1".

For information on automatically testing images, see the "Performing Automated Runtime Testing" section in the Yocto Project Development Manual.

### `do_vmdkimg`

Creates a `.vmdk` image for use with VMware and compatible virtual machine hosts.

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

### `do_compile_kernelmodules`

Compiles loadable modules for the Linux kernel.

### `do_diffconfig`

Compares the old and new config files after running the `do_menuconfig` task for the kernel.

### `do_kernel_checkout`

Checks out source/meta branches for a linux-yocto style kernel.

### `do_kernel_configcheck`

Validates the kernel configuration for a linux-yocto style kernel.

### `do_kernel_configme`

Assembles the kernel configuration for a linux-yocto style kernel.

### `do_kernel_link_vmlinux`

Creates a symbolic link in `arch/$arch/boot` for vmlinux kernel images.

### `do_kernel_metadata`

Collects kernel metadata for a `linux-yocto` style kernel.

### `do_menuconfig`

Runs `make menuconfig` for the kernel. For information on `menuconfig`, see the "Using `menuconfig`" section in the Yocto Project Development Manual.

### `do_savedefconfig`

Creates a minimal Linux kernel configuration file.

### `do_shared_workdir`

Creates the shared working directory for the kernel.

### `do_sizecheck`

Checks the size of the kernel image against `KERNEL_IMAGE_MAXSIZE` when set.

### `do_strip`

Strips unneeded sections out of the Linux kernel image.

### `do_uboot_mkimage`

Creates a uImage file from the kernel for the U-Boot bootloader.

### `do_validate_branches`

Ensures that the source, metadata (or both) branches are on the locations specified by their `SRCREV` values for a linux-yocto style kernel.

## Miscellaneous Tasks

The following sections describe miscellaneous tasks.

### `do_spdx`

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.