Began to sketch an releng/README file

releng/README

@@ -1,28 +1,102 @@
-Release Engineering
+------------------------------------------------------------------------------
-~~~~~~~~~~~~~~~~~~~
+                         http:libburnia-project.org
-* SOFTWARE TO TEST
+------------------------------------------------------------------------------
- + Use latest libburnia libraries code base from svn and bzr
+libisoburn/releng. By George Danchev <danchev@spnet.net>
-   (see top-level README for aditional library dependencies)
+                  and Thomas Schmitt <scdbackup@gmx.net>
- + Alternatively, use latest all-in-one development tarball from:
-   http://www.gnu.org/software/xorriso/
 
-* SETUP THE TEST ENVIRONMENT AND RUN THE TEST SUITE
+Test suite for xorriso and libburnia libraries.
- + All tests have to be run from the releng/ directory, within
+Copyright (C) 2011 George Danchev, Thomas Schmitt
-   libisoburn source tree. Self-generated data are stored in
+Provided under GPL version 2 or later.
-   ./releng_generated_data/ directory, and the required space for
+------------------------------------------------------------------------------
-   these data is about 300 megabytes. There is a 'master' script
+
-   called run_all_auto, which runs all scripts prefixed with auto_*.
+>>> introduce the test suite,
- + Any auto_* script can be run on its own, regardless.
+
- + Any manual_* script is to be run on its own, only.
+Directory ./releng of libisoburn contains a collection of test scripts and
- + All scripts support -h, -help, --help and
+auxiliary data. They exercise some typical use cases of building libisoburn
-   print usage help when run without options.
+applications and running the ISO 9660 filesystem manipulation and CD/DVD/BD
+burn program xorriso. 
+
+
+>>> inform about intended audience and resource needs,
+
+It is assumed that libburn and libisofs are installed, so that libisoburn
+can be configured and built. It is not mandatory that libisoburn is already
+installed. The tests may use an installed xorriso program as well as a
+freshly built one.
+
+
+>>> auto and manual tests
+
+There are two groups of test scripts:
+
+  auto_*    gets started and watched by script run_all_auto.
+            These tests have a moderate resource consumption and do
+            not cause mechanical movements of drive trays.
+
+  manual_*  get started by the user if desired.
+            Manual tests may create larger sets of temporary files,
+            may download test data from the internet, may need
+            system privileges beyond the reach of a sandbox user,
+            and operate the mechanics of a CD drive.
+
+>>> tell how to run the tests,
+
+The test scripts expect to get run while the working directory is
+  ./releng
+of a libisoburn source tree. E.g.: libisoburn-1.1.4/releng
+They create all their temporary files underneath
+  ./releng/releng_generated_data 
+Some of these files are persistent between tests.
+Nevertheless it is safe to empty ./releng/releng_generated_data after
+tests are done. The directory itself must be kept.
+
+To run the unobtrusive automatic tests, build libisoburn and xorriso,
+go to directory ./releng, and execute
+
+  ./run_all_auto -x ../xorriso/xorriso
+
+or if you want to use an installed xorriso program:
+
+  ./run_all_auto -x $(type -p xorriso)
+
+
+>>> list of manual tests
+
+Currently there are the folling tests which should have the attention of
+the user or require sysadmin considerations before they get run:
+
+  ./manual_isojigdo -x ../xorriso/xorriso
+Exercises the production of a bootable Debian GNU/Linux image and its Jigdo
+files. This test downloads a Debian daily image for i386 of about 70 MB,
+extracts its content and composes a new image.
+Thus it needs about 250 MB of disk space in releng/releng_generated_data .
+
+  ./manual_devices -x ../xorriso/xorriso
+Exercises listing of all accessible optical drives and the examination of
+a one of these drives. The user needs the permission to operate the CD
+drives. This might involve the need for superuser authority.
+The media tray of the examined drive will get loaded if it is not already.
+
+>>> ./run_all_manual
+
+
+>>> give hints what to do with FAIL results.
+
+=============================================================================
+TODO:
+
+
+* move auto_isojigdo to manual_isojigdo
+  because of its resource consumption
+
+* Remove NOTE|DEBUG|ALL from run_all_auto event class list
+
+* Delete debian-testing-i386-businesscard.iso with ./run_all_auto -c
+
+* manual_isojigdo proposes to run manual checks after it removed the
+  generated images.
+
+* Have a script ./run_all_manual
+
+* derive a GNU xorriso test suite from libisoburn test suite
 
-* DELIVERING A NEW TEST SCRIPT
- + Start a new test script over the top of template_new_releng
- + Each completed script starts with auto_ or manual_ prefix
- + Each script' self-generated data are to be stored in
-   ./releng_generated_data/scriptname/ directory
- + Keep the newly added script options in sync with other scripts
- + Throw FAIL string to stdout if any failure is detected
- + Return exit code 0 on success, non-zero on failure
- + Use different exit codes for any failure (range 0-31)