From 43d07a285181e64c30d98d10ff93ef50391efe59 Mon Sep 17 00:00:00 2001 From: Nicolas Dechesne Date: Mon, 5 Oct 2020 16:30:32 +0200 Subject: sphinx: remove DocBook files The Yocto Project documentation was migrated to Sphinx. Let's remove the deprecated DocBook files. (From yocto-docs rev: 28fb0e63b2fbfd6426b00498bf2682bb53fdd862) Signed-off-by: Nicolas Dechesne Signed-off-by: Richard Purdie --- documentation/ref-manual/ref-tasks.xml | 1131 -------------------------------- 1 file changed, 1131 deletions(-) delete mode 100644 documentation/ref-manual/ref-tasks.xml (limited to 'documentation/ref-manual/ref-tasks.xml') 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 @@ - %poky; ] > - - - -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_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. - - - - After fetching and unpacking source files, the build system - uses the recipe's - SRC_URI - statements to locate and apply patch files to the source code. - - The build system uses the - FILESPATH - variable to determine the default set of directories when - searching for patches. - - Patch files, by default, are *.patch and - *.diff files created and kept in a - subdirectory of the directory holding the recipe file. - For example, consider the - bluez5 - recipe from the OE-Core layer (i.e. - poky/meta): - - poky/meta/recipes-connectivity/bluez5 - - This recipe has two patch files located here: - - poky/meta/recipes-connectivity/bluez5/bluez5 - - - - - In the bluez5 recipe, the - SRC_URI statements point to the source and - patch files needed to build the package. - - In the case for the bluez5_5.48.bb - recipe, the SRC_URI statements are from an - include file bluez5.inc. - - - - - As mentioned earlier, the build system treats files whose file - types are .patch and - .diff as patch files. - However, you can use the "apply=yes" parameter with the - SRC_URI statement to indicate any file as a - patch file: - - SRC_URI = " \ - git://path_to_repo/some_package \ - file://file;apply=yes \ - " - - - - - Conversely, if you have a directory full of patch files and you - want to exclude some so that the do_patch - task does not apply them during the patch phase, you can use - the "apply=no" parameter with the SRC_URI - statement: - - SRC_URI = " \ - git://path_to_repo/some_package \ - file://path_to_lots_of_patch_files \ - file://path_to_lots_of_patch_files/patch_file5;apply=no \ - " - - In the previous example, assuming all the files in the directory - holding the patch files end with either .patch - or .diff, every file would be applied as a - patch by default except for the - patch_file5 patch. - - - - You can find out more about the patching process in the - "Patching" - section in the Yocto Project Overview and Concepts Manual and the - "Patching Code" - section in the Yocto Project Development Tasks Manual. - -
- -
- <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_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. - - - - To check the upstream version and status of a recipe, use the - following devtool commands: - - $ devtool latest-version - $ devtool check-upgrade-status - - See the - "devtool Quick Reference" - chapter for more information on devtool. - See the - "Checking on the Upgrade Status of a Recipe" - section for information on checking the upgrade status of a recipe. - - - - 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. - - -
-
- - - - - -
- 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. - -
-
- - - -- cgit v1.2.3-54-g00ecf