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

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

[Joel Brobecker]

Hello,

This patch documents a new testsuite variable introduced to allow
the user to configure the timeout duration used while running
the testsuite.

    http://www.sourceware.org/ml/gdb-patches/2010-02/msg00101.html

gdb/doc/ChangeLog:

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

This patch was tested on x86_64-linux by rebuilding the PDF, PS and
HTML documentation.

OK to apply?

Thanks,
-- 
Joel

---
 gdb/doc/gdbint.texinfo |   28 ++++++++++++++++++++++++++++
 1 files changed, 28 insertions(+), 0 deletions(-)

diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
index c90af05..b97d0e1 100644
--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -7693,6 +7693,34 @@ make site.exp
 runtest TRANSCRIPT=y
 @end smallexample
 
+@section 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 @code{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.
+
+If not specifically defined, this variable gets automatically defined
+to the same value as @code{timeout} during the testsuite initialization
+(the actual value depends on the exact running parameters).
+
+This global variable is usually used when the debugger is slower than
+normal due to the testing environment, triggering unexpected @code{TIMEOUT}
+test failures.  For instance, when testing on a remote machine, or against
+a system where communications are slow.
+
+@end itemize
+
 @section Testsuite Organization
 
 @cindex test suite organization
-- 
1.6.3.3

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

[Eli Zaretskii]

> From: Joel Brobecker <brobecker@adacore.com>
> Date: Mon,  8 Feb 2010 16:17:32 +0400
> 
> This patch documents a new testsuite variable introduced to allow
> the user to configure the timeout duration used while running
> the testsuite.
> 
>     http://www.sourceware.org/ml/gdb-patches/2010-02/msg00101.html
> 
> gdb/doc/ChangeLog:
> 
>         * gdbint.texinfo (Testsuite): New section "Testsuite Configuration",
>         documenting the gdb_test_timeout variable.

Thanks.

> +@section Testsuite Configuration

It's usually a good idea to put a @cindex entry with the same text as
the name of the section (with all words lower-cased) right after the
section header.  That is because most section names introduce a topic,
and users looking for that info will likely think about that topic as
well.

> +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 @code{board} file.

Why "board" is in @code, not in @file?  Isn't it a file?

> +If not specifically defined, this variable gets automatically defined
> +to the same value as @code{timeout} during the testsuite initialization
> +(the actual value depends on the exact running parameters).

It would be worth saying more about how to find out the default
value.  If I'm a reader of this section, I might ask myself whether I
need to set the variable to a non-default value, but it is impossible
to answer that question without knowing what would be the value if I
don't do anything.

> +This global variable is usually used when the debugger is slower than

"usually used" sounds awkward.  How about "comes in handy"?

> +test failures.  For instance, when testing on a remote machine, or against
> +a system where communications are slow.

The last sentence is not a complete one.  How about

  Examples include testing on a remote ...

?

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

[Joel Brobecker]

> > +If not specifically defined, this variable gets automatically defined
> > +to the same value as @code{timeout} during the testsuite initialization
> > +(the actual value depends on the exact running parameters).
> 
> It would be worth saying more about how to find out the default
> value.  If I'm a reader of this section, I might ask myself whether I
> need to set the variable to a non-default value, but it is impossible
> to answer that question without knowing what would be the value if I
> don't do anything.

The problem is that this is tricky and really depends a lot on whether
the user uses a board file or not, since dejagnu is so configurable
(you should see the list of files that get loaded at startup).  I'm not
even certain that *I* know the entire story: As far as I can tell,
gdb/testsuite/config/unix.exp sets a timeout of 60 seconds.  I don't
think we set the timeout anywhere else.  So that leaves the question
of board files. If the user used board files, then they may or may not
have also set the timeout there.

On the other hand, one easy way to determine the default timeout is
just to add a trace in one testcase that prints it. Crude, but
effective, since this is how I noticed that the default timeout was
not the value that I thought it would be (and hence ended up noticing
the change in unix.exp, only after some heavy grepping).

So what should do we do in this case?  I've fixed all the other nits
that you mentioned, except this... Perhaps we should just refer the user
to the dejagnu documentation somewhere earlier.

-- 
Joel

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

[Eli Zaretskii]

> Date: Tue, 9 Feb 2010 17:10:15 +0400
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org
> 
> > > +If not specifically defined, this variable gets automatically defined
> > > +to the same value as @code{timeout} during the testsuite initialization
> > > +(the actual value depends on the exact running parameters).
> > 
> > It would be worth saying more about how to find out the default
> > value.  If I'm a reader of this section, I might ask myself whether I
> > need to set the variable to a non-default value, but it is impossible
> > to answer that question without knowing what would be the value if I
> > don't do anything.
> 
> The problem is that this is tricky and really depends a lot on whether
> the user uses a board file or not, since dejagnu is so configurable
> (you should see the list of files that get loaded at startup).  I'm not
> even certain that *I* know the entire story: As far as I can tell,
> gdb/testsuite/config/unix.exp sets a timeout of 60 seconds.  I don't
> think we set the timeout anywhere else.  So that leaves the question
> of board files. If the user used board files, then they may or may not
> have also set the timeout there.

How about this?

   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".}.

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

[Joel Brobecker]

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

> How about this?

Works for me! Thanks for the suggestion. Attached is the new version.
I moved up a bit the paragraph explaining why this global variable
might be useful - I felt it was nicer and more natural to have it
before explaining what the default value was, and where to find it.
But I can move it back.

OK to commit this version?

Thanks,
-- 
Joel

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

commit bdb6c0007cdba70be6f48515823368aca6dc8eee
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..7c3fb7e 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 @file{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

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

[Eli Zaretskii]

> Date: Thu, 11 Feb 2010 11:52:23 +0400
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org
> 
> OK to commit this version?

Yes, with just one nit: from this:

> +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:

> +test suite@footnote{If you are using a board file, it could override
> +the test-suite default; search the board file for "timeout".}.

Thanks.

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

[Joel Brobecker]

[-- 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

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

[Eli Zaretskii]

> Date: Fri, 12 Feb 2010 08:49:08 +0400
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org
> 
> 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).

This version is fine with me.  Thanks.

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

[Joel Brobecker]

> > 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).
> 
> This version is fine with me.  Thanks.

Thanks, I just checked it in.

-- 
Joel