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 @@
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 (run-ptest),
- and the actual test.
+ A ptest contains at least two items: the actual test, and
+ a shell script (run-ptest) 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,124 +3526,31 @@
- The test formats the output into the single, common
- format used by Automake:
+ The test generates output in the format used by
+ Automake:
<result>: <testname>
- The <result> can be
- PASS, FAIL, or
- SKIP.
- The <testname> can be any
- identifying string.
+ where the result can be PASS,
+ FAIL, or SKIP,
+ and the testname can be any identifying string.
-
- Getting Your Package Ready
-
-
- In order 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:
-
- Be sure the recipe
- inherits ptest:
- Include the following line in your recipes:
-
- inherit ptest
-
-
- Create run-ptest:
- The run-ptest script needs to
- start your tests.
- Locate this script where you would point to it
- using
- SRC_URI.
- Here is an example that starts a test for
- dbus:
-
- #!/bin/sh
- cd test
- make -k runtest-TESTS
-
-
- Ensure dependencies are
- met:
- If the test adds build or runtime dependencies
- to the package that do not normally exist
- (such as requiring "make" to run the test suite),
- use the
- RDEPENDS
- variable in your recipe so the package meets the
- dependency.
- Here is an example where the package has a build
- dependency on "make":
-
- RDEPENDS_${PN}-ptest += "make"
-
-
- Add a function to build the
- test suite:
- Few packages support cross-compiling their test
- suites.
- Consequently, you usually need to add that function.
-
- Many packages based on Automake compile and
- run the test suite by using a single command
- such as make check.
- 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
- make check automatically
- cross-compile.
- However, you still must add a
- do_compile_ptest function to
- build the test suite.
- Add a function similar to the following to your
- recipe:
-
- do_compile_ptest() {
- oe_runmake buildtest-TESTS
- }
-
-
- Ensure special configurations
- are set:
- If the package requires special configurations
- prior to compiling the test code, you must
- insert a do_configure_ptest
- function into the recipe.
-
- Install the test
- suite:
- The ptest.bbclass class
- automatically copies the file
- run-ptest to the target and
- then runs make install-ptest
- to run the tests.
- If this is not the case, you need to create a
- do_install_ptest that gets
- called after the "make install-ptest" completes.
-
-
-
-
+
+ With this release of the Yocto Project, three recipes exist
+ that are "ptest-enabled": bash,
+ glib-2.0, and
+ dbus.
+ These three recipes are Autotool-enabled.
+ Adding ptest to Your Build
To add package testing to your build, add the
- DISTRO_FEATURES
- and EXTRA_IMAGE_FEATURES
+ DISTRO_FEATURES
+ and EXTRA_IMAGE_FEATURES
variables to your local.conf file,
which is found in the
Build Directory:
@@ -3669,7 +3576,108 @@
Consequently, you might want to add this package to
your image.
-
+
+
+
+ Getting Your Package Ready
+
+
+ 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:
+
+ Be sure the recipe
+ inherits ptest:
+ Include the following line in each recipe:
+
+ inherit ptest
+
+
+ Create run-ptest:
+ This script starts your test.
+ Locate the script where you will refer to it
+ using
+ SRC_URI.
+ Here is an example that starts a test for
+ dbus:
+
+ #!/bin/sh
+ cd test
+ make -k runtest-TESTS
+
+
+ Ensure dependencies are
+ met:
+ If the test adds build or runtime dependencies
+ that normally do not exist for the package
+ (such as requiring "make" to run the test suite),
+ use the
+ DEPENDS
+ and
+ RDEPENDS
+ 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":
+
+ RDEPENDS_${PN}-ptest += "make"
+
+
+ Add a function to build the
+ test suite:
+ Not many packages support cross-compilation of
+ their test suites.
+ Consequently, you usually need to add a
+ cross-compilation function to the package.
+
+ Many packages based on Automake compile and
+ run the test suite by using a single command
+ such as make check.
+ However, the native make check
+ 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 make check
+ automatically cross-compiles.
+ However, you still must add a
+ do_compile_ptest function to
+ build the test suite.
+ Add a function similar to the following to your
+ recipe:
+
+ do_compile_ptest() {
+ oe_runmake buildtest-TESTS
+ }
+
+
+ Ensure special configurations
+ are set:
+ If the package requires special configurations
+ prior to compiling the test code, you must
+ insert a do_configure_ptest
+ function into the recipe.
+
+ Install the test
+ suite:
+ The ptest.bbclass class
+ automatically copies the file
+ run-ptest to the target and
+ then runs make install-ptest
+ to run the tests.
+ If this is not enough, you need to create a
+ do_install_ptest function and
+ make sure it gets called after the
+ "make install-ptest" completes.
+
+
+
+