dev-manual: Edits to "Testing Packages with ptest" section.

Applied some changes from Bjorn's review.  Also included are
some better wordings according to one of their staff technical
writers.

(From yocto-docs rev: 42f2ba26528d4f356422332e8fe95ff4a24337f3)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

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 @@
             <para>
                 A Package Test (ptest) runs tests against packages built 
                 by the OpenEmbedded build system on the target machine.
-                Minimally, a ptest contains two things: a shell script that 
-                starts the test (<filename>run-ptest</filename>),
-                and the actual test.
+                A ptest contains at least two items: the actual test, and 
+                a shell script (<filename>run-ptest</filename>) that starts
+                the test.
                 The shell script that starts the test must not contain 
                 the actual test, the script only starts it.
                 On the other hand, the test can be anything from a simple
@@ -3526,38 +3526,78 @@
             </para>
 
             <para>
-                The test formats the output into the single, common
-                format used by Automake:
+                The test generates output in the format used by 
+                Automake:
                 <literallayout class='monospaced'>
      &lt;result&gt;: &lt;testname&gt;
                 </literallayout>
-                The <filename>&lt;result&gt;</filename> can be 
-                <filename>PASS</filename>, <filename>FAIL</filename>, or
-                <filename>SKIP</filename>.
-                The <filename>&lt;testname&gt;</filename> can be any
-                identifying string.
+                where the result can be <filename>PASS</filename>, 
+                <filename>FAIL</filename>, or <filename>SKIP</filename>,
+                and the testname can be any identifying string.
             </para>
 
+            <note>
+                With this release of the Yocto Project, three recipes exist
+                that are "ptest-enabled": <filename>bash</filename>, 
+                <filename>glib-2.0</filename>, and 
+                <filename>dbus</filename>.
+                These three recipes are Autotool-enabled.
+            </note>
+
+            <section id='adding-ptest-to-your-build'>
+                <title>Adding ptest to Your Build</title>
+
+                <para>
+                    To add package testing to your build, add the 
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
+                    and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
+                    variables to your <filename>local.conf</filename> file, 
+                    which is found in the 
+                    <link linkend='build-directory'>Build Directory</link>:
+                    <literallayout class='monospaced'>
+     EXTRA_IMAGE_FEATURES += "ptest" 
+     DISTRO_FEATURES_append = " ptest-pkgs"
+                    </literallayout>
+                    Once your build is complete, the ptest files are installed
+                    into the <filename>/usr/lib/&lt;package&gt;/ptest</filename>
+                    directory within the image, where 
+                    <filename>&lt;package&gt;</filename> is the name of the 
+                    package.
+                </para>
+            </section>
+
+            <section id='running-ptest'>
+                <title>Running ptest</title>
+
+                <para>
+                    The <filename>ptest-runner</filename> package installs a 
+                    shell script that loops through all installed ptest test 
+                    suites and runs them in sequence. 
+                    Consequently, you might want to add this package to
+                    your image. 
+                </para>
+            </section> 
+
             <section id='getting-your-package-ready'>
                 <title>Getting Your Package Ready</title>
  
                 <para>
-                    In order to run installed ptests on target hardware, 
+                    In order to enable a recipe to run installed ptests 
+                    on target hardware, 
                     you need to prepare the recipes that build the packages     
                     you want to test.
                     Here is what you have to do for each recipe:
                     <itemizedlist>
                         <listitem><para><emphasis>Be sure the recipe
                             inherits ptest:</emphasis>
-                            Include the following line in your recipes:
+                            Include the following line in each recipe:
                             <literallayout class='monospaced'>
      inherit ptest
                             </literallayout>
                             </para></listitem>
                         <listitem><para><emphasis>Create <filename>run-ptest</filename>:</emphasis>
-                            The <filename>run-ptest</filename> script needs to
-                            start your tests.
-                            Locate this script where you would point to it 
+                            This script starts your test.
+                            Locate the script where you will refer to it 
                             using 
                             <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
                             Here is an example that starts a test for 
@@ -3571,13 +3611,15 @@
                         <listitem><para><emphasis>Ensure dependencies are
                             met:</emphasis>
                             If the test adds build or runtime dependencies 
-                            to the package that do not normally exist
+                            that normally do not exist for the package 
                             (such as requiring "make" to run the test suite), 
                             use the 
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
+                            and 
                             <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
-                            variable in your recipe so the package meets the 
-                            dependency.
-                            Here is an example where the package has a build
+                            variables in your recipe in order for the package
+                            to meet the dependencies. 
+                            Here is an example where the package has a runtime 
                             dependency on "make":
                             <literallayout class='monospaced'>
      RDEPENDS_${PN}-ptest += "make"
@@ -3585,25 +3627,24 @@
                             </para></listitem>
                         <listitem><para><emphasis>Add a function to build the 
                             test suite:</emphasis>
-                            Few packages support cross-compiling their test 
-                            suites.
-                            Consequently, you usually need to add that function.
+                            Not many packages support cross-compilation of 
+                            their test suites. 
+                            Consequently, you usually need to add a 
+                            cross-compilation function to the package.
                             </para>
                             <para>Many packages based on Automake compile and 
                             run the test suite by using a single command
                             such as <filename>make check</filename>.
-                            However, this method does not work when you are 
-                            cross-compiling packages because building occurs on
-                            the host and execution occurs on the target.
-                            Thus, compilation needs to occur separately on 
-                            the host.
-                            The built version of Automake that ships with 
-                            the Yocto Project separates these actions 
-                            automatically through a patch.
-                            Consequently, packages that use the unaltered
-                            patched version of 
-                            <filename>make check</filename> automatically 
-                            cross-compile.</para>
+                            However, the native <filename>make check</filename>
+                            builds and runs on the same computer, while 
+                            cross-compiling requires that the package is built 
+                            on the host but executed on the target.
+                            The built version of Automake that ships with the 
+                            Yocto Project includes a patch that separates 
+                            building and execution.
+                            Consequently, packages that use the unaltered, 
+                            patched version of <filename>make check</filename>
+                            automatically cross-compiles.</para>
                             <para>However, you still must add a 
                             <filename>do_compile_ptest</filename> function to 
                             build the test suite.
@@ -3624,52 +3665,19 @@
                             </para></listitem>
                        <listitem><para><emphasis>Install the test 
                             suite:</emphasis>
-                            The <filename>ptest.bbclass</filename> class
-                            automatically copies the file
+                            The <filename>ptest.bbclass</filename> class 
+                            automatically copies the file 
                             <filename>run-ptest</filename> to the target and 
-                            then runs <filename>make install-ptest</filename>
-                            to run the tests.
-                            If this is not the case, you need to create a 
-                            <filename>do_install_ptest</filename> that gets
-                            called after the "make install-ptest" completes.
+                            then runs make <filename>install-ptest</filename>
+                            to run the tests. 
+                            If this is not enough, you need to create a 
+                            <filename>do_install_ptest</filename> function and 
+                            make sure it gets called after the 
+                            "make install-ptest" completes.
                             </para></listitem>
                     </itemizedlist>
                 </para>
-            </section>
-
-            <section id='adding-ptest-to-your-build'>
-                <title>Adding ptest to Your Build</title>
-
-                <para>
-                    To add package testing to your build, add the 
-                    <ulink url='&YOCTO_DOCS_REF_URL;#DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
-                    and <ulink url='&YOCTO_DOCS_REF_URL;#EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
-                    variables to your <filename>local.conf</filename> file, 
-                    which is found in the 
-                    <link linkend='build-directory'>Build Directory</link>:
-                    <literallayout class='monospaced'>
-     EXTRA_IMAGE_FEATURES += "ptest" 
-     DISTRO_FEATURES_append = " ptest-pkgs"
-                    </literallayout>
-                    Once your build is complete, the ptest files are installed
-                    into the <filename>/usr/lib/&lt;package&gt;/ptest</filename>
-                    directory within the image, where 
-                    <filename>&lt;package&gt;</filename> is the name of the 
-                    package.
-                </para>
-            </section>
-
-            <section id='running-ptest'>
-                <title>Running ptest</title>
-
-                <para>
-                    The <filename>ptest-runner</filename> package installs a 
-                    shell script that loops through all installed ptest test 
-                    suites and runs them in sequence. 
-                    Consequently, you might want to add this package to
-                    your image. 
-                </para>
-            </section>           
+            </section>         
         </section>
     </section>