List inferiors/threads/pspaces in ascending order

[deliverable/binutils-gdb.git] / gdb / testsuite / README

diff --git a/gdb/testsuite/README b/gdb/testsuite/README
index c17bd3465dedc7a6029166d092f08e280fc3e710..70f65cdafe2662218eae694913867ce01aeb3e38 100644 (file)
--- a/gdb/testsuite/README
+++ b/gdb/testsuite/README
@@ -151,6 +151,73 @@ them, both to stdout and in the test suite log file.
 
 This setting is only meaningful in conjunction with GDB_PARALLEL.
 
+TESTS
+
+This variable is used to specify which set of tests to run.
+It is passed to make (not runtest) and its contents are a space separated
+list of tests to run.
+
+If using GNU make then the contents are wildcard-expanded using
+GNU make's $(wildcard) function.  Test paths must be fully specified,
+relative to the "testsuite" subdirectory.  This allows one to run all
+tests in a subdirectory by passing "gdb.subdir/*.exp", or more simply
+by using the check-gdb.subdir target in the Makefile.
+
+If for some strange reason one wanted to run all tests that begin with
+the letter "d" that is also possible: TESTS="*/d*.exp".
+
+Do not write */*.exp to specify all tests (assuming all tests are only
+nested one level deep, which is not necessarily true).  This will pick up
+.exp files in ancillary directories like "lib" and "config".
+Instead write gdb.*/*.exp.
+
+Example:
+
+       make -j10 check TESTS="gdb.server/[s-w]*.exp */x*.exp"
+
+If not using GNU make then the value is passed directly to runtest.
+If not specified, all tests are run.
+
+READ1
+
+This make (not runtest) variable is used to specify whether the
+testsuite preloads the read1.so library into expect.  Any non-empty
+value means true.  See "Race detection" below.
+
+Race detection
+**************
+
+The testsuite includes a mechanism that helps detect test races.
+
+For example, say the program running under expect outputs "abcd", and
+a test does something like this:
+
+  expect {
+    "a.*c" {
+    }
+    "b" {
+    }
+    "a" {
+    }
+  }
+
+Which case happens to match depends on what expect manages to read
+into its internal buffer in one go.  If it manages to read three bytes
+or more, then the first case matches.  If it manages to read two
+bytes, then the second case matches.  If it manages to read only one
+byte, then the third case matches.
+
+To help detect these cases, the race detection mechanism preloads a
+library into expect that forces the `read' system call to always
+return at most 1 byte.
+
+To enable this, either pass a non-empty value in the READ1 make
+variable, or use the check-read1 make target instead of check.
+
+Examples:
+
+       make -j10 check-read1 TESTS="*/paginate-*.exp"
+       make -j10 check READ1="1"
 
 Testsuite Configuration
 ***********************
@@ -179,6 +246,15 @@ The default value of the timeout is defined in the file
 `testsuite/config/unix.exp' (at least for Unix hosts; board files may
 have their own values).
 
+gdb_reverse_timeout
+
+Defining this variable changes the default timeout duration when tests
+under gdb.reverse directory are running.  Process record and reverse
+debugging is so slow that its tests have unexpected `TIMEOUT' test
+failures.  This global variable is useful to bump up the value of
+`timeout' for gdb.reverse tests and doesn't cause any delay where
+actual failures happen in the rest of the testsuite.
+
 
 Board Settings
 **************
@@ -238,6 +314,16 @@ gdb,use_precord
 
   The board supports process record.
 
+gdb_init_command
+gdb_init_commands
+
+  Commands to send to GDB every time a program is about to be run.  The
+  first of these settings defines a single command as a string.  The
+  second defines a TCL list of commands being a string each.  The commands
+  are sent one by one in a sequence, first from `gdb_init_command', if any,
+  followed by individual commands from `gdb_init_command', if any, in this
+  list's order.
+
 gdb_server_prog
 
   The location of GDBserver.  If GDBserver somewhere other than its
@@ -325,8 +411,7 @@ gdb.cp for C++ and gdb.java for Java.
 gdb.<platform>
 
 Non-portable tests.  The tests are specific to a specific
-configuration (host or target), such as HP-UX or eCos.  Example is
-gdb.hp, for HP-UX.
+configuration (host or target), such as eCos.
 
 gdb.arch