summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-04-08 10:02:07 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-05-22 17:23:35 +0100
commit06af7c1b3240f23f036afab3baf664f37a0b6f36 (patch)
treef45c511e451a6bd42eaa17bf7c5f7723fb4e545a
parentd95a27b4d9eac34eaf125f7cdf261a215f7f11d1 (diff)
downloadpoky-06af7c1b3240f23f036afab3baf664f37a0b6f36.tar.gz
dev-manual: Review edits applied to selecting init manager section.
Applied comments based on Ross Burton's review of this new section. (From yocto-docs rev: d4f5f7b712ea2944efffec9b675341143675efb0) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml258
1 files changed, 133 insertions, 125 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 219ee68d40..e6696319ec 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -411,7 +411,7 @@
411 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ 411 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
412 fi 412 fi
413 } </literallayout> 413 } </literallayout>
414 In the main recipe, note the 414 In the main recipe, note the
415 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 415 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
416 variable, which tells the OpenEmbedded build system where to 416 variable, which tells the OpenEmbedded build system where to
417 find files during the build. 417 find files during the build.
@@ -431,27 +431,27 @@
431 </para> 431 </para>
432 432
433 <para> 433 <para>
434 By default, the build system uses the 434 By default, the build system uses the
435 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> 435 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
436 variable to locate files. 436 variable to locate files.
437 This append file extends the locations by setting the 437 This append file extends the locations by setting the
438 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> 438 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
439 variable. 439 variable.
440 Setting this variable in the <filename>.bbappend</filename> 440 Setting this variable in the <filename>.bbappend</filename>
441 file is the most reliable and recommended method for adding 441 file is the most reliable and recommended method for adding
442 directories to the search path used by the build system 442 directories to the search path used by the build system
443 to find files. 443 to find files.
444 </para> 444 </para>
445 445
446 <para> 446 <para>
447 The statement in this example extends the directories to include 447 The statement in this example extends the directories to include
448 <filename>${THISDIR}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>, 448 <filename>${THISDIR}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>,
449 which resolves to a directory named 449 which resolves to a directory named
450 <filename>formfactor</filename> in the same directory 450 <filename>formfactor</filename> in the same directory
451 in which the append file resides (i.e. 451 in which the append file resides (i.e.
452 <filename>meta-intel/meta-crownbay/recipes-bsp/formfactor/formfactor</filename>. 452 <filename>meta-intel/meta-crownbay/recipes-bsp/formfactor/formfactor</filename>.
453 This implies that you must have the supporting directory 453 This implies that you must have the supporting directory
454 structure set up that will contain any files or patches you 454 structure set up that will contain any files or patches you
455 will be including from the layer. 455 will be including from the layer.
456 </para> 456 </para>
457 457
@@ -660,7 +660,7 @@
660 script to accept the default value. 660 script to accept the default value.
661 Once the script completes, the new layer 661 Once the script completes, the new layer
662 is created in the current working directory. 662 is created in the current working directory.
663 The script names the layer by prepending 663 The script names the layer by prepending
664 <filename>meta-</filename> to the name you provide. 664 <filename>meta-</filename> to the name you provide.
665 </para> 665 </para>
666 666
@@ -1270,7 +1270,7 @@
1270 1270
1271 <para> 1271 <para>
1272 To add a post-installation script to a package, add a 1272 To add a post-installation script to a package, add a
1273 <filename>pkg_postinst_PACKAGENAME()</filename> function to the 1273 <filename>pkg_postinst_PACKAGENAME()</filename> function to the
1274 <filename>.bb</filename> file and use 1274 <filename>.bb</filename> file and use
1275 <filename>PACKAGENAME</filename> as the name of the package you want to attach to the 1275 <filename>PACKAGENAME</filename> as the name of the package you want to attach to the
1276 <filename>postinst</filename> script. 1276 <filename>postinst</filename> script.
@@ -1504,8 +1504,8 @@
1504 By default, the <filename>PACKAGES</filename> variable contains 1504 By default, the <filename>PACKAGES</filename> variable contains
1505 <filename>${PN}-staticdev</filename>, which includes all static library files. 1505 <filename>${PN}-staticdev</filename>, which includes all static library files.
1506 <note> 1506 <note>
1507 Some previously released versions of the Yocto Project 1507 Some previously released versions of the Yocto Project
1508 defined the static library files through 1508 defined the static library files through
1509 <filename>${PN}-dev</filename>. 1509 <filename>${PN}-dev</filename>.
1510 </note> 1510 </note>
1511 Following, is part of the BitBake configuration file. 1511 Following, is part of the BitBake configuration file.
@@ -1810,7 +1810,7 @@
1810 <para> 1810 <para>
1811 To use the <filename>menuconfig</filename> tool in the Yocto Project development 1811 To use the <filename>menuconfig</filename> tool in the Yocto Project development
1812 environment, you must build the tool using BitBake. 1812 environment, you must build the tool using BitBake.
1813 Thus, the environment must be set up using the 1813 Thus, the environment must be set up using the
1814 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> 1814 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1815 script found in the 1815 script found in the
1816 <link linkend='build-directory'>Build Directory</link>. 1816 <link linkend='build-directory'>Build Directory</link>.
@@ -2240,7 +2240,7 @@
2240 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> 2240 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
2241 and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 2241 and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2242 statements enable the OpenEmbedded build system to find the patch file. 2242 statements enable the OpenEmbedded build system to find the patch file.
2243 For more information on using append files, see the 2243 For more information on using append files, see the
2244 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" 2244 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
2245 section. 2245 section.
2246 </para></listitem> 2246 </para></listitem>
@@ -2262,7 +2262,7 @@
2262 <itemizedlist> 2262 <itemizedlist>
2263 <listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your 2263 <listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your
2264 selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> 2264 selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
2265 definition within the <filename>local.conf</filename> file in the 2265 definition within the <filename>local.conf</filename> file in the
2266 <link linkend='build-directory'>Build Directory</link> 2266 <link linkend='build-directory'>Build Directory</link>
2267 specifies the target architecture used when building the Linux kernel. 2267 specifies the target architecture used when building the Linux kernel.
2268 By default, <filename>MACHINE</filename> is set to 2268 By default, <filename>MACHINE</filename> is set to
@@ -2270,7 +2270,7 @@
2270 <trademark class='registered'>Intel</trademark> Architecture 2270 <trademark class='registered'>Intel</trademark> Architecture
2271 target machine suitable for the QEMU emulator.</para></listitem> 2271 target machine suitable for the QEMU emulator.</para></listitem>
2272 <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename> 2272 <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename>
2273 layer:</emphasis> The 2273 layer:</emphasis> The
2274 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> 2274 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
2275 variable in the 2275 variable in the
2276 <filename>bblayers.conf</filename> file found in the 2276 <filename>bblayers.conf</filename> file found in the
@@ -2306,7 +2306,7 @@
2306 <orderedlist> 2306 <orderedlist>
2307 <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>: 2307 <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
2308 Your environment should be set up since you previously sourced 2308 Your environment should be set up since you previously sourced
2309 the 2309 the
2310 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> 2310 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
2311 script. 2311 script.
2312 If it is not, source the script again from <filename>poky</filename>. 2312 If it is not, source the script again from <filename>poky</filename>.
@@ -2322,7 +2322,7 @@
2322 $ bitbake -c cleansstate linux-yocto 2322 $ bitbake -c cleansstate linux-yocto
2323 </literallayout></para> 2323 </literallayout></para>
2324 <para><note>Never remove any files by hand from the <filename>tmp/deploy</filename> 2324 <para><note>Never remove any files by hand from the <filename>tmp/deploy</filename>
2325 directory inside the 2325 directory inside the
2326 <link linkend='build-directory'>Build Directory</link>. 2326 <link linkend='build-directory'>Build Directory</link>.
2327 Always use the various BitBake clean tasks to clear out previous 2327 Always use the various BitBake clean tasks to clear out previous
2328 build artifacts. 2328 build artifacts.
@@ -2390,7 +2390,7 @@
2390 configurations in a <filename>local.conf</filename> 2390 configurations in a <filename>local.conf</filename>
2391 configuration file makes it easier to reproduce the same 2391 configuration file makes it easier to reproduce the same
2392 build configuration when using multiple build machines. 2392 build configuration when using multiple build machines.
2393 See the 2393 See the
2394 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>" 2394 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
2395 section for information on how to quickly set up a layer. 2395 section for information on how to quickly set up a layer.
2396 </para></listitem> 2396 </para></listitem>
@@ -2416,7 +2416,7 @@
2416 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink> [required] 2416 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink> [required]
2417 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></ulink> [required] 2417 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></ulink> [required]
2418 </literallayout> 2418 </literallayout>
2419 These following variables are optional and you typically 2419 These following variables are optional and you typically
2420 set them from the distribution configuration file: 2420 set them from the distribution configuration file:
2421 <literallayout class='monospaced'> 2421 <literallayout class='monospaced'>
2422 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink> [optional] 2422 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink> [optional]
@@ -2427,7 +2427,7 @@
2427 <tip> 2427 <tip>
2428 If you want to base your distribution configuration file 2428 If you want to base your distribution configuration file
2429 on the very basic configuration from OE-Core, you 2429 on the very basic configuration from OE-Core, you
2430 can use 2430 can use
2431 <filename>conf/distro/defaultsetup.conf</filename> as 2431 <filename>conf/distro/defaultsetup.conf</filename> as
2432 a reference and just include variables that differ 2432 a reference and just include variables that differ
2433 as compared to <filename>defaultsetup.conf</filename>. 2433 as compared to <filename>defaultsetup.conf</filename>.
@@ -2573,7 +2573,7 @@
2573 <filename>poky-tiny</filename>. 2573 <filename>poky-tiny</filename>.
2574 <note> 2574 <note>
2575 To use <filename>poky-tiny</filename> in your build, 2575 To use <filename>poky-tiny</filename> in your build,
2576 set the 2576 set the
2577 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> 2577 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
2578 variable in your 2578 variable in your
2579 <filename>local.conf</filename> file to "poky-tiny" 2579 <filename>local.conf</filename> file to "poky-tiny"
@@ -3069,7 +3069,7 @@
3069 3069
3070 <para> 3070 <para>
3071 The alternative to setting up a PR Service is to manually 3071 The alternative to setting up a PR Service is to manually
3072 bump the 3072 bump the
3073 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> 3073 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
3074 variable. 3074 variable.
3075 </para> 3075 </para>
@@ -3102,8 +3102,8 @@
3102 <para> 3102 <para>
3103 When upgrading the version of a package, assuming the 3103 When upgrading the version of a package, assuming the
3104 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename> 3104 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
3105 changes, the <filename>PR</filename> variable should be 3105 changes, the <filename>PR</filename> variable should be
3106 reset to "r0" (or "$(INC_PR).0" if you are using 3106 reset to "r0" (or "$(INC_PR).0" if you are using
3107 <filename>INC_PR</filename>). 3107 <filename>INC_PR</filename>).
3108 </para> 3108 </para>
3109 3109
@@ -3163,7 +3163,7 @@
3163 $ bitbake world -f -c distro_check 3163 $ bitbake world -f -c distro_check
3164 </literallayout> 3164 </literallayout>
3165 The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename> 3165 The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename>
3166 file found in the 3166 file found in the
3167 <link linkend='source-directory'>Source Directory</link>. 3167 <link linkend='source-directory'>Source Directory</link>.
3168 </para> 3168 </para>
3169 </section> 3169 </section>
@@ -3203,7 +3203,7 @@
3203 The <filename>do_split_packages</filename> function 3203 The <filename>do_split_packages</filename> function
3204 searches for a pattern of files or directories under a 3204 searches for a pattern of files or directories under a
3205 specified path and creates a package for each one it finds 3205 specified path and creates a package for each one it finds
3206 by appending to the 3206 by appending to the
3207 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink> 3207 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
3208 variable and setting the appropriate values for 3208 variable and setting the appropriate values for
3209 <filename>FILES_packagename</filename>, 3209 <filename>FILES_packagename</filename>,
@@ -3241,7 +3241,7 @@
3241 Thus, if a file in <filename>${libdir}</filename> 3241 Thus, if a file in <filename>${libdir}</filename>
3242 called <filename>mod_alias.so</filename> is found, 3242 called <filename>mod_alias.so</filename> is found,
3243 a package called <filename>lighttpd-module-alias</filename> 3243 a package called <filename>lighttpd-module-alias</filename>
3244 is created for it and the 3244 is created for it and the
3245 <ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink> 3245 <ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
3246 is set to "Lighttpd module for alias".</para></listitem> 3246 is set to "Lighttpd module for alias".</para></listitem>
3247 </itemizedlist> 3247 </itemizedlist>
@@ -3265,7 +3265,7 @@
3265 <filename>do_split_packages</filename>, see the 3265 <filename>do_split_packages</filename>, see the
3266 <filename>connman.inc</filename> file in the 3266 <filename>connman.inc</filename> file in the
3267 <filename>meta/recipes-connectivity/connman/</filename> 3267 <filename>meta/recipes-connectivity/connman/</filename>
3268 directory of the <filename>poky</filename> 3268 directory of the <filename>poky</filename>
3269 <link linkend='yocto-project-repositories'>source repository</link>. 3269 <link linkend='yocto-project-repositories'>source repository</link>.
3270 You can also find examples in 3270 You can also find examples in
3271 <filename>meta/classes/kernel.bbclass</filename>. 3271 <filename>meta/classes/kernel.bbclass</filename>.
@@ -3535,33 +3535,33 @@
3535 <title>Testing Packages With ptest</title> 3535 <title>Testing Packages With ptest</title>
3536 3536
3537 <para> 3537 <para>
3538 A Package Test (ptest) runs tests against packages built 3538 A Package Test (ptest) runs tests against packages built
3539 by the OpenEmbedded build system on the target machine. 3539 by the OpenEmbedded build system on the target machine.
3540 A ptest contains at least two items: the actual test, and 3540 A ptest contains at least two items: the actual test, and
3541 a shell script (<filename>run-ptest</filename>) that starts 3541 a shell script (<filename>run-ptest</filename>) that starts
3542 the test. 3542 the test.
3543 The shell script that starts the test must not contain 3543 The shell script that starts the test must not contain
3544 the actual test, the script only starts it. 3544 the actual test, the script only starts it.
3545 On the other hand, the test can be anything from a simple 3545 On the other hand, the test can be anything from a simple
3546 shell script that runs a binary and checks the output to 3546 shell script that runs a binary and checks the output to
3547 an elaborate system of test binaries and data files. 3547 an elaborate system of test binaries and data files.
3548 </para> 3548 </para>
3549 3549
3550 <para> 3550 <para>
3551 The test generates output in the format used by 3551 The test generates output in the format used by
3552 Automake: 3552 Automake:
3553 <literallayout class='monospaced'> 3553 <literallayout class='monospaced'>
3554 &lt;result&gt;: &lt;testname&gt; 3554 &lt;result&gt;: &lt;testname&gt;
3555 </literallayout> 3555 </literallayout>
3556 where the result can be <filename>PASS</filename>, 3556 where the result can be <filename>PASS</filename>,
3557 <filename>FAIL</filename>, or <filename>SKIP</filename>, 3557 <filename>FAIL</filename>, or <filename>SKIP</filename>,
3558 and the testname can be any identifying string. 3558 and the testname can be any identifying string.
3559 </para> 3559 </para>
3560 3560
3561 <note> 3561 <note>
3562 With this release of the Yocto Project, three recipes exist 3562 With this release of the Yocto Project, three recipes exist
3563 that are "ptest-enabled": <filename>bash</filename>, 3563 that are "ptest-enabled": <filename>bash</filename>,
3564 <filename>glib-2.0</filename>, and 3564 <filename>glib-2.0</filename>, and
3565 <filename>dbus</filename>. 3565 <filename>dbus</filename>.
3566 These three recipes are Autotool-enabled. 3566 These three recipes are Autotool-enabled.
3567 </note> 3567 </note>
@@ -3570,20 +3570,20 @@
3570 <title>Adding ptest to Your Build</title> 3570 <title>Adding ptest to Your Build</title>
3571 3571
3572 <para> 3572 <para>
3573 To add package testing to your build, add the 3573 To add package testing to your build, add the
3574 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink> 3574 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
3575 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink> 3575 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
3576 variables to your <filename>local.conf</filename> file, 3576 variables to your <filename>local.conf</filename> file,
3577 which is found in the 3577 which is found in the
3578 <link linkend='build-directory'>Build Directory</link>: 3578 <link linkend='build-directory'>Build Directory</link>:
3579 <literallayout class='monospaced'> 3579 <literallayout class='monospaced'>
3580 EXTRA_IMAGE_FEATURES += "ptest" 3580 EXTRA_IMAGE_FEATURES += "ptest"
3581 DISTRO_FEATURES_append = " ptest-pkgs" 3581 DISTRO_FEATURES_append = " ptest-pkgs"
3582 </literallayout> 3582 </literallayout>
3583 Once your build is complete, the ptest files are installed 3583 Once your build is complete, the ptest files are installed
3584 into the <filename>/usr/lib/&lt;package&gt;/ptest</filename> 3584 into the <filename>/usr/lib/&lt;package&gt;/ptest</filename>
3585 directory within the image, where 3585 directory within the image, where
3586 <filename>&lt;package&gt;</filename> is the name of the 3586 <filename>&lt;package&gt;</filename> is the name of the
3587 package. 3587 package.
3588 </para> 3588 </para>
3589 </section> 3589 </section>
@@ -3592,21 +3592,21 @@
3592 <title>Running ptest</title> 3592 <title>Running ptest</title>
3593 3593
3594 <para> 3594 <para>
3595 The <filename>ptest-runner</filename> package installs a 3595 The <filename>ptest-runner</filename> package installs a
3596 shell script that loops through all installed ptest test 3596 shell script that loops through all installed ptest test
3597 suites and runs them in sequence. 3597 suites and runs them in sequence.
3598 Consequently, you might want to add this package to 3598 Consequently, you might want to add this package to
3599 your image. 3599 your image.
3600 </para> 3600 </para>
3601 </section> 3601 </section>
3602 3602
3603 <section id='getting-your-package-ready'> 3603 <section id='getting-your-package-ready'>
3604 <title>Getting Your Package Ready</title> 3604 <title>Getting Your Package Ready</title>
3605 3605
3606 <para> 3606 <para>
3607 In order to enable a recipe to run installed ptests 3607 In order to enable a recipe to run installed ptests
3608 on target hardware, 3608 on target hardware,
3609 you need to prepare the recipes that build the packages 3609 you need to prepare the recipes that build the packages
3610 you want to test. 3610 you want to test.
3611 Here is what you have to do for each recipe: 3611 Here is what you have to do for each recipe:
3612 <itemizedlist> 3612 <itemizedlist>
@@ -3619,10 +3619,10 @@
3619 </para></listitem> 3619 </para></listitem>
3620 <listitem><para><emphasis>Create <filename>run-ptest</filename>:</emphasis> 3620 <listitem><para><emphasis>Create <filename>run-ptest</filename>:</emphasis>
3621 This script starts your test. 3621 This script starts your test.
3622 Locate the script where you will refer to it 3622 Locate the script where you will refer to it
3623 using 3623 using
3624 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>. 3624 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
3625 Here is an example that starts a test for 3625 Here is an example that starts a test for
3626 <filename>dbus</filename>: 3626 <filename>dbus</filename>:
3627 <literallayout class='monospaced'> 3627 <literallayout class='monospaced'>
3628 #!/bin/sh 3628 #!/bin/sh
@@ -3632,45 +3632,45 @@
3632 </para></listitem> 3632 </para></listitem>
3633 <listitem><para><emphasis>Ensure dependencies are 3633 <listitem><para><emphasis>Ensure dependencies are
3634 met:</emphasis> 3634 met:</emphasis>
3635 If the test adds build or runtime dependencies 3635 If the test adds build or runtime dependencies
3636 that normally do not exist for the package 3636 that normally do not exist for the package
3637 (such as requiring "make" to run the test suite), 3637 (such as requiring "make" to run the test suite),
3638 use the 3638 use the
3639 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> 3639 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
3640 and 3640 and
3641 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> 3641 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
3642 variables in your recipe in order for the package 3642 variables in your recipe in order for the package
3643 to meet the dependencies. 3643 to meet the dependencies.
3644 Here is an example where the package has a runtime 3644 Here is an example where the package has a runtime
3645 dependency on "make": 3645 dependency on "make":
3646 <literallayout class='monospaced'> 3646 <literallayout class='monospaced'>
3647 RDEPENDS_${PN}-ptest += "make" 3647 RDEPENDS_${PN}-ptest += "make"
3648 </literallayout> 3648 </literallayout>
3649 </para></listitem> 3649 </para></listitem>
3650 <listitem><para><emphasis>Add a function to build the 3650 <listitem><para><emphasis>Add a function to build the
3651 test suite:</emphasis> 3651 test suite:</emphasis>
3652 Not many packages support cross-compilation of 3652 Not many packages support cross-compilation of
3653 their test suites. 3653 their test suites.
3654 Consequently, you usually need to add a 3654 Consequently, you usually need to add a
3655 cross-compilation function to the package. 3655 cross-compilation function to the package.
3656 </para> 3656 </para>
3657 <para>Many packages based on Automake compile and 3657 <para>Many packages based on Automake compile and
3658 run the test suite by using a single command 3658 run the test suite by using a single command
3659 such as <filename>make check</filename>. 3659 such as <filename>make check</filename>.
3660 However, the native <filename>make check</filename> 3660 However, the native <filename>make check</filename>
3661 builds and runs on the same computer, while 3661 builds and runs on the same computer, while
3662 cross-compiling requires that the package is built 3662 cross-compiling requires that the package is built
3663 on the host but executed on the target. 3663 on the host but executed on the target.
3664 The built version of Automake that ships with the 3664 The built version of Automake that ships with the
3665 Yocto Project includes a patch that separates 3665 Yocto Project includes a patch that separates
3666 building and execution. 3666 building and execution.
3667 Consequently, packages that use the unaltered, 3667 Consequently, packages that use the unaltered,
3668 patched version of <filename>make check</filename> 3668 patched version of <filename>make check</filename>
3669 automatically cross-compiles.</para> 3669 automatically cross-compiles.</para>
3670 <para>However, you still must add a 3670 <para>However, you still must add a
3671 <filename>do_compile_ptest</filename> function to 3671 <filename>do_compile_ptest</filename> function to
3672 build the test suite. 3672 build the test suite.
3673 Add a function similar to the following to your 3673 Add a function similar to the following to your
3674 recipe: 3674 recipe:
3675 <literallayout class='monospaced'> 3675 <literallayout class='monospaced'>
3676 do_compile_ptest() { 3676 do_compile_ptest() {
@@ -3680,26 +3680,26 @@
3680 </para></listitem> 3680 </para></listitem>
3681 <listitem><para><emphasis>Ensure special configurations 3681 <listitem><para><emphasis>Ensure special configurations
3682 are set:</emphasis> 3682 are set:</emphasis>
3683 If the package requires special configurations 3683 If the package requires special configurations
3684 prior to compiling the test code, you must 3684 prior to compiling the test code, you must
3685 insert a <filename>do_configure_ptest</filename> 3685 insert a <filename>do_configure_ptest</filename>
3686 function into the recipe. 3686 function into the recipe.
3687 </para></listitem> 3687 </para></listitem>
3688 <listitem><para><emphasis>Install the test 3688 <listitem><para><emphasis>Install the test
3689 suite:</emphasis> 3689 suite:</emphasis>
3690 The <filename>ptest.bbclass</filename> class 3690 The <filename>ptest.bbclass</filename> class
3691 automatically copies the file 3691 automatically copies the file
3692 <filename>run-ptest</filename> to the target and 3692 <filename>run-ptest</filename> to the target and
3693 then runs make <filename>install-ptest</filename> 3693 then runs make <filename>install-ptest</filename>
3694 to run the tests. 3694 to run the tests.
3695 If this is not enough, you need to create a 3695 If this is not enough, you need to create a
3696 <filename>do_install_ptest</filename> function and 3696 <filename>do_install_ptest</filename> function and
3697 make sure it gets called after the 3697 make sure it gets called after the
3698 "make install-ptest" completes. 3698 "make install-ptest" completes.
3699 </para></listitem> 3699 </para></listitem>
3700 </itemizedlist> 3700 </itemizedlist>
3701 </para> 3701 </para>
3702 </section> 3702 </section>
3703 </section> 3703 </section>
3704 </section> 3704 </section>
3705 3705
@@ -3771,20 +3771,22 @@
3771 </para> 3771 </para>
3772 3772
3773 <para> 3773 <para>
3774 If you want to use <filename>SysVinit</filename>, you do 3774 If you want to use <filename>sysvinit</filename>, you do
3775 not have to do anything. 3775 not have to do anything.
3776 But, if you want to use <filename>systemd</filename>, you must 3776 But, if you want to use <filename>systemd</filename>, you must
3777 take some steps as described in the following sections. 3777 take some steps as described in the following sections.
3778 </para> 3778 </para>
3779 3779
3780<!--
3780 <note> 3781 <note>
3781 It is recommended that you create your own distribution configuration 3782 It is recommended that you create your own distribution configuration
3782 file to hold these settings instead of using your 3783 file to hold these settings instead of using your
3783 <filename>local.conf</filename> file. 3784 <filename>local.conf</filename> file.
3784 For information on creating your own distribution, see the 3785 For information on creating your own distribution, see the
3785 "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>" 3786 "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
3786 section. 3787 section.
3787 </note> 3788 </note>
3789-->
3788 3790
3789 <section id='using-systemd-exclusively'> 3791 <section id='using-systemd-exclusively'>
3790 <title>Using systemd Exclusively</title> 3792 <title>Using systemd Exclusively</title>
@@ -3797,7 +3799,7 @@
3797 VIRTUAL-RUNTIME_init_manager = "systemd" 3799 VIRTUAL-RUNTIME_init_manager = "systemd"
3798 </literallayout> 3800 </literallayout>
3799 You can also prevent the <filename>sysvinit</filename> 3801 You can also prevent the <filename>sysvinit</filename>
3800 distribution feature from 3802 distribution feature from
3801 being automatically enabled as follows: 3803 being automatically enabled as follows:
3802 <literallayout class='monospaced'> 3804 <literallayout class='monospaced'>
3803 DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit" 3805 DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
@@ -3805,6 +3807,12 @@
3805 Doing so removes any redundant <filename>sysvinit</filename> 3807 Doing so removes any redundant <filename>sysvinit</filename>
3806 scripts. 3808 scripts.
3807 </para> 3809 </para>
3810
3811 <para>
3812 For information on the backfill variable, see
3813 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></ulink>
3814 in the Yocto Project Reference Manual.
3815 </para>
3808 </section> 3816 </section>
3809 3817
3810 <section id='using-systemd-for-the-main-image-and-using-sysvinit-for-the-rescue-image'> 3818 <section id='using-systemd-for-the-main-image-and-using-sysvinit-for-the-rescue-image'>
@@ -3838,7 +3846,7 @@
3838 However, on rare occasions where you might want to use a 3846 However, on rare occasions where you might want to use a
3839 layer but exclude parts that are causing problems, such 3847 layer but exclude parts that are causing problems, such
3840 as introducing a different version of a recipe, you can 3848 as introducing a different version of a recipe, you can
3841 use 3849 use
3842 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBMASK'><filename>BBMASK</filename></ulink> 3850 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBMASK'><filename>BBMASK</filename></ulink>
3843 to exclude the recipe. 3851 to exclude the recipe.
3844 </para> 3852 </para>
@@ -3978,7 +3986,7 @@
3978 creation: 3986 creation:
3979 <itemizedlist> 3987 <itemizedlist>
3980 <listitem><para><emphasis>Not using $D in front of absolute paths:</emphasis> 3988 <listitem><para><emphasis>Not using $D in front of absolute paths:</emphasis>
3981 The build system defines 3989 The build system defines
3982 <filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink> 3990 <filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
3983 at root filesystem creation time, and 3991 at root filesystem creation time, and
3984 it is blank when run on the target device. 3992 it is blank when run on the target device.
@@ -4034,9 +4042,9 @@
4034 </para> 4042 </para>
4035 4043
4036 <tip> 4044 <tip>
4037 For best results, install <filename>-dbg</filename> packages for 4045 For best results, install <filename>-dbg</filename> packages for
4038 the applications you are going to debug. 4046 the applications you are going to debug.
4039 Doing so makes extra debug symbols available that give you more 4047 Doing so makes extra debug symbols available that give you more
4040 meaningful output. 4048 meaningful output.
4041 </tip> 4049 </tip>
4042 4050
@@ -4097,11 +4105,11 @@
4097 <para> 4105 <para>
4098 Before you can initiate a remote debugging session, you need 4106 Before you can initiate a remote debugging session, you need
4099 to be sure you have set up the cross-development environment, 4107 to be sure you have set up the cross-development environment,
4100 toolchain, and sysroot. 4108 toolchain, and sysroot.
4101 The "<ulink url='&YOCTO_DOCS_ADT_URL;#adt-prepare'>Preparing for Application Development</ulink>" 4109 The "<ulink url='&YOCTO_DOCS_ADT_URL;#adt-prepare'>Preparing for Application Development</ulink>"
4102 chapter of the Yocto Project Application Developer's Guide 4110 chapter of the Yocto Project Application Developer's Guide
4103 describes this process. 4111 describes this process.
4104 Be sure you have read that chapter and have set up 4112 Be sure you have read that chapter and have set up
4105 your environment. 4113 your environment.
4106 </para> 4114 </para>
4107 </section> 4115 </section>
@@ -4111,22 +4119,22 @@
4111 4119
4112 <para> 4120 <para>
4113 Make sure Gdbserver is installed on the target. 4121 Make sure Gdbserver is installed on the target.
4114 If it is not, install the package 4122 If it is not, install the package
4115 <filename>gdbserver</filename>, which needs the 4123 <filename>gdbserver</filename>, which needs the
4116 <filename>libthread-db1</filename> package. 4124 <filename>libthread-db1</filename> package.
4117 </para> 4125 </para>
4118 4126
4119 <para> 4127 <para>
4120 Here is an example that when entered from the host 4128 Here is an example that when entered from the host
4121 connects to the target and launches Gdbserver in order to 4129 connects to the target and launches Gdbserver in order to
4122 "debug" a binary named <filename>helloworld</filename>: 4130 "debug" a binary named <filename>helloworld</filename>:
4123 <literallayout class='monospaced'> 4131 <literallayout class='monospaced'>
4124 $ gdbserver localhost:2345 /usr/bin/helloworld 4132 $ gdbserver localhost:2345 /usr/bin/helloworld
4125 </literallayout> 4133 </literallayout>
4126 Gdbserver should now be listening on port 2345 for debugging 4134 Gdbserver should now be listening on port 2345 for debugging
4127 commands coming from a remote GDB process that is running on 4135 commands coming from a remote GDB process that is running on
4128 the host computer. 4136 the host computer.
4129 Communication between Gdbserver and the host GDB are done 4137 Communication between Gdbserver and the host GDB are done
4130 using TCP. 4138 using TCP.
4131 To use other communication protocols, please refer to the 4139 To use other communication protocols, please refer to the
4132 <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>. 4140 <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
@@ -4144,23 +4152,23 @@
4144 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross"> 4152 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
4145 <title>Build the Cross-GDB Package</title> 4153 <title>Build the Cross-GDB Package</title>
4146 <para> 4154 <para>
4147 A suitable GDB cross-binary is required that runs on your 4155 A suitable GDB cross-binary is required that runs on your
4148 host computer but also knows about the the ABI of the 4156 host computer but also knows about the the ABI of the
4149 remote target. 4157 remote target.
4150 You can get this binary from the 4158 You can get this binary from the
4151 <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>. 4159 <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>.
4152 Here is an example where the toolchain has been installed 4160 Here is an example where the toolchain has been installed
4153 in the default directory 4161 in the default directory
4154 <filename>/opt/poky/&DISTRO;</filename>: 4162 <filename>/opt/poky/&DISTRO;</filename>:
4155 <literallayout class='monospaced'> 4163 <literallayout class='monospaced'>
4156 /opt/poky/1.4/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb 4164 /opt/poky/1.4/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb
4157 </literallayout> 4165 </literallayout>
4158 where <filename>arm</filename> is the target architecture 4166 where <filename>arm</filename> is the target architecture
4159 and <filename>linux-gnueabi</filename> is the target ABI. 4167 and <filename>linux-gnueabi</filename> is the target ABI.
4160 </para> 4168 </para>
4161 4169
4162 <para> 4170 <para>
4163 Alternatively, you can use BitBake to build the 4171 Alternatively, you can use BitBake to build the
4164 <filename>gdb-cross</filename> binary. 4172 <filename>gdb-cross</filename> binary.
4165 Here is an example: 4173 Here is an example:
4166 <literallayout class='monospaced'> 4174 <literallayout class='monospaced'>
@@ -4190,10 +4198,10 @@
4190 </para> 4198 </para>
4191 4199
4192 <para> 4200 <para>
4193 You need to add a statement in the 4201 You need to add a statement in the
4194 <filename>.gdbinit</filename> file that points to your 4202 <filename>.gdbinit</filename> file that points to your
4195 root filesystem. 4203 root filesystem.
4196 Here is an example that points to the root filesystem for 4204 Here is an example that points to the root filesystem for
4197 an ARM-based target device: 4205 an ARM-based target device:
4198 <literallayout class='monospaced'> 4206 <literallayout class='monospaced'>
4199 set sysroot /home/jzhang/sysroot_arm 4207 set sysroot /home/jzhang/sysroot_arm
@@ -4205,14 +4213,14 @@
4205 <title>Launch the Host GDB</title> 4213 <title>Launch the Host GDB</title>
4206 4214
4207 <para> 4215 <para>
4208 Before launching the host GDB, you need to be sure 4216 Before launching the host GDB, you need to be sure
4209 you have sourced the cross-debugging environment script, 4217 you have sourced the cross-debugging environment script,
4210 which if you installed the root filesystem in the default 4218 which if you installed the root filesystem in the default
4211 location is at <filename>/opt/poky/&DISTRO;</filename> 4219 location is at <filename>/opt/poky/&DISTRO;</filename>
4212 and begins with the string "environment-setup". 4220 and begins with the string "environment-setup".
4213 For more information, see the 4221 For more information, see the
4214 "<ulink url='&YOCTO_DOCS_ADT_URL;#setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</ulink>" 4222 "<ulink url='&YOCTO_DOCS_ADT_URL;#setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</ulink>"
4215 section in the Yocto Project Application Developer's 4223 section in the Yocto Project Application Developer's
4216 Guide. 4224 Guide.
4217 </para> 4225 </para>
4218 4226
@@ -4222,7 +4230,7 @@
4222 Provide the binary file you are going to debug. 4230 Provide the binary file you are going to debug.
4223 For example, the following command continues with the 4231 For example, the following command continues with the
4224 example used in the previous section by loading 4232 example used in the previous section by loading
4225 the <filename>helloworld</filename> binary as well as the 4233 the <filename>helloworld</filename> binary as well as the
4226 debugging information: 4234 debugging information:
4227 <literallayout class='monospaced'> 4235 <literallayout class='monospaced'>
4228 $ arm-poky-linux-gnuabi-gdb helloworld 4236 $ arm-poky-linux-gnuabi-gdb helloworld
@@ -4238,7 +4246,7 @@
4238 4246
4239 <para> 4247 <para>
4240 From the target, you need to connect to the remote GDB 4248 From the target, you need to connect to the remote GDB
4241 server that is running on the host. 4249 server that is running on the host.
4242 You need to specify the remote host and port. 4250 You need to specify the remote host and port.
4243 Here is the command continuing with the example: 4251 Here is the command continuing with the example:
4244 <literallayout class='monospaced'> 4252 <literallayout class='monospaced'>
@@ -4315,7 +4323,7 @@
4315 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename> 4323 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename>
4316 variable to "1" in the <filename>local.conf</filename> configuration file. 4324 variable to "1" in the <filename>local.conf</filename> configuration file.
4317 If you use the <filename>DEBUG_BUILD</filename> variable, 4325 If you use the <filename>DEBUG_BUILD</filename> variable,
4318 you also add extra debugging information that can make the debug 4326 you also add extra debugging information that can make the debug
4319 packages large. 4327 packages large.
4320 </para> 4328 </para>
4321 4329
@@ -4390,8 +4398,8 @@
4390 <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>. 4398 <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>.
4391 If the "tools-profile" image feature is selected, all necessary binaries 4399 If the "tools-profile" image feature is selected, all necessary binaries
4392 are installed onto the target device for OProfileUI interaction. 4400 are installed onto the target device for OProfileUI interaction.
4393 For a list of image features that ship with the Yocto Project, 4401 For a list of image features that ship with the Yocto Project,
4394 see the 4402 see the
4395 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Images</ulink>" 4403 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Images</ulink>"
4396 section in the Yocto Project Reference Manual. 4404 section in the Yocto Project Reference Manual.
4397 </para> 4405 </para>
@@ -4460,7 +4468,7 @@
4460 </para> 4468 </para>
4461 4469
4462 <para> 4470 <para>
4463 Downloaded archives reside in the 4471 Downloaded archives reside in the
4464 <link linkend='build-directory'>Build Directory</link> in 4472 <link linkend='build-directory'>Build Directory</link> in
4465 <filename>/tmp</filename> and are cleared up when they are no longer in use. 4473 <filename>/tmp</filename> and are cleared up when they are no longer in use.
4466 </para> 4474 </para>
@@ -4604,7 +4612,7 @@
4604 release of proprietary software. 4612 release of proprietary software.
4605 The Yocto Project provides an archiver class to help avoid 4613 The Yocto Project provides an archiver class to help avoid
4606 some of these concerns. 4614 some of these concerns.
4607 See the 4615 See the
4608 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'>Archiving Sources - <filename>archive*.bbclass</filename></ulink>" 4616 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'>Archiving Sources - <filename>archive*.bbclass</filename></ulink>"
4609 section in the Yocto Project Reference Manual for information 4617 section in the Yocto Project Reference Manual for information
4610 on this class. 4618 on this class.
@@ -4752,7 +4760,7 @@
4752 ##COREBASE##/meta-yocto \ 4760 ##COREBASE##/meta-yocto \
4753 " 4761 "
4754 </literallayout> 4762 </literallayout>
4755 Creating and providing an archive of the 4763 Creating and providing an archive of the
4756 <link linkend='metadata'>Metadata</link> layers 4764 <link linkend='metadata'>Metadata</link> layers
4757 (recipes, configuration files, and so forth) 4765 (recipes, configuration files, and so forth)
4758 enables you to meet your 4766 enables you to meet your