From fa9e6267c455bdc80aaa5f45a6dc1f6958883595 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 16 Apr 2013 11:01:57 -0700 Subject: 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 Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 160 +++++++++++---------- 1 file changed, 84 insertions(+), 76 deletions(-) (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml') 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,38 +3526,78 @@ - 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. + + 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 + variables to your local.conf file, + which is found in the + Build Directory: + + EXTRA_IMAGE_FEATURES += "ptest" + DISTRO_FEATURES_append = " ptest-pkgs" + + Once your build is complete, the ptest files are installed + into the /usr/lib/<package>/ptest + directory within the image, where + <package> is the name of the + package. + +
+ +
+ Running ptest + + + The ptest-runner 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. + +
+
Getting Your Package Ready - 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: Be sure the recipe inherits ptest: - Include the following line in your recipes: + Include the following line in each recipe: inherit ptest Create run-ptest: - The run-ptest 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 SRC_URI. Here is an example that starts a test for @@ -3571,13 +3611,15 @@ Ensure dependencies are met: 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 + DEPENDS + and RDEPENDS - 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": RDEPENDS_${PN}-ptest += "make" @@ -3585,25 +3627,24 @@ Add a function to build the test suite: - 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. 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, 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. @@ -3624,52 +3665,19 @@ Install the test suite: - The ptest.bbclass class - automatically copies the file + 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. + 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. -
- -
- Adding ptest to Your Build - - - To add package testing to your build, add the - DISTRO_FEATURES - and EXTRA_IMAGE_FEATURES - variables to your local.conf file, - which is found in the - Build Directory: - - EXTRA_IMAGE_FEATURES += "ptest" - DISTRO_FEATURES_append = " ptest-pkgs" - - Once your build is complete, the ptest files are installed - into the /usr/lib/<package>/ptest - directory within the image, where - <package> is the name of the - package. - -
- -
- Running ptest - - - The ptest-runner 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. - -
+ -- cgit v1.2.3-54-g00ecf