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.)
28 Running the Performance Tests
29 *****************************
31 GDB Testsuite includes performance test cases, which are not run together
32 with other test cases, because performance test cases are slow and need
33 a quiet system. There are two ways to run the performance test cases.
34 The first is to do `make check-perf' in the main build directory:
36 make check-perf RUNTESTFLAGS="solib.exp SOLIB_COUNT=8"
38 The second is to cd to the testsuite directory and invoke the DejaGnu
39 `runtest' command directly.
43 runtest GDB_PERFTEST_MODE=both GDB_PERFTEST_TIMEOUT=4000 --directory=gdb.perf solib.exp SOLIB_COUNT=8
45 Only "compile", "run" and "both" are valid to GDB_PERFTEST_MODE. They
46 stand for "compile tests only", "run tests only", and "compile and run
47 tests" respectively. "both" is the default. GDB_PERFTEST_TIMEOUT
48 specify the timeout, which is 3000 in default. The result of
49 performance test is appended in `testsuite/perftest.log'.
54 The following parameters are DejaGNU variables that you can set to
55 affect the testsuite run globally.
59 You may find it useful to have a transcript of the commands that the
60 testsuite sends to GDB, for instance if GDB crashes during the run,
61 and you want to reconstruct the sequence of commands.
63 If the DejaGNU variable TRANSCRIPT is set (to any value), each
64 invocation of GDB during the test run will get a transcript file
65 written into the DejaGNU output directory. The file will have the
66 name transcript.<n>, where <n> is an integer. The first line of the
67 file shows the invocation command with all the options passed to it,
68 while subsequent lines are the GDB commands. A `make check' might
71 make check RUNTESTFLAGS=TRANSCRIPT=y
73 The transcript may not be complete, as for instance tests of command
74 completion may show only partial command lines.
78 By default, the testsuite exercises the GDB in the build directory,
79 but you can set GDB to be a pathname to a different version. For
82 make check RUNTESTFLAGS=GDB=/usr/bin/gdb
84 runs the testsuite on the GDB in /usr/bin.
88 You can set GDBSERVER to be a particular GDBserver of interest, so for
91 make check RUNTESTFLAGS="GDB=/usr/bin/gdb GDBSERVER=/usr/bin/gdbserver"
93 checks both the installed GDB and GDBserver.
97 Command line options passed to all GDB invocations.
99 The default is "-nw -nx".
101 `-nw' disables any of the windowed interfaces.
102 `-nx' disables ~/.gdbinit, so that it doesn't interfere with
105 This is actually considered an internal variable, and you
106 won't normally want to change it. However, in some situations,
107 this may be tweaked as a last resort if the testsuite doesn't
108 have direct support for the specifics of your environment.
109 The testsuite does not override a value provided by the user.
111 As an example, when testing an installed GDB that has been
112 configured with `--with-system-gdbinit', like by default,
113 you do not want ~/.gdbinit to interfere with tests, but, you
114 may want the system .gdbinit file loaded. As there's no way to
115 ask the testsuite, or GDB, to load the system gdbinit but
116 not ~/.gdbinit, a workaround is then to remove `-nx' from
117 INTERNAL_GDBFLAGS, and point $HOME at a directory without
118 a .gdbinit. For example:
123 GDBSERVER=/usr/bin/gdbserver \
124 INTERNAL_GDBFLAGS=-nw
128 When testing natively (that is, not with a remote host), you can run
129 the GDB test suite in a fully parallel mode. In this mode, each .exp
130 file runs separately and maybe simultaneously. The test suite will
131 ensure that all the temporary files created by the test suite do not
132 clash, by putting them into separate directories. This mode is
133 primarily intended for use by the Makefile.
135 To use this mode, set the GDB_PARALLEL on the runtest command line.
136 Before starting the tests, you must ensure that the directories cache,
137 outputs, and temp in the test suite build directory are either empty
138 or have been deleted. cache in particular is used to share data
139 across invocations of runtest, and files there may affect the test
140 results. Note that the Makefile automatically does these deletions.
144 For debugging parallel mode, it is handy to be able to see when a test
145 case writes to a file outside of its designated output directory.
147 If you have the inotify-tools package installed, you can set the
148 GDB_INOTIFY variable on the runtest command line. This will cause the
149 test suite to watch for parallel-unsafe file creations and report
150 them, both to stdout and in the test suite log file.
152 This setting is only meaningful in conjunction with GDB_PARALLEL.
156 This variable is used to specify which set of tests to run.
157 It is passed to make (not runtest) and its contents are a space separated
158 list of tests to run.
160 If using GNU make then the contents are wildcard-expanded using
161 GNU make's $(wildcard) function. Test paths must be fully specified,
162 relative to the "testsuite" subdirectory. This allows one to run all
163 tests in a subdirectory by passing "gdb.subdir/*.exp".
164 If for some strange reason one wanted to run all tests that begin with
165 the letter "d" that is also possible: TESTS="*/d*.exp".
167 Do not write */*.exp to specify all tests (assuming all tests are only
168 nested one level deep, which is not necessarily true). This will pick up
169 .exp files in ancillary directories like "lib" and "config".
170 Instead write gdb.*/*.exp.
174 make -j10 check TESTS="gdb.server/[s-w]*.exp */x*.exp"
176 If not using GNU make then the value is passed directly to runtest.
177 If not specified, all tests are run.
179 Testsuite Configuration
180 ***********************
182 It is possible to adjust the behavior of the testsuite by defining
183 the global variables listed below, either in a `site.exp' file,
188 Defining this variable changes the default timeout duration used
189 during communication with GDB. More specifically, the global variable
190 used during testing is `timeout', but this variable gets reset to
191 `gdb_test_timeout' at the beginning of each testcase, which ensures
192 that any local change to `timeout' in a testcase does not affect
193 subsequent testcases.
195 This global variable comes in handy when the debugger is slower than
196 normal due to the testing environment, triggering unexpected `TIMEOUT'
197 test failures. Examples include when testing on a remote machine, or
198 against a system where communications are slow.
200 If not specifically defined, this variable gets automatically defined
201 to the same value as `timeout' during the testsuite initialization.
202 The default value of the timeout is defined in the file
203 `testsuite/config/unix.exp' (at least for Unix hosts; board files may
204 have their own values).
208 Defining this variable changes the default timeout duration when tests
209 under gdb.reverse directory are running. Process record and reverse
210 debugging is so slow that its tests have unexpected `TIMEOUT' test
211 failures. This global variable is useful to bump up the value of
212 `timeout' for gdb.reverse tests and doesn't cause any delay where
213 actual failures happen in the rest of the testsuite.
219 DejaGNU includes the concept of a "board file", which specifies
220 testing details for a particular target (which are often bare circuit
221 boards, thus the name).
223 In the GDB testsuite specifically, the board file may include a
224 number of "board settings" that test cases may check before deciding
225 whether to exercise a particular feature. For instance, a board
226 lacking any I/O devices, or perhaps simply having its I/O devices
227 not wired up, should set `noinferiorio'.
229 Here are the supported board settings:
231 gdb,cannot_call_functions
233 The board does not support inferior call, that is, invoking inferior
238 The board supports reverse execution.
240 gdb,no_hardware_watchpoints
242 The board does not support hardware watchpoints.
246 GDB is unable to intercept target file operations in remote and
247 perform them on the host.
251 The board is unable to provide I/O capability to the inferior.
255 A program will not return an exit code or result code (or the value
256 of the result is undefined, and should not be looked at).
260 The board does not support signals.
264 Skip time-consuming tests on the board with slow connection.
268 Skip tests related to floating point.
272 The board supports process record.
277 Commands to send to GDB every time a program is about to be run. The
278 first of these settings defines a single command as a string. The
279 second defines a TCL list of commands being a string each. The commands
280 are sent one by one in a sequence, first from `gdb_init_command', if any,
281 followed by individual commands from `gdb_init_command', if any, in this
286 The location of GDBserver. If GDBserver somewhere other than its
287 default location is used in test, specify the location of GDBserver in
288 this variable. The location is a file name for GDBserver, and may be
289 either absolute or relative to the testsuite subdirectory of the build
294 The location of the in-process agent (used for fast tracepoints and
295 other special tests). If the in-process agent of interest is anywhere
296 other than its default location, set this variable. The location is a
297 filename, and may be either absolute or relative to the testsuite
298 subdirectory of the build directory.
302 GDB does not support argument passing for inferior.
306 The board does not support type long long.
310 The board is running the monitor Cygmon.
314 The tests are running with a GDB stub.
318 Set to true if GDB can assume that letting the program run to end
319 reliably results in program exits being reported as such, as opposed
320 to, e.g., the program ending in an infinite loop or the board
321 crashing/resetting. If not set, this defaults to $use_gdb_stub. In
322 other words, native targets are assumed reliable by default, and
323 remote stubs assumed unreliable.
327 The predefined trace state variables the board has.
330 Testsuite Organization
331 **********************
333 The testsuite is entirely contained in `gdb/testsuite'. The main
334 directory of the testsuite includes some makefiles and configury, but
335 these are minimal, and used for little besides cleaning up, since the
336 tests themselves handle the compilation of the programs that GDB will
339 The file `testsuite/lib/gdb.exp' contains common utility procs useful
340 for all GDB tests, while the directory testsuite/config contains
341 configuration-specific files, typically used for special-purpose
342 definitions of procs like `gdb_load' and `gdb_start'.
344 The tests themselves are to be found in directories named
345 'testsuite/gdb.* and subdirectories of those. The names of the test
346 files must always end with ".exp". DejaGNU collects the test files by
347 wildcarding in the test directories, so both subdirectories and
348 individual files typically get chosen and run in alphabetical order.
350 The following lists some notable types of subdirectories and what they
351 are for. Since DejaGNU finds test files no matter where they are
352 located, and since each test file sets up its own compilation and
353 execution environment, this organization is simply for convenience and
358 This is the base testsuite. The tests in it should apply to all
359 configurations of GDB (but generic native-only tests may live here).
360 The test programs should be in the subset of C that is both valid
365 Language-specific tests for any language besides C. Examples are
366 gdb.cp for C++ and gdb.java for Java.
370 Non-portable tests. The tests are specific to a specific
371 configuration (host or target), such as HP-UX or eCos. Example is
376 Architecture-specific tests that are (usually) cross-platform.
380 Tests that exercise a specific GDB subsystem in more depth. For
381 instance, gdb.disasm exercises various disassemblers, while
382 gdb.stabs tests pathways through the stabs symbol reader.
386 GDB performance tests.
391 In many areas, the GDB tests are already quite comprehensive; you
392 should be able to copy existing tests to handle new cases. Be aware
393 that older tests may use obsolete practices but have not yet been
396 You should try to use `gdb_test' whenever possible, since it includes
397 cases to handle all the unexpected errors that might happen. However,
398 it doesn't cost anything to add new test procedures; for instance,
399 gdb.base/exprs.exp defines a `test_expr' that calls `gdb_test'
402 Only use `send_gdb' and `gdb_expect' when absolutely necessary. Even
403 if GDB has several valid responses to a command, you can use
404 `gdb_test_multiple'. Like `gdb_test', `gdb_test_multiple' recognizes
405 internal errors and unexpected prompts.
407 Do not write tests which expect a literal tab character from GDB. On
408 some operating systems (e.g. OpenBSD) the TTY layer expands tabs to
409 spaces, so by the time GDB's output reaches `expect' the tab is gone.
411 The source language programs do *not* need to be in a consistent
412 style. Since GDB is used to debug programs written in many different
413 styles, it's worth having a mix of styles in the testsuite; for
414 instance, some GDB bugs involving the display of source lines might
415 never manifest themselves if the test programs used GNU coding style
418 Some testcase results need more detailed explanation:
422 Use KFAIL for known problem of GDB itself. You must specify the GDB
423 bug report number, as in these sample tests:
425 kfail "gdb/13392" "continue to marker 2"
429 setup_kfail gdb/13392 "*-*-*"
430 kfail "continue to marker 2"
435 Short for "expected failure", this indicates a known problem with the
436 environment. This could include limitations of the operating system,
437 compiler version, and other components.
439 This example from gdb.base/attach-pie-misread.exp is a sanity check
440 for the target environment:
442 # On x86_64 it is commonly about 4MB.
443 if {$stub_size > 25000000} {
444 xfail "stub size $stub_size is too large"
448 You should provide bug report number for the failing component of the
449 environment, if such bug report is available, as with this example
450 referring to a GCC problem:
452 if {[test_compiler_info {gcc-[0-3]-*}]
453 || [test_compiler_info {gcc-4-[0-5]-*}]} {
454 setup_xfail "gcc/46955" *-*-*
456 gdb_test "python print ttype.template_argument(2)" "&C::c"
458 Note that it is also acceptable, and often preferable, to avoid
459 running the test at all. This is the better option if the limitation
460 is intrinsic to the environment, rather than a bug expected to be
461 fixed in the near future.