-\input texinfo @c -*- Texinfo -*-
-@finalout
+\input texinfo
@setfilename dejagnu.info
-@c
-@c This file documents the GNU Testing Framework ``DejaGnu''
-@c
-@c Copyright (C) 92 - 2000, 2001 Free Software Foundation, Inc.
-@c
-@c This text may be freely distributed under the terms of the GNU
-@c General Public License.
-@c
-
-@c FIXME---MAIN TODO LIST!
-@c
-@c * Revisit organization.
-@c
-@c * discuss Tcl/expect basics---enough to get started (see seminar notes).
-@c Maybe this would permit abbreviating appendices.
-
-@ifinfo
-@format
-START-INFO-DIR-ENTRY
-* DejaGnu: (dejagnu). The GNU testing framework.
-END-INFO-DIR-ENTRY
-@end format
-@end ifinfo
-
-@syncodeindex ky cp
-@syncodeindex fn cp
-
-@setchapternewpage odd
-@settitle DejaGnu Testing Framework
-@titlepage
-@title The DejaGnu Testing Framework
-@subtitle for DejaGnu Version 1.3
-@sp 1
-@subtitle Jan 1996
-@author Rob Savoye
-@page
-
-@tex
-{\parskip=0pt \hfill Cygnus Support}
-@end tex
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
+@documentencoding us-ascii
+@direntry
+* DejaGnu: . ???
+@end direntry
-@noindent
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that
-the entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
+@node Top, Abstract, , (dir)
+@top DejaGnu
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
-@end titlepage
+@menu
+* Abstract::
+* Overview::
+* Getting DejaGnu up and running::
+* Running Tests::
+* Customizing DejaGnu::
+* Extending DejaGnu::
+* Unit Testing::
+* Reference::
+* Unit Testing API::
-@ifinfo
-Copyright @copyright{} 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software Foundation, Inc.
+@detailmenu
+--- The Detailed Node Listing ---
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
+Overview
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries a copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-@end ignore
+* What is DejaGnu ?::
+* What_s New In This Release: Release Notes.
+* Design Goals::
+* A POSIX conforming test framework: A POSIX Conforming Test Framework.
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that
-the entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
+Getting DejaGnu up and running
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
+* Test your installation::
+* Create a minimal project; e_g_ calc::
+* Our first automated tests::
+* A first remote test::
-@node Top
+Running Tests
-@top DejaGnu
+* Make check: Make Check.
+* Runtest::
+* The files DejaGnu produces_: Output Files.
-DejaGnu is a framework for running test suites on software tools.
+Customizing DejaGnu
-This file describes version 1.3 of DejaGnu.
+* Local Config File::
+* Global Config File::
+* Board Config File::
+* Remote Host Testing::
+* Config File Values::
-@menu
-* Overview:: What is DejaGnu?
-* What is New:: What is new in this release.
-* Invoking runtest:: Using `runtest', the main test driver
-* Customizing:: Setting `runtest' defaults
-* Internals:: The DejaGnu implementation
-* Tests:: How to write a test case
-* Extending:: New tools, new targets, and new hosts
-* Installation:: Configuring and Installing DejaGnu
-* Index:: Index
-@end menu
-@end ifinfo
+Extending DejaGnu
-@iftex
-@raggedbottom
-@end iftex
+* Adding A New Testsuite: Adding a new Testsuite.
+* Adding A New Tool::
+* Adding A New Target::
+* Adding A New Board::
+* Board Config File Values: Board File Values.
+* Writing A Test Case::
+* Debugging A Test Case::
+* Adding A Test Case To A Testsuite_: Adding A Test Case To A Testsuite.
+* Hints On Writing A Test Case::
+* Special variables used by test cases_: Test Case Variables.
-@node Overview
-@chapter What is DejaGnu?
-@cindex overview
+Unit Testing
-DejaGnu is a framework for testing other programs. Its purpose is to
-provide a single front end for all tests. Beyond this, DejaGnu offers
-several advantages for testing:
+* What Is Unit Testing ?::
+* The dejagnu_h Header File::
-@enumerate
-@item
-The flexibility and consistency of the DejaGnu framework make it easy
-to write tests for any program.
+Reference
-@item
-DejaGnu provides a layer of abstraction which allows you to write tests
-that are portable to any host or target where a program must be tested.
- For instance, a test for GDB can run (from any Unix based host) on any
-target architecture that DejaGnu supports. Currently DejaGnu runs tests
-on several single board computers, whose operating software ranges from
-just a boot monitor to a full-fledged, Unix-like realtime OS.
+* Obtaining DejaGnu::
+* Installation::
+* Builtin Procedures::
+* File Map::
-@item
-All tests have the same output format. This makes it easy to integrate
-testing into other software development processes. DejaGnu's output is
-designed to be parsed by other filtering script, and it is also human
-readable.
-@end enumerate
+Unit Testing API
-DejaGnu is written in @code{expect}, which in turn uses @dfn{Tcl}---Tool
-command language.
+* C Unit Testing API::
+* C++ Unit Testing API::
-@cindex @code{expect} script names
-@kindex .exp
-@cindex suffix, @code{expect} scripts
-Running tests requires two things: the testing framework, and the test
-suites themselves. Tests are usually written in @code{expect} using
-Tcl, but you can also use a Tcl script to run a test suite that is not
-based on @code{expect}. (@code{expect} script filenames conventionally
-use @samp{.exp} as a suffix; for example, the main implementation of the
-DejaGnu test driver is in the file @file{runtest.exp}.)
+@end detailmenu
+@end menu
+@node Abstract, Overview, Top, Top
+@chapter Abstract
+
+This document describes the functionality of DejaGnu, the
+testing framework of the GNU project. DejaGnu is written in
+Expect, which uses
+Tcl as a command
+language. Expect acts as a very
+programmable shell. As with other Unix command shells, you can
+run any program, but once the program is started, your test script
+has programmable control over its input and output. This does not
+just apply to the programs under test; @code{expect}
+can also run any auxiliary program, such as
+@code{diff} or @code{sh}, with full
+control over its input and output.
+
+DejaGnu itself is merely a framework for the creation of
+testsuites. Testsuites are distributed with each
+application.
+
+@node Overview, Getting DejaGnu up and running, Abstract, Top
+@chapter Overview
@menu
-* Running Tests:: A first look at running DejaGnu tests
-* Sample Test:: What does a DejaGnu test case look like?
-* Design Goals:: Goals behind DejaGnu
-* Posix:: DejaGnu conforms to POSIX 1003.3
-* Future Directions:: Where is DejaGnu going?
-* Tcl and Expect:: Reading more about Tcl and Expect
+* What is DejaGnu ?::
+* What_s New In This Release: Release Notes.
+* Design Goals::
+* A POSIX conforming test framework: A POSIX Conforming Test Framework.
@end menu
-@node What is New
-@chapter What is new in this release ?
-@cindex What is New
-
-This release has a number of substantial changes over version 1.2. The
-most visible change is that the version of expect and Tcl included in
-the release are up-to-date with the current stable net releases. Other
-changes are:
+@node What is DejaGnu ?, Release Notes, , Overview
+@section What is DejaGnu ?
+
+DejaGnu is a framework for
+testing other programs. Its purpose is to provide a single
+front end for all tests. Think of it as a custom library of
+Tcl procedures crafted to support writing a test harness. A
+@i{Test Harness} is the testing
+infrastructure that is created to support a specific program
+or tool. Each program can have multiple testsuites, all
+supported by a single test harness. DejaGnu is written in
+Expect, which in turn uses
+Tcl -- Tool command
+language. There is more information on Tcl at the @uref{http://www.scriptics.com,Scriptics} web site and the
+Expect web site is at @uref{http://expect.nist.gov,NIST}.
+
+Julia Menapace first coined the term ``DejaGnu'' to describe
+an earlier testing framework at Cygnus Support she had written
+for @code{GDB}. When we replaced it with the
+Expect-based framework, it was like DejaGnu all over again.
+More importantly, it was also named after my daughter, @uref{http://www.welcomehome.org/deja/,Deja Snow Savoye}
+(now 14 years old as of Feb 2004), who was a toddler
+during DejaGnu's beginnings.
+
+DejaGnu offers several advantages for testing:
+
+@itemize @bullet{}
-@enumerate
@item
-@c FIXME: add a link to the config section
-The config sub-system in DejaGnu has been completely redesigned. It now
-supports testing on remote hosts as well as remote targets.
+The flexibility and consistency of the DejaGnu
+framework make it easy to write tests for any program, with
+either batch oriented, or interactive programs.
@item
-More builtin support for building target binaries with the correct
-linker flags. Currently this only works with GCC, preferably with a
-target support by @code{libgloss}.
+DejaGnu provides a layer of abstraction which
+allows you to write tests that are portable to any host or
+target where a program must be tested. For instance, a test
+for @code{GDB} can run from any supported host
+system on any supported target system. DejaGnu runs tests on
+many single board computers, whose operating software ranges
+from a simple boot monitor to a real-time OS.
@item
-Lots of little bug fixes from a year of heavy use here at Cygnus
-Support.
+All tests have the same output format. This
+makes it easy to integrate testing into other software
+development processes. DejaGnu's output is designed to be
+parsed by other filtering script and it is also human
+readable.
@item
-DejaGnu now uses @code{autoconf} for configuration.
+Using Tcl and Expect, it's easy to create wrappers
+for existing testsuites. By incorporating existing tests under
+DejaGnu, it's easier to have a single set of report analyse
+programs..
+@end itemize
-@item
-New test cases for DejaGnu have been added for the new features, plus
-the "--tool" option bug in the 1.2 testsuite has been fixed.
+Running tests requires two things: the testing framework and
+the testsuites themselves. Tests are usually written in
+Expect using Tcl, but you can also use
+a Tcl script to run a testsuite that is not based on
+Expect. Expect
+script filenames conventionally use @i{.exp} as a
+suffix; for example, the main implementation of the DejaGnu test
+driver is in the file
+runtest.exp.)
+
+@node Release Notes, Design Goals, What is DejaGnu ?, Overview
+@section What's New In This Release
+
+This release has a number of substantial changes over version
+1.3. The most visible change is that the version of Expect and Tcl
+included in the release are up-to-date with the current stable net
+releases. The biggest change is years of modifications to the
+target configuration system, used for cross testing. While this
+greatly improved cross testing, is has made that subsystem very
+complicated. The goal is to have this entirely rewritten using
+iTcl by the next release. Other changes
+are:
+
+@itemize @bullet{}
@item
-The @code{--tool} option is now optional.
+More built-in support for building target binaries
+with the correct linker flags. Currently this only works with
+GCC as the cross compiler,
+preferably with a target supported by
+@ref{Libgloss,,Libgloss}..
@item
-@code{runtest} when searching for test drivers ignores all directories
-named SCCS, RCS, and CVS.
+Lots of little bug fixes from years of heavy
+use at Cygnus Solutions.
@item
-There is now a generic keyword based test harness that uses comments in
-source code to control how each test case gets built and run.
+DejaGnu now uses
+Automake for Makefile
+configuration.
@item
-There is now some support for running a testsuite with multiple passes
-and multiple targets.
-
-@end enumerate
-
-@node Running Tests
-@section Running existing tests
-@cindex existing tests, running
-@cindex running tests
-@cindex tests, running
-
-@kindex make check
-To run tests from an existing collection, first use @code{configure} as
-usual to set up the source directory containing the tests. Then try
-running
-
-@example
-make check
-@end example
-
-@cindex @code{check} makefile target
-If the @code{check} target exists, it usually saves you some
-trouble---for instance, it can set up any auxiliary programs or other
-files needed by the tests.
-
-@cindex auxiliary files, building
-Once you have run @samp{make check} to build any auxiliary files, you
-might want to call the test driver @code{runtest} directly to repeat the
-tests. You may also have to call @code{runtest} directly for test
-collections with no @code{check} target in the @file{Makefile}.
-
-@c force page break to avoid losing footnote to another page
-@page
-@cindex @code{runtest}, most common options
-@cindex options for @code{runtest}, common
-Typically, you must use two command-line options: @samp{--tool}, to
-specify which set of tests to run@footnote{@samp{--tool} selects a
-particular suite of tests, @emph{not} the name of the executable program
-to run. @xref{Config Values,,Configuration dependent values}, for
-information on the variables that you can use to specify the names of
-programs to run.}, and @samp{--srcdir}, to specify where to find test
-directories.
-
-For example, if the directory @file{gdb/testsuite} contains a collection
-of DejaGnu tests for @sc{gdb}, you can run them like this:
-
-@example
-eg$ cd gdb/testsuite
-eg$ runtest --tool gdb
-@exdent @emph{Test output follows, ending with:}
-
- === gdb Summary ===
-
-# of expected passes 508
-# of expected failures 103
-/usr/latest/bin/gdb version 4.14.4 -nx
-@end example
-
-You can use the option @samp{--srcdir} to point to some other directory
-containing a collection of tests:
-
-@smallexample
-eg$ runtest --tool gdb --srcdir /devo/gdb/testsuite
-@end smallexample
-
-@cindex native configuration
-@cindex cross configuration
-These examples assume a @dfn{native} configuration, where the same
-computer runs both @code{runtest} and the tests themselves. When you
-have a @dfn{cross} configuration, the tests run on a different computer,
-controlled by the host running @code{runtest}. In this situation, you
-need the option @samp{--name} to specify the network address for the
-other computer:
-
-@smallexample
-eg$ runtest --tool gdb --name vx9.munist.com
-@end smallexample
-
-If you always use the same option values, you can record them in a file
-called @file{site.exp}, rather than typing them each time. @xref{Config
-Values,,Setting defaults for @code{runtest} options}.
-
-By default, @code{runtest} prints only the names of the tests it runs,
-output from any tests that have unexpected results, and a summary
-showing how many tests passed and how many failed. To display output
-from all tests (whether or not they behave as expected), use the
-@samp{--all} option. For more verbose output about processes being run,
-communication, and so on, use @samp{--verbose}. To see even more output,
-use multiple @samp{--verbose} options. @xref{Invoking runtest,,Using
-@code{runtest}}, for a more detailed explanation of each @code{runtest}
-option.
-
-Test output goes into two files in your current directory: summary
-output in @file{@var{tool}.sum}, and detailed output in
-@file{@var{tool}.log}. (@var{tool} refers to the collection of tests;
-for example, after a run with @samp{--tool gdb}, look for output files
-@file{gdb.sum} and @file{gdb.log}.) @xref{Output Files,,The files
-DejaGnu writes}.
-
-@node Sample Test
-@section What does a DejaGnu test look like?
-
-@cindex example
-Each DejaGnu test is an @code{expect} script; the tests vary widely in
-complexity, depending on the nature of the tool and the feature tested.
-
-@kindex gdb.t00/echo.exp
-@kindex echo.exp
-Here is a very simple @sc{gdb} test---one of the simplest tests shipped
-with DejaGnu (extracted from @file{gdb.t00/echo.exp}):@footnote{More
-recent @sc{gdb} tests use the @samp{gdb_test} procedure.
-An equivalent test using that procedure is @samp{ gdb_test "echo Hello
-world!" "Hello world!" }}
-@c FIXME! include xref in footnote, when gdb_test documented in some manual.
-@c @xref{}.
-@c Extra spaces in @samp above avoid running end ' against " inside.
-
-@cartouche
-@smallexample
-# send a string to the GDB stdin:
-send "echo Hello world!\n"
-
-# inspect the GDB stdout for the correct reply,
-# and determine whether the test passes or fails:
-expect @{
- -re "Hello world.*$prompt $" @{ pass "Echo test" @}
- -re "$prompt $" @{ fail "Echo test" @}
- timeout @{ fail "(timeout) Echo test" @}
- @}
-@end smallexample
-@end cartouche
-
-Though brief, this example is a complete test. It illustrates some of
-the main features of DejaGnu test scripts:
+Updated documentation, now in DocBook XML.
-@itemize @bullet
@item
-The test case does not start the tested program (@sc{gdb} in this case);
-all test scripts for interactive tools can assume the corresponding tool
-is running.
+Windows support. There is beta level support for
+Windows that is still a work in progress. This requires the
+@uref{http://www.cygwin.com/,Cygwin} POSIX
+subsystem for Windows.
+@end itemize
-@item
-Comments start with @samp{#}.
+@menu
+* Windows Support::
+@end menu
-@item
-The main commands you use to control a tested program are @code{send}
-(to give it commands) and @code{expect} (to analyze its responses).
+@node Windows Support, , , Release Notes
+@subsection Windows Support
-@item
-The @code{expect} command uses a list of pairs; a pattern (regular
-expression if @samp{-re} specified), followed by an action to run if the
-pattern matches output from the program. Only the action for the
-@emph{first} matching pattern will execute.
+To use DejaGnu on Windows, you need to first install the
+@uref{http://www.cygwin.com/,Cygwin}
+release. This works as of the B20.1 release. Cygwin is a POSIX
+system for Windows. This covers both utility programs and a library
+that adds POSIX system calls to Windows. Among them is pseudo tty
+support for Windows that emulates the POSIX pty standard. The
+latest Cygwin is always available from @uref{http://www.cygwin.com/,this location}. This
+works well enough to run @i{"make check"} of
+the GNU development tree on Windows after a native build. But the
+nature of ptys on Windows is still evolving. Your mileage may
+vary.
-@item
-Test cases use the commands @code{pass} and @code{fail} to record the
-test outcome.
-@end itemize
+@node Design Goals, A POSIX Conforming Test Framework, Release Notes, Overview
+@section Design Goals
-@node Design Goals
-@section Design goals
-@cindex design goals
+DejaGnu grew out of the internal needs of Cygnus Solutions,
+the company formerly known as Cygnus Support. Cygnus maintained
+and enhanced a variety of free programs in many different
+environments and we needed a testing tool that:
-DejaGnu grew out of the internal needs of Cygnus Support. Cygnus
-maintains and enhances a variety of free programs in many different
-environments, and we needed a testing tool that:
+@itemize @bullet{}
-@itemize @bullet
@item
-is useful to developers while fixing bugs;
+was useful to developers while fixing
+bugs;
@item
-automates running many tests during a software release process;
+automated running many tests during a software
+release process;
@item
-is portable among a variety of host computers;
+was portable among a variety of host
+computers;
@item
-supports cross-development testing;
+supported cross-development
+testing;
@item
-permits testing interactive programs, like @sc{gdb}; and
+permitted testing interactive programs, like
+@code{GDB}; and
@item
-permits testing batch oriented programs, like @sc{gcc}.
+permitted testing batch oriented programs, like
+@code{GCC}.
@end itemize
-Some of the requirements proved challenging. For example, interactive
-programs do not lend themselves very well to automated testing. But all
-the requirements are important: for instance, it is imperative to make
-sure that @sc{gdb} works as well when cross-debugging as it does in a
-native configuration.
-
-Probably the greatest challenge was testing in a cross-development
-environment (which can be a real nightmare). Most cross-development
-environments are customized by each developer. Even when buying
-packaged boards from vendors there are many differences. The
-communication interfaces vary from a serial line to ethernet. DejaGnu
-was designed with a modular communication setup, so that each kind of
-communication can be added as required, and supported thereafter. Once
-a communication procedure is coded, any test can use it. Currently
-DejaGnu can use @code{rsh}, @code{rlogin}, @code{telnet}, @code{tip},
-@code{kermit}, and @code{mondfe} for remote communications.
-
-@cindex name ``DejaGnu''
-@cindex DejaGnu, the name
-@cindex Menapace, Julia
-Julia Menapace first coined the term ``DejaGnu'' to describe an earlier
-testing framework at Cygnus Support. When we replaced it with the
-Expect-based framework, it was like DejaGnu all over again@dots{}
-
-@node Posix
+Some of the requirements proved challenging. For example,
+interactive programs do not lend themselves very well to automated testing.
+But all the requirements are important: for instance, it is imperative to
+make sure that @code{GDB} works as well when cross-debugging
+as it does in a native configuration.
+
+Probably the greatest challenge was testing in a
+cross-development environment. Most cross-development
+environments are customized by each developer. Even when buying
+packaged boards from vendors there are many differences. The
+communication interfaces vary from a serial line to Ethernet.
+DejaGnu was designed with a modular communication setup, so that
+each kind of communication can be added as required and supported
+thereafter. Once a communication procedure is coded, any test can
+use it. Currently DejaGnu can use @code{rsh},
+@code{rlogin}, @code{telnet},
+@code{tip}, @code{kermit} and
+@code{mondfe} for remote communications.
+
+@node A POSIX Conforming Test Framework, , Design Goals, Overview
@section A POSIX conforming test framework
-@cindex POSIX conformance
-@cindex standard conformance: POSIX 1003.3
-DejaGnu conforms to the @sc{posix} standard for test frameworks.
-
-@cindex TET
-@sc{posix} standard 1003.3 defines what a testing framework needs to
-provide, in order to permit the creation of @sc{posix} conformance
-test suites. This standard is primarily oriented to running @sc{posix}
-conformance tests, but its requirements also support testing of features
-not related to @sc{posix} conformance. @sc{posix} 1003.3 does not
-specify a particular testing framework, but at this time there is only
-one other @sc{posix} conforming test framework:
-@sc{tet}.@footnote{@sc{tet} was created by Unisoft for a consortium
-comprised of X/Open, Unix International, and the Open Software
-Foundation.}
-
-The @sc{posix} documentation refers to @dfn{assertions}. An assertion
-is a description of behavior. For example, if a standard says ``The sun
-shall shine'', a corresponding assertion might be ``The sun is
-shining.'' A test based on this assertion would pass or fail depending
-on whether it is daytime or nighttime. It is important to note that the
-standard being tested is never 1003.3; the standard being tested is some
-other standard, for which the assertions were written.
-
-As there is no test suite to test @emph{testing frameworks} for
-@sc{posix} 1003.3 conformance, verifying conformance to this standard is
-done by repeatedly reading the standard and experimenting. One of the
-main things 1003.3 does specify is the set of allowed output messages,
-and their definitions. Four messages are supported for a required
-feature of @sc{posix} conforming systems, and a fifth for a conditional
-feature. DejaGnu supports the use of all five output messages; in this
-sense a test suite that uses exactly these messages can be considered
-@sc{posix} conforming. These definitions specify the output of a test
+DejaGnu conforms to the POSIX 1003.3 standard for test
+frameworks. Rob Savoye was a member of that committee.
+
+The POSIX standard 1003.3 defines what a testing framework needs to
+provide, in order to permit the creation of POSIX conformance test
+suites. This standard is primarily oriented to running POSIX conformance
+tests, but its requirements also support testing of features not related
+to POSIX conformance. POSIX 1003.3 does not specify a particular testing
+framework, but at this time there is only one other POSIX conforming test
+framework: TET. TET was created by Unisoft for a consortium comprised of
+X/Open, Unix International and the Open Software Foundation.
+
+The POSIX documentation refers to @i{assertions}.
+An assertion is a description of behavior. For example, if a standard
+says ``The sun shall shine'', a corresponding assertion might be ``The
+sun is shining.'' A test based on this assertion would pass or fail
+depending on whether it is day or night. It is important to note
+that the standard being tested is never 1003.3; the standard being tested
+is some other standard, for which the assertions were written.
+
+As there is no testsuite to test testing frameworks for POSIX
+1003.3 conformance, verifying conformance to this standard is done by
+repeatedly reading the standard and experimenting. One of the main
+things 1003.3 does specify is the set of allowed output messages and
+their definitions. Four messages are supported for a required feature of
+POSIX conforming systems and a fifth for a conditional feature. DejaGnu
+supports the use of all five output messages. In this sense a testsuite
+that uses exactly these messages can be considered POSIX conforming.
+These definitions specify the output of a test
case:
-@ftable @code
-@cindex success, POSIX definition
+@table @asis
+
@item PASS
-A test has succeeded. That is, it demonstrated that the assertion is true.
+A test has succeeded. That is, it demonstrated that
+the assertion is true.
+
+@item XFAIL
+POSIX 1003.3 does not incorporate the notion of
+expected failures, so @i{PASS}, instead of
+@i{XPASS}, must also be returned for test cases
+which were expected to fail and did not. This means that
+@i{PASS} is in some sense more ambiguous than if
+@i{XPASS} is also used.
@item FAIL
-@cindex failure, POSIX definition
-A test @emph{has} produced the bug it was intended to capture. That is,
-it has demonstrated that the assertion is false. The @code{FAIL}
-message is based on the test case only. Other messages are used to
-indicate a failure of the framework.
+A test has produced the bug it was intended to
+capture. That is, it has demonstrated that the assertion is false.
+The @i{FAIL} message is based on the test case only.
+Other messages are used to indicate a failure of the framework. As
+with @i{PASS}, POSIX tests must return
+@i{FAIL} rather than @i{XFAIL} even
+if a failure was expected.
@item UNRESOLVED
-@cindex ambiguity, required for POSIX
-A test produced indeterminate results. Usually, this means the test
-executed in an unexpected fashion; this outcome requires that a human
-being go over results, to determine if the test should have passed or
-failed. This message is also used for any test that requires human
-intervention because it is beyond the abilities of the testing
-framework. Any unresolved test should resolved to @code{PASS} or
-@code{FAIL} before a test run can be considered finished.
-
-Note that for @sc{posix}, each assertion must produce a test result
-code. If the test isn't actually run, it must produce @code{UNRESOLVED}
-rather than just leaving that test out of the output. This means that
-you have to be careful when writing tests, to not carelessly use tcl
-statements like @code{return}---if you alter the flow of control of the
-tcl code you must insure that every test still produces some result code.
+A test produced indeterminate results. Usually, this
+means the test executed in an unexpected fashion; this outcome
+requires that a human being go over results, to determine if the test
+should have passed or failed. This message is also used for any test
+that requires human intervention because it is beyond the abilities
+of the testing framework. Any unresolved test should resolved to
+@i{PASS} or @i{FAIL} before a test
+run can be considered finished.
+
+Note that for POSIX, each assertion must produce a test result
+code. If the test isn't actually run, it must produce
+@i{UNRESOLVED} rather than just leaving that test
+out of the output. This means that you have to be careful when
+writing tests to not carelessly use Tcl commands like
+@i{return}---if you alter the flow of control of the
+Tcl code you must insure that every test still produces some result
+code.
+
+Here are some of the ways a test may wind up
+@i{UNRESOLVED}:
+@end table
-Here are some of the ways a test may wind up @code{UNRESOLVED}:
+@itemize @bullet{}
-@itemize @bullet
@item
-A test's execution is interrupted.
+A test's execution is
+interrupted.
@item
-A test does not produce a clear result. This is usually because there
-was an @code{ERROR} from DejaGnu while processing the test, or because there
-were three or more @code{WARNING} messages. Any @code{WARNING} or
-@code{ERROR} messages can invalidate the output of the test. This
+A test does not produce a clear
+result. This is usually because there was an
+@i{ERROR} from DejaGnu while processing
+the test, or because there were three or more
+@i{WARNING} messages. Any
+@i{WARNING} or @i{ERROR}
+messages can invalidate the output of the test. This
usually requires a human being to examine the output to
-determine what really happened---and to improve the test case.
+determine what really happened---and to improve the test
+case.
@item
-A test depends on a previous test, which fails.
+A test depends on a previous test, which
+fails.
@item
-The test was set up incorrectly.
+The test was set up
+incorrectly.
@end itemize
+@table @asis
+
@item UNTESTED
-A test was not run. This is a placeholder, used when there is no
-real test case yet.
-@end ftable
+A test was not run. This is a place-holder, used
+when there is no real test case yet.
+@end table
-@noindent
-The only remaining @sc{posix} output message left is intended to test
-features that are specified by the applicable @sc{posix} standard as
+The only remaining output message left is intended to test
+features that are specified by the applicable POSIX standard as
conditional:
-@ftable @code
+@table @asis
+
@item UNSUPPORTED
-There is no support for the tested case. This may mean that a
-conditional feature of an operating system, or of a compiler, is not
-implemented. DejaGnu also uses this message when a testing environment
-(often a ``bare board'' target) lacks basic support for compiling or
-running the test case. For example, a test for the system subroutine
-@code{gethostname} would never work on a target board running only a
-boot monitor.
-@end ftable
-
-DejaGnu uses the same output procedures to produce these messages for
-all test suites, and these procedures are already known to conform to
-@sc{posix} 1003.3. For a DejaGnu test suite to conform to @sc{posix}
-1003.3, you must avoid the @code{setup_xfail} and @code{setup_kfail}
-procedures (see below), and you must be careful to return
-@code{UNRESOLVED} where appropriate, as described in the
-@code{UNRESOLVED} section above.
-
-Besides the @sc{posix} messages, DejaGnu provides for variations of the
-PASS and FAIL messages that can be helpful for the tool maintainers.
-It must be noted, however, that this feature is not @sc{posix} 1003.3
-compliant, so its use should be avoided if compliance is necessary.
-
-The additional messages are:
-
-@ftable @code
+There is no support for the tested case. This may
+mean that a conditional feature of an operating system, or of a
+compiler, is not implemented. DejaGnu also uses this message when
+a testing environment (often a ``bare board'' target) lacks basic
+support for compiling or running the test case. For example, a
+test for the system subroutine @i{gethostname}
+would never work on a target board running only a boot
+monitor.
+@end table
-@item XFAIL
-A test is expected to fail in some environment(s) due to some bug
-in the environment that we hope is fixed someday (but we can't do
-nothing about as it is not a bug in the tool that we are testing).
-The procedure @code{setup_xfail} is used to indicate that a failure
-is expected.
-
-@cindex XFAIL, avoiding for POSIX
-@sc{posix} 1003.3 does not incorporate the notion of expected failures,
-so @sc{posix} tests must return @code{FAIL} rather
-than @code{XFAIL} even if a failure was expected.
-
-@item KFAIL
-A test is known to fail in some environment(s) due to a known bug
-in the tool being tested (identified by a bug id string). This
-exists so that, after a bug is identified and properly registered
-in a bug tracking database (Gnats, for instance), the count of
-failures can be kept as zero. Having zero as a baseline in all
-platforms allow the tool developers to immediately detect regressions
-caused by changes (which may affect some platforms and not others).
-The connection with a bug tracking database allows for automatic
-generation of the BUGS section of man pages or Release Notes, as
-well as a "Bugs Fixed this Release" section (by comparing to a
-previous release set of known failures).
-The procedure @code{setup_kfail} is used to indicate a failure is
-known to exist.
-
-@cindex KFAIL, avoiding for POSIX
-As with @code{XFAIL}, @sc{posix} tests must return @code{FAIL} rather
-than @code{KFAIL} even if a failure was due to a known bug.
+DejaGnu uses the same output procedures to produce these messages
+for all testsuites and these procedures are already known to conform
+to POSIX 1003.3. For a DejaGnu testsuite to conform to POSIX 1003.3,
+you must avoid the @i{setup}xfail@} procedure as
+described in the @i{PASS} section above and you must
+be careful to return @i{UNRESOLVED} where appropriate,
+as described in the @i{UNRESOLVED} section
+above.
+@node Getting DejaGnu up and running, Running Tests, Overview, Top
+@chapter Getting DejaGnu up and running
-@item XPASS
-A test was expected to fail with @code{XFAIL} but passed instead.
-Whatever problem that used to exist in the environment was corrected
-The test may also be failing to detect the failure due to some
-environment or output changes, so this possibility must be investigated
-as well.
-
-@item KPASS
-A test was expected to fail with @code{KFAIL} but passed instead.
-Someone may have fixed the bug and failed to unmark the test.
-As for XPASS, the test may also be failing to detect the
-failure due to some environment or output changes, so this possibility
-must also be checked.
-
-@code{PASS}, instead of @code{XPASS} or @code{KPASS}, must also be
-returned for test cases which were expected to fail and did not,
-if @sc{posix} 1003.3 compliance is required.
-This means that @code{PASS} is in some sense more ambiguous than if
-@code{XPASS} and @code{KPASS} are also used.
-
-@end ftable
-
-See also @ref{Invoking runtest,,Using @code{runtest}}.
-For information on how to mark tests as expected/known to fail by using
-@code{setup_xfail} and @code{setup_kfail}, see
-@ref{framework.exp,,Core Internal Procedures}.
-
-
-@node Future Directions
-@section Future directions
-@cindex future directions
-
-In the near future, there are two parallel directions for DejaGnu
-development. The first is to add support for more hosts and targets.
-
-The second would permit testing programs with a more complex interface,
-whether text based or GUI based. Two components already exist: a Tcl
-based X window toolkit, and a terminal package for @code{expect}. Both
-of these could be merged into DejaGnu in a way that permits testing
-programs that run in each environment.
-
-Meanwhile, we hope DejaGnu enables the creation of test suites for
-conformance to @sc{ansi} C and C++, to @sc{posix}, and to other
-standards. We encourage you to make any test suites you create freely
-available, under the same terms as DejaGnu itself.
-
-@node Tcl and Expect
-@section Tcl and Expect
-@cindex tool command language
-@cindex tcl
-@cindex Ousterhout, John K.
-Tcl was introduced in a paper by John K. Ousterhout at the 1990 Winter
-Usenix conference, @cite{Tcl: An Embeddable Command Language}. That
-paper is included in PostScript form in the @file{doc} subdirectory of
-the Tcl distribution. The version of Tcl included in DejaGnu at this time is
-Tcl 7.4p3.
-
-@cindex @code{expect} scripting language
-@cindex Libes, Don
-Don Libes introduced @code{expect} in his paper @cite{expect: Curing
-Those Uncontrollable Fits of Interaction} at the 1990 Summer Usenix
-conference. The paper is included in PostScript form in the
-@code{expect} distribution (as are several other papers about
-@code{expect}). The version of expect included in DejaGnu at this time
-is expect 5.18.0.
-
-@node Invoking runtest
-@chapter Using @code{runtest}
-@cindex invoking
-@cindex running
-@cindex command line options
-@cindex options
-
-@cindex @code{runtest} description
-@cindex DejaGnu test driver
-@code{runtest} is the executable test driver for DejaGnu. You can
-specify two kinds of things on the @code{runtest} command line: command
-line options, and Tcl variables for the test scripts. The options are
-listed alphabetically below.
-
-@cindex exit code from @code{runtest}
-@cindex @code{runtest} exit code
-@code{runtest} returns an exit code of @code{1} if any test
-has an unexpected result; otherwise (if all tests pass or fail as
-expected) it returns @code{0} as the exit code.
-
-@code{runtest} flags the outcome of each test as one of these cases.
-(@xref{Posix,,A POSIX conforming test framework}, for a discussion of
-how @sc{posix} specifies the meanings of these cases.)
-
-@table @code
-@item PASS
-@kindex PASS
-@cindex successful test
-@cindex test, successful
-The most desirable outcome: the test succeeded, and was expected to
-succeed.
+This chapter was originally written by Niklaus Giger
+(ngiger@@mus.ch) because he lost a week to figure out how DejaGnu works
+and how to write a first test.
-@item XPASS
-@kindex XPASS
-@cindex successful test, unexpected
-@cindex unexpected success
-A pleasant kind of failure: a test was expected to fail, but succeeded.
-This may indicate progress; inspect the test case to determine whether
-you should amend it to stop expecting failure.
-
-@item KPASS
-@kindex KPASS
-@cindex successful test, unexpected
-@cindex unexpected success
-A pleasant kind of failure: a test was known to fail, but succeeded.
-This may indicate progress; inspect the test case to determine whether
-you should amend it to stop expecting failure.
-
-@item KPASS
-@kindex KPASS
-@cindex successful test, unexpected
-@cindex unexpected success
-A pleasant kind of failure: a test was known to fail, but succeeded.
-This may indicate progress; inspect the test case to determine whether
-you should amend it to stop expecting failure.
+Follow these instructions as closely a possible in order get a
+good insight into how DejaGnu works, else you might run into a lot of
+subtle problems. You have been warned.
-@item FAIL
-@kindex FAIL
-@cindex failing test, unexpected
-@cindex test, failing
-A test failed, although it was expected to succeed. This may indicate
-regress; inspect the test case and the failing software to locate the bug.
+It should be no big problems installing DejaGnu using your
+package manager or from the source code. Under a Debian/GNU/Linux
+systems just type (as root)
-@item XFAIL
-@kindex XFAIL
-@cindex expected failure
-@cindex failing test, expected
-A test failed, but it was expected to fail. This result indicates no
-change in a known environment bug. If a test fails because the operating
-system where the test runs lacks some facility required by the test
-(i.e. failure is due to the lack of a feature, not the existence of a bug),
-the outcome is @code{UNSUPPORTED} instead.
-
-@item KFAIL
-@kindex KFAIL
-@cindex known failure
-@cindex failing test, known
-A test failed, but it was known to fail. This result indicates no
-change in a known bug. If a test fails because of a problem in the
-environment, not in the tool being tested, that is expected to be
-fixed one day, the outcome is @code{XFAIL} instead.
+@example
+apt-get
+dejagnu
+@end example
-@item UNRESOLVED
-@kindex UNRESOLVED
-@cindex test, unresolved outcome
-Output from a test requires manual inspection; the test suite could not
-automatically determine the outcome. For example, your tests can report
-this outcome is when a test does not complete as expected.
+@noindent
+. These examples were run on a primary machine
+with a AMD K6 and a Mac Powerbook G3 serving as a remote
+target.
-@item UNTESTED
-@kindex UNTESTED
-@cindex untested properties
-A test case is not yet complete, and in particular cannot yet produce a
-@code{PASS} or @code{FAIL}. You can also use this outcome in dummy
-``tests'' that note explicitly the absence of a real test case
-for a particular property.
+The tests for Windows were run under Windows NT using the
+actual Cygwin version (1.3.x as of October 2001). It's target system
+was a PPC embedded system running vxWorks.
-@item UNSUPPORTED
-@kindex UNSUPPORTED
-@cindex unsupported test
-@cindex test, unsupported
-A test depends on a conditionally available feature that does not exist
-(in the configured testing environment). For example, you can use this
-outcome to report on a test case that does not work on a particular
-target because its operating system support does not include a required
-subroutine.
-@end table
+@menu
+* Test your installation::
+* Create a minimal project; e_g_ calc::
+* Our first automated tests::
+* A first remote test::
+@end menu
-@code{runtest} may also display the following messages:
+@node Test your installation, Create a minimal project; e_g_ calc, , Getting DejaGnu up and running
+@section Test your installation
-@table @code
-@item ERROR
-@kindex ERROR
-@cindex problem, detected by test case
-@cindex test case cannot run
-Indicates a major problem (detected by the test case itself) in running
-the test. This is usually an unrecoverable error, such as a missing file
-or loss of communication to the target. (@sc{posix} test suites should
-not emit this message; use @code{UNSUPPORTED}, @code{UNTESTED}, or
-@code{UNRESOLVED} instead, as appropriate.)
+Create a new user called "dgt" (DejaGnuTest), which uses bash as
+it login shell. PS1 must be set to '\u:\w\$ ' in its ~/.bashrc. Login
+as this user, create an empty directory and change the working
+directory to it. e.g
-@item WARNING
-@kindex WARNING
-@cindex test case warnings
-Indicates a possible problem in running the test. Usually warnings
-correspond to recoverable errors, or display an important message about
-the following tests.
+@example
-@item NOTE
-@kindex NOTE
-@cindex test case messages
-An informational message about the test case.
-@end table
-
-This is the full set of command line options that @code{runtest}
-recognizes. Arguments may be abbreviated to the shortest unique string.
-
-@cindex @code{runtest} option list
-@cindex option list, @code{runtest}
-@smallexample
-runtest --tool @var{tool} [ @var{testsuite}.exp @dots{} ]
-[ @var{testsuite}.exp="testfile1 @dots{}" ]
-[ @var{tclvar}=@var{value}@dots{} ]
-[ --all ] [ --baud @var{baud-rate} ] [ --connect @var{type} ]
-[ --debug ] [ --help ] [ --host @var{string} ]
-[ --mail "@var{name} @dots{}" ] [ --name @var{string} ]
-[ --name @var{name} ] [ --outdir @var{path} ]
-[ --objdir @var{path} ] [ --reboot ]
-[ --srcdir @var{path} ] [ --strace @var{n} ]
-[ --target @var{string} --build @var{string} ]
-[ -v | --verbose ] [ -V | --version ] [ --D@var{n} ]
-@end smallexample
-
-@table @code
-@item --tool @var{tool}
-@cindex selecting tests for a tool
-@cindex @code{--tool} (@code{runtest} option)
-@var{tool} specifies what set of tests to run, and what initialization
-module to use. @var{tool} is used @emph{only} for these two purposes:
-it is @emph{not} used to name the executable program to test.
-Executable tool names (and paths) are recorded in @file{site.exp}
-(@pxref{Config Values,,Configuration dependent values}), and you can
-override them by specifying Tcl variables on the command line.
-
-For example, including @samp{--tool gcc} on the @code{runtest} command
-line runs tests from all test subdirectories whose names match
-@file{gcc.*}, and uses one of the initialization modules named
-@file{config/*-gcc.exp}. To specify the name of the compiler (perhaps
-as an alternative path to what @code{runtest} would use by default), use
-@samp{GCC=@var{binname}} on the @code{runtest} command line.
-
-@item @var{testsuite}.exp @dots{}
-@cindex selecting a range of tests
-@cindex tests, running specifically
-@cindex naming tests to run
-Specify the names of testsuites to run.
-By default, @code{runtest} runs all tests for the tool, but you can
-restrict it to particular testsuites by giving the names of the @samp{.exp}
-@code{expect} scripts that control them.
-
-@var{testsuite}.exp may not include path information; use plain filenames.
-
-@item @var{testfile}.exp="testfile1 @dots{}"
-@cindex selecting a range of tests
-@cindex tests, running specifically
-@cindex naming tests to run
-Specify a subset of tests in a suite to run.
-For compiler or assembler tests, which often use a single @samp{.exp}
-script covering many different source files, this option allows you to
-further restrict the tests by listing particular source files to compile.
-Some tools even support wildcards here. The wildcards supported depend
-upon the tool, but typically they are @code{?}, @code{*}, and @code{[chars]}.
-
-@item @var{tclvar}=@var{value}
-@kindex @var{tclvar}=@var{value}
-@cindex Tcl variables, defining for @code{runtest}
-@cindex command line Tcl variable definition
-@cindex @code{runtest}, variable defns on cmdline
-You can define Tcl variables for use by your test scripts in the same
-style used with @code{make} for environment variables. For example,
-@samp{runtest GDB=gdb.old} defines a variable called @samp{GDB}; when
-your scripts refer to @samp{$GDB} in this run, they use the value
-@samp{gdb.old}.
-
-The default Tcl variables used for most tools are defined in the main
-DejaGnu @code{Makefile}; their values are captured in the
-@file{site.exp} file. @xref{Config Values,,Configuration dependent
-values}.
-
-@item --all
-@cindex @code{--all} (@code{runtest} option)
-@cindex test output, displaying all
-Display all test output. By default, @code{runtest} shows only the
-output of tests that produce unexpected results; that is, tests with
-status @samp{FAIL} (unexpected failure), @samp{XPASS} or @samp{KPASS}
-(unexpected success), or @samp{ERROR} (a severe error in the test case itself).
-Specify @samp{--all} to see output for tests with status @samp{PASS}
-(success, as expected) @samp{XFAIL} (failure, as expected), or
-@samp{WARNING} (minor error in the test case itself).
-
-@item --baud @var{baud-rate}
-@itemx -b @var{baud-rate}
-@cindex baud rate, specifying
-@cindex bps, specifying
-@cindex @code{--baud} (@code{runtest} option)
-@cindex @code{-b} (@code{runtest} option)
-Set the default baud rate to something other than 9600. (Some serial
-interface programs, like @code{tip}, use a separate initialization file
-instead of this value.)
-
-@item --connect @var{type}
-@cindex connecting to target
-@cindex @code{--connect} (@code{runtest} option)
-@cindex remote testbed, connecting to
-@cindex @code{rlogin}, remote testing via
-@cindex @code{telnet}, remote testing via
-@cindex @code{rsh}, remote testing via
-@cindex @code{tip}, remote testing via
-@cindex @code{kermit}, remote testing via
-@cindex @code{mondfe}, remote testing via
-@cindex remote testing via @code{rlogin}
-@cindex remote testing via @code{telnet}
-@cindex remote testing via @code{rsh}
-@cindex remote testing via @code{tip}
-@cindex remote testing via @code{kermit}
-@cindex remote testing via @code{mondfe}
-Connect to a target testing environment as specified by @var{type}, if
-the target is not the computer running @code{runtest}. For example, use
-@samp{--connect} to change the program used to connect to a ``bare
-board'' boot monitor. The choices for @var{type} in the DejaGnu 1.0
-distribution are @samp{rlogin}, @samp{telnet}, @samp{rsh}, @samp{tip},
-@samp{kermit}, and @samp{mondfe}.
+dgt:~$ mkdir ~/dejagnu.test
+dgt:~$ cd ~/dejagnu.test
+@end example
-@noindent
-The default for this option depends on the configuration (@pxref{Cross
-Targets,,Remote targets supported}). The default is chosen to be the
-most convenient communication method available, but often other
-alternatives work as well; you may find it useful to try alternative
-connect methods if you suspect a communication problem with your testing
-target.
+Now you are ready to test DejaGnu's main program called
+runtest. The expecteted output is shown
-@item --debug
-@cindex @code{--debug} (@code{runtest} option)
-@cindex debug log for test cases
-@cindex test cases, debug log
-@cindex @code{dbg.log} file
-Turns on the @code{expect} internal debugging output. Debugging output
-is displayed as part of the @code{runtest} output, and logged to a file
-called @file{dbg.log}. The extra debugging output does @emph{not}
-appear on standard output, unless the verbose level is greater than 2
-(for instance, to see debug output immediately, specify @samp{--debug -v
--v}). The debugging output shows all attempts at matching the test
-output of the tool with the scripted patterns describing expected
-output. The output generated with @samp{--strace} also goes into
-@file{dbg.log}.
+@strong{Runtest output in a empty directory
+}
-@item --help
-@itemx -he
-@cindex @code{--help} (@code{runtest} option)
-@cindex help with @code{runtest}
-@cindex @code{runtest}, listing options
-Prints out a short summary of the @code{runtest} options, then exits
-(even if you also specify other options).
-
-@item --host @var{string}
-@cindex @code{--host} (@code{runtest} option)
-@cindex specifying the host config name
-@cindex host config name, changing
-@var{string} is a full configuration ``triple'' name as used by
-@code{configure}. Use this option to override the default string
-recorded by your configuration's choice of host. This choice does not
-change how anything is actually configured unless --build is also
-specified; it affects @emph{only} DejaGnu procedures that compare the
-host string with particular values. The procedures @code{ishost},
-@code{istarget}, @code{isnative}, @code{setup_xfail} and
-@code{setup_kfail} are affected by @samp{--host}.
-In this usage, @code{host} refers to the machine that the
-tests are to be run on, which may not be the same as the @code{build}
-machine. If @code{--build} is also specified, then @code{--host} refers
-to the machine that the tests wil, be run on, not the machine DejaGnu is
-run on.
-
-@item --build @var{string}
-@cindex @code{--build} (@code{runtest} option)
-@cindex specifying the build config name
-@cindex build config name, changing
-@var{string} is a full configuration ``triple'' name as used by
-@code{configure}. This is the type of machine DejaGnu and the tools to
-be tested are built on. For a normal cross this is the same as the host,
-but for a canadian cross, they are seperate.
-
-@item --name @var{name}
-@cindex specifying target name
-@cindex target machine name
-@cindex @code{--name} (@code{runtest} option)
-@var{name} is a name for the particular testing target machine (for
-cross testing). If the testing target has IP network support (for
-example, @code{RPC} or @code{NFS}), this is the network name for the
-target itself. (@var{name} is @emph{not the configuration string} you
-specify as a target with @code{configure}; the @samp{--name} option
-names a particular target, rather than describing a class of targets.)
-For targets that connect in other ways, the meaning of the @var{name}
-string depends on the connection method. @xref{Cross Targets,,Remote
-targets supported}.
-
-@item --name @var{string}
-@cindex remote test machine name
-@cindex name for remote test machine
-Specify a network name of testing target or its host. The particular
-names that are meaningful with @samp{--name} will depend on your site
-configuration, and on the connection protocol: for example, @code{tip}
-connections require names from a serial line configuration file (usually
-called @file{/etc/remote}), while @code{telnet} connections use IP
-hostnames.
-
-@item --objdir @var{path}
-@cindex @code{--objdir} (@code{runtest} option)
-@cindex object directory
-@cindex test programs, auxiliary
-@cindex auxiliary test programs
-Use @var{path} as the top directory containing any auxiliary compiled
-test code. This defaults to @file{.}. Use this option to locate
-pre-compiled test code. You can normally prepare any auxiliary files
-needed with @code{make}.
-
-@item --outdir @var{path}
-@cindex output directory
-@cindex @code{--outdir} (@code{runtest} option)
-@cindex log files, where to write
-Write output logs in directory @var{path}. The default is @samp{.}, the
-directory where you start @code{runtest}. This option affects only the
-summary and the detailed log files @file{@var{tool}.sum} and
-@file{@var{tool}.log}. The DejaGnu debug log @file{dbg.log} always
-appears (when requested) in the local directory.
-
-@item --reboot
-@cindex rebooting remote targets
-@cindex @code{--reboot} (@code{runtest} option)
-Reboot the target board when @code{runtest} initializes.
-Usually, when running tests on a separate target board, it is safer to
-reboot the target to be certain of its state. However, when developing
-test scripts, rebooting takes a lot of time.
-
-@item --srcdir @var{path}
-@cindex source directory
-@cindex @code{--srcdir} (@code{runtest} option)
-Use @var{path} as the top directory for test scripts to run.
-@code{runtest} looks in this directory for any subdirectory whose name
-begins with the toolname (specified with @samp{--tool}). For instance,
-with @samp{--tool gdb}, @code{runtest} uses tests in subdirectories
-@file{gdb.*} (with the usual shell-like filename expansion). If you do
-not use @samp{--srcdir}, @code{runtest} looks for test directories under
-the current working directory.
-
-@item --strace @var{n}
-@cindex @code{--strace} (@code{runtest} option)
-@cindex tracing Tcl commands
-@cindex @code{expect} internal tracing
-Turn on internal tracing for @code{expect}, to @var{n} levels deep. By
-adjusting the level, you can control the extent to which your output
-expands multi-level Tcl statements. This allows you to ignore some
-levels of @code{case} or @code{if} statements. Each procedure call or
-control structure counts as one ``level''.
-
-The output is recorded in the same file, @file{dbg.log}, used for output
-from @samp{--debug}.
-
-@item --target @var{string}
-@cindex @code{--target} (@code{runtest} option)
-@cindex specifying the target configuration
-@cindex target configuration, specifying
-Use this option to override the default setting (running native tests).
-@var{string} is a full configuration ``triple''
-name@footnote{Configuration triples have the form
-@samp{@var{cpu}-@var{vendor}-@var{os}}.} as used by @code{configure}.
-This option changes the configuration @code{runtest} uses for the
-default tool names, and other setup information. @xref{Using
-configure,,Using @code{configure}, configure.info, Cygnus configure},
-for details about @code{configure} names.
-
-@item --verbose
-@itemx -v
-@cindex @code{--verbose} (@code{runtest} option)
-@cindex @code{-v} (@code{runtest} option)
-@cindex turning on output
-@cindex output, additional
-Turns on more output. Repeating this option increases the amount of
-output displayed. Level one (@samp{-v}) is simply test output. Level
-two (@samp{-v -v}) shows messages on options, configuration, and process
-control. Verbose messages appear in the detailed (@file{*.log}) log
-file, but not in the summary (@file{*.sum}) log file.
-
-@item --version
-@itemx -V
-@cindex @code{-V} (@code{runtest} option)
-@cindex @code{--version} (@code{runtest} option)
-@cindex version numbers
-Prints out the version numbers of DejaGnu, @code{expect} and Tcl, and
-exits without running any tests.
-
-@item -D0
-@itemx -D1
-@cindex starting the tcl debugger
-@cindex tcl debugger
-@c FIXME!!! we should say a *lot* more about this debugger
-Start the internal Tcl debugger. The Tcl debugger supports breakpoints,
-single stepping, and other common debugging activities. (See @cite{A
-Debugger for Tcl Applications} by Don Libes. @footnote{Distributed in
-PostScript form with @code{expect} as the file@*
-@file{expect/tcl-debug.ps}.})
-
-If you specify @samp{-D1}, the @code{expect} shell stops at a breakpoint
-as soon as DejaGnu invokes it.
-
-If you specify @samp{-D0}, DejaGnu starts as usual, but you can enter
-the debugger by sending an interrupt (e.g. by typing @key{C-c}).
-@end table
-
-@node Customizing
-@chapter Setting @code{runtest} defaults
-
-@kindex site.exp
-@cindex variables of DejaGnu, defaults
-The site configuration file, @file{site.exp}, captures
-configuration-dependent values and propagates them to the DejaGnu test
-environment using Tcl variables. This ties the DejaGnu test scripts
-into the @code{configure} and @code{make} programs.
-
-@cindex @file{site.exp}, multiple
-@cindex overriding @file{site.exp}
-DejaGnu supports more than one @file{site.exp} file. The multiple
-instances of @file{site.exp} are loaded in a fixed order built into
-DejaGnu (the more local last). The first file loaded is the optional
-@code{~/.dejagnurc}, then the local files, and finally the global file.
-
-@enumerate
-@item
-There is am optional ``master'' @file{site.exp}, capturing configuration values
-that apply to DejaGnu across the board, in each configuration-specific
-subdirectory of the DejaGnu library directory. @code{runtest} loads
-these values first. @xref{Installation,,Configuring and Installing
-DejaGnu}. The master @file{site.exp} contains the default values for
-all targets and hosts supported by DejaGnu. This master file is
-identified by setting the environment variable @code{DEJAGNU} to the
-name of the file. This is also refered to as the ``global'' config file.
-
-@item
-Any directory containing a configured test suite also has a
-@file{site.exp}, capturing configuration values specific to the tool
-under test. Since @code{runtest} loads these values last, the
-individual test configuration can either rely on and use, or override,
-any of the global values from the ``master'' @file{site.exp}.
-
-You can usually generate or update the testsuite @file{site.exp} by
-typing @samp{make site.exp} in the test suite directory, after the test
-suite is configured.
+@example
-@item
-You can also have a file in your home directory called
-@code{.dejagnurc}. This gets loaded first before the other config
-files. Usually this is used for personal stuff, like setting
-@code{all_flag} so all the output gets printed, or verbosity levels.
-@end enumerate
+dgt:~/dejagnu.test$ runtest
+WARNING: Couldn't find the global config file.
+WARNING: No tool specified Test
+Run By dgt on Sun Nov 25 17:07:03 2001 Native configuration is i586-pc-linux-gnu
+=== tests ===
+Schedule of variations: unix
+Running target unix Using /usr/share/dejagnu/baseboards/unix.exp as board description file for target.
+Using /usr/share/dejagnu/config/unix.exp as generic interface file for target.
+ERROR: Couldn't find tool config file for unix.
+=== Summary ===
+@end example
-You can further override the default values in a user-editable section
-of any @file{site.exp}, or by setting variables on the @code{runtest}
-command line.
+We will show you later how to get rid of all the WARNING- and
+ERROR-messages. The files testrun.sum and testrun.log have been
+created, which do not interest us at this point. Let's remove
+them.
+
+@example
+:~/dejagnu.test$ rm testrun.sum testrun.log
+@end example
@menu
-* Config Values:: Variables used in the configuration file.
-* Master Config File:: The master configuration file.
-* Local Config File:: The local configuration file.
-* Personal Config File:: The personal configuration file.
+* Windows::
+* Getting the source code for the calc example::
@end menu
-@node Config Values, Master Config File, , Customizing
-@subsection Config Variables
-@cindex configuration dependent defaults
-@cindex setting defaults for DejaGnu variables
-
-@c NOTE: default values are given via @code{"fubar"} rather than the
-@c more conventional @samp{fubar} to permit a consistent and clear
-@c notation for the empty string (@code{""}), which will work exactly as
-@c typed.
-
-DejaGnu uses a named array in Tcl 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
-@code{target_info}, and it has two indices. The following fields are
-part of the array.
-
-@table @code
-@item name
-The name of the target. (mostly for error messages) This
-should also be the string used for this target's array.
-It should also be the same as the linker script so we
-can find them dynamically. This should be the same as the argument used
-for @code{push_target@{@}}.
-
-@item ldflags
-This is the linker flags required to produce a fully linked
-executable. For @code{libgloss} supported targets this is usually just
-the name of the linker script.
-
-@item config
-The target canonical for this target. This is used by some init files to
-make sure the target is supported.
-
-@item cflags
-The flags required to produce an object file from a source file.
-
-@item connect
-This is the connectmode for this target. This is for both IP and
-serial connections. Typically this is either @code{telnet},
-@code{rlogin}, or @code{rsh}.
-
-@item target
-This is the hostname of the target. This is for TCP/IP based connections,
-and is also used for version of tip that use /etc/remote.
-
-@item serial
-This is the serial port. This is typically /dev/tty? or com?:.
-
-@item netport
-This is the IP port. This is commonly used for telneting to target
-boards that are connected to a terminal server. In that case the IP port
-specifies the which serial port to use.
-
-@item baud
-This is the baud rate for a serial port connection.
-
-@item x10
-This is the parameters for an x10 controller. These are simple devices
-that let us power cycle or reset a target board remotely.
-
-@item fileid
-This is the fileid or spawn id of of the connection.
-
-@item prompt
-a glob style pattern to recognize the prompt.
-
-@item abbrev
-abbreviation for tool init files.
-
-@item ioport
-This is the port for I/O on dual port systems. In this configuration,
-the main serial port @code{0} is usually used for stdin and stdout,
-which the second serial port can be used for debugging.
-@end table
-
-The first index into the array is the same value as used in the
-@code{name} field. This is usually a short version of the name of the
-target board. For an example, here's the settings I use for my
-@code{Motorola's} @code{IDP} board and my @code{Motorola} 6U VME
-@code{MVME135-1} board. (both m68k targets)
-
-@cartouche
-@smallexample
-# IDP board
-set target_info(idp,name) "idp"
-set target_info(idp,ldflags) "-Tidp.ld"
-set target_info(idp,config) m68k-unknown-aout
-set target_info(idp,cflags) ""
-set target_info(idp,connect) telnet
-set target_info(idp,target) "s7"
-set target_info(idp,serial) "tstty7"
-set target_info(idp,netport) "wharfrat:1007"
-set target_info(idp,baud) "9600"
-# MVME 135 board
-set target_info(idp,name) "mvme"
-set target_info(idp,ldflags) "-Tmvme.ld"
-set target_info(idp,config) m68k-unknown-aout
-set target_info(idp,cflags) ""
-set target_info(idp,connect) telnet
-set target_info(idp,target) "s8"
-set target_info(idp,serial) "tstty8"
-set target_info(idp,netport) "wharfrat:1008"
-set target_info(idp,baud) "9600"
-@end smallexample
-@end cartouche
-
-DejaGnu can use this information to switch between multiple targets in
-one test run. This is done through the use of the @code{push_target}
-procedure, which is discussed elsewhere.
-@c FIXME: write that section and put an xref here
-
-This array can also hold information for a remote host, which is used
-when testing a candain cross. In this case, the only thing different is
-the index is just @code{host}. Here's the settings I use to run tests
-on my NT machine while running DejaGnu on a Unix machine. (in this case
-a Linux box)
-
-@cartouche
-@smallexample
-set target_info(host,name) "nt-host"
-set target_info(host,config) "386-unknown-winnt"
-set target_info(host,connect) "telnet"
-set target_info(host,target) "ripple"
-@end smallexample
-@end cartouche
-
-There is more info on how to use these variables in the sections on the
-config files. @xref{Master Config File,,Configuration Files}.
-
-@cindex option defaults
-@cindex @code{runtest} option defaults
-@cindex variables for option defaults
-@cindex defaults, option
-In the user editable second section of @file{site.exp}, you can not only
-override the configuration variables captured in the first section, but
-also specify default values for all the @code{runtest} command line
-options. Save for @samp{--debug}, @samp{--help}, and @samp{--version},
-each command line option has an associated Tcl variable. Use the Tcl
-@code{set} command to specify a new default value (as for the
-configuration variables). The following table describes the
-correspondence between command line options and variables you can set in
-@file{site.exp}. @xref{Invoking runtest,,Running the Tests}, for
-explanations of the command-line options.
-
-@kindex all_flag
-@kindex baud
-@kindex reboot
-@kindex outdir
-@kindex objdir
-@kindex runtests
-@kindex ignoretests
-@kindex srcdir
-@kindex tracelevel
-@kindex targetname
-@kindex connectmode
-@kindex tool
-@kindex target_triplet
-@kindex host_triplet
-@kindex build_triplet
-@kindex verbose
-
-@cindex command line option variables
-@cindex Tcl variables for option defaults
-@cindex default options, controlling
-@cindex options, Tcl variables for defaults
-
-@ifinfo
-@display
-runtest Tcl
-option variable description
-__________ ________ ___________________________________________
-
---all all_flag display all test results if set
-
---baud baud set the default baud rate to something other
- than 9600.
---connect connectmode @samp{rlogin}, @samp{telnet}, @samp{rsh},
- @samp{kermit}, @samp{tip}, or @samp{mondfe}
-
---outdir outdir directory for @file{@var{tool}.sum} and @file{@var{tool}.log}
-
---objdir objdir directory for pre-compiled binaries
-
---reboot reboot reboot the target if set to @code{"1"};
- do not reboot if set to @code{"0"} (the default)
-
---srcdir srcdir directory of test subdirectories
-
---strace tracelevel a number: Tcl trace depth
-
---tool tool name of tool to test; identifies init, test subdir
-
---verbose verbose verbosity level. As option, use multiple times;
- as variable, set a number, 0 or greater
---target target_triplet The canonical configuration string for the target.
---host host_triplet The canonical configuration string for the host.
---build build_triplet The canonical configuration string for the
- build host.
-
-@end display
-@end ifinfo
-
-@tex
-\vbox{\halign{\hfil \tt #\quad &\quad\tt #\hfil &\hbox{\vtop{{\raggedright\parindent=0pt\parskip=5pt\hsize=2.75in\rm#\strut\par}}}\hfill\cr
-\cr
-{\it runtest}&{\it Tcl}\cr
-{\it option}&{\it variable}&{\it description}\cr
-\noalign{\hrule width\hsize}\cr
---all &all\_flag &display all test results if set\cr
---baud &baud &set the default baud rate to something other
- than 9600.\cr
---connect &connectmode &@samp{rlogin}, @samp{telnet}, @samp{rsh},
- @samp{kermit}, @samp{tip}, or @samp{mondfe}\cr
---mail &mailing\_list&address list for mailing test output\cr
---name &targetname &network name of testing target or its host\cr
---outdir &outdir &directory for @file{@var{tool}.sum} and @file{@var{tool}.log}\cr
---objdir &objdir &directory for compiled binaries\cr
---reboot &reboot &reboot the target if set to @code{"1"};
-do not reboot if set to @code{"0"} (the default)\cr
---srcdir &srcdir &directory of test subdirectories\cr
---strace &tracelevel &a number: Tcl trace depth\cr
---tool &tool &name of tool to test; identifies init, test subdir\cr
---verbose &verbose &verbosity level. As option, use multiple times;
- as variable, set a number, 0 or greater\cr
---target &target\_triplet
- &The canonical configuration string for the target.\cr
---host &host\_triplet &The canonical configuration string for the host.\cr
---build &build\_triplet &The canonical configuration string for the
- build host.\cr
-}}
-@end tex
-
-@node Master Config File, Local Config File, Config Values, Customizing
-@subsection Master Config File
-@cindex master @file{site.exp}
-@cindex @file{site.exp} for all of DejaGnu
-The master config file is where all the target specific config variables
-get set for a whole site get set. The idea is that for a centralized
-testing lab where people have to share a target between multiple
-developers. There are settings for both remote targets and remote hosts.
-Here's an example of a Master Config File (also called the Global config
-file) for a @emph{canadian cross}. A canadian cross is when you build
-and test a cross compiler on a machine other than the one it's to be
-hosted on.
-
-Here we have the config settings for our California office. Note that
-all config values are site dependant. Here we have two sets of values
-that we use for testing m68k-aout cross compilers. As both of these
-target boards has a different debugging protocol, we test on both of
-them in sequence.
-
-@cartouche
-@smallexample
-global CFLAGS
-global CXXFLAGS
-
-case "$target_triplet" in @{
- @{ "native" @} @{
- set target_abbrev unix
- @}
- @{ "m68*-unknown-aout" @} @{
- set target_abbrev "rom68k"
- # IDP target # IDP board with rom68k monitor
- set target_info(idp,name) "idp"
- set target_info(idp,ldflags) "-Tidp.ld"
- set target_info(idp,config) m68k-unknown-aout
- set target_info(idp,cflags) ""
- set target_info(idp,connect) telnet
- set target_info(idp,target) "s7"
- set target_info(idp,serial) "tstty12"
- set target_info(idp,netport) "truckin:1007"
- set target_info(idp,baud) "9600"
- # MVME target # Motorola MVME 135 with BUG monitor
- set target_info(mvme,name) "mvme"
- set target_info(mvme,ldflags) "-Tmvme.ld"
- set target_info(mvme,config) m68k-unknown-aout
- set target_info(mvme,cflags) ""
- set target_info(mvme,connect) telnet
- set target_info(mvme,target) "s4"
- set target_info(mvme,serial) "tstty8"
- set target_info(mvme,netport) "truckin:1004"
- set target_info(mvme,baud) "9600"
- @}
-@}
-@end smallexample
-@end cartouche
-
- In this case, we have support for several remote hosts for
-our m68k-aout cross compiler. Typically the remote Unix hosts run
-DejaGnu locally, but we also use them for debugging the testsuites when
-we find problems in running on remote hosts. Expect won't run on NT, so
-DejaGnu is run on the local build machine, and it'll connect to the NT
-host and run all the tests for this cross compiler on that host.
-
-@smallexample
-@cartouche
-case "$host_triplet" in @{
- "native" @{
- @}
- "i?86-*-linux*" @{ # Linux host
- set target_info(host,name) "linux-host"
- set target_info(host,config) $host_triplet
- set target_info(host,connect) rlogin
- set target_info(host,target) chinadoll
- @}
- "i?86-*-winnt # NT host
- set target_info(host,name) "nt-host"
- set target_info(host,config) i386-unknown-winnt
- set target_info(host,connect) telnet
- set target_info(host,target) ripple
- @}
- "hppa*-hp-hpux*" @{ # HP-UX host
- set target_info(host,name) "hpux-host"
- set target_info(host,config) $host_triplet
- set target_info(host,connect) rlogin
- set target_info(host,target) slipknot
- @}
- "sparc-sun-sunos*" @{ # SunOS (sun4)
- set target_info(host,name) "sunos-host"
- set target_info(host,config) $host_triplet
- set target_info(host,connect) rlogin
- set target_info(host,target) darkstar
- @}
-@}
-@end cartouche
-@end smallexample
-
-@node Local Config File, Personal Config File, Master Config File, Customizing
-@subsection Local Config File
-@cindex local @file{site.exp}
-@cindex @file{site.exp} for each tool
-It is usually more convenient to keep these ``manual overrides'' in the
-@file{site.exp} local to each test directory, rather than in the
-``master'' @file{site.exp} in the DejaGnu library.
-
-All local @file{site.exp} usually files have two sections, separated by
-comment text. The first section is the part that is generated by
-@code{make}. It is essentially a collection of Tcl variable definitions
-based on @file{Makefile} environment variables. Since they are generated
-by @code{make}, they contain the values as specified by
-@code{configure}. (You can also customize these values by using the
-@samp{--site} option to @code{configure}.) In particular, this section
-contains the @file{Makefile} variables for host and target configuration
-data. Do not edit this first section; if you do, your changes are replaced
-next time you run @code{make}.
-
-The first section starts with:
-
-@cartouche
-@smallexample
-## these variables are automatically generated by make ##
-# Do not edit here. If you wish to override these values
-# add them to the last section
-@end smallexample
-@end cartouche
-
-In the second section, you can override any default values (locally to
-DejaGnu) for all the variables. The
-second section can also contain your preferred defaults for all the
-command line options to @code{runtest}. This allows you to easily
-customize @code{runtest} for your preferences in each configured
-test-suite tree, so that you need not type options repeatedly on the
-command line. (The second section may also be empty, if you do not wish
-to override any defaults.)
-
-The first section ends with this line:
-
-@cartouche
-@smallexample
-## All variables above are generated by configure. Do Not Edit ##
-@end smallexample
-@end cartouche
-
-You can make any changes under this line. If you wish to redefine a
-variable in the top section, then just put a duplicate value in this
-second section. Usually the values defined in this config file are
-related to the configuration of the test run. This is the ideal place to
-set the variables @code{host_triplet}, @code{build_triplet},
-@code{target_triplet}. All other variables are tool dependant, i.e., for
-testing a compiler, the value for @var{CC} might be set to a freshly
-built binary, as opposed to one in the user's path.
-
-@node Personal Config File, , Local Config File, Customizing
-@subsection Personal Config File
-@cindex personal config @file{site.exp}
-@cindex @file{site.exp} for each person
-The personal config file is used to customize @code{runtest's} behaviour
-for each person. It's typically used to set the user prefered setting
-for verbosity, and any experimental Tcl procedures. My personal
-@file{~/.dejagnurc} file looks like:
-
-@cartouche
-@smallexample
-set all_flag 1
-set RLOGIN /usr/ucb/rlogin
-set RSH /usr/ucb/rsh
-@end smallexample
-@end cartouche
-
-Here I set @code{all_flag} so I see all the test cases that PASS along
-with the ones that FAIL. I also set @var{RLOGIN} and @code{RSH} to the
-BSD version. I have @code{kerberos} installed, and when I rlogin to a
-target board, it usually isn't supported. So I use the non secure
-versions of these programs rather than the default that's in my path.
+@node Windows, Getting the source code for the calc example, , Test your installation
+@subsection Windows
-@node Internals
-@chapter The DejaGnu Implementation
-@cindex operating principles
-@cindex internal details
+On Windows systems DejaGnu is part of a port of a lot of Unix
+tools to the Windows OS, called Cygwin. Cygwin may be downloaded and
+installed from a mirror of http://www.cygwin.com/. All examples were
+also run on Windows NT. If nothing is said, you can assume that you
+should get the same output as on a Unix system.
-DejaGnu is entirely written in @code{expect}, which uses Tcl as a
-command language. @code{expect} serves as a very programmable shell;
-you can run any program, as with the usual Unix command shells---but
-once the program is started, your @code{expect} script has fully
-programmable control of its input and output. This does not just apply
-to the programs under test; @code{expect} can also run any auxiliary
-program, such as @code{diff} or @code{sh}, with full control over its
-input and output.
+You will need a telnet daemon if you want to use a Windows box
+as a remote target. There seems to be a freeware telnet daemon at
+http://www.fictional.net/.
-DejaGnu itself is merely a framework for the set of test suites
-distributed separately for each @sc{gnu} tool. Future releases of
-@sc{gnu} tools will include even more tests, developed throughout the
-free software community.
+@node Getting the source code for the calc example, , Windows, Test your installation
+@subsection Getting the source code for the calc example
-@kindex runtest.exp
-@code{runtest} is the glue to tie together and manage the test scripts.
-The @code{runtest} program is actually a simple Bourne shell script that
-locates a copy of the @code{expect} shell and then starts the main Tcl
-code, @code{runtest.exp}. @code{runtest.exp} itself has these essential
-functions:
-
-@enumerate
-@item
-Parse the command line options, load the library files, and load the
-default configuration files.
-
-@item
-Locating the individual test scripts. @code{runtest.exp} locates the tests
-by exploiting a straightforward naming convention based on the string
-you specify with the @samp{--tool} option.
+If you are running a Debian distribution you can find the
+examples under /usr/share/doc/dejagnu/examples. These examples seem to
+be missing in Red Hat's RPM. In this case download the sources of
+DejaGnu and adjust the pathes to the DejaGnu examples
+accordingly.
-@item
-Providing an extended test environment, by defining additional Tcl
-procedures beyond those already in @code{expect}.
+@node Create a minimal project; e_g_ calc, Our first automated tests, Test your installation, Getting DejaGnu up and running
+@section Create a minimal project, e.g. calc
-@item
-Locating target-dependent functions, to standardize the test environment
-across a wide variety of test platforms.
-@end enumerate
+In this section you will to start a small project,
+using the sample application calc, which is part of your DejaGnu
+distribution
@menu
-* Names:: Conventions for using tool names
-* Init Module:: Initialization module
-* DejaGnu Builtins:: DejaGnu provides these Tcl procedures
-* Target Dependent:: Procedures supplied by the init module
-* Cross Targets:: Remote targets supported
-* Input Files:: The files DejaGnu depends on
-* Output Files:: The files DejaGnu produces
+* A simple project without the GNU autotools::
+* Using autoconf/autoheader/automake::
@end menu
-@node Names
-@section Conventions for using tool names
-
-@cindex @code{--tool} and naming conventions
-@cindex tool names and naming conventions
-@cindex naming conventions
-DejaGnu uses @samp{$tool}, the name of the tool under test, to tie
-together the testing configuration in a straightforward but flexible
-way. If there is only one testsuite for a particular application, then
-@samp{$tool} is optional.
-
-@samp{$tool} is @emph{not} used to invoke the tool, since sites that run
-multiple configurations of a particular tool often call each
-configuration by a different name. @code{runtest} uses the
-configuration-dependent variables captured in @file{site.exp} to
-determine how to call each tool.
-
-@cindex directory names and @code{--tool}
-@cindex test directories, naming
-@code{runtest} uses tool names to find directories containing tests.
-@code{runtest} scans the source directory (specified with
-@code{--srcdir}) for all directories whose names start with the tool
-name. It is a common practice to put a period after the tool part of the
-name. For instance, directories that start with
-@samp{g++.} contain @sc{g++} tests. To add a new test, just put it in
-any directory (create an entirely new directory, if you wish) whose name
-follows this convention.
-
-@cindex @code{exp} filename suffix
-@cindex test filename
-@cindex filename for test files
-A test is any file in an appropriately named subdirectory whose name
-ends in @samp{.exp} (the conventional way of naming @code{expect}
-scripts). These simple naming conventions make it as simple as possible
-to install new tests: all you must do is put the test in the right
-directory.
+@node A simple project without the GNU autotools, Using autoconf/autoheader/automake, , Create a minimal project; e_g_ calc
+@subsection A simple project without the GNU autotools
-@cindex order of tests
-@cindex tests, running order
-@code{runtest} sorts the tests in each subdirectory by name (using the
-Tcl @code{lsort} command) and runs them in the resulting order.
-
-@node Init Module
-@section Initialization module
-@cindex tool initialization
-@cindex setting up targets
-
-@c FIXME! should this node be merged with "Target dependent"?
-
-@cindex init file, purpose
-@cindex starting interactive tools
-@cindex initialization
-The initialization module (or ``init file'') has two purposes: to
-provide tool and target dependent procedures, and to start up an
-interactive tool to the point where it is ready to operate. The latter
-includes establishing communications with the target. All the tests for
-interactive programs assume that the tool is already running and
-communicating. Initialization modules for non-interactive programs may
-only need to supply the support functions.
-
-@cindex init file name
-@cindex name, initialization module
-Each test suite directory must contain (in its @file{config}
-subdirectory) a separate initialization module for each target. The
-appropriate init file is can be named several ways. The prefered name is
-the @emph{os} part of the canonical configuration name with @code{.exp}
-as the suffix. An example would be that for an @code{m68k-coff} system,
-the @code{target_os} part would be @code{coff}. The next way is for
-system where there are short filenames, or a shortcut is desired to
-refer to the OS name for that target. This is uses the value of
-@code{$target_abbrev} rather than the @code{target_os}.
-
-The final file looked for is simply @file{default.exp}. If there is only
-one operating system to support, then this file can be used. It's main
-purpose is to offer some support for new operating systems, or for
-unsupported cross targets. The last file looked for is
-@file{unknown.exp}. This is usually limited to error handling for
-unsupported targets. It's whole contents is typically.
-
-@cartouche
-@smallexample
-perror "Sorry, there is no support for this target"
-exit 1
-@end smallexample
-@end cartouche
-
-At the beginning of the init file, you must first determine the proper
-executable name of the tool to execute, since the actual name of the
-tool to be tested my vary from system to system. Here's an example
-for the @sc{gnu} C compiler.
-
-@cartouche
-@smallexample
-global AR
-# look for the archiver ar
-if ![info exists AR] @{
- set AR [findfile $base_dir/../../binutils/ar $base_dir/../../binutils/ar [tr
-ansform ar]]
- verbose "AR defaulting to $AR" 2
-@}
-@}
+The runtest program can be run standalone. All the
+autoconf/automake support is just cause those programs are commonly
+used for other GNU applications. The key to running runtest standalone
+is having the local site.exp file setup correctly, which automake
+does.
-global CFLAGS
-if ![info exists CFLAGS] then @{
- set CFLAGS ""
-@}
-@end smallexample
-@end cartouche
-
-It is always a good idea to first check the variable, and only set it if
-it has not yet been defined. Often the proper value of @code{AR} is set
-on the command line that invokes @file{runtest}.
-
-@kindex findfile
-The @code{findfile} procedure takes as it's first argument a file name
-to look for. The second argument is returned if the file is found, and
-the third argument is returned if the file is not found. @code{base_dir}
-is set internally by DejaGnu to the top level directory of the object
-tree.
-
-@kindex transform
-The @code{transform} procedure takes as its argument the native name of
-a tool (such as @samp{gcc} for the compiler), and returns the name as
-configured for that tool in the current installation. (For example, a
-cross-compiling version of @sc{gnu} CC that generates MIPS code may be
-installed with a name like @code{mips-idt-ecoff-gcc}.)
-
-In a test running native, writing the Tcl code for initialization is
-usually quite simple. For cross configurations, however, more elaborate
-instructions are usually needed to describe how to talk to a remote
-target.
+The generated site.exp should like like:
-Each initialization module defines up to four procedures with standard
-names and purposes. The names of these procedures begin with
-@samp{$tool}, the string that identifies tests for a particular tool:
-@code{$tool_start}, @code{$tool_load}, @code{$tool_exit}, and
-@code{$tool_version}. For example, the start procedure for @sc{gdb} is
-called @code{gdb_start}. (Since start procedures are used differently
-for batch and interactive tools, however, @code{runtest} itself never
-calls the start procedure. Init files for interactive tools are
-expected to end by running the start procedure.)
-
-@cindex utilities, loading from init file
-@cindex defaults, setting in init file
-The initialization module is also a good place to call @code{load_lib}
-to get any collections of utility procedures meant for a family of test
-cases, and to set up default values for any additional Tcl variables
-needed for a specific set of tests.
-
-@xref{Target Dependent,,Target dependent procedures}, for full
-descriptions of these procedures.
-
-@node DejaGnu Builtins
-@section DejaGnu procedures
-@cindex built in procedures, DejaGnu
-
-DejaGnu provides these Tcl procedures for use in test scripts.
-You can also use any standard @code{expect} or Tcl function. These
-procedures are stored in libraries, which DejaGnu loads at
-runtime. Here's explanation of the library procedures that get loaded at
-runtime. All other librarys are optional, and need to be loaded by the
-testsuite.
+@example
-@menu
-* framework.exp:: Core Internal Procedures.
-* remote.exp:: Procedures for remote communication.
-* utils.exp:: Utility procedures.
-* target.exp:: Cross target procedures.
-* debugger.exp:: Procedures for debugging your Tcl code.
-@end menu
+set tool calc
+set srcdir .
+set objdir /home/dgt/dejagnu.test
+@end example
-@node framework.exp, remote.exp, ,DejaGnu Builtins
-@subsection Core Internal Procedures
-@cindex Core Internal Procedures
-
-@xref{Posix,,A POSIX conforming test framework}, for more detailed
-explanations of the test outcomes (@samp{FAIL}, @samp{PASS},
-@samp{UNTESTED}, @samp{UNRESOLVED}, @samp{UNSUPPORTED}).
-
-@ftable @code
-@item perror "@var{string} @var{number}"
-@cindex test case, ERROR in
-@kindex ERROR
-Declares a severe error in the testing framework itself.
-@code{perror} writes in the log files a message beginning with
-@samp{ERROR}, appending the argument @var{string}. If the optional
-@var{number} is supplied, then this is used to set the internal count of
-errors to that value.
-
-As a side effect, @code{perror} also changes the effect of the next
-@code{pass} or @code{fail} command: the test outcome becomes
-@samp{UNRESOLVED}, since an automatic @samp{PASS} or @samp{FAIL} cannot
-be trusted after a severe error in the test framework. If the optional
-numeric value is @samp{0}, then there are no further side effects to
-calling this function, and the following test outcome doesn't become
-@samp{UNRESOLVED}. This can be used for errors with no known side
-effects.
-
-@item warning "@var{string} @var{number}"
-@cindex test case, WARNING in
-@kindex WARNING
-Declares detection of a minor error in the test case itself.
-@code{warning} writes in the log files a message beginning with
-@samp{WARNING}, appending the argument @var{string}. Use @code{warning}
-rather than @code{error} for cases (such as communication failure
-to be followed by a retry) where the test case can recover from the
-error. If the optional @var{number} is supplied, then this is used to
-set the internal count of warnings to that value.
-
-As a side effect, @code{warning_threshold} or more calls to
-@code{warning} in a single test case also changes the effect of the next
-@code{pass} or @code{fail} command: the test outcome becomes
-@samp{UNRESOLVED} since an automatic @samp{PASS} or @samp{FAIL} may not
-be trustworthy after many warnings. If the optional numeric value is
-@samp{0}, then there are no further side effects to calling this
-function, and the following test outcome doesn't become
-@samp{UNRESOLVED}. This can be used for errors with no known side
-effects.
-
-@item note "@var{string}"
-@cindex test case, informational messages
-@kindex NOTE
-Appends an informational message to the log file.
-@code{note} writes in the log files a message beginning with
-@samp{NOTE}, appending the argument @var{string}. Use @code{note}
-sparingly. @code{verbose} should be used for most such messages,
-but in cases where a message is needed in the log file regardless of
-the verbosity level use @code{note}.
-
-@item pass "@var{string}"
-@cindex test case, declaring success
-Declares a test to have passed. @code{pass} writes in the
-log files a message beginning with @samp{PASS}
-(or @code{XPASS}/@code{KPASS}, if failure was expected),
-appending the argument @var{string}.
-
-@item fail "@var{string}"
-@cindex test case, declaring failure
-Declares a test to have failed. @code{fail} writes in the
-log files a message beginning with @samp{FAIL} (or @code{XFAIL}, if
-failure was expected), appending the argument @var{string}.
-
-@item unresolved "@var{string}"
-@cindex test case, declaring ambiguity
-Declares a test to have an unresolved outcome. @code{unresolved} writes
-in the log file a message beginning with @samp{UNRESOLVED}, appending
-the argument @var{string}. This usually means the test did not execute
-as expected, and a human being must go over results to determine if it
-passed or failed (and to improve the test case).
-
-@item untested "@var{string}"
-@cindex test case, declaring no test
-Declares a test was not run. @code{untested} writes in the log file a
-message beginning with @samp{UNTESTED}, appending the argument
-@var{string}. For example, you might use this in a dummy test whose
-only role is to record that a test does not yet exist for some feature.
-
-@item unsupported "@var{string}"
-@cindex test case, declaring no support
-Declares that a test case depends on some facility that does not exist
-in the testing environment. @code{unsupported} writes in the log file a
-message beginning with @samp{UNSUPPORTED}, appending the argument
-@var{string}.
-
-@item get_warning_threshold
-@cindex test case, WARNING threshold
-Returns the current value of @code{warning_threshold}.
-The default value is 3.
-
-@item set_warning_threshold @var{threshold}
-@cindex test case, WARNING threshold
-Sets the value of @code{warning_threshold}.
-A value of @code{0} disables it: calls to @code{warning} will not turn
-a @samp{PASS} or @samp{FAIL} into an @samp{UNRESOLVED}.
-
-@item transform "@var{toolname}"
-@cindex transform tool name
-@cindex installed tool name
-@cindex tool name, as installed
-@cindex name transformations
-Generates a string for the name of a tool as it was configured and
-installed, given its native name (as the argument @var{toolname}).
-This makes the assumption that all tools are installed using the same
-naming conventions: it extrapolates from the invocation name for
-@file{runtest}. For example, if you call @code{runtest} as
-@file{m68k-vxworks-runtest}, the result of @w{@samp{ transform "gcc" }}
-is @samp{m68k-vxworks-gcc}.
-
-@item ishost "@var{host}"
-@cindex host configuration test
-Tests for a particular @emph{host} environment. If the currently
-configured host matches the argument string, the result is @code{1};
-otherwise the result is @code{0}. @var{host} must be a full three-part
-@code{configure} host name; in particular, you may not use the shorter
-nicknames supported by @code{configure} (but you can use wildcard
-characters, using shell syntax, to specify sets of names).
+@node Using autoconf/autoheader/automake, , A simple project without the GNU autotools, Create a minimal project; e_g_ calc
+@subsection Using autoconf/autoheader/automake
-@item istarget "@var{target}"
-@cindex target configuration test
-Tests for a particular @emph{target} environment. If the currently
-configured target matches the argument string, the result is @code{1};
-otherwise the result is @code{0}. @var{target} must be a full
-three-part @code{configure} target name; in particular, you may not use
-the shorter nicknames supported by @code{configure} (but you can use
-wildcard characters, using shell syntax, to specify sets of names). If it is
-passed a @code{NULL} string, then it returns the name of the build
-canonical configuration.
-
-@item isbuild "@var{host}"
-@cindex build host configuration test
-Tests for a particular @emph{build host} environment. If the currently
-configured host matches the argument string, the result is @code{1};
-otherwise the result is @code{0}. @var{host} must be a full three-part
-@code{configure} host name; in particular, you may not use the shorter
-nicknames supported by @code{configure} (but you can use wildcard
-characters, using shell syntax, to specify sets of names). If it is
-passed a @code{NULL} string, then it returns the name of the build
-canonical configuration.
-
-item is3way "@var{host}"
-@cindex canadian cross configuration test
-Tests for a canadian cross. This is when the tests will be run on a
-remotly hosted cross compiler. If it is a canadian cross, then the
-result is @code{1}; otherwise the result is @code{0}.
-
-@item isnative
-@cindex native configuration test
-Tests whether the current configuration has the same host and target.
-When it runs in a @emph{native} configuration this procedure returns a
-@code{1}; otherwise it returns a @code{0}.
-
-@item load_lib "@var{library-file}"
-@cindex load library file
-Loads the file @var{library-file} by searching a fixed path built into
-@code{runtest}. If DejaGnu has been installed, it looks in a path
-starting with the installed library directory. If you are running
-DejaGnu directly from a source directory, without first running
-@samp{make install}, this path defaults to the current directory. In
-either case, it then looks in the current directory for a directory
-called @code{lib}. If there are duplicate definitions, the last one
-loaded takes precedence over the earlier ones.
-
-@item setup_xfail "@var{config} @r{[}@var{bugid}@r{]}"
-@c two spaces above to make it absolutely clear there's whitespace---a
-@c crude sort of italic correction!
-@cindex test case, expecting failure
-@cindex failure, expected
-@cindex expected failure
-Declares that the test is expected to fail on a particular set of
-configurations. The @var{config} argument must be a list of full
-three-part @code{configure} target name; in particular, you may not use
-the shorter nicknames supported by @code{configure} (but you can use the
-common shell wildcard characters to specify sets of names). The
-@var{bugid} argument is optional, and used only in the logging file
-output; use it as a link to a bug-tracking system such as @sc{gnats}
-(@pxref{Overview,, Overview, gnats.info, Tracking Bugs With GNATS}).
-
-See notes under setup_kfail (below).
-
-@item setup_kfail "@var{config} @r{[}@var{bugid}@r{]}"
-@c two spaces above to make it absolutely clear there's whitespace---a
-@c crude sort of italic correction!
-@cindex test case, known failure
-@cindex failure, known
-@cindex known failure
-Declares that the test is known to fail on a particular set of
-configurations. The @var{config} argument must be a list of full
-three-part @code{configure} target name; in particular, you may not use
-the shorter nicknames supported by @code{configure} (but you can use the
-common shell wildcard characters to specify sets of names). The
-@var{bugid} argument is mandatory, and used only in the logging file
-output; use it as a link to a bug-tracking system such as @sc{gnats}
-(@pxref{Overview,, Overview, gnats.info, Tracking Bugs With GNATS}).
-
-@cindex @code{XFAIL}, producing
-@cindex @code{KFAIL}, producing
-@cindex @code{XPASS}, producing
-@cindex @code{KPASS}, producing
-Once you use @code{setup_xfail} or @code{setup_kfail}, the @code{fail}
-and @code{pass} procedures produce the messages @samp{XFAIL} or @samp{KFAIL}
-and @samp{XPASS} or @samp{KPASS} respectively, allowing you to distinguish
-expected/known failures (and unexpected success!) from other test outcomes.
-
-If a test is marked as both expected to fail and known to fail for a
-certain configuration, a @samp{KFAIL} message will be generated.
-As @samp{KFAIL} messages are expected to draw more attention than
-the @samp{XFAIL} ones this will hopefuly ensure the test result is not
-overlooked.
-
-@emph{Warning:} you must clear the expected/known failure after using
-@code{setup_xfail} or @code{setup_kfail} in a test case. Any call to
-@code{pass} or @code{fail} clears the expectedknown failure implicitly;
-if the test has some other outcome, e.g. an error, you can call
-@code{clear_xfail} to clear the expected failure or @code{clear_kfail}
-to clear the known failure explicitly. Otherwise, the expected-failure
-declaration applies to whatever test runs next, leading to surprising
-results.
+We have to prepare some input file in order to run autocon and
+automake. There is book "GNU autoconf, automake and
+libtool" by Garry V. Vaughan, et al. NewRider, ISBN
+1-57870-190-2 which describes this process thoroughly.
-@item check_conditional_xfail @var{message} @var{targets} @var{includes} @var{excludes}
-@cindex test case, expecting a conditional failure
-@cindex failure, conditional expected
-@cindex conditional expected failure
-
-This procedure adds a conditional xfail, based on compiler options used to
-create a test case executable. If an include options is found in the
-compiler flags, and it's the right architecture, it'll trigger an
-XFAIL. Otherwise it'll produce an ordinary FAIL. You can also specify
-flags to exclude. This makes a result be a FAIL, even if the included
-options are found. To set the conditional, set the variable
-@var{compiler_conditional_xfail_data} to the fields "[message string] [targets
-list] [includes list] [excludes list]" (descriptions below). This is the
-checked at pass/fail decision time, so there is no need to call the
-procedure yourself, unless you wish to know if it gets triggered. After
-a pass/fail, the variable is reset, so it doesn't effect other tests.
-
-The parameters are:
-
-@table @code
-@item message
-is the message to print with the normal test result
-
-@item targets
-is a string with the targets to activate this conditional on.
-
-@item includes
-is a list of sets of options to search for in the compiler options to
-activate this conditional. If the list of sets of options is empty or
-if any set of the options matches, then this conditional is true.
-(It may be useful to specify an empty list of include sets if the
-conditional is always true unless one of the exclude sets matches.)
-
-@item excludes
-is a list of sets of options to search for in the compiler options to
-activate this conditional. If any set of the options matches,
-(regardless of whether any of the include sets match) then this
-conditional is de-activated.
-@end table
-
-returns:
-
-@table @code
-@item 1
-if the conditional is true
-@item 0
-if the conditional is false
-@end table
-
-An example of setting the variable would be:
-
-@cartouche
-@smallexample
-set compiler_conditional_xfail_data @{@ \
- "I sure wish I knew why this was hosed" \
- "sparc*-sun*-* *-pc-*-*" \
- @{@"-Wall -v" "-O3"@}@ \
- @{@"-O1" "-Map" @}@ \
- @}@
-@end smallexample
-@end cartouche
-
- What this does is it matches only for these two targets if "-Wall -v" or
-"-O3" is set, but neither "-O1" or "-Map" is set.
-
- For a set to match, the options specified are searched for independantly of
-each other, so a "-Wall -v" matches either "-Wall -v" or "-v -Wall". A space
-seperates the options in the string. Glob-style regular expressions are also
-permitted.
-
-@item clear_xfail @var{config}
-@cindex cancelling expected failure
-@cindex expected failure, cancelling
-Cancel an expected failure (previously declared with @code{setup_xfail})
-for a particular set of configurations. The @var{config} argument is a
-list of configuration target names. It is only necessary to call
-@code{clear_xfail} if a test case ends without calling either
-@code{pass} or @code{fail}, after calling @code{setup_xfail}.
-
-@item clear_kfail @var{config}
-@cindex cancelling known failure
-@cindex known failure, cancelling
-Cancel a known failure (previously declared with @code{setup_kfail})
-for a particular set of configurations. The @var{config} argument is a
-list of configuration target names. It is only necessary to call
-@code{clear_kfail} if a test case ends without calling either
-@code{pass} or @code{fail}, after calling @code{setup_kfail}.
-
-@item clear_kfail @var{config}
-@cindex cancelling known failure
-@cindex known failure, cancelling
-Cancel a known failure (previously declared with @code{setup_kfail})
-for a particular set of configurations. The @var{config} argument is a
-list of configuration target names. It is only necessary to call
-@code{clear_kfail} if a test case ends without calling either
-@code{pass} or @code{fail}, after calling @code{setup_kfail}.
-
-@item verbose @r{[}-log@r{]} @r{[}-n@r{]} @r{[}--@r{]} @r{[}--@r{]} "@var{string}" @var{number}
-@cindex @code{verbose} builtin function
-Test cases can use this function to issue helpful messages depending on
-the number of @samp{--verbose} options on the @code{runtest} command
-line. It prints @var{string} if the value of the variable
-@code{verbose} is higher than or equal to the optional @var{number}. The
-default value for @var{number} is 1. Use the optional @samp{-log} argument
-to cause @var{string} to always be added to the log file, even if it won't
-be printed. Use the optional @samp{-n} argument to print @var{string}
-without a trailing newline. Use the optional @samp{--} argument if
-@var{string} begins with "-". To log test results to a XML file use the
-@samp{-x} argument.
-
-@end ftable
+From the calc example distributed with the DejaGnu documentation
+you should copy the program file itself (calc.c) and some additional
+files, which you might examine a little bit close to derive their
+meanings.
-@noindent
-@node remote.exp, utils.exp, framework.exp, DejaGnu Builtins
-@subsection Remote Communication Procedures
-
-@kindex remote.exp
-@kindex lib/remote.exp
-@cindex remote connection procedures
-@cindex communications procedures
-@file{lib/remote.exp} defines these functions, for establishing and
-managing communications:
-
-@emph{Procedures to establish a connection:} Each of these procedures
-tries to establish the connection up to three times before returning.
-Warnings (if retries will continue) or errors (if the attempt is
-abandoned) report on communication failures. The result for any of
-these procedures is either @code{-1}, when the connection cannot be
-established, or the spawn ID returned by the @code{expect} command
-@code{spawn}.
+@example
-It use the value of the @code{connect} field in the @code{target_info}
-array (was @code{connectmode} as the type of connection to make. Current
-supported connection types are tip, kermit, telnet, rsh, rlogin, and
-netdata. If the @code{--reboot} option was used on the runtest command
-line, then the target is rebooted before the connection is made.
-
-@ftable @code
-
-@item remote_open @var{type}
-@cindex Opening a remote connection
-@emph{Remote Connection Procedure.} This is passed @emph{host} or
-@emph{target}. Host or target refers to whether it is a connection to a
-remote target, or a remote host. This opens the connection to the
-desired target or host using the default values in the configuration
-system. It returns that @code{spawn_id} of the process that manages the
-connection. This value can be used in @code{expect} or @code{exp_send}
-statements, or passed to other procedures that need the connection
-process's id. This also sets the @code{fileid} field in the
-@code{target_info} array.
-
-
-@item remote_close @var{shellid}
-@cindex Closing a remote connection
-@emph{shellid} is value returned by a call to @code{remote_open}. This
-closes the connection to the target so resources can be used by
-others. This parameter can be left off if the @code{fileid} field in the
-@code{target_info} array is set.
+dgt:~/dejagnu.test$ cp -r /usr/share/doc/dejagnu/examples/calc/\
+@{configure.in,Makefile.am,calc.c,testsuite@} .
+@end example
-@item telnet @var{hostname} @var{port}
-@itemx rlogin @var{hostname}
-@itemx rsh @var{hostname}
-@cindex IP network procedures
-@cindex network (IP) procedures
-@emph{IP network procedures.} @var{hostname} refers to the IP address or
-name (for example, an entry in @file{/etc/hosts}) for this target. The
-procedure names reflect the Unix utility used to establish a
-connection. The optional @var{port} is used to specify the IP port
-number. The value of the @code{netport} field in the @code{target_info}
-array is used. (was @code{$netport}) This value has two parts, the
-hostname and the port number, seperated by a @emph{:}. If @code{host} or
-@code{target} is used in the @code{hostname} field, than the config
-array is used for all information.
-
-@item tip @var{port}
-@cindex serial line connection, @code{tip}
-@emph{Serial line procedure.} Connect using the Unix utility @code{tip}.
-@var{port} must be a name from the @code{tip} configuration file
-@file{/etc/remote}. Often, this is called @samp{hardwire}, or something
-like @samp{ttya}. This file holds all the configuration data for
-the serial port. The value of the @code{serial} field in the
-@code{target_info} array is used. (was @code{$serialport}) If
-@code{host} or @code{target} is used in the @code{port} field, than
-the config array is used for all information.
-
-@item kermit @var{port} @var{bps}
-@cindex serial line connection, @code{kermit}
-@emph{Serial line procedure.} Connect using the program @code{kermit}.
-@var{port} is the device name, e.g. @file{/dev/ttyb}. @var{bps} is
-the line speed to use (in bits per second) for the connection. The value
-of the @code{serial} field in the @code{target_info} array is used. (was
-@code{$serialport}) If @code{host} or @code{target} is used in the
-@code{port} field, than the config array is used for all information.
-
-@end ftable
+In Makemake.am note the presence of the AUTOMAKE_OPTIONS = dejagnu. This option is needed.
-@noindent
-@emph{Procedures to manage a connection:}
-
-@ftable @code
-@item tip_download @var{spawnid} @var{file}
-@cindex download, @code{tip}
-@cindex serial download, @code{tip}
-Download @file{@var{file}} to the process @var{spawnid} (the value
-returned when the connection was established), using the @code{~put}
-command under @code{tip}. Most often used for single board computers
-that require downloading programs in @sc{ascii} S-records. Returns
-@code{1} if an error occurs, @code{0} otherwise.
-
-@item exit_remote_shell @var{spawnid}
-@cindex terminating remote connection
-@cindex remote connection, ending
-Exits a remote process started by any of the connection procedures.
-@var{spawnid} is the result of the connection procedure that started the
-remote process.
-
-@item download @var{file} @r{[} @var{spawnid} @r{]}
-@cindex download a file
-After you establish a connection to a target, you can download programs
-using this command. @code{download} reads in @var{file} (object code in
-S-record format) and writes it to the device controlling this
-@var{spawnid}. (From the point of view of the target, the S-record file
-comes in via standard input.)
-
-If you have more than one target active, you can use the optional argument
-@var{spawnid} to specify an alternative target (the default is the most
-recently established @var{spawnid}.)
-@end ftable
+Run aclocal to generate aclocal.m4, which is a collection of
+macros needed by configure.in
-@noindent
-@node utils.exp, target.exp, remote.exp, DejaGnu Builtins
-@subsection Utility Procedures
+@example
-@kindex utils.exp
-@kindex lib/utils.exp
-@file{lib/utils.exp} defines these utility procedures:
-
-@ftable @code
-@item getdirs @var{dir}
-@itemx getdirs @var{dir} @var{pattern}
-@cindex directories matching a pattern
-@cindex pattern match, directory
-Returns a list of all the directories in the single directory @var{dir}
-that match @var{pattern}. If you do not specify @var{pattern},
-@code{getdirs} assumes @samp{*}. You may use the common shell wildcard
-characters in @var{pattern}. If no directories match the pattern, then a
-@code{NULL} string is returned.
-
-@item find @var{dir} @var{pattern}
-@cindex files matching a pattern
-@cindex pattern match, filenames
-Search for files whose names match @var{pattern} (using shell wildcard
-characters for filename expansion). Search subdirectories recursively,
-starting at @var{dir}. The result is the list of files whose names
-match; if no files match, the result is empty. Filenames in the result
-include all intervening subdirectory names. If no files match the
-pattern, then a @code{NULL} string is returned.
-
-@item which @var{binary}
-@cindex path lookup
-Searches the execution path for an executable file @var{binary}, like
-the the BSD @code{which} utility. This procedure uses the shell
-environment variable @samp{PATH}. It returns @code{0} if the binary is
-not in the path, or if there is no @samp{PATH} environment variable. If
-@var{binary} is in the path, it returns the full path to @var{binary}.
-
-@item grep @var{filename} @var{regexp}
-@item grep @var{filename} @var{regexp} line
-@cindex regular expression, file contents
-@cindex searching file contents
-Search the file called @var{filename} (a fully specified path) for lines
-that contain a match for regular expression @var{regexp}. The result is
-a list of all the lines that match. If no lines match, the result is an
-empty string. Specify @var{regexp} using the standard regular
-expression style used by the Unix utility program @code{grep}.
-
-Use the optional third argument @samp{line} to start lines in the result
-with the line number in @var{filename}. (This argument is simply an
-option flag; type it just as shown---@samp{line}.)
-
-@item diff @var{filename} @var{filename}
-@cindex finding file differences
-@cindex comparing files
-Compares the two files and returns a 1 if they match, or a 0 if they
-don't. If @code{verbose} is set, then it'll print the differences to the
-screen.
-
-@item slay @var{name}
-@cindex slaying processes
-This look in the process table for @var{name} and send it a unix
-@code{SIGINT}, killing the process.
-
-@item absolute @var{path}
-@cindex converting relative paths to absolute
-This procedure takes the relative @var{path}, and converts it to an
-absolute path.
-
-@item psource @var{filename}
-@cindex sourcing Tcl files
-This sources the file @var{filename}, and traps all errors. It also
-ignores all extraneous output. If there was an error it returns a 1,
-otherwise it returns a 0.
-
-@item prune @var{list} @var{pattern}
-@cindex list, pruning
-Remove elements of the Tcl list @var{list}. Elements are fields
-delimited by spaces. The result is a copy of @var{list}, without any
-elements that match @var{pattern}. You can use the common shell
-wildcard characters to specify @var{pattern}.
-
-@item setenv @var{var} @var{val}
-@cindex setting environment variables
-Sets the variable @var{var} to the value @var{val}.
-
-@item unsetenv @var{var}
-@cindex unsetting environment variables
-Unsets the environment variable @var{var}
-
-@item getenv @var{var}
-@cindex getting environment variables
-returns the value of @var{var} in the environment if it exists,
-otherwise it returns @code{NULL}.
-
-@item runtest_file_p @var{runtests} @var{testcase}
-@cindex selecting a range of tests
-@cindex tests, running specifically
-Search @var{runtests} for @var{testcase} and return 1 if found, 0 if not.
-@var{runtests} is a list of two elements. The first is a copy of what was
-on the right side of the @code{=} if @samp{foo.exp="@dots{}"} was specified,
-or an empty string if no such argument is present. The second is the
-pathname of the current testcase under consideration.
-This is used by tools like compilers where each testcase is a file.
-
-@item prune_system_crud @var{system} @var{text}
-@cindex pruning system output, examining program output
-For system @var{system}, delete text the host or target operating system might
-issue that will interfere with pattern matching of program output in
-@var{text}. An example is the message that is printed if a shared library
-is out of date.
-
-@end ftable
+dgt:~/dejagnu.test$ aclocal
+@end example
-@noindent
-@node target.exp, debugger.exp, utils.exp, DejaGnu Builtins
-@subsection Cross target procedure
+autoconf is another part of the auto-tools. Run it to generate
+configure based on information contained in configure.in.
-@kindex target.exp
-@kindex lib/target.exp
-@file{lib/target.exp} defines these utility procedures:
+@example
-@ftable @code
+dgt:~/dejagnu.test$ autoconf
+@end example
-@item push_target @emph{name}
-@cindex set current target
-This makes the target named @emph{name} be the current target
-connection. The value of @emph{name} is an index into the
-@code{target_info} array and is set in the global config file.
+autoheader is another part of the auto-tools.
+Run it to generate calc.h.in.
-@item pop_target
-@cindex unset current target
-This unsets the current target connection.
+@example
-@item list_targets
-@cindex lists supported targets
-This lists all the supported targets for this architecture.
+dgt:~/dejagnu.test$ autoheader
+@end example
-@item push_host @emph{name}
-@cindex set current host
-This makes the host named @emph{name} be the current remote host
-connection. The value of @emph{name} is an index into the
-@code{target_info} array and is set in the global config file.
+The Makefile.am of this example was developed as port of the DejaGnu
+distribution.
+Adapt Makefile.am for this test. Replace the line
+"#noinst_PROGRAMS = calc" to
+"bin_PROGRAMS = calc".
+Change the RUNTESTDEFAULTFLAGS from
+"$$srcdir/testsuite" to
+"./testsuite".
-@item pop_host
-@cindex unset current host
-This unsets the current host connection.
+Running automake at this point contains a series of warning in
+its output as shown in the following example:
-@c @item compile @emph{file}
-@cindex compile a file
-This invokes the compiler as set by @code{CC} to compile the file
-@emph{file}. The default options for many cross compilation targets are
-@emph{guessed} by DejaGnu, and these options can be added to by passing
-in more parameters as arguments to @code{compile}. Optionally, this will
-also use the value of the @code{cflags} field in the target config
-array. If the host is not the same as the build machines, then then
-compiler is run on the remote host using @code{execute_anywhere}.
-
-@c @item archive @emph{file}
-@cindex archive object files
-This produces an archive file. Any parameters passed to @code{archive}
-are used in addition to the default flags. Optionally, this will
-also use the value of the @code{arflags} field in the target config
-array. If the host is not the same as the build machines, then then
-archiver is run on the remote host using @code{execute_anywhere}.
-
-@c @item ranlib @emph{file}
-@cindex ranlib a file
-This generates an index for the archive file for systems that aren't
-POSIX yet. Any parameters passed to @code{ranlib} are used in for the
-flags.
-
-@item execute_anywhere @emph{cmdline}
-@cindex executing commands remotely
-This executes the @emph{cmdline} on the proper host. This should be used
-as a replacement for the Tcl command @code{exec} as this version
-utilizes the target config info to execute this command on the build
-machine or a remote host. All config information for the remote host
-must be setup to have this command work. If this is a canadian cross,
-(where we test a cross compiler that runs on a different host then where
-DejaGnu is running) then a connection is made to the remote host and
-the command is executed there. It returns either @emph{REMOTERROR} (for
-an error) or the output produced when the command was executed. This is
-used for running the tool to be tested, not a test case.
-
-@end ftable
-
-@node debugger.exp, , target.exp, DejaGnu Builtins
-@subsection Debugging Procedures
-
-@kindex debugger.exp
-@kindex lib/debugger.exp
-@file{lib/debugger.exp} defines these utility procedures:
-
-@ftable @code
-
-@item dumpvars @emph{expr}
-@cindex Print global variable values
-This takes a csh style regular expression (glob rules) and prints the
-values of the global variable names that match. It is abbreviated as
-@code{dv}
-
-@item dumplocals @emph{expr}
-@cindex Print local variable value
-This takes a csh style regular expression (glob rules) and prints the
-values of the local variable names that match. It is abbreviated as
-@code{dl}.
-
-@item dumprocs @emph{expr}
-@cindex Print procedure bodies
-This takes a csh style regular expression (glob rules) and prints the
-body of all procs that match. It is abbreviated as @code{dp}
-
-@item dumpwatch @emph{expr}
-@cindex Print watchpoints
-This takes a csh style regular expression (glob rules) and prints all
-the watchpoints. It is abbreviated as @code{dw}.
-
-@c FIXME: finish these when the code is fixed.
-@c @item watcharray @emph{element} @emph{type}
-@c @cindex Set a watchpoint on an array
-@c This sets an watchpoint of the @emph{element-type} on the
-@c @item watchvar v null type
-@c @cindex Set a watchpoint on a variable
-
-@item watchunset @emph{var}
-@cindex Watch when a variable is unset
-This breaks program execution when the variable @emph{var} is unset. It
-is abbreviated as @code{wu}.
-
-@item watchwrite @emph{var}
-@cindex Watch when a variable is written
-This breaks program execution when the variable @emph{var} is
-written. It is abbreviated as @code{ww}.
-
-@item watchread @emph{var}
-@cindex Watch when a variable is read
-This breaks program execution when the variable @emph{var} is read. It
-is abbreviated as @code{wr}.
-
-@item watchdel @emph{watch}
-@cindex Delete a watchpoint.
-This deletes a the watchpoint for @emph{watch}. It is abbreviated as
-@code{wd}.
-
-@item print @emph{var}
-@cindex Printing variable values
-This prints the value of the variable @emph{var}. It is abbreviated as
-@code{p}.
-
-@item quit
-@cindex Quiting DejaGnu
-This makes runtest exit. It is abbreviated as @code{q}.
-
-@item bt
-@cindex Print a backtrace
-This prints a backtrace of the executed Tcl commands.
-
-@end ftable
-
-@node Target Dependent
-@section Target dependent procedures
-@cindex target dependent procedures
-
-@c FIXME? These may be renamed to just "start", "load", "exit", and
-@c "version" eventually.
-
-Each combination of target and tool requires some target-dependent
-procedures. The names of these procedures have a common form: the tool
-name, followed by an underbar @samp{_}, and finally a suffix describing
-the procedure's purpose. For example, a procedure to extract the
-version from @sc{gdb} is called @samp{gdb_version}. @xref{Init Module,,
-Initialization Module}, for a discussion of how DejaGnu arranges to find
-the right procedures for each target.
-
-@code{runtest} itself calls only two of these procedures,
-@code{@var{tool}_exit} and @code{@var{tool}_version}; these procedures use
-no arguments.
-
-The other two procedures, @code{@var{tool}_start} and
-@code{@var{tool}_load}, are only called by the test suites themselves
-(or by testsuite-specific initialization code); they may take arguments
-or not, depending on the conventions used within each test suite.
-
-@ftable @code
-@item @var{tool}_start
-@cindex start procedure, tested tools
-Starts a particular tool. For an interactive tool,
-@code{@var{tool}_start} starts and initializes the tool, leaving the
-tool up and running for the test cases; an example is @code{gdb_start},
-the start function for @sc{gdb}. For a batch oriented tool,
-@code{@var{tool}_start} is optional; the recommended convention is to
-let @code{@var{tool}_start} run the tool, leaving the output in a
-variable called @code{comp_output}. Test scripts can then analyze
-@samp{$comp_output} to determine the test results. An example of this
-second kind of start function is @code{gcc_start}, the start function
-for @sc{gcc}.
-
-@code{runtest} itself @emph{does not call} @code{@var{tool}_start}. The
-initialization module @file{@var{tool}_init.exp} must call
-@code{@var{tool}_start} for interactive tools; for batch-oriented tools,
-each individual test script calls @code{@var{tool}_start} (or makes
-other arrangements to run the tool).
-
-@item @var{tool}_load
-@cindex load procedure, tested tools
-Loads something into a tool. For an interactive tool, this conditions
-the tool for a particular test case; for example, @code{gdb_load} loads
-a new executable file into the debugger. For batch oriented tools,
-@code{@var{tool}_load} may do nothing---though, for example, the
-@sc{gcc} support uses @code{gcc_load} to load and run a binary on the
-target environment. Conventionally, @code{@var{tool}_load} leaves the
-output of any program it runs in a variable called @samp{exec_output}.
-Writing @code{@var{tool}_load} can be the most complex part of extending
-DejaGnu to a new tool or a new target, if it requires much communication
-coding or file downloading.
-
-Test scripts call @code{@var{tool}_load}.
-
-@item @var{tool}_exit
-@cindex exit procedure, tested tools
-Cleans up (if necessary) before @code{runtest} exits. For interactive
-tools, this usually ends the interactive session. You can also use
-@code{@var{tool}_exit} to remove any temporary files left over from the
-tests.
+@strong{Sample output of automake with missing files}
-@code{runtest} calls @code{@var{tool}_exit}.
-
-@item @var{tool}_version
-@cindex version procedure, tested tools
-Prints the version label and number for @var{tool}. This is called by
-the DejaGnu procedure that prints the final summary report. The output
-should consist of the full path name used for the tested tool, and its
-version number.
-
-@code{runtest} calls @code{@var{tool}_version}.
-@end ftable
-
-The usual convention for return codes from any of these procedures
-(although it is not required by @code{runtest}) is to return @code{0} if
-the procedure succeeded, @code{1} if it failed, and @code{-1} if there
-was a communication error.
-
-@node Cross Targets
-@section Remote targets supported
-
-@cindex targets
-@cindex remote testing
-The DejaGnu distribution includes support for the following remote
-targets. You can set the target name and the connect mode in the
-@file{site.exp} file (using the Tcl variables @samp{targetname} and
-@samp{connectmode}, respectively), or on the @code{runtest} command line
-(using @samp{--name} and @samp{--connect}).
-
-@table @strong
-@item @sc{amd} 29000, with UDI protocol
-Configure DejaGnu for target @samp{a29k-amd-udi}. (Cygnus
-@code{configure} also recognizes the abbreviation @samp{udi29k}.) Then,
-to run tests, use the @code{runtest} target name to specify whether you
-want to use a simulator, or a particular hardware board. The particular
-string to use with @samp{--name} will depend on your UDI setup file,
-@file{udi_soc} (if @file{udi_soc} is not in your working directory, the
-environment variable @samp{UDICONF} should contain a path to this file).
-For example, if your UDI setup file includes these lines:
-@end table
-@c table "ends" *only* to allow wider example below
-
-@cartouche
-@smallexample
-iss AF_UNIX * isstip -r /home/gnu/29k/src/osboot/sim/osboot
-mon AF_UNIX * montip -t serial -baud 9600 -com /dev/ttyb
-@end smallexample
-@end cartouche
-
-@table @strong
-@item @w{ }
-@c fake out table/item into continuing w/same margin as before
-You can use @samp{--name iss} to run tests on the simulator, and
-@samp{--name mon} to run tests on the 29K hardware. See the
-manufacturer's manuals for more information on UDI and @file{udi_soc}.
-@c FIXME! Is there a better ref than "the manufacturer's manuals"?
-
-@kindex mondfe
-The default connect protocol is @samp{mondfe} with either back end.
-@code{mondfe} is the only shell DejaGnu supports for UDI targets.
-@code{mondfe} is an @sc{amd} specific monitor program freely available
-from @sc{amd}.
-
-@emph{Warning:} This target requires @sc{gdb} version 4.7.2 (or
-greater). Earlier versions of @sc{gdb} do not fully support the
-@code{load} command on this target, so DejaGnu has no way to load
-executable files from the debugger.
-
-@item Motorola 680x0 boards, a.out or @sc{coff} object format
-Configure DejaGnu for any remote target matching @samp{m68k-*}.
-
-@emph{Warning:} Most @samp{m68k-*} configurations run all tests only for
-native testing (when the target is the same as the host). When you
-specify most of these targets for a cross configuration, you will only be
-able to use tests that run completely within the host (for example,
-tests of the binary utilities such as the archiver; or compiler tests
-that only generate code rather than running it).
-
-To run a.out or @sc{coff} binaries on a remote M68K, you must configure
-DejaGnu for a particular target board. @samp{m68k-abug} is an example.
-(In general for an embedded environment, because it does not have absolute
-addresses, a.out is not a good choice for output format in any case; most
-often S-records or Hex-32 are used instead.)
-
-@item Motorola 68K MVME 135 board running ABug boot monitor
-Configure for @samp{m68k-abug-aout} or @samp{m68k-abug-coff} (as a
-target). This boot monitor can only download S-records; therefore, the
-DejaGnu tests for this environment require a linker command script to
-convert either output format to S-records, setting the default addresses
-for @code{.text}, @code{.bss}, and @code{.data}.
-
-With this configuration, the default for @samp{--connect} is @samp{tip}.
-@samp{tip} is the only communications protocol supported for connecting
-to @samp{m68k-abug-*} targets. @samp{tip} uses an @sc{ascii} downloader
-(the @code{~put} command) to load S-records into the target board. The
-@samp{--name} string must be a machine name that @code{tip}
-understands (for example, on some @code{tip} implementations it must be
-an entry from the initialization file for @code{tip}; this file is
-sometimes called @file{/etc/remote}).
-
-See your system documentation for information on how to create new
-entries in @file{/etc/remote}. (Some @sc{unix} systems are distributed
-with at least one default entry with a name resembling @samp{hardwire};
-if your system has one, you can edit it, or make a modified copy with a
-new name.) When you have a working @file{/etc/remote} entry
-@var{abugtarget}, you should be able to type @samp{tip
-@var{abugtarget}}, and get the prompt @samp{135ABUG>} from the board.
-Use the same @var{abugtarget} string with @samp{runtest --name}.
-
-@item Motorola IDP board running the rom68k boot monitor
-@c FIXME 1: this doesn't really say anything! OK, so functionality is
-@c the same. Is object code the same (srecords)? Do we configure with
-@c the same triplets? What is the default for --connect? Is
-@c any comms method other than tip supported? What prompt to expect
-@c when tip connected?
-@c FIXME 2: should @code{BUG} below be @code{ABUG}?
-This is the same in functionality as the MVME board running the
-@code{BUG} boot monitor. Only the monitor commands and the addresses are
-different.
-
-@item VxWorks (Motorola 68K or Intel 960)
-Configure DejaGnu for either @samp{m68k-wrs-vxworks} (abbreviated
-@samp{vxworks68}) or @samp{i960-wrs-vxworks} (abbreviated
-@samp{vxworks960}). Since both targets support IP addressing, specify
-the network address (for example, a host name from @file{/etc/hosts})
-with @samp{--name}.
-
-The default connect protocol is @samp{rlogin}, but you can use any of
-@samp{--connect rlogin}, @samp{--connect telnet}, or @samp{--connect
-rsh}.
-
-Test scripts need no special code to load programs into these targets;
-since VxWorks supports NFS, all you must do is ensure test programs are
-on an exported filesystem.
-
-@cindex VxWorks, link with @samp{-r}
-When you compile for VxWorks, use the linker @samp{-r} option to make
-the linker output relocatable---at least if you want to use library
-routines. Many standard C routines are included in VxWorks; often no
-additional libraries are needed. See your VxWorks system documentation
-for additional details.
-@end table
-
-@node Input Files
-@section The files DejaGnu reads
-@cindex input files
-
-The @code{runtest} program used to invoke DejaGnu is a short shell
-script generated by @code{make} during the configuration process. Its
-main task is to read the main test framework driver, @file{runtest.exp}.
-
-@file{runtest.exp}, in turn, reads @code{expect} code from certain other
-files, in this order:
-
-@enumerate
-@item
-Each of the @file{site.exp} local definition files available.
-@xref{Customizing,,Setting @code{runtest} defaults}, for details.
-
-@item
-@file{lib/utils.exp}, a collection of utility procedures. @xref{DejaGnu
-Builtins,,DejaGnu Builtins}, for descriptions of these procedures.
-
-@item
-@file{lib/framework.exp}, a file of subroutines meant for @code{runtest}
-itself rather than for general-purpose use in both @code{runtest} and
-test suites.
-
-@item
-@file{debugger.exp}, Don Libes' Tcl Debugger. (See @cite{A Debugger for
-Tcl Applications} by Don Libes. This paper is distributed with
-@code{expect} in PostScript form as the file
-@file{expect/tcl-debug.ps}.)
-
-@item
-@file{lib/remote.exp}, a collection of subroutines meant for connecting
-to remote machines.
-
-@item
-@file{lib/target.exp}, a collection of subroutines used for the
-configuration systems in DejaGnu. These procedures typically manipulate
-or utilize the configuration system.
-
-@item
-@c FIXME! A comment in runtest.exp claims a system default is used if
-@c no tool-specific init file is not available; I couldn't see where
-@c the program flow actually does this, though---pesch 30jul1993.
-An initialization file @code{@var{tool}_init.exp}. @xref{Init
-Module,,Initialization module}, for more discussion of init files.
-@end enumerate
+@example
-@c This hard page break is mainly intended for smallbook formatting;
-@c some examples in this section come out better if this starts at a
-@c page boundary.
-@page
-@node Output Files
-@section The files DejaGnu writes
-@cindex output files
+dgt:~/dejagnu.test$ automake --add-missing
+automake: configure.in: installing `./install-sh'
+automake: configure.in: installing `./mkinstalldirs'
+automake: configure.in: installing `./missing'
+automake: Makefile.am: installing `./INSTALL'
+automake: Makefile.am: required file `./NEWS' not found
+automake: Makefile.am: required file `./README' not found
+automake: Makefile.am: installing `./COPYING'
+automake: Makefile.am: required file `./AUTHORS' not found
+automake: Makefile.am: required file `./ChangeLog' not found
+configure.in: 4: required file `./calc.h.in' not found
+Makefile.am:6: required directory ./doc does not exist
+@end example
-@code{runtest} always writes two kinds of output files: summary logs and
-detailed logs. The contents of both of these are determined by your
-tests.
+Create a empty directory doc and empty files
+INSTALL, NEWS, README, AUTHORS, ChangeLog and COPYING.
+The default COPYING will point to the GNU Public License (GPL).
+In a real project it would be time to add some meaningfull text in each file.
-For troubleshooting, a third kind of output file is useful: use
-@samp{--debug} to request an output file showing details of what
-@code{expect} is doing internally.
+Adapt calc to your environment by calling configure.
-@menu
-* Summary:: Files that summarize tests
-* Detail:: Files that contain complete test results
-* Debug:: Logging expect internal actions
-@end menu
+@strong{Sample output of configure
+}
-@node Summary
-@subsection Summary log
-@cindex summary log
-
-@code{runtest} always produces a summary output file
-@file{@var{tool}.sum}. This summary shows the names of all test files
-run; for each test file, one line of output from each @code{pass}
-command (showing status @samp{PASS}, @samp{XPASS} or @samp{KPASS}) or
-@code{fail} command (status @samp{FAIL}, @samp{XFAIL} or @samp{KFAIL});
-trailing summary statistics that count passing and failing tests (expected and
-unexpected); and the full pathname and version number of the tool
-tested. (All possible outcomes, and all errors, are always reflected in
-the summary output file, regardless of whether or not you specify
-@samp{--all}.)
-
-If any of your tests use the procedures @code{unresolved},
-@code{unsupported}, or @code{untested}, the summary output also
-tabulates the corresponding outcomes.
+@example
-For example, after @samp{runtest --tool binutils}, look for a summary
-log in @file{binutils.sum}. Normally, @code{runtest} writes this file
-in your current working directory; use the @samp{--outdir} option to
-select a different directory.
+dgt:~/dejagnu.test$ ./configure
+creating cache ./config.cache
+checking whether to enable maintainer-specific portions of Makefiles... no
+checking for a BSD compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+checking whether make sets $@{MAKE@}... yes
+checking for working aclocal... found
+checking for working autoconf... found
+checking for working automake... found
+checking for working autoheader... found
+checking for working makeinfo... found
+checking for gcc... gcc checking whether the C compiler (gcc ) works... yes
+checking whether the C compiler (gcc ) is a cross-compiler... no
+checking whether we are using GNU C... yes
+checking whether gcc accepts -g... yes
+checking for a BSD compatible install... /usr/bin/install -c
+checking how to run the C preprocessor... gcc -E
+checking for stdlib.h... yes
+checking for strcmp... yes
+updating cache ./config.cache
+creating ./config.status
+creating Makefile creating calc.h
+@end example
-@need 3500
-@noindent
-Here is a short sample summary log:
-
-@cartouche
-@smallexample
-Test Run By rob on Mon May 25 21:40:57 PDT 1992
- === gdb tests ===
-Running ./gdb.t00/echo.exp ...
-PASS: Echo test
-Running ./gdb.all/help.exp ...
-PASS: help add-symbol-file
-PASS: help aliases
-PASS: help breakpoint "bre" abbreviation
-FAIL: help run "r" abbreviation
-Running ./gdb.t10/crossload.exp ...
-PASS: m68k-elf (elf-big) explicit format; loaded
-XFAIL: mips-ecoff (ecoff-bigmips) "ptype v_signed_char" signed
-C types
- === gdb Summary ===
-# of expected passes 5
-# of expected failures 1
-# of unexpected failures 1
-/usr/latest/bin/gdb version 4.6.5 -q
-@end smallexample
-@end cartouche
-
-@node Detail
-@subsection Detailed log
-@cindex detailed log
-
-@code{runtest} also saves a detailed log file @file{@var{tool}.log},
-showing any output generated by tests as well as the summary output.
-For example, after @samp{runtest --tool binutils}, look for a detailed
-log in @file{binutils.log}. Normally, @code{runtest} writes this file
-in your current working directory; use the @samp{--outdir} option to
-select a different directory.
-
-@need 4000
-@noindent
-Here is a brief example showing a detailed log for @sc{g++} tests:
+If you are familiar with GNU software,
+this output should not contain any surprise to you.
+Any errors should be easy to fix for such a simple program.
-@cartouche
-@smallexample
-Test Run By rob on Mon May 25 21:40:43 PDT 1992
+Build the calc executable:
- === g++ tests ===
+@strong{Sample output building calc
+}
---- Running ./g++.other/t01-1.exp ---
- PASS: operate delete
+@example
---- Running ./g++.other/t01-2.exp ---
- FAIL: i960 bug EOF
-p0000646.C: In function `int warn_return_1 ()':
-p0000646.C:109: warning: control reaches end of non-void function
-p0000646.C: In function `int warn_return_arg (int)':
-p0000646.C:117: warning: control reaches end of non-void function
-p0000646.C: In function `int warn_return_sum (int, int)':
-p0000646.C:125: warning: control reaches end of non-void function
-p0000646.C: In function `struct foo warn_return_foo ()':
-p0000646.C:132: warning: control reaches end of non-void function
-
---- Running ./g++.other/t01-4.exp ---
- FAIL: abort
-900403_04.C:8: zero width for bit-field `foo'
---- Running ./g++.other/t01-3.exp ---
- FAIL: segment violation
-900519_12.C:9: parse error before `;'
-900519_12.C:12: Segmentation violation
-/usr/latest/bin/gcc: Internal compiler error: program cc1plus got
-fatal signal
+dgt:~/dejagnu.test$ make
+gcc -DHAVE_CONFIG_H -I. -I. -I. -g -O2 -c calc.c
+gcc -g -O2 -o calc calc.o
+@end example
- === g++ Summary ===
+You prepared a few files and then called some
+commands. Respecting the right order assures a automatic and correctly
+compiled calc program. The following example resumes the correct
+order.
-# of expected passes 1
-# of expected failures 3
-/usr/ps/bin/g++ version cygnus-2.0.1
-@end smallexample
-@end cartouche
+@strong{Creating the calc program using the GNU autotools}
-@node Debug
-@subsection Logging @code{expect} internal actions
-@cindex debug log
+@example
-With the @samp{--debug} option, you can request a log file showing the
-output from @code{expect} itself, running in debugging mode. This file
-(@file{dbg.log}, in the directory where you start @code{runtest}) shows
-each pattern @code{expect} considers in analyzing test output.
+dgt:~/dejagnu.test$ aclocal
+dgt:~/dejagnu.test$ autoconf
+dgt:~/dejagnu.test$ autoheader
+dgt:~/dejagnu.test$ automake --add-missing
+dgt:~/dejagnu.test$ ./configure
+dgt:~/dejagnu.test$ make
-This file reflects each @code{send} command, showing the string sent as
-input to the tool under test; and each @code{expect} command, showing
-each pattern it compares with the tool output.
+@end example
-The log messages for @code{expect} begin with a message of the form
+Play with calc and verify whether it works correctly.
+A sample session might look like this:
-@smallexample
-expect: does @{@var{tool output}@} (spawn_id @var{n}) match pattern
-@{@var{expected pattern}@}?
-@end smallexample
+@example
-@noindent
-For every unsuccessful match, @code{expect} issues a @samp{no} after
-this message; if other patterns are specified for the same
-@code{expect} command, they are reflected also, but without the first
-part of the message (@samp{expect@dots{}match pattern}).
-
-When @code{expect} finds a match, the log for the successful match ends
-with @samp{yes}, followed by a record of the @code{expect} variables set
-to describe a successful match. Here is an excerpt from the debugging
-log for a @sc{gdb} test:
-
-@c FIXME! Why is the second spawn_id shown 0 rather than 6?
-@cartouche
-@smallexample
-send: sent @{break gdbme.c:34\n@} to spawn id 6
-expect: does @{@} (spawn_id 6) match pattern @{Breakpoint.*at.* file
- gdbme.c, line 34.*\(gdb\) $@}? no
-@{.*\(gdb\) $@}? no
-expect: does @{@} (spawn_id 0) match pattern @{<return>@}? no
-@{\(y or n\) @}? no
-@{buffer_full@}? no
-@{virtual@}? no
-@{memory@}? no
-@{exhausted@}? no
-@{Undefined@}? no
-@{command@}? no
-break gdbme.c:34
-Breakpoint 8 at 0x23d8: file gdbme.c, line 34.
-(gdb) expect: does @{break gdbme.c:34\r\nBreakpoint 8 at 0x23d8:
-file gdbme.c, line 34.\r\n(gdb) @} (spawn_id 6) match pattern
-@{Breakpoint.*at.* file gdbme.c, line 34.*\(gdb\) $@}? yes
-expect: set expect_out(0,start) @{18@}
-expect: set expect_out(0,end) @{71@}
-expect: set expect_out(0,string) @{Breakpoint 8 at 0x23d8: file
-gdbme.c, line 34.\r\n(gdb) @}
-expect: set expect_out(spawn_id) @{6@}
-expect: set expect_out(buffer) @{break gdbme.c:34\r\nBreakpoint 8
-at 0x23d8: file gdbme.c, line 34.\r\n(gdb) @}
- PASS: 70 0 breakpoint line number in file
-@end smallexample
-@end cartouche
+dgt:~/dejagnu.test$ ./calc
+calc: version
+Version: 1.1
+calc: add 3 4
+7
+calc: multiply 3 4
+12
+calc: multiply 2 4
+12
+calc: quit
-@noindent
-This example exhibits three properties of @code{expect} and DejaGnu that
-might be surprising at first glance:
+@end example
-@itemize @bullet
-@item
-Empty output for the first attempted match. The first set of attempted
-matches shown ran against the output @samp{@{@}}---that is, no output.
-@code{expect} begins attempting to match the patterns supplied
-immediately; often, the first pass is against incomplete output (or
-completely before all output, as in this case).
+Look at the intentional bug that 2 times 4 equals 12.
-@item
-Interspersed tool output. The beginning of the log entry for the second
-attempted match may be hard to spot: this is because the prompt
-@samp{(gdb) } appears on the same line, just before the @samp{expect:}
-that marks the beginning of the log entry.
+The tests run by DejaGnu need a file called site.exp,
+which is automatically generated if we call "make
+site.exp". This was the purpose of the "AUTOMAKE_OPTIONS =
+dejagnu" in Makefile.am.
-@item
-Fail-safe patterns. Many of the patterns tested are fail-safe patterns
-provided by @sc{gdb} testing utilities, to reduce possible
-indeterminacy. It is useful to anticipate potential variations
-caused by extreme system conditions (@sc{gdb} might issue the message
-@samp{virtual memory exhausted} in rare circumstances), or by changes in
-the tested program (@samp{Undefined command} is the likeliest outcome if
-the name of a tested command changes).
+@strong{Sample output generating a site.exp}
-The pattern @samp{@{<return>@}} is a particularly interesting fail-safe
-to notice; it checks for an unexpected @key{RET} prompt. This may
-happen, for example, if the tested tool can filter output through a
-pager.
+@example
-These fail-safe patterns (like the debugging log itself) are primarily
-useful while developing test scripts. Use the @code{error} procedure to
-make the actions for fail-safe patterns produce messages starting with
-@samp{ERROR} on the @code{runtest} standard output, and in the detailed
-log file.
-@end itemize
+dgt: make site.exp
+dgt:~/dejagnu.test$ make site.exp
+Making a new site.exp file...
+@end example
-@node Tests
-@chapter How To Write a Test Cases
-@cindex writing a test case
-@cindex test case, writing
+@node Our first automated tests, A first remote test, Create a minimal project; e_g_ calc, Getting DejaGnu up and running
+@section Our first automated tests
@menu
-* Writing:: Writing a test case
-* Debugging:: Debugging a test case
-* Adding:: Adding a test case to a test suite
-* Hints:: Hints on writing a test case
-* Variables:: Special variables used by test cases
+* Running the test for the calc example::
+* The various config files or how to avoid warnings::
+* When trouble strikes::
+* Testing "Hello world" locally::
@end menu
-@node Writing
-@section Writing a test case
-
-The easiest way to prepare a new test case is to base it on an existing
-one for a similar situation. There are two major categories of tests:
-batch or interactive. Batch oriented tests are usually easier to write.
-
-The @sc{gcc} tests are a good example of batch oriented tests. All
-@sc{gcc} tests consist primarily of a call to a single common procedure,
-since all the tests either have no output, or only have a few warning
-messages when successfully compiled. Any non-warning output is a test
-failure. All the C code needed is kept in the test directory. The test
-driver, written in @code{expect}, need only get a listing of all the C
-files in the directory, and compile them all using a generic procedure.
-This procedure and a few others supporting for these tests are kept in
-the library module @file{lib/c-torture.exp} in the @sc{gcc} test suite.
-Most tests of this kind use very few @code{expect} features, and are
-coded almost purely in Tcl.
+@node Running the test for the calc example, The various config files or how to avoid warnings, , Our first automated tests
+@subsection Running the test for the calc example
-@noindent
-Writing the complete suite of C tests, then, consisted of these steps:
+Now we are ready to call the automated tests
-@enumerate
-@item
-@cindex Granlund, Torbjorn
-@cindex C torture test
-Copying all the C code into the test directory. These tests were based on
-the C-torture test created by Torbjorn Granlund (on behalf of the Free
-Software Foundation) for @sc{gcc} development.
+@strong{Sample output of runtest in a configured directory}
-@item
-Writing (and debugging) the generic @code{expect} procedures for
-compilation.
+@example
-@item
-Writing the simple test driver: its main task is to search the directory
-(using the Tcl procedure @code{glob} for filename expansion with
-wildcards) and call a Tcl procedure with each filename. It also checks
-for a few errors from the testing procedure.
-@end enumerate
+dgt:~/dejagnu.test$ make check
+make check-DEJAGNU
+make[1]: Entering directory `/home/dgt/dejagnu.test' srcdir=`cd . && pwd`; export srcdir; \
+EXPECT=expect; export EXPECT; \ runtest=runtest; \
+if /bin/sh -c "$runtest --version" > /dev/null 2>&1; then \
+$runtest --tool calc CALC=`pwd`/calc --srcdir ./testsuite ; \
+else echo "WARNING: could not find \`runtest'" 1>&2; :;\
+fi
+WARNING: Couldn't find the global config file.
+WARNING: Couldn't find tool init file
+Test Run By dgt on Sun Nov 25 21:42:21 2001
+Native configuration is i586-pc-linux-gnu
+
+ === calc tests ===
+
+Schedule of variations:
+ unix
+
+Running target unix
+Using /usr/share/dejagnu/baseboards/unix.exp as board description file for target.
+Using /usr/share/dejagnu/config/unix.exp as generic interface file for target.
+Using ./testsuite/config/unix.exp as tool-and-target-specific interface file.
+Running ./testsuite/calc.test/calc.exp ...
+FAIL: multiply2 (bad match)
+
+=== calc Summary ===
-Testing interactive programs is intrinsically more complex. Tests for most
-interactive programs require some trial and error before they are complete.
+# of expected passes 5
+# of unexpected failures 1
+/home/Dgt/dejagnu.test/calc version Version: 1.1
+make[1]: *** [check-DEJAGNU] Fehler 1
+make[1]: Leaving directory `/home/Dgt/dejagnu.test' make: *** [check-am] Fehler 2
+@end example
-However, some interactive programs can be tested in a simple fashion
-reminiscent of batch tests. For example, prior to the creation of
-DejaGnu, the @sc{gdb} distribution already included a wide-ranging
-testing procedure. This procedure was very robust, and had already
-undergone much more debugging and error checking than many recent
-DejaGnu test cases. Accordingly, the best approach was simply to
-encapsulate the existing @sc{gdb} tests, for reporting purposes.
-Thereafter, new @sc{gdb} tests built up a family of @code{expect}
-procedures specialized for @sc{gdb} testing.
+Did you see the line "FAIL:"? The test cases for calc catch the bug in the calc.c file. Fix the error in calc.c later as the following examples assume a unchanged calc.c.
-@file{gdb.t10/crossload.exp} is a good example of an interactive test.
-@c FIXME! Check what *kind* of example it is---work-intensive, or generic...
+Examine the output files calc.sum and calc.log. Try to
+understand the testcases written in
+~/dejagnu.test/testsuite/calc.test/calc.exp. To understand Expect you
+might take a look at the book "Exploring Expect", which is
+an excellent resource for learning and using Expect. (Pub: O'Reilly,
+ISBN 1-56592-090-2) The book contains hundreds of examples and also
+includes a tutorial on Tcl. Exploring Expect is 602 pages
+long.
-@node Debugging
-@section Debugging a test case
-@cindex debugging a test case
-@cindex test case, debugging
+@node The various config files or how to avoid warnings, When trouble strikes, Running the test for the calc example, Our first automated tests
+@subsection The various config files or how to avoid warnings
-@noindent
-These are the kinds of debugging information available from DejaGnu:
-
-@enumerate
-@item
-Output controlled by test scripts themselves, explicitly allowed for by
-the test author. This kind of debugging output appears in the detailed
-output recorded in the @file{@var{tool}.log} file. To do the same for
-new tests, use the @code{verbose} procedure (which in turn uses the
-variable also called @code{verbose}) to control how much output to
-generate. This will make it easier for other people running the test to
-debug it if necessary. Whenever possible, if @samp{$verbose} is
-@code{0}, there should be no output other than the output from
-@code{pass}, @code{fail}, @code{error}, and @code{warning}. Then, to
-whatever extent is appropriate for the particular test, allow
-successively higher values of @samp{$verbose} to generate more
-information. Be kind to other programmers who use your tests: provide
-for a lot of debugging information.
-
-@item
-Output from the internal debugging functions of Tcl and @code{expect}.
-There is a command line options for each; both forms of debugging output
-are recorded in the file @code{dbg.log} in the current directory.
-
-Use @samp{--debug} for information from the @code{expect} level; it
-generates displays of the @code{expect} attempts to match the tool
-output with the patterns specified (@pxref{Debug,,Debug Log}). This
-output can be very helpful while developing test scripts, since it shows
-precisely the characters received. Iterating between the latest attempt
-at a new test script and the corresponding @file{dbg.log} can allow you
-to create the final patterns by ``cut and paste''. This is sometimes
-the best way to write a test case.
-
-Use @samp{--strace} to see more detail at the Tcl level; this shows how Tcl
-procedure definitions expand, as they execute. The associated number
-controls the depth of definitions expanded; see the discussion of
-@samp{--strace} in @ref{Invoking runtest,,Running the Tests}.
-
-@item
-Finally, if the value of @samp{verbose} is 3 or greater, @code{runtest}
-turns on the @code{expect} command @code{log_user}. This command prints
-all @code{expect} actions to the @code{expect} standard output, to the
-detailed log file, and (if @samp{--debug} is on) to @file{dbg.log}.
-@end enumerate
-
-@node Adding
-@section Adding a test case to a test suite
-@cindex adding a test case
-
-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
-directory to hold your test. The existing test directories represent
-several styles of testing, all of which are slightly different; examine
-the directories for the tool of interest to see which (if any) is most
-suitable.
-
-Adding a @sc{gcc} test can be very simple: just add the C code to any
-directory beginning with @samp{gcc.} and it runs on the next
-@samp{runtest --tool gcc}.
-
-To add a test to @sc{gdb}, first add any source code you will need to
-the test directory. Then you can either create a new @code{expect} file,
-or add your test to an existing one (any file with a @samp{.exp}
-suffix). Creating a new @samp{.exp} file is probably a better idea if
-the test is significantly different from existing tests. Adding it as a
-separate file also makes upgrading easier. If the C code has to be
-already compiled before the test will run, then you'll have to add it to
-the @file{Makefile.in} file for that test directory, then run
-@code{configure} and @code{make}.
-
-Adding a test by creating a new directory is very similar:
-
-@enumerate
-@item
-Create the new directory. All subdirectory names begin with the name of
-the tool to test; e.g. @sc{g++} tests might be in a directory called
-@file{g++.other}. There can be multiple test directories that start with
-the same tool name (such as @samp{g++}).
-
-@item
-Add the new directory name to the @samp{configdirs} definition in the
-@file{configure.in} file for the test suite directory. This way when
-@code{make} and @code{configure} next run, they include the new directory.
-
-@item
-Add the new test case to the directory, as above.
-
-@item
-To add support in the new directory for configure and make, you must
-also create a @code{Makefile.in} and a @code{configure.in}. @xref{What
-Configure Does,,What Configure Does, configure.info, Cygnus Configure}.
-@end enumerate
-
-@c FIXME! Expand this sentence to at least a section, maybe a chapter...
-@c The @file{admin} directory contains templates for a few common forms
-@c of test.
-
-@node Hints
-@section Hints on writing a test case
-@cindex hints on test case writing
-
-There may be useful existing procedures already written for your test in
-the @file{lib} directory of the DejaGnu distribution. @xref{DejaGnu
-Builtins,,DejaGnu Builtins}.
-
-It is safest to write patterns that match @emph{all} the output
-generated by the tested program; this is called @dfn{closure}. If a
-pattern does not match the entire output, any output that remains will
-be examined by the @emph{next} @code{expect} command. In this
-situation, the precise boundary that determines which @code{expect}
-command sees what is very sensitive to timing between the @code{expect}
-task and the task running the tested tool. As a result, the test may
-sometimes appear to work, but is likely to have unpredictable results.
-(This problem is particularly likely for interactive tools, but can also
-affect batch tools---especially for tests that take a long time to finish.)
-The best way to ensure closure is to use the @samp{-re} option for the
-@code{expect} command to write the pattern as a full regular
-expressions; then you can match the end of output using a @samp{$}. It
-is also a good idea to write patterns that match all available output by
-using @samp{.*\} after the text of interest; this will also match any
-intervening blank lines. Sometimes an alternative is to match end of
-line using @samp{\r} or @samp{\n}, but this is usually too dependent on
-terminal settings.
-@c FIXME!! explain what "end of output" means for interactive task.
-@c (Timeout or EOF, right?)
-
-Always escape punctuation, such as @samp{(} or @samp{"}, in your
-patterns; for example, write @samp{\(}. If you forget to escape
-punctuation, you will usually see an error message like @samp{extra
-characters after close-quote}.
-
-If you have trouble understanding why a pattern does not match the
-program output, try using the @samp{--debug} option to @code{runtest},
-and examine the debug log carefully. @xref{Debug,,Debug Log}.
-
-Be careful not to neglect output generated by setup rather than by the
-interesting parts of a test case. For example, while testing @sc{gdb},
-I issue a send @samp{set height 0\n} command. The purpose is simply to
-make sure @sc{gdb} never calls a paging program. The @samp{set height}
-command in @sc{gdb} does not generate any output; but running @emph{any}
-command makes @sc{gdb} issue a new @samp{(gdb) } prompt. If there were
-no @code{expect} command to match this prompt, the output @samp{(gdb) }
-begins the text seen by the next @code{expect} command---which might
-make @emph{that} pattern fail to match.
-
-To preserve basic sanity, I also recommended that no test ever pass if
-there was any kind of problem in the test case. To take an extreme
-case, tests that pass even when the tool will not spawn are misleading.
-Ideally, a test in this sort of situation should not fail either.
-Instead, print an error message by calling one of the DejaGnu procedures
-@code{error} or @code{warning}.
+DejaGnu may be customized by each user. It first searches for a
+file called ~/.dejagnurc. Create the file ~/.dejagnurc and insert the
+following line:
-@node Variables
-@section Special variables used by test cases
-@cindex special variables
+@example
-@cindex variables for all tests
-Your test cases can use these variables, with conventional meanings (as
-well as the variables saved in @file{site.exp}
-@pxref{Customizing,,Setting @code{runtest} defaults}):
+puts "I am ~/.dejagnurc"
+@end example
-@quotation
-@emph{These variables are available to all test cases.}
-@end quotation
+Rerun make check. Test whether the output contains "I am ~/.dejagnurc".
+Create ~/my_dejagnu.exp and insert the following line:
-@ftable @code
-@item prms_id
-@cindex PRMS bug number
-@cindex GNATS bug number
-@cindex bug number
-The tracking system (e.g. @sc{gnats}) number identifying a corresponding
-bugreport. (@samp{0} if you do not specify it in the test script.)
+@example
-@item bug_id
-@cindex bug number, extra
-An optional bug id; may reflect a bug identification from another
-organization. (@samp{0} if you do not specify it.)
+puts "I am ~/my_dejagnu.exp"
+@end example
-@item subdir
-@cindex current test subdirectory
-The subdirectory for the current test case.
-@end ftable
+In a Bash-Shell enter
-@quotation
-@emph{These variables should never be changed. They appear in most
-tests.}
-@end quotation
+@example
-@ftable @code
-@item expect_out(buffer)
-@cindex last command output
-The output from the last command. This is an internal variable set by
-@code{expect}.
+dgt:~/dejagnu.test$ export DEJAGNU=~/my_dejagnu.exp
+@end example
-@item exec_output
-This is the output from a @code{@var{tool}_load} command. This only
-applies to tools like @sc{gcc} and @sc{gas} which produce an object
-file that must in turn be executed to complete a test.
+Run "make check" again. The output should not contain
+"WARNING: Couldn't find the global config file.".
+Create the sub-directory lib. Create the file "calc.exp" in it and insert the following line:
-@item comp_output
-This is the output from a @code{@var{tool}_start} command. This is
-conventionally used for batch oriented programs, like @sc{gcc} and
-@sc{gas}, that may produce interesting output (warnings, errors) without
-further interaction.
-@end ftable
+@example
-@node Extending
-@chapter New Tools, Targets, or Hosts
+puts "I am lib/calc.exp"
+@end example
-The most common ways to extend the DejaGnu framework are: adding a suite
-of tests for a new tool to be tested; adding support for testing on a
-new target; and porting @code{runtest} to a new host.
+The last warning "WARNING: Couldn't find tool init file"
+should not be part of the output of make check.
+Create the directory ~/boards. Create the file ~/boards/standard.exp and insert the following line:
-@menu
-* Adding Tools:: How to add tests for a new tool
-* Adding Targets:: How to add a new target
-* Porting:: Porting DejaGnu to a new host
-@end menu
+@example
-@node Adding Tools
-@section Writing tests for a new tool
+puts "I am boards/standard.exp"
+@end example
-In general, the best way to learn how to write (code or even prose) is
-to read something similar. This principle applies to test cases and to
-test suites. Unfortunately, well-established test suites have a way of
-developing their own conventions: as test writers become more
-experienced with DejaGnu and with Tcl, they accumulate more utilities,
-and take advantage of more and more features of @code{expect} and Tcl in
-general.
+If the variable DEJAGNU is still not empty then the (abbreviated) output of "make check" should look like this:
+
+@strong{Sample output of runtest with the usual configuration files}
-Inspecting such established test suites may make the prospect of
-creating an entirely new test suite appear overwhelming. Nevertheless,
-it is quite straightforward to get a new test suite going.
+@example
+
+dgt:~/dejagnu.test$ make check
+<...>
+fi
+I am ~/.dejagnurc
+I am ~/my_dejagnu.exp
+I am lib/calc.exp
+Test Run By dgt on Sun Nov 25 22:19:14 2001
+Native configuration is i586-pc-linux-gnu
+
+ === calc tests ===
+Using /home/Dgt/boards/standard.exp as standard board description\
+file for build.
+I am ~/boards/standard.exp
+Using /home/Dgt/boards/standard.exp as standard board description\
+ file for host.
+I am ~/boards/standard.exp
+
+Schedule of variations:
+ unix
+
+Running target unix
+Using /home/Dgt/boards/standard.exp as standard board description\
+ file for target.
+I am ~/boards/standard.exp
+Using /usr/share/dejagnu/baseboards/unix.exp as board description file\
+for target.
+<...>
+@end example
-@cindex Lupton, Robert
-There is one test suite that is guaranteed not to grow more elaborate
-over time: both it and the tool it tests were created expressly to
-illustrate what it takes to get started with DejaGnu. The
-@file{example/} directory of the DejaGnu distribution contains both an
-interactive tool called @code{calc}, and a test suite for it. Reading
-this test suite, and experimenting with it, is a good way to supplement
-the information in this section. (Thanks to Robert Lupton for creating
-@code{calc} and its test suite---and also the first version of this
-section of the manual!)
+It is up to you to decide when and where to use any of the above
+mentioned config files for customizing.
+This chapters showed you where and in which order the different config
+files are run.
-To help orient you further in this task, here is an outline of the steps
-to begin building a test suite for a program @var{example}.
+@node When trouble strikes, Testing "Hello world" locally, The various config files or how to avoid warnings, Our first automated tests
+@subsection When trouble strikes
-@enumerate
-@item
-Create or select a directory to contain your new collection of tests.
-Change to that directory (shown here as @code{testsuite}):
+Calling runtest with the '-v'-flag shows you in even more details which files are searched in which order. Passing it several times gives more and more details.
+
+@strong{Displaying details about runtest execution}
@example
-eg$ cd testsuite/
+
+runtest -v -v -v --tool calc CALC=`pwd`/calc --srcdir ./testsuite
@end example
-@item
-Create a @file{configure.in} file in this directory, to control
-configuration-dependent choices for your tests. So far as DejaGnu is
-concerned, the important thing is to set a value for the variable
-@code{target_abbrev}; this value is the link to the init file you will
-write soon. (For simplicity, we assume the environment is Unix, and use
-@samp{unix} as the value.)
+Calling runtest with the '--debug'-flag logs a lot of details to dbg.log where you can analyse it afterwards.
-What else is needed in @file{configure.in} depends on the requirements
-of your tool, your intended test environments, and which
-@code{configure} system you use. This example is a minimal
-@code{configure.in} for use with Cygnus Configure. (For an alternative
-based on the FSF @code{autoconf} system, see the @code{calc} example
-distributed with DejaGnu.) Replace @var{example} with the name of your
-program:
+In all test cases you can temporary adjust the verbosity of information by adding the following Tcl-command to any tcl file that gets loaded by
+dejagnu, for instance, ~/.dejagnurc:
-@cartouche
-@smallexample
-# This file is a shell script fragment
-# for use with Cygnus configure.
+@example
-srctrigger="@var{example}.0"
-srcname="The DejaGnu @var{example} tests"
+set verbose 9
+@end example
-# per-host:
+@node Testing "Hello world" locally, , When trouble strikes, Our first automated tests
+@subsection Testing "Hello world" locally
-# per-target:
+This test checks, whether the built-in shell command "echo Hello world"
+will really write "Hello world" on the console.
+Create the file ~/dejagnu.test/testsuite/calc.test/local_echo.exp.
+It should contain the following lines
-# everything defaults to unix for a target
-target_abbrev=unix
+@strong{A first (local) test case}
-# post-target:
+@example
-@end smallexample
-@end cartouche
+set test "Local Hello World"
+send "echo Hello World"
+expect @{
+ -re "Hello World" @{ pass "$test" @}
+@}
+@end example
-@item
-Create @file{Makefile.in}, the source file used by @code{configure} to
-build your @file{Makefile}. Its leading section should as usual contain
-the values that @code{configure} may override:
+Run runtest again and verify the output "calc.log"
-@cartouche
-@smallexample
-srcdir = .
-prefix = /usr/local
+@node A first remote test, , Our first automated tests, Getting DejaGnu up and running
+@section A first remote test
-exec_prefix = $(prefix)
-bindir = $(exec_prefix)/bin
-libdir = $(exec_prefix)/lib
-tooldir = $(libdir)/$(target_alias)
+Testing remote targets is a lot trickier especially if you are using an
+embedded target
+which has no built in support for things like a compiler, ftp server or a Bash-shell.
+Before you can test calc on a remote target you have to acquire a few basics skills.
-datadir = $(exec_prefix)/lib/dejagnu
+@menu
+* Setup telnet to your own host::
+* A test case for login via telnet::
+* Remote testing "Hello world"::
+* Transferring files from/to the target::
+* Preparing for crosscompilation::
+* Remote testing of calc::
+* Using Windows as host and vxWorks as target::
+@end menu
-RUNTEST = runtest
-RUNTESTFLAGS =
-FLAGS_TO_PASS =
+@node Setup telnet to your own host, A test case for login via telnet, , A first remote test
+@subsection Setup telnet to your own host
-#### host, target, site specific Makefile frags come in here.
-@end smallexample
-@end cartouche
+The easiest remote host is usually the host you are working on.
+In this example we will use telnet to login in your own workstation.
+For security reason you should never have a telnet deamon running on
+machine connected on the internet, as password and usernames are transmitted
+in clear text.
+We assume you know how to setup your machine for a telnet daemon.
-This should be followed by the standard targets at your site. To begin
-with, they need not do anything---for example, these definitions will
-do:
+Next try whether you may login in your own host by issuing the
+command "telnet localhost.1". In order to be able to
+distinguish between a normal session an a telnet login add the following lines to /home/dgt/.bashrc.
-@cartouche
-@smallexample
+@example
-all:
+if [ "$REMOTEHOST" ]
+then
+ PS1='remote:\w\$ '
+fi
+@end example
-info:
+Now on the machine a "remote" login looks like this:
-install-info:
+@strong{Sample log of a telnet login to localhost}
-install:
-uninstall:
+@example
-clean:
- -rm -f *~ core *.info*
+dgt:~/dejagnu.test$ telnet localhost
+Trying 127.0.0.1...
+Connected to 127.0.0.1.
+Escape character is '^]'.
+Debian GNU/Linux testing/unstable Linux
+K6Linux login: dgt
+Password:
+Last login: Sun Nov 25 22:46:34 2001 from localhost on pts/4
+Linux K6Linux 2.4.14 #1 Fre Nov 16 19:28:25 CET 2001 i586 unknown
+No mail.
+remote:~$ exit
+logout
+Connection closed by foreign host.
+@end example
-@end smallexample
-@end cartouche
+@node A test case for login via telnet, Remote testing "Hello world", Setup telnet to your own host, A first remote test
+@subsection A test case for login via telnet
-It is also a good idea to make sure your @file{Makefile} can rebuild
-itself if @file{Makefile.in} changes, with a target like this (which
-works for either Cygnus or FSF Configure):
+In order to define a correct setup we have add a line containing
+"set target unix" either to ~/.dejagnurc or to ~/my_dejagnu.exp.
+In ~/boards/standard.exp add the following four lines to define a few patterns for the DejaGnu telnet login procedure.
-@cartouche
-@smallexample
-Makefile : $(srcdir)/Makefile.in $(host_makefile_frag) \
- $(target_makefile_frag)
- $(SHELL) ./config.status
-@end smallexample
-@end cartouche
+@strong{Defining a remote target board}
-You also need to include two targets important to DejaGnu: @code{check},
-to run the tests, and @code{site.exp}, to set up the Tcl copies of
-configuration-dependent values. The @code{check} target must run
-@samp{runtest --tool @var{example}}:
+@example
-@cartouche
-@smallexample
-check: site.exp all
- $(RUNTEST) $(RUNTESTFLAGS) $(FLAGS_TO_PASS) \
- --tool @var{example} --srcdir $(srcdir)
-@end smallexample
-@end cartouche
+set_board_info shell_prompt "remote:"
+set_board_info telnet_username "dgt"
+set_board_info telnet_password "top_secret"
+set_board_info hostname "localhost"
-The @code{site.exp} target should usually set up (among other things!) a
-Tcl variable for the name of your program:
+@end example
-@cartouche
-@smallexample
-site.exp: ./config.status Makefile
- @@echo "Making a new config file..."
- -@@rm -f ./tmp?
- @@touch site.exp
+As DejaGnu will be parsing the telnet session output for some well
+known pattern the output there are a lot of things that can go wrong.
+If you have any problems verify your setup:
- -@@mv site.exp site.bak
- @@echo "## these variables are automatically\
- generated by make ##" > ./tmp0
- @@echo "# Do not edit here. If you wish to\
- override these values" >> ./tmp0
- @@echo "# add them to the last section" >> ./tmp0
- @@echo "set host_os $@{host_os@}" >> ./tmp0
- @@echo "set host_alias $@{host_alias@}" >> ./tmp0
- @@echo "set host_cpu $@{host_cpu@}" >> ./tmp0
- @@echo "set host_vendor $@{host_vendor@}" >> ./tmp0
- @@echo "set target_os $@{target_os@}" >> ./tmp0
- @@echo "set target_alias $@{target_alias@}" >> ./tmp0
- @@echo "set target_cpu $@{target_cpu@}" >> ./tmp0
- @@echo "set target_vendor $@{target_vendor@}" >> ./tmp0
- @@echo "set host_triplet $@{host_canonical@}" >> ./tmp0
- @@echo "set target_triplet $@{target_canonical@}">>./tmp0
- @@echo "set tool binutils" >> ./tmp0
- @@echo "set srcdir $@{srcdir@}" >> ./tmp0
- @@echo "set objdir `pwd`" >> ./tmp0
- @@echo "set @var{examplename} @var{example}" >> ./tmp0
- @@echo "## All variables above are generated by\
- configure. Do Not Edit ##" >> ./tmp0
- @@cat ./tmp0 > site.exp
- @@sed < site.bak \
- -e '1,/^## All variables above are.*##/ d' \
- >> site.exp
- -@@rm -f ./tmp?
-@end smallexample
-@end cartouche
+@itemize @bullet{}
@item
-Create a directory (in @file{testsuite/}) called @file{config/}:
+Is @file{/etc/motd} empty?
-@example
-eg$ mkdir config
-@end example
+@item
+Is @file{/etc/issue.net} empty?
@item
-Make an init file in this directory; its name must start with the
-@code{target_abbrev} value, so call it @file{config/unix.exp}.
-This is the file that contains the target-dependent procedures;
-fortunately, most of them do not have to do very much in order for
-@code{runtest} to run.
+Exists a empty @file{~/.hushlogin}?
-If @var{example} is not interactive, you can get away with this minimal
-@file{unix.exp} to begin with:
+@item
+The LANG environment variable must be either empty or set to "C".
+@end itemize
-@cartouche
-@smallexample
-proc foo_exit @{@} @{@}
-proc foo_version @{@} @{@}
-@end smallexample
-@end cartouche
+To test the login via telnet write a sample test case.
+Create the file ~/dejagnu.test/testsuite/calc.test/remote_echo.exp and
+add the following few lines:
-If @var{example} is interactive, however, you might as well define a
-start routine @emph{and invoke it} by using an init file like this:
+@strong{DejaGnu script for logging in into a remote target}
-@cartouche
-@smallexample
-proc foo_exit @{@} @{@}
-proc foo_version @{@} @{@}
+@example
-proc foo_start @{@} @{
- global @var{examplename}
- spawn $@var{examplename}
- expect @{
- -re "" @{@}
- @}
+puts "this is remote_echo.exp target for $target "
+target_info $target
+#set verbose 9
+set shell_id [remote_open $target]
+set test "Remote login to $target"
+#set verbose 0
+puts "Spawn id for remote shell is $shell_id"
+if @{ $shell_id > 0 @} @{
+ pass "$test"
+@} else @{
+ fail "Remote open to $target"
@}
-foo_start
-@end smallexample
-@end cartouche
+@end example
-@item
-Create a directory whose name begins with your tool's name, to contain
-tests:
+In the runtest output you should find something like:
@example
-eg$ mkdir @var{example}.0
+
+Running ./testsuite/calc.test/local_echo.exp ...
+Running ./testsuite/calc.test/remote_echoo.exp ...
+this is remote_echo.exp target is unix
+Spawn id for remote shell is exp7
@end example
-@item
-Create a sample test file in @file{@var{example}.0}. Its name must end
-with @samp{.exp}; you can use @samp{first-try.exp} To begin with, just
-write there a line of Tcl code to issue a message:
+Have again a look at calc.log to get a feeling how DejaGnu and expect
+parse the input.
-@cartouche
-@smallexample
-send_user "Testing: one, two...\n"
-@end smallexample
-@end cartouche
+@node Remote testing "Hello world", Transferring files from/to the target, A test case for login via telnet, A first remote test
+@subsection Remote testing "Hello world"
-@item
-Back in the @file{testsuite/} (top level) directory, run
+Next you will transform the above "hello world" example to
+its remote equivalent.
+This can be done by adding the following lines to our file remote_echo.exp.
+
+@strong{A first (local) remote "Hello world" test}
@example
-eg$ configure
+
+set test "Remote_send Hello World"
+set status [remote_send $target "echo \"Hello\" \"World\"\n" ]
+pass "$test"
+set test "Remote_expect Hello World"
+remote_expect $target 5 @{
+ -re "Hello World" @{ pass "$test" @}
+@}
@end example
-(You may have to specify more of a path, if a suitable @code{configure}
-is not available in your execution path.)
+Call make check. The output should contain
+"# of expected passes 9" and "# of unexcpected failures 1".
-@item
-You are now ready to triumphantly type @samp{make check} or
-@samp{runtest --tool @var{example}}. You should see something like this:
+Have a look at the procedures in /usr/share/dejagnu/remote.exp to have an overview of the offered procedures and their features.
-@cartouche
-@smallexample
-Test Run By rhl on Fri Jan 29 16:25:44 EST 1993
+Now setup a real target.
+In the following example we assume as target a PowerBook running Debian.
+As above add a test user "dgt", install telnet and FTP servers.
+In order to distinguish it from the host add the line
- === @var{example} tests ===
+@example
+PS1='test:>'
+@end example
-Running ./@var{example}.0/first-try.exp ...
-Testing: one, two...
+@noindent
+to /home/dgt/.bash_profile.
+Also add a corresponding entry "powerbook" to /etc/hosts and verify that you
+are able to ping, telnet and ftp to the target "powerbook".
- === @var{example} Summary ===
+In order to let runtest run its test on the "powerbook" target change the following lines in ~/boards/standard.exp:
-@end smallexample
-@end cartouche
+@strong{Board definition for a remote target}
-There is no output in the summary, because so far the example does not
-call any of the procedures that establish a test outcome.
+@example
-@item
-Begin writing some real tests. For an interactive tool, you should
-probably write a real exit routine in fairly short order; in any case,
-you should also write a real version routine soon.
-@end enumerate
+set_board_info protocol "telnet"
+set_board_info telnet_username "dgt"
+set_board_info telnet_password "top_secret"
+set_board_info shell_prompt "test:> "
+set_board_info hostname "powerbook"
+@end example
-@node Adding Targets
-@section Adding a target
-@cindex adding a target
+Now call runtest again with the same arguments and verify whether all went okay by taking a close look at calc.log.
-DejaGnu has some additional requirements for target support, beyond the
-general-purpose provisions of Cygnus @code{configure}. @code{runtest}
-must actively communicate with the target, rather than simply generating
-or managing code for the target architecture. Therefore, each tool
-requires an initialization module for each target. For new targets, you
-must supply a few Tcl procedures to adapt DejaGnu to the target. This
-permits DejaGnu itself to remain target independent. @xref{Init
-Module,,Initialization module}, for a discussion of the naming
-conventions that enable DejaGnu to locate and use init files.
+@node Transferring files from/to the target, Preparing for crosscompilation, Remote testing "Hello world", A first remote test
+@subsection Transferring files from/to the target
-Usually the best way to write a new initialization module is to edit an
-existing initialization module; some trial and error will be required.
-If necessary, you can use the @samp{--debug} option to see what
-is really going on.
+A simple procedure like this will do the job for you:
-When you code an initialization module, be generous in printing
-information controlled by the @code{verbose} procedure (@pxref{DejaGnu
-Builtins, DejaGnu procedures}).
+@strong{Test script to transfer a file to a remote target}
-Most of the work is in getting the communications right. Communications
-code (for several situations involving IP networks or serial lines) is
-available in a DejaGnu library file, @file{lib/remote.exp}.
-@xref{DejaGnu Builtins,,DejaGnu Builtins}.
+@example
-@c FIXME! Say something about Tcl debugger here.
-If you suspect a communication problem, try running the connection
-interactively from @code{expect}. (There are three ways of running
-@code{expect} as an interactive interpreter. You can run @code{expect}
-with no arguments, and control it completely interactively; or you can
-use @samp{expect -i} together with other command-line options and
-arguments; or you can run the command @code{interpreter} from any
-@code{expect} procedure. Use @code{return} to get back to the calling
-procedure (if any), or @code{return -tcl} to make the calling procedure
-itself return to its caller; use @code{exit} or end-of-file to leave
-@code{expect} altogether.) Run the program whose name is recorded in
-@samp{$connectmode}, with the arguments in @samp{$targetname}, to
-establish a connection. You should at least be able to get a prompt
-from any target that is physically connected.
-
-@node Porting
-@section Porting to a new host
-@cindex porting to a new host
-
-The task of porting DejaGnu is basically that of porting Tcl and
-@code{expect}. Tcl and @code{expect}, as distributed with DejaGnu, both
-use @code{autoconf}; they should port automatically to most Unix
-systems.
-
-Once Tcl and @code{expect} are ported, DejaGnu should run. Most system
-dependencies are taken care of by using @code{expect} as the main
-command shell.
-
-@node Installation
-@appendix Installing DejaGnu
-
-@cindex host, explained
-@cindex target, explained
-@cindex DejaGnu configuration
-@cindex configuring DejaGnu
-Once you have the DejaGnu source unpacked and available, you must first
-configure the software to specify where it is to run (and the associated
-defaults); then you can proceed to installing it.
+set test "Remote_download"
+puts "Running Remote_download"
+# set verbose 9
+set remfile /home/dgt/dejagnu2
-@menu
-* Configuring DejaGnu::
-* Installing DejaGnu::
-@end menu
+set status [remote_download $target /home/dgt/.dejagnurc $remfile]
+if @{ "$status" == "" @} @{
+ fail "Remote download to $remfile on $target"
+@} else @{
+ pass "$test"
+@}
-@node Configuring DejaGnu
-@section Configuring the DejaGnu test driver
+puts "status of remote_download ist $status"
+# set verbose 0
+@end example
-It is usually best to configure in a directory separate
-from the source tree, specifying where to find the source with the
-optional @samp{--srcdir} option to @code{configure}. DejaGnu uses the
-GNU @code{autoconf} to configure itself. For more info on using
-autoconf, read the GNU autoconf manual. To configure, execute the
-@file{configure} program, no other options are required. For an example,
-to configure in a seperate tree for objects, execute the configure
-script from the source tree like this:
-
-@smallexample
-../dejagnu-1.3/configure
-@end smallexample
-
-DejaGnu doesn't care at config time if it's for testing a native system
-or a cross system. That is determined at runtime by using the config
-files.
-
-@cindex @code{prefix}, configure options
-@cindex @code{exec_prefix}, configure options.
-You may also want to use the @code{configure} option @samp{--prefix} to
-specify where you want DejaGnu and its supporting code installed. By
-default, installation is in subdirectories of @file{/usr/local}, but you
-can select any alternate directory @var{altdir} by including
-@samp{--prefix=@var{altdir}} on the @code{configure} command line.
-(This value is captured in the Makefile variables @code{prefix}
-and @code{exec_prefix}.)
-
-@cindex auxiliary programs
-@cindex test suite distributions
-@cindex @code{make} builds part of tests
-Save for a small number of example tests, the DejaGnu distribution
-itself does not include any test suites; these are available separately.
-Test suites for the @sc{gnu} compiler (testing both GCC and G++) and for
-the @sc{gnu} binary utilities are distributed in parallel with the
-DejaGnu distribution (but packaged as separate files). The test suite
-for the @sc{gnu} debugger is distributed in parallel with each release
-of GDB itself, starting with GDB 4.9. After configuring the top-level
-DejaGnu directory, unpack and configure the test directories for the
-tools you want to test; then, in each test directory, run @code{make} to
-build auxiliary programs required by some of the tests.
+After running runtest again, check whether the file dejagnu2 exists on the target.
+This example will only work if the rcp command works with your target.
+If you have a working FTP-server on the target you can use it by adding the
+following lines to ~/boards/standard.exp:
-@node Installing DejaGnu
-@section Installing DejaGnu
+@strong{Defining a board to use FTP as file transport}
-@cindex installing DejaGnu
-To install DejaGnu in your filesystem (either in @file{/usr/local}, or
-as specified by your @samp{--prefix} option to @code{configure}), execute
+@example
+
+set_board_info file_transfer "ftp"
+set_board_info ftp_username "dgt"
+set_board_info ftp_password "1234"
+@end example
+
+@node Preparing for crosscompilation, Remote testing of calc, Transferring files from/to the target, A first remote test
+@subsection Preparing for crosscompilation
+
+For crosscompiling you need working binutils, gcc and a base library like
+libc or glib for your target.
+It is beyond the scope of this document to describe how to get it working.
+The following examples assume a cross compiler for PowerPC which is called linux-powerpc-gcc.
+
+Add AC_CANONICAL_TARGET in dejagnu.test/configure.in at the following location. Copy config.guess from /usr/share/automake to dejagnu.test.
+
+@example
+
+AM_CONFIG_HEADER(calc.h)
+AC_CANONICAL_TARGET([])
+AM_INIT_AUTOMAKE(calc, 1.1)
+@end example
+
+You need to run automake 2.5 or later.
+Depending on your installation calling autoconf2.5 instead of autoconf is not needed.
+The sequence to regenerate all files is:
+
+@strong{Using autotools for cross development}
+
+@example
+
+$ autoconf2.5
+$ autoheader
+$ automake
+$ ./configure --host=powerpc-linux --target=powerpc-linux
+configure: WARNING: If you wanted to set the --build type, don't use --host.
+ If a cross compiler is detected then cross compile mode will be used.
+checking build system type... ./config.guess: ./config.guess: No such file or directory
+configure: error: cannot guess build type; you must specify one
+$ cp /usr/share/automake/config.guess .
+$ ./configure --host=powerpc-linux --target=powerpc-linux
+configure: WARNING: If you wanted to set the --build type, don't use --host.
+If a cross compiler is detected then cross compile mode will be used. \
+checking build system type... i586-pc-linux-gnu
+checking host system type... powerpc-unknown-linux-gnu
+<...>
+checking whether we are cross compiling... yes
+<...>
+Configuration:
+Source code location: .
+C Compiler: powerpc-linux-gcc
+C Compiler flags: -g -O2
+
+@end example
+
+Everything should be ready to recompile for the target:
+
+@example
+$ make
+powerpc-linux-gcc -DHAVE_CONFIG_H -I. -I. -I. -g -O2 -c calc.c
+powerpc-linux-gcc -g -O2 -o calc calc.o
+
+@end example
+
+@node Remote testing of calc, Using Windows as host and vxWorks as target, Preparing for crosscompilation, A first remote test
+@subsection Remote testing of calc
+
+Not yet written, as I have problem getting libc6-dev-powerpc to work. Probably I first have to build my cross compiler.
+
+@node Using Windows as host and vxWorks as target, , Remote testing of calc, A first remote test
+@subsection Using Windows as host and vxWorks as target
+
+A more thorough walk-through will be written in a few weeks.
+
+In order to test the vxWorks as a target I changed boards/standards.exp to reflect my settings (IP, username, password). Then I reconfigured vxWorks to include a FTP and telnet server (using the same username/password combination ad in boards/standard.exp).
+
+With this setup and some minor modification (e.g. replacing echo by printf) in my test cases I could test my vxWorks system. It sure does not seem to be a correct setup by DejaGnu standard. For instance, it still loading /usr/share/dejagnu/baseboards/unix.exp instead of vxWorks. In any case I found that (at least under Windows) I did not find out how the command line would let me override settings in my personal config files.
+
+@node Running Tests, Customizing DejaGnu, Getting DejaGnu up and running, Top
+@chapter Running Tests
+
+There are two ways to execute a testsuite. The most
+common way is when there is existing support in the
+@file{Makefile}. This support consists of a
+@i{check} target. The other way is to execute the
+@code{runtest} program directly. To run
+@code{runtest} directcly from the command line requires
+either all the correct options, or the @ref{Local Config File,,Local Config File}. must be setup
+correctly.
+
+@menu
+* Make check: Make Check.
+* Runtest::
+* The files DejaGnu produces_: Output Files.
+@end menu
+
+@node Make Check, Runtest, , Running Tests
+@section Make check
+
+To run tests from an existing collection, first use
+@code{configure} as usual to set up the
+build directory. Then try typing:
+
+@example
+
+ make check
+
+@end example
+
+If the @i{check} target exists, it
+usually saves you some trouble. For instance, it can set up any
+auxiliary programs or other files needed by the tests. The most
+common file the check builds is the
+@i{site.exp}. The site.exp file contains
+various variables that DejaGnu used to dertermine the
+configuration of the program being tested. This is mostly for
+supporting remote testing.
+
+The @i{check} target is supported by GNU
+Automake. To have DejaGnu support added to your
+generated @file{Makefile.in}, just add the keyword
+dejagnu to the AUTOMAKE_OPTIONS variable in your
+@file{Makefile.am} file.
+
+Once you have run @i{make check} to build
+any auxiliary files, you can invoke the test driver
+@code{runtest} directly to repeat the tests.
+You will also have to execute @code{runtest}
+directly for test collections with no
+@i{check} target in the
+@file{Makefile}.
+
+@node Runtest, Output Files, Make Check, Running Tests
+@section Runtest
+
+@code{runtest} is the executable test driver
+for DejaGnu. You can specify two kinds of things on the
+@code{runtest} command line: command line options,
+and Tcl variables for the test scripts. The options are listed
+alphabetically below.
+
+@code{runtest} returns an exit code of
+@i{1} if any test has an unexpected result; otherwise
+(if all tests pass or fail as expected) it returns @i{0}
+as the exit code.
+
+@menu
+* Output States::
+* Invoking Runtest::
+* Common Options: Common Operations.
+@end menu
+
+@node Output States, Invoking Runtest, , Runtest
+@subsection Output States
+
+@file{runtest} flags the outcome of each
+test as one of these cases. @ref{A POSIX Conforming Test Framework,,A POSIX Conforming Test Framework}. for a
+discussion of how POSIX specifies the meanings of these
+cases.
+
+@table @asis
+
+@item PASS
+The most desirable outcome: the test succeeded, and
+was expected to succeed.
+
+@item XPASS
+A pleasant kind of failure: a test was expected to
+fail, but succeeded. This may indicate progress; inspect the test
+case to determine whether you should amend it to stop expecting
+failure.
+
+@item FAIL
+A test failed, although it was expected to succeed.
+This may indicate regress; inspect the test case and the failing
+software to ocate the bug.
+
+@item XFAIL
+A test failed, but it was expected to fail. This
+result indicates no change in a known bug. If a test fails because
+the operating system where the test runs lacks some facility required
+by the test, the outcome is @i{UNSUPPORTED}
+instead.
+
+@item UNRESOLVED
+Output from a test requires manual inspection; the
+testsuite could not automatically determine the outcome. For
+example, your tests can report this outcome is when a test does not
+complete as expected.
+
+@item UNTESTED
+A test case is not yet complete, and in particular
+cannot yet produce a @i{PASS} or
+@i{FAIL}. You can also use this outcome in dummy
+``tests'' that note explicitly the absence of a real test case for a
+particular property.
+
+@item UNSUPPORTED
+A test depends on a conditionally available feature
+that does not exist (in the configured testing environment). For
+example, you can use this outcome to report on a test case that does
+not work on a particular target because its operating system support
+does not include a required subroutine.
+@end table
+
+runtest may also display the following messages:
+
+@table @asis
+
+@item ERROR
+Indicates a major problem (detected by the test case
+itself) in running the test. This is usually an unrecoverable error,
+such as a missing file or loss of communication to the target. (POSIX
+testsuites should not emit this message; use
+@i{UNSUPPORTED}, @i{UNTESTED}, or
+@i{UNRESOLVED} instead, as
+appropriate.)
+
+@item WARNING
+Indicates a possible problem in running the
+test. Usually warnings correspond to recoverable errors, or display
+an important message about the following tests.
+
+@item NOTE
+An informational message about the test
+case.
+@end table
+
+@node Invoking Runtest, Common Operations, Output States, Runtest
+@subsection Invoking Runtest
+
+This is the full set of command line options that
+@file{runtest} recognizes. Arguments may be
+abbreviated to the shortest unique string.
+
+@table @asis
+
+@item @code{--all} (-a)
+Display all test output. By default,
+@i{runtest} shows only the output of tests that
+produce unexpected results; that is, tests with status
+@i{FAIL} (unexpected failure),
+@i{XPASS} (unexpected success), or
+@i{ERROR} (a severe error in the test case
+itself). Specify @i{--all} to see output for tests
+with status @i{PASS} (success, as expected)
+@i{XFAIL} (failure, as expected), or
+@i{WARNING} (minor error in the test case
+itself).
+
+@item @code{--build [string]}
+@i{string} is a full configuration
+``triple'' name as used by @code{configure}. This
+is the type of machine DejaGnu and the tools to be tested are built
+on. For a normal cross this is the same as the host, but for a
+canadian cross, they are seperate.
+
+@item @code{--host [string]}
+@code{string} is a full configuration
+``triple'' name as used by @i{configure}. Use this
+option to override the default string recorded by your
+configuration's choice of host. This choice does not change how
+anything is actually configured unless --build is also specified; it
+affects @i{only} DejaGnu procedures that compare the
+host string with particular values. The procedures
+@i{ishost}, @i{istarget},
+@i{isnative}, and @i{setup}xfail@}
+are affected by @i{--host}. In this usage,
+@i{host} refers to the machine that the tests are to
+be run on, which may not be the same as the
+@i{build} machine. If @i{--build}
+is also specified, then @i{--host} refers to the
+machine that the tests wil, be run on, not the machine DejaGnu is run
+on.
+
+@item @code{--host_board [name]}
+The host board to use.
+
+@item @code{--target [string]}
+Use this option to override the default setting
+(running native tests). @i{string} is a full
+configuration ``triple'' name of the form
+@i{cpu-vendor-os} as used by
+@code{configure}. This option changes the
+configuration @i{runtest} uses for the default tool
+names, and other setup information.
+
+@item @code{--debug} (-de)
+Turns on the @i{expect} internal
+debugging output. Debugging output is displayed as part of the
+@i{runtest} output, and logged to a file called
+@file{dbg.log}. The extra debugging output does
+@i{not} appear on standard output, unless the
+verbose level is greater than 2 (for instance, to see debug output
+immediately, specify @i{--debug}-v -v@}). The
+debugging output shows all attempts at matching the test output of
+the tool with the scripted patterns describing expected output. The
+output generated with @i{--strace} also goes into
+@file{dbg.log}.
+
+@item @code{--help} (-he)
+Prints out a short summary of the
+@i{runtest} options, then exits (even if you also
+specify other options).
+
+@item @code{--ignore [name(s)] }
+The names of specific tests to
+ignore.
+
+@item @code{--objdir [path]}
+Use @i{path} as the top directory
+containing any auxiliary compiled test code. This defaults to
+@file{.}. Use this option to locate pre-compiled test
+code. You can normally prepare any auxiliary files needed with
+@i{make}.
+
+@item @code{--outdir [path]}
+Write output logs in directory
+@file{path}. The default is @i{.@},
+the} directory where you start
+@i{runtest}. This option affects only the summary
+and the detailed log files
+@file{tool.sum} and
+@file{tool.log}. The DejaGnu debug
+log @file{dbg.log} always appears (when requested) in
+the local directory.
+
+@item @code{--reboot [name]}
+Reboot the target board when
+@i{runtest} initializes. Usually, when running tests
+on a separate target board, it is safer to reboot the target to be
+certain of its state. However, when developing test scripts,
+rebooting takes a lot of time.
+
+@item @code{--srcdir [path]}
+Use @file{path} as the top directory
+for test scripts to run. @i{runtest} looks in this
+directory for any subdirectory whose name begins with the toolname
+(specified with @i{--tool}). For instance, with
+@i{--tool}gdb@}, @i{runtest} uses
+tests in subdirectories @file{gdb.*} (with the usual
+shell-like filename expansion). If you do not use
+@i{--srcdir}, @i{runtest} looks for
+test directories under the current working
+directory.
+
+@item @code{--strace [number]}
+Turn on internal tracing for
+@i{expect}, to n levels deep. By adjusting the
+level, you can control the extent to which your output expands
+multi-level Tcl statements. This allows you to ignore some levels of
+@i{case} or @i{if} statements.
+Each procedure call or control structure counts as one ``level''. The
+output is recorded in the same file, @file{dbg.log},
+used for output from @i{--debug}.
+
+@item @code{--connect [program]}
+Connect to a target testing environment as specified
+by @i{type}, if the target is not the computer
+running @i{runtest}. For example, use
+@i{--connect} to change the program used to connect
+to a ``bare board'' boot monitor. The choices for
+@i{type} in the DejaGnu 1.4 distribution are
+@i{rlogin}, @i{telnet},
+@i{rsh}, @i{tip},
+@i{kermit}, and @i{mondfe}.
+
+The default for this option depends on the configuration most
+convenient communication method available, but often other
+alternatives work as well; you may find it useful to try alternative
+connect methods if you suspect a communication problem with your
+testing target.
+
+@item @code{--baud [number]}
+Set the default baud rate to something other than
+9600. (Some serial interface programs, like @i{tip},
+use a separate initialization file instead of this
+value.)
+
+@item @code{--target_board [name(s)]}
+The list of target boards to run tests
+on.
+
+@item @code{--tool[name(s)]}
+Specifies which testsuite to run, and what
+initialization module to use. @code{--tool} is used
+@i{only} for these two purposes. It is
+@i{not} used to name the executable program to
+test. Executable tool names (and paths) are recorded in
+@file{site.exp} and you can override them by specifying
+Tcl variables on the command line.
+
+For example, including "@code{--tool} gcc" on the
+@i{runtest} command line runs tests from all test
+subdirectories whose names match @file{gcc.*}, and uses
+one of the initialization modules named
+@file{config/*-gcc.exp}. To specify the name of the
+compiler (perhaps as an alternative path to what
+@i{runtest} would use by default), use
+@i{GCC=binname} on the @i{runtest}
+command line.
+
+@item @code{--tool_exec [name]}
+The path to the tool executable to
+test.
+
+@item @code{--tool_opts [options]}
+A list of additional options to pass to the
+tool.
+
+@item @code{--verbose} (-v)
+Turns on more output. Repeating this option increases
+the amount of output displayed. Level one (@i{-v})
+is simply test output. Level two (@i{-v}-v@}) shows
+messages on options, configuration, and process control. Verbose
+messages appear in the detailed (@file{*.log}) log
+file, but not in the summary (@file{*.sum}) log
+file.
+
+@item @code{--version} (-V)
+Prints out the version numbers of DejaGnu,
+@i{expect} and Tcl, and exits without running any
+tests.
+
+@item @code{--D[0-1]}
+Start the internal Tcl debugger. The Tcl debugger
+supports breakpoints, single stepping, and other common debugging
+activities. See the document "Debugger for Tcl Applications" by Don
+Libes. (Distributed in PostScript form with
+@i{expect} as the file
+@file{expect/tcl-debug.ps.}. If you specify
+@i{-D1}, the @i{expect} shell stops
+at a breakpoint as soon as DejaGnu invokes it. If you specify
+@i{-D0}, DejaGnu starts as usual, but you can enter
+the debugger by sending an interrupt (e.g. by typing
+@key{C}@key{c}).
+
+@item @file{testfile}.exp[=arg(s)]
+Specify the names of testsuites to run. By default,
+@i{runtest} runs all tests for the tool, but you can
+restrict it to particular testsuites by giving the names of the
+@i{.exp expect} scripts that control
+them. @i{testsuite}.exp may not include path
+information; use plain filenames.
+
+@item @file{testfile}.exp="testfile1 ..."
+Specify a subset of tests in a suite to run. For
+compiler or assembler tests, which often use a single
+@i{.exp} script covering many different source
+files, this option allows you to further restrict the tests by
+listing particular source files to compile. Some tools even support
+wildcards here. The wildcards supported depend upon the tool, but
+typically they are @i{?}, @i{*},
+and @i{[chars]}.
+
+@item @code{tclvar}=value
+You can define Tcl variables for use by your test
+scripts in the same style used with @i{make} for
+environment variables. For example, @i{runtest
+GDB=gdb.old} defines a variable called
+@code{GDB}; when your scripts refer to
+@code{$GDB} in this run, they use the value
+@i{gdb.old}.
+
+The default Tcl variables used for most tools are defined in
+the main DejaGnu @i{Makefile}; their values are
+captured in the @file{site.exp} file.
+@end table
+
+@node Common Operations, , Invoking Runtest, Runtest
+@subsection Common Options
+
+Typically, you don't need must to use any command-line options.
+@code{--tool} used is only required when there are more than
+one testsuite in the same directory. The default options are in the
+local site.exp file, created by "make site.exp".
+
+For example, if the directory @file{gdb/testsuite}
+contains a collection of DejaGnu tests for GDB, you can run them like
+this:
+
+@example
+
+ eg$ cd gdb/testsuite
+ eg$ runtest --tool gdb
+
+@end example
+
+Test output follows, ending with:
+
+@example
+
+ === gdb Summary ===
+
+ # of expected passes 508
+ # of expected failures 103
+ /usr/latest/bin/gdb version 4.14.4 -nx
+
+@end example
+
+You can use the option @i{--srcdir} to point to
+some other directory containing a collection of tests:
+
+@example
+
+ eg$ runtest--srcdir /devo/gdb/testsuite
+
+@end example
+
+By default, @code{runtest} prints only the
+names of the tests it runs, output from any tests that have unexpected
+results, and a summary showing how many tests passed and how many
+failed. To display output from all tests (whether or not they behave
+as expected), use the @i{--all} option. For more
+verbose output about processes being run, communication, and so on, use
+@i{--verbose}. To see even more output, use multiple
+@i{--verbose} options. for a more detailed explanation
+of each @code{runtest} option.
+
+Test output goes into two files in your current directory:
+summary output in @file{tool.sum},
+and detailed output in @file{
+tool.log}. (@i{tool}
+refers to the collection of tests; for example, after a run with
+@i{--tool} gdb, look for output files
+@file{gdb.sum} and
+@file{gdb.log}.)
+
+@node Output Files, , Runtest, Running Tests
+@section The files DejaGnu produces.
+
+DejaGnu always writes two kinds of output files: summary
+logs and detailed logs. The contents of both of these are
+determined by your tests.
+
+For troubleshooting, a third kind of output file is useful:
+use @code{--debug} to request an output file showing
+details of what Expect is doing
+internally.
+
+@menu
+* Summary File::
+* Log File::
+* Debug Log File::
+@end menu
+
+@node Summary File, Log File, , Output Files
+@subsection Summary File
+
+DejaGnu always produces a summary output file
+@file{tool.sum}. This summary shows the names of
+all test files run; for each test file, one line of output from
+each @code{pass} command (showing status
+@i{PASS} or @i{XPASS}) or
+@code{fail} command (status
+@i{FAIL} or @i{XFAIL});
+trailing summary statistics that count passing and failing tests
+(expected and unexpected); and the full pathname and version
+number of the tool tested. (All possible outcomes, and all
+errors, are always reflected in the summary output file,
+regardless of whether or not you specify
+@code{--all}.)
+
+If any of your tests use the procedures
+@code{unresolved}, @code{unsupported},
+or @code{runtested}, the summary output also
+tabulates the corresponding outcomes.
+
+For example, after @code{runtest --tool
+binutils}, look for a summary log in
+@file{binutils.sum}. Normally, DejaGnu writes this
+file in your current working directory; use the
+@code{--outdir} option to select a different
+directory.
+
+@strong{Here is a short sample summary log}
+
+@example
+
+ Test Run By rob on Mon May 25 21:40:57 PDT 1992
+ === gdb tests ===
+ Running ./gdb.t00/echo.exp ...
+ PASS: Echo test
+ Running ./gdb.all/help.exp ...
+ PASS: help add-symbol-file
+ PASS: help aliases
+ PASS: help breakpoint "bre" abbreviation
+ FAIL: help run "r" abbreviation
+ Running ./gdb.t10/crossload.exp ...
+ PASS: m68k-elf (elf-big) explicit format; loaded
+ XFAIL: mips-ecoff (ecoff-bigmips) "ptype v_signed_char" signed C types
+ === gdb Summary ===
+ # of expected passes 5
+ # of expected failures 1
+ # of unexpected failures 1
+ /usr/latest/bin/gdb version 4.6.5 -q
+
+@end example
+
+@node Log File, Debug Log File, Summary File, Output Files
+@subsection Log File
+
+DejaGnu also saves a detailed log file
+@file{tool.log}, showing any output generated by
+tests as well as the summary output. For example, after
+@code{runtest --tool binutils}, look for a detailed
+log in @file{binutils.log}. Normally, DejaGnu
+writes this file in your current working directory; use the
+@code{--outdir} option to select a different
+directory.
+
+@strong{Here is a brief example showing a detailed log for
+G++ tests}
+
+@example
+
+ Test Run By rob on Mon May 25 21:40:43 PDT 1992
+
+ === g++ tests ===
+
+ --- Running ./g++.other/t01-1.exp ---
+ PASS: operate delete
+
+ --- Running ./g++.other/t01-2.exp ---
+ FAIL: i960 bug EOF
+ p0000646.C: In function `int warn_return_1 ()':
+ p0000646.C:109: warning: control reaches end of non-void function
+ p0000646.C: In function `int warn_return_arg (int)':
+ p0000646.C:117: warning: control reaches end of non-void function
+ p0000646.C: In function `int warn_return_sum (int, int)':
+ p0000646.C:125: warning: control reaches end of non-void function
+ p0000646.C: In function `struct foo warn_return_foo ()':
+ p0000646.C:132: warning: control reaches end of non-void function
+
+ --- Running ./g++.other/t01-4.exp ---
+ FAIL: abort
+ 900403_04.C:8: zero width for bit-field `foo'
+ --- Running ./g++.other/t01-3.exp ---
+ FAIL: segment violation
+ 900519_12.C:9: parse error before `;'
+ 900519_12.C:12: Segmentation violation
+ /usr/latest/bin/gcc: Internal compiler error: program cc1plus got fatal signal
+
+ === g++ Summary ===
+
+ # of expected passes 1
+ # of expected failures 3
+ /usr/latest/bin/g++ version cygnus-2.0.1
+
+@end example
+
+@node Debug Log File, , Log File, Output Files
+@subsection Debug Log File
+
+With the @code{--debug} option, you can request
+a log file showing the output from
+Expect itself, running in debugging
+mode. This file (@file{dbg.log}, in the directory
+where you start @code{runtest}) shows each pattern
+Expect considers in analyzing test
+output.
+
+This file reflects each @code{send} command,
+showing the string sent as input to the tool under test; and
+each Expect command, showing each
+pattern it compares with the tool output.
+
+@strong{The log messages begin with a message of the form}
+
+@example
+
+
+ expect: does @{tool output@} (spawn_id n)
+ match pattern @{expected pattern@}?
+
+
+@end example
+
+For every unsuccessful match,
+Expect issues a
+@i{no} after this message; if other patterns
+are specified for the same Expect
+command, they are reflected also, but without the first part of
+the message (@i{expect... match pattern}).
+
+When Expect finds a match, the
+log for the successful match ends with @i{yes},
+followed by a record of the Expect
+variables set to describe a successful match.
+
+@strong{Here is an excerpt from the debugging log for a
+GDB test:}
+
+@example
+
+ send: sent @{break gdbme.c:34\n@} to spawn id 6
+ expect: does @{@} (spawn_id 6) match pattern @{Breakpoint.*at.* file
+ gdbme.c, line 34.*\(gdb\) $@}? no
+ @{.*\(gdb\) $@}? no
+ expect: does @{@} (spawn_id 0) match pattern @{return@} ? no
+ @{\(y or n\) @}? no
+ @{buffer_full@}? no
+ @{virtual@}? no
+ @{memory@}? no
+ @{exhausted@}? no
+ @{Undefined@}? no
+ @{command@}? no
+ break gdbme.c:34
+ Breakpoint 8 at 0x23d8: file gdbme.c, line 34.
+ (gdb) expect: does @{break gdbme.c:34\r\nBreakpoint 8 at 0x23d8:
+ file gdbme.c, line 34.\r\n(gdb) @} (spawn_id 6) match pattern
+ @{Breakpoint.*at.* file gdbme.c, line 34.*\(gdb\) $@}? yes
+ expect: set expect_out(0,start) @{18@}
+ expect: set expect_out(0,end) @{71@}
+ expect: set expect_out(0,string) @{Breakpoint 8 at 0x23d8: file
+ gdbme.c, line 34.\r\n(gdb) @}
+ epect: set expect_out(spawn_id) @{6@}
+ expect: set expect_out(buffer) @{break gdbme.c:34\r\nBreakpoint 8
+ at 0x23d8: file gdbme.c, line 34.\r\n(gdb) @}
+ PASS: 70 0 breakpoint line number in file
+
+@end example
+
+This example exhibits three properties of
+Expect and
+DejaGnu that might be surprising at
+first glance:
+
+@itemize @bullet{}
+
+@item
+Empty output for the first attempted match. The
+first set of attempted matches shown ran against the output
+@i{@{@}} --- that is, no
+output. Expect begins
+attempting to match the patterns supplied immediately; often,
+the first pass is against incomplete output (or completely
+before all output, as in this case).
+
+@item
+Interspersed tool output. The beginning of
+the log entry for the second attempted match may be hard to
+spot: this is because the prompt @i{@{(gdb) @}}
+appears on the same line, just before the
+@i{expect:} that marks the beginning of the
+log entry.
+
+@item
+Fail-safe patterns. Many of the patterns
+tested are fail-safe patterns provided by
+GDB testing utilities, to reduce
+possible indeterminacy. It is useful to anticipate potential
+variations caused by extreme system conditions
+(GDB might issue the message
+@i{virtual memory exhausted} in rare
+circumstances), or by changes in the tested program
+(@i{Undefined command} is the likeliest
+outcome if the name of a tested command changes).
+
+The pattern @i{@{return@}} is a
+particularly interesting fail-safe to notice; it checks for an
+unexpected @key{RET} prompt. This may happen,
+for example, if the tested tool can filter output through a
+pager.
+
+These fail-safe patterns (like the debugging log itself)
+are primarily useful while developing test scripts. Use the
+@code{error} procedure to make the actions for
+fail-safe patterns produce messages starting with
+@i{ERROR} on standard output, and in the
+detailed log file.
+@end itemize
+
+@node Customizing DejaGnu, Extending DejaGnu, Running Tests, Top
+@chapter Customizing DejaGnu
+
+The site configuration file, @file{site.exp},
+captures configuration-dependent values and propagates them to the
+DejaGnu test environment using Tcl variables. This ties the
+DejaGnu test scripts into the @code{configure} and
+@code{make} programs. If this file is setup correctly,
+it is possible to execute a testsuite merely by typing
+@code{runtest}.
+
+DejaGnu supports two @file{site.exp}
+files. The multiple instances of @file{site.exp} are
+loaded in a fixed order built into DejaGnu. The first file loaded
+is the local file @file{site.exp}, and then the
+optional global @file{site.exp} file as
+pointed to by the @code{DEJAGNU} environment
+variable.
+
+There is an optional @i{master}
+@file{site.exp}, capturing configuration values that
+apply to DejaGnu across the board, in each configuration-specific
+subdirectory of the DejaGnu library directory.
+@code{runtest} loads these values first. The master
+@file{site.exp} contains the default values for all
+targets and hosts supported by DejaGnu. This master file is
+identified by setting the environment variable
+@code{DEJAGNU} to the name of the file. This is also
+refered to as the ``global'' config file.
+
+Any directory containing a configured testsuite also has a
+local @file{site.exp}, capturing configuration values
+specific to the tool under test. Since @code{runtest}
+loads these values last, the individual test configuration can
+either rely on and use, or override, any of the global values from
+the global @file{site.exp} file.
+
+You can usually generate or update the testsuite's local
+@file{site.exp} by typing @code{make
+site.exp} in the testsuite directory, after the test
+suite is configured.
+
+You can also have a file in your home directory called
+@file{.dejagnurc}. This gets loaded first before the
+other config files. Usually this is used for personal stuff, like
+setting the @code{all_flag} so all the output gets
+printed, or your own verbosity levels. This file is usually
+restricted to setting command line options.
+
+You can further override the default values in a
+user-editable section of any @file{site.exp}, or by
+setting variables on the @code{runtest} command
+line.
+
+@menu
+* Local Config File::
+* Global Config File::
+* Board Config File::
+* Remote Host Testing::
+* Config File Values::
+@end menu
+
+@node Local Config File, Global Config File, , Customizing DejaGnu
+@section Local Config File
+
+It is usually more convenient to keep these @i{manual
+overrides} in the @file{site.exp}
+local to each test directory, rather than in the global
+@file{site.exp} in the installed DejaGnu
+library. This file is mostly for supplying tool specific info
+that is required by the testsuite.
+
+All local @file{site.exp} files have
+two sections, separated by comment text. The first section is
+the part that is generated by @code{make}. It is
+essentially a collection of Tcl variable definitions based on
+@file{Makefile} environment variables. Since they
+are generated by @code{make}, they contain the
+values as specified by @code{configure}. (You can
+also customize these values by using the @code{--site}
+option to @code{configure}.) In particular, this
+section contains the @file{Makefile}
+variables for host and target configuration data. Do not edit
+this first section; if you do, your changes are replaced next
+time you run @code{make}.
+
+@strong{The first section starts with}
+
+@example
+
+ ## these variables are automatically generated by make ##
+ # Do not edit here. If you wish to override these values
+ # add them to the last section
+
+@end example
+
+In the second section, you can override any default values
+(locally to DejaGnu) for all the variables. The second section
+can also contain your preferred defaults for all the command
+line options to @code{runtest}. This allows you to
+easily customize @code{runtest} for your preferences
+in each configured test-suite tree, so that you need not type
+options repeatedly on the command line. (The second section may
+also be empty, if you do not wish to override any defaults.)
+
+@strong{The first section ends with this line}
+
+@example
+
+ ## All variables above are generated by configure. Do Not Edit ##
+
+@end example
+
+You can make any changes under this line. If you wish to
+redefine a variable in the top section, then just put a
+duplicate value in this second section. Usually the values
+defined in this config file are related to the configuration of
+the test run. This is the ideal place to set the variables
+@code{host_triplet}, @code{build_triplet},
+@code{target_triplet}. All other variables are tool
+dependant, i.e., for testing a compiler, the value for
+@code{CC} might be set to a freshly built binary, as
+opposed to one in the user's path.
+
+Here's an example local site.exp file, as used for
+GCC/G++ testing.
+
+@strong{Local Config File}
+
+@example
+
+ ## these variables are automatically generated by make ##
+ # Do not edit here. If you wish to override these values
+ # add them to the last section
+ set rootme "/build/devo-builds/i586-pc-linux-gnulibc1/gcc"
+ set host_triplet i586-pc-linux-gnulibc1
+ set build_triplet i586-pc-linux-gnulibc1
+ set target_triplet i586-pc-linux-gnulibc1
+ set target_alias i586-pc-linux-gnulibc1
+ set CFLAGS ""
+ set CXXFLAGS "-isystem /build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libio -isystem $srcdir/../libg++/src -isystem $srcdir/../libio -isystem $srcdir/../libstdc++ -isystem $srcdir/../libstdc++/stl -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libg++ -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libstdc++"
+ append LDFLAGS " -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../ld"
+ set tmpdir /build/devo-builds/i586-pc-linux-gnulibc1/gcc/testsuite
+ set srcdir "$@{srcdir@}/testsuite"
+ ## All variables above are generated by configure. Do Not Edit ##
+
+
+@end example
+
+This file defines the required fields for a local config
+file, namely the three config triplets, and the srcdir. It also
+defines several other Tcl variables that are used exclusivly by
+the GCC testsuite. For most 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.
+
+@node Global Config File, Board Config File, Local Config File, Customizing DejaGnu
+@section Global Config File
+
+The master config file is where all the target specific
+config variables for a whole site get set. The idea is
+that for a centralized testing lab where people have to share a
+target between multiple developers. There are settings for both
+remote targets and remote hosts. Here's an example of a Master
+Config File (also called the Global config file) for a
+@i{canadian cross}. A canadian cross is when
+you build and test a cross compiler on a machine other than the
+one it's to be hosted on.
+
+Here we have the config settings for our California
+office. Note that all config values are site dependant. Here we
+have two sets of values that we use for testing m68k-aout cross
+compilers. As both of these target boards has a different
+debugging protocol, we test on both of them in sequence.
+
+@strong{Global Config file}
+
+@example
+
+
+ # Make sure we look in the right place for the board description files.
+ if ![info exists boards_dir] @{
+ set boards_dir @{@}
+ @}
+ lappend boards_dir "/nfs/cygint/s1/cygnus/dejagnu/boards"
+
+ verbose "Global Config File: target_triplet is $target_triplet" 2
+ global target_list
+
+ case "$target_triplet" in @{
+ @{ "native" @} @{
+ set target_list "unix"
+ @}
+ @{ "sparc64-*elf" @} @{
+ set target_list "sparc64-sim"
+ @}
+ @{ "mips-*elf" @} @{
+ set target_list "mips-sim wilma barney"
+ @}
+ @{ "mips-lsi-elf" @} @{
+ set target_list "mips-lsi-sim@{,soft-float,el@}"
+ @}
+ @{ "sh-*hms" @} @{
+ set target_list @{ "sh-hms-sim" "bloozy" @}
+ @}
+ @}
+
+@end example
+
+In this case, we have support for several cross compilers,
+that all run on this host. For testing on operating systems that
+don't support Expect, DejaGnu can be run on the local build
+machine, and it can connect to the remote host and run all the
+tests for this cross compiler on that host. All the remote OS
+requires is a working telnetd.
+
+As you can see, all one does is set the variable
+@code{target_list} to the list of targets and options to
+test. The simple settings, like for
+@i{sparc64-elf} only require setting the name of
+the single board config file. The @i{mips-elf}
+target is more complicated. Here it sets the list to three target
+boards. One is the default mips target, and both
+@i{wilma} @i{barney} are
+symbolic names for other mips boards. Symbolic names are covered
+in the @ref{Adding A New Board,,Adding A New Board}. chapter. The more complicated
+example is the one for @i{mips-lsi-elf}. This one
+runs the tests with multiple iterations using all possible
+combinations of the @code{--soft-float} and the
+@code{--el} (little endian) option. Needless to say,
+this last feature is mostly compiler specific.
+
+@node Board Config File, Remote Host Testing, Global Config File, Customizing DejaGnu
+@section Board Config File
+
+The board config file is where board specfic config data
+is stored. A board config file contains all the higher-level
+configuration settings. There is a rough inheritance scheme, where it is
+possible to base a new board description file on an existing one. There
+are also collections of custom procedures for common environments. For
+more information on adding a new board config file, go to the @ref{Adding A New Board,,Adding A New Board}. chapter.
+
+An example board config file for a GNU simulator is as
+follows. @code{set_board_info} is a procedure that sets the
+field name to the specified value. The procedures in square brackets
+@i{[]} are @i{helper procedures}. Thes
+are used to find parts of a tool chain required to build an executable
+image that may reside in various locations. This is mostly of use for
+when the startup code, the standard C lobraries, or the tool chain itself
+is part of your build tree.
+
+@strong{Board Config File}
+
+@example
+
+ # This is a list of toolchains that are supported on this board.
+ set_board_info target_install @{sparc64-elf@}
+
+ # Load the generic configuration for this board. This will define any
+ # routines needed by the tool to communicate with the board.
+ load_generic_config "sim"
+
+ # We need this for find_gcc and *_include_flags/*_link_flags.
+ load_base_board_description "basic-sim"
+
+ # Use long64 by default.
+ process_multilib_options "long64"
+
+ setup_sim sparc64
+
+ # We only support newlib on this target. We assume that all multilib
+ # options have been specified before we get here.
+ set_board_info compiler "[find_gcc]"
+ set_board_info cflags "[libgloss_include_flags] [newlib_include_flags]"
+ set_board_info ldflags "[libgloss_link_flags] [newlib_link_flags]"
+ # No linker script.
+ set_board_info ldscript "";
+
+ # Used by a few gcc.c-torture testcases to delimit how large the
+ # stack can be.
+ set_board_info gcc,stack_size 16384
+ # The simulator doesn't return exit statuses and we need to indicate this
+ # the standard GCC wrapper will work with this target.
+ set_board_info needs_status_wrapper 1
+ # We can't pass arguments to programs.
+ set_board_info noargs 1
+
+@end example
+
+There are five helper procedures used in this example. The first
+one, @code{find gcc} looks for a copy of the GNU compiler in
+your build tree, or it uses the one in your path. This will also return
+the proper transformed name for a cross compiler if you whole build tree
+is configured for one. The next helper procedures are
+@code{libgloss_include_flags} &
+@code{libgloss_link_flags}. These return the proper flags to
+compiler and link an executable image using @ref{Libgloss,,Libgloss}., the GNU BSP (Board Support Package). The final
+procedures are @code{newlib_include_flag} &
+@code{newlib_include_flag}. These find the Newlib C
+library, which is a reentrant standard C 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
+
+@quotation
+
+@strong{Note}
+
+Thanks to Dj Delorie for the original paper that
+this section is based on.
+@end quotation
+
+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 foreign operating systems used as
+remote hosts are VxWorks, VRTX, DOS/Windows 3.1, MacOS and Windows.
+
+The recommended source for a Windows-based FTP
+server is to get IIS (either IIS 1 or Personal Web Server) from
+@uref{http://www.microsoft.com,http://www.microsoft.com}.
+When you install it, make sure you install the FTP server - it's
+not selected by default. Go into the IIS manager and change the
+FTP server so that it does not allow anonymous FTP. Set the home
+directory to the root directory (i.e. c:\) of a suitable
+drive. Allow writing via FTP.
+
+It will create an account like IUSR_FOOBAR where foobar is
+the name of your machine. Go into the user editor and give that
+account a password that you don't mind hanging around in the
+clear (i.e. not the same as your admin or personal
+passwords). Also, add it to all the various permission groups.
+
+You'll also need a telnet server. For Windows, go
+to the @uref{http://ataman.com,Ataman} web site,
+pick up the Ataman Remote Logon Services for Windows, and
+install it. You can get started on the eval period anyway. Add
+IUSR_FOOBAR to the list of allowed users, set the HOME directory
+to be the same as the FTP default directory. Change the Mode
+prompt to simple.
+
+Ok, now you need to pick a directory name to do all the
+testing in. For the sake of this example, we'll call it piggy
+(i.e. c:\piggy). Create this directory.
+
+You'll need a unix machine. Create a directory for the
+scripts you'll need. For this example, we'll use
+/usr/local/swamp/testing. You'll need to have a source tree
+somewhere, say /usr/src/devo. Now, copy some files from
+releng's area in SV to your machine:
+
+@strong{Remote host setup}
+
+@example
+
+ cd /usr/local/swamp/testing
+ mkdir boards
+ scp darkstar.welcomehome.org:/dejagnu/cst/bin/MkTestDir .
+ scp darkstar.welcomehome.org:/dejagnu/site.exp .
+ scp darkstar.welcomehome.org:/dejagnu/boards/useless98r2.exp boards/foobar.exp
+ export DEJAGNU=/usr/local/swamp/testing/site.exp
+
+
+@end example
+
+You must edit the boards/foobar.exp file to reflect your
+machine; change the hostname (foobar.com), username
+(iusr_foobar), password, and ftp_directory (c:/piggy) to match
+what you selected.
+
+Edit the global @file{ site.exp} to reflect your
+boards directory:
+
+@strong{Add The Board Directory}
+
+@example
+
+ lappend boards_dir "/usr/local/swamp/testing/boards"
+
+@end example
+
+Now run MkTestDir, which is in the contrib
+directory. The first parameter is the toolchain prefix, the
+second is the location of your devo tree. If you are testing a
+cross compiler (ex: you have sh-hms-gcc.exe in your PATH on
+the PC), do something like this:
+
+@strong{Setup Cross Remote Testing}
+
+@example
+
+ ./MkTestDir sh-hms /usr/dejagnu/src/devo
+
+@end example
+
+If you are testing a native PC compiler (ex: you have
+gcc.exe in your PATH on the PC), do this:
+
+@strong{Setup Native Remote Testing}
+
+@example
+
+ ./MkTestDir '' /usr/dejagnu/src/devo
+
+@end example
+
+To test the setup, @code{ftp} to your PC
+using the username (iusr_foobar) and password you selected. CD
+to the test directory. Upload a file to the PC. Now telnet to
+your PC using the same username and password. CD to the test
+directory. Make sure the file is there. Type "set" and/or "gcc
+-v" (or sh-hms-gcc -v) and make sure the default PATH contains
+the installation you want to test.
+
+@strong{Run Test Remotely}
+
+@example
+
+ cd /usr/local/swamp/testing
+ make -k -w check RUNTESTFLAGS="--host_board foobar --target_board foobar -v -v" > check.out 2>&1
+
+@end example
+
+To run a specific test, use a command like this (for
+this example, you'd run this from the gcc directory that
+MkTestDir created):
+
+@strong{Run a Test Remotely}
+
+@example
+
+ make check RUNTESTFLAGS="--host_board sloth --target_board sloth -v compile.exp=921202-1.c"
+
+@end example
+
+Note: if you are testing a cross-compiler, put in the
+correct target board. You'll also have to download more .exp
+files and modify them for your local configuration. The -v's
+are optional.
+
+@node Config File Values, , Remote Host Testing, Customizing DejaGnu
+@section Config File Values
+
+DejaGnu uses a named array in Tcl 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 @code{target_info}, and it has two indices. The
+following fields are part of the array.
+
+@menu
+* Command Line Option Variables: Option Variables.
+* Personal Config File::
+@end menu
+
+@node Option Variables, Personal Config File, , Config File Values
+@subsection Command Line Option Variables
+
+In the user editable second section of the @ref{Personal Config File,,Personal Config File}. you can not only override the configuration
+variables captured in the first section, but also specify
+default values for all on the @code{runtest}
+command line options. Save for @code{--debug},
+@code{--help}, and @code{--version}, each
+command line option has an associated Tcl variable. Use the
+Tcl @code{set} command to specify a new default
+value (as for the configuration variables). The following
+table describes the correspondence between command line
+options and variables you can set in
+@file{site.exp}. @ref{Invoking Runtest,,Invoking Runtest}., for
+explanations of the command-line options.
+
+
+@strong{Tcl Variables For Command Line Options}
+
+@multitable @columnfractions 0.333333333333333 0.333333333333333 0.333333333333333
+@item
+runtest@tab Tcl@tab optionvariabledescription
+@item
+--all@tab all_flag@tab display all test results if set
+@item
+--baud@tab baud@tab set the default baud rate to something other than
+9600.
+@item
+--connect@tab connectmode@tab @code{rlogin},
+@code{telnet}, @code{rsh},
+@code{kermit}, @code{tip}, or
+@code{mondfe}
+@item
+--outdir@tab outdir@tab directory for @file{tool.sum} and
+@file{tool.log.}
+@item
+--objdir@tab objdir@tab directory for pre-compiled binaries
+@item
+--reboot@tab reboot@tab reboot the target if set to
+@i{"1"}; do not reboot if set to
+@i{"0"} (the default).
+@item
+--srcdir@tab srcdir@tab directory of test subdirectories
+@item
+--strace@tab tracelevel@tab a number: Tcl trace depth
+@item
+--tool@tab tool@tab name of tool to test; identifies init, test subdir
+@item
+--verbose@tab verbose@tab verbosity level. As option, use multiple times; as
+variable, set a number, 0 or greater.
+@item
+--target@tab target_triplet@tab The canonical configuration string for the target.
+@item
+--host@tab host_triplet@tab The canonical configuration string for the host.
+@item
+--build@tab build_triplet@tab The canonical configuration string for the build
+host.
+@item
+--mail@tab address@tab Email the output log to the specified address.
+@end multitable
+
+@node Personal Config File, , Option Variables, Config File Values
+@subsection Personal Config File
+
+The personal config file is used to customize
+@code{runtest's} behaviour for each person. It's
+typically used to set the user prefered setting for verbosity,
+and any experimental Tcl procedures. My personal
+@file{~/.dejagnurc} file looks like:
+
+@strong{Personal Config File}
+
+@example
+
+ set all_flag 1
+ set RLOGIN /usr/ucb/rlogin
+ set RSH /usr/local/sbin/ssh
+
+@end example
+
+Here I set @code{all_flag} so I see all the test
+cases that PASS along with the ones that FAIL. I also set
+@code{RLOGIN} to the BSD version. I have
+Kerberos installed, and when I rlogin
+to a target board, it usually isn't supported. So I use the non
+secure version rather than the default that's in my path. I also
+set @code{RSH} to the SSH
+secure shell, as rsh is mostly used to test unix
+machines within a local network here.
+
+@node Extending DejaGnu, Unit Testing, Customizing DejaGnu, Top
+@chapter Extending DejaGnu
+
+@menu
+* Adding A New Testsuite: Adding a new Testsuite.
+* Adding A New Tool::
+* Adding A New Target::
+* Adding A New Board::
+* Board Config File Values: Board File Values.
+* Writing A Test Case::
+* Debugging A Test Case::
+* Adding A Test Case To A Testsuite_: Adding A Test Case To A Testsuite.
+* Hints On Writing A Test Case::
+* Special variables used by test cases_: Test Case Variables.
+@end menu
+
+@node Adding a new Testsuite, Adding A New Tool, , Extending DejaGnu
+@section Adding A New Testsuite
+
+The testsuite for a new tool should always be located in that tools
+source directory. DejaGnu require the directory be named
+@file{testsuite}. Under this directory, the test cases go
+in a subdirectory whose name begins with the tool name. For example, for
+a tool named @i{flubber}, each subdirectory containing
+testsuites must start with @i{"flubber."}.
+
+@node Adding A New Tool, Adding A New Target, Adding a new Testsuite, Extending DejaGnu
+@section Adding A New Tool
+
+In general, the best way to learn how to write (code or even prose)
+is to read something similar. This principle applies to test cases and
+to testsuites. Unfortunately, well-established testsuites have a way
+of developing their own conventions: as test writers become more
+experienced with DejaGnu and with Tcl, they accumulate more utilities,
+and take advantage of more and more features of
+Expect and Tcl in
+general.
+
+Inspecting such established testsuites may make the prospect of
+creating an entirely new testsuite appear overwhelming. Nevertheless,
+it is quite straightforward to get a new testsuite going.
+
+There is one testsuite that is guaranteed not to grow more
+elaborate over time: both it and the tool it tests were created expressly
+to illustrate what it takes to get started with DejaGnu. The
+@file{example/} directory of the DejaGnu distribution
+contains both an interactive tool called @code{calc}, and a
+testsuite for it. Reading this testsuite, and experimenting with it,
+is a good way to supplement the information in this section. (Thanks to
+Robert Lupton for creating calc and its testsuite---and also the first
+version of this section of the manual!)
+
+To help orient you further in this task, here is an outline of the
+steps to begin building a testsuite for a program example.
+
+@itemize @bullet{}
+
+@item
+Create or select a directory to contain your new
+collection of tests. Change into that directory (shown here as
+@file{testsuite}):
+
+Create a @file{configure.in} file in this directory,
+to control configuration-dependent choices for your tests. So far as
+DejaGnu is concerned, the important thing is to set a value for the
+variable @code{target_abbrev}; this value is the link to the
+init file you will write soon. (For simplicity, we assume the
+environment is Unix, and use @i{unix} as the
+value.)
+
+What else is needed in @file{configure.in} depends on
+the requirements of your tool, your intended test environments, and which
+configure system you use. This example is a minimal configure.in for use
+with GNU Autoconf.
+
+@item
+Create @file{Makefile.in} (if you are using
+Autoconf), or @file{Makefile.am}(if you are using
+Automake), the source file used by configure to build your
+@file{Makefile}. If you are using GNU Automake.just add the
+keyword @i{dejagnu} to the
+@i{AUTOMAKE_OPTIONS} variable in your
+@file{Makefile.am} file. This will add all the Makefile
+support needed to run DejaGnu, and support the @ref{Make Check,,Make Check}.
+target.
+
+You also need to include two targets important to DejaGnu:
+@i{check}, to run the tests, and
+@i{site.exp}, to set up the Tcl copies of
+configuration-dependent values. This is called the @ref{Local Config File,,Local Config File}.
+The check target must run the @code{runtest} program to
+execute the tests.
+
+The @file{site.exp} target should usually set up
+(among other things) the $tool variable for the name of your program. If
+the local site.exp file is setup correctly, it is possible to execute the
+tests by merely typing @code{runtest} on the command
+line.
+
+@strong{Sample Makefile.in Fragment}
+
+@example
+
+ # Look for a local version of DejaGnu, otherwise use one in the path
+ RUNTEST = `if test -f $(top_srcdir)/../dejagnu/runtest; then \
+ echo $(top_srcdir) ../dejagnu/runtest; \
+ else \
+ echo runtest; \
+ fi`
+
+ # The flags to pass to runtest
+ RUNTESTFLAGS =
+
+ # Execute the tests
+ check: site.exp all
+ $(RUNTEST) $(RUNTESTFLAGS) \
+ --tool $@{example@} --srcdir $(srcdir)
+
+ # Make the local config file
+ site.exp: ./config.status Makefile
+ @@echo "Making a new config file..."
+ -@@rm -f ./tmp?
+ @@touch site.exp
+
+ -@@mv site.exp site.bak
+ @@echo "## these variables are automatically\
+ generated by make ##" > ./tmp0
+ @@echo "# Do not edit here. If you wish to\
+ override these values" >> ./tmp0
+ @@echo "# add them to the last section" >> ./tmp0
+ @@echo "set host_os $@{host_os@}" >> ./tmp0
+ @@echo "set host_alias $@{host_alias@}" >> ./tmp0
+ @@echo "set host_cpu $@{host_cpu@}" >> ./tmp0
+ @@echo "set host_vendor $@{host_vendor@}" >> ./tmp0
+ @@echo "set target_os $@{target_os@}" >> ./tmp0
+ @@echo "set target_alias $@{target_alias@}" >> ./tmp0
+ @@echo "set target_cpu $@{target_cpu@}" >> ./tmp0
+ @@echo "set target_vendor $@{target_vendor@}" >> ./tmp0
+ @@echo "set host_triplet $@{host_canonical@}" >> ./tmp0
+ @@echo "set target_triplet $@{target_canonical@}">>./tmp0
+ @@echo "set tool binutils" >> ./tmp0
+ @@echo "set srcdir $@{srcdir@}" >> ./tmp0
+ @@echo "set objdir `pwd`" >> ./tmp0
+ @@echo "set $@{examplename@} $@{example@}" >> ./tmp0
+ @@echo "## All variables above are generated by\
+ configure. Do Not Edit ##" >> ./tmp0
+ @@cat ./tmp0 > site.exp
+ @@sed < site.bak \
+ -e '1,/^## All variables above are.*##/ d' \
+ >> site.exp
+ -@@rm -f ./tmp?
+
+
+@end example
+
+@item
+Create a directory (in @file{testsuite})
+called @file{config}. Make a @i{Tool Init
+File} in this directory. Its name must start with the
+@code{target_abbrev} value, or be named
+@file{default.exp} so call it
+@file{config/unix.exp} for our Unix based example. This
+is the file that contains the target-dependent procedures.
+Fortunately, on Unix, most of them do not have to do very much in
+order for @code{runtest} to run.
+
+If the program being tested is not interactive, you can get
+away with this minimal @file{unix.exp} to begin
+with:
+
+@strong{Simple Batch Program Tool Init File}
+
+@example
+
+
+ proc foo_exit @{@} @{@}
+ proc foo_version @{@} @{@}
+
+
+@end example
+
+If the program being tested is interactive, however, you might
+as well define a @i{start} routine and invoke it by
+using an init file like this:
+
+@strong{Simple Interactive Program Tool Init File}
+
+@example
+
+
+ proc foo_exit @{@} @{@}
+ proc foo_version @{@} @{@}
+
+ proc foo_start @{@} @{
+ global $@{examplename@}
+ spawn $@{examplename@}
+ expect @{
+ -re "" @{@}
+ @}
+ @}
+
+ # Start the program running we want to test
+ foo_start
+
+
+@end example
+
+@item
+Create a directory whose name begins with your tool's
+name, to contain tests. For example, if your tool's name is
+@i{gcc}, then the directories all need to start with
+@i{"gcc."}.
+
+@item
+Create a sample test file. Its name must end with
+@file{.exp}. You can use
+@file{first-try.exp}. To begin with, just write there a
+line of Tcl code to issue a message.
+
+@strong{Testing A New Tool Config}
+
+@example
+
+
+ send_user "Testing: one, two...\n"
+
+
+@end example
+
+@item
+Back in the @file{testsuite} (top
+level) directory, run @code{configure}. Typically you do
+this while in the build directory. You may have to specify more of a
+path, if a suitable configure is not available in your execution
+path.
+
+@item
+e now ready to triumphantly type @code{make
+check} or @code{runtest}. You should see
+something like this:
+
+@strong{Example Test Case Run}
+
+@example
+
+ Test Run By rhl on Fri Jan 29 16:25:44 EST 1993
+
+ === example tests ===
+
+ Running ./example.0/first-try.exp ...
+ Testing: one, two...
+
+ === example Summary ===
+
+
+@end example
+
+There is no output in the summary, because so far the example
+does not call any of the procedures that establish a test
+outcome.
+
+@item
+Write some real tests. For an interactive tool, you
+should probably write a real exit routine in fairly short order. In
+any case, you should also write a real version routine
+soon.
+@end itemize
+
+@node Adding A New Target, Adding A New Board, Adding A New Tool, Extending DejaGnu
+@section Adding A New Target
+
+DejaGnu has some additional requirements for target support, beyond
+the general-purpose provisions of configure. DejaGnu must actively
+communicate with the target, rather than simply generating or managing
+code for the target architecture. Therefore, each tool requires an
+initialization module for each target. For new targets, you must supply
+a few Tcl procedures to adapt DejaGnu to the target. This permits
+DejaGnu itself to remain target independent.
+
+Usually the best way to write a new initialization module is to
+edit an existing initialization module; some trial and error will be
+required. If necessary, you can use the @@samp@{--debug@} option to see what
+is really going on.
+
+When you code an initialization module, be generous in printing
+information controlled by the @code{verbose}
+procedure.
+
+For cross targets, most of the work is in getting the
+communications right. Communications code (for several situations
+involving IP networks or serial lines) is available in a DejaGnu library
+file.
+
+If you suspect a communication problem, try running the connection
+interactively from Expect. (There are three
+ways of running Expect as an interactive
+interpreter. You can run Expect with no
+arguments, and control it completely interactively; or you can use
+@code{expect -i} together with other command-line options and
+arguments; or you can run the command @code{interpreter} from
+any Expect procedure. Use
+@code{return} to get back to the calling procedure (if any),
+or @code{return -tcl} to make the calling procedure itself
+return to its caller; use @code{exi}t or end-of-file to leave
+Expect altogether.) Run the program whose name is recorded in
+@code{$connectmode}, with the arguments in
+@code{$targetname}, to establish a connection. You should at
+least be able to get a prompt from any target that is physically
+connected.
+
+@node Adding A New Board, Board File Values, Adding A New Target, Extending DejaGnu
+@section Adding A New Board
+
+Adding a new board consists of creating a new board config
+file. Examples are in
+@file{dejagnu/baseboards}. Usually to make a new
+board file, it's easiest to copy an existing one. It is also
+possible to have your file be based on a
+@i{baseboard} file with only one or two
+changes needed. Typically, this can be as simple as just
+changing the linker script. Once the new baseboard file is done,
+add it to the @code{boards_DATA} list in the
+@file{dejagnu/baseboards/Makefile.am}, and regenerate the
+Makefile.in using automake. Then just rebuild and install DejaGnu. You
+can test it by:
+
+There is a crude inheritance scheme going on with board files, so
+you can include one board file into another, The two main procedures used
+to do this are @code{load_generic_config} and
+@code{load_base_board_description}. The generic config file
+contains other procedures used for a certain class of target. The
+board description file is where the board specfic settings go. Commonly
+there are similar target environments with just different
+processors.
+
+@strong{Testing a New Board Config File}
+
+@example
+
+ make check RUNTESTFLAGS="--target_board=newboardfile".
+
+@end example
+
+Here's an example of a board config file. There are
+several @i{helper procedures} used in this
+example. A helper procedure is one that look for a tool of files
+in commonly installed locations. These are mostly used when
+testing in the build tree, because the executables to be tested
+are in the same tree as the new dejagnu files. The helper
+procedures are the ones in square braces
+@i{[]}, which is the Tcl execution characters.
+
+@strong{Example Board Config File}
+
+@example
+
+
+ # Load the generic configuration for this board. This will define a basic
+ # set of routines needed by the tool to communicate with the board.
+ load_generic_config "sim"
+
+ # basic-sim.exp is a basic description for the standard Cygnus simulator.
+ load_base_board_description "basic-sim"
+
+ # The compiler used to build for this board. This has *nothing* to do
+ # with what compiler is tested if we're testing gcc.
+ set_board_info compiler "[find_gcc]"
+
+ # We only support newlib on this target.
+ # However, we include libgloss so we can find the linker scripts.
+ set_board_info cflags "[newlib_include_flags] [libgloss_include_flags]"
+ set_board_info ldflags "[newlib_link_flags]"
+
+ # No linker script for this board.
+ set_board_info ldscript "-Tsim.ld";
+
+ # The simulator doesn't return exit statuses and we need to indicate this.
+ set_board_info needs_status_wrapper 1
+
+ # Can't pass arguments to this target.
+ set_board_info noargs 1
+
+ # No signals.
+ set_board_info gdb,nosignals 1
+
+ # And it can't call functions.
+ set_board_info gdb,cannot_call_functions 1
+
+
+@end example
+
+@node Board File Values, Writing A Test Case, Adding A New Board, Extending DejaGnu
+@section Board Config File Values
+
+These fields are all in the @code{board_info} These are
+all set by using the @code{set_board_info} procedure. The
+parameters are the field name, followed by the value to set the field
+to.
+
+
+@strong{Common Board Info Fields}
+
+@multitable @columnfractions 0.333333333333333 0.333333333333333 0.333333333333333
+@item
+Field@tab Sample Value@tab Description
+@item
+compiler@tab "[find_gcc]"@tab The path to the compiler to use.
+@item
+cflags@tab "-mca"@tab Compilation flags for the compiler.
+@item
+ldflags@tab "[libgloss_link_flags] [newlib_link_flags]"@tab Linking flags for the compiler.
+@item
+ldscript@tab "-Wl,-Tidt.ld"@tab The linker script to use when cross compiling.
+@item
+libs@tab "-lgcc"@tab Any additional libraries to link in.
+@item
+shell_prompt@tab "cygmon>"@tab The command prompt of the remote shell.
+@item
+hex_startaddr@tab "0xa0020000"@tab The Starting address as a string.
+@item
+start_addr@tab 0xa0008000@tab The starting address as a value.
+@item
+startaddr@tab "a0020000"@tab
+@item
+exit_statuses_bad@tab 1@tab Whether there is an accurate exit status.
+@item
+reboot_delay@tab 10@tab The delay between power off and power on.
+@item
+unreliable@tab 1@tab Whether communication with the board is unreliable.
+@item
+sim@tab [find_sim]@tab The path to the simulator to use.
+@item
+objcopy@tab $tempfil@tab The path to the @code{objcopy} program.
+@item
+support_libs@tab "$@{prefix_dir@}/i386-coff/"@tab Support libraries needed for cross compiling.
+@item
+addl_link_flags@tab "-N"@tab Additional link flags, rarely used.
+@end multitable
+
+These fields are used by the GCC and GDB tests, and are mostly
+only useful to somewhat trying to debug a new board file for one of
+these tools. Many of these are used only by a few testcases, and their
+purpose is esoteric. These are listed with sample values as a guide to
+better guessing if you need to change any of these.
+
+
+@strong{Board Info Fields For GCC & GDB}
+
+@multitable @columnfractions 0.333333333333333 0.333333333333333 0.333333333333333
+@item
+Field@tab Sample Value@tab Description
+@item
+strip@tab $tempfile@tab Strip the executable of symbols.
+@item
+gdb_load_offset@tab "0x40050000"@tab
+@item
+gdb_protocol@tab "remote"@tab The GDB debugging protocol to use.
+@item
+gdb_sect_offset@tab "0x41000000";@tab
+@item
+gdb_stub_ldscript@tab "-Wl,-Teva-stub.ld"@tab The linker script to use with a GDB stub.
+@item
+gdb_init_command@tab "set mipsfpu none"@tab
+@item
+gdb,cannot_call_functions@tab 1@tab Whether GDB can call functions on the target,
+@item
+gdb,noargs@tab 1@tab Whether the target can take command line arguments.
+@item
+gdb,nosignals@tab 1@tab Whether there are signals on the target.
+@item
+gdb,short_int@tab 1@tab
+@item
+gdb,start_symbol@tab "_start";@tab The starting symbol in the executable.
+@item
+gdb,target_sim_options@tab "-sparclite"@tab Special options to pass to the simulator.
+@item
+gdb,timeout@tab 540@tab Timeout value to use for remote communication.
+@item
+gdb_init_command@tab "print/x \$fsr = 0x0"@tab
+@item
+gdb_load_offset@tab "0x12020000"@tab
+@item
+gdb_opts@tab "--command gdbinit"@tab
+@item
+gdb_prompt@tab "\\(gdb960\\)"@tab The prompt GDB is using.
+@item
+gdb_run_command@tab "jump start"@tab
+@item
+gdb_stub_offset@tab "0x12010000"@tab
+@item
+use_gdb_stub@tab 1@tab Whether to use a GDB stub.
+@item
+use_vma_offset@tab 1@tab
+@item
+wrap_m68k_aout@tab 1@tab
+@item
+gcc,no_label_values@tab 1@tab
+@item
+gcc,no_trampolines@tab 1@tab
+@item
+gcc,no_varargs@tab 1@tab
+@item
+gcc,stack_size@tab 16384@tab Stack size to use with some GCC testcases.
+@item
+ieee_multilib_flags@tab "-mieee";@tab
+@item
+is_simulator@tab 1@tab
+@item
+needs_status_wrapper@tab 1@tab
+@item
+no_double@tab 1@tab
+@item
+no_long_long@tab 1@tab
+@item
+noargs@tab 1@tab
+@item
+nullstone,lib@tab "mips-clock.c"@tab
+@item
+nullstone,ticks_per_sec@tab 3782018@tab
+@item
+sys_speed_value@tab 200@tab
+@item
+target_install@tab @{sh-hms@}@tab
+@end multitable
+
+@node Writing A Test Case, Debugging A Test Case, Board File Values, Extending DejaGnu
+@section Writing A Test Case
+
+The easiest way to prepare a new test case is to base it
+on an existing one for a similar situation. There are two major
+categories of tests: batch or interactive. Batch oriented tests
+are usually easier to write.
+
+The GCC tests are a good example of batch oriented tests.
+All GCC tests consist primarily of a call to a single common
+procedure, Since all the tests either have no output, or only
+have a few warning messages when successfully compiled. Any
+non-warning output is a test failure. All the C code needed is
+kept in the test directory. The test driver, written in Tcl,
+need only get a listing of all the C files in the directory, and
+compile them all using a generic procedure. This procedure and a
+few others supporting for these tests are kept in the library
+module @file{lib/c-torture.exp} in the GCC test
+suite. Most tests of this kind use very few
+expect features, and are coded almost
+purely in Tcl.
+
+Writing the complete suite of C tests, then, consisted of
+these steps:
+
+@itemize @bullet{}
+
+@item
+Copying all the C code into the test directory.
+These tests were based on the C-torture test created by Torbjorn
+Granlund (on behalf of the Free Software Foundation) for GCC
+development.
+
+@item
+Writing (and debugging) the generic Tcl procedures for
+compilation.
+
+@item
+Writing the simple test driver: its main task is to
+search the directory (using the Tcl procedure
+@i{glob} for filename expansion with wildcards)
+and call a Tcl procedure with each filename. It also checks for
+a few errors from the testing procedure.
+@end itemize
+
+Testing interactive programs is intrinsically more
+complex. Tests for most interactive programs require some trial
+and error before they are complete.
+
+However, some interactive programs can be tested in a
+simple fashion reminiscent of batch tests. For example, prior
+to the creation of DejaGnu, the GDB distribution already
+included a wide-ranging testing procedure. This procedure was
+very robust, and had already undergone much more debugging and
+error checking than many recent DejaGnu test cases.
+Accordingly, the best approach was simply to encapsulate the
+existing GDB tests, for reporting purposes. Thereafter, new GDB
+tests built up a family of Tcl procedures specialized for GDB
+testing.
+
+@node Debugging A Test Case, Adding A Test Case To A Testsuite, Writing A Test Case, Extending DejaGnu
+@section Debugging A Test Case
+
+These are the kinds of debugging information available
+from DejaGnu:
+
+@itemize @bullet{}
+
+@item
+Output controlled by test scripts themselves,
+explicitly allowed for by the test author. This kind of
+debugging output appears in the detailed output recorded in the
+DejaGnu log file. To do the same for new tests, use the
+@code{verbose} procedure (which in turn uses the
+variable also called @i{verbose}) to control
+how much output to generate. This will make it easier for other
+people running the test to debug it if necessary. Whenever
+possible, if @i{$verbose} is
+@i{0}, there should be no output other than the
+output from @i{pass},
+@i{fail}, @i{error}, and
+@i{warning}. Then, to whatever extent is
+appropriate for the particular test, allow successively higher
+values of @i{$verbose} to generate more
+information. Be kind to other programmers who use your tests:
+provide for a lot of debugging information.
+
+@item
+Output from the internal debugging functions of
+Tcl and Expect. There is a command
+line options for each; both forms of debugging output are
+recorded in the file @file{dbg.log} in the current
+directory.
+
+Use @code{--debug} for information from the
+expect level; it generates displays of the expect attempts to
+match the tool output with the patterns specified. This output
+can be very helpful while developing test scripts, since it
+shows precisely the characters received. Iterating between the
+latest attempt at a new test script and the corresponding
+@file{dbg.log} can allow you to create the final
+patterns by ``cut and paste''. This is sometimes the best way
+to write a test case.
+
+@item
+Use @code{--strace} to see more
+detail at the Tcl level; this shows how Tcl procedure
+definitions expand, as they execute. The associated number
+controls the depth of definitions expanded.
+
+@item
+Finally, if the value of
+@i{verbose} is 3 or greater,DejaGnu turns on
+the expect command @code{log_user}. This command
+prints all expect actions to the expect standard output, to the
+detailed log file, and (if @code{--debug} is on) to
+@file{dbg.log}.
+@end itemize
+
+@node Adding A Test Case To A Testsuite, Hints On Writing A Test Case, Debugging A Test Case, Extending DejaGnu
+@section Adding A Test Case To A Testsuite.
+
+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 directory to hold your test. The
+existing test directories represent several styles of testing,
+all of which are slightly different; examine the directories for
+the tool of interest to see which (if any) is most suitable.
+
+Adding a GCC test can be very simple: just add the C code
+to any directory beginning with @file{gcc}. and it
+runs on the next
+
+@example
+runtest --tool
+ gcc
+@end example
+
+@noindent
+.
+
+To add a test to GDB, first add any source code you will
+need to the test directory. Then you can either create a new
+expect file, or add your test to an existing one (any
+file with a @i{.exp} suffix). Creating a new
+.exp file is probably a better idea if the test is significantly
+different from existing tests. Adding it as a separate file also
+makes upgrading easier. If the C code has to be already compiled
+before the test will run, then you'll have to add it to the
+@file{Makefile.in} file for that test directory,
+then run @code{configure} and
+@code{make}.
+
+Adding a test by creating a new directory is very
+similar:
+
+@itemize @bullet{}
+
+@item
+Create the new directory. All subdirectory names
+begin with the name of the tool to test; e.g. G++ tests might be
+in a directory called @file{g++.other}. There can
+be multiple test directories that start with the same tool name
+(such as @i{g++}).
+
+@item
+Add the new directory name to the
+@code{configdirs} definition in the
+@file{configure.in} file for the testsuite
+directory. This way when @code{make} and
+@code{configure} next run, they include the new
+directory.
+
+@item
+Add the new test case to the directory, as
+above.
+
+@item
+To add support in the new directory for
+configure and make, you must also create a
+@file{Makefile.in} and a
+@file{configure.in}.
+@end itemize
+
+@node Hints On Writing A Test Case, Test Case Variables, Adding A Test Case To A Testsuite, Extending DejaGnu
+@section Hints On Writing A Test Case
+
+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 the entire output, any output that
+remains will be examined by the next @code{expect}
+command. In this situation, the precise boundary that determines
+which @code{expect} command sees what is very
+sensitive to timing between the Expect task and the task running
+the tested tool. As a result, the test may sometimes appear to
+work, but is likely to have unpredictable results. (This problem
+is particularly likely for interactive tools, but can also
+affect batch tools---especially for tests that take a long time
+to finish.) The best way to ensure closure is to use the
+@code{-re} option for the @code{expect}
+command to write the pattern as a full regular expressions; then
+you can match the end of output using a @i{$}.
+It is also a good idea to write patterns that match all
+available output by using @i{.*\} after the
+text of interest; this will also match any intervening blank
+lines. Sometimes an alternative is to match end of line using
+@i{\r} or @i{\n}, but this is
+usually too dependent on terminal settings.
+
+Always escape punctuation, such as @i{(}
+or @i{"}, in your patterns; for example, write
+@i{\(}. If you forget to escape punctuation,
+you will usually see an error message like
+
+@example
+extra
+ characters after close-quote.
+@end example
+
+If you have trouble understanding why a pattern does not
+match the program output, try using the @code{--debug}
+option to @code{runtest}, and examine the debug log
+carefully.
+
+Be careful not to neglect output generated by setup rather
+than by the interesting parts of a test case. For example,
+while testing GDB, I issue a send @i{set height
+0\n} command. The purpose is simply to make sure GDB
+never calls a paging program. The @i{set
+height} command in GDB does not generate any
+output; but running any command makes GDB issue a new
+@i{(gdb) } prompt. If there were no
+@code{expect} command to match this prompt, the
+output @i{(gdb) } begins the text seen by the
+next @code{expect} command---which might make that
+pattern fail to match.
+
+To preserve basic sanity, I also recommended that no test
+ever pass if there was any kind of problem in the test case. To
+take an extreme case, tests that pass even when the tool will
+not spawn are misleading. Ideally, a test in this sort of
+situation should not fail either. Instead, print an error
+message by calling one of the DejaGnu procedures
+@code{error} or @code{warning}.
+
+@node Test Case Variables, , Hints On Writing A Test Case, Extending DejaGnu
+@section Special variables used by test cases.
+
+There are special variables used by test cases. These contain
+other information from DejaGnu. Your test cases can use these variables,
+with conventional meanings (as well as the variables saved in
+@file{site.exp}. You can use the value of these variables,
+but they should never be changed.
+
+@table @asis
+
+@item $prms_id
+The tracking system (e.g. GNATS) number identifying
+a corresponding bugreport. (@i{0}@} if you do not
+specify it in the test script.)
+
+@item $item bug_id
+An optional bug id; may reflect a bug
+identification from another organization. (@i{0}
+if you do not specify it.)
+
+@item $subdir
+The subdirectory for the current test
+case.
+
+@item $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.
+
+@item $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
+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.
+@end table
+
+@node Unit Testing, Reference, Extending DejaGnu, Top
+@chapter Unit Testing
+
+@menu
+* What Is Unit Testing ?::
+* The dejagnu_h Header File::
+@end menu
+
+@node What Is Unit Testing ?, The dejagnu_h Header File, , Unit Testing
+@section What Is Unit Testing ?
+
+Most regression testing as done by DejaGnu is system
+testing. This is the complete application is tested all at
+once. Unit testing is for testing single files, or small
+libraries. In this case, each file is linked with a test case in
+C or C++, and each function or class and method is tested in
+series, with the test case having to check private data or
+global variables to see if the function or method worked.
+
+This works particularly well for testing APIs and at level
+where it is easier to debug them, than by needing to trace through
+the entire appication. Also if there is a specification for the
+API to be tested, the testcase can also function as a compliance
+test.
+
+@node The dejagnu_h Header File, , What Is Unit Testing ?, Unit Testing
+@section The dejagnu.h Header File
+
+DejaGnu uses a single header file to assist in unit
+testing. As this file also produces it's one test state output,
+it can be run standalone, which is very useful for testing on
+embedded systems. This header file has a C and C++ API for the
+test states, with simple totals, and standardized
+output. Because the output has been standardized, DejaGnu can be
+made to work with this test case, without writing almost any
+Tcl. The library module, dejagnu.exp, will look for the output
+messages, and then merge them into DejaGnu's.
+
+@node Reference, Unit Testing API, Unit Testing, Top
+@chapter Reference
+
+@menu
+* Obtaining DejaGnu::
+* Installation::
+* Builtin Procedures::
+* File Map::
+@end menu
+
+@node Obtaining DejaGnu, Installation, , Reference
+@section Obtaining DejaGnu
+
+You can obtain DejaGnu from the DejaGnu web site at the
+@uref{http://www.gnu.org,Free Software Foundation},
+which is at @uref{http://www.gnu.org/software/dejagnu/,www.gnu.org/software/dejagnu/ }
+
+@node Installation, Builtin Procedures, Obtaining DejaGnu, Reference
+@section Installation
+
+Once you have the DejaGnu source unpacked and available, you must
+first configure the software to specify where it is to run (and the
+associated defaults); then you can proceed to installing it.
+
+@menu
+* Configuring DejaGnu::
+* Installing DejaGnu::
+@end menu
+
+@node Configuring DejaGnu, Installing DejaGnu, , Installation
+@subsection Configuring DejaGnu
+
+It is usually best to configure in a directory separate from the
+source tree, specifying where to find the source with the optional
+@i{--srcdir} option to
+@i{configure}. DejaGnu uses the GNU
+@i{autoconf} to configure itself. For more info on using
+autoconf, read the GNU autoconf manual. To configure, execute the
+@file{configure} program, no other options are
+required. For an example, to configure in a seperate tree for objects,
+execute the configure script from the source tree like this:
+
+@example
+
+ ../dejagnu-1.4.5/configure
+
+@end example
+
+DejaGnu doesn't care at config time if it's for testing a native
+system or a cross system. That is determined at runtime by using the
+config files.
+
+You may also want to use the @code{configure} option
+@i{--prefix} to specify where you want DejaGnu and its
+supporting code installed. By default, installation is in subdirectories
+of @file{/usr/local}, but you can select any alternate
+directory @code{altdir} by including
+@code{--prefix}@{altdir@}@} on the
+@code{configure} command line. (This value is captured in
+the Makefile variables @i{prefix} and
+@i{exec}prefix@}.)
+
+Save for a small number of example tests, the DejaGnu distribution
+itself does not include any testsuites; these are available
+separately. Testsuites for the GNU development tools are included in
+those releases. After configuring the top-level DejaGnu directory, unpack
+and configure the test directories for the tools you want to test; then,
+in each test directory, run @i{make check} to build
+auxiliary programs required by some of the tests, and run the test
+suites.
+
+@node Installing DejaGnu, , Configuring DejaGnu, Installation
+@subsection Installing DejaGnu
+
+To install DejaGnu in your filesystem (either in
+@file{/usr/local}, or as specified by your
+@i{--prefix} option to @i{configure}),
+execute.
+
+@example
+
+ eg$ make install
+
+@end example
+
+@i{make install}does thes things for
+DejaGnu:
+
+@itemize @bullet{}
+
+@item
+Look in the path specified for executables
+@code{$exec_prefix}) for directories called
+@file{lib} and @file{bin}. If these
+directories do not exist, @i{make install} creates
+them.
+
+@item
+Create another directory in the
+@file{share} directory, called
+@file{dejagnu}, and copy all the library files into
+it.
+
+@item
+Create a directory in the
+@file{dejagnu/share} directory, called
+@file{config}, and copy all the configuration files into
+it.
+
+@item
+Copy the @i{runtest} shell script into
+@file{$exec_prefix/bin}.
+
+@item
+Copy @file{runtest.exp} into
+@file{$exec_prefix/lib/dejagnu}. This is the main Tcl
+code implementing DejaGnu.
+@end itemize
+
+@node Builtin Procedures, File Map, Installation, Reference
+@section Builtin Procedures
+
+DejaGnu provides these Tcl procedures.
+
+@menu
+* Core Internal Procedures::
+* Procedures For Remote Communication::
+* Procedures For Using Utilities to Connect: connprocs.
+* Procedures For Target Boards::
+* Target Database Procedures: target database library file.
+* Platform Dependant Procedures: platform dependant procedures.
+* Utility Procedures::
+* Libgloss; A Free BSP: Libgloss.
+* Procedures for debugging your Tcl code_: Debugging Procedures.
+@end menu
+
+@node Core Internal Procedures, Procedures For Remote Communication, , Builtin Procedures
+@subsection Core Internal Procedures
+
+@menu
+* Mail_file Procedure: mail_file procedure.
+* Open_logs Procedure: open_logs procedure.
+* Close_logs Procedure: close_logs procedure.
+* Isbuild Procedure: isbuild procedure.
+* Is_remote Procedure: is_remote procedure.
+* is3way Procedure: is3way procedure.
+* Ishost Procedure: ishost procedure.
+* Istarget Procedure: istarget procedure.
+* Isnative Procedure: isnative procedure.
+* Unknown Procedure: unknown procedure.
+* Clone_output Procedure: clone_output procedure.
+* Reset_vars Procedure: reset_vars procedure.
+* Log_and_exit Procedure: log_and_exit procedure.
+* Log_summary Procedure: log_summary procedure.
+* Cleanup Procedure: cleanup procedure.
+* Setup_xfail Procedure: setup_xfail procedure.
+* Record_test Procedure: record_test procedure.
+* Pass Procedure: pass procedure.
+* Fail Procedure: fail procedure.
+* Xpass Procedure: xpass procedure.
+* Xfail Procedure: xfail procedure.
+* Set_warning_threshold Procedure: set_warning_threshold procedure.
+* Get_warning_threshold Procedure: get_warning_threshold procedure.
+* Warning Procedure: warning procedure.
+* Perror Procedure: perror procedure.
+* Note Procedure: note procedure.
+* Untested Procedure: untested procedure.
+* Unresolved Procedure: unresolved procedure.
+* Unsupported Procedure: unsupported procedure.
+* Init_testcounts Procedure: init_testcounts procedure.
+* Incr_count Procedure: incr_count procedure.
+* transform Procedure: transform procedure.
+* Check_conditional_xfail Procedure: check_conditional_xfail procedure.
+* Clear_xfail Procedure: clear_xfail procedure.
+* Verbose Procedure: verbose procedure.
+* Load_lib Procedure: load_lib procedure.
+@end menu
+
+@node mail_file procedure, open_logs procedure, , Core Internal Procedures
+@subsubsection Mail_file Procedure
+
+@quotation
+
+@t{@b{mail_file}(@i{file to
+subject});}
+@end quotation
+
+@table @asis
+
+@item @code{}
+@end table
+
+@node open_logs procedure, close_logs procedure, mail_file procedure, Core Internal Procedures
+@subsubsection Open_logs Procedure
+
+@quotation
+
+@t{@b{open_logs}(@i{});}
+@end quotation
+
+@node close_logs procedure, isbuild procedure, open_logs procedure, Core Internal Procedures
+@subsubsection Close_logs Procedure
+
+
+@quotation
+
+@t{@b{close_logs}(@i{});}
+@end quotation
+
+@node isbuild procedure, is_remote procedure, close_logs procedure, Core Internal Procedures
+@subsubsection Isbuild Procedure
+
+Tests for a particular build host environment. If the
+currently configured host matches the argument string, the result is
+@i{1}; otherwise the result is
+@i{0}. @i{host} must be a full
+three-part configure host name; in particular, you may not use the
+shorter nicknames supported by configure (but you can use wildcard
+characters, using shell syntax, to specify sets of names). If it is
+passed a NULL string, then it returns the name of the build canonical
+configuration.
+
+@quotation
+
+@t{@b{isbuild}(@i{pattern});}
+@end quotation
+
+@table @asis
+
+@item @code{pattern}
+@end table
+
+@node is_remote procedure, is3way procedure, isbuild procedure, Core Internal Procedures
+@subsubsection Is_remote Procedure
+
+
+@quotation
+
+@t{@b{is_remote}(@i{board});}
+@end quotation
+
+@table @asis
+
+@item @code{}
+@end table
+
+@node is3way procedure, ishost procedure, is_remote procedure, Core Internal Procedures
+@subsubsection is3way Procedure
+
+Tests for a canadian cross. This is when the tests will be run
+on a remotly hosted cross compiler. If it is a canadian cross, then
+the result is @i{1}; otherwise the result is
+@i{0}.
+
+@quotation
+
+@t{@b{is3way}(@i{});}
+@end quotation
+
+@node ishost procedure, istarget procedure, is3way procedure, Core Internal Procedures
+@subsubsection Ishost Procedure
+
+Tests for a particular host environment. If the currently
+configured host matches the argument string, the result is
+@i{1}; otherwise the result is
+@i{0}. @i{host} must be a full
+three-part configure host name; in particular, you may not use the
+shorter nicknames supported by configure (but you can use wildcard
+characters, using shell syntax, to specify sets of names).
+
+@quotation
+
+@t{@b{ishost}(@i{pattern});}
+@end quotation
+
+@table @asis
+
+@item @code{}
+@end table
+
+@node istarget procedure, isnative procedure, ishost procedure, Core Internal Procedures
+@subsubsection Istarget Procedure
+
+Tests for a particular target environment. If the currently
+configured target matches the argument string, the result is
+@i{1} ; otherwise the result is
+@i{0}. target must be a full three-part configure
+target name; in particular, you may not use the shorter nicknames
+supported by configure (but you can use wildcard characters, using
+shell syntax, to specify sets of names). If it is passed a
+@i{NULL} string, then it returns the name of the
+build canonical configuration.
+
+@quotation
+
+@t{@b{istarget}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{}
+@end table
+
+@node isnative procedure, unknown procedure, istarget procedure, Core Internal Procedures
+@subsubsection Isnative Procedure
+
+Tests whether the current configuration has the same host and
+target. When it runs in a native configuration this procedure returns
+a @i{1}; otherwise it returns a
+@i{0}.
+
+@quotation
+
+@t{@b{isnative}(@i{});}
+@end quotation
+
+@node unknown procedure, clone_output procedure, isnative procedure, Core Internal Procedures
+@subsubsection Unknown Procedure
+
+
+@quotation
+
+@t{@b{unknown}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node clone_output procedure, reset_vars procedure, unknown procedure, Core Internal Procedures
+@subsubsection Clone_output Procedure
+
+
+@quotation
+
+@t{@b{clone_output}(@i{message});}
+@end quotation
+
+@table @asis
+
+@item @code{message}
+@end table
+
+@node reset_vars procedure, log_and_exit procedure, clone_output procedure, Core Internal Procedures
+@subsubsection Reset_vars Procedure
+
+
+@quotation
+
+@t{@b{reset_vars}(@i{});}
+@end quotation
+
+@node log_and_exit procedure, log_summary procedure, reset_vars procedure, Core Internal Procedures
+@subsubsection Log_and_exit Procedure
+
+
+@quotation
+
+@t{@b{log_and_exit}(@i{});}
+@end quotation
+
+@node log_summary procedure, cleanup procedure, log_and_exit procedure, Core Internal Procedures
+@subsubsection Log_summary Procedure
+
+
+@quotation
+
+@t{@b{log_summary}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node cleanup procedure, setup_xfail procedure, log_summary procedure, Core Internal Procedures
+@subsubsection Cleanup Procedure
+
+
+@quotation
+
+@t{@b{cleanup}(@i{});}
+@end quotation
+
+@node setup_xfail procedure, record_test procedure, cleanup procedure, Core Internal Procedures
+@subsubsection Setup_xfail Procedure
+
+Declares that the test is expected to fail on a particular set
+of configurations. The config argument must be a list of full
+three-part configure target name; in particular, you may not use the
+shorter nicknames supported by configure (but you can use the common
+shell wildcard characters to specify sets of names). The
+@i{bugid} argument is optional, and used only in the
+logging file output; use it as a link to a bug-tracking system such
+as GNATS.
+
+Once you use @code{setup_xfail}, the
+@code{fail} and @code{pass} procedures
+produce the messages @i{XFAIL} and
+@i{XPASS} respectively, allowing you to distinguish
+expected failures (and unexpected success!) from other test
+outcomes.
+
+@quotation
+
+@strong{Warning}
+
+Warning you must clear the expected failure after
+using setup_xfail in a test case. Any call to @code{pass
+}or @code{fail}l clears the expected failure
+implicitly; if the test has some other outcome, e.g. an error, you
+can call @code{clear_xfail} to clear the expected
+failure explicitly. Otherwise, the expected-failure declaration
+applies to whatever test runs next, leading to surprising
+results.
+@end quotation
+
+@quotation
+
+@t{@b{setup_xfail}(@i{config}
+@i{bugid});}
+@end quotation
+
+@table @asis
+
+@item @code{config}
+The config triplet to trigger whether this is an
+unexpected or expect failure.
+
+@item @code{bugid}
+The optional bugid, used to tie it this test case
+to a bug tracking system.
+@end table
+
+@node record_test procedure, pass procedure, setup_xfail procedure, Core Internal Procedures
+@subsubsection Record_test Procedure
+
+
+@quotation
+
+@t{@b{record_test}(@i{type}
+@i{message}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{type}
+
+@item @code{message}
+
+@item @code{args}
+@end table
+
+@node pass procedure, fail procedure, record_test procedure, Core Internal Procedures
+@subsubsection Pass Procedure
+
+Declares a test to have passed. @code{pass}
+writes in the log files a message beginning with
+@i{PASS} (or @i{XPASS}, if failure
+was expected), appending the argument
+@code{string}.
+
+@quotation
+
+@t{@b{pass}(@i{string});}
+@end quotation
+
+@table @asis
+
+@item @code{string}
+The string to use for this PASS
+message.
+@end table
+
+@node fail procedure, xpass procedure, pass procedure, Core Internal Procedures
+@subsubsection Fail Procedure
+
+Declares a test to have failed. @code{fail}
+writes in the log files a message beginning with
+@i{FAIL} (or @i{XFAIL}, if failure
+was expected), appending the argument
+@code{string}.
+
+@quotation
+
+@t{@b{fail}(@i{string});}
+@end quotation
+
+@table @asis
+
+@item @code{string}
+The string to use for this FAIL
+message.
+@end table
+
+@node xpass procedure, xfail procedure, fail procedure, Core Internal Procedures
+@subsubsection Xpass Procedure
+
+Declares a test to have unexpectably passed, when it was
+expected to be a failure. @code{xpass}
+writes in the log files a message beginning with
+@i{XPASS} (or @i{XFAIL}, if failure
+was expected), appending the argument
+@code{string}.
+
+@quotation
+
+@t{@b{xpass}(@i{string});}
+@end quotation
+
+@table @asis
+
+@item @code{string}
+The string to use for this output
+state.
+@end table
+
+@node xfail procedure, set_warning_threshold procedure, xpass procedure, Core Internal Procedures
+@subsubsection Xfail Procedure
+
+Declares a test to have expectably
+failed. @code{xfail}
+writes in the log files a message beginning with
+@i{XFAIL} (or @i{PASS}, if success
+was expected), appending the argument
+@code{string}.
+
+@quotation
+
+@t{@b{xpass}(@i{string});}
+@end quotation
+
+@table @asis
+
+@item @code{string}
+The string to use for this output
+state.
+@end table
+
+@node set_warning_threshold procedure, get_warning_threshold procedure, xfail procedure, Core Internal Procedures
+@subsubsection Set_warning_threshold Procedure
+
+Sets the value of @code{warning_threshold}. A value
+of @i{0} disables it: calls to
+@code{warning} will not turn a
+@i{PASS} or @i{FAIL} into an
+@i{UNRESOLVED}.
+
+@quotation
+
+@t{@b{set_warning_threshold}(@i{threshold});}
+@end quotation
+
+@table @asis
+
+@item @code{threshold}
+This is the value of the new warning
+threshold.
+@end table
+
+@node get_warning_threshold procedure, warning procedure, set_warning_threshold procedure, Core Internal Procedures
+@subsubsection Get_warning_threshold Procedure
+
+Returns the current value of
+@code{@{warning_threshold}. The default value is 3. This
+value controls how many @code{warning} procedures can
+be called before becoming @i{UNRESOLVED}.
+
+@quotation
+
+@t{@b{get_warning_threshold}(@i{});}
+@end quotation
+
+@node warning procedure, perror procedure, get_warning_threshold procedure, Core Internal Procedures
+@subsubsection Warning Procedure
+
+Declares detection of a minor error in the test case
+itself. @code{warning} writes in the log files a message
+beginning with @i{WARNING}, appending the argument
+@code{string}. Use @code{warning} rather
+than @code{perror} for cases (such as communication
+failure to be followed by a retry) where the test case can recover from
+the error. If the optional @code{number} is supplied,
+then this is used to set the internal count of warnings to that
+value.
+
+As a side effect, @code{warning_threshold} or more
+calls to warning in a single test case also changes the effect of the
+next @code{pass} or @code{fail} command:
+the test outcome becomes @i{UNRESOLVED} since an
+automatic @i{PASS} or @i{FAIL} may
+not be trustworthy after many warnings. If the optional numeric value
+is @i{0}, then there are no further side effects to
+calling this function, and the following test outcome doesn't become
+@i{UNRESOLVED}. This can be used for errors with no
+known side effects.
+
+@quotation
+
+@t{@b{warning}(@i{string}
+@i{number}
+);}
+@end quotation
+
+@table @asis
+
+@item @code{string}
+
+@item @code{number}
+The optional number to set the error counter. Thius
+is only used to fake out the counter when using the
+@code{xfail} procedure to control when it flips the
+output over to @i{UNRESOLVED}
+state.
+@end table
+
+@node perror procedure, note procedure, warning procedure, Core Internal Procedures
+@subsubsection Perror Procedure
+
+Declares a severe error in the testing framework
+itself. @code{perror} writes in the log files a message
+beginning with @i{ERROR}, appending the argument
+@code{string}.
+
+As a side effect, perror also changes the effect of the next
+@code{pass} or @code{fail} command: the
+test outcome becomes @i{UNRESOLVED}, since an
+automatic @i{PASS} or @i{FAIL} cannot
+be trusted after a severe error in the test framework. If the optional
+numeric value is @i{0}, then there are no further side
+effects to calling this function, and the following test outcome
+doesn't become @i{UNRESOLVED}. This can be used for
+errors with no known side effects.
+
+@quotation
+
+@t{@b{perror}(@i{string}
+@i{number}
+);}
+@end quotation
+
+@table @asis
+
+@item @code{string}
+
+@item @code{number}
+The optional number to set the error counter. Thius
+is only used to fake out the counter when using the
+@code{xfail} procedure to control when it flips the
+output over to @i{UNRESOLVED}
+state.
+@end table
+
+@node note procedure, untested procedure, perror procedure, Core Internal Procedures
+@subsubsection Note Procedure
+
+Appends an informational message to the log
+file. @code{note} writes in the log files a message
+beginning with @i{NOTE}, appending the argument
+@code{string}. Use @code{note}
+sparingly. The @code{verbose} should be used for most
+such messages, but in cases where a message is needed in the log file
+regardless of the verbosity level use @code{note}.
+
+@quotation
+
+@t{@b{note}(@i{string});}
+@end quotation
+
+@table @asis
+
+@item @code{string}
+The string to use for this note.
+@end table
+
+@node untested procedure, unresolved procedure, note procedure, Core Internal Procedures
+@subsubsection Untested Procedure
+
+Declares a test was not run. @code{untested} writes
+in the log file a message beginning with @i{UNTESTED},
+appending the argument @i{string}. For example, you
+might use this in a dummy test whose only role is to record that a test
+does not yet exist for some feature.
+
+@quotation
+
+@t{@b{untested}(@i{string});}
+@end quotation
+
+@table @asis
+
+@item @code{string}
+The string to use for this output
+state.
+@end table
+
+@node unresolved procedure, unsupported procedure, untested procedure, Core Internal Procedures
+@subsubsection Unresolved Procedure
+
+Declares a test to have an unresolved
+outcome. @code{unresolved} writes in the log file a
+message beginning with @i{UNRESOLVED}, appending the
+argument @i{string}. This usually means the test did
+not execute as expected, and a human being must go over results to
+determine if it passed or failed (and to improve the test case).
+
+@quotation
+
+@t{@b{unresolved}(@i{string});}
+@end quotation
+
+@table @asis
+
+@item @code{string}
+The string to use for this output
+state.
+@end table
+
+@node unsupported procedure, init_testcounts procedure, unresolved procedure, Core Internal Procedures
+@subsubsection Unsupported Procedure
+
+Declares that a test case depends on some facility that does not
+exist in the testing environment. @code{unsupported}
+writes in the log file a message beginning with
+@i{UNSUPPORTED}, appending the argument string.
+
+@quotation
+
+@t{@b{unsupported}(@i{string});}
+@end quotation
+
+@table @asis
+
+@item @code{string}
+The string to use for this output
+state.
+@end table
+
+@node init_testcounts procedure, incr_count procedure, unsupported procedure, Core Internal Procedures
+@subsubsection Init_testcounts Procedure
+
+
+@quotation
+
+@t{@b{init_testcounts}(@i{});}
+@end quotation
+
+@node incr_count procedure, transform procedure, init_testcounts procedure, Core Internal Procedures
+@subsubsection Incr_count Procedure
+
+
+@quotation
+
+@t{@b{incr_count}(@i{name}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{name}
+
+@item @code{args}
+@end table
+
+@node transform procedure, check_conditional_xfail procedure, incr_count procedure, Core Internal Procedures
+@subsubsection transform Procedure
+
+Generates a string for the name of a tool as it was configured
+and installed, given its native name (as the argument
+@code{toolname}). This makes the assumption that all
+tools are installed using the same naming conventions: For example,
+for a cross compiler supporting the @i{m68k-vxworks}
+configuration, the result of transform @code{gcc} is
+@code{m68k-vxworks-gcc}.
+
+@quotation
+
+@t{@b{transform}(@i{toolname});}
+@end quotation
+
+@table @asis
+
+@item @code{toolname}
+The name of the cross-development program to
+transform.
+@end table
+
+@node check_conditional_xfail procedure, clear_xfail procedure, transform procedure, Core Internal Procedures
+@subsubsection Check_conditional_xfail Procedure
+
+This procedure adds a conditional xfail, based on compiler
+options used to create a test case executable. If an include options
+is found in the compiler flags, and it's the right architecture,
+it'll trigger an @i{XFAIL}. Otherwise it'll produce
+an ordinary @i{FAIL}. You can also specify flags to
+exclude. This makes a result be a @i{FAIL}, even if
+the included options are found. To set the conditional, set
+the variable @code{compiler_conditional_xfail_data} to the
+fields
+
+@example
+"[message string] [targets list] [includes
+ list] [excludes list]"
+@end example
+
+@noindent
+(descriptions below). This is
+the checked at pass/fail decision time, so there is no need to call
+the procedure yourself, unless you wish to know if it gets
+triggered. After a pass/fail, the variable is reset, so it doesn't
+effect other tests. It returns @i{1} if the
+conditional is true, or @i{0} if the conditional is
+false.
+
+@quotation
+
+@t{@b{check_conditional_xfail}(@i{message}
+@i{targets}
+@i{includes}
+@i{excludes});}
+@end quotation
+
+@table @asis
+
+@item @code{message}
+This is the message to print with the normal test
+result.
+
+@item @code{targets}
+This is a string with the list targets to activate
+this conditional on.
+
+@item @code{includes}
+This is a list of sets of options to search for in
+the compiler options to activate this conditional. If the list of
+sets of options is empty or if any set of the options matches,
+then this conditional is true. (It may be useful to specify an
+empty list of include sets if the conditional is always true
+unless one of the exclude sets matches.)
+
+@item @code{excludes}
+This is a list of sets of options to search for in
+the compiler options to activate this conditional. If any set of
+the options matches, (regardless of whether any of the include sets
+match) then this conditional is de-activated.
+@end table
+
+@strong{Specifying the conditional xfail data}
+
+@example
+
+ set compiler_conditional_xfail_data @{ \
+ "I sure wish I knew why this was hosed" \
+ "sparc*-sun*-* *-pc-*-*" \
+ @{"-Wall -v" "-O3"@} \
+ @{"-O1" "-Map"@} \
+ @}
+
+@end example
+
+What this does is it matches only for these two targets if
+"-Wall -v" or "-O3" is set, but neither "-O1" or "-Map" is set. For
+a set to match, the options specified are searched for independantly
+of each other, so a "-Wall -v" matches either "-Wall -v" or "-v
+-Wall". A space seperates the options in the string. Glob-style
+regular expressions are also permitted.
+
+@node clear_xfail procedure, verbose procedure, check_conditional_xfail procedure, Core Internal Procedures
+@subsubsection Clear_xfail Procedure
+
+Cancel an expected failure (previously declared with
+@code{setup_xfail}) for a particular set of
+configurations. The @code{config} argument is a list
+of configuration target names. It is only necessary to call
+@code{clear_xfail} if a test case ends without calling
+either @code{pass} or @code{fail}, after
+calling @code{setup_xfail}.
+
+@quotation
+
+@t{@b{clear_xfail}(@i{config});}
+@end quotation
+
+@table @asis
+
+@item @code{config}
+The configuration triplets to
+clear.
+@end table
+
+@node verbose procedure, load_lib procedure, clear_xfail procedure, Core Internal Procedures
+@subsubsection Verbose Procedure
+
+Test cases can use this function to issue helpful messages
+depending on the number of @code{--verbose} options on the
+runtest command line. It prints string if the value of the variable
+@code{verbose} is higher than or equal to the optional
+number. The default value for number is @i{1}. Use
+the optional @code{-log} argument to cause string to always
+be added to the log file, even if it won't be printed. Use the
+optional @code{-x} argument to log the test results into
+a parsable XML file. Use the optional @code{-n} argument
+to print string without a trailing newline. Use the optional
+@code{--} argument if string begins with "-".
+
+@quotation
+
+@t{@b{verbose}(@i{-log}
+@i{-x}
+@i{-n}
+@i{-r}
+@i{string}
+@i{number});}
+@end quotation
+
+@table @asis
+
+@item @code{-x}
+
+@item @code{-log}
+
+@item @code{-n}
+
+@item @code{--}
+
+@item @code{string}
+
+@item @code{number}
+@end table
+
+@node load_lib procedure, , verbose procedure, Core Internal Procedures
+@subsubsection Load_lib Procedure
+
+Loads a DejaGnu library file by searching a fixed path built
+into DejaGnu. If DejaGnu has been installed, it looks in a path
+starting with the installed library directory. If you are running
+DejaGnu directly from a source directory, without first running
+@code{make install}, this path defaults to the current
+directory. In either case, it then looks in the current directory
+for a directory called @file{lib}. If there are
+duplicate definitions, the last one loaded takes precedence over the
+earlier ones.
+
+@quotation
+
+@t{@b{load_lib}(@i{filespec});}
+@end quotation
+
+@table @asis
+
+@item @code{filespec}
+The name of the DejaGnu library file to
+load.
+@end table
+
+@node Procedures For Remote Communication, connprocs, Core Internal Procedures, Builtin Procedures
+@subsection Procedures For Remote Communication
+
+@file{lib/remote.exp} defines these
+functions, for establishing and managing communications. Each
+of these procedures tries to establish the connection up to
+three times before returning. Warnings (if retries will
+continue) or errors (if the attempt is abandoned) report on
+communication failures. The result for any of these
+procedures is either @i{-1}, when the
+connection cannot be established, or the spawn ID returned by
+the Expect command
+@code{spawn}.
+
+It use the value of the @code{connect} field
+in the @code{target_info} array (was
+@code{connectmode} as the type of connection to
+make. Current supported connection types are tip, kermit,
+telnet, rsh, rlogin, and netdata. If the @code{--reboot}
+option was used on the runtest command line, then the target
+is rebooted before the connection is made.
+
+@menu
+* Call_remote Procedure: call_remote procedure.
+* Check_for_board_status Procedure: check_for_board_status procedure.
+* File_on_build Procedure: file_on_build procedure.
+* File_on_host Procedure: file_on_host procedure.
+* Local_exec Procedure: local_exec procedure.
+* Remote_binary Procedure: remote_binary procedure.
+* Remote_close Procedure: remote_close procedure.
+* Remote_download Procedure: remote_download procedure.
+* Remote_exec Procedure: remote_exec procedure.
+* Remote_expect Procedure: remote_expect procedure.
+* Remote_file Procedure: remote_file procedure.
+* Remote_ld Procedure: remote_ld procedure.
+* Remote_load Procedure: remote_load procedure.
+* Remote_open Procedure: remote_open procedure.
+* Remote_pop_conn Procedure: remote_pop_conn procedure.
+* Remote_push_conn Procedure: remote_push_conn procedure.
+* Remote_raw_binary Procedure: remote_raw_binary procedure.
+* Remote_raw_close Procedure: remote_raw_close procedure.
+* Remote_raw_file Procedure: remote_raw_file procedure.
+* remote_raw_ld Procedure: remote_raw_ld procedure.
+* Remote_raw_load Procedure: remote_raw_load procedure.
+* Remote_raw_open Procedure: remote_raw_open procedure.
+* Remote_raw_send Procedure: remote_raw_send procedure.
+* Remote_raw_spawn Procedure: remote_raw_spawn procedure.
+* Remote_raw_transmit Procedure: remote_raw_transmit procedure.
+* Remote_raw_wait Procedure: remote_raw_wait procedure.
+* Remote_reboot Procedure: remote_reboot procedure.
+* Remote_send Procedure: remote_send procedure.
+* Remote_spawn Procedure: remote_spawn procedure.
+* Remote_swap_conn Procedure: remote_swap_conn procedure.
+* Remote_transmit Procedure: remote_transmit procedure.
+* Remote_upload Procedure: remote_upload procedure.
+* Remote_wait Procedure: remote_wait procedure.
+* Standard_close Procedure: standard_close procedure.
+* Standard_download Procedure: standard_download procedure.
+* Standard_exec Procedure: standard_exec procedure.
+* Standard_file Procedure: standard_file procedure.
+* Standard_load Procedure: standard_load procedure.
+* Standard_reboot Procedure: standard_reboot procedure.
+* Standard_send Procedure: standard_send procedure.
+* Standard_spawn Procedure: standard_spawn procedure.
+* Standard_transmit Procedure: standard_transmit procedure.
+* Standard_upload Procedure: standard_upload procedure.
+* Standard_wait Procedure: standard_wait procedure.
+* Unix_clean_filename Procedure: unix_clean_filename procedure.
+@end menu
+
+@node call_remote procedure, check_for_board_status procedure, , Procedures For Remote Communication
+@subsubsection Call_remote Procedure
+
+
+@quotation
+
+@t{@b{call_remote}(@i{type}
+@i{proc}
+@i{dest}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{proc}
+
+@item @code{dest}
+
+@item @code{args}
+@end table
+
+@node check_for_board_status procedure, file_on_build procedure, call_remote procedure, Procedures For Remote Communication
+@subsubsection Check_for_board_status Procedure
+
+
+@quotation
+
+@t{@b{check_for_board_status}(@i{variable});}
+@end quotation
+
+@table @asis
+
+@item @code{variable}
+@end table
+
+@node file_on_build procedure, file_on_host procedure, check_for_board_status procedure, Procedures For Remote Communication
+@subsubsection File_on_build Procedure
+
+
+@quotation
+
+@t{@b{file_on_build}(@i{op}
+@i{file}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{op}
+
+@item @code{file}
+
+@item @code{args}
+@end table
+
+@node file_on_host procedure, local_exec procedure, file_on_build procedure, Procedures For Remote Communication
+@subsubsection File_on_host Procedure
+
+
+@quotation
+
+@t{@b{file_on_host}(@i{op}
+@i{file}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{op}
+
+@item @code{file}
+
+@item @code{args}
+@end table
+
+@node local_exec procedure, remote_binary procedure, file_on_host procedure, Procedures For Remote Communication
+@subsubsection Local_exec Procedure
+
+
+@quotation
+
+@t{@b{local_exec}(@i{commandline}
+@i{inp}
+@i{outp}
+@i{timeout});}
+@end quotation
+
+@table @asis
+
+@item @code{inp}
+
+@item @code{outp}
+
+@item @code{timeout}
+@end table
+
+@node remote_binary procedure, remote_close procedure, local_exec procedure, Procedures For Remote Communication
+@subsubsection Remote_binary Procedure
+
+
+@quotation
+
+@t{@b{remote_binary}(@i{host});}
+@end quotation
+
+@table @asis
+
+@item @code{host}
+@end table
+
+@node remote_close procedure, remote_download procedure, remote_binary procedure, Procedures For Remote Communication
+@subsubsection Remote_close Procedure
+
+
+@quotation
+
+@t{@b{remote_close}(@i{shellid});}
+@end quotation
+
+@table @asis
+
+@item @code{shellid}
+This is the value returned by a call
+to @code{remote_open}. This closes the
+connection to the target so resources can be used by
+others. This parameter can be left off if the
+@code{fileid} field in the
+@code{target_info} array is set.
+@end table
+
+@node remote_download procedure, remote_exec procedure, remote_close procedure, Procedures For Remote Communication
+@subsubsection Remote_download Procedure
+
+
+@quotation
+
+@t{@b{remote_download}(@i{dest}
+@i{file}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{file}
+
+@item @code{args}
+@end table
+
+@node remote_exec procedure, remote_expect procedure, remote_download procedure, Procedures For Remote Communication
+@subsubsection Remote_exec Procedure
+
+
+@quotation
+
+@t{@b{remote_exec}(@i{hostname}
+@i{program}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{hostname}
+
+@item @code{program}
+
+@item @code{args}
+@end table
+
+@node remote_expect procedure, remote_file procedure, remote_exec procedure, Procedures For Remote Communication
+@subsubsection Remote_expect Procedure
+
+
+@quotation
+
+@t{@b{remote_expect}(@i{board}
+@i{timeout}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{board}
+
+@item @code{timeout}
+
+@item @code{args}
+@end table
+
+@node remote_file procedure, remote_ld procedure, remote_expect procedure, Procedures For Remote Communication
+@subsubsection Remote_file Procedure
+
+
+@quotation
+
+@t{@b{remote_file}(@i{dest}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{args}
+@end table
+
+@node remote_ld procedure, remote_load procedure, remote_file procedure, Procedures For Remote Communication
+@subsubsection Remote_ld Procedure
+
+
+@quotation
+
+@t{@b{remote_ld}(@i{dest}
+@i{prog});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{prog}
+@end table
+
+@node remote_load procedure, remote_open procedure, remote_ld procedure, Procedures For Remote Communication
+@subsubsection Remote_load Procedure
+
+
+@quotation
+
+@t{@b{remote_load}(@i{dest}
+@i{prog}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{prog}
+
+@item @code{args}
+@end table
+
+@node remote_open procedure, remote_pop_conn procedure, remote_load procedure, Procedures For Remote Communication
+@subsubsection Remote_open Procedure
+
+
+@quotation
+
+@t{@b{remote_open}(@i{type});}
+@end quotation
+
+@table @asis
+
+@item @code{type}
+This is passed @code{host} or
+@code{target}. Host or target refers to
+whether it is a connection to a remote target, or a
+remote host. This opens the connection to the desired
+target or host using the default values in the
+configuration system. It returns that
+@code{spawn_id} of the process that manages
+the connection. This value can be used in
+Expect or
+@code{exp_send} statements, or passed to
+other procedures that need the connection process's
+id. This also sets the @code{fileid} field in
+the @code{target_info} array.
+@end table
+
+@node remote_pop_conn procedure, remote_push_conn procedure, remote_open procedure, Procedures For Remote Communication
+@subsubsection Remote_pop_conn Procedure
+
+
+@quotation
+
+@t{@b{remote_pop_conn}(@i{host});}
+@end quotation
+
+@table @asis
+
+@item @code{host}
+@end table
+
+@node remote_push_conn procedure, remote_raw_binary procedure, remote_pop_conn procedure, Procedures For Remote Communication
+@subsubsection Remote_push_conn Procedure
+
+
+@quotation
+
+@t{@b{remote_push_conn}(@i{host});}
+@end quotation
+
+@table @asis
+
+@item @code{host}
+@end table
+
+@node remote_raw_binary procedure, remote_raw_close procedure, remote_push_conn procedure, Procedures For Remote Communication
+@subsubsection Remote_raw_binary Procedure
+
+
+@quotation
+
+@t{@b{remote_raw_binary}(@i{host});}
+@end quotation
+
+@table @asis
+
+@item @code{host}
+@end table
+
+@node remote_raw_close procedure, remote_raw_file procedure, remote_raw_binary procedure, Procedures For Remote Communication
+@subsubsection Remote_raw_close Procedure
+
+
+@quotation
+
+@t{@b{remote_raw_close}(@i{host});}
+@end quotation
+
+@table @asis
+
+@item @code{host}
+@end table
+
+@node remote_raw_file procedure, remote_raw_ld procedure, remote_raw_close procedure, Procedures For Remote Communication
+@subsubsection Remote_raw_file Procedure
+
+
+@quotation
+
+@t{@b{remote_raw_file}(@i{dest}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{args}
+@end table
+
+@node remote_raw_ld procedure, remote_raw_load procedure, remote_raw_file procedure, Procedures For Remote Communication
+@subsubsection remote_raw_ld Procedure
+
+
+@quotation
+
+@t{@b{remote_raw_ld}(@i{dest}
+@i{prog});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{prog}
+@end table
+
+@node remote_raw_load procedure, remote_raw_open procedure, remote_raw_ld procedure, Procedures For Remote Communication
+@subsubsection Remote_raw_load Procedure
+
+
+@quotation
+
+@t{@b{remote_raw_load}(@i{dest}
+@i{prog}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{prog}
+
+@item @code{args}
+@end table
+
+@node remote_raw_open procedure, remote_raw_send procedure, remote_raw_load procedure, Procedures For Remote Communication
+@subsubsection Remote_raw_open Procedure
+
+
+@quotation
+
+@t{@b{remote_raw_open}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node remote_raw_send procedure, remote_raw_spawn procedure, remote_raw_open procedure, Procedures For Remote Communication
+@subsubsection Remote_raw_send Procedure
+
+
+@quotation
+
+@t{@b{remote_raw_send}(@i{dest}
+@i{string});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{string}
+@end table
+
+@node remote_raw_spawn procedure, remote_raw_transmit procedure, remote_raw_send procedure, Procedures For Remote Communication
+@subsubsection Remote_raw_spawn Procedure
+
+
+@quotation
+
+@t{@b{remote_raw_spawn}(@i{dest}
+@i{commandline});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{commandline}
+@end table
+
+@node remote_raw_transmit procedure, remote_raw_wait procedure, remote_raw_spawn procedure, Procedures For Remote Communication
+@subsubsection Remote_raw_transmit Procedure
+
+
+@quotation
+
+@t{@b{remote_raw_transmit}(@i{dest}
+@i{file});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{file}
+@end table
+
+@node remote_raw_wait procedure, remote_reboot procedure, remote_raw_transmit procedure, Procedures For Remote Communication
+@subsubsection Remote_raw_wait Procedure
+
+
+@quotation
+
+@t{@b{remote_raw_wait}(@i{dest}
+@i{timeout});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{timeout}
+@end table
+
+@node remote_reboot procedure, remote_send procedure, remote_raw_wait procedure, Procedures For Remote Communication
+@subsubsection Remote_reboot Procedure
+
+
+@quotation
+
+@t{@b{remote_reboot}(@i{host});}
+@end quotation
+
+@table @asis
+
+@item @code{host}
+@end table
+
+@node remote_send procedure, remote_spawn procedure, remote_reboot procedure, Procedures For Remote Communication
+@subsubsection Remote_send Procedure
+
+
+@quotation
+
+@t{@b{remote_send}(@i{dest}
+@i{string});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{string}
+@end table
+
+@node remote_spawn procedure, remote_swap_conn procedure, remote_send procedure, Procedures For Remote Communication
+@subsubsection Remote_spawn Procedure
+
+
+@quotation
+
+@t{@b{remote_spawn}(@i{dest}
+@i{commandline}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{commandline}
+
+@item @code{args}
+@end table
+
+@node remote_swap_conn procedure, remote_transmit procedure, remote_spawn procedure, Procedures For Remote Communication
+@subsubsection Remote_swap_conn Procedure
+
+
+@quotation
+
+@t{@b{remote_swap_conn}(@i{host});}
+@end quotation
+
+@table @asis
+
+@item @code{}
+@end table
+
+@node remote_transmit procedure, remote_upload procedure, remote_swap_conn procedure, Procedures For Remote Communication
+@subsubsection Remote_transmit Procedure
+
+
+@quotation
+
+@t{@b{remote_transmit}(@i{dest}
+@i{file});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{file}
+@end table
+
+@node remote_upload procedure, remote_wait procedure, remote_transmit procedure, Procedures For Remote Communication
+@subsubsection Remote_upload Procedure
+
+
+@quotation
+
+@t{@b{remote_upload}(@i{dest}
+@i{srcfile}
+@i{arg});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{srcfile}
+
+@item @code{arg}
+@end table
+
+@node remote_wait procedure, standard_close procedure, remote_upload procedure, Procedures For Remote Communication
+@subsubsection Remote_wait Procedure
+
+
+@quotation
+
+@t{@b{remote_wait}(@i{dest}
+@i{timeout});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{timeout}
+@end table
+
+@node standard_close procedure, standard_download procedure, remote_wait procedure, Procedures For Remote Communication
+@subsubsection Standard_close Procedure
+
+@quotation
+
+@t{@b{standard_close}(@i{host});}
+@end quotation
+
+@table @asis
+
+@item @code{host}
+@end table
+
+@node standard_download procedure, standard_exec procedure, standard_close procedure, Procedures For Remote Communication
+@subsubsection Standard_download Procedure
+
+
+@quotation
+
+@t{@b{standard_download}(@i{dest}
+@i{file}
+@i{destfile});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{file}
+
+@item @code{destfile}
+@end table
+
+@node standard_exec procedure, standard_file procedure, standard_download procedure, Procedures For Remote Communication
+@subsubsection Standard_exec Procedure
+
+
+@quotation
+
+@t{@b{standard_exec}(@i{hostname}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{hostname}
+
+@item @code{args}
+@end table
+
+@node standard_file procedure, standard_load procedure, standard_exec procedure, Procedures For Remote Communication
+@subsubsection Standard_file Procedure
+
+
+@quotation
+
+@t{@b{standard_file}(@i{dest}
+@i{op}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{}
+@end table
+
+@node standard_load procedure, standard_reboot procedure, standard_file procedure, Procedures For Remote Communication
+@subsubsection Standard_load Procedure
+
+
+@quotation
+
+@t{@b{standard_load}(@i{dest}
+@i{prog}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{prog}
+
+@item @code{args}
+@end table
+
+@node standard_reboot procedure, standard_send procedure, standard_load procedure, Procedures For Remote Communication
+@subsubsection Standard_reboot Procedure
+
+
+@quotation
+
+@t{@b{standard_reboot}(@i{host});}
+@end quotation
+
+@table @asis
+
+@item @code{host}
+@end table
+
+@node standard_send procedure, standard_spawn procedure, standard_reboot procedure, Procedures For Remote Communication
+@subsubsection Standard_send Procedure
+
+
+@quotation
+
+@t{@b{standard_send}(@i{dest}
+@i{string});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{string}
+@end table
+
+@node standard_spawn procedure, standard_transmit procedure, standard_send procedure, Procedures For Remote Communication
+@subsubsection Standard_spawn Procedure
+
+
+@quotation
+
+@t{@b{standard_spawn}(@i{dest}
+@i{commandline});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{commndline}
+@end table
+
+@node standard_transmit procedure, standard_upload procedure, standard_spawn procedure, Procedures For Remote Communication
+@subsubsection Standard_transmit Procedure
+
+
+@quotation
+
+@t{@b{standard_transmit}(@i{dest}
+@i{file});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{file}
+@end table
+
+@node standard_upload procedure, standard_wait procedure, standard_transmit procedure, Procedures For Remote Communication
+@subsubsection Standard_upload Procedure
+
+
+@quotation
+
+@t{@b{standard_upload}(@i{dest srcfile destfile});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{srcfile}
+
+@item @code{destfile}
+@end table
+
+@node standard_wait procedure, unix_clean_filename procedure, standard_upload procedure, Procedures For Remote Communication
+@subsubsection Standard_wait Procedure
+
+
+@quotation
+
+@t{@b{standard_wait}(@i{dest}
+@i{timeout});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{timeout}
+@end table
+
+@node unix_clean_filename procedure, , standard_wait procedure, Procedures For Remote Communication
+@subsubsection Unix_clean_filename Procedure
+
+
+@quotation
+
+@t{@b{unix_clean_filename}(@i{dest}
+@i{file});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{file}
+@end table
+
+@node connprocs, Procedures For Target Boards, Procedures For Remote Communication, Builtin Procedures
+@subsection Procedures For Using Utilities to Connect
+
+telnet, rsh, tip, kermit
+
+@menu
+* telnet Procedure: telnet procedure.
+* rsh Procedure: rsh procedure.
+* Tip Procedure: tip procedure.
+* Kermit Procedure: kermit procedure.
+* kermit_open Procedure: kermit_open procedure.
+* Kermit_command Procedure: kermit_command procedure.
+* Kermit_send Procedure: kermit_send procedure.
+* Kermit_transmit Procedure: kermit_transmit procedure.
+* Telnet_open Procedure: telnet_open procedure.
+* Telnet_binary Procedure: telnet_binary procedure.
+* Telnet_transmit Procedure: telnet_transmit procedure.
+* Tip_open Procedure: tip_open procedure.
+* Rlogin_open Procedure: rlogin_open procedure.
+* Rlogin_spawn Procedure: rlogin_spawn procedure.
+* Rsh_open Procedure: rsh_open procedure.
+* Rsh_download Procedure: rsh_download procedure.
+* Rsh_upload Procedure: rsh_upload procedure.
+* Rsh_exec Procedure: rsh_exec procedure.
+* Ftp_open Procedure: ftp_open procedure.
+* Ftp_upload Procedure: ftp_upload procedure.
+* Ftp_download Procedure: ftp_download procedure.
+* Ftp_close Procedure: ftp_close procedure.
+* Tip_download Procedure: tip_download procedure.
+@end menu
+
+@node telnet procedure, rsh procedure, , connprocs
+@subsubsection telnet Procedure
+
+
+@quotation
+
+@t{@b{telnet}(@i{hostname}
+@i{port});}
+@end quotation
+
+@quotation
+
+@t{@b{rlogin}(@i{hostname});}
+@end quotation
+
+@node rsh procedure, tip procedure, telnet procedure, connprocs
+@subsubsection rsh Procedure
+
+
+@quotation
+
+@t{@b{rsh}(@i{hostname});}
+@end quotation
+
+@table @asis
+
+@item @code{hostname}
+This refers to the IP address or name
+(for example, an entry in
+@file{/etc/hosts}) for this target. The
+procedure names reflect the Unix utility used to
+establish a connection. The optional
+@code{port} is used to specify the IP
+port number. The value of the
+@code{netport} field in the
+@code{target_info} array is used. (was
+@code{$netport}) This value has two parts,
+the hostname and the port number, seperated by a
+@i{:}. If host or target is used in
+the @code{hostname} field, than the
+config array is used for all information.
+@end table
+
+@node tip procedure, kermit procedure, rsh procedure, connprocs
+@subsubsection Tip Procedure
+
+
+@quotation
+
+@t{@b{tip}(@i{port});}
+@end quotation
+
+@table @asis
+
+@item @code{port}
+Connect using the Unix utility
+@code{tip}. @code{Port}must
+be a name from the tip
+configuration file
+@file{/etc/remote}. Often, this is called
+@code{hardwire}, or something like
+@code{ttya}. This file holds all the
+configuration data for the serial port. The value of
+the @code{serial} field in the
+@code{target_info} array is used. (was
+@code{$serialport}) If @code{host}
+or @code{target} is used in the
+@code{port} field, than the config
+array is used for all information. the
+config array is used for all information.
+@end table
+
+@node kermit procedure, kermit_open procedure, tip procedure, connprocs
+@subsubsection Kermit Procedure
+
+
+@quotation
+
+@t{@b{kermit}(@i{port}
+@i{bps});}
+@end quotation
+
+@table @asis
+
+@item @code{port}
+Connect using the program
+@code{kermit}. @code{Port}
+is the device name,
+e.g. @file{/dev/ttyb}.
+
+@item @code{bps}
+@code{bps} is the line
+speed to use (in its per second) for the
+connection. The value of the @code{serial}
+field in the @code{target_info} array is
+used. (was @code{$serialport}) If
+@code{host} or @code{target} is
+used in the @code{port} field, than the
+config array is used for all information. the
+config array is used for all information.
+@end table
+
+@node kermit_open procedure, kermit_command procedure, kermit procedure, connprocs
+@subsubsection kermit_open Procedure
+
+
+@quotation
+
+@t{@b{kermit_open}(@i{dest}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{args}
+@end table
+
+@node kermit_command procedure, kermit_send procedure, kermit_open procedure, connprocs
+@subsubsection Kermit_command Procedure
+
+
+@quotation
+
+@t{@b{kermit_command}(@i{dest}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{args}
+@end table
+
+@node kermit_send procedure, kermit_transmit procedure, kermit_command procedure, connprocs
+@subsubsection Kermit_send Procedure
+
+
+@quotation
+
+@t{@b{kermit_send}(@i{dest string args});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{string}
+
+@item @code{args}
+@end table
+
+@node kermit_transmit procedure, telnet_open procedure, kermit_send procedure, connprocs
+@subsubsection Kermit_transmit Procedure
+
+
+@quotation
+
+@t{@b{kermit_transmit}(@i{dest}
+@i{file}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{file}
+
+@item @code{args}
+@end table
+
+@node telnet_open procedure, telnet_binary procedure, kermit_transmit procedure, connprocs
+@subsubsection Telnet_open Procedure
+
+
+@quotation
+
+@t{@b{telnet_open}(@i{hostname}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{hostname}
+
+@item @code{args}
+@end table
+
+@node telnet_binary procedure, telnet_transmit procedure, telnet_open procedure, connprocs
+@subsubsection Telnet_binary Procedure
+
+
+@quotation
+
+@t{@b{telnet_binary}(@i{hostname});}
+@end quotation
+
+@table @asis
+
+@item @code{hostname}
+@end table
+
+@node telnet_transmit procedure, tip_open procedure, telnet_binary procedure, connprocs
+@subsubsection Telnet_transmit Procedure
+
+
+@quotation
+
+@t{@b{telnet_transmit}(@i{dest}
+@i{file}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{file}
+
+@item @code{args}
+@end table
+
+@node tip_open procedure, rlogin_open procedure, telnet_transmit procedure, connprocs
+@subsubsection Tip_open Procedure
+
+
+@quotation
+
+@t{@b{tip_open}(@i{hostname});}
+@end quotation
+
+@table @asis
+
+@item @code{hostname}
+@end table
+
+@node rlogin_open procedure, rlogin_spawn procedure, tip_open procedure, connprocs
+@subsubsection Rlogin_open Procedure
+
+
+@quotation
+
+@t{@b{rlogin_open}(@i{arg});}
+@end quotation
+
+@table @asis
+
+@item @code{arg}
+@end table
+
+@node rlogin_spawn procedure, rsh_open procedure, rlogin_open procedure, connprocs
+@subsubsection Rlogin_spawn Procedure
+
+
+@quotation
+
+@t{@b{rlogin_spawn}(@i{dest}
+@i{cmdline});}
+@end quotation
+
+@table @asis
+
+@item @code{dest}
+
+@item @code{cmdline}
+@end table
+
+@node rsh_open procedure, rsh_download procedure, rlogin_spawn procedure, connprocs
+@subsubsection Rsh_open Procedure
+
+
+@quotation
+
+@t{@b{rsh_open}(@i{hostname});}
+@end quotation
+
+@table @asis
+
+@item @code{hostname}
+@end table
+
+@node rsh_download procedure, rsh_upload procedure, rsh_open procedure, connprocs
+@subsubsection Rsh_download Procedure
+
+
+@quotation
+
+@t{@b{rsh_download}(@i{desthost}
+@i{srcfile}
+@i{destfile});}
+@end quotation
+
+@table @asis
+
+@item @code{desthost}
+
+@item @code{srcfile}
+
+@item @code{destfile}
+@end table
+
+@node rsh_upload procedure, rsh_exec procedure, rsh_download procedure, connprocs
+@subsubsection Rsh_upload Procedure
+
+
+@quotation
+
+@t{@b{rsh_upload}(@i{desthost}
+@i{srcfile}
+@i{destfile});}
+@end quotation
+
+@table @asis
+
+@item @code{desthost}
+
+@item @code{srcfile}
+
+@item @code{destfile}
+@end table
+
+@node rsh_exec procedure, ftp_open procedure, rsh_upload procedure, connprocs
+@subsubsection Rsh_exec Procedure
+
+
+@quotation
+
+@t{@b{rsh_exec}(@i{boardname}
+@i{cmd}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{boardname}
+
+@item @code{cmd}
+
+@item @code{args}
+@end table
+
+@node ftp_open procedure, ftp_upload procedure, rsh_exec procedure, connprocs
+@subsubsection Ftp_open Procedure
+
+
+@quotation
+
+@t{@b{ftp_open}(@i{host});}
+@end quotation
+
+@table @asis
+
+@item @code{host}
+@end table
+
+@node ftp_upload procedure, ftp_download procedure, ftp_open procedure, connprocs
+@subsubsection Ftp_upload Procedure
+
+
+@quotation
+
+@t{@b{ftp_upload}(@i{host}
+@i{remotefile}
+@i{localfile});}
+@end quotation
+
+@table @asis
+
+@item @code{host}
+
+@item @code{remotefile}
+
+@item @code{localfile}
+@end table
+
+@node ftp_download procedure, ftp_close procedure, ftp_upload procedure, connprocs
+@subsubsection Ftp_download Procedure
+
+
+@quotation
+
+@t{@b{ftp_download}(@i{host}
+@i{localfile}
+@i{remotefile});}
+@end quotation
+
+@table @asis
+
+@item @code{host}
+
+@item @code{localfile}
+
+@item @code{remotefile}
+@end table
+
+@node ftp_close procedure, tip_download procedure, ftp_download procedure, connprocs
+@subsubsection Ftp_close Procedure
+
+
+@quotation
+
+@t{@b{ftp_close}(@i{host});}
+@end quotation
+
+@table @asis
+
+@item @code{host}
+@end table
+
+@node tip_download procedure, , ftp_close procedure, connprocs
+@subsubsection Tip_download Procedure
+
+
+@quotation
+
+@t{@b{tip_download}(@i{spawnid}
+@i{file});}
+@end quotation
+
+@table @asis
+
+@item @code{spawnid}
+Download @code{file} to the
+process @code{spawnid} (the value returned
+when the connection was established), using the
+@code{~put} command under
+tip. Most often used for
+single board computers that require downloading
+programs in ASCII S-records. Returns
+@i{1} if an error occurs,
+@i{0} otherwise.
+
+@item @code{file}
+This is the filename to
+downlaod.
+@end table
+
+@node Procedures For Target Boards, target database library file, connprocs, Builtin Procedures
+@subsection Procedures For Target Boards
+
+
+@menu
+* Default_link Procedure: default_link procedure.
+* Default_target_assemble Procedure: default_target_assemble procedure.
+* default_target_compile Procedure: default_target_compile procedure.
+* Pop_config Procedure: pop_config procedure.
+* Prune_warnings Procedure: prune_warnings procedure.
+* Push_build Procedure: push_build procedure.
+* push_config Procedure: push_config procedure.
+* Reboot_target Procedure: reboot_target procedure.
+* Target_assemble Procedure: target_assemble procedure.
+* Target_compile Procedure: target_compile procedure.
+@end menu
+
+@node default_link procedure, default_target_assemble procedure, , Procedures For Target Boards
+@subsubsection Default_link Procedure
+
+
+@quotation
+
+@t{@b{default_link}(@i{board}
+@i{objects}
+@i{destfile}
+@i{flags});}
+@end quotation
+
+@table @asis
+
+@item @code{board}
+
+@item @code{objects}
+
+@item @code{destfile}
+
+@item @code{flags}
+@end table
+
+@node default_target_assemble procedure, default_target_compile procedure, default_link procedure, Procedures For Target Boards
+@subsubsection Default_target_assemble Procedure
+
+
+@quotation
+
+@t{@b{default_target_assemble}(@i{source}
+@i{destfile}
+@i{flags});}
+@end quotation
+
+@table @asis
+
+@item @code{source}
+
+@item @code{destfile}
+
+@item @code{flags}
+@end table
+
+@node default_target_compile procedure, pop_config procedure, default_target_assemble procedure, Procedures For Target Boards
+@subsubsection default_target_compile Procedure
+
+
+@quotation
+
+@t{@b{default_target_compile}(@i{source}
+@i{destfile}
+@i{type}
+@i{options});}
+@end quotation
+
+@table @asis
+
+@item @code{source}
+
+@item @code{destfile}
+
+@item @code{type}
+
+@item @code{options}
+@end table
+
+@node pop_config procedure, prune_warnings procedure, default_target_compile procedure, Procedures For Target Boards
+@subsubsection Pop_config Procedure
+
+
+@quotation
+
+@t{@b{pop_config}(@i{type});}
+@end quotation
+
+@table @asis
+
+@item @code{type}
+@end table
+
+@node prune_warnings procedure, push_build procedure, pop_config procedure, Procedures For Target Boards
+@subsubsection Prune_warnings Procedure
+
+
+@quotation
+
+@t{@b{prune_warnings}(@i{text});}
+@end quotation
+
+@table @asis
+
+@item @code{text}
+@end table
+
+@node push_build procedure, push_config procedure, prune_warnings procedure, Procedures For Target Boards
+@subsubsection Push_build Procedure
+
+
+@quotation
+
+@t{@b{push_build}(@i{name});}
+@end quotation
+
+@table @asis
+
+@item @code{name}
+@end table
+
+@node push_config procedure, reboot_target procedure, push_build procedure, Procedures For Target Boards
+@subsubsection push_config Procedure
+
+
+@quotation
+
+@t{@b{push_config}(@i{type}
+@i{name});}
+@end quotation
+
+@table @asis
+
+@item @code{type}
+
+@item @code{name}
+@end table
+
+@node reboot_target procedure, target_assemble procedure, push_config procedure, Procedures For Target Boards
+@subsubsection Reboot_target Procedure
+
+
+@quotation
+
+@t{@b{reboot_target}(@i{});}
+@end quotation
+
+@node target_assemble procedure, target_compile procedure, reboot_target procedure, Procedures For Target Boards
+@subsubsection Target_assemble Procedure
+
+
+@quotation
+
+@t{@b{target_assemble}(@i{source destfile flags});}
+@end quotation
+
+@table @asis
+
+@item @code{source}
+
+@item @code{destfile}
+
+@item @code{flags}
+@end table
+
+@node target_compile procedure, , target_assemble procedure, Procedures For Target Boards
+@subsubsection Target_compile Procedure
+
+
+@quotation
+
+@t{@b{target_compile}(@i{source}
+@i{destfile}
+@i{type}
+@i{options});}
+@end quotation
+
+@table @asis
+
+@item @code{source}
+
+@item @code{destfile}
+
+@item @code{type}
+
+@item @code{options}
+@end table
+
+@node target database library file, platform dependant procedures, Procedures For Target Boards, Builtin Procedures
+@subsection Target Database Procedures
+
+@menu
+* Board_info Procedure: board_info procedure.
+* Host_info Procedure: host_info procedure.
+* Set_board_info Procedure: set_board_info procedure.
+* Set_currtarget_info Procedure: set_currtarget_info procedure.
+* Target_info Procedure: target_info procedure.
+* Unset_board_info Procedure: unset_board_info procedure.
+* Unset_currtarget_info Procedure: unset_currtarget_info procedure.
+* Push_target Procedure: push_target procedure.
+* Pop_target Procedure: poptarget procedure.
+* List_targets Procedure: list_targets procedure.
+* Push_host Procedure: push_host procedure.
+* Pop_host Procedure: pop_host procedure.
+* Compile Procedure: compile procedure.
+* Archive Procedure: archive procedure.
+* Ranlib Procedure: ranlib procedure.
+* Execute_anywhere Procedure: execute_anywhere procedure.
+@end menu
+
+@node board_info procedure, host_info procedure, , target database library file
+@subsubsection Board_info Procedure
+
+
+@quotation
+
+@t{@b{board_info}(@i{machine}
+@i{op}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{machine}
+
+@item @code{op}
+
+@item @code{args}
+@end table
+
+@node host_info procedure, set_board_info procedure, board_info procedure, target database library file
+@subsubsection Host_info Procedure
+
+
+@quotation
+
+@t{@b{host_info}(@i{op}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{op}
+
+@item @code{args}
+@end table
+
+@node set_board_info procedure, set_currtarget_info procedure, host_info procedure, target database library file
+@subsubsection Set_board_info Procedure
+
+
+@quotation
+
+@t{@b{set_board_info}(@i{entry}
+@i{value});}
+@end quotation
+
+@table @asis
+
+@item @code{entry}
+
+@item @code{value}
+@end table
+
+@node set_currtarget_info procedure, target_info procedure, set_board_info procedure, target database library file
+@subsubsection Set_currtarget_info Procedure
+
+
+@quotation
+
+@t{@b{set_currtarget_info}(@i{entry}
+@i{value});}
+@end quotation
+
+@table @asis
+
+@item @code{entry}
+
+@item @code{value}
+@end table
+
+@node target_info procedure, unset_board_info procedure, set_currtarget_info procedure, target database library file
+@subsubsection Target_info Procedure
+
+
+@quotation
+
+@t{@b{target_info}(@i{op}
+@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{op}
+
+@item @code{args}
+@end table
+
+@node unset_board_info procedure, unset_currtarget_info procedure, target_info procedure, target database library file
+@subsubsection Unset_board_info Procedure
+
+
+@quotation
+
+@t{@b{unset_board_info}(@i{entry});}
+@end quotation
+
+@table @asis
+
+@item @code{entry}
+@end table
+
+@node unset_currtarget_info procedure, push_target procedure, unset_board_info procedure, target database library file
+@subsubsection Unset_currtarget_info Procedure
+
+
+@quotation
+
+@t{@b{unset_currtarget_info}(@i{entry});}
+@end quotation
+
+@table @asis
+
+@item @code{entry}
+@end table
+
+@node push_target procedure, poptarget procedure, unset_currtarget_info procedure, target database library file
+@subsubsection Push_target Procedure
+
+This makes the target named @i{name} be the
+current target connection. The value of @i{name} is
+an index into the @code{target_info} array and is set in
+the global config file.
+
+@quotation
+
+@t{@b{push_target}(@i{name});}
+@end quotation
+
+@table @asis
+
+@item @code{name}
+The name of the target to make current
+connection.
+@end table
+
+@node poptarget procedure, list_targets procedure, push_target procedure, target database library file
+@subsubsection Pop_target Procedure
+
+This unsets the current target connection.
+
+@quotation
+
+@t{@b{pop_target}(@i{});}
+@end quotation
+
+@node list_targets procedure, push_host procedure, poptarget procedure, target database library file
+@subsubsection List_targets Procedure
+
+This lists all the supported targets for this
+architecture.
+
+@quotation
+
+@t{@b{list_targets}(@i{});}
+@end quotation
+
+@node push_host procedure, pop_host procedure, list_targets procedure, target database library file
+@subsubsection Push_host Procedure
+
+This makes the host named @i{name} be the
+current remote host connection. The value of
+@i{name} is an index into the
+@code{target_info} array and is set in the global config
+file.
+
+@quotation
+
+@t{@b{push_host}(@i{name});}
+@end quotation
+
+@table @asis
+
+@item @code{name}
+@end table
+
+@node pop_host procedure, compile procedure, push_host procedure, target database library file
+@subsubsection Pop_host Procedure
+
+This unsets the current host connection.
+
+@quotation
+
+@t{@b{pop_host}(@i{});}
+@end quotation
+
+@node compile procedure, archive procedure, pop_host procedure, target database library file
+@subsubsection Compile Procedure
+
+This invokes the compiler as set by CC to compile the
+file @file{file}. The default options for many cross
+compilation targets are @i{guessed} by DejaGnu, and
+these options can be added to by passing in more parameters as
+arguments to @code{compile}. Optionally, this will also
+use the value of the @i{cflags} field in the target
+config array. If the host is not the same as the build machines, then
+then compiler is run on the remote host using
+@code{execute_anywhere}.
+
+@quotation
+
+@t{@b{compile}(@i{file});}
+@end quotation
+
+@table @asis
+
+@item @code{file}
+@end table
+
+@node archive procedure, ranlib procedure, compile procedure, target database library file
+@subsubsection Archive Procedure
+
+This produces an archive file. Any parameters passed to
+@code{archive} are used in addition to the default
+flags. Optionally, this will also use the value of the
+@i{arflags} field in the target config array. If the
+host is not the same as the build machines, then then archiver is run
+on the remote host using @code{execute_anywhere}.
+
+@quotation
+
+@t{@b{archive}(@i{file});}
+@end quotation
+
+@table @asis
+
+@item @code{file}
+@end table
+
+@node ranlib procedure, execute_anywhere procedure, archive procedure, target database library file
+@subsubsection Ranlib Procedure
+
+This generates an index for the archive file for systems that
+aren't POSIX yet. Any parameters passed to @code{ranlib}
+are used in for the flags.
+
+@quotation
+
+@t{@b{ranlib}(@i{file});}
+@end quotation
+
+@table @asis
+
+@item @code{file}
+@end table
+
+@node execute_anywhere procedure, , ranlib procedure, target database library file
+@subsubsection Execute_anywhere Procedure
+
+This executes the @i{cmdline} on the proper
+host. This should be used as a replacement for the Tcl command
+@code{exec} as this version utilizes the target config
+info to execute this command on the build machine or a remote
+host. All config information for the remote host must be setup to
+have this command work. If this is a canadian cross, (where we test a
+cross compiler that runs on a different host then where DejaGnu is
+running) then a connection is made to the remote host and the command
+is executed there. It returns either REMOTERROR (for an error) or the
+output produced when the command was executed. This is used for
+running the tool to be tested, not a test case.
+
+@quotation
+
+@t{@b{execute_anywhere}(@i{cmdline});}
+@end quotation
+
+@table @asis
+
+@item @code{cmdline}
+@end table
+
+@node platform dependant procedures, Utility Procedures, target database library file, Builtin Procedures
+@subsection Platform Dependant Procedures
+
+Each combination of target and tool requires some
+target-dependent procedures. The names of these procedures have
+a common form: the tool name, followed by an underbar
+@i{_}, and finally a suffix describing the
+procedure's purpose. For example, a procedure to extract the
+version from GDB is called
+@code{gdb_version}.
+
+@code{runtest} itself calls only two of these
+procedures, @code{$@{tool@}_exit} and
+@code{$@{tool@}_version}; these procedures use no
+arguments.
+
+The other two procedures, @code{$@{tool@}_start}
+and @code{$@{tool@}_load}@}, are only called by the test
+suites themselves (or by testsuite-specific initialization
+code); they may take arguments or not, depending on the
+conventions used within each testsuite.
+
+The usual convention for return codes from any of these
+procedures (although it is not required by
+@code{runtest}) is to return @i{0}
+if the procedure succeeded, @i{1} if it failed,
+and @i{-1} if there was a communication error.
+
+@menu
+* $@{tool@}_start Procedure: $@{tool@}_start procedure.
+* $@{tool@}_load Procedure: $@{tool@}_load procedure.
+* $@{tool@}_exit Procedure: $@{tool@}_exit procedure.
+* $@{tool@}_version Procedure: $@{tool@}_version procedure.
+@end menu
+
+@node $@{tool@}_start procedure, $@{tool@}_load procedure, , platform dependant procedures
+@subsubsection $@{tool@}_start Procedure
+
+Starts a particular tool. For an interactive tool,
+@code{$@{tool@}_start} starts and initializes the
+tool, leaving the tool up and running for the test cases; an
+example is @code{gdb_start}, the start function
+for GDB. For a batch oriented tool,
+@code{$@{tool@}_start} is optional; the recommended
+convention is to let @code{$@{tool@}_start} run the
+tool, leaving the output in a variable called
+@code{comp_output}. Test scripts can then analyze
+@code{$comp_output} to determine the test results.
+An example of this second kind of start function is
+@code{gcc_start}, the start function for GCC.
+
+DejaGnu itself does not call
+@code{$@{tool@}_start}. The initialization
+module @code{$@{tool@}_init.exp} must call
+@code{$@{tool@}_start} for interactive tools;
+for batch-oriented tools, each individual test script calls
+@code{$@{tool@}_start} (or makes other
+arrangements to run the tool).
+
+@quotation
+
+@t{@b{$@{tool@}_start}(@i{});}
+@end quotation
+
+@node $@{tool@}_load procedure, $@{tool@}_exit procedure, $@{tool@}_start procedure, platform dependant procedures
+@subsubsection $@{tool@}_load Procedure
+
+Loads something into a tool. For an interactive tool,
+this conditions the tool for a particular test case; for
+example, @code{gdb_load} loads a new
+executable file into the debugger. For batch oriented tools,
+@code{$@{tool@}_load} may do nothing---though,
+for example, the GCC support uses
+@code{gcc_load} to load and run a binary on
+the target environment. Conventionally,
+@code{$@{tool@}_load} leaves the output of any
+program it runs in a variable called
+@code{$exec_output}. Writing
+@code{$@{tool@}_load} can be the most complex
+part of extending DejaGnu to a new tool or a new target, if
+it requires much communication coding or file
+downloading. Test scripts call
+@code{$@{tool@}_load}.
+
+@quotation
+
+@t{@b{$@{tool@}_load}(@i{});}
+@end quotation
+
+@node $@{tool@}_exit procedure, $@{tool@}_version procedure, $@{tool@}_load procedure, platform dependant procedures
+@subsubsection $@{tool@}_exit Procedure
+
+Cleans up (if necessary) before DejaGnu exits. For
+interactive tools, this usually ends the interactive
+session. You can also use @code{$@{tool@}_exit}
+to remove any temporary files left over from the
+tests. @code{runtest} calls
+@code{$@{tool@}_exit}.
+
+@quotation
+
+@t{@b{$@{tool@}_exit}(@i{});}
+@end quotation
+
+@node $@{tool@}_version procedure, , $@{tool@}_exit procedure, platform dependant procedures
+@subsubsection $@{tool@}_version Procedure
+
+Prints the version label and number for
+@code{$@{tool@}}. This is called by the DejaGnu
+procedure that prints the final summary report. The output
+should consist of the full path name used for the tested
+tool, and its version number.
+
+@quotation
+
+@t{@b{$@{tool@}_version}(@i{});}
+@end quotation
+
+@node Utility Procedures, Libgloss, platform dependant procedures, Builtin Procedures
+@subsection Utility Procedures
+
+@menu
+* Getdirs Procedure: getdirs procedure.
+* Find Procedure: find procedure.
+* Which Procedure: which procedure.
+* Grep Procedure: grep procedure.
+* Prune Procedure: prune procedure.
+* Slay Procedure: slay procedure.
+* Absolute Procedure: absolute procedure.
+* Psource Procedure: psource procedure.
+* Runtest_file_p Procedure: runtest_file_p procedure.
+* Diff Procedure: diff procedure.
+* Setenv Procedure: setenv procedure.
+* unsetenv Procedure: unsetenv procedure.
+* Getenv Procedure: getenv procedure.
+* Prune_system_crud Procedure: prune_system_crud procedure.
+@end menu
+
+@node getdirs procedure, find procedure, , Utility Procedures
+@subsubsection Getdirs Procedure
+
+Returns a list of all the directories in the single
+directory a single directory that match an optional
+pattern.
+
+@quotation
+
+@t{@b{getdirs}(@i{rootdir}
+@i{pattern});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+
+@item @code{pattern}
+If you do not specify
+@code{pattern},
+@code{Getdirs} assumes a default pattern of
+@i{*}. You may use the common shell
+wildcard characters in the pattern. If no directories
+match the pattern, then a NULL string is
+returned
+@end table
+
+@node find procedure, which procedure, getdirs procedure, Utility Procedures
+@subsubsection Find Procedure
+
+Search for files whose names match @i{pattern}
+(using shell wildcard characters for filename expansion). Search
+subdirectories recursively, starting at
+@i{rootdir}. The result is the list of files whose
+names match; if no files match, the result is empty. Filenames in the
+result include all intervening subdirectory names. If no files match
+the pattern, then a NULL string is returned.
+
+@quotation
+
+@t{@b{find}(@i{rootdir}
+@i{pattern});}
+@end quotation
+
+@table @asis
+
+@item @code{rootdir}
+The top level directory to search the search
+from.
+
+@item @code{pattern}
+A csh "glob" style regular expression reprsenting
+the files to find.
+@end table
+
+@node which procedure, grep procedure, find procedure, Utility Procedures
+@subsubsection Which Procedure
+
+Searches the execution path for an executable file
+@i{binary}, like the the BSD @code{which}
+utility. This procedure uses the shell environment variable
+@i{PATH}. It returns @i{0} if the
+binary is not in the path, or if there is no @i{PATH}
+environment variable. If @code{binary} is in the path, it
+returns the full path to @code{binary}.
+
+@quotation
+
+@t{@b{which}(@i{file});}
+@end quotation
+
+@table @asis
+
+@item @code{binary}
+The executable program or shell script to look
+for.
+@end table
+
+@node grep procedure, prune procedure, which procedure, Utility Procedures
+@subsubsection Grep Procedure
+
+Search the file called @file{filename} (a fully
+specified path) for lines that contain a match for regular expression
+@i{regexp}. The result is a list of all the lines that
+match. If no lines match, the result is an empty string. Specify
+@i{regexp} using the standard regular expression style
+used by the Unix utility program grep.
+
+Use the optional third argument @i{line} to
+start lines in the result with the line number in
+@file{filename}. (This argument is simply an option
+flag; type it just as shown @code{--line}.)
+
+@quotation
+
+@t{@b{grep}(@i{filename}
+@i{regexp}
+@i{--line});}
+@end quotation
+
+@table @asis
+
+@item @code{filename}
+The file to search.
+
+@item @code{regexp}
+The Unix style regular expression (as used by the
+@code{grep} Unix utility) to search
+for.
+
+@item @code{--line}
+Prefix the line number to each line where the
+regexp matches.
+@end table
+
+@node prune procedure, slay procedure, grep procedure, Utility Procedures
+@subsubsection Prune Procedure
+
+Remove elements of the Tcl list @i{list}.
+Elements are fields delimited by spaces. The result is a copy of
+list, without any elements that match @i{pattern}.
+You can use the common shell wildcard characters to specify the
+pattern.
+
+@quotation
+
+@t{@b{prune}(@i{list}
+@i{pattern});}
+@end quotation
+
+@table @asis
+
+@item @code{list}
+A Tcl list containing the original data. Commonly
+this is the output of a batch executed command, like running a
+compiler.
+
+@item @code{pattern}
+The csh shell "glob" style pattern to search
+for.
+@end table
+
+@node slay procedure, absolute procedure, prune procedure, Utility Procedures
+@subsubsection Slay Procedure
+
+This look in the process table for @i{name}
+and send it a unix SIGINT, killing the process. This will only work
+under Windows if you have Cygwin or another Unix subsystem for Windows
+installed.
+
+@quotation
+
+@t{@b{slay}(@i{name});}
+@end quotation
+
+@table @asis
+
+@item @code{name}
+The name of the program to kill.
+@end table
+
+@node absolute procedure, psource procedure, slay procedure, Utility Procedures
+@subsubsection Absolute Procedure
+
+This procedure takes the relative @i{path},
+and converts it to an absolute path.
+
+@quotation
+
+@t{@b{absolute}(@i{path});}
+@end quotation
+
+@table @asis
+
+@item @code{path}
+The path to convert.
+@end table
+
+@node psource procedure, runtest_file_p procedure, absolute procedure, Utility Procedures
+@subsubsection Psource Procedure
+
+This sources the file @i{filename}, and traps
+all errors. It also ignores all extraneous output. If there was an
+error it returns a @i{1}, otherwise it returns a
+@i{0}.
+
+@quotation
+
+@t{@b{psource}(@i{file});}
+@end quotation
+
+@table @asis
+
+@item @code{filename}
+The filename to Tcl script to
+source.
+@end table
+
+@node runtest_file_p procedure, diff procedure, psource procedure, Utility Procedures
+@subsubsection Runtest_file_p Procedure
+
+Search @i{runtest}s for
+@i{testcase} and return @i{1} if
+found, @i{0} if not. @i{runtests}
+is a list of two elements. The first is a copy of what was on
+the right side of the @i{=} if
+
+@example
+foo.exp="..."
+@end example
+
+@noindent
+" was specified, or
+an empty string if no such argument is present. The second is the
+pathname of the current testcase under consideration. This is used
+by tools like compilers where each testcase is a file.
+
+@quotation
+
+@t{@b{runtest_file_p}(@i{runtests}
+@i{testcase});}
+@end quotation
+
+@table @asis
+
+@item @code{runtests}
+The list of patterns to compare against.
+
+@item @code{testcase}
+The test case filename.
+@end table
+
+@node diff procedure, setenv procedure, runtest_file_p procedure, Utility Procedures
+@subsubsection Diff Procedure
+
+Compares the two files and returns a @i{1} if
+they match, or a @i{0} if they don't. If
+@code{verbose} is set, then it'll print the differences to
+the screen.
+
+@quotation
+
+@t{@b{diff}(@i{file_1}
+@i{file_2});}
+@end quotation
+
+@table @asis
+
+@item @code{file_1}
+The first file to compare.
+
+@item @code{file_2}
+The second file to compare.
+@end table
+
+@node setenv procedure, unsetenv procedure, diff procedure, Utility Procedures
+@subsubsection Setenv Procedure
+
+Sets the environment variable @i{var} to the
+value @i{val}.
+
+@quotation
+
+@t{@b{setenv}(@i{var}
+@i{val});}
+@end quotation
+
+@table @asis
+
+@item @code{var}
+The environment variable to set.
+
+@item @code{val}
+The value to set the variable to.
+@end table
+
+@node unsetenv procedure, getenv procedure, setenv procedure, Utility Procedures
+@subsubsection unsetenv Procedure
+
+Unsets the environment variable
+@i{var}.
+
+@quotation
+
+@t{@b{unsetenv}(@i{var});}
+@end quotation
+
+@table @asis
+
+@item @code{var}
+The environment variable to
+unset.
+@end table
+
+@node getenv procedure, prune_system_crud procedure, unsetenv procedure, Utility Procedures
+@subsubsection Getenv Procedure
+
+Returns the value of @i{var} in the
+environment if it exists, otherwise it returns NULL.
+
+@quotation
+
+@t{@b{getenv}(@i{var});}
+@end quotation
+
+@table @asis
+
+@item @code{var}
+The environment variable to get the value
+of.
+@end table
+
+@node prune_system_crud procedure, , getenv procedure, Utility Procedures
+@subsubsection Prune_system_crud Procedure
+
+For system @i{system}, delete text the host or
+target operating system might issue that will interfere with pattern
+matching of program output in @i{text}. An example
+is the message that is printed if a shared library is out of
+date.
+
+@quotation
+
+@t{@b{prune_system_crud}(@i{system}
+@i{test});}
+@end quotation
+
+@table @asis
+
+@item @code{system}
+The system error messages to look for to screen out
+.
+
+@item @code{text}
+The Tcl variable containing the
+text.
+@end table
+
+@node Libgloss, Debugging Procedures, Utility Procedures, Builtin Procedures
+@subsection Libgloss, A Free BSP
+
+Libgloss is a free @i{BSP} (Board Support
+Package) commonly used with GCC and G++ to produce a fully linked
+executable image for an embedded systems.
+
+@menu
+* Libgloss_link_flags Procedure: libgloss_link_flags procedure.
+* Libgloss_include_flags Procedure: libgloss_include_flags procedure.
+* Newlib_link_flags Procedure: newlib_link_flags procedure.
+* Newlib_include_flags Procedure: newlib_include_flags procedure.
+* Libio_include_flags Procedure: libio_include_flags procedure.
+* Libio_link_flags Procedure: libio_link_flags procedure.
+* G++_include_flags Procedure: g++_include_flags procedure.
+* G++_link_flags Procedure: g++_link_flags procedure.
+* Libstdc++_include_flags Procedure: libstdc++_include_flags procedure.
+* Libstdc++_link_flags Procedure: libstdc++_link_flags procedure.
+* Get_multilibs Procedure: get_multilibs procedure.
+* Find_binutils_prog Procedure: find_binutils_prog procedure.
+* Find_gcc Procedure: find_gcc procedure.
+* Find_gcj Procedure: find_gcj procedure.
+* Find_g++ Procedure: find_g++ procedure.
+* Find_g77 Procedure: find_g77 procedure.
+* Process_multilib_options Procedure: process_multilib_options procedure.
+* Add_multilib_option Procedure: add_multilib_option procedure.
+* Find_gas Procedure: find_gas procedure.
+* Find_ld Procedure: find_ld procedure.
+* Build_wrapper Procedure: build_wrapper procedure.
+* Winsup_include_flags Procedure: winsup_include_flags procedure.
+* Winsup_link_flags Procedure: winsup_link_flags procedure.
+@end menu
+
+@node libgloss_link_flags procedure, libgloss_include_flags procedure, , Libgloss
+@subsubsection Libgloss_link_flags Procedure
+
+
+@quotation
+
+@t{@b{libgloss_link_flags}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node libgloss_include_flags procedure, newlib_link_flags procedure, libgloss_link_flags procedure, Libgloss
+@subsubsection Libgloss_include_flags Procedure
+
+
+@quotation
+
+@t{@b{libgloss_include_flags}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node newlib_link_flags procedure, newlib_include_flags procedure, libgloss_include_flags procedure, Libgloss
+@subsubsection Newlib_link_flags Procedure
+
+
+@quotation
+
+@t{@b{newlib_link_flags}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node newlib_include_flags procedure, libio_include_flags procedure, newlib_link_flags procedure, Libgloss
+@subsubsection Newlib_include_flags Procedure
+
+
+@quotation
+
+@t{@b{newlib_include_flags}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node libio_include_flags procedure, libio_link_flags procedure, newlib_include_flags procedure, Libgloss
+@subsubsection Libio_include_flags Procedure
+
+
+@quotation
+
+@t{@b{libio_include_flags}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node libio_link_flags procedure, g++_include_flags procedure, libio_include_flags procedure, Libgloss
+@subsubsection Libio_link_flags Procedure
+
+
+@quotation
+
+@t{@b{libio_link_flags}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node g++_include_flags procedure, g++_link_flags procedure, libio_link_flags procedure, Libgloss
+@subsubsection G++_include_flags Procedure
+
+
+@quotation
+
+@t{@b{g++_include_flags}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node g++_link_flags procedure, libstdc++_include_flags procedure, g++_include_flags procedure, Libgloss
+@subsubsection G++_link_flags Procedure
+
+
+@quotation
+
+@t{@b{g++_link_flags}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node libstdc++_include_flags procedure, libstdc++_link_flags procedure, g++_link_flags procedure, Libgloss
+@subsubsection Libstdc++_include_flags Procedure
+
+
+@quotation
+
+@t{@b{libstdc++_include_flags}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node libstdc++_link_flags procedure, get_multilibs procedure, libstdc++_include_flags procedure, Libgloss
+@subsubsection Libstdc++_link_flags Procedure
+
+
+@quotation
+
+@t{@b{libstdc++_link_flags}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node get_multilibs procedure, find_binutils_prog procedure, libstdc++_link_flags procedure, Libgloss
+@subsubsection Get_multilibs Procedure
+
+
+@quotation
+
+@t{@b{get_multilibs}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node find_binutils_prog procedure, find_gcc procedure, get_multilibs procedure, Libgloss
+@subsubsection Find_binutils_prog Procedure
+
+
+@quotation
+
+@t{@b{find_binutils_prog}(@i{name});}
+@end quotation
+
+@table @asis
+
+@item @code{name}
+@end table
+
+@node find_gcc procedure, find_gcj procedure, find_binutils_prog procedure, Libgloss
+@subsubsection Find_gcc Procedure
+
+
+@quotation
+
+@t{@b{find_gcc}(@i{});}
+@end quotation
+
+@node find_gcj procedure, find_g++ procedure, find_gcc procedure, Libgloss
+@subsubsection Find_gcj Procedure
+
+
+@quotation
+
+@t{@b{find_gcj}(@i{});}
+@end quotation
+
+@node find_g++ procedure, find_g77 procedure, find_gcj procedure, Libgloss
+@subsubsection Find_g++ Procedure
+
+
+@quotation
+
+@t{@b{find_g++}(@i{});}
+@end quotation
+
+@node find_g77 procedure, process_multilib_options procedure, find_g++ procedure, Libgloss
+@subsubsection Find_g77 Procedure
+
+
+@quotation
+
+@t{@b{find_g77}(@i{});}
+@end quotation
+
+@node process_multilib_options procedure, add_multilib_option procedure, find_g77 procedure, Libgloss
+@subsubsection Process_multilib_options Procedure
+
+
+@quotation
+
+@t{@b{process_multilib_options}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node add_multilib_option procedure, find_gas procedure, process_multilib_options procedure, Libgloss
+@subsubsection Add_multilib_option Procedure
+
+
+@quotation
+
+@t{@b{add_multilib_option}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node find_gas procedure, find_ld procedure, add_multilib_option procedure, Libgloss
+@subsubsection Find_gas Procedure
+
+
+@quotation
+
+@t{@b{find_gas}(@i{});}
+@end quotation
+
+@node find_ld procedure, build_wrapper procedure, find_gas procedure, Libgloss
+@subsubsection Find_ld Procedure
+
+
+@quotation
-@example
-eg$ make install
-@end example
+@t{@b{find_ld}(@i{});}
+@end quotation
-@noindent
-@samp{make install} does these things for DejaGnu:
+@node build_wrapper procedure, winsup_include_flags procedure, find_ld procedure, Libgloss
+@subsubsection Build_wrapper Procedure
+
+
+@quotation
+
+@t{@b{build_wrapper}(@i{gluefile});}
+@end quotation
+
+@table @asis
+
+@item @code{gluefile}
+@end table
+
+@node winsup_include_flags procedure, winsup_link_flags procedure, build_wrapper procedure, Libgloss
+@subsubsection Winsup_include_flags Procedure
+
+
+@quotation
+
+@t{@b{winsup_include_flags}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node winsup_link_flags procedure, , winsup_include_flags procedure, Libgloss
+@subsubsection Winsup_link_flags Procedure
+
+
+@quotation
+
+@t{@b{winsup_link_flags}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node Debugging Procedures, , Libgloss, Builtin Procedures
+@subsection Procedures for debugging your Tcl code.
+
+@file{lib/debugger.exp}defines these utility
+procedures:
+
+@menu
+* Dumpvars Procedure: dumpvars procedure.
+* Dumplocals Procedure: dumplocals procedure.
+* Dumprocs Procedure: dumprocs procedure.
+* Dumpwatch Procedure: dumpwatch procedure.
+* Watcharray Procedure: watcharray procedure.
+* Watchvar Procedure: watchvar procedure.
+* Watchunset Procedure: watchunset procedure.
+* Watchwrite Procedure: watchwrite procedure.
+* Watchread Procedure: watchread procedure.
+* Watchdel Procedure: watchdel procedure.
+* Print Procedure: print procedure.
+* Quit Procedure: quit procedure.
+@end menu
+
+@node dumpvars procedure, dumplocals procedure, , Debugging Procedures
+@subsubsection Dumpvars Procedure
+
+This takes a csh style regular expression (glob rules) and prints
+the values of the global variable names that match. It is abbreviated
+as @i{dv}.
+
+@quotation
+
+@t{@b{dumpvars}(@i{vars});}
+@end quotation
+
+@table @asis
+
+@item @code{vars}
+The variables to dump.
+@end table
+
+@node dumplocals procedure, dumprocs procedure, dumpvars procedure, Debugging Procedures
+@subsubsection Dumplocals Procedure
+
+This takes a csh style regular expression (glob rules) and
+prints the values of the local variable names that match. It is
+abbreviated as @i{dl}.
+
+@quotation
+
+@t{@b{dumplocals}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node dumprocs procedure, dumpwatch procedure, dumplocals procedure, Debugging Procedures
+@subsubsection Dumprocs Procedure
+
+This takes a csh style regular expression (glob rules) and
+prints the body of all procs that match. It is abbreviated as
+@i{dp}.
+
+@quotation
+
+@t{@b{dumprocs}(@i{pattern});}
+@end quotation
+
+@table @asis
+
+@item @code{pattern}
+The csh "glob" style pattern to look
+for.
+@end table
+
+@node dumpwatch procedure, watcharray procedure, dumprocs procedure, Debugging Procedures
+@subsubsection Dumpwatch Procedure
+
+This takes a csh style regular expression (glob rules) and
+prints all the watchpoints. It is abbreviated as
+@i{dw}.
+
+@quotation
+
+@t{@b{dumpwatch}(@i{pattern});}
+@end quotation
+
+@table @asis
+
+@item @code{pattern}
+The csh "glob" style pattern to look
+for.
+@end table
+
+@node watcharray procedure, watchvar procedure, dumpwatch procedure, Debugging Procedures
+@subsubsection Watcharray Procedure
+
+
+@quotation
+
+@t{@b{watcharray}(@i{element}
+@i{type});}
+@end quotation
+
+@table @asis
+
+@item @code{type}
+The csh "glob" style pattern to look
+for.
+@end table
+
+@node watchvar procedure, watchunset procedure, watcharray procedure, Debugging Procedures
+@subsubsection Watchvar Procedure
+
+
+@quotation
+
+@t{@b{watchvar}(@i{var}
+@i{type});}
+@end quotation
+
+@table @asis
+
+@item @code{}
+@end table
+
+@node watchunset procedure, watchwrite procedure, watchvar procedure, Debugging Procedures
+@subsubsection Watchunset Procedure
+
+This breaks program execution when the variable
+@code{var} is unset. It is abbreviated as
+@i{wu}.
+
+@quotation
+
+@t{@b{watchunset}(@i{arg});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node watchwrite procedure, watchread procedure, watchunset procedure, Debugging Procedures
+@subsubsection Watchwrite Procedure
+
+This breaks program execution when the variable
+@code{var} is written. It is abbreviated as
+@i{ww}.
+
+@quotation
+
+@t{@b{watchwrite}(@i{var});}
+@end quotation
+
+@table @asis
+
+@item @code{var}
+The variable to watch.
+@end table
+
+@node watchread procedure, watchdel procedure, watchwrite procedure, Debugging Procedures
+@subsubsection Watchread Procedure
+
+This breaks program execution when the variable
+@code{var} is read. It is abbreviated as
+@i{wr}.
+
+@quotation
+
+@t{@b{watchread}(@i{var});}
+@end quotation
+
+@table @asis
+
+@item @code{var}
+The variable to watch.
+@end table
+
+@node watchdel procedure, print procedure, watchread procedure, Debugging Procedures
+@subsubsection Watchdel Procedure
+
+This deletes a the watchpoint from the watch list. It is
+abbreviated as @i{wd}.
+
+@quotation
+
+@t{@b{watchdel}(@i{args});}
+@end quotation
+
+@table @asis
+
+@item @code{args}
+@end table
+
+@node print procedure, quit procedure, watchdel procedure, Debugging Procedures
+@subsubsection Print Procedure
+
+This prints the value of the variable
+@code{var}. It is abbreviated as
+@i{p}.
+
+@quotation
+
+@t{@b{print}(@i{var});}
+@end quotation
+
+@table @asis
+
+@item @code{var}
+@end table
+
+@node quit procedure, , print procedure, Debugging Procedures
+@subsubsection Quit Procedure
+
+This makes runtest exit. It is abbreviated as
+@i{q}.
+
+@quotation
+
+@t{@b{quit}(@i{});}
+@end quotation
+
+@table @asis
+
+@item @code{}
+@end table
+
+@node File Map, , Builtin Procedures, Reference
+@section File Map
+
+This is a map of the files in DejaGnu.
+
+@itemize @bullet{}
+
+@item
+runtest
+
+@item
+runtest.exp
+
+@item
+stub-loader.c
+
+@item
+testglue.c
+
+@item
+config
+
+@item
+baseboards
+
+@item
+lib/debugger.exp
-@enumerate
@item
-Look in the path specified for executables (@file{$exec_prefix}) for
-directories called @file{lib} and @file{bin}. If these directories do
-not exist, @samp{make install} creates them.
+lib/dg.exp
@item
-Create another directory in the @file{lib} directory, called
-@file{dejagnu}.
+lib/framework.exp
@item
-Copy the @code{runtest} shell script into @file{$exec_prefix/bin}.
+lib/ftp.exp
@item
-Copy all the library files (used to support the framework) into
-@file{$exec_prefix/lib/dejagnu}.
+lib/kermit.exp
@item
-Copy @file{runtest.exp} into @file{$exec_prefix/lib/dejagnu}. This is
-the main Tcl code implementing DejaGnu.
+lib/libgloss.exp
+
+@item
+lib/mondfe.exp
+
+@item
+lib/remote.exp
+
+@item
+lib/rlogin.exp
+
+@item
+lib/rsh.exp
+
+@item
+lib/standard.exp
+
+@item
+lib/target.exp
+
+@item
+lib/targetdb.exp
+
+@item
+lib/telnet.exp
+
+@item
+lib/tip.exp
+
+@item
+lib/util-defs.exp
+
+@item
+lib/utils.exp
+
+@item
+lib/xsh.exp
+
+@item
+lib/dejagnu.exp
+@end itemize
+
+@node Unit Testing API, , Reference, Top
+@chapter Unit Testing API
+
+@menu
+* C Unit Testing API::
+* C++ Unit Testing API::
+@end menu
+
+@node C Unit Testing API, C++ Unit Testing API, , Unit Testing API
+@section C Unit Testing API
-@end enumerate
+All of the functions that take a
+@code{msg} parameter use a C char * that is
+the message to be dislayed. There currently is no support for
+variable length arguments.
-Each test suite collection comes with simple installation instructions
-in a @file{README} file; in general, the test suites are designed to be
-unpacked in the source directory for the corresponding tool, and extract
-into a directory called @file{testsuite}.
+@menu
+* Pass Function: pass function.
+* Fail Function: fail function.
+* Untested Function: untested function.
+* Unresolved Function: unresolved function.
+* Totals Function: totals function.
+@end menu
+
+@node pass function, fail function, , C Unit Testing API
+@subsection Pass Function
+
+This prints a message for a successful test
+completion.
+
+@quotation
+
+@t{@b{pass}(@i{msg});}
+@end quotation
+
+@node fail function, untested function, pass function, C Unit Testing API
+@subsection Fail Function
+
+This prints a message for an unsuccessful test
+completion.
+
+@quotation
+
+@t{@b{fail}(@i{msg});}
+@end quotation
+
+@node untested function, unresolved function, fail function, C Unit Testing API
+@subsection Untested Function
+
+This prints a message for an test case that isn't run
+for some technical reason.
+
+@quotation
+
+@t{@b{untested}(@i{msg});}
+@end quotation
+
+@node unresolved function, totals function, untested function, C Unit Testing API
+@subsection Unresolved Function
+
+This prints a message for an test case that is run,
+but there is no clear result. These output states require a
+human to look over the results to determine what happened.
+
+@quotation
+
+@t{@b{unresolved}(@i{msg});}
+@end quotation
+
+@node totals function, , unresolved function, C Unit Testing API
+@subsection Totals Function
+
+This prints out the total numbers of all the test
+state outputs.
+
+@quotation
+
+@t{@b{totals}(@i{});}
+@end quotation
-@node Index
-@unnumbered Index
+@node C++ Unit Testing API, , C Unit Testing API, Unit Testing API
+@section C++ Unit Testing API
-@printindex cp
+All of the methods that take a
+@code{msg} parameter use a C char *
+or STL string, that is the message to be
+dislayed. There currently is no support for variable
+length arguments.
-@contents
+@menu
+* Pass Method: pass method.
+* Fail Method: fail method.
+* Untested Method: untested method.
+* Unresolved Method: unresolved method.
+* Totals Method: totals method.
+@end menu
+
+@node pass method, fail method, , C++ Unit Testing API
+@subsection Pass Method
+
+This prints a message for a successful test
+completion.
+
+@quotation
+
+@t{@b{TestState::pass}(@i{msg});}
+@end quotation
+
+@node fail method, untested method, pass method, C++ Unit Testing API
+@subsection Fail Method
+
+This prints a message for an unsuccessful test
+completion.
+
+@quotation
+
+@t{@b{TestState::fail}(@i{msg});}
+@end quotation
+
+@node untested method, unresolved method, fail method, C++ Unit Testing API
+@subsection Untested Method
+
+This prints a message for an test case that isn't run
+for some technical reason.
+
+@quotation
+
+@t{@b{TestState::untested}(@i{msg});}
+@end quotation
+
+@node unresolved method, totals method, untested method, C++ Unit Testing API
+@subsection Unresolved Method
+
+This prints a message for an test case that is run,
+but there is no clear result. These output states require a
+human to look over the results to determine what happened.
+
+@quotation
+
+@t{@b{TestState::unresolved}(@i{msg});}
+@end quotation
+
+@node totals method, , unresolved method, C++ Unit Testing API
+@subsection Totals Method
+
+This prints out the total numbers of all the test
+state outputs.
+
+@quotation
+
+@t{@b{TestState::totals}(@i{});}
+@end quotation
@bye
projects / platform / upstream / dejagnu.git / commitdiff