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.
155 Testsuite Configuration
156 ***********************
158 It is possible to adjust the behavior of the testsuite by defining
159 the global variables listed below, either in a `site.exp' file,
164 Defining this variable changes the default timeout duration used
165 during communication with GDB. More specifically, the global variable
166 used during testing is `timeout', but this variable gets reset to
167 `gdb_test_timeout' at the beginning of each testcase, which ensures
168 that any local change to `timeout' in a testcase does not affect
169 subsequent testcases.
171 This global variable comes in handy when the debugger is slower than
172 normal due to the testing environment, triggering unexpected `TIMEOUT'
173 test failures. Examples include when testing on a remote machine, or
174 against a system where communications are slow.
176 If not specifically defined, this variable gets automatically defined
177 to the same value as `timeout' during the testsuite initialization.
178 The default value of the timeout is defined in the file
179 `testsuite/config/unix.exp' (at least for Unix hosts; board files may
180 have their own values).
186 DejaGNU includes the concept of a "board file", which specifies
187 testing details for a particular target (which are often bare circuit
188 boards, thus the name).
190 In the GDB testsuite specifically, the board file may include a
191 number of "board settings" that test cases may check before deciding
192 whether to exercise a particular feature. For instance, a board
193 lacking any I/O devices, or perhaps simply having its I/O devices
194 not wired up, should set `noinferiorio'.
196 Here are the supported board settings:
198 gdb,cannot_call_functions
200 The board does not support inferior call, that is, invoking inferior
205 The board supports reverse execution.
207 gdb,no_hardware_watchpoints
209 The board does not support hardware watchpoints.
213 GDB is unable to intercept target file operations in remote and
214 perform them on the host.
218 The board is unable to provide I/O capability to the inferior.
222 A program will not return an exit code or result code (or the value
223 of the result is undefined, and should not be looked at).
227 The board does not support signals.
231 Skip time-consuming tests on the board with slow connection.
235 Skip tests related to floating point.
239 The board supports process record.
243 The location of GDBserver. If GDBserver somewhere other than its
244 default location is used in test, specify the location of GDBserver in
245 this variable. The location is a file name for GDBserver, and may be
246 either absolute or relative to the testsuite subdirectory of the build
251 The location of the in-process agent (used for fast tracepoints and
252 other special tests). If the in-process agent of interest is anywhere
253 other than its default location, set this variable. The location is a
254 filename, and may be either absolute or relative to the testsuite
255 subdirectory of the build directory.
259 GDB does not support argument passing for inferior.
263 The board does not support type long long.
267 The board is running the monitor Cygmon.
271 The tests are running with a GDB stub.
275 Set to true if GDB can assume that letting the program run to end
276 reliably results in program exits being reported as such, as opposed
277 to, e.g., the program ending in an infinite loop or the board
278 crashing/resetting. If not set, this defaults to $use_gdb_stub. In
279 other words, native targets are assumed reliable by default, and
280 remote stubs assumed unreliable.
284 The predefined trace state variables the board has.
287 Testsuite Organization
288 **********************
290 The testsuite is entirely contained in `gdb/testsuite'. The main
291 directory of the testsuite includes some makefiles and configury, but
292 these are minimal, and used for little besides cleaning up, since the
293 tests themselves handle the compilation of the programs that GDB will
296 The file `testsuite/lib/gdb.exp' contains common utility procs useful
297 for all GDB tests, while the directory testsuite/config contains
298 configuration-specific files, typically used for special-purpose
299 definitions of procs like `gdb_load' and `gdb_start'.
301 The tests themselves are to be found in directories named
302 'testsuite/gdb.* and subdirectories of those. The names of the test
303 files must always end with ".exp". DejaGNU collects the test files by
304 wildcarding in the test directories, so both subdirectories and
305 individual files typically get chosen and run in alphabetical order.
307 The following lists some notable types of subdirectories and what they
308 are for. Since DejaGNU finds test files no matter where they are
309 located, and since each test file sets up its own compilation and
310 execution environment, this organization is simply for convenience and
315 This is the base testsuite. The tests in it should apply to all
316 configurations of GDB (but generic native-only tests may live here).
317 The test programs should be in the subset of C that is both valid
322 Language-specific tests for any language besides C. Examples are
323 gdb.cp for C++ and gdb.java for Java.
327 Non-portable tests. The tests are specific to a specific
328 configuration (host or target), such as HP-UX or eCos. Example is
333 Architecture-specific tests that are (usually) cross-platform.
337 Tests that exercise a specific GDB subsystem in more depth. For
338 instance, gdb.disasm exercises various disassemblers, while
339 gdb.stabs tests pathways through the stabs symbol reader.
343 GDB performance tests.
348 In many areas, the GDB tests are already quite comprehensive; you
349 should be able to copy existing tests to handle new cases. Be aware
350 that older tests may use obsolete practices but have not yet been
353 You should try to use `gdb_test' whenever possible, since it includes
354 cases to handle all the unexpected errors that might happen. However,
355 it doesn't cost anything to add new test procedures; for instance,
356 gdb.base/exprs.exp defines a `test_expr' that calls `gdb_test'
359 Only use `send_gdb' and `gdb_expect' when absolutely necessary. Even
360 if GDB has several valid responses to a command, you can use
361 `gdb_test_multiple'. Like `gdb_test', `gdb_test_multiple' recognizes
362 internal errors and unexpected prompts.
364 Do not write tests which expect a literal tab character from GDB. On
365 some operating systems (e.g. OpenBSD) the TTY layer expands tabs to
366 spaces, so by the time GDB's output reaches `expect' the tab is gone.
368 The source language programs do *not* need to be in a consistent
369 style. Since GDB is used to debug programs written in many different
370 styles, it's worth having a mix of styles in the testsuite; for
371 instance, some GDB bugs involving the display of source lines might
372 never manifest themselves if the test programs used GNU coding style
375 Some testcase results need more detailed explanation:
379 Use KFAIL for known problem of GDB itself. You must specify the GDB
380 bug report number, as in these sample tests:
382 kfail "gdb/13392" "continue to marker 2"
386 setup_kfail gdb/13392 "*-*-*"
387 kfail "continue to marker 2"
392 Short for "expected failure", this indicates a known problem with the
393 environment. This could include limitations of the operating system,
394 compiler version, and other components.
396 This example from gdb.base/attach-pie-misread.exp is a sanity check
397 for the target environment:
399 # On x86_64 it is commonly about 4MB.
400 if {$stub_size > 25000000} {
401 xfail "stub size $stub_size is too large"
405 You should provide bug report number for the failing component of the
406 environment, if such bug report is available, as with this example
407 referring to a GCC problem:
409 if {[test_compiler_info {gcc-[0-3]-*}]
410 || [test_compiler_info {gcc-4-[0-5]-*}]} {
411 setup_xfail "gcc/46955" *-*-*
413 gdb_test "python print ttype.template_argument(2)" "&C::c"
415 Note that it is also acceptable, and often preferable, to avoid
416 running the test at all. This is the better option if the limitation
417 is intrinsic to the environment, rather than a bug expected to be
418 fixed in the near future.