diff options
Diffstat (limited to 'doc/dejagnu.texi')
| -rw-r--r-- | doc/dejagnu.texi | 57 |
1 files changed, 49 insertions, 8 deletions
diff --git a/doc/dejagnu.texi b/doc/dejagnu.texi index 524454f..887891e 100644 --- a/doc/dejagnu.texi +++ b/doc/dejagnu.texi @@ -54,8 +54,10 @@ Free Documentation License''. * Extending DejaGnu:: * Unit testing:: * Reference:: +* GNU Free Documentation License:: * Concept Index:: * Procedure Index:: +* Variable Index:: @detailmenu @@ -231,6 +233,7 @@ The user-visible utility procedure @code{unsetenv} is @node Design goals, A POSIX Conforming Test Framework, Release Notes, Introduction @section Design goals +@cindex design goals DejaGnu grew out of the internal needs of Cygnus Solutions (formerly Cygnus Support). Cygnus maintained and enhanced a variety of free @@ -275,8 +278,9 @@ it. Currently DejaGnu can use @code{ssh}, @code{rsh}, @code{rlogin}, @node A POSIX Conforming Test Framework, Installation, Design goals, Introduction @section A POSIX compliant test framework - +@cindex POSIX compliant test framework @cindex POSIX 1003.3 + DejaGnu conforms to the POSIX 1003.3 standard for test frameworks. Rob Savoye was a member of that committee. @@ -549,6 +553,7 @@ An informational message about the test case. @node Invoking runtest, Common Operations, Output States, Runtest @subsection Invoking runtest +@cindex runtest, invoking This is the full set of command line options that @code{runtest} recognizes. Option names may be abbreviated to the shortest unique @@ -746,6 +751,7 @@ DejaGnu @emph{Makefile}; their values are captured in the @node Common Operations, , Invoking runtest, Runtest @subsection Common Options +@cindex options, common Typically, you don't need to use any command line options. The @code{--tool} option is only required when there is more than one @@ -788,7 +794,6 @@ a more detailed explanation of each @code{runtest} option. @node Output Files, , Runtest, Running tests @section Output files -@cindex output files DejaGnu always writes two kinds of output files. Summary output is written to the @file{.sum} file, and detailed output is written to the @@ -806,6 +811,7 @@ available. Each of these will be described in turn. @node Summary log file, Detailed log file, , Output Files @subsection Summary log file +@cindex output file, summary log DejaGnu always produces a summary (@file{.sum}) output file. This summary lists the names of all test files run. For each test file, one @@ -855,6 +861,7 @@ option to select a different output directory. @node Detailed log file, Debug log file, Summary log file, Output Files @subsection Detailed log file +@cindex output file, detailed log DejaGnu also saves a detailed log file (@file{.log}), showing any output generated by test cases as well as the summary output. For example, @@ -902,6 +909,7 @@ a different output directory. @node Debug log file, , Detailed log file, Output Files @subsection Debug log file +@cindex output file, debug log The @code{runtest} option @code{--debug} creates a file showing the output from Expect in debugging mode. The @file{dbg.log} file is created @@ -996,6 +1004,7 @@ make the actions for fail-safe patterns produce messages starting with @node Customizing DejaGnu, Extending DejaGnu, Running tests, Top @chapter Customizing DejaGnu +@cindex customization The site configuration file, @file{site.exp}, captures configuration-dependent values and propagates them to the DejaGnu test @@ -1048,6 +1057,7 @@ command line. @node Global config file, Local config file, , Customizing DejaGnu @section Global config file +@cindex configuration file, global The global configuration file is where all the target specific configuration variables for a site are set. For example, a centralized @@ -1108,6 +1118,7 @@ compiler testing. @node Local config file, Board config file, Global config file, Customizing DejaGnu @section Local config file +@cindex configuration file, local It is usually more convenient to keep these @emph{manual overrides} in the @file{site.exp} local to each test directory, rather than in the @@ -1182,6 +1193,7 @@ test cases, the CXXFLAGS and LDFLAGS are supplied by DejaGnu itself for cross testing, but to test a compiler, GCC needs to manipulate these itself. +@vindex test_timeout The local @file{site.exp} may also set Tcl variables such as @code{test_timeout} which can control the amount of time (in seconds) to wait for a remote test to complete. If not specified, @@ -1189,6 +1201,7 @@ wait for a remote test to complete. If not specified, @node Board config file, Remote host testing, Local config file, Customizing DejaGnu @section Board configuration file +@cindex configuration file, board The board configuration file is where board-specific configuration details are stored. A board configuration file contains all the @@ -1272,6 +1285,7 @@ library for embedded systems comprising of non-GPL'd code @node Remote host testing, Config file values, Board config file, Customizing DejaGnu @section Remote host testing +@cindex testing on remote hosts DejaGnu also supports running the tests on a remote host. To set this up, the remote host needs an FTP server, and a telnet server. Currently @@ -1380,7 +1394,9 @@ your local configuration. The -v's are optional. @node Config file values, , Remote host testing, Customizing DejaGnu @section Config file values +@cindex configuration values +@vindex target_info DejaGnu uses a Tcl associative array to hold all the info for each machine. In the case of a Canadian cross, this means host information as well as target information. The named array is called @@ -1507,6 +1523,8 @@ as rsh is mostly used to test Unix machines within a local network. @node Extending DejaGnu, Unit testing, Customizing DejaGnu, Top @chapter Extending DejaGnu +@cindex extensions +@cindex extending DejaGnu @menu * Adding a new testsuite:: @@ -1522,6 +1540,7 @@ as rsh is mostly used to test Unix machines within a local network. @node Adding a new testsuite, Adding a new tool, , Extending DejaGnu @section Adding a new testsuite +@cindex adding, testsuite The testsuite for a new tool should always be located in that tools source directory. DejaGnu require the directory be named @@ -1704,6 +1723,7 @@ also write a real version routine soon. @node Adding a new target, Adding a new board, Adding a new tool, Extending DejaGnu @section Adding a new target +@cindex adding, target DejaGnu has some additional requirements for target support, beyond the general-purpose provisions of a @code{configure} script. DejaGnu must @@ -1739,6 +1759,7 @@ connected. @node Adding a new board, Board file values, Adding a new target, Extending DejaGnu @section Adding a new board +@cindex adding, board Adding a new board consists of creating a new board configuration file. Examples are in @file{dejagnu/baseboards}. Usually to make a new @@ -1983,7 +2004,8 @@ existing GDB tests, for reporting purposes. Thereafter, new GDB tests built up a family of Tcl procedures specialized for GDB testing. @subsection Hints on writing a test case -@cindex Hints on writing a test case +@cindex hints on writing a test case +@cindex test cases, writing It is safest to write patterns that match all the output generated by the tested program; this is called closure. If a pattern does not match @@ -2035,6 +2057,7 @@ procedures @code{error} or @code{warning}. @node Debugging a test case, Adding a test case to a testsuite, Writing a test case, Extending DejaGnu @section Debugging a test case +@cindex test cases, debugging These are the kinds of debugging information available from DejaGnu: @@ -2081,6 +2104,7 @@ file and, if @code{--debug} is given, to @file{dbg.log}. @node Adding a test case to a testsuite, Test case variables, Debugging a test case, Extending DejaGnu @section Adding a test case to a testsuite +@cindex test cases, adding There are two slightly different ways to add a test case. One is to add the test case to an existing directory. The other is to create a new @@ -2117,28 +2141,34 @@ changed. @table @code @item $prms_id +@vindex prms_id The bug tracking system (eg. PRMS/GNATS) number identifying a corresponding bug report (@emph{0} if you do not specify it). @item $bug_id +@vindex bug_id An optional bug ID, perhaps a bug identification number from another organization (@emph{0} if you do not specify it). @item $subdir +@vindex subdir The subdirectory for the current test case. @item $exec_output +@vindex exec_output This is the output from a @code{$@{tool@}_load} command. This only applies to tools like GCC and GAS which produce an object file that must in turn be executed to complete a test. @item $comp_output +@vindex comp_output This is the output from a @code{$@{tool@}_start} command. This is conventionally used for batch-oriented programs, like GCC and GAS, that may produce interesting output (warnings, errors) without further interaction. @item $expect_out(buffer) +@vindex expect_out(buffer) The output from the last command. This is an internal variable set by Expect. More information can be found in the Expect manual. @end table @@ -2155,7 +2185,7 @@ Expect. More information can be found in the Expect manual. @node What is unit testing?, The dejagnu_h header file, , Unit testing @section What is unit testing? -@cindex Unit testing +@cindex unit testing Most regression testing as done by DejaGnu is system testing: the complete application is tested all at once. Unit testing is for testing @@ -2171,6 +2201,7 @@ the testcase can also function as a compliance test. @node The dejagnu_h header file, C unit testing API, What is unit testing?, Unit testing @section The dejagnu.h header file +@cindex dejagnu.h header DejaGnu uses a single header file, @file{dejagnu.h} to assist in unit testing. As this file also produces its one test state output, it can be @@ -2183,6 +2214,7 @@ the output messages, and then merge them into DejaGnu's. @node C unit testing API, C++ unit testing API, The dejagnu_h header file, Unit testing @section C unit testing API +@cindex C unit testing API All of the functions that take a @code{msg} parameter use a C @code{char *} that is the message to be displayed. There currently is no support @@ -2232,6 +2264,7 @@ outputs. @node C++ unit testing API, , C unit testing API, Unit testing @section C++ unit testing API +@cindex C++ unit testing API All of the methods that take a @code{msg} parameter use a C char * or STL string, that is the message to be displayed. There currently is no @@ -2278,8 +2311,8 @@ outputs. @end itemize -@node Reference, , Unit testing, Top -@chapter Reference +@node Reference, GNU Free Documentation License, Unit testing, Top +@appendix Framework reference @menu * Builtin Procedures:: @@ -5392,14 +5425,22 @@ This makes runtest exit. It is abbreviated as @emph{q}. @item @code{} @end table -@node Concept Index +@node GNU Free Documentation License, Reference, Concept Index, Top +@appendix GNU Free Documentation License +@include fdl.texi + +@node Concept Index, GNU Free Documentation License, Procedure Index, Top @unnumbered Concept Index @printindex cp -@node Procedure Index +@node Procedure Index, Concept Index, Variable Index, Top @unnumbered Procedure Index @printindex fn +@node Variable Index, Procedure Index, , Top +@unnumbered Variable Index +@printindex vr + @bye @c LocalWords: subdirectory |