summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/closer-look.xml47
-rw-r--r--documentation/ref-manual/migration.xml13
-rw-r--r--documentation/ref-manual/ref-classes.xml72
-rw-r--r--documentation/ref-manual/ref-features.xml10
-rw-r--r--documentation/ref-manual/ref-tasks.xml19
-rw-r--r--documentation/ref-manual/ref-variables.xml67
-rw-r--r--documentation/ref-manual/technical-details.xml25
-rw-r--r--documentation/ref-manual/usingpoky.xml14
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 @@
568 Another place the build system can get source files from is 568 Another place the build system can get source files from is
569 through an SCM such as Git or Subversion. 569 through an SCM such as Git or Subversion.
570 In this case, a repository is cloned or checked out. 570 In this case, a repository is cloned or checked out.
571 The <filename>do_fetch</filename> task inside BitBake uses 571 The
572 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>
573 task inside BitBake uses
572 the <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> 574 the <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
573 variable and the argument's prefix to determine the correct 575 variable and the argument's prefix to determine the correct
574 fetcher module. 576 fetcher module.
@@ -664,9 +666,16 @@
664 </para> 666 </para>
665 667
666 <para> 668 <para>
667 BitBake uses the <filename>do_package_write_*</filename> task to 669 BitBake uses the <filename>do_package_write_*</filename> tasks to
668 place generated packages into the package holding area (e.g. 670 place generated packages into the package holding area (e.g.
669 <filename>do_package_write_ipk</filename> for IPK packages). 671 <filename>do_package_write_ipk</filename> for IPK packages).
672 See the
673 "<link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link>",
674 "<link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>",
675 "<link linkend='ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></link>",
676 and
677 "<link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link>"
678 sections for additional information.
670 </para> 679 </para>
671 </section> 680 </section>
672 681
@@ -700,8 +709,11 @@
700 </para> 709 </para>
701 710
702 <para> 711 <para>
703 The <filename>do_fetch</filename> and 712 The
704 <filename>do_unpack</filename> tasks fetch the source files 713 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>
714 and
715 <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link>
716 tasks fetch the source files
705 and unpack them into the work directory. 717 and unpack them into the work directory.
706 By default, everything is accomplished in the 718 By default, everything is accomplished in the
707 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, 719 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
@@ -762,7 +774,9 @@
762 </para> 774 </para>
763 775
764 <para> 776 <para>
765 The <filename>do_patch</filename> task processes recipes by 777 The
778 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
779 task processes recipes by
766 using the 780 using the
767 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> 781 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
768 variable to locate applicable patch files, which by default 782 variable to locate applicable patch files, which by default
@@ -810,7 +824,8 @@
810 </para> 824 </para>
811 825
812 <para>The configurations handled by the 826 <para>The configurations handled by the
813 <filename>do_configure</filename> task are specific 827 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
828 task are specific
814 to source code configuration for the source code 829 to source code configuration for the source code
815 being built by the recipe.</para> 830 being built by the recipe.</para>
816 831
@@ -827,7 +842,8 @@
827 <listitem><para><emphasis><filename>do_compile</filename>:</emphasis> 842 <listitem><para><emphasis><filename>do_compile</filename>:</emphasis>
828 Once a configuration task has been satisfied, BitBake 843 Once a configuration task has been satisfied, BitBake
829 compiles the source using the 844 compiles the source using the
830 <filename>do_compile</filename> task. 845 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
846 task.
831 Compilation occurs in the directory pointed to by the 847 Compilation occurs in the directory pointed to by the
832 <link linkend='var-B'><filename>B</filename></link> 848 <link linkend='var-B'><filename>B</filename></link>
833 variable. 849 variable.
@@ -837,7 +853,8 @@
837 directory.</para></listitem> 853 directory.</para></listitem>
838 <listitem><para><emphasis><filename>do_install</filename>:</emphasis> 854 <listitem><para><emphasis><filename>do_install</filename>:</emphasis>
839 Once compilation is done, BitBake executes the 855 Once compilation is done, BitBake executes the
840 <filename>do_install</filename> task. 856 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
857 task.
841 This task copies files from the <filename>B</filename> 858 This task copies files from the <filename>B</filename>
842 directory and places them in a holding area pointed to 859 directory and places them in a holding area pointed to
843 by the 860 by the
@@ -858,8 +875,11 @@
858 </para> 875 </para>
859 876
860 <para> 877 <para>
861 The <filename>do_package</filename> and 878 The
862 <filename>do_packagedata</filename> tasks combine to analyze 879 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
880 and
881 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
882 tasks combine to analyze
863 the files found in the 883 the files found in the
864 <link linkend='var-D'><filename>D</filename></link> directory 884 <link linkend='var-D'><filename>D</filename></link> directory
865 and split them into subsets based on available packages and 885 and split them into subsets based on available packages and
@@ -935,7 +955,9 @@
935 <para> 955 <para>
936 The image generation process consists of several stages and 956 The image generation process consists of several stages and
937 depends on many variables. 957 depends on many variables.
938 The <filename>do_rootfs</filename> task uses these key variables 958 The
959 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
960 task uses these key variables
939 to help create the list of packages to actually install: 961 to help create the list of packages to actually install:
940 <itemizedlist> 962 <itemizedlist>
941 <listitem><para><link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>: 963 <listitem><para><link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>:
@@ -1046,7 +1068,8 @@
1046 section. 1068 section.
1047 For information on advantages gained when building a 1069 For information on advantages gained when building a
1048 cross-development toolchain using the 1070 cross-development toolchain using the
1049 <filename>do_populate_sdk</filename> task, see the 1071 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
1072 task, see the
1050 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>" 1073 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
1051 section in the Yocto Project Application Developer's Guide. 1074 section in the Yocto Project Application Developer's Guide.
1052 </note> 1075 </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 @@
701 An additional QA check has been added to check if 701 An additional QA check has been added to check if
702 <filename>/usr/share/info/dir</filename> is being installed. 702 <filename>/usr/share/info/dir</filename> is being installed.
703 Your recipe should delete this file within 703 Your recipe should delete this file within
704 <filename>do_install</filename> if "make install" is 704 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
705 installing it.</para></listitem> 705 if "make install" is installing it.
706 </para></listitem>
706 <listitem><para> 707 <listitem><para>
707 If you are using the buildhistory class, the check for the 708 If you are using the buildhistory class, the check for the
708 package version going backwards is now controlled using a 709 package version going backwards is now controlled using a
@@ -863,7 +864,9 @@
863 <title>Images Now Rebuild Only on Changes Instead of Every Time</title> 864 <title>Images Now Rebuild Only on Changes Instead of Every Time</title>
864 865
865 <para> 866 <para>
866 The <filename>do_rootfs</filename> and other related image 867 The
868 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
869 and other related image
867 construction tasks are no longer marked as "nostamp". 870 construction tasks are no longer marked as "nostamp".
868 Consequently, they will only be re-executed when their inputs have 871 Consequently, they will only be re-executed when their inputs have
869 changed. 872 changed.
@@ -1246,8 +1249,8 @@
1246 underscores replaced by hyphens for the override so that they 1249 underscores replaced by hyphens for the override so that they
1247 now function properly. 1250 now function properly.
1248 For example, the task override for 1251 For example, the task override for
1249 <filename>do_populate_sdk</filename> is 1252 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
1250 <filename>task-populate-sdk</filename>. 1253 is <filename>task-populate-sdk</filename>.
1251 </para> 1254 </para>
1252 </section> 1255 </section>
1253 </section> 1256 </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 @@
105 It's useful to have some idea of how the tasks defined by this class work 105 It's useful to have some idea of how the tasks defined by this class work
106 and what they do behind the scenes. 106 and what they do behind the scenes.
107 <itemizedlist> 107 <itemizedlist>
108 <listitem><para><filename>do_configure</filename> &dash; Regenerates the 108 <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> &dash; Regenerates the
109 configure script (using <filename>autoreconf</filename>) and then launches it 109 configure script (using <filename>autoreconf</filename>) and then launches it
110 with a standard set of arguments used during cross-compilation. 110 with a standard set of arguments used during cross-compilation.
111 You can pass additional parameters to <filename>configure</filename> through the 111 You can pass additional parameters to <filename>configure</filename> through the
112 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable. 112 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
113 </para></listitem> 113 </para></listitem>
114 <listitem><para><filename>do_compile</filename> &dash; Runs <filename>make</filename> with 114 <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> &dash; Runs <filename>make</filename> with
115 arguments that specify the compiler and linker. 115 arguments that specify the compiler and linker.
116 You can pass additional arguments through 116 You can pass additional arguments through
117 the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable. 117 the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
118 </para></listitem> 118 </para></listitem>
119 <listitem><para><filename>do_install</filename> &dash; Runs <filename>make install</filename> 119 <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> &dash; Runs <filename>make install</filename>
120 and passes in 120 and passes in
121 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename> 121 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
122 as <filename>DESTDIR</filename>. 122 as <filename>DESTDIR</filename>.
@@ -550,12 +550,14 @@
550 The main function of this class is to allow the deploy step to be 550 The main function of this class is to allow the deploy step to be
551 accelerated by shared state. 551 accelerated by shared state.
552 Recipes that inherit this class should define their own 552 Recipes that inherit this class should define their own
553 <filename>do_deploy</filename> function to copy the files to be 553 <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link>
554 deployed to 554 function to copy the files to be deployed to
555 <link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link>, 555 <link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link>,
556 and use <filename>addtask</filename> to add the task at the appropriate 556 and use <filename>addtask</filename> to add the task at the appropriate
557 place, which is usually after <filename>do_compile</filename> or 557 place, which is usually after
558 <filename>do_install</filename>. 558 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
559 or
560 <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
559 The class then takes care of staging the files from 561 The class then takes care of staging the files from
560 <filename>DEPLOYDIR</filename> to 562 <filename>DEPLOYDIR</filename> to
561 <filename>DEPLOY_DIR_IMAGE</filename>. 563 <filename>DEPLOY_DIR_IMAGE</filename>.
@@ -1174,7 +1176,8 @@
1174 <para> 1176 <para>
1175 The <filename>image-mklibs</filename> class 1177 The <filename>image-mklibs</filename> class
1176 enables the use of the <filename>mklibs</filename> utility during the 1178 enables the use of the <filename>mklibs</filename> utility during the
1177 <filename>do_rootfs</filename> task, which optimizes the size of 1179 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
1180 task, which optimizes the size of
1178 libraries contained in the image. 1181 libraries contained in the image.
1179 </para> 1182 </para>
1180 1183
@@ -1195,7 +1198,9 @@
1195 <para> 1198 <para>
1196 The <filename>image-prelink</filename> class 1199 The <filename>image-prelink</filename> class
1197 enables the use of the <filename>prelink</filename> utility during 1200 enables the use of the <filename>prelink</filename> utility during
1198 the <filename>do_rootfs</filename> task, which optimizes the dynamic 1201 the
1202 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
1203 task, which optimizes the dynamic
1199 linking of shared libraries to reduce executable startup time. 1204 linking of shared libraries to reduce executable startup time.
1200 </para> 1205 </para>
1201 1206
@@ -1310,7 +1315,9 @@
1310 thus is not normally enabled. 1315 thus is not normally enabled.
1311 </para></listitem> 1316 </para></listitem>
1312 <listitem><para><emphasis><filename>compile-host-path:</filename></emphasis> 1317 <listitem><para><emphasis><filename>compile-host-path:</filename></emphasis>
1313 Checks the <filename>do_compile</filename> log for indications 1318 Checks the
1319 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
1320 log for indications
1314 that paths to locations on the build host were used. 1321 that paths to locations on the build host were used.
1315 Using such paths might result in host contamination of the 1322 Using such paths might result in host contamination of the
1316 build output. 1323 build output.
@@ -1367,7 +1374,9 @@
1367 <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>. 1374 <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>.
1368 </para></listitem> 1375 </para></listitem>
1369 <listitem><para><emphasis><filename>install-host-path:</filename></emphasis> 1376 <listitem><para><emphasis><filename>install-host-path:</filename></emphasis>
1370 Checks the <filename>do_install</filename> log for indications 1377 Checks the
1378 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1379 log for indications
1371 that paths to locations on the build host were used. 1380 that paths to locations on the build host were used.
1372 Using such paths might result in host contamination of the 1381 Using such paths might result in host contamination of the
1373 build output. 1382 build output.
@@ -1451,7 +1460,8 @@
1451 </para></listitem> 1460 </para></listitem>
1452 <listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis> 1461 <listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis>
1453 Checks to see if the <filename>PKGV</filename> variable 1462 Checks to see if the <filename>PKGV</filename> variable
1454 is undefined during <filename>do_package</filename>. 1463 is undefined during
1464 <link linkend='ref-tasks-package'><filename>do_package</filename></link>.
1455 </para></listitem> 1465 </para></listitem>
1456 <listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis> 1466 <listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis>
1457 Checks through the variables 1467 Checks through the variables
@@ -1569,7 +1579,8 @@
1569 <link linkend='var-D'><filename>D</filename></link>, 1579 <link linkend='var-D'><filename>D</filename></link>,
1570 <link linkend='var-PN'><filename>PN</filename></link>, and 1580 <link linkend='var-PN'><filename>PN</filename></link>, and
1571 <link linkend='var-PKGD'><filename>PKGD</filename></link>) are 1581 <link linkend='var-PKGD'><filename>PKGD</filename></link>) are
1572 undefined during <filename>do_package</filename>. 1582 undefined during
1583 <link linkend='ref-tasks-package'><filename>do_package</filename></link>.
1573 </para></listitem> 1584 </para></listitem>
1574 <listitem><para><emphasis><filename>version-going-backwards:</filename></emphasis> 1585 <listitem><para><emphasis><filename>version-going-backwards:</filename></emphasis>
1575 If Build History is enabled, reports when a package 1586 If Build History is enabled, reports when a package
@@ -1803,8 +1814,11 @@
1803 <link linkend='ref-classes-module-base'><filename>module-base</filename></link> 1814 <link linkend='ref-classes-module-base'><filename>module-base</filename></link>
1804 and 1815 and
1805 <link linkend='ref-classes-kernel-module-split'><filename>kernel-module-split</filename></link> 1816 <link linkend='ref-classes-kernel-module-split'><filename>kernel-module-split</filename></link>
1806 classes, and implements <filename>do_compile</filename> and 1817 classes, and implements the
1807 <filename>do_install</filename> functions. 1818 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
1819 and
1820 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1821 tasks.
1808 The class provides everything needed to build and package a kernel 1822 The class provides everything needed to build and package a kernel
1809 module. 1823 module.
1810 </para> 1824 </para>
@@ -2216,7 +2230,9 @@
2216 2230
2217 <para> 2231 <para>
2218 The <filename>patch</filename> class provides all functionality for 2232 The <filename>patch</filename> class provides all functionality for
2219 applying patches during the <filename>do_patch</filename> task. 2233 applying patches during the
2234 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
2235 task.
2220 </para> 2236 </para>
2221 2237
2222 <para> 2238 <para>
@@ -2285,7 +2301,9 @@
2285 The <filename>populate_sdk</filename> class provides support for 2301 The <filename>populate_sdk</filename> class provides support for
2286 SDK-only recipes. 2302 SDK-only recipes.
2287 For information on advantages gained when building a cross-development 2303 For information on advantages gained when building a cross-development
2288 toolchain using the <filename>do_populate_sdk</filename> task, see the 2304 toolchain using the
2305 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
2306 task, see the
2289 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>" 2307 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
2290 section in the Yocto Project Application Developer's Guide. 2308 section in the Yocto Project Application Developer's Guide.
2291 </para> 2309 </para>
@@ -2360,7 +2378,8 @@
2360 section. 2378 section.
2361 For information on advantages gained when building a 2379 For information on advantages gained when building a
2362 cross-development toolchain using the 2380 cross-development toolchain using the
2363 <filename>do_populate_sdk</filename> task, see the 2381 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
2382 task, see the
2364 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>" 2383 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
2365 section in the Yocto Project Application Developer's Guide. 2384 section in the Yocto Project Application Developer's Guide.
2366 </para> 2385 </para>
@@ -2722,7 +2741,9 @@
2722 provides functionality for handling site configuration. 2741 provides functionality for handling site configuration.
2723 The class is used by the 2742 The class is used by the
2724 <link linkend='ref-classes-autotools'><filename>autotools</filename></link> 2743 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
2725 class to accelerate the <filename>do_configure</filename> task. 2744 class to accelerate the
2745 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2746 task.
2726 </para> 2747 </para>
2727</section> 2748</section>
2728 2749
@@ -2802,7 +2823,8 @@
2802 <para> 2823 <para>
2803 The <filename>staging</filename> class provides support for staging 2824 The <filename>staging</filename> class provides support for staging
2804 files into the sysroot during the 2825 files into the sysroot during the
2805 <filename>do_populate_sysroot</filename> task. 2826 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
2827 task.
2806 The class is enabled by default because it is inherited by the 2828 The class is enabled by default because it is inherited by the
2807 <link linkend='ref-classes-base'><filename>base</filename></link> 2829 <link linkend='ref-classes-base'><filename>base</filename></link>
2808 class. 2830 class.
@@ -2873,8 +2895,9 @@
2873 2895
2874 <para> 2896 <para>
2875 Under this class, the recipe or Makefile (i.e. whatever the recipe is 2897 Under this class, the recipe or Makefile (i.e. whatever the recipe is
2876 calling during the <filename>do_install</filename> task) installs unit 2898 calling during the
2877 files into 2899 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
2900 task) installs unit files into
2878 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}${systemd_unitdir}/system</filename>. 2901 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}${systemd_unitdir}/system</filename>.
2879 If the unit files being installed go into packages other than the 2902 If the unit files being installed go into packages other than the
2880 main package, you need to set 2903 main package, you need to set
@@ -3192,8 +3215,9 @@
3192 <para> 3215 <para>
3193 The <filename>utility-tasks</filename> class provides support for 3216 The <filename>utility-tasks</filename> class provides support for
3194 various "utility" type tasks that are applicable to all recipes, 3217 various "utility" type tasks that are applicable to all recipes,
3195 such as <filename>do_clean</filename> and 3218 such as
3196 <filename>do_listtasks</filename>. 3219 <link linkend='ref-tasks-clean'><filename>do_clean</filename></link> and
3220 <link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>.
3197 </para> 3221 </para>
3198 3222
3199 <para> 3223 <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 @@
53 go beyond simply controlling the installation of a package or packages. 53 go beyond simply controlling the installation of a package or packages.
54 Sometimes a feature can influence how certain recipes are built. 54 Sometimes a feature can influence how certain recipes are built.
55 For example, a feature might determine whether a particular configure option 55 For example, a feature might determine whether a particular configure option
56 is specified within <filename>do_configure</filename> for a particular 56 is specified within the
57 recipe. 57 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
58 task for a particular recipe.
58 </para> 59 </para>
59 60
60 <para> 61 <para>
@@ -105,8 +106,9 @@
105 and they can go beyond simply controlling the installation of a 106 and they can go beyond simply controlling the installation of a
106 package or packages. 107 package or packages.
107 In most cases, the presence or absence of a feature translates to 108 In most cases, the presence or absence of a feature translates to
108 the appropriate option supplied to the configure script during 109 the appropriate option supplied to the configure script during the
109 <filename>do_configure</filename> for the recipes that optionally 110 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
111 task for the recipes that optionally
110 support the feature. 112 support the feature.
111 </para> 113 </para>
112 114
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 @@
189 <title><filename>do_populate_sysroot</filename></title> 189 <title><filename>do_populate_sysroot</filename></title>
190 190
191 <para> 191 <para>
192 Copies a subset of files installed by do_install into the sysroot 192 Copies a subset of files installed by the
193 in order to make them available to other recipes. 193 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
194 task into the sysroot in order to make them available to other
195 recipes.
194 </para> 196 </para>
195 </section> 197 </section>
196 198
@@ -360,9 +362,11 @@
360 <title>Kernel-Related Tasks</title> 362 <title>Kernel-Related Tasks</title>
361 363
362 <para> 364 <para>
363 The following tasks are applicable to kernel recipes. Some of them 365 The following tasks are applicable to kernel recipes.
364 (for example do_menuconfig) are also applicable to recipes which use 366 Some of them (e.g. the
365 Linux kernel style configuration (e.g. busybox). 367 <link linkend='ref-tasks-menuconfig'><filename>do_menuconfig</filename></link>
368 task) are also applicable to recipes that use
369 Linux kernel style configuration (e.g. BusyBox).
366 </para> 370 </para>
367 371
368 <section id='ref-tasks-compile_kernelmodules'> 372 <section id='ref-tasks-compile_kernelmodules'>
@@ -377,8 +381,9 @@
377 <title><filename>do_diffconfig</filename></title> 381 <title><filename>do_diffconfig</filename></title>
378 382
379 <para> 383 <para>
380 Compares the old and new config files after running do_menuconfig 384 Compares the old and new config files after running the
381 for the kernel. 385 <link linkend='ref-tasks-menuconfig'><filename>do_menuconfig</filename></link>
386 task for the kernel.
382 </para> 387 </para>
383 </section> 388 </section>
384 389
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 @@
189 Finally, if the file referenced has not been 189 Finally, if the file referenced has not been
190 renamed, the alternatives system will rename it to 190 renamed, the alternatives system will rename it to
191 avoid the need to rename alternative files in the 191 avoid the need to rename alternative files in the
192 <filename>do_install</filename> task while 192 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
193 task while
193 retaining support for the command if necessary. 194 retaining support for the command if necessary.
194 </para> 195 </para>
195 </note> 196 </note>
@@ -1434,7 +1435,9 @@
1434 <para> 1435 <para>
1435 The destination directory. 1436 The destination directory.
1436 The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> 1437 The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1437 where components are installed by the <filename>do_install</filename> task. 1438 where components are installed by the
1439 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1440 task.
1438 This location defaults to: 1441 This location defaults to:
1439 <literallayout class='monospaced'> 1442 <literallayout class='monospaced'>
1440 ${WORKDIR}/image 1443 ${WORKDIR}/image
@@ -1518,8 +1521,9 @@
1518 DEPENDS = "b" 1521 DEPENDS = "b"
1519 </literallayout> 1522 </literallayout>
1520 Here, the dependency is such that the 1523 Here, the dependency is such that the
1521 <filename>do_configure</filename> task for recipe "a" 1524 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
1522 depends on the <filename>do_populate_sysroot</filename> 1525 task for recipe "a" depends on the
1526 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
1523 task of recipe "b". 1527 task of recipe "b".
1524 This means anything that recipe "b" puts into sysroot 1528 This means anything that recipe "b" puts into sysroot
1525 is available when recipe "a" is configuring itself. 1529 is available when recipe "a" is configuring itself.
@@ -1750,8 +1754,9 @@
1750 In most cases, the presence or absence of a feature in 1754 In most cases, the presence or absence of a feature in
1751 <filename>DISTRO_FEATURES</filename> is translated to the 1755 <filename>DISTRO_FEATURES</filename> is translated to the
1752 appropriate option supplied to the configure script 1756 appropriate option supplied to the configure script
1753 during <filename>do_configure</filename> for recipes that 1757 during the
1754 optionally support the feature. 1758 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
1759 task for recipes that optionally support the feature.
1755 For example, specifying "x11" in 1760 For example, specifying "x11" in
1756 <filename>DISTRO_FEATURES</filename>, causes 1761 <filename>DISTRO_FEATURES</filename>, causes
1757 every piece of software built for the target that can 1762 every piece of software built for the target that can
@@ -2763,8 +2768,9 @@
2763 <glossdef> 2768 <glossdef>
2764 <para> 2769 <para>
2765 Extra options passed to the <filename>make</filename> 2770 Extra options passed to the <filename>make</filename>
2766 command during the <filename>do_compile</filename> task 2771 command during the
2767 that specify parallel compilation. 2772 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
2773 task that specify parallel compilation.
2768 This variable usually takes the form of 2774 This variable usually takes the form of
2769 <filename>-j 4</filename>, where the number 2775 <filename>-j 4</filename>, where the number
2770 represents the maximum number of parallel threads 2776 represents the maximum number of parallel threads
@@ -3222,7 +3228,9 @@
3222 <glossdef> 3228 <glossdef>
3223 <para> 3229 <para>
3224 The location of the root filesystem while it is under 3230 The location of the root filesystem while it is under
3225 construction (i.e. during <filename>do_rootfs</filename>). 3231 construction (i.e. during the
3232 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
3233 task).
3226 This variable is not configurable. 3234 This variable is not configurable.
3227 Do not change it. 3235 Do not change it.
3228 </para> 3236 </para>
@@ -5395,7 +5403,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
5395 produced, then the other package will be broken. 5403 produced, then the other package will be broken.
5396 Thus, if you attempt to include that package in an image, 5404 Thus, if you attempt to include that package in an image,
5397 you will get a dependency failure from the packaging system 5405 you will get a dependency failure from the packaging system
5398 during <filename>do_rootfs</filename>. 5406 during the
5407 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
5408 task.
5399 </para> 5409 </para>
5400 <para> 5410 <para>
5401 Typically, if there is a chance that such a situation can 5411 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"
5419 <glossdef> 5429 <glossdef>
5420 <para> 5430 <para>
5421 Extra options passed to the <filename>make</filename> 5431 Extra options passed to the <filename>make</filename>
5422 command during the <filename>do_compile</filename> task 5432 command during the
5423 in order to specify parallel compilation on the local 5433 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
5434 task in order to specify parallel compilation on the local
5424 build host. 5435 build host.
5425 This variable is usually in the form "-j &lt;x&gt;", 5436 This variable is usually in the form "-j &lt;x&gt;",
5426 where x represents the maximum number of parallel threads 5437 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"
5447 <para> 5458 <para>
5448 Extra options passed to the 5459 Extra options passed to the
5449 <filename>make install</filename> command during the 5460 <filename>make install</filename> command during the
5450 <filename>do_install</filename> task in order to specify 5461 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
5451 parallel installation. 5462 task in order to specify parallel installation.
5452 This variable defaults to the value of 5463 This variable defaults to the value of
5453 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>. 5464 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
5454 <note> 5465 <note>
@@ -5488,7 +5499,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
5488 <glossdef> 5499 <glossdef>
5489 <para> 5500 <para>
5490 Specifies the utility used to apply patches for a recipe 5501 Specifies the utility used to apply patches for a recipe
5491 during <filename>do_patch</filename>. 5502 during the
5503 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
5504 task.
5492 You can specify one of three utilities: "patch", "quilt", or 5505 You can specify one of three utilities: "patch", "quilt", or
5493 "git". 5506 "git".
5494 The default utility used is "quilt" except for the 5507 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"
5587 Points to a shared, global-state directory that holds data 5600 Points to a shared, global-state directory that holds data
5588 generated during the packaging process. 5601 generated during the packaging process.
5589 During the packaging process, the 5602 During the packaging process, the
5590 <filename>do_packagedata</filename> task packages 5603 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
5591 data for each recipe and installs it into this temporary, 5604 task packages data for each recipe and installs it into
5592 shared area. 5605 this temporary, shared area.
5593 This directory defaults to the following: 5606 This directory defaults to the following:
5594 <literallayout class='monospaced'> 5607 <literallayout class='monospaced'>
5595 ${STAGING_DIR_HOST}/pkgdata 5608 ${STAGING_DIR_HOST}/pkgdata
@@ -5620,8 +5633,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
5620 <glossdef> 5633 <glossdef>
5621 <para> 5634 <para>
5622 Points to a temporary work area used by the 5635 Points to a temporary work area used by the
5623 <filename>do_package</filename> task to write output 5636 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
5624 from the <filename>do_packagedata</filename> task. 5637 task to write output from the
5638 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
5639 task.
5625 The <filename>PKGDESTWORK</filename> location defaults to 5640 The <filename>PKGDESTWORK</filename> location defaults to
5626 the following: 5641 the following:
5627 <literallayout class='monospaced'> 5642 <literallayout class='monospaced'>
@@ -6069,8 +6084,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
6069 <para> 6084 <para>
6070 When you use the <filename>RDEPENDS</filename> variable 6085 When you use the <filename>RDEPENDS</filename> variable
6071 in a recipe, you are essentially stating that the recipe's 6086 in a recipe, you are essentially stating that the recipe's
6072 <filename>do_build</filename> task depends on the existence 6087 <link linkend='ref-tasks-build'><filename>do_build</filename></link>
6073 of a specific package. 6088 task depends on the existence of a specific package.
6074 Consider this simple example for two recipes named "a" and 6089 Consider this simple example for two recipes named "a" and
6075 "b" that produce similarly named IPK packages. 6090 "b" that produce similarly named IPK packages.
6076 In this example, the <filename>RDEPENDS</filename> 6091 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"
6080 </literallayout> 6095 </literallayout>
6081 Here, the dependency is such that the 6096 Here, the dependency is such that the
6082 <filename>do_build</filename> task for recipe "a" depends 6097 <filename>do_build</filename> task for recipe "a" depends
6083 on the <filename>do_package_write_ipk</filename> task 6098 on the
6084 of recipe "b". 6099 <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
6100 task of recipe "b".
6085 This means the package file for "b" must be available when 6101 This means the package file for "b" must be available when
6086 the output for recipe "a" has been completely built. 6102 the output for recipe "a" has been completely built.
6087 More importantly, package "a" will be marked as depending 6103 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"
6126 <filename>RDEPENDS</filename> variable must appear 6142 <filename>RDEPENDS</filename> variable must appear
6127 as it would in the <filename>PACKAGES</filename> 6143 as it would in the <filename>PACKAGES</filename>
6128 namespace before any renaming of the output package by 6144 namespace before any renaming of the output package by
6129 classes like <filename>debian.bbclass</filename>. 6145 classes like
6146 <link linkend='ref-classes-debian'><filename>debian.bbclass</filename></link>.
6130 </para> 6147 </para>
6131 6148
6132 <para> 6149 <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 @@
442 works on a per-task basis rather than a per-recipe basis. 442 works on a per-task basis rather than a per-recipe basis.
443 You might wonder why using a per-task basis is preferred over a per-recipe basis. 443 You might wonder why using a per-task basis is preferred over a per-recipe basis.
444 To help explain, consider having the IPK packaging backend enabled and then switching to DEB. 444 To help explain, consider having the IPK packaging backend enabled and then switching to DEB.
445 In this case, <filename>do_install</filename> and <filename>do_package</filename> 445 In this case,
446 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
447 and
448 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
446 outputs are still valid. 449 outputs are still valid.
447 However, with a per-recipe approach, the build would not include the 450 However, with a per-recipe approach, the build would not include the
448 <filename>.deb</filename> files. 451 <filename>.deb</filename> files.
@@ -643,8 +646,10 @@
643 <para> 646 <para>
644 There are two types of output, one is just about creating a directory 647 There are two types of output, one is just about creating a directory
645 in <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>. 648 in <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
646 A good example is the output of either <filename>do_install</filename> or 649 A good example is the output of either
647 <filename>do_package</filename>. 650 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
651 or
652 <link linkend='ref-tasks-package'><filename>do_package</filename></link>.
648 The other type of output occurs when a set of data is merged into a shared directory 653 The other type of output occurs when a set of data is merged into a shared directory
649 tree such as the sysroot. 654 tree such as the sysroot.
650 </para> 655 </para>
@@ -653,8 +658,9 @@
653 The Yocto Project team has tried to keep the details of the 658 The Yocto Project team has tried to keep the details of the
654 implementation hidden in <filename>sstate</filename> class. 659 implementation hidden in <filename>sstate</filename> class.
655 From a user's perspective, adding shared state wrapping to a task 660 From a user's perspective, adding shared state wrapping to a task
656 is as simple as this <filename>do_deploy</filename> example taken 661 is as simple as this
657 from the 662 <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link>
663 example taken from the
658 <link linkend='ref-classes-deploy'><filename>deploy</filename></link> 664 <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
659 class: 665 class:
660 <literallayout class='monospaced'> 666 <literallayout class='monospaced'>
@@ -737,7 +743,9 @@
737 743
738 <para> 744 <para>
739 As a real world example, the aim is when building an IPK-based image, 745 As a real world example, the aim is when building an IPK-based image,
740 only the <filename>do_package_write_ipk</filename> tasks would have their 746 only the
747 <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
748 tasks would have their
741 shared state packages fetched and extracted. 749 shared state packages fetched and extracted.
742 Since the sysroot is not used, it would never get extracted. 750 Since the sysroot is not used, it would never get extracted.
743 This is another reason why a task-based approach is preferred over a 751 This is another reason why a task-based approach is preferred over a
@@ -834,8 +842,9 @@
834 The steps you can take are as simple as changing a function's 842 The steps you can take are as simple as changing a function's
835 comments in the source code. 843 comments in the source code.
836 For example, to invalidate package shared state files, change 844 For example, to invalidate package shared state files, change
837 the comment statements of <filename>do_package</filename> or 845 the comment statements of
838 the comments of one of the functions it calls. 846 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
847 or the comments of one of the functions it calls.
839 Even though the change is purely cosmetic, it causes the 848 Even though the change is purely cosmetic, it causes the
840 checksum to be recalculated and forces the OpenEmbedded build 849 checksum to be recalculated and forces the OpenEmbedded build
841 system to run the task again. 850 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 @@
280 <listitem><para><emphasis><filename>eglibc-initial</filename> fails to build</emphasis>: 280 <listitem><para><emphasis><filename>eglibc-initial</filename> fails to build</emphasis>:
281 If your development host system has the unpatched 281 If your development host system has the unpatched
282 <filename>GNU Make 3.82</filename>, 282 <filename>GNU Make 3.82</filename>,
283 the <filename>do_install</filename> task 283 the
284 fails for <filename>eglibc-initial</filename> during the 284 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
285 build.</para> 285 task fails for <filename>eglibc-initial</filename> during
286 the build.</para>
286 <para>Typically, every distribution that ships 287 <para>Typically, every distribution that ships
287 <filename>GNU Make 3.82</filename> as 288 <filename>GNU Make 3.82</filename> as
288 the default already has the patched version. 289 the default already has the patched version.
@@ -370,8 +371,11 @@
370 371
371 <para> 372 <para>
372 Following is an example written in Python. 373 Following is an example written in Python.
373 The code handles logging for a function that determines the number of tasks 374 The code handles logging for a function that determines the
374 needed to be run: 375 number of tasks needed to be run.
376 See the
377 "<link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>"
378 section for additional information:
375 <literallayout class='monospaced'> 379 <literallayout class='monospaced'>
376 python do_listtasks() { 380 python do_listtasks() {
377 bb.debug(2, "Starting to figure out the task list") 381 bb.debug(2, "Starting to figure out the task list")