[RFA] doc addition to gdbint.texinfo

[RFA] doc addition to gdbint.texinfo

[Doug Evans]

Hi.

The Testsuite section of gdbint.texinfo is missing docs on at least
two more DejaGnu variables that are available to be overridden:
GDB, GDBSERVER.

Since there's at least three of them (those two plus TRANSCRIPT),
with more to come, it seemed appropriate to create a new section to
document them all.

Ok to check in?

2010-02-04  Doug Evans  <dje@google.com>

	* gdbint.texinfo (Testsuite): Add a new section to document the
	various DejaGnu variables that may be overridden.

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.316
diff -u -p -r1.316 gdbint.texinfo
--- gdbint.texinfo	1 Jan 2010 11:38:33 -0000	1.316
+++ gdbint.texinfo	4 Feb 2010 21:32:09 -0000
@@ -7599,6 +7599,14 @@ will give a result of ``UNRESOLVED'', li
 UNRESOLVED: gdb.base/example.exp: This test script does not work on a remote host.
 @end smallexample
 
+@section Testsuite Parameters
+
+Several variables exist to modify the behavior of the testsuite.
+
+@itemize @bullet
+
+@item TRANSCRIPT
+
 Sometimes it is convenient to get a transcript of the commands which
 the testsuite sends to @value{GDBN}.  For example, if @value{GDBN}
 crashes during testing, a transcript can be used to more easily
@@ -7620,6 +7628,44 @@ make check RUNTESTFLAGS=TRANSCRIPT=y
 Note that the transcript is not always complete.  In particular, tests
 of completion can yield partial command lines.
 
+@item GDB
+
+Sometimes one wishes to test a different @value{GDBN} than the one in the build
+directory.  For example, one may wish to run the testsuite on
+@file{/usr/bin/gdb}.
+
+@smallexample
+make check RUNTESTFLAGS=GDB=/usr/bin/gdb
+@end smallexample
+
+@item GDBSERVER
+
+When testing a different @value{GDBN}, it is often useful to also test a
+different gdbserver.
+
+@smallexample
+make check RUNTESTFLAGS="GDB=/usr/bin/gdb GDBSERVER=/usr/bin/gdbserver"
+@end smallexample
+
+@end itemize
+
+There are two ways to run the testsuite and pass additional parameters
+to DejaGnu.  The first is with @kbd{make check} and specifying the
+makefile variable @samp{RUNTESTFLAGS}.
+
+@smallexample
+make check RUNTESTFLAGS=TRANSCRIPT=y
+@end smallexample
+
+The second is to cd to the @file{testsuite} directory and invoke the DejaGnu
+@kbd{runtest} command directly.
+
+@smallexample
+cd testsuite
+make site.exp
+runtest TRANSCRIPT=y
+@end smallexample
+
 @section Testsuite Organization
 
 @cindex test suite organization

Re: [RFA] doc addition to gdbint.texinfo

[Eli Zaretskii]

> Date: Thu,  4 Feb 2010 13:37:09 -0800 (PST)
> From: dje@google.com (Doug Evans)
> 
> The Testsuite section of gdbint.texinfo is missing docs on at least
> two more DejaGnu variables that are available to be overridden:
> GDB, GDBSERVER.
> 
> Since there's at least three of them (those two plus TRANSCRIPT),
> with more to come, it seemed appropriate to create a new section to
> document them all.

I agree.

> Ok to check in?

Yes, after this:

> +Several variables exist to modify the behavior of the testsuite.
> +
> +@itemize @bullet
> +
> +@item TRANSCRIPT

Please give each variable the @code markup.

> +@smallexample
> +make check RUNTESTFLAGS="GDB=/usr/bin/gdb GDBSERVER=/usr/bin/gdbserver"
> +@end smallexample

Did you try to "make pdf"?  I suspect that this line is too long and
will overflow the right margin.  If it does, please break it into two
(and tell in the text that it is just one long line).

> +The second is to cd to the @file{testsuite} directory and invoke the DejaGnu
> +@kbd{runtest} command directly.

In this context, "runtest" is a name of a command, not a command line
typed at the keyboard.  So @command will be more appropriate than @kbd
here.

OK with these changes.

Thanks.

Re: [RFA] doc addition to gdbint.texinfo

[Doug Evans]

On Thu, Feb 4, 2010 at 2:20 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Thu,  4 Feb 2010 13:37:09 -0800 (PST)
>> From: dje@google.com (Doug Evans)
>>
>> The Testsuite section of gdbint.texinfo is missing docs on at least
>> two more DejaGnu variables that are available to be overridden:
>> GDB, GDBSERVER.
>>
>> Since there's at least three of them (those two plus TRANSCRIPT),
>> with more to come, it seemed appropriate to create a new section to
>> document them all.
>
> I agree.
>
>> Ok to check in?
>
> Yes, after this:
>
>> +Several variables exist to modify the behavior of the testsuite.
>> +
>> +@itemize @bullet
>> +
>> +@item TRANSCRIPT
>
> Please give each variable the @code markup.
>
>> +@smallexample
>> +make check RUNTESTFLAGS="GDB=/usr/bin/gdb GDBSERVER=/usr/bin/gdbserver"
>> +@end smallexample
>
> Did you try to "make pdf"?  I suspect that this line is too long and
> will overflow the right margin.  If it does, please break it into two
> (and tell in the text that it is just one long line).
>
>> +The second is to cd to the @file{testsuite} directory and invoke the DejaGnu
>> +@kbd{runtest} command directly.
>
> In this context, "runtest" is a name of a command, not a command line
> typed at the keyboard.  So @command will be more appropriate than @kbd
> here.
>
> OK with these changes.
>
> Thanks.
>

Thanks.  I just checked and the line wasn't too long, and I made the
other requested changes.