diff options
| -rw-r--r-- | documentation/ref-manual/closer-look.xml | 47 | ||||
| -rw-r--r-- | documentation/ref-manual/migration.xml | 13 | ||||
| -rw-r--r-- | documentation/ref-manual/ref-classes.xml | 72 | ||||
| -rw-r--r-- | documentation/ref-manual/ref-features.xml | 10 | ||||
| -rw-r--r-- | documentation/ref-manual/ref-tasks.xml | 19 | ||||
| -rw-r--r-- | documentation/ref-manual/ref-variables.xml | 67 | ||||
| -rw-r--r-- | documentation/ref-manual/technical-details.xml | 25 | ||||
| -rw-r--r-- | documentation/ref-manual/usingpoky.xml | 14 |
8 files changed, 177 insertions, 90 deletions
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 <filename>do_fetch</filename> task inside BitBake uses + The + <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link> + task inside BitBake uses the <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> variable and the argument's prefix to determine the correct fetcher module. @@ -664,9 +666,16 @@ </para> <para> - BitBake uses the <filename>do_package_write_*</filename> task to + BitBake uses the <filename>do_package_write_*</filename> tasks to place generated packages into the package holding area (e.g. <filename>do_package_write_ipk</filename> for IPK packages). + See the + "<link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link>", + "<link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>", + "<link linkend='ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></link>", + and + "<link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link>" + sections for additional information. </para> </section> @@ -700,8 +709,11 @@ </para> <para> - The <filename>do_fetch</filename> and - <filename>do_unpack</filename> tasks fetch the source files + The + <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link> + and + <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link> + tasks fetch the source files and unpack them into the work directory. By default, everything is accomplished in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, @@ -762,7 +774,9 @@ </para> <para> - The <filename>do_patch</filename> task processes recipes by + The + <link linkend='ref-tasks-patch'><filename>do_patch</filename></link> + task processes recipes by using the <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> variable to locate applicable patch files, which by default @@ -810,7 +824,8 @@ </para> <para>The configurations handled by the - <filename>do_configure</filename> task are specific + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + task are specific to source code configuration for the source code being built by the recipe.</para> @@ -827,7 +842,8 @@ <listitem><para><emphasis><filename>do_compile</filename>:</emphasis> Once a configuration task has been satisfied, BitBake compiles the source using the - <filename>do_compile</filename> task. + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> + task. Compilation occurs in the directory pointed to by the <link linkend='var-B'><filename>B</filename></link> variable. @@ -837,7 +853,8 @@ directory.</para></listitem> <listitem><para><emphasis><filename>do_install</filename>:</emphasis> Once compilation is done, BitBake executes the - <filename>do_install</filename> task. + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task. This task copies files from the <filename>B</filename> directory and places them in a holding area pointed to by the @@ -858,8 +875,11 @@ </para> <para> - The <filename>do_package</filename> and - <filename>do_packagedata</filename> tasks combine to analyze + The + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + and + <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> + tasks combine to analyze the files found in the <link linkend='var-D'><filename>D</filename></link> directory and split them into subsets based on available packages and @@ -935,7 +955,9 @@ <para> The image generation process consists of several stages and depends on many variables. - The <filename>do_rootfs</filename> task uses these key variables + The + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + task uses these key variables to help create the list of packages to actually install: <itemizedlist> <listitem><para><link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>: @@ -1046,7 +1068,8 @@ section. For information on advantages gained when building a cross-development toolchain using the - <filename>do_populate_sdk</filename> task, see the + <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link> + task, see the "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>" section in the Yocto Project Application Developer's Guide. </note> 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 <filename>/usr/share/info/dir</filename> is being installed. Your recipe should delete this file within - <filename>do_install</filename> if "make install" is - installing it.</para></listitem> + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + if "make install" is installing it. + </para></listitem> <listitem><para> If you are using the buildhistory class, the check for the package version going backwards is now controlled using a @@ -863,7 +864,9 @@ <title>Images Now Rebuild Only on Changes Instead of Every Time</title> <para> - The <filename>do_rootfs</filename> and other related image + The + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + 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 - <filename>do_populate_sdk</filename> is - <filename>task-populate-sdk</filename>. + <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link> + is <filename>task-populate-sdk</filename>. </para> </section> </section> 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. <itemizedlist> - <listitem><para><filename>do_configure</filename> ‐ Regenerates the + <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> ‐ Regenerates the configure script (using <filename>autoreconf</filename>) and then launches it with a standard set of arguments used during cross-compilation. You can pass additional parameters to <filename>configure</filename> through the <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable. </para></listitem> - <listitem><para><filename>do_compile</filename> ‐ Runs <filename>make</filename> with + <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> ‐ Runs <filename>make</filename> with arguments that specify the compiler and linker. You can pass additional arguments through the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable. </para></listitem> - <listitem><para><filename>do_install</filename> ‐ Runs <filename>make install</filename> + <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> ‐ Runs <filename>make install</filename> and passes in <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename> as <filename>DESTDIR</filename>. @@ -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 - <filename>do_deploy</filename> function to copy the files to be - deployed to + <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link> + function to copy the files to be deployed to <link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link>, and use <filename>addtask</filename> to add the task at the appropriate - place, which is usually after <filename>do_compile</filename> or - <filename>do_install</filename>. + place, which is usually after + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> + or + <link linkend='ref-tasks-install'><filename>do_install</filename></link>. The class then takes care of staging the files from <filename>DEPLOYDIR</filename> to <filename>DEPLOY_DIR_IMAGE</filename>. @@ -1174,7 +1176,8 @@ <para> The <filename>image-mklibs</filename> class enables the use of the <filename>mklibs</filename> utility during the - <filename>do_rootfs</filename> task, which optimizes the size of + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + task, which optimizes the size of libraries contained in the image. </para> @@ -1195,7 +1198,9 @@ <para> The <filename>image-prelink</filename> class enables the use of the <filename>prelink</filename> utility during - the <filename>do_rootfs</filename> task, which optimizes the dynamic + the + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + task, which optimizes the dynamic linking of shared libraries to reduce executable startup time. </para> @@ -1310,7 +1315,9 @@ thus is not normally enabled. </para></listitem> <listitem><para><emphasis><filename>compile-host-path:</filename></emphasis> - Checks the <filename>do_compile</filename> log for indications + Checks the + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> + 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 @@ <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>. </para></listitem> <listitem><para><emphasis><filename>install-host-path:</filename></emphasis> - Checks the <filename>do_install</filename> log for indications + Checks the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + 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 @@ </para></listitem> <listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis> Checks to see if the <filename>PKGV</filename> variable - is undefined during <filename>do_package</filename>. + is undefined during + <link linkend='ref-tasks-package'><filename>do_package</filename></link>. </para></listitem> <listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis> Checks through the variables @@ -1569,7 +1579,8 @@ <link linkend='var-D'><filename>D</filename></link>, <link linkend='var-PN'><filename>PN</filename></link>, and <link linkend='var-PKGD'><filename>PKGD</filename></link>) are - undefined during <filename>do_package</filename>. + undefined during + <link linkend='ref-tasks-package'><filename>do_package</filename></link>. </para></listitem> <listitem><para><emphasis><filename>version-going-backwards:</filename></emphasis> If Build History is enabled, reports when a package @@ -1803,8 +1814,11 @@ <link linkend='ref-classes-module-base'><filename>module-base</filename></link> and <link linkend='ref-classes-kernel-module-split'><filename>kernel-module-split</filename></link> - classes, and implements <filename>do_compile</filename> and - <filename>do_install</filename> functions. + classes, and implements the + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> + and + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + tasks. The class provides everything needed to build and package a kernel module. </para> @@ -2216,7 +2230,9 @@ <para> The <filename>patch</filename> class provides all functionality for - applying patches during the <filename>do_patch</filename> task. + applying patches during the + <link linkend='ref-tasks-patch'><filename>do_patch</filename></link> + task. </para> <para> @@ -2285,7 +2301,9 @@ The <filename>populate_sdk</filename> class provides support for SDK-only recipes. For information on advantages gained when building a cross-development - toolchain using the <filename>do_populate_sdk</filename> task, see the + toolchain using the + <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link> + task, see the "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>" section in the Yocto Project Application Developer's Guide. </para> @@ -2360,7 +2378,8 @@ section. For information on advantages gained when building a cross-development toolchain using the - <filename>do_populate_sdk</filename> task, see the + <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link> + task, see the "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>" section in the Yocto Project Application Developer's Guide. </para> @@ -2722,7 +2741,9 @@ provides functionality for handling site configuration. The class is used by the <link linkend='ref-classes-autotools'><filename>autotools</filename></link> - class to accelerate the <filename>do_configure</filename> task. + class to accelerate the + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + task. </para> </section> @@ -2802,7 +2823,8 @@ <para> The <filename>staging</filename> class provides support for staging files into the sysroot during the - <filename>do_populate_sysroot</filename> task. + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task. The class is enabled by default because it is inherited by the <link linkend='ref-classes-base'><filename>base</filename></link> class. @@ -2873,8 +2895,9 @@ <para> Under this class, the recipe or Makefile (i.e. whatever the recipe is - calling during the <filename>do_install</filename> task) installs unit - files into + calling during the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task) installs unit files into <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}${systemd_unitdir}/system</filename>. If the unit files being installed go into packages other than the main package, you need to set @@ -3192,8 +3215,9 @@ <para> The <filename>utility-tasks</filename> class provides support for various "utility" type tasks that are applicable to all recipes, - such as <filename>do_clean</filename> and - <filename>do_listtasks</filename>. + such as + <link linkend='ref-tasks-clean'><filename>do_clean</filename></link> and + <link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>. </para> <para> 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 <filename>do_configure</filename> for a particular - recipe. + is specified within the + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + task for a particular recipe. </para> <para> @@ -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 - <filename>do_configure</filename> for the recipes that optionally + the appropriate option supplied to the configure script during the + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + task for the recipes that optionally support the feature. </para> 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 @@ <title><filename>do_populate_sysroot</filename></title> <para> - 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 + <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> @@ -360,9 +362,11 @@ <title>Kernel-Related Tasks</title> <para> - 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 + <link linkend='ref-tasks-menuconfig'><filename>do_menuconfig</filename></link> + task) are also applicable to recipes that use + Linux kernel style configuration (e.g. BusyBox). </para> <section id='ref-tasks-compile_kernelmodules'> @@ -377,8 +381,9 @@ <title><filename>do_diffconfig</filename></title> <para> - Compares the old and new config files after running do_menuconfig - for the kernel. + 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> 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 - <filename>do_install</filename> task while + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task while retaining support for the command if necessary. </para> </note> @@ -1434,7 +1435,9 @@ <para> The destination directory. The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> - where components are installed by the <filename>do_install</filename> task. + where components are installed by the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task. This location defaults to: <literallayout class='monospaced'> ${WORKDIR}/image @@ -1518,8 +1521,9 @@ DEPENDS = "b" </literallayout> Here, the dependency is such that the - <filename>do_configure</filename> task for recipe "a" - depends on the <filename>do_populate_sysroot</filename> + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + task for recipe "a" depends on the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> 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 <filename>DISTRO_FEATURES</filename> is translated to the appropriate option supplied to the configure script - during <filename>do_configure</filename> for recipes that - optionally support the feature. + during the + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + task for recipes that optionally support the feature. For example, specifying "x11" in <filename>DISTRO_FEATURES</filename>, causes every piece of software built for the target that can @@ -2763,8 +2768,9 @@ <glossdef> <para> Extra options passed to the <filename>make</filename> - command during the <filename>do_compile</filename> task - that specify parallel compilation. + command during the + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> + task that specify parallel compilation. This variable usually takes the form of <filename>-j 4</filename>, where the number represents the maximum number of parallel threads @@ -3222,7 +3228,9 @@ <glossdef> <para> The location of the root filesystem while it is under - construction (i.e. during <filename>do_rootfs</filename>). + construction (i.e. during the + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + task). This variable is not configurable. Do not change it. </para> @@ -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 <filename>do_rootfs</filename>. + during the + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + task. </para> <para> 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" <glossdef> <para> Extra options passed to the <filename>make</filename> - command during the <filename>do_compile</filename> task - in order to specify parallel compilation on the local + command during the + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> + 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" <para> Extra options passed to the <filename>make install</filename> command during the - <filename>do_install</filename> task in order to specify - parallel installation. + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task in order to specify parallel installation. This variable defaults to the value of <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>. <note> @@ -5488,7 +5499,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdef> <para> Specifies the utility used to apply patches for a recipe - during <filename>do_patch</filename>. + during the + <link linkend='ref-tasks-patch'><filename>do_patch</filename></link> + 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 - <filename>do_packagedata</filename> task packages - data for each recipe and installs it into this temporary, - shared area. + <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> + task packages data for each recipe and installs it into + this temporary, shared area. This directory defaults to the following: <literallayout class='monospaced'> ${STAGING_DIR_HOST}/pkgdata @@ -5620,8 +5633,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdef> <para> Points to a temporary work area used by the - <filename>do_package</filename> task to write output - from the <filename>do_packagedata</filename> task. + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task to write output from the + <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> + task. The <filename>PKGDESTWORK</filename> location defaults to the following: <literallayout class='monospaced'> @@ -6069,8 +6084,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <para> When you use the <filename>RDEPENDS</filename> variable in a recipe, you are essentially stating that the recipe's - <filename>do_build</filename> task depends on the existence - of a specific package. + <link linkend='ref-tasks-build'><filename>do_build</filename></link> + 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 <filename>RDEPENDS</filename> @@ -6080,8 +6095,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </literallayout> Here, the dependency is such that the <filename>do_build</filename> task for recipe "a" depends - on the <filename>do_package_write_ipk</filename> task - of recipe "b". + on the + <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link> + 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" <filename>RDEPENDS</filename> variable must appear as it would in the <filename>PACKAGES</filename> namespace before any renaming of the output package by - classes like <filename>debian.bbclass</filename>. + classes like + <link linkend='ref-classes-debian'><filename>debian.bbclass</filename></link>. </para> <para> 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, <filename>do_install</filename> and <filename>do_package</filename> + In this case, + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + and + <link linkend='ref-tasks-package'><filename>do_package</filename></link> outputs are still valid. However, with a per-recipe approach, the build would not include the <filename>.deb</filename> files. @@ -643,8 +646,10 @@ <para> There are two types of output, one is just about creating a directory in <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>. - A good example is the output of either <filename>do_install</filename> or - <filename>do_package</filename>. + A good example is the output of either + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + or + <link linkend='ref-tasks-package'><filename>do_package</filename></link>. The other type of output occurs when a set of data is merged into a shared directory tree such as the sysroot. </para> @@ -653,8 +658,9 @@ The Yocto Project team has tried to keep the details of the implementation hidden in <filename>sstate</filename> class. From a user's perspective, adding shared state wrapping to a task - is as simple as this <filename>do_deploy</filename> example taken - from the + is as simple as this + <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link> + example taken from the <link linkend='ref-classes-deploy'><filename>deploy</filename></link> class: <literallayout class='monospaced'> @@ -737,7 +743,9 @@ <para> As a real world example, the aim is when building an IPK-based image, - only the <filename>do_package_write_ipk</filename> tasks would have their + only the + <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link> + 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 <filename>do_package</filename> or - the comments of one of the functions it calls. + the comment statements of + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + 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 @@ <listitem><para><emphasis><filename>eglibc-initial</filename> fails to build</emphasis>: If your development host system has the unpatched <filename>GNU Make 3.82</filename>, - the <filename>do_install</filename> task - fails for <filename>eglibc-initial</filename> during the - build.</para> + the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task fails for <filename>eglibc-initial</filename> during + the build.</para> <para>Typically, every distribution that ships <filename>GNU Make 3.82</filename> as the default already has the patched version. @@ -370,8 +371,11 @@ <para> 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 + "<link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>" + section for additional information: <literallayout class='monospaced'> python do_listtasks() { bb.debug(2, "Starting to figure out the task list") |