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.
56 Sometimes, new testcases are added to the testsuite that are not
57 entirely deterministic, and can randomly pass or fail. We call them
58 "racy testcases", and they can be bothersome when one is comparing
59 different testsuite runs. In order to help identifying them, it is
60 possible to run the tests several times in a row and ask the testsuite
61 machinery to analyze the results. To do that, you need to specify the
62 RACY_ITER environment variable to make:
64 make check RACY_ITER=5 -j4
66 The value assigned to RACY_ITER represents the number of times you
67 wish to run the tests in sequence (in the example above, the entire
68 testsuite will be executed 5 times in a row, in parallel). It is also
69 possible to check just a specific test:
71 make check TESTS='gdb.base/default.exp' RACY_ITER=3
73 One can also decide to call the Makefile rules by hand inside the
74 gdb/testsuite directory, e.g.:
76 make check-paralell-racy -j4
78 In which case the value of the DEFAULT_RACY_ITER variable (inside
79 gdb/testsuite/Makefile.in) will be used to determine how many
80 iterations will be run.
82 After running the tests, you shall see a file name 'racy.sum' in the
83 gdb/testsuite directory. You can also inspect the generated *.log and
84 *.sum files by looking into the gdb/testsuite/racy_ouputs directory.
86 If you already have *.sum files generated from previous testsuite runs
87 and you would like to analyze them without having to run the testsuite
88 again, you can also use the 'analyze-racy-logs.py' script directly.
89 It is located in the gdb/testsuite/ directory, and it expects a list
90 of two or more *.sum files to be provided as its argument. For
93 ./gdb/testsuite/analyze-racy-logs.py testsuite-01/gdb.sum \
94 testsuite-02/gdb.sum testsuite-03/gdb.sum
96 The script will output its analysis report to the standard output.
98 Running the Performance Tests
99 *****************************
101 GDB Testsuite includes performance test cases, which are not run together
102 with other test cases, because performance test cases are slow and need
103 a quiet system. There are two ways to run the performance test cases.
104 The first is to do `make check-perf' in the main build directory:
106 make check-perf RUNTESTFLAGS="solib.exp SOLIB_COUNT=8"
108 The second is to cd to the testsuite directory and invoke the DejaGnu
109 `runtest' command directly.
113 runtest GDB_PERFTEST_MODE=both GDB_PERFTEST_TIMEOUT=4000 --directory=gdb.perf solib.exp SOLIB_COUNT=8
115 Only "compile", "run" and "both" are valid to GDB_PERFTEST_MODE. They
116 stand for "compile tests only", "run tests only", and "compile and run
117 tests" respectively. "both" is the default. GDB_PERFTEST_TIMEOUT
118 specify the timeout, which is 3000 in default. The result of
119 performance test is appended in `testsuite/perftest.log'.
124 The following parameters are DejaGNU variables that you can set to
125 affect the testsuite run globally.
129 You may find it useful to have a transcript of the commands that the
130 testsuite sends to GDB, for instance if GDB crashes during the run,
131 and you want to reconstruct the sequence of commands.
133 If the DejaGNU variable TRANSCRIPT is set (to any value), each
134 invocation of GDB during the test run will get a transcript file
135 written into the DejaGNU output directory. The file will have the
136 name transcript.<n>, where <n> is an integer. The first line of the
137 file shows the invocation command with all the options passed to it,
138 while subsequent lines are the GDB commands. A `make check' might
141 make check RUNTESTFLAGS=TRANSCRIPT=y
143 The transcript may not be complete, as for instance tests of command
144 completion may show only partial command lines.
148 By default, the testsuite exercises the GDB in the build directory,
149 but you can set GDB to be a pathname to a different version. For
152 make check RUNTESTFLAGS=GDB=/usr/bin/gdb
154 runs the testsuite on the GDB in /usr/bin.
158 You can set GDBSERVER to be a particular GDBserver of interest, so for
161 make check RUNTESTFLAGS="GDB=/usr/bin/gdb GDBSERVER=/usr/bin/gdbserver"
163 checks both the installed GDB and GDBserver.
167 Command line options passed to all GDB invocations.
169 The default is "-nw -nx".
171 `-nw' disables any of the windowed interfaces.
172 `-nx' disables ~/.gdbinit, so that it doesn't interfere with
175 This is actually considered an internal variable, and you
176 won't normally want to change it. However, in some situations,
177 this may be tweaked as a last resort if the testsuite doesn't
178 have direct support for the specifics of your environment.
179 The testsuite does not override a value provided by the user.
181 As an example, when testing an installed GDB that has been
182 configured with `--with-system-gdbinit', like by default,
183 you do not want ~/.gdbinit to interfere with tests, but, you
184 may want the system .gdbinit file loaded. As there's no way to
185 ask the testsuite, or GDB, to load the system gdbinit but
186 not ~/.gdbinit, a workaround is then to remove `-nx' from
187 INTERNAL_GDBFLAGS, and point $HOME at a directory without
188 a .gdbinit. For example:
193 GDBSERVER=/usr/bin/gdbserver \
194 INTERNAL_GDBFLAGS=-nw
198 To use parallel testing mode without using the the Makefile, set
199 GDB_PARALLEL on the runtest command line to "yes". Before starting
200 the tests, you must ensure that the directories cache, outputs, and
201 temp in the test suite build directory are either empty or have been
202 deleted. cache in particular is used to share data across invocations
203 of runtest, and files there may affect the test results. The Makefile
204 automatically does these deletions.
208 Setting FORCE_PARALLEL to any non-empty value forces parallel testing
209 mode even if RUNTESTFLAGS is not empty.
211 FORCE_SEPARATE_MI_TTY
213 Setting FORCE_MI_SEPARATE_UI to 1 forces all MI testing to start GDB
214 in console mode, with MI running on a separate TTY, on a secondary UI
215 started with "new-ui".
219 For debugging parallel mode, it is handy to be able to see when a test
220 case writes to a file outside of its designated output directory.
222 If you have the inotify-tools package installed, you can set the
223 GDB_INOTIFY variable on the runtest command line. This will cause the
224 test suite to watch for parallel-unsafe file creations and report
225 them, both to stdout and in the test suite log file.
227 This setting is only meaningful in conjunction with GDB_PARALLEL.
231 This variable is used to specify which set of tests to run.
232 It is passed to make (not runtest) and its contents are a space separated
233 list of tests to run.
235 If using GNU make then the contents are wildcard-expanded using
236 GNU make's $(wildcard) function. Test paths must be fully specified,
237 relative to the "testsuite" subdirectory. This allows one to run all
238 tests in a subdirectory by passing "gdb.subdir/*.exp", or more simply
239 by using the check-gdb.subdir target in the Makefile.
241 If for some strange reason one wanted to run all tests that begin with
242 the letter "d" that is also possible: TESTS="*/d*.exp".
244 Do not write */*.exp to specify all tests (assuming all tests are only
245 nested one level deep, which is not necessarily true). This will pick up
246 .exp files in ancillary directories like "lib" and "config".
247 Instead write gdb.*/*.exp.
251 make -j10 check TESTS="gdb.server/[s-w]*.exp */x*.exp"
253 If not using GNU make then the value is passed directly to runtest.
254 If not specified, all tests are run.
258 This make (not runtest) variable is used to specify whether the
259 testsuite preloads the read1.so library into expect. Any non-empty
260 value means true. See "Race detection" below.
265 The testsuite includes a mechanism that helps detect test races.
267 For example, say the program running under expect outputs "abcd", and
268 a test does something like this:
279 Which case happens to match depends on what expect manages to read
280 into its internal buffer in one go. If it manages to read three bytes
281 or more, then the first case matches. If it manages to read two
282 bytes, then the second case matches. If it manages to read only one
283 byte, then the third case matches.
285 To help detect these cases, the race detection mechanism preloads a
286 library into expect that forces the `read' system call to always
287 return at most 1 byte.
289 To enable this, either pass a non-empty value in the READ1 make
290 variable, or use the check-read1 make target instead of check.
294 make -j10 check-read1 TESTS="*/paginate-*.exp"
295 make -j10 check READ1="1"
297 Testsuite Configuration
298 ***********************
300 It is possible to adjust the behavior of the testsuite by defining
301 the global variables listed below, either in a `site.exp' file,
306 Defining this variable changes the default timeout duration used
307 during communication with GDB. More specifically, the global variable
308 used during testing is `timeout', but this variable gets reset to
309 `gdb_test_timeout' at the beginning of each testcase, which ensures
310 that any local change to `timeout' in a testcase does not affect
311 subsequent testcases.
313 This global variable comes in handy when the debugger is slower than
314 normal due to the testing environment, triggering unexpected `TIMEOUT'
315 test failures. Examples include when testing on a remote machine, or
316 against a system where communications are slow.
318 If not specifically defined, this variable gets automatically defined
319 to the same value as `timeout' during the testsuite initialization.
320 The default value of the timeout is defined in the file
321 `testsuite/config/unix.exp' (at least for Unix hosts; board files may
322 have their own values).
326 Defining this variable changes the default timeout duration when tests
327 under gdb.reverse directory are running. Process record and reverse
328 debugging is so slow that its tests have unexpected `TIMEOUT' test
329 failures. This global variable is useful to bump up the value of
330 `timeout' for gdb.reverse tests and doesn't cause any delay where
331 actual failures happen in the rest of the testsuite.
337 DejaGNU includes the concept of a "board file", which specifies
338 testing details for a particular target (which are often bare circuit
339 boards, thus the name).
341 In the GDB testsuite specifically, the board file may include a
342 number of "board settings" that test cases may check before deciding
343 whether to exercise a particular feature. For instance, a board
344 lacking any I/O devices, or perhaps simply having its I/O devices
345 not wired up, should set `noinferiorio'.
347 Here are the supported board settings:
349 gdb,cannot_call_functions
351 The board does not support inferior call, that is, invoking inferior
356 The board supports reverse execution.
358 gdb,no_hardware_watchpoints
360 The board does not support hardware watchpoints.
364 GDB is unable to intercept target file operations in remote and
365 perform them on the host.
369 The board is unable to provide I/O capability to the inferior.
373 A program will not return an exit code or result code (or the value
374 of the result is undefined, and should not be looked at).
378 The board does not support signals.
382 Skip time-consuming tests on the board with slow connection.
386 Skip tests related to floating point.
390 The board supports process record.
395 Commands to send to GDB every time a program is about to be run. The
396 first of these settings defines a single command as a string. The
397 second defines a TCL list of commands being a string each. The commands
398 are sent one by one in a sequence, first from `gdb_init_command', if any,
399 followed by individual commands from `gdb_init_command', if any, in this
404 The location of GDBserver. If GDBserver somewhere other than its
405 default location is used in test, specify the location of GDBserver in
406 this variable. The location is a file name for GDBserver, and may be
407 either absolute or relative to the testsuite subdirectory of the build
412 The location of the in-process agent (used for fast tracepoints and
413 other special tests). If the in-process agent of interest is anywhere
414 other than its default location, set this variable. The location is a
415 filename, and may be either absolute or relative to the testsuite
416 subdirectory of the build directory.
420 GDB does not support argument passing for inferior.
424 The board does not support type long long.
428 The board is running the monitor Cygmon.
432 The tests are running with a GDB stub.
436 Set to true if GDB can assume that letting the program run to end
437 reliably results in program exits being reported as such, as opposed
438 to, e.g., the program ending in an infinite loop or the board
439 crashing/resetting. If not set, this defaults to $use_gdb_stub. In
440 other words, native targets are assumed reliable by default, and
441 remote stubs assumed unreliable.
445 The predefined trace state variables the board has.
449 The target doesn't support thread names.
451 Testsuite Organization
452 **********************
454 The testsuite is entirely contained in `gdb/testsuite'. The main
455 directory of the testsuite includes some makefiles and configury, but
456 these are minimal, and used for little besides cleaning up, since the
457 tests themselves handle the compilation of the programs that GDB will
460 The file `testsuite/lib/gdb.exp' contains common utility procs useful
461 for all GDB tests, while the directory testsuite/config contains
462 configuration-specific files, typically used for special-purpose
463 definitions of procs like `gdb_load' and `gdb_start'.
465 The tests themselves are to be found in directories named
466 'testsuite/gdb.* and subdirectories of those. The names of the test
467 files must always end with ".exp". DejaGNU collects the test files by
468 wildcarding in the test directories, so both subdirectories and
469 individual files typically get chosen and run in alphabetical order.
471 The following lists some notable types of subdirectories and what they
472 are for. Since DejaGNU finds test files no matter where they are
473 located, and since each test file sets up its own compilation and
474 execution environment, this organization is simply for convenience and
479 This is the base testsuite. The tests in it should apply to all
480 configurations of GDB (but generic native-only tests may live here).
481 The test programs should be in the subset of C that is both valid
486 Language-specific tests for any language besides C. Examples are
487 gdb.cp for C++ and gdb.rust for Rust.
491 Non-portable tests. The tests are specific to a specific
492 configuration (host or target), such as eCos.
496 Architecture-specific tests that are (usually) cross-platform.
500 Tests that exercise a specific GDB subsystem in more depth. For
501 instance, gdb.disasm exercises various disassemblers, while
502 gdb.stabs tests pathways through the stabs symbol reader.
506 GDB performance tests.
511 In many areas, the GDB tests are already quite comprehensive; you
512 should be able to copy existing tests to handle new cases. Be aware
513 that older tests may use obsolete practices but have not yet been
516 You should try to use `gdb_test' whenever possible, since it includes
517 cases to handle all the unexpected errors that might happen. However,
518 it doesn't cost anything to add new test procedures; for instance,
519 gdb.base/exprs.exp defines a `test_expr' that calls `gdb_test'
522 Only use `send_gdb' and `gdb_expect' when absolutely necessary. Even
523 if GDB has several valid responses to a command, you can use
524 `gdb_test_multiple'. Like `gdb_test', `gdb_test_multiple' recognizes
525 internal errors and unexpected prompts.
527 Do not write tests which expect a literal tab character from GDB. On
528 some operating systems (e.g. OpenBSD) the TTY layer expands tabs to
529 spaces, so by the time GDB's output reaches `expect' the tab is gone.
531 The source language programs do *not* need to be in a consistent
532 style. Since GDB is used to debug programs written in many different
533 styles, it's worth having a mix of styles in the testsuite; for
534 instance, some GDB bugs involving the display of source lines might
535 never manifest themselves if the test programs used GNU coding style
538 Some testcase results need more detailed explanation:
542 Use KFAIL for known problem of GDB itself. You must specify the GDB
543 bug report number, as in these sample tests:
545 kfail "gdb/13392" "continue to marker 2"
549 setup_kfail gdb/13392 "*-*-*"
550 kfail "continue to marker 2"
555 Short for "expected failure", this indicates a known problem with the
556 environment. This could include limitations of the operating system,
557 compiler version, and other components.
559 This example from gdb.base/attach-pie-misread.exp is a sanity check
560 for the target environment:
562 # On x86_64 it is commonly about 4MB.
563 if {$stub_size > 25000000} {
564 xfail "stub size $stub_size is too large"
568 You should provide bug report number for the failing component of the
569 environment, if such bug report is available, as with this example
570 referring to a GCC problem:
572 if {[test_compiler_info {gcc-[0-3]-*}]
573 || [test_compiler_info {gcc-4-[0-5]-*}]} {
574 setup_xfail "gcc/46955" *-*-*
576 gdb_test "python print ttype.template_argument(2)" "&C::c"
578 Note that it is also acceptable, and often preferable, to avoid
579 running the test at all. This is the better option if the limitation
580 is intrinsic to the environment, rather than a bug expected to be
581 fixed in the near future.