Re: [RFA/doco/testsuite] Document new gdb_test_timeout global variable.

[Joel Brobecker <brobecker@adacore.com>]

[-- Attachment #1: Type: text/plain, Size: 1182 bytes --]

> > +It is possible to adjust the behavior of the testsuite by defining
> > +the global variables listed below, either in a @file{site.exp} file,
> > +or in a @file{board} file.
> 
> I learn that "board" is the name of a file, is that right?  If so,
> then please give the @file markup to its 2 other instances, inside the
> @footnote:

Hmmm, that's a good question. As far as my understanding of these things
goes, I think I made a mistake in my text.  The correct terms should
be either a "board file" (no @file markup), because "board" is not the
name of a file.  We could have used "@file{boards} files" with boards
being a reference to the directory where the board files are stored,
but as far as I can tell from the dejagnu documentation, this is just
a convention at best - this seems to be something entirely configurable
although the dejagnu documentation is quite vague about it (I couldn't
find a single line of text explaining the significance of this directory
or how dejagnu even locates it - using "boards_dir"?).

I think "board file" is what we should use.  Attached is the revised
version (the only change was to remove the one @file markup for board).

-- 
Joel

[-- Attachment #2: gdb-test-timeout-doco.diff --]
[-- Type: text/x-diff, Size: 2004 bytes --]

commit 7191e16411c47b0df2eb8ec051dcb725795fcb89
Author: Joel Brobecker <brobecker@adacore.com>
Date:   Mon Feb 8 16:11:28 2010 +0400

[testsuite] Document new gdb_test_timeout global variable.

gdb/doc/ChangeLog:

        * gdbint.texinfo (Testsuite): New section "Testsuite Configuration",
        documenting the gdb_test_timeout variable.

diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
index c90af05..7741855 100644
--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -7693,6 +7693,38 @@ make site.exp
 runtest TRANSCRIPT=y
 @end smallexample
 
+@section Testsuite Configuration
+@cindex Testsuite Configuration
+
+It is possible to adjust the behavior of the testsuite by defining
+the global variables listed below, either in a @file{site.exp} file,
+or in a board file.
+
+@itemize @bullet
+
+@item @code{gdb_test_timeout}
+
+Defining this variable changes the default timeout duration used during
+communication with @value{GDBN}.  More specifically, the global variable
+used during testing is @code{timeout}, but this variable gets reset to
+@code{gdb_test_timeout} at the beginning of each testcase, making sure
+that any local change to @code{timeout} in a testcase does not affect
+subsequent testcases.
+
+This global variable comes in handy when the debugger is slower than
+normal due to the testing environment, triggering unexpected @code{TIMEOUT}
+test failures.  Examples include when testing on a remote machine, or
+against a system where communications are slow.
+
+If not specifically defined, this variable gets automatically defined
+to the same value as @code{timeout} during the testsuite initialization.
+The default value of the timeout is defined in the file
+@file{gdb/testsuite/config/unix.exp} that is part of the @value{GDBN}
+test suite@footnote{If you are using a board file, it could override
+the test-suite default; search the board file for "timeout".}.
+
+@end itemize
+
 @section Testsuite Organization
 
 @cindex test suite organization