diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml index c223bbb0ce..7546215ae6 100644 --- a/documentation/ref-manual/closer-look.xml +++ b/documentation/ref-manual/closer-look.xml @@ -568,7 +568,9 @@ Another place the build system can get source files from is through an SCM such as Git or Subversion. In this case, a repository is cloned or checked out. - The do_fetch task inside BitBake uses + The + do_fetch + task inside BitBake uses the SRC_URI variable and the argument's prefix to determine the correct fetcher module. @@ -664,9 +666,16 @@ - BitBake uses the do_package_write_* task to + BitBake uses the do_package_write_* tasks to place generated packages into the package holding area (e.g. do_package_write_ipk for IPK packages). + See the + "do_package_write_deb", + "do_package_write_ipk", + "do_package_write_rpm", + and + "do_package_write_tar" + sections for additional information. @@ -700,8 +709,11 @@ - The do_fetch and - do_unpack tasks fetch the source files + The + do_fetch + and + do_unpack + tasks fetch the source files and unpack them into the work directory. By default, everything is accomplished in the Build Directory, @@ -762,7 +774,9 @@ - The do_patch task processes recipes by + The + do_patch + task processes recipes by using the SRC_URI variable to locate applicable patch files, which by default @@ -810,7 +824,8 @@ The configurations handled by the - do_configure task are specific + do_configure + task are specific to source code configuration for the source code being built by the recipe. @@ -827,7 +842,8 @@ do_compile: Once a configuration task has been satisfied, BitBake compiles the source using the - do_compile task. + do_compile + task. Compilation occurs in the directory pointed to by the B variable. @@ -837,7 +853,8 @@ directory. do_install: Once compilation is done, BitBake executes the - do_install task. + do_install + task. This task copies files from the B directory and places them in a holding area pointed to by the @@ -858,8 +875,11 @@ - The do_package and - do_packagedata tasks combine to analyze + The + do_package + and + do_packagedata + tasks combine to analyze the files found in the D directory and split them into subsets based on available packages and @@ -935,7 +955,9 @@ The image generation process consists of several stages and depends on many variables. - The do_rootfs task uses these key variables + The + do_rootfs + task uses these key variables to help create the list of packages to actually install: IMAGE_INSTALL: @@ -1046,7 +1068,8 @@ section. For information on advantages gained when building a cross-development toolchain using the - do_populate_sdk task, see the + do_populate_sdk + task, see the "Optionally Building a Toolchain Installer" section in the Yocto Project Application Developer's Guide. diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml index 7cefa5ebf4..7d6363013a 100644 --- a/documentation/ref-manual/migration.xml +++ b/documentation/ref-manual/migration.xml @@ -701,8 +701,9 @@ An additional QA check has been added to check if /usr/share/info/dir is being installed. Your recipe should delete this file within - do_install if "make install" is - installing it. + do_install + if "make install" is installing it. + If you are using the buildhistory class, the check for the package version going backwards is now controlled using a @@ -863,7 +864,9 @@ Images Now Rebuild Only on Changes Instead of Every Time - The do_rootfs and other related image + The + do_rootfs + and other related image construction tasks are no longer marked as "nostamp". Consequently, they will only be re-executed when their inputs have changed. @@ -1246,8 +1249,8 @@ underscores replaced by hyphens for the override so that they now function properly. For example, the task override for - do_populate_sdk is - task-populate-sdk. + do_populate_sdk + is task-populate-sdk. diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml index 7331867a02..8730f01a67 100644 --- a/documentation/ref-manual/ref-classes.xml +++ b/documentation/ref-manual/ref-classes.xml @@ -105,18 +105,18 @@ It's useful to have some idea of how the tasks defined by this class work and what they do behind the scenes. - do_configure ‐ Regenerates the + do_configure ‐ Regenerates the configure script (using autoreconf) and then launches it with a standard set of arguments used during cross-compilation. You can pass additional parameters to configure through the EXTRA_OECONF variable. - do_compile ‐ Runs make with + do_compile ‐ Runs make with arguments that specify the compiler and linker. You can pass additional arguments through the EXTRA_OEMAKE variable. - do_install ‐ Runs make install + do_install ‐ Runs make install and passes in ${D} as DESTDIR. @@ -550,12 +550,14 @@ The main function of this class is to allow the deploy step to be accelerated by shared state. Recipes that inherit this class should define their own - do_deploy function to copy the files to be - deployed to + do_deploy + function to copy the files to be deployed to DEPLOYDIR, and use addtask to add the task at the appropriate - place, which is usually after do_compile or - do_install. + place, which is usually after + do_compile + or + do_install. The class then takes care of staging the files from DEPLOYDIR to DEPLOY_DIR_IMAGE. @@ -1174,7 +1176,8 @@ The image-mklibs class enables the use of the mklibs utility during the - do_rootfs task, which optimizes the size of + do_rootfs + task, which optimizes the size of libraries contained in the image. @@ -1195,7 +1198,9 @@ The image-prelink class enables the use of the prelink utility during - the do_rootfs task, which optimizes the dynamic + the + do_rootfs + task, which optimizes the dynamic linking of shared libraries to reduce executable startup time. @@ -1310,7 +1315,9 @@ thus is not normally enabled. compile-host-path: - Checks the do_compile log for indications + Checks the + do_compile + log for indications that paths to locations on the build host were used. Using such paths might result in host contamination of the build output. @@ -1367,7 +1374,9 @@ INCOMPATIBLE_LICENSE. install-host-path: - Checks the do_install log for indications + Checks the + do_install + log for indications that paths to locations on the build host were used. Using such paths might result in host contamination of the build output. @@ -1451,7 +1460,8 @@ pkgv-undefined: Checks to see if the PKGV variable - is undefined during do_package. + is undefined during + do_package. pkgvarcheck: Checks through the variables @@ -1569,7 +1579,8 @@ D, PN, and PKGD) are - undefined during do_package. + undefined during + do_package. version-going-backwards: If Build History is enabled, reports when a package @@ -1803,8 +1814,11 @@ module-base and kernel-module-split - classes, and implements do_compile and - do_install functions. + classes, and implements the + do_compile + and + do_install + tasks. The class provides everything needed to build and package a kernel module. @@ -2216,7 +2230,9 @@ The patch class provides all functionality for - applying patches during the do_patch task. + applying patches during the + do_patch + task. @@ -2285,7 +2301,9 @@ The populate_sdk class provides support for SDK-only recipes. For information on advantages gained when building a cross-development - toolchain using the do_populate_sdk task, see the + toolchain using the + do_populate_sdk + task, see the "Optionally Building a Toolchain Installer" section in the Yocto Project Application Developer's Guide. @@ -2360,7 +2378,8 @@ section. For information on advantages gained when building a cross-development toolchain using the - do_populate_sdk task, see the + do_populate_sdk + task, see the "Optionally Building a Toolchain Installer" section in the Yocto Project Application Developer's Guide. @@ -2722,7 +2741,9 @@ provides functionality for handling site configuration. The class is used by the autotools - class to accelerate the do_configure task. + class to accelerate the + do_configure + task. @@ -2802,7 +2823,8 @@ The staging class provides support for staging files into the sysroot during the - do_populate_sysroot task. + do_populate_sysroot + task. The class is enabled by default because it is inherited by the base class. @@ -2873,8 +2895,9 @@ Under this class, the recipe or Makefile (i.e. whatever the recipe is - calling during the do_install task) installs unit - files into + calling during the + do_install + task) installs unit files into ${D}${systemd_unitdir}/system. If the unit files being installed go into packages other than the main package, you need to set @@ -3192,8 +3215,9 @@ The utility-tasks class provides support for various "utility" type tasks that are applicable to all recipes, - such as do_clean and - do_listtasks. + such as + do_clean and + do_listtasks. diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml index f351931ab6..4aafaea674 100644 --- a/documentation/ref-manual/ref-features.xml +++ b/documentation/ref-manual/ref-features.xml @@ -53,8 +53,9 @@ go beyond simply controlling the installation of a package or packages. Sometimes a feature can influence how certain recipes are built. For example, a feature might determine whether a particular configure option - is specified within do_configure for a particular - recipe. + is specified within the + do_configure + task for a particular recipe. @@ -105,8 +106,9 @@ and they can go beyond simply controlling the installation of a package or packages. In most cases, the presence or absence of a feature translates to - the appropriate option supplied to the configure script during - do_configure for the recipes that optionally + the appropriate option supplied to the configure script during the + do_configure + task for the recipes that optionally support the feature. diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml index aea0858f73..8f62da02f0 100644 --- a/documentation/ref-manual/ref-tasks.xml +++ b/documentation/ref-manual/ref-tasks.xml @@ -189,8 +189,10 @@ <filename>do_populate_sysroot</filename> - Copies a subset of files installed by do_install into the sysroot - in order to make them available to other recipes. + Copies a subset of files installed by the + do_install + task into the sysroot in order to make them available to other + recipes. @@ -360,9 +362,11 @@ Kernel-Related Tasks - The following tasks are applicable to kernel recipes. Some of them - (for example do_menuconfig) are also applicable to recipes which use - Linux kernel style configuration (e.g. busybox). + The following tasks are applicable to kernel recipes. + Some of them (e.g. the + do_menuconfig + task) are also applicable to recipes that use + Linux kernel style configuration (e.g. BusyBox).
@@ -377,8 +381,9 @@ <filename>do_diffconfig</filename> - Compares the old and new config files after running do_menuconfig - for the kernel. + Compares the old and new config files after running the + do_menuconfig + task for the kernel.
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml index 4ff1a21323..9a027375fa 100644 --- a/documentation/ref-manual/ref-variables.xml +++ b/documentation/ref-manual/ref-variables.xml @@ -189,7 +189,8 @@ Finally, if the file referenced has not been renamed, the alternatives system will rename it to avoid the need to rename alternative files in the - do_install task while + do_install + task while retaining support for the command if necessary.
@@ -1434,7 +1435,9 @@ The destination directory. The location in the Build Directory - where components are installed by the do_install task. + where components are installed by the + do_install + task. This location defaults to: ${WORKDIR}/image @@ -1518,8 +1521,9 @@ DEPENDS = "b" Here, the dependency is such that the - do_configure task for recipe "a" - depends on the do_populate_sysroot + do_configure + task for recipe "a" depends on the + do_populate_sysroot task of recipe "b". This means anything that recipe "b" puts into sysroot is available when recipe "a" is configuring itself. @@ -1750,8 +1754,9 @@ In most cases, the presence or absence of a feature in DISTRO_FEATURES is translated to the appropriate option supplied to the configure script - during do_configure for recipes that - optionally support the feature. + during the + do_configure + task for recipes that optionally support the feature. For example, specifying "x11" in DISTRO_FEATURES, causes every piece of software built for the target that can @@ -2763,8 +2768,9 @@ Extra options passed to the make - command during the do_compile task - that specify parallel compilation. + command during the + do_compile + task that specify parallel compilation. This variable usually takes the form of -j 4, where the number represents the maximum number of parallel threads @@ -3222,7 +3228,9 @@ The location of the root filesystem while it is under - construction (i.e. during do_rootfs). + construction (i.e. during the + do_rootfs + task). This variable is not configurable. Do not change it. @@ -5395,7 +5403,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" produced, then the other package will be broken. Thus, if you attempt to include that package in an image, you will get a dependency failure from the packaging system - during do_rootfs. + during the + do_rootfs + task. Typically, if there is a chance that such a situation can @@ -5419,8 +5429,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Extra options passed to the make - command during the do_compile task - in order to specify parallel compilation on the local + command during the + do_compile + task in order to specify parallel compilation on the local build host. This variable is usually in the form "-j <x>", where x represents the maximum number of parallel threads @@ -5447,8 +5458,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Extra options passed to the make install command during the - do_install task in order to specify - parallel installation. + do_install + task in order to specify parallel installation. This variable defaults to the value of PARALLEL_MAKE. @@ -5488,7 +5499,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Specifies the utility used to apply patches for a recipe - during do_patch. + during the + do_patch + task. You can specify one of three utilities: "patch", "quilt", or "git". The default utility used is "quilt" except for the @@ -5587,9 +5600,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Points to a shared, global-state directory that holds data generated during the packaging process. During the packaging process, the - do_packagedata task packages - data for each recipe and installs it into this temporary, - shared area. + do_packagedata + task packages data for each recipe and installs it into + this temporary, shared area. This directory defaults to the following: ${STAGING_DIR_HOST}/pkgdata @@ -5620,8 +5633,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Points to a temporary work area used by the - do_package task to write output - from the do_packagedata task. + do_package + task to write output from the + do_packagedata + task. The PKGDESTWORK location defaults to the following: @@ -6069,8 +6084,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" When you use the RDEPENDS variable in a recipe, you are essentially stating that the recipe's - do_build task depends on the existence - of a specific package. + do_build + task depends on the existence of a specific package. Consider this simple example for two recipes named "a" and "b" that produce similarly named IPK packages. In this example, the RDEPENDS @@ -6080,8 +6095,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Here, the dependency is such that the do_build task for recipe "a" depends - on the do_package_write_ipk task - of recipe "b". + on the + do_package_write_ipk + task of recipe "b". This means the package file for "b" must be available when the output for recipe "a" has been completely built. More importantly, package "a" will be marked as depending @@ -6126,7 +6142,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" RDEPENDS variable must appear as it would in the PACKAGES namespace before any renaming of the output package by - classes like debian.bbclass. + classes like + debian.bbclass. diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index d34be750e3..8560e9aa4f 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml @@ -442,7 +442,10 @@ works on a per-task basis rather than a per-recipe basis. You might wonder why using a per-task basis is preferred over a per-recipe basis. To help explain, consider having the IPK packaging backend enabled and then switching to DEB. - In this case, do_install and do_package + In this case, + do_install + and + do_package outputs are still valid. However, with a per-recipe approach, the build would not include the .deb files. @@ -643,8 +646,10 @@ There are two types of output, one is just about creating a directory in WORKDIR. - A good example is the output of either do_install or - do_package. + A good example is the output of either + do_install + or + do_package. The other type of output occurs when a set of data is merged into a shared directory tree such as the sysroot. @@ -653,8 +658,9 @@ The Yocto Project team has tried to keep the details of the implementation hidden in sstate class. From a user's perspective, adding shared state wrapping to a task - is as simple as this do_deploy example taken - from the + is as simple as this + do_deploy + example taken from the deploy class: @@ -737,7 +743,9 @@ As a real world example, the aim is when building an IPK-based image, - only the do_package_write_ipk tasks would have their + only the + do_package_write_ipk + tasks would have their shared state packages fetched and extracted. Since the sysroot is not used, it would never get extracted. This is another reason why a task-based approach is preferred over a @@ -834,8 +842,9 @@ The steps you can take are as simple as changing a function's comments in the source code. For example, to invalidate package shared state files, change - the comment statements of do_package or - the comments of one of the functions it calls. + the comment statements of + do_package + or the comments of one of the functions it calls. Even though the change is purely cosmetic, it causes the checksum to be recalculated and forces the OpenEmbedded build system to run the task again. diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml index a8a6f3b92a..3748ac21bb 100644 --- a/documentation/ref-manual/usingpoky.xml +++ b/documentation/ref-manual/usingpoky.xml @@ -280,9 +280,10 @@ eglibc-initial fails to build: If your development host system has the unpatched GNU Make 3.82, - the do_install task - fails for eglibc-initial during the - build. + the + do_install + task fails for eglibc-initial during + the build. Typically, every distribution that ships GNU Make 3.82 as the default already has the patched version. @@ -370,8 +371,11 @@ Following is an example written in Python. - The code handles logging for a function that determines the number of tasks - needed to be run: + The code handles logging for a function that determines the + number of tasks needed to be run. + See the + "do_listtasks" + section for additional information: python do_listtasks() { bb.debug(2, "Starting to figure out the task list")