"Fossies" - the Fresh Open Source Software Archive 
Member "libisoburn-1.5.6/releng/README" (10 May 2022, 12839 Bytes) of package /linux/misc/libisoburn-1.5.6.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 latest
Fossies "Diffs" side-by-side code changes report for "README":
1.5.4_vs_1.5.6.
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 is possible to override the
145 use of g++ as compiler by shell variable CC. It might be necessary to set
146 compiler options by shell variable CFLAGS before running the test.
147 It might be necessary to hand over the install directory of libburn and
148 libisofs in shell variable LD_LIBRARY_PATH.
149 E.g. if on FreeBSD the include headers libisofs.h , libburn.h are not found:
150 export CFLAGS="-I/usr/local/include"
151 E.g. on GNU/Hurd, where libburn and libisofs are not found by the linker:
152 export LD_LIBRARY_PATH="/usr/local/lib"
153
154 ./auto_isocontent -x ../xorriso/xorriso
155 Tests whether xorriso is able to record and restore two families of
156 hard links.
157
158 ./auto_printsize -x ../xorriso/xorriso
159 Tests how long xorriso needs to compose a medium sized directory tree.
160 If programs mkisofs and/or genisomage are available, then the same test
161 is done with them.
162
163
164 ----------------------------------------------------------------------------
165
166 What to do with FAIL results
167
168 The text output of the automatic tests is recorded in file
169 releng_generated_data/log.run_all_auto
170
171 Script ./run_all_auto will detect failure of particular tests and report
172 lines from the log file which contain problem indicating keywords:
173 NEVER,ABORT,FATAL,FAILURE,MISHAP,SORRY,WARNING,HINT,FAIL,ERROR,WRONG
174
175 If the program messages in log.run_all_auto do not explain the failure,
176 please contact mailing list libburn-hackers@pykix.org .
177
178
179 ----------------------------------------------------------------------------
180
181 Alternative Shells
182
183 If you decided against installing /bin/bash, you may try to use your
184 current $SHELL by running
185 ./change_shell_to_use
186 which will modify the test scripts named run_all_auto , auto_* ,manual_*.
187
188 Known to be suitable are the following shells
189 GNU/Linux: /bin/bash
190 FreeBSD 8: /bin/sh
191 Solaris: /bin/bash , /bin/i86/ksh93
192 In general, the shell should have Bourne shell ancestry.
193
194 The script does not choose an interpreter explicitly and is safe to be run
195 inline:
196 . ./change_shell_to_use
197 One may set any interpreter path by running a sub shell and changing its
198 variable SHELL. E.g. by:
199 ( SHELL=/bin/my_shell" ; . ./change_shell_to_use )
200
201
202 ----------------------------------------------------------------------------
203
204 Creating a new test script
205
206 If you want to provide an own test, manual or auto, then first invent a name
207 for it
208 test_name="releng/manual_"...some.name...
209 or
210 test_name="releng/auto_"...some.name...
211 Then copy file releng/template_new to $test_name.
212 Edit $test_name and process any line that begins by "# === TEMPLATE:".
213 Do what the line prescribes and then remove it from the script. You are
214 not done as long as such a line remains.
215
216 Your test must not start if no file
217 ./inc/releng_getopts.inc
218 exists, i.e. if the current working directory is not ./releng.
219 If your test creates own files on disk, then it must do this underneath
220 directory
221 ./releng_generated_data/$test_name (or $GEN_DATA_DIR, see below).
222
223 In case of failure, issue a line to stdout that begins by the word "FAIL",
224 followed by " : " and the name of the test (e.g. $SELF, see below).
225 Make sure that the test script finally returns a non-zero exit value.
226 This value should be between 1 and 28. Each type of failure should have its
227 own exit value.
228 Predefined are:
229 31 = Unknown option or unusable argument with known option
230 30 = Unexpected state of own directory for self generated files
231 29 = Not in ./releng directory or missing essential parts of ./releng
232
233 When exiting prematurely, make sure to call function cleanup.
234
235
236 Variables, general options, helper functions
237
238 The master script run_all_auto sets this variable:
239
240 RELENG_SCRIPT_RUN_BY_RUN_ALL_AUTO
241 1=supervised, the script is run by run_all_auto script
242 else=standalone, the script is run in standalone mode
243
244 The code piece inc/releng_getopts.inc should get executed inline at the
245 start of a test script. It initializes the following variables and sets
246 some of them according to the general options of the test suite:
247
248 SELF basename $0
249
250 GEN_DATA_DIR releng_generated_data/${SELF}
251
252 RELENG_XORRISO Path to xorriso binary. "" or "0" means no xorriso.
253 Default "0". Adjustable by option -x.
254
255 SIMULATE_FAILURE 0=normal operation, 1=test script shall simulate a failure.
256 Default 0. Setable to 1 by option -f.
257
258 CLEANUP 0=do not cleanup temporary data, 1=normal operation
259 Default 1. Setable to 0 by option -k.
260
261 SPECIFIC_HELP 0=normal operation, 1=print help text of script and exit 0
262 Default 0. Setable to 1 by option -h.
263
264 The code piece inc/releng_getopts.inc defines the following functions
265 for use by the single tests:
266
267 standalone_or_supervised This is internally called routine to print out
268 the running mode of the scripts - standalone,
269 supervised by run_all_auto.
270 No need to call it from the scripts themselves.
271
272 print_help Prints the help text for general options.
273
274 check_for_xorriso [-x]
275 Will exit with value 31 if no path to a xorriso binary
276 was defined by option -x of ./run_all_auto or a single
277 test.
278 Option -x of check_for_xorriso additionally tests whether
279 the given path leads to an executable program.
280
281 cleanup Removes the directory tree GEN_DATA_DIR after making
282 some safety checks.
283
284 boldify Try to set the terminal mode for future output to a more
285 noticeable style of writing.
286 unboldify Reset terminal mode to normal style of writing.
287
288
289 Specific options
290
291 Options which are specific to the test should begin with a double dash.
292 They may have further arguments.
293 Implement them in the prepared interpreter loop which begins after line
294 next_is=ignore
295
296 Specific options shall only be interpreted by tests which get run manually.
297 If you plan to introduce a specific option, look at the description of
298 existing tests whether one of them would match your needs. In that case,
299 please re-use the name of that existing option.
300