1 This is a collection of tests for GDB.
3 The file gdb/README contains basic instructions on how to run the
4 testsuite, while this file documents additional options and controls
5 that are available. The GDB wiki may also have some pages with ideas
12 There are two ways to run the testsuite and pass additional parameters
13 to DejaGnu. The first is to do `make check' in the main build
14 directory and specifying the makefile variable `RUNTESTFLAGS':
16 make check RUNTESTFLAGS='TRANSCRIPT=y gdb.base/a2-run.exp'
18 The second is to cd to the testsuite directory and invoke the DejaGnu
19 `runtest' command directly.
25 (The `site.exp' file contains a handful of useful variables like host
26 and target triplets, and pathnames.)
31 If not testing with a remote host (in DejaGnu's sense), you can run
32 the GDB test suite in a fully parallel mode. In this mode, each .exp
33 file runs separately and maybe simultaneously. The test suite ensures
34 that all the temporary files created by the test suite do not clash,
35 by putting them into separate directories. This mode is primarily
36 intended for use by the Makefile.
38 For GNU make, the Makefile tries to run the tests in parallel mode if
39 any -j option is given. For a non-GNU make, tests are not
42 If RUNTESTFLAGS is not empty, then by default the tests are
43 serialized. This can be overridden by either using the
44 `check-parallel' target in the Makefile, or by setting FORCE_PARALLEL
45 to any non-empty value:
47 make check-parallel RUNTESTFLAGS="--target_board=native-gdbserver
48 make check RUNTESTFLAGS="--target_board=native-gdbserver FORCE_PARALLEL=1
50 If you want to use runtest directly instead of using the Makefile, see
51 the description of GDB_PARALLEL below.
53 Running the Performance Tests
54 *****************************
56 GDB Testsuite includes performance test cases, which are not run together
57 with other test cases, because performance test cases are slow and need
58 a quiet system. There are two ways to run the performance test cases.
59 The first is to do `make check-perf' in the main build directory:
61 make check-perf RUNTESTFLAGS="solib.exp SOLIB_COUNT=8"
63 The second is to cd to the testsuite directory and invoke the DejaGnu
64 `runtest' command directly.
68 runtest GDB_PERFTEST_MODE=both GDB_PERFTEST_TIMEOUT=4000 --directory=gdb.perf solib.exp SOLIB_COUNT=8
70 Only "compile", "run" and "both" are valid to GDB_PERFTEST_MODE. They
71 stand for "compile tests only", "run tests only", and "compile and run
72 tests" respectively. "both" is the default. GDB_PERFTEST_TIMEOUT
73 specify the timeout, which is 3000 in default. The result of
74 performance test is appended in `testsuite/perftest.log'.
79 The following parameters are DejaGNU variables that you can set to
80 affect the testsuite run globally.
84 You may find it useful to have a transcript of the commands that the
85 testsuite sends to GDB, for instance if GDB crashes during the run,
86 and you want to reconstruct the sequence of commands.
88 If the DejaGNU variable TRANSCRIPT is set (to any value), each
89 invocation of GDB during the test run will get a transcript file
90 written into the DejaGNU output directory. The file will have the
91 name transcript.<n>, where <n> is an integer. The first line of the
92 file shows the invocation command with all the options passed to it,
93 while subsequent lines are the GDB commands. A `make check' might
96 make check RUNTESTFLAGS=TRANSCRIPT=y
98 The transcript may not be complete, as for instance tests of command
99 completion may show only partial command lines.
103 By default, the testsuite exercises the GDB in the build directory,
104 but you can set GDB to be a pathname to a different version. For
107 make check RUNTESTFLAGS=GDB=/usr/bin/gdb
109 runs the testsuite on the GDB in /usr/bin.
113 You can set GDBSERVER to be a particular GDBserver of interest, so for
116 make check RUNTESTFLAGS="GDB=/usr/bin/gdb GDBSERVER=/usr/bin/gdbserver"
118 checks both the installed GDB and GDBserver.
122 Command line options passed to all GDB invocations.
124 The default is "-nw -nx".
126 `-nw' disables any of the windowed interfaces.
127 `-nx' disables ~/.gdbinit, so that it doesn't interfere with
130 This is actually considered an internal variable, and you
131 won't normally want to change it. However, in some situations,
132 this may be tweaked as a last resort if the testsuite doesn't
133 have direct support for the specifics of your environment.
134 The testsuite does not override a value provided by the user.
136 As an example, when testing an installed GDB that has been
137 configured with `--with-system-gdbinit', like by default,
138 you do not want ~/.gdbinit to interfere with tests, but, you
139 may want the system .gdbinit file loaded. As there's no way to
140 ask the testsuite, or GDB, to load the system gdbinit but
141 not ~/.gdbinit, a workaround is then to remove `-nx' from
142 INTERNAL_GDBFLAGS, and point $HOME at a directory without
143 a .gdbinit. For example:
148 GDBSERVER=/usr/bin/gdbserver \
149 INTERNAL_GDBFLAGS=-nw
153 To use parallel testing mode without using the the Makefile, set
154 GDB_PARALLEL on the runtest command line to "yes". Before starting
155 the tests, you must ensure that the directories cache, outputs, and
156 temp in the test suite build directory are either empty or have been
157 deleted. cache in particular is used to share data across invocations
158 of runtest, and files there may affect the test results. The Makefile
159 automatically does these deletions.
163 Setting FORCE_PARALLEL to any non-empty value forces parallel testing
164 mode even if RUNTESTFLAGS is not empty.
168 For debugging parallel mode, it is handy to be able to see when a test
169 case writes to a file outside of its designated output directory.
171 If you have the inotify-tools package installed, you can set the
172 GDB_INOTIFY variable on the runtest command line. This will cause the
173 test suite to watch for parallel-unsafe file creations and report
174 them, both to stdout and in the test suite log file.
176 This setting is only meaningful in conjunction with GDB_PARALLEL.
180 This variable is used to specify which set of tests to run.
181 It is passed to make (not runtest) and its contents are a space separated
182 list of tests to run.
184 If using GNU make then the contents are wildcard-expanded using
185 GNU make's $(wildcard) function. Test paths must be fully specified,
186 relative to the "testsuite" subdirectory. This allows one to run all
187 tests in a subdirectory by passing "gdb.subdir/*.exp", or more simply
188 by using the check-gdb.subdir target in the Makefile.
190 If for some strange reason one wanted to run all tests that begin with
191 the letter "d" that is also possible: TESTS="*/d*.exp".
193 Do not write */*.exp to specify all tests (assuming all tests are only
194 nested one level deep, which is not necessarily true). This will pick up
195 .exp files in ancillary directories like "lib" and "config".
196 Instead write gdb.*/*.exp.
200 make -j10 check TESTS="gdb.server/[s-w]*.exp */x*.exp"
202 If not using GNU make then the value is passed directly to runtest.
203 If not specified, all tests are run.
207 This make (not runtest) variable is used to specify whether the
208 testsuite preloads the read1.so library into expect. Any non-empty
209 value means true. See "Race detection" below.
214 The testsuite includes a mechanism that helps detect test races.
216 For example, say the program running under expect outputs "abcd", and
217 a test does something like this:
228 Which case happens to match depends on what expect manages to read
229 into its internal buffer in one go. If it manages to read three bytes
230 or more, then the first case matches. If it manages to read two
231 bytes, then the second case matches. If it manages to read only one
232 byte, then the third case matches.
234 To help detect these cases, the race detection mechanism preloads a
235 library into expect that forces the `read' system call to always
236 return at most 1 byte.
238 To enable this, either pass a non-empty value in the READ1 make
239 variable, or use the check-read1 make target instead of check.
243 make -j10 check-read1 TESTS="*/paginate-*.exp"
244 make -j10 check READ1="1"
246 Testsuite Configuration
247 ***********************
249 It is possible to adjust the behavior of the testsuite by defining
250 the global variables listed below, either in a `site.exp' file,
255 Defining this variable changes the default timeout duration used
256 during communication with GDB. More specifically, the global variable
257 used during testing is `timeout', but this variable gets reset to
258 `gdb_test_timeout' at the beginning of each testcase, which ensures
259 that any local change to `timeout' in a testcase does not affect
260 subsequent testcases.
262 This global variable comes in handy when the debugger is slower than
263 normal due to the testing environment, triggering unexpected `TIMEOUT'
264 test failures. Examples include when testing on a remote machine, or
265 against a system where communications are slow.
267 If not specifically defined, this variable gets automatically defined
268 to the same value as `timeout' during the testsuite initialization.
269 The default value of the timeout is defined in the file
270 `testsuite/config/unix.exp' (at least for Unix hosts; board files may
271 have their own values).
275 Defining this variable changes the default timeout duration when tests
276 under gdb.reverse directory are running. Process record and reverse
277 debugging is so slow that its tests have unexpected `TIMEOUT' test
278 failures. This global variable is useful to bump up the value of
279 `timeout' for gdb.reverse tests and doesn't cause any delay where
280 actual failures happen in the rest of the testsuite.
286 DejaGNU includes the concept of a "board file", which specifies
287 testing details for a particular target (which are often bare circuit
288 boards, thus the name).
290 In the GDB testsuite specifically, the board file may include a
291 number of "board settings" that test cases may check before deciding
292 whether to exercise a particular feature. For instance, a board
293 lacking any I/O devices, or perhaps simply having its I/O devices
294 not wired up, should set `noinferiorio'.
296 Here are the supported board settings:
298 gdb,cannot_call_functions
300 The board does not support inferior call, that is, invoking inferior
305 The board supports reverse execution.
307 gdb,no_hardware_watchpoints
309 The board does not support hardware watchpoints.
313 GDB is unable to intercept target file operations in remote and
314 perform them on the host.
318 The board is unable to provide I/O capability to the inferior.
322 A program will not return an exit code or result code (or the value
323 of the result is undefined, and should not be looked at).
327 The board does not support signals.
331 Skip time-consuming tests on the board with slow connection.
335 Skip tests related to floating point.
339 The board supports process record.
344 Commands to send to GDB every time a program is about to be run. The
345 first of these settings defines a single command as a string. The
346 second defines a TCL list of commands being a string each. The commands
347 are sent one by one in a sequence, first from `gdb_init_command', if any,
348 followed by individual commands from `gdb_init_command', if any, in this
353 The location of GDBserver. If GDBserver somewhere other than its
354 default location is used in test, specify the location of GDBserver in
355 this variable. The location is a file name for GDBserver, and may be
356 either absolute or relative to the testsuite subdirectory of the build
361 The location of the in-process agent (used for fast tracepoints and
362 other special tests). If the in-process agent of interest is anywhere
363 other than its default location, set this variable. The location is a
364 filename, and may be either absolute or relative to the testsuite
365 subdirectory of the build directory.
369 GDB does not support argument passing for inferior.
373 The board does not support type long long.
377 The board is running the monitor Cygmon.
381 The tests are running with a GDB stub.
385 Set to true if GDB can assume that letting the program run to end
386 reliably results in program exits being reported as such, as opposed
387 to, e.g., the program ending in an infinite loop or the board
388 crashing/resetting. If not set, this defaults to $use_gdb_stub. In
389 other words, native targets are assumed reliable by default, and
390 remote stubs assumed unreliable.
394 The predefined trace state variables the board has.
398 The target doesn't support thread names.
400 Testsuite Organization
401 **********************
403 The testsuite is entirely contained in `gdb/testsuite'. The main
404 directory of the testsuite includes some makefiles and configury, but
405 these are minimal, and used for little besides cleaning up, since the
406 tests themselves handle the compilation of the programs that GDB will
409 The file `testsuite/lib/gdb.exp' contains common utility procs useful
410 for all GDB tests, while the directory testsuite/config contains
411 configuration-specific files, typically used for special-purpose
412 definitions of procs like `gdb_load' and `gdb_start'.
414 The tests themselves are to be found in directories named
415 'testsuite/gdb.* and subdirectories of those. The names of the test
416 files must always end with ".exp". DejaGNU collects the test files by
417 wildcarding in the test directories, so both subdirectories and
418 individual files typically get chosen and run in alphabetical order.
420 The following lists some notable types of subdirectories and what they
421 are for. Since DejaGNU finds test files no matter where they are
422 located, and since each test file sets up its own compilation and
423 execution environment, this organization is simply for convenience and
428 This is the base testsuite. The tests in it should apply to all
429 configurations of GDB (but generic native-only tests may live here).
430 The test programs should be in the subset of C that is both valid
435 Language-specific tests for any language besides C. Examples are
436 gdb.cp for C++ and gdb.java for Java.
440 Non-portable tests. The tests are specific to a specific
441 configuration (host or target), such as eCos.
445 Architecture-specific tests that are (usually) cross-platform.
449 Tests that exercise a specific GDB subsystem in more depth. For
450 instance, gdb.disasm exercises various disassemblers, while
451 gdb.stabs tests pathways through the stabs symbol reader.
455 GDB performance tests.
460 In many areas, the GDB tests are already quite comprehensive; you
461 should be able to copy existing tests to handle new cases. Be aware
462 that older tests may use obsolete practices but have not yet been
465 You should try to use `gdb_test' whenever possible, since it includes
466 cases to handle all the unexpected errors that might happen. However,
467 it doesn't cost anything to add new test procedures; for instance,
468 gdb.base/exprs.exp defines a `test_expr' that calls `gdb_test'
471 Only use `send_gdb' and `gdb_expect' when absolutely necessary. Even
472 if GDB has several valid responses to a command, you can use
473 `gdb_test_multiple'. Like `gdb_test', `gdb_test_multiple' recognizes
474 internal errors and unexpected prompts.
476 Do not write tests which expect a literal tab character from GDB. On
477 some operating systems (e.g. OpenBSD) the TTY layer expands tabs to
478 spaces, so by the time GDB's output reaches `expect' the tab is gone.
480 The source language programs do *not* need to be in a consistent
481 style. Since GDB is used to debug programs written in many different
482 styles, it's worth having a mix of styles in the testsuite; for
483 instance, some GDB bugs involving the display of source lines might
484 never manifest themselves if the test programs used GNU coding style
487 Some testcase results need more detailed explanation:
491 Use KFAIL for known problem of GDB itself. You must specify the GDB
492 bug report number, as in these sample tests:
494 kfail "gdb/13392" "continue to marker 2"
498 setup_kfail gdb/13392 "*-*-*"
499 kfail "continue to marker 2"
504 Short for "expected failure", this indicates a known problem with the
505 environment. This could include limitations of the operating system,
506 compiler version, and other components.
508 This example from gdb.base/attach-pie-misread.exp is a sanity check
509 for the target environment:
511 # On x86_64 it is commonly about 4MB.
512 if {$stub_size > 25000000} {
513 xfail "stub size $stub_size is too large"
517 You should provide bug report number for the failing component of the
518 environment, if such bug report is available, as with this example
519 referring to a GCC problem:
521 if {[test_compiler_info {gcc-[0-3]-*}]
522 || [test_compiler_info {gcc-4-[0-5]-*}]} {
523 setup_xfail "gcc/46955" *-*-*
525 gdb_test "python print ttype.template_argument(2)" "&C::c"
527 Note that it is also acceptable, and often preferable, to avoid
528 running the test at all. This is the better option if the limitation
529 is intrinsic to the environment, rather than a bug expected to be
530 fixed in the near future.