summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml160
1 files changed, 84 insertions, 76 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 8754c0516f..20e79c05db 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -3515,9 +3515,9 @@
3515 <para> 3515 <para>
3516 A Package Test (ptest) runs tests against packages built 3516 A Package Test (ptest) runs tests against packages built
3517 by the OpenEmbedded build system on the target machine. 3517 by the OpenEmbedded build system on the target machine.
3518 Minimally, a ptest contains two things: a shell script that 3518 A ptest contains at least two items: the actual test, and
3519 starts the test (<filename>run-ptest</filename>), 3519 a shell script (<filename>run-ptest</filename>) that starts
3520 and the actual test. 3520 the test.
3521 The shell script that starts the test must not contain 3521 The shell script that starts the test must not contain
3522 the actual test, the script only starts it. 3522 the actual test, the script only starts it.
3523 On the other hand, the test can be anything from a simple 3523 On the other hand, the test can be anything from a simple
@@ -3526,38 +3526,78 @@
3526 </para> 3526 </para>
3527 3527
3528 <para> 3528 <para>
3529 The test formats the output into the single, common 3529 The test generates output in the format used by
3530 format used by Automake: 3530 Automake:
3531 <literallayout class='monospaced'> 3531 <literallayout class='monospaced'>
3532 &lt;result&gt;: &lt;testname&gt; 3532 &lt;result&gt;: &lt;testname&gt;
3533 </literallayout> 3533 </literallayout>
3534 The <filename>&lt;result&gt;</filename> can be 3534 where the result can be <filename>PASS</filename>,
3535 <filename>PASS</filename>, <filename>FAIL</filename>, or 3535 <filename>FAIL</filename>, or <filename>SKIP</filename>,
3536 <filename>SKIP</filename>. 3536 and the testname can be any identifying string.
3537 The <filename>&lt;testname&gt;</filename> can be any
3538 identifying string.
3539 </para> 3537 </para>
3540 3538
3539 <note>
3540 With this release of the Yocto Project, three recipes exist
3541 that are "ptest-enabled": <filename>bash</filename>,
3542 <filename>glib-2.0</filename>, and
3543 <filename>dbus</filename>.
3544 These three recipes are Autotool-enabled.
3545 </note>
3546
3547 <section id='adding-ptest-to-your-build'>
3548 <title>Adding ptest to Your Build</title>
3549
3550 <para>
3551 To add package testing to your build, add the
3552 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
3553 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
3554 variables to your <filename>local.conf</filename> file,
3555 which is found in the
3556 <link linkend='build-directory'>Build Directory</link>:
3557 <literallayout class='monospaced'>
3558 EXTRA_IMAGE_FEATURES += "ptest"
3559 DISTRO_FEATURES_append = " ptest-pkgs"
3560 </literallayout>
3561 Once your build is complete, the ptest files are installed
3562 into the <filename>/usr/lib/&lt;package&gt;/ptest</filename>
3563 directory within the image, where
3564 <filename>&lt;package&gt;</filename> is the name of the
3565 package.
3566 </para>
3567 </section>
3568
3569 <section id='running-ptest'>
3570 <title>Running ptest</title>
3571
3572 <para>
3573 The <filename>ptest-runner</filename> package installs a
3574 shell script that loops through all installed ptest test
3575 suites and runs them in sequence.
3576 Consequently, you might want to add this package to
3577 your image.
3578 </para>
3579 </section>
3580
3541 <section id='getting-your-package-ready'> 3581 <section id='getting-your-package-ready'>
3542 <title>Getting Your Package Ready</title> 3582 <title>Getting Your Package Ready</title>
3543 3583
3544 <para> 3584 <para>
3545 In order to run installed ptests on target hardware, 3585 In order to enable a recipe to run installed ptests
3586 on target hardware,
3546 you need to prepare the recipes that build the packages 3587 you need to prepare the recipes that build the packages
3547 you want to test. 3588 you want to test.
3548 Here is what you have to do for each recipe: 3589 Here is what you have to do for each recipe:
3549 <itemizedlist> 3590 <itemizedlist>
3550 <listitem><para><emphasis>Be sure the recipe 3591 <listitem><para><emphasis>Be sure the recipe
3551 inherits ptest:</emphasis> 3592 inherits ptest:</emphasis>
3552 Include the following line in your recipes: 3593 Include the following line in each recipe:
3553 <literallayout class='monospaced'> 3594 <literallayout class='monospaced'>
3554 inherit ptest 3595 inherit ptest
3555 </literallayout> 3596 </literallayout>
3556 </para></listitem> 3597 </para></listitem>
3557 <listitem><para><emphasis>Create <filename>run-ptest</filename>:</emphasis> 3598 <listitem><para><emphasis>Create <filename>run-ptest</filename>:</emphasis>
3558 The <filename>run-ptest</filename> script needs to 3599 This script starts your test.
3559 start your tests. 3600 Locate the script where you will refer to it
3560 Locate this script where you would point to it
3561 using 3601 using
3562 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>. 3602 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
3563 Here is an example that starts a test for 3603 Here is an example that starts a test for
@@ -3571,13 +3611,15 @@
3571 <listitem><para><emphasis>Ensure dependencies are 3611 <listitem><para><emphasis>Ensure dependencies are
3572 met:</emphasis> 3612 met:</emphasis>
3573 If the test adds build or runtime dependencies 3613 If the test adds build or runtime dependencies
3574 to the package that do not normally exist 3614 that normally do not exist for the package
3575 (such as requiring "make" to run the test suite), 3615 (such as requiring "make" to run the test suite),
3576 use the 3616 use the
3617 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
3618 and
3577 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> 3619 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
3578 variable in your recipe so the package meets the 3620 variables in your recipe in order for the package
3579 dependency. 3621 to meet the dependencies.
3580 Here is an example where the package has a build 3622 Here is an example where the package has a runtime
3581 dependency on "make": 3623 dependency on "make":
3582 <literallayout class='monospaced'> 3624 <literallayout class='monospaced'>
3583 RDEPENDS_${PN}-ptest += "make" 3625 RDEPENDS_${PN}-ptest += "make"
@@ -3585,25 +3627,24 @@
3585 </para></listitem> 3627 </para></listitem>
3586 <listitem><para><emphasis>Add a function to build the 3628 <listitem><para><emphasis>Add a function to build the
3587 test suite:</emphasis> 3629 test suite:</emphasis>
3588 Few packages support cross-compiling their test 3630 Not many packages support cross-compilation of
3589 suites. 3631 their test suites.
3590 Consequently, you usually need to add that function. 3632 Consequently, you usually need to add a
3633 cross-compilation function to the package.
3591 </para> 3634 </para>
3592 <para>Many packages based on Automake compile and 3635 <para>Many packages based on Automake compile and
3593 run the test suite by using a single command 3636 run the test suite by using a single command
3594 such as <filename>make check</filename>. 3637 such as <filename>make check</filename>.
3595 However, this method does not work when you are 3638 However, the native <filename>make check</filename>
3596 cross-compiling packages because building occurs on 3639 builds and runs on the same computer, while
3597 the host and execution occurs on the target. 3640 cross-compiling requires that the package is built
3598 Thus, compilation needs to occur separately on 3641 on the host but executed on the target.
3599 the host. 3642 The built version of Automake that ships with the
3600 The built version of Automake that ships with 3643 Yocto Project includes a patch that separates
3601 the Yocto Project separates these actions 3644 building and execution.
3602 automatically through a patch. 3645 Consequently, packages that use the unaltered,
3603 Consequently, packages that use the unaltered 3646 patched version of <filename>make check</filename>
3604 patched version of 3647 automatically cross-compiles.</para>
3605 <filename>make check</filename> automatically
3606 cross-compile.</para>
3607 <para>However, you still must add a 3648 <para>However, you still must add a
3608 <filename>do_compile_ptest</filename> function to 3649 <filename>do_compile_ptest</filename> function to
3609 build the test suite. 3650 build the test suite.
@@ -3624,52 +3665,19 @@
3624 </para></listitem> 3665 </para></listitem>
3625 <listitem><para><emphasis>Install the test 3666 <listitem><para><emphasis>Install the test
3626 suite:</emphasis> 3667 suite:</emphasis>
3627 The <filename>ptest.bbclass</filename> class 3668 The <filename>ptest.bbclass</filename> class
3628 automatically copies the file 3669 automatically copies the file
3629 <filename>run-ptest</filename> to the target and 3670 <filename>run-ptest</filename> to the target and
3630 then runs <filename>make install-ptest</filename> 3671 then runs make <filename>install-ptest</filename>
3631 to run the tests. 3672 to run the tests.
3632 If this is not the case, you need to create a 3673 If this is not enough, you need to create a
3633 <filename>do_install_ptest</filename> that gets 3674 <filename>do_install_ptest</filename> function and
3634 called after the "make install-ptest" completes. 3675 make sure it gets called after the
3676 "make install-ptest" completes.
3635 </para></listitem> 3677 </para></listitem>
3636 </itemizedlist> 3678 </itemizedlist>
3637 </para> 3679 </para>
3638 </section> 3680 </section>
3639
3640 <section id='adding-ptest-to-your-build'>
3641 <title>Adding ptest to Your Build</title>
3642
3643 <para>
3644 To add package testing to your build, add the
3645 <ulink url='&YOCTO_DOCS_REF_URL;#DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
3646 and <ulink url='&YOCTO_DOCS_REF_URL;#EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
3647 variables to your <filename>local.conf</filename> file,
3648 which is found in the
3649 <link linkend='build-directory'>Build Directory</link>:
3650 <literallayout class='monospaced'>
3651 EXTRA_IMAGE_FEATURES += "ptest"
3652 DISTRO_FEATURES_append = " ptest-pkgs"
3653 </literallayout>
3654 Once your build is complete, the ptest files are installed
3655 into the <filename>/usr/lib/&lt;package&gt;/ptest</filename>
3656 directory within the image, where
3657 <filename>&lt;package&gt;</filename> is the name of the
3658 package.
3659 </para>
3660 </section>
3661
3662 <section id='running-ptest'>
3663 <title>Running ptest</title>
3664
3665 <para>
3666 The <filename>ptest-runner</filename> package installs a
3667 shell script that loops through all installed ptest test
3668 suites and runs them in sequence.
3669 Consequently, you might want to add this package to
3670 your image.
3671 </para>
3672 </section>
3673 </section> 3681 </section>
3674 </section> 3682 </section>
3675 3683