"Fossies" - the Fresh Open Source Software Archive

Member "xorriso-1.5.4/releng/README" (26 Nov 2019, 12761 Bytes) of package /linux/misc/xorriso-1.5.4.pl02.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "README": 1.5.2_vs_1.5.4.

    1 ------------------------------------------------------------------------------
    2                          http:libburnia-project.org
    3 ------------------------------------------------------------------------------
    4 libisoburn/releng. By George Danchev <danchev@spnet.net>
    5                   and Thomas Schmitt <scdbackup@gmx.net>
    6 
    7 Test suite for xorriso and libburnia libraries.
    8 Copyright (C) 2011 - 2012 George Danchev
    9 Copyright (C) 2011, 2012, 2019 Thomas Schmitt
   10 Provided under GPL version 2 or later.
   11 ------------------------------------------------------------------------------
   12 
   13 The impatient tester will build libisoburn according to its README and then do
   14 
   15   cd ./releng
   16   ./run_all_auto -x ../xorriso/xorriso
   17 
   18 More patient testers will first read the following description.
   19 
   20 Those who simply lack the interpreter /bin/bash, may do
   21   ./change_shell_to_use
   22 and then retry.
   23 
   24 
   25                             The test suite
   26 
   27 Directory ./releng of libisoburn contains a collection of test scripts and
   28 auxiliary data. They exercise some typical use cases of building libisoburn
   29 applications and running the ISO 9660 filesystem manipulation and CD/DVD/BD
   30 burn program xorriso. 
   31 
   32 It is assumed that libburn and libisofs are installed, so that libisoburn
   33 can be configured and built. It is not mandatory that libisoburn is already
   34 installed. The tests may use an installed xorriso program as well as a
   35 freshly built one.
   36 
   37 The test scripts explicitly demand /bin/bash as interpreter, although they
   38 would run on certain other shells too. If you get an error message like
   39   ./run_all_auto: not found
   40 then consider to install /bin/bash.
   41 If you decide against that, see below "Alternative Shells".
   42 
   43 
   44 There are two groups of test scripts:
   45 
   46   auto_*    gets started and watched by script run_all_auto.
   47             These tests have a moderate resource consumption and do
   48             not cause mechanical movements of drive trays.
   49 
   50   manual_*  gets started by the user if desired.
   51             Manual tests may create larger sets of temporary files,
   52             may download test data from the internet, may need
   53             system privileges beyond the reach of a sandbox user,
   54             and operate the mechanics of a CD drive.
   55 
   56 
   57                        Running automated tests
   58 
   59 The test scripts expect to get run while the working directory is
   60   ./releng
   61 of a libisoburn source tree. E.g.: libisoburn-1.1.4/releng
   62 They create all their temporary files underneath
   63   ./releng/releng_generated_data 
   64 Some of these files are persistent between tests.
   65 Nevertheless it is safe to empty ./releng/releng_generated_data after
   66 tests are done. The directory itself must be kept.
   67 
   68 To run the unobtrusive automatic tests, build libisoburn and xorriso,
   69 go to directory ./releng, and execute
   70 
   71   ./run_all_auto -x ../xorriso/xorriso
   72 
   73 or if you want to use an installed xorriso program:
   74 
   75   ./run_all_auto -x $(which xorriso)
   76 
   77   ./run_all_auto -x $(type -p xorriso)
   78 
   79 There are several options which work with run_all_auto and any single test.
   80   -x  absolute or relative path to xorriso binary to be run.
   81   -k  keep self-generated data.
   82   -c  cleanup temporary data kept from previous run and exit.
   83   -f  simulate failure.
   84   -h  print this help text.
   85   --  end of general options, begin of test specific options.
   86 After option "--", there may be given options which are specific to
   87 particular manually executable test scripts. 
   88 
   89 
   90                         Manually executable tests
   91                  
   92 Currently there are the following tests which should have the attention of
   93 the user or require sysadmin considerations before they are run:
   94 
   95 ./manual_devices -x ../xorriso/xorriso [-- [--dev device_file_to_use]
   96                                         [--priv_cmd 'command [arg [arg ...]]']]
   97   Exercises listing of all accessible optical drives and the examination of
   98   a one of these drives. The user needs the permission to operate the CD
   99   drives. This might involve the need for superuser authority.
  100   The media tray of the examined drive will get loaded if it is not already.
  101   If no option --dev is given, then the user gets asked which of the listed
  102   drives to examine more closely.
  103   If a privilege command and optional arguments are given with --priv_cmd,
  104   then this command and arguments are used to launch the xorriso runs.
  105   Command and arguments must be single words and be submitted altogether
  106   as one single argument. On Solaris use: --priv_cmd pfexec
  107 
  108 ./manual_burn -x ../xorriso/xorriso [-- [--dev device_file_to_use]
  109                                         [--priv_cmd 'command [arg [arg ...]]']
  110                                         [--what ...directory...] [--any_media]]
  111   Burns the content of the directory given with --what onto re-usable
  112   media: CD-RW, DVD-RW, DVD-RAM, DVD+RW, BD-RE.
  113   Other media types get refused, unless option --any_media is given.
  114   Data, which are possibly present on the media, get overwritten.
  115   The result gets check read and compared with the state of the input
  116   directory. MD5 mismatch causes a test failure. Differences to the directory
  117   state are reported but still regarded as success.
  118   If a privilege command and optional arguments are given with --priv_cmd,
  119   then this command and arguments are used to launch the xorriso runs.
  120   Command and arguments must be single words and be submitted altogether
  121   as one single argument. On Solaris use:
  122     --priv_cmd pfexec
  123 
  124 ./manual_isojigdo -x ../xorriso/xorriso [-- [--md5 | --sha256]]
  125   Exercises the production of a bootable Debian GNU/Linux image and its Jigdo
  126   files. This test downloads a Debian daily image for i386 of about 350 MB,
  127   extracts its content and composes a new image. Thus it needs about 1100 MB
  128   of disk space in releng/releng_generated_data when unpacked. Adding the daily
  129   image size itself, the total space used would peak at about 1.5 GB.
  130   This test will only work with GNU xorriso or if libjte was installed already
  131   when libisofs was built. Further it needs the program jigit-mkimage. Both
  132   are part of package jigit, version >= 1.22, available at:
  133     http://www.einval.com/~steve/software/JTE/
  134   Currently jigit builds only in GNU environments.
  135   debian-cd currently uses the --md5 format. In future it will use --sha256.
  136 
  137 
  138 Any auto_* script can be run on its own. Some of them demand option -x.
  139 All general options are accepted.
  140 
  141 ./auto_cxx
  142   Not included in GNU xorriso.
  143   Exercises inclusion of xorriso/xorriso.h and libisoburn/libisoburn.h
  144   in C++ programs and linking of the libraries. It might be necessary
  145   to set compiler options by shell variable CFLAGS before running the test.
  146   It might be necessary to hand over the install directory of libburn and
  147   libisofs in shell variable LD_LIBRARY_PATH.
  148   E.g. if on FreeBSD the include headers libisofs.h , libburn.h are not found:
  149     export CFLAGS="-I/usr/local/include"
  150   E.g. on GNU/Hurd, where libburn and libisofs are not found by the linker:
  151     export LD_LIBRARY_PATH="/usr/local/lib"
  152 
  153 ./auto_isocontent -x ../xorriso/xorriso
  154   Tests whether xorriso is able to record and restore two families of
  155   hard links.
  156 
  157 ./auto_printsize -x ../xorriso/xorriso
  158   Tests how long xorriso needs to compose a medium sized directory tree.
  159   If programs mkisofs and/or genisomage are available, then the same test
  160   is done with them.
  161 
  162 
  163 ----------------------------------------------------------------------------
  164 
  165                        What to do with FAIL results
  166 
  167 The text output of the automatic tests is recorded in file
  168    releng_generated_data/log.run_all_auto
  169 
  170 Script ./run_all_auto will detect failure of particular tests and report
  171 lines from the log file which contain problem indicating keywords:
  172   NEVER,ABORT,FATAL,FAILURE,MISHAP,SORRY,WARNING,HINT,FAIL,ERROR,WRONG
  173 
  174 If the program messages in log.run_all_auto do not explain the failure,
  175 please contact mailing list libburn-hackers@pykix.org .
  176 
  177 
  178 ----------------------------------------------------------------------------
  179 
  180                           Alternative Shells
  181 
  182 If you decided against installing /bin/bash, you may try to use your
  183 current $SHELL by running
  184   ./change_shell_to_use
  185 which will modify the test scripts named run_all_auto , auto_* ,manual_*.
  186 
  187 Known to be suitable are the following shells
  188   GNU/Linux: /bin/bash
  189   FreeBSD 8: /bin/sh
  190   Solaris:   /bin/bash , /bin/i86/ksh93
  191 In general, the shell should have Bourne shell ancestry.
  192 
  193 The script does not choose an interpreter explicitly and is safe to be run
  194 inline:
  195   . ./change_shell_to_use
  196 One may set any interpreter path by running a sub shell and changing its
  197 variable SHELL. E.g. by:
  198   ( SHELL=/bin/my_shell" ; . ./change_shell_to_use )
  199 
  200 
  201 ----------------------------------------------------------------------------
  202 
  203                           Creating a new test script
  204 
  205 If you want to provide an own test, manual or auto, then first invent a name
  206 for it
  207   test_name="releng/manual_"...some.name...
  208 or
  209   test_name="releng/auto_"...some.name...
  210 Then copy file releng/template_new to $test_name.
  211 Edit $test_name and process any line that begins by "# === TEMPLATE:".
  212 Do what the line prescribes and then remove it from the script. You are
  213 not done as long as such a line remains.
  214 
  215 Your test must not start if no file
  216    ./inc/releng_getopts.inc
  217 exists, i.e. if the current working directory is not ./releng.
  218 If your test creates own files on disk, then it must do this underneath
  219 directory
  220    ./releng_generated_data/$test_name (or $GEN_DATA_DIR, see below).
  221 
  222 In case of failure, issue a line to stdout that begins by the word "FAIL",
  223 followed by " : " and the name of the test (e.g. $SELF, see below).
  224 Make sure that the test script finally returns a non-zero exit value.
  225 This value should be between 1 and 28. Each type of failure should have its
  226 own exit value.
  227 Predefined are:
  228   31 = Unknown option or unusable argument with known option
  229   30 = Unexpected state of own directory for self generated files
  230   29 = Not in ./releng directory or missing essential parts of ./releng
  231 
  232 When exiting prematurely, make sure to call function cleanup.
  233 
  234 
  235                Variables, general options, helper functions
  236 
  237 The master script run_all_auto sets this variable:
  238 
  239   RELENG_SCRIPT_RUN_BY_RUN_ALL_AUTO
  240                     1=supervised, the script is run by run_all_auto script
  241                     else=standalone, the script is run in standalone mode 
  242 
  243 The code piece inc/releng_getopts.inc should get executed inline at the
  244 start of a test script. It initializes the following variables and sets
  245 some of them according to the general options of the test suite:
  246 
  247   SELF              basename $0
  248 
  249   GEN_DATA_DIR      releng_generated_data/${SELF}
  250 
  251   RELENG_XORRISO    Path to xorriso binary. "" or "0" means no xorriso.
  252                     Default "0". Adjustable by option -x.
  253 
  254   SIMULATE_FAILURE  0=normal operation, 1=test script shall simulate a failure.
  255                     Default 0. Setable to 1 by option -f.
  256 
  257   CLEANUP           0=do not cleanup temporary data, 1=normal operation
  258                     Default 1. Setable to 0 by option -k.
  259 
  260   SPECIFIC_HELP     0=normal operation, 1=print help text of script and exit 0
  261                     Default 0. Setable to 1 by option -h.
  262 
  263 The code piece inc/releng_getopts.inc defines the following functions
  264 for use by the single tests:
  265 
  266   standalone_or_supervised This is internally called routine to print out
  267                            the running mode of the scripts - standalone,
  268                            supervised by run_all_auto.
  269 			   No need to call it from the scripts themselves.
  270 
  271   print_help        Prints the help text for general options.
  272 
  273   check_for_xorriso [-x]
  274                     Will exit with value 31 if no path to a xorriso binary
  275                     was defined by option -x of ./run_all_auto or a single
  276                     test.
  277                     Option -x of check_for_xorriso additionally tests whether
  278                     the given path leads to an executable program.
  279 
  280   cleanup           Removes the directory tree GEN_DATA_DIR after making
  281                     some safety checks.
  282 
  283   boldify           Try to set the terminal mode for future output to a more
  284                     noticeable style of writing.
  285   unboldify         Reset terminal mode to normal style of writing.
  286 
  287 
  288                              Specific options
  289 
  290 Options which are specific to the test should begin with a double dash.
  291 They may have further arguments.
  292 Implement them in the prepared interpreter loop which begins after line
  293   next_is=ignore
  294 
  295 Specific options shall only be interpreted by tests which get run manually.
  296 If you plan to introduce a specific option, look at the description of
  297 existing tests whether one of them would match your needs. In that case,
  298 please re-use the name of that existing option.
  299