aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/.cvsignore2
-rw-r--r--doc/Makefile.am47
-rw-r--r--doc/Makefile.in338
-rw-r--r--doc/README2
-rwxr-xr-xdoc/configure860
-rw-r--r--doc/configure.in5
-rw-r--r--doc/dejagnu.texi3572
-rw-r--r--doc/overview.sgml439
-rw-r--r--doc/ref.sgml4242
-rw-r--r--doc/runtest.1119
-rw-r--r--doc/user.sgml2355
11 files changed, 11981 insertions, 0 deletions
diff --git a/doc/.cvsignore b/doc/.cvsignore
new file mode 100644
index 0000000..7abff1d
--- /dev/null
+++ b/doc/.cvsignore
@@ -0,0 +1,2 @@
+Makefile
+config.status
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..9521a40
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,47 @@
+## Process this file with automake to generate Makefile.in
+
+AUTOMAKE_OPTIONS = cygnus
+
+info_TEXINFOS = dejagnu.texi
+
+TARGETS = overview.rtf overview.html overview.dvi overview.ps
+
+docs: $(TARGETS)
+
+%.ps: %.dvi
+ dvips -o $@ $<
+
+%.pdf: %.sgml
+ db2pdf $<
+
+%.dvi: %.sgml
+ db2dvi $<
+
+%.rtf: %.sgml
+ db2rtf -o $@ $<
+
+%.gif: %.fig
+ convert -transparency white $< $@ # .fig -> .gif
+
+%.epsi: %.eps
+ ps2epsi $< # .eps -> .epsi
+
+%.eps: %.fig
+ fig2dev -L ps -m 0.7 -p dummy $< > $@ # .fig -> .eps/portrait
+
+%.html: %.sgml
+ db2html $<
+
+# now for some extra dependencies that the automatic rules will not
+# catch:
+
+overview.pdf overview.ps overview.dvi overview.rtf overview.html: overview.sgml ref.sgml user.sgml
+
+clean:
+ rm -f $(TARGETS)
+
+# install-data-local: overview.pdf overview.html
+# $(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/html
+# $(INSTALL_DATA) overview/*.html $(DESTDIR)$(pkgdatadir)/html
+# $(INSTALL_DATA) overview.ps $(DESTDIR)$(pkgdatadir)/dejagnu.ps
+# $(INSTALL_DATA) overview.pdf $(DESTDIR)$(pkgdatadir)/dejagnu.pdf
diff --git a/doc/Makefile.in b/doc/Makefile.in
new file mode 100644
index 0000000..31d809b
--- /dev/null
+++ b/doc/Makefile.in
@@ -0,0 +1,338 @@
+# Makefile.in generated automatically by automake 1.4 from Makefile.am
+
+# Copyright (C) 1994, 1995-8, 1999 Free Software Foundation, Inc.
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+
+SHELL = @SHELL@
+
+srcdir = @srcdir@
+top_srcdir = @top_srcdir@
+VPATH = @srcdir@
+prefix = @prefix@
+exec_prefix = @exec_prefix@
+
+bindir = @bindir@
+sbindir = @sbindir@
+libexecdir = @libexecdir@
+datadir = @datadir@
+sysconfdir = @sysconfdir@
+sharedstatedir = @sharedstatedir@
+localstatedir = @localstatedir@
+libdir = @libdir@
+infodir = @infodir@
+mandir = @mandir@
+includedir = @includedir@
+oldincludedir = /usr/include
+
+DESTDIR =
+
+pkgdatadir = $(datadir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+
+top_builddir = ..
+
+ACLOCAL = @ACLOCAL@
+AUTOCONF = @AUTOCONF@
+AUTOMAKE = @AUTOMAKE@
+AUTOHEADER = @AUTOHEADER@
+
+INSTALL = @INSTALL@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@ $(AM_INSTALL_PROGRAM_FLAGS)
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+transform = @program_transform_name@
+
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+BOARDS = @BOARDS@
+CC = @CC@
+CONFIG = @CONFIG@
+EXEEXT = @EXEEXT@
+MAINT = @MAINT@
+MAKEINFO = @MAKEINFO@
+PACKAGE = @PACKAGE@
+VERSION = @VERSION@
+
+AUTOMAKE_OPTIONS = cygnus
+
+info_TEXINFOS = dejagnu.texi
+
+TARGETS = overview.rtf overview.html overview.dvi overview.ps
+mkinstalldirs = $(SHELL) $(top_srcdir)/../mkinstalldirs
+CONFIG_CLEAN_FILES =
+TEXI2DVI = `if test -f $(top_srcdir)/../texinfo/util/texi2dvi; then echo $(top_srcdir)/../texinfo/util/texi2dvi; else echo texi2dvi; fi`
+TEXINFO_TEX = $(top_srcdir)/../texinfo/texinfo.tex
+INFO_DEPS = dejagnu.info
+DVIS = dejagnu.dvi
+TEXINFOS = dejagnu.texi
+DIST_COMMON = README Makefile.am Makefile.in configure configure.in
+
+
+DISTFILES = $(DIST_COMMON) $(SOURCES) $(HEADERS) $(TEXINFOS) $(EXTRA_DIST)
+
+TAR = gtar
+GZIP_ENV = --best
+all: all-redirect
+.SUFFIXES:
+.SUFFIXES: .dvi .info .ps .texi .texinfo .txi
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ Makefile.am $(top_srcdir)/configure.in $(ACLOCAL_M4)
+ cd $(top_srcdir) && $(AUTOMAKE) --cygnus doc/Makefile
+
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+ cd $(top_builddir) \
+ && CONFIG_FILES=$(subdir)/$@ CONFIG_HEADERS= $(SHELL) ./config.status
+
+
+dejagnu.info: dejagnu.texi
+dejagnu.dvi: dejagnu.texi
+
+
+DVIPS = dvips
+
+.texi.info:
+ @rm -f $@ $@-[0-9] $@-[0-9][0-9]
+ $(MAKEINFO) -I $(srcdir) $<
+
+.texi.dvi:
+ TEXINPUTS=$(top_srcdir)/../texinfo/texinfo.tex:$$TEXINPUTS \
+ MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $<
+
+.texi:
+ @rm -f $@ $@-[0-9] $@-[0-9][0-9]
+ $(MAKEINFO) -I $(srcdir) $<
+
+.texinfo.info:
+ @rm -f $@ $@-[0-9] $@-[0-9][0-9]
+ $(MAKEINFO) -I $(srcdir) $<
+
+.texinfo:
+ @rm -f $@ $@-[0-9] $@-[0-9][0-9]
+ $(MAKEINFO) -I $(srcdir) $<
+
+.texinfo.dvi:
+ TEXINPUTS=$(top_srcdir)/../texinfo/texinfo.tex:$$TEXINPUTS \
+ MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $<
+
+.txi.info:
+ @rm -f $@ $@-[0-9] $@-[0-9][0-9]
+ $(MAKEINFO) -I $(srcdir) $<
+
+.txi.dvi:
+ TEXINPUTS=$(top_srcdir)/../texinfo/texinfo.tex:$$TEXINPUTS \
+ MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $<
+
+.txi:
+ @rm -f $@ $@-[0-9] $@-[0-9][0-9]
+ $(MAKEINFO) -I $(srcdir) $<
+.dvi.ps:
+ $(DVIPS) $< -o $@
+
+install-info-am: $(INFO_DEPS)
+ @$(NORMAL_INSTALL)
+ $(mkinstalldirs) $(DESTDIR)$(infodir)
+ @list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ if test -f $$file; then d=.; else d=$(srcdir); fi; \
+ for ifile in `cd $$d && echo $$file $$file-[0-9] $$file-[0-9][0-9]`; do \
+ if test -f $$d/$$ifile; then \
+ echo " $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile"; \
+ $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile; \
+ else : ; fi; \
+ done; \
+ done
+ @$(POST_INSTALL)
+ @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \
+ list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ echo " install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file";\
+ install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file || :;\
+ done; \
+ else : ; fi
+
+uninstall-info:
+ $(PRE_UNINSTALL)
+ @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \
+ ii=yes; \
+ else ii=; fi; \
+ list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ test -z "$ii" \
+ || install-info --info-dir=$(DESTDIR)$(infodir) --remove $$file; \
+ done
+ @$(NORMAL_UNINSTALL)
+ list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ (cd $(DESTDIR)$(infodir) && rm -f $$file $$file-[0-9] $$file-[0-9][0-9]); \
+ done
+
+dist-info: $(INFO_DEPS)
+ list='$(INFO_DEPS)'; \
+ for base in $$list; do \
+ if test -f $$base; then d=.; else d=$(srcdir); fi; \
+ for file in `cd $$d && eval echo $$base*`; do \
+ test -f $(distdir)/$$file \
+ || ln $$d/$$file $(distdir)/$$file 2> /dev/null \
+ || cp -p $$d/$$file $(distdir)/$$file; \
+ done; \
+ done
+
+mostlyclean-aminfo:
+ -rm -f dejagnu.aux dejagnu.cp dejagnu.cps dejagnu.dvi dejagnu.fn \
+ dejagnu.fns dejagnu.ky dejagnu.kys dejagnu.ps dejagnu.log \
+ dejagnu.pg dejagnu.toc dejagnu.tp dejagnu.tps dejagnu.vr \
+ dejagnu.vrs dejagnu.op dejagnu.tr dejagnu.cv dejagnu.cn
+
+clean-aminfo:
+
+distclean-aminfo:
+
+maintainer-clean-aminfo:
+ for i in $(INFO_DEPS); do \
+ rm -f $$i; \
+ if test "`echo $$i-[0-9]*`" != "$$i-[0-9]*"; then \
+ rm -f $$i-[0-9]*; \
+ fi; \
+ done
+clean-info: mostlyclean-aminfo
+tags: TAGS
+TAGS:
+
+
+distdir = $(top_builddir)/$(PACKAGE)-$(VERSION)/$(subdir)
+
+subdir = doc
+
+distdir: $(DISTFILES)
+ @for file in $(DISTFILES); do \
+ if test -f $$file; then d=.; else d=$(srcdir); fi; \
+ if test -d $$d/$$file; then \
+ cp -pr $$d/$$file $(distdir)/$$file; \
+ else \
+ test -f $(distdir)/$$file \
+ || ln $$d/$$file $(distdir)/$$file 2> /dev/null \
+ || cp -p $$d/$$file $(distdir)/$$file || :; \
+ fi; \
+ done
+ $(MAKE) $(AM_MAKEFLAGS) top_distdir="$(top_distdir)" distdir="$(distdir)" dist-info
+info-am: $(INFO_DEPS)
+info: info-am
+dvi-am: $(DVIS)
+dvi: dvi-am
+check-am:
+check: check-am
+installcheck-am:
+installcheck: installcheck-am
+install-info-am:
+install-info: install-info-am
+install-exec-am:
+install-exec: install-exec-am
+
+install-data-am:
+install-data: install-data-am
+
+install-am: all-am
+ @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+install: install-am
+uninstall-am:
+uninstall: uninstall-am
+all-am: Makefile
+all-redirect: all-am
+install-strip:
+ $(MAKE) $(AM_MAKEFLAGS) AM_INSTALL_PROGRAM_FLAGS=-s install
+installdirs:
+
+
+mostlyclean-generic:
+
+clean-generic:
+
+distclean-generic:
+ -rm -f Makefile $(CONFIG_CLEAN_FILES)
+ -rm -f config.cache config.log stamp-h stamp-h[0-9]*
+
+maintainer-clean-generic:
+mostlyclean-am: mostlyclean-aminfo mostlyclean-generic
+
+mostlyclean: mostlyclean-am
+
+clean-am: clean-aminfo clean-generic mostlyclean-am
+
+clean: clean-am
+
+distclean-am: distclean-aminfo distclean-generic clean-am
+
+distclean: distclean-am
+
+maintainer-clean-am: maintainer-clean-aminfo maintainer-clean-generic \
+ distclean-am
+ @echo "This command is intended for maintainers to use;"
+ @echo "it deletes files that may require special tools to rebuild."
+
+maintainer-clean: maintainer-clean-am
+
+.PHONY: install-info-am uninstall-info mostlyclean-aminfo \
+distclean-aminfo clean-aminfo maintainer-clean-aminfo tags distdir \
+info-am info dvi-am dvi check check-am installcheck-am installcheck \
+install-info-am install-info install-exec-am install-exec \
+install-data-am install-data install-am install uninstall-am uninstall \
+all-redirect all-am all installdirs mostlyclean-generic \
+distclean-generic clean-generic maintainer-clean-generic clean \
+mostlyclean distclean maintainer-clean
+
+
+docs: $(TARGETS)
+
+%.ps: %.dvi
+ dvips -o $@ $<
+
+%.pdf: %.sgml
+ db2pdf $<
+
+%.dvi: %.sgml
+ db2dvi $<
+
+%.rtf: %.sgml
+ db2rtf -o $@ $<
+
+%.gif: %.fig
+ convert -transparency white $< $@ # .fig -> .gif
+
+%.epsi: %.eps
+ ps2epsi $< # .eps -> .epsi
+
+%.eps: %.fig
+ fig2dev -L ps -m 0.7 -p dummy $< > $@ # .fig -> .eps/portrait
+
+%.html: %.sgml
+ db2html $<
+
+# now for some extra dependencies that the automatic rules will not
+# catch:
+
+overview.pdf overview.ps overview.dvi overview.rtf overview.html: overview.sgml ref.sgml user.sgml
+
+clean:
+ rm -f $(TARGETS)
+
+# install-data-local: overview.pdf overview.html
+# $(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/html
+# $(INSTALL_DATA) overview/*.html $(DESTDIR)$(pkgdatadir)/html
+# $(INSTALL_DATA) overview.ps $(DESTDIR)$(pkgdatadir)/dejagnu.ps
+# $(INSTALL_DATA) overview.pdf $(DESTDIR)$(pkgdatadir)/dejagnu.pdf
+
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT:
diff --git a/doc/README b/doc/README
new file mode 100644
index 0000000..fc8ae45
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,2 @@
+One can obtain the Free DocBook Tools for Linux and NT at
+http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html
diff --git a/doc/configure b/doc/configure
new file mode 100755
index 0000000..638b3bf
--- /dev/null
+++ b/doc/configure
@@ -0,0 +1,860 @@
+#! /bin/sh
+
+# Guess values for system-dependent variables and create Makefiles.
+# Generated automatically using autoconf version 2.12.1
+# Copyright (C) 1992, 93, 94, 95, 96 Free Software Foundation, Inc.
+#
+# This configure script is free software; the Free Software Foundation
+# gives unlimited permission to copy, distribute and modify it.
+
+# Defaults:
+ac_help=
+ac_default_prefix=/usr/local
+# Any additions from configure.in:
+
+# Initialize some variables set by options.
+# The variables have the same names as the options, with
+# dashes changed to underlines.
+build=NONE
+cache_file=./config.cache
+exec_prefix=NONE
+host=NONE
+no_create=
+nonopt=NONE
+no_recursion=
+prefix=NONE
+program_prefix=NONE
+program_suffix=NONE
+program_transform_name=s,x,x,
+silent=
+site=
+srcdir=
+target=NONE
+verbose=
+x_includes=NONE
+x_libraries=NONE
+bindir='${exec_prefix}/bin'
+sbindir='${exec_prefix}/sbin'
+libexecdir='${exec_prefix}/libexec'
+datadir='${prefix}/share'
+sysconfdir='${prefix}/etc'
+sharedstatedir='${prefix}/com'
+localstatedir='${prefix}/var'
+libdir='${exec_prefix}/lib'
+includedir='${prefix}/include'
+oldincludedir='/usr/include'
+infodir='${prefix}/info'
+mandir='${prefix}/man'
+
+# Initialize some other variables.
+subdirs=
+MFLAGS= MAKEFLAGS=
+SHELL=${CONFIG_SHELL-/bin/sh}
+# Maximum number of lines to put in a shell here document.
+ac_max_here_lines=12
+
+ac_prev=
+for ac_option
+do
+
+ # If the previous option needs an argument, assign it.
+ if test -n "$ac_prev"; then
+ eval "$ac_prev=\$ac_option"
+ ac_prev=
+ continue
+ fi
+
+ case "$ac_option" in
+ -*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;;
+ *) ac_optarg= ;;
+ esac
+
+ # Accept the important Cygnus configure options, so we can diagnose typos.
+
+ case "$ac_option" in
+
+ -bindir | --bindir | --bindi | --bind | --bin | --bi)
+ ac_prev=bindir ;;
+ -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*)
+ bindir="$ac_optarg" ;;
+
+ -build | --build | --buil | --bui | --bu)
+ ac_prev=build ;;
+ -build=* | --build=* | --buil=* | --bui=* | --bu=*)
+ build="$ac_optarg" ;;
+
+ -cache-file | --cache-file | --cache-fil | --cache-fi \
+ | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c)
+ ac_prev=cache_file ;;
+ -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \
+ | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*)
+ cache_file="$ac_optarg" ;;
+
+ -datadir | --datadir | --datadi | --datad | --data | --dat | --da)
+ ac_prev=datadir ;;
+ -datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \
+ | --da=*)
+ datadir="$ac_optarg" ;;
+
+ -disable-* | --disable-*)
+ ac_feature=`echo $ac_option|sed -e 's/-*disable-//'`
+ # Reject names that are not valid shell variable names.
+ if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then
+ { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; }
+ fi
+ ac_feature=`echo $ac_feature| sed 's/-/_/g'`
+ eval "enable_${ac_feature}=no" ;;
+
+ -enable-* | --enable-*)
+ ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'`
+ # Reject names that are not valid shell variable names.
+ if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then
+ { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; }
+ fi
+ ac_feature=`echo $ac_feature| sed 's/-/_/g'`
+ case "$ac_option" in
+ *=*) ;;
+ *) ac_optarg=yes ;;
+ esac
+ eval "enable_${ac_feature}='$ac_optarg'" ;;
+
+ -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \
+ | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \
+ | --exec | --exe | --ex)
+ ac_prev=exec_prefix ;;
+ -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \
+ | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \
+ | --exec=* | --exe=* | --ex=*)
+ exec_prefix="$ac_optarg" ;;
+
+ -gas | --gas | --ga | --g)
+ # Obsolete; use --with-gas.
+ with_gas=yes ;;
+
+ -help | --help | --hel | --he)
+ # Omit some internal or obsolete options to make the list less imposing.
+ # This message is too long to be a string in the A/UX 3.1 sh.
+ cat << EOF
+Usage: configure [options] [host]
+Options: [defaults in brackets after descriptions]
+Configuration:
+ --cache-file=FILE cache test results in FILE
+ --help print this message
+ --no-create do not create output files
+ --quiet, --silent do not print \`checking...' messages
+ --version print the version of autoconf that created configure
+Directory and file names:
+ --prefix=PREFIX install architecture-independent files in PREFIX
+ [$ac_default_prefix]
+ --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX
+ [same as prefix]
+ --bindir=DIR user executables in DIR [EPREFIX/bin]
+ --sbindir=DIR system admin executables in DIR [EPREFIX/sbin]
+ --libexecdir=DIR program executables in DIR [EPREFIX/libexec]
+ --datadir=DIR read-only architecture-independent data in DIR
+ [PREFIX/share]
+ --sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc]
+ --sharedstatedir=DIR modifiable architecture-independent data in DIR
+ [PREFIX/com]
+ --localstatedir=DIR modifiable single-machine data in DIR [PREFIX/var]
+ --libdir=DIR object code libraries in DIR [EPREFIX/lib]
+ --includedir=DIR C header files in DIR [PREFIX/include]
+ --oldincludedir=DIR C header files for non-gcc in DIR [/usr/include]
+ --infodir=DIR info documentation in DIR [PREFIX/info]
+ --mandir=DIR man documentation in DIR [PREFIX/man]
+ --srcdir=DIR find the sources in DIR [configure dir or ..]
+ --program-prefix=PREFIX prepend PREFIX to installed program names
+ --program-suffix=SUFFIX append SUFFIX to installed program names
+ --program-transform-name=PROGRAM
+ run sed PROGRAM on installed program names
+EOF
+ cat << EOF
+Host type:
+ --build=BUILD configure for building on BUILD [BUILD=HOST]
+ --host=HOST configure for HOST [guessed]
+ --target=TARGET configure for TARGET [TARGET=HOST]
+Features and packages:
+ --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no)
+ --enable-FEATURE[=ARG] include FEATURE [ARG=yes]
+ --with-PACKAGE[=ARG] use PACKAGE [ARG=yes]
+ --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no)
+ --x-includes=DIR X include files are in DIR
+ --x-libraries=DIR X library files are in DIR
+EOF
+ if test -n "$ac_help"; then
+ echo "--enable and --with options recognized:$ac_help"
+ fi
+ exit 0 ;;
+
+ -host | --host | --hos | --ho)
+ ac_prev=host ;;
+ -host=* | --host=* | --hos=* | --ho=*)
+ host="$ac_optarg" ;;
+
+ -includedir | --includedir | --includedi | --included | --include \
+ | --includ | --inclu | --incl | --inc)
+ ac_prev=includedir ;;
+ -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \
+ | --includ=* | --inclu=* | --incl=* | --inc=*)
+ includedir="$ac_optarg" ;;
+
+ -infodir | --infodir | --infodi | --infod | --info | --inf)
+ ac_prev=infodir ;;
+ -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*)
+ infodir="$ac_optarg" ;;
+
+ -libdir | --libdir | --libdi | --libd)
+ ac_prev=libdir ;;
+ -libdir=* | --libdir=* | --libdi=* | --libd=*)
+ libdir="$ac_optarg" ;;
+
+ -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \
+ | --libexe | --libex | --libe)
+ ac_prev=libexecdir ;;
+ -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \
+ | --libexe=* | --libex=* | --libe=*)
+ libexecdir="$ac_optarg" ;;
+
+ -localstatedir | --localstatedir | --localstatedi | --localstated \
+ | --localstate | --localstat | --localsta | --localst \
+ | --locals | --local | --loca | --loc | --lo)
+ ac_prev=localstatedir ;;
+ -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \
+ | --localstate=* | --localstat=* | --localsta=* | --localst=* \
+ | --locals=* | --local=* | --loca=* | --loc=* | --lo=*)
+ localstatedir="$ac_optarg" ;;
+
+ -mandir | --mandir | --mandi | --mand | --man | --ma | --m)
+ ac_prev=mandir ;;
+ -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*)
+ mandir="$ac_optarg" ;;
+
+ -nfp | --nfp | --nf)
+ # Obsolete; use --without-fp.
+ with_fp=no ;;
+
+ -no-create | --no-create | --no-creat | --no-crea | --no-cre \
+ | --no-cr | --no-c)
+ no_create=yes ;;
+
+ -no-recursion | --no-recursion | --no-recursio | --no-recursi \
+ | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r)
+ no_recursion=yes ;;
+
+ -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \
+ | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \
+ | --oldin | --oldi | --old | --ol | --o)
+ ac_prev=oldincludedir ;;
+ -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \
+ | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \
+ | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*)
+ oldincludedir="$ac_optarg" ;;
+
+ -prefix | --prefix | --prefi | --pref | --pre | --pr | --p)
+ ac_prev=prefix ;;
+ -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*)
+ prefix="$ac_optarg" ;;
+
+ -program-prefix | --program-prefix | --program-prefi | --program-pref \
+ | --program-pre | --program-pr | --program-p)
+ ac_prev=program_prefix ;;
+ -program-prefix=* | --program-prefix=* | --program-prefi=* \
+ | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*)
+ program_prefix="$ac_optarg" ;;
+
+ -program-suffix | --program-suffix | --program-suffi | --program-suff \
+ | --program-suf | --program-su | --program-s)
+ ac_prev=program_suffix ;;
+ -program-suffix=* | --program-suffix=* | --program-suffi=* \
+ | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*)
+ program_suffix="$ac_optarg" ;;
+
+ -program-transform-name | --program-transform-name \
+ | --program-transform-nam | --program-transform-na \
+ | --program-transform-n | --program-transform- \
+ | --program-transform | --program-transfor \
+ | --program-transfo | --program-transf \
+ | --program-trans | --program-tran \
+ | --progr-tra | --program-tr | --program-t)
+ ac_prev=program_transform_name ;;
+ -program-transform-name=* | --program-transform-name=* \
+ | --program-transform-nam=* | --program-transform-na=* \
+ | --program-transform-n=* | --program-transform-=* \
+ | --program-transform=* | --program-transfor=* \
+ | --program-transfo=* | --program-transf=* \
+ | --program-trans=* | --program-tran=* \
+ | --progr-tra=* | --program-tr=* | --program-t=*)
+ program_transform_name="$ac_optarg" ;;
+
+ -q | -quiet | --quiet | --quie | --qui | --qu | --q \
+ | -silent | --silent | --silen | --sile | --sil)
+ silent=yes ;;
+
+ -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb)
+ ac_prev=sbindir ;;
+ -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \
+ | --sbi=* | --sb=*)
+ sbindir="$ac_optarg" ;;
+
+ -sharedstatedir | --sharedstatedir | --sharedstatedi \
+ | --sharedstated | --sharedstate | --sharedstat | --sharedsta \
+ | --sharedst | --shareds | --shared | --share | --shar \
+ | --sha | --sh)
+ ac_prev=sharedstatedir ;;
+ -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \
+ | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \
+ | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \
+ | --sha=* | --sh=*)
+ sharedstatedir="$ac_optarg" ;;
+
+ -site | --site | --sit)
+ ac_prev=site ;;
+ -site=* | --site=* | --sit=*)
+ site="$ac_optarg" ;;
+
+ -srcdir | --srcdir | --srcdi | --srcd | --src | --sr)
+ ac_prev=srcdir ;;
+ -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*)
+ srcdir="$ac_optarg" ;;
+
+ -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \
+ | --syscon | --sysco | --sysc | --sys | --sy)
+ ac_prev=sysconfdir ;;
+ -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \
+ | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*)
+ sysconfdir="$ac_optarg" ;;
+
+ -target | --target | --targe | --targ | --tar | --ta | --t)
+ ac_prev=target ;;
+ -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*)
+ target="$ac_optarg" ;;
+
+ -v | -verbose | --verbose | --verbos | --verbo | --verb)
+ verbose=yes ;;
+
+ -version | --version | --versio | --versi | --vers)
+ echo "configure generated by autoconf version 2.12.1"
+ exit 0 ;;
+
+ -with-* | --with-*)
+ ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'`
+ # Reject names that are not valid shell variable names.
+ if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then
+ { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; }
+ fi
+ ac_package=`echo $ac_package| sed 's/-/_/g'`
+ case "$ac_option" in
+ *=*) ;;
+ *) ac_optarg=yes ;;
+ esac
+ eval "with_${ac_package}='$ac_optarg'" ;;
+
+ -without-* | --without-*)
+ ac_package=`echo $ac_option|sed -e 's/-*without-//'`
+ # Reject names that are not valid shell variable names.
+ if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then
+ { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; }
+ fi
+ ac_package=`echo $ac_package| sed 's/-/_/g'`
+ eval "with_${ac_package}=no" ;;
+
+ --x)
+ # Obsolete; use --with-x.
+ with_x=yes ;;
+
+ -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \
+ | --x-incl | --x-inc | --x-in | --x-i)
+ ac_prev=x_includes ;;
+ -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \
+ | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*)
+ x_includes="$ac_optarg" ;;
+
+ -x-libraries | --x-libraries | --x-librarie | --x-librari \
+ | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l)
+ ac_prev=x_libraries ;;
+ -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \
+ | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*)
+ x_libraries="$ac_optarg" ;;
+
+ -*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; }
+ ;;
+
+ *)
+ if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then
+ echo "configure: warning: $ac_option: invalid host type" 1>&2
+ fi
+ if test "x$nonopt" != xNONE; then
+ { echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; }
+ fi
+ nonopt="$ac_option"
+ ;;
+
+ esac
+done
+
+if test -n "$ac_prev"; then
+ { echo "configure: error: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" 1>&2; exit 1; }
+fi
+
+trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15
+
+# File descriptor usage:
+# 0 standard input
+# 1 file creation
+# 2 errors and warnings
+# 3 some systems may open it to /dev/tty
+# 4 used on the Kubota Titan
+# 6 checking for... messages and results
+# 5 compiler messages saved in config.log
+if test "$silent" = yes; then
+ exec 6>/dev/null
+else
+ exec 6>&1
+fi
+exec 5>./config.log
+
+echo "\
+This file contains any messages produced by compilers while
+running configure, to aid debugging if configure makes a mistake.
+" 1>&5
+
+# Strip out --no-create and --no-recursion so they do not pile up.
+# Also quote any args containing shell metacharacters.
+ac_configure_args=
+for ac_arg
+do
+ case "$ac_arg" in
+ -no-create | --no-create | --no-creat | --no-crea | --no-cre \
+ | --no-cr | --no-c) ;;
+ -no-recursion | --no-recursion | --no-recursio | --no-recursi \
+ | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) ;;
+ *" "*|*" "*|*[\[\]\~\#\$\^\&\*\(\)\{\}\\\|\;\<\>\?]*)
+ ac_configure_args="$ac_configure_args '$ac_arg'" ;;
+ *) ac_configure_args="$ac_configure_args $ac_arg" ;;
+ esac
+done
+
+# NLS nuisances.
+# Only set these to C if already set. These must not be set unconditionally
+# because not all systems understand e.g. LANG=C (notably SCO).
+# Fixing LC_MESSAGES prevents Solaris sh from translating var values in `set'!
+# Non-C LC_CTYPE values break the ctype check.
+if test "${LANG+set}" = set; then LANG=C; export LANG; fi
+if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi
+if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi
+if test "${LC_CTYPE+set}" = set; then LC_CTYPE=C; export LC_CTYPE; fi
+
+# confdefs.h avoids OS command line length limits that DEFS can exceed.
+rm -rf conftest* confdefs.h
+# AIX cpp loses on an empty file, so make sure it contains at least a newline.
+echo > confdefs.h
+
+# A filename unique to this package, relative to the directory that
+# configure is in, which we can look for to find out if srcdir is correct.
+ac_unique_file=dejagnu.texi
+
+# Find the source files, if location was not specified.
+if test -z "$srcdir"; then
+ ac_srcdir_defaulted=yes
+ # Try the directory containing this script, then its parent.
+ ac_prog=$0
+ ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'`
+ test "x$ac_confdir" = "x$ac_prog" && ac_confdir=.
+ srcdir=$ac_confdir
+ if test ! -r $srcdir/$ac_unique_file; then
+ srcdir=..
+ fi
+else
+ ac_srcdir_defaulted=no
+fi
+if test ! -r $srcdir/$ac_unique_file; then
+ if test "$ac_srcdir_defaulted" = yes; then
+ { echo "configure: error: can not find sources in $ac_confdir or .." 1>&2; exit 1; }
+ else
+ { echo "configure: error: can not find sources in $srcdir" 1>&2; exit 1; }
+ fi
+fi
+srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'`
+
+# Prefer explicitly selected file to automatically selected ones.
+if test -z "$CONFIG_SITE"; then
+ if test "x$prefix" != xNONE; then
+ CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site"
+ else
+ CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site"
+ fi
+fi
+for ac_site_file in $CONFIG_SITE; do
+ if test -r "$ac_site_file"; then
+ echo "loading site script $ac_site_file"
+ . "$ac_site_file"
+ fi
+done
+
+if test -r "$cache_file"; then
+ echo "loading cache $cache_file"
+ . $cache_file
+else
+ echo "creating cache $cache_file"
+ > $cache_file
+fi
+
+ac_ext=c
+# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options.
+ac_cpp='$CPP $CPPFLAGS'
+ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5'
+ac_link='${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5'
+cross_compiling=$ac_cv_prog_cc_cross
+
+if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then
+ # Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu.
+ if (echo -n testing; echo 1,2,3) | sed s/-n/xn/ | grep xn >/dev/null; then
+ ac_n= ac_c='
+' ac_t=' '
+ else
+ ac_n=-n ac_c= ac_t=
+ fi
+else
+ ac_n= ac_c='\c' ac_t=
+fi
+
+
+ac_aux_dir=
+for ac_dir in $srcdir $srcdir/.. $srcdir/../..; do
+ if test -f $ac_dir/install-sh; then
+ ac_aux_dir=$ac_dir
+ ac_install_sh="$ac_aux_dir/install-sh -c"
+ break
+ elif test -f $ac_dir/install.sh; then
+ ac_aux_dir=$ac_dir
+ ac_install_sh="$ac_aux_dir/install.sh -c"
+ break
+ fi
+done
+if test -z "$ac_aux_dir"; then
+ { echo "configure: error: can not find install-sh or install.sh in $srcdir $srcdir/.. $srcdir/../.." 1>&2; exit 1; }
+fi
+ac_config_guess=$ac_aux_dir/config.guess
+ac_config_sub=$ac_aux_dir/config.sub
+ac_configure=$ac_aux_dir/configure # This should be Cygnus configure.
+
+# Find a good install program. We prefer a C program (faster),
+# so one script is as good as another. But avoid the broken or
+# incompatible versions:
+# SysV /etc/install, /usr/sbin/install
+# SunOS /usr/etc/install
+# IRIX /sbin/install
+# AIX /bin/install
+# AIX 4 /usr/bin/installbsd, which doesn't work without a -g flag
+# AFS /usr/afsws/bin/install, which mishandles nonexistent args
+# SVR4 /usr/ucb/install, which tries to use the nonexistent group "staff"
+# ./install, which can be erroneously created by make from ./install.sh.
+echo $ac_n "checking for a BSD compatible install""... $ac_c" 1>&6
+echo "configure:554: checking for a BSD compatible install" >&5
+if test -z "$INSTALL"; then
+if eval "test \"`echo '$''{'ac_cv_path_install'+set}'`\" = set"; then
+ echo $ac_n "(cached) $ac_c" 1>&6
+else
+ IFS="${IFS= }"; ac_save_IFS="$IFS"; IFS="${IFS}:"
+ for ac_dir in $PATH; do
+ # Account for people who put trailing slashes in PATH elements.
+ case "$ac_dir/" in
+ /|./|.//|/etc/*|/usr/sbin/*|/usr/etc/*|/sbin/*|/usr/afsws/bin/*|/usr/ucb/*) ;;
+ *)
+ # OSF1 and SCO ODT 3.0 have their own names for install.
+ # Don't use installbsd from OSF since it installs stuff as root
+ # by default.
+ for ac_prog in ginstall scoinst install; do
+ if test -f $ac_dir/$ac_prog; then
+ if test $ac_prog = install &&
+ grep dspmsg $ac_dir/$ac_prog >/dev/null 2>&1; then
+ # AIX install. It has an incompatible calling convention.
+ :
+ else
+ ac_cv_path_install="$ac_dir/$ac_prog -c"
+ break 2
+ fi
+ fi
+ done
+ ;;
+ esac
+ done
+ IFS="$ac_save_IFS"
+
+fi
+ if test "${ac_cv_path_install+set}" = set; then
+ INSTALL="$ac_cv_path_install"
+ else
+ # As a last resort, use the slow shell script. We don't cache a
+ # path for INSTALL within a source directory, because that will
+ # break other packages using the cache if that directory is
+ # removed, or if the path is relative.
+ INSTALL="$ac_install_sh"
+ fi
+fi
+echo "$ac_t""$INSTALL" 1>&6
+
+# Use test -z because SunOS4 sh mishandles braces in ${var-val}.
+# It thinks the first close brace ends the variable substitution.
+test -z "$INSTALL_PROGRAM" && INSTALL_PROGRAM='${INSTALL}'
+
+test -z "$INSTALL_DATA" && INSTALL_DATA='${INSTALL} -m 644'
+
+trap '' 1 2 15
+cat > confcache <<\EOF
+# This file is a shell script that caches the results of configure
+# tests run on this system so they can be shared between configure
+# scripts and configure runs. It is not useful on other systems.
+# If it contains results you don't want to keep, you may remove or edit it.
+#
+# By default, configure uses ./config.cache as the cache file,
+# creating it if it does not exist already. You can give configure
+# the --cache-file=FILE option to use a different cache file; that is
+# what configure does when it calls configure scripts in
+# subdirectories, so they share the cache.
+# Giving --cache-file=/dev/null disables caching, for debugging configure.
+# config.status only pays attention to the cache file if you give it the
+# --recheck option to rerun configure.
+#
+EOF
+# The following way of writing the cache mishandles newlines in values,
+# but we know of no workaround that is simple, portable, and efficient.
+# So, don't put newlines in cache variables' values.
+# Ultrix sh set writes to stderr and can't be redirected directly,
+# and sets the high bit in the cache file unless we assign to the vars.
+(set) 2>&1 |
+ case `(ac_space=' '; set) 2>&1 | grep ac_space` in
+ *ac_space=\ *)
+ # `set' does not quote correctly, so add quotes (double-quote substitution
+ # turns \\\\ into \\, and sed turns \\ into \).
+ sed -n \
+ -e "s/'/'\\\\''/g" \
+ -e "s/^\\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\\)=\\(.*\\)/\\1=\${\\1='\\2'}/p"
+ ;;
+ *)
+ # `set' quotes correctly as required by POSIX, so do not add quotes.
+ sed -n -e 's/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=${\1=\2}/p'
+ ;;
+ esac >> confcache
+if cmp -s $cache_file confcache; then
+ :
+else
+ if test -w $cache_file; then
+ echo "updating cache $cache_file"
+ cat confcache > $cache_file
+ else
+ echo "not updating unwritable cache $cache_file"
+ fi
+fi
+rm -f confcache
+
+trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15
+
+test "x$prefix" = xNONE && prefix=$ac_default_prefix
+# Let make expand exec_prefix.
+test "x$exec_prefix" = xNONE && exec_prefix='${prefix}'
+
+# Any assignment to VPATH causes Sun make to only execute
+# the first set of double-colon rules, so remove it if not needed.
+# If there is a colon in the path, we need to keep it.
+if test "x$srcdir" = x.; then
+ ac_vpsub='/^[ ]*VPATH[ ]*=[^:]*$/d'
+fi
+
+trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15
+
+# Transform confdefs.h into DEFS.
+# Protect against shell expansion while executing Makefile rules.
+# Protect against Makefile macro expansion.
+cat > conftest.defs <<\EOF
+s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g
+s%[ `~#$^&*(){}\\|;'"<>?]%\\&%g
+s%\[%\\&%g
+s%\]%\\&%g
+s%\$%$$%g
+EOF
+DEFS=`sed -f conftest.defs confdefs.h | tr '\012' ' '`
+rm -f conftest.defs
+
+
+# Without the "./", some shells look in PATH for config.status.
+: ${CONFIG_STATUS=./config.status}
+
+echo creating $CONFIG_STATUS
+rm -f $CONFIG_STATUS
+cat > $CONFIG_STATUS <<EOF
+#! /bin/sh
+# Generated automatically by configure.
+# Run this file to recreate the current configuration.
+# This directory was configured as follows,
+# on host `(hostname || uname -n) 2>/dev/null | sed 1q`:
+#
+# $0 $ac_configure_args
+#
+# Compiler output produced by configure, useful for debugging
+# configure, is in ./config.log if it exists.
+
+ac_cs_usage="Usage: $CONFIG_STATUS [--recheck] [--version] [--help]"
+for ac_option
+do
+ case "\$ac_option" in
+ -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r)
+ echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion"
+ exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;;
+ -version | --version | --versio | --versi | --vers | --ver | --ve | --v)
+ echo "$CONFIG_STATUS generated by autoconf version 2.12.1"
+ exit 0 ;;
+ -help | --help | --hel | --he | --h)
+ echo "\$ac_cs_usage"; exit 0 ;;
+ *) echo "\$ac_cs_usage"; exit 1 ;;
+ esac
+done
+
+ac_given_srcdir=$srcdir
+ac_given_INSTALL="$INSTALL"
+
+trap 'rm -fr `echo "Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15
+EOF
+cat >> $CONFIG_STATUS <<EOF
+
+# Protect against being on the right side of a sed subst in config.status.
+sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g;
+ s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF
+$ac_vpsub
+$extrasub
+s%@SHELL@%$SHELL%g
+s%@CFLAGS@%$CFLAGS%g
+s%@CPPFLAGS@%$CPPFLAGS%g
+s%@CXXFLAGS@%$CXXFLAGS%g
+s%@DEFS@%$DEFS%g
+s%@LDFLAGS@%$LDFLAGS%g
+s%@LIBS@%$LIBS%g
+s%@exec_prefix@%$exec_prefix%g
+s%@prefix@%$prefix%g
+s%@program_transform_name@%$program_transform_name%g
+s%@bindir@%$bindir%g
+s%@sbindir@%$sbindir%g
+s%@libexecdir@%$libexecdir%g
+s%@datadir@%$datadir%g
+s%@sysconfdir@%$sysconfdir%g
+s%@sharedstatedir@%$sharedstatedir%g
+s%@localstatedir@%$localstatedir%g
+s%@libdir@%$libdir%g
+s%@includedir@%$includedir%g
+s%@oldincludedir@%$oldincludedir%g
+s%@infodir@%$infodir%g
+s%@mandir@%$mandir%g
+s%@INSTALL_PROGRAM@%$INSTALL_PROGRAM%g
+s%@INSTALL_DATA@%$INSTALL_DATA%g
+
+CEOF
+EOF
+
+cat >> $CONFIG_STATUS <<\EOF
+
+# Split the substitutions into bite-sized pieces for seds with
+# small command number limits, like on Digital OSF/1 and HP-UX.
+ac_max_sed_cmds=90 # Maximum number of lines to put in a sed script.
+ac_file=1 # Number of current file.
+ac_beg=1 # First line for current file.
+ac_end=$ac_max_sed_cmds # Line after last line for current file.
+ac_more_lines=:
+ac_sed_cmds=""
+while $ac_more_lines; do
+ if test $ac_beg -gt 1; then
+ sed "1,${ac_beg}d; ${ac_end}q" conftest.subs > conftest.s$ac_file
+ else
+ sed "${ac_end}q" conftest.subs > conftest.s$ac_file
+ fi
+ if test ! -s conftest.s$ac_file; then
+ ac_more_lines=false
+ rm -f conftest.s$ac_file
+ else
+ if test -z "$ac_sed_cmds"; then
+ ac_sed_cmds="sed -f conftest.s$ac_file"
+ else
+ ac_sed_cmds="$ac_sed_cmds | sed -f conftest.s$ac_file"
+ fi
+ ac_file=`expr $ac_file + 1`
+ ac_beg=$ac_end
+ ac_end=`expr $ac_end + $ac_max_sed_cmds`
+ fi
+done
+if test -z "$ac_sed_cmds"; then
+ ac_sed_cmds=cat
+fi
+EOF
+
+cat >> $CONFIG_STATUS <<EOF
+
+CONFIG_FILES=\${CONFIG_FILES-"Makefile"}
+EOF
+cat >> $CONFIG_STATUS <<\EOF
+for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then
+ # Support "outfile[:infile[:infile...]]", defaulting infile="outfile.in".
+ case "$ac_file" in
+ *:*) ac_file_in=`echo "$ac_file"|sed 's%[^:]*:%%'`
+ ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;;
+ *) ac_file_in="${ac_file}.in" ;;
+ esac
+
+ # Adjust a relative srcdir, top_srcdir, and INSTALL for subdirectories.
+
+ # Remove last slash and all that follows it. Not all systems have dirname.
+ ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'`
+ if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then
+ # The file is in a subdirectory.
+ test ! -d "$ac_dir" && mkdir "$ac_dir"
+ ac_dir_suffix="/`echo $ac_dir|sed 's%^\./%%'`"
+ # A "../" for each directory in $ac_dir_suffix.
+ ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'`
+ else
+ ac_dir_suffix= ac_dots=
+ fi
+
+ case "$ac_given_srcdir" in
+ .) srcdir=.
+ if test -z "$ac_dots"; then top_srcdir=.
+ else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;;
+ /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;;
+ *) # Relative path.
+ srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix"
+ top_srcdir="$ac_dots$ac_given_srcdir" ;;
+ esac
+
+ case "$ac_given_INSTALL" in
+ [/$]*) INSTALL="$ac_given_INSTALL" ;;
+ *) INSTALL="$ac_dots$ac_given_INSTALL" ;;
+ esac
+
+ echo creating "$ac_file"
+ rm -f "$ac_file"
+ configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure."
+ case "$ac_file" in
+ *Makefile*) ac_comsub="1i\\
+# $configure_input" ;;
+ *) ac_comsub= ;;
+ esac
+
+ ac_file_inputs=`echo $ac_file_in|sed -e "s%^%$ac_given_srcdir/%" -e "s%:% $ac_given_srcdir/%g"`
+ sed -e "$ac_comsub
+s%@configure_input@%$configure_input%g
+s%@srcdir@%$srcdir%g
+s%@top_srcdir@%$top_srcdir%g
+s%@INSTALL@%$INSTALL%g
+" $ac_file_inputs | (eval "$ac_sed_cmds") > $ac_file
+fi; done
+rm -f conftest.s*
+
+EOF
+cat >> $CONFIG_STATUS <<EOF
+
+EOF
+cat >> $CONFIG_STATUS <<\EOF
+
+exit 0
+EOF
+chmod +x $CONFIG_STATUS
+rm -fr confdefs* $ac_clean_files
+test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1
+
diff --git a/doc/configure.in b/doc/configure.in
new file mode 100644
index 0000000..2575d44
--- /dev/null
+++ b/doc/configure.in
@@ -0,0 +1,5 @@
+dnl Process this file with autoconf to produce a configure script.
+AC_PREREQ(2.5)
+AC_INIT(dejagnu.texi)
+AC_PROG_INSTALL
+AC_OUTPUT(Makefile)
diff --git a/doc/dejagnu.texi b/doc/dejagnu.texi
new file mode 100644
index 0000000..68c4008
--- /dev/null
+++ b/doc/dejagnu.texi
@@ -0,0 +1,3572 @@
+o\input texinfo @c -*- Texinfo -*-
+@finalout
+@setfilename dejagnu.info
+@c
+@c This file documents the GNU Testing Framework ``DejaGnu''
+@c
+@c Copyright (C) 92, 93, 94, 95, 1996 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, 1996 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.
+
+@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.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end titlepage
+
+@ifinfo
+Copyright @copyright{} 92, 93, 94, 95, 1996 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.
+
+@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
+
+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.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+
+@node Top
+@top DejaGnu
+
+DejaGnu is a framework for running test suites on software tools.
+
+This file describes version 1.3 of DejaGnu.
+
+@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
+
+@iftex
+@raggedbottom
+@end iftex
+
+@node Overview
+@chapter What is DejaGnu?
+@cindex overview
+
+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:
+
+@enumerate
+@item
+The flexibility and consistency of the DejaGnu framework make it easy
+to write tests for any program.
+
+@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.
+
+@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
+
+DejaGnu is written in @code{expect}, which in turn uses @dfn{Tcl}---Tool
+command language.
+
+@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}.)
+
+
+@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
+@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:
+
+@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.
+
+@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}.
+
+@item
+Lots of little bug fixes from a year of heavy use here at Cygnus
+Support.
+
+@item
+DejaGnu now uses @code{autoconf} for configuration.
+
+@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.
+
+@item
+The @code{--tool} option is now optional.
+
+@item
+@code{runtest} when searching for test drivers ignores all directories
+named SCCS, RCS, and CVS.
+
+@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.
+
+@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:
+
+@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.
+
+@item
+Comments start with @samp{#}.
+
+@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).
+
+@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.
+
+@item
+Test cases use the commands @code{pass} and @code{fail} to record the
+test outcome.
+@end itemize
+
+@node Design Goals
+@section Design goals
+@cindex design goals
+
+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
+@item
+is useful to developers while fixing bugs;
+
+@item
+automates running many tests during a software release process;
+
+@item
+is portable among a variety of host computers;
+
+@item
+supports cross-development testing;
+
+@item
+permits testing interactive programs, like @sc{gdb}; and
+
+@item
+permits testing batch oriented programs, like @sc{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 ``Deja Gnu'' 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
+@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
+case:
+
+@ftable @code
+@cindex success, POSIX definition
+@item PASS
+A test has succeeded. That is, it demonstrated that the assertion is true.
+
+@cindex XFAIL, avoiding for POSIX
+@item XFAIL
+@sc{posix} 1003.3 does not incorporate the notion of expected failures,
+so @code{PASS}, instead of @code{XPASS}, must also be returned for test
+cases which were expected to fail and did not. This means that
+@code{PASS} is in some sense more ambiguous than if @code{XPASS} is also
+used. For information on @code{XPASS} and @code{XFAIL}, see
+@ref{Invoking runtest,,Using @code{runtest}}.
+
+@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.
+
+As with @code{PASS}, @sc{posix} tests must return @code{FAIL} rather
+than @code{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.
+
+Here are some of the ways a test may wind up @code{UNRESOLVED}:
+
+@itemize @bullet
+@item
+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
+usually requires a human being to examine the output to
+determine what really happened---and to improve the test case.
+
+@item
+A test depends on a previous test, which fails.
+
+@item
+The test was set up incorrectly.
+@end itemize
+
+@item UNTESTED
+A test was not run. This is a placeholder, used when there is no
+real test case yet.
+@end ftable
+
+@noindent
+The only remaining output message left is intended to test features that
+are specified by the applicable @sc{posix} standard as conditional:
+
+@ftable @code
+@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} procedure as described in
+the @code{PASS} section above, and you must be careful to return
+@code{UNRESOLVED} where appropriate, as described in the
+@code{UNRESOLVED} section above.
+
+@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.
+
+@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 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.
+
+@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 bug. If a test fails because the operating system
+where the test runs lacks some facility required by the test, the
+outcome is @code{UNSUPPORTED} instead.
+
+@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.
+
+@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.
+
+@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
+
+@code{runtest} may also display the following messages:
+
+@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.)
+
+@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.
+
+@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} (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}.
+
+@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.
+
+@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}.
+
+@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}, and @code{setup_xfail} 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.
+
+@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
+
+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
+* 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.
+@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. ie 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 Internals
+@chapter The DejaGnu Implementation
+@cindex operating principles
+@cindex internal details
+
+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.
+
+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.
+
+@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.
+
+@item
+Providing an extended test environment, by defining additional Tcl
+procedures beyond those already in @code{expect}.
+
+@item
+Locating target-dependent functions, to standardize the test environment
+across a wide variety of test platforms.
+@end enumerate
+
+@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
+@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.
+
+@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
+@}
+@}
+
+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.
+
+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.
+
+@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
+
+@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}, 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).
+
+@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}).
+
+@cindex @code{XFAIL}, producing
+@cindex @code{XPASS}, producing
+Once you use @code{setup_xfail}, the @code{fail} and @code{pass}
+procedures produce the messages @samp{XFAIL} and @samp{XPASS}
+respectively, allowing you to distinguish expected failures (and
+unexpected success!) from other test outcomes.
+
+@emph{Warning:} you must clear the expected failure after using
+@code{setup_xfail} in a test case. Any call to @code{pass} or
+@code{fail} 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.
+
+@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 condition 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 any set of the options matches, then this
+conditional is true.
+
+@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 verbose @r{[}-log@r{]} @r{[}-n@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 "-".
+
+@end ftable
+
+@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}.
+
+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.
+
+@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
+
+@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
+
+@noindent
+@node utils.exp, target.exp, remote.exp, DejaGnu Builtins
+@subsection Utility Procedures
+
+@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 the pathname of
+the testsuite expect script running. The second 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.
+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
+
+@noindent
+@node target.exp, debugger.exp, utils.exp, DejaGnu Builtins
+@subsection Cross target procedure
+
+@kindex target.exp
+@kindex lib/target.exp
+@file{lib/target.exp} defines these utility procedures:
+
+@ftable @code
+
+@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.
+
+@item pop_target
+@cindex unset current target
+This unsets the current target connection.
+
+@item list_targets
+@cindex lists supported targets
+This lists all the supported targets for this architecture.
+
+@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.
+
+@item pop_host
+@cindex unset current host
+This unsets the current host connection.
+
+@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.
+
+@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
+
+@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
+
+@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.
+
+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.
+
+@menu
+* Summary:: Files that summarize tests
+* Detail:: Files that contain complete test results
+* Debug:: Logging expect internal actions
+@end menu
+
+@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} or @samp{XPASS}) or @code{fail}
+command (status @samp{FAIL} or @samp{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
+@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.
+
+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.
+
+@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:
+
+@cartouche
+@smallexample
+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/ps/bin/g++ version cygnus-2.0.1
+@end smallexample
+@end cartouche
+
+@node Debug
+@subsection Logging @code{expect} internal actions
+@cindex debug log
+
+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.
+
+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.
+
+The log messages for @code{expect} begin with a message of the form
+
+@smallexample
+expect: does @{@var{tool output}@} (spawn_id @var{n}) match pattern
+@{@var{expected pattern}@}?
+@end smallexample
+
+@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
+
+@noindent
+This example exhibits three properties of @code{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 @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).
+
+@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.
+
+@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).
+
+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.
+
+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
+
+@node Tests
+@chapter How To Write a Test Cases
+@cindex writing a test case
+@cindex test case, writing
+
+@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
+@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.
+
+@noindent
+Writing the complete suite of C tests, then, consisted of these steps:
+
+@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.
+
+@item
+Writing (and debugging) the generic @code{expect} procedures for
+compilation.
+
+@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
+
+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 @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.
+
+@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...
+
+@node Debugging
+@section Debugging a test case
+@cindex debugging a test case
+@cindex test case, debugging
+
+@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}.
+
+@node Variables
+@section Special variables used by test cases
+@cindex special variables
+
+@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}):
+
+@quotation
+@emph{These variables are available to all test cases.}
+@end quotation
+
+@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.)
+
+@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.)
+
+@item subdir
+@cindex current test subdirectory
+The subdirectory for the current test case.
+@end ftable
+
+@quotation
+@emph{These variables should never be changed. They appear in most
+tests.}
+@end quotation
+
+@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}.
+
+@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.
+
+@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
+
+@node Extending
+@chapter New Tools, Targets, or Hosts
+
+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.
+
+@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
+
+@node Adding Tools
+@section Writing tests for 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
+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.
+
+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.
+
+@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!)
+
+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}.
+
+@enumerate
+@item
+Create or select a directory to contain your new collection of tests.
+Change to that directory (shown here as @code{testsuite}):
+
+@example
+eg$ cd 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.)
+
+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:
+
+@cartouche
+@smallexample
+# This file is a shell script fragment
+# for use with Cygnus configure.
+
+srctrigger="@var{example}.0"
+srcname="The DejaGnu @var{example} tests"
+
+# per-host:
+
+# per-target:
+
+# everything defaults to unix for a target
+target_abbrev=unix
+
+# post-target:
+
+@end smallexample
+@end cartouche
+
+@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:
+
+@cartouche
+@smallexample
+srcdir = .
+prefix = /usr/local
+
+exec_prefix = $(prefix)
+bindir = $(exec_prefix)/bin
+libdir = $(exec_prefix)/lib
+tooldir = $(libdir)/$(target_alias)
+
+datadir = $(exec_prefix)/lib/dejagnu
+
+RUNTEST = runtest
+RUNTESTFLAGS =
+FLAGS_TO_PASS =
+
+#### host, target, site specific Makefile frags come in here.
+@end smallexample
+@end cartouche
+
+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:
+
+@cartouche
+@smallexample
+
+all:
+
+info:
+
+install-info:
+
+install:
+uninstall:
+
+clean:
+ -rm -f *~ core *.info*
+
+@end smallexample
+@end cartouche
+
+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):
+
+@cartouche
+@smallexample
+Makefile : $(srcdir)/Makefile.in $(host_makefile_frag) \
+ $(target_makefile_frag)
+ $(SHELL) ./config.status
+@end smallexample
+@end cartouche
+
+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}}:
+
+@cartouche
+@smallexample
+check: site.exp all
+ $(RUNTEST) $(RUNTESTFLAGS) $(FLAGS_TO_PASS) \
+ --tool @var{example} --srcdir $(srcdir)
+@end smallexample
+@end cartouche
+
+The @code{site.exp} target should usually set up (among other things!) a
+Tcl variable for the name of your program:
+
+@cartouche
+@smallexample
+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 @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
+
+@item
+Create a directory (in @file{testsuite/}) called @file{config/}:
+
+@example
+eg$ mkdir config
+@end example
+
+@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.
+
+If @var{example} is not interactive, you can get away with this minimal
+@file{unix.exp} to begin with:
+
+@cartouche
+@smallexample
+proc foo_exit @{@} @{@}
+proc foo_version @{@} @{@}
+@end smallexample
+@end cartouche
+
+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:
+
+@cartouche
+@smallexample
+proc foo_exit @{@} @{@}
+proc foo_version @{@} @{@}
+
+proc foo_start @{@} @{
+ global @var{examplename}
+ spawn $@var{examplename}
+ expect @{
+ -re "" @{@}
+ @}
+@}
+foo_start
+@end smallexample
+@end cartouche
+
+@item
+Create a directory whose name begins with your tool's name, to contain
+tests:
+
+@example
+eg$ mkdir @var{example}.0
+@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:
+
+@cartouche
+@smallexample
+send_user "Testing: one, two...\n"
+@end smallexample
+@end cartouche
+
+@item
+Back in the @file{testsuite/} (top level) directory, run
+
+@example
+eg$ configure
+@end example
+
+(You may have to specify more of a path, if a suitable @code{configure}
+is not available in your execution path.)
+
+@item
+You are now ready to triumphantly type @samp{make check} or
+@samp{runtest --tool @var{example}}. You should see something like this:
+
+@cartouche
+@smallexample
+Test Run By rhl on Fri Jan 29 16:25:44 EST 1993
+
+ === @var{example} tests ===
+
+Running ./@var{example}.0/first-try.exp ...
+Testing: one, two...
+
+ === @var{example} Summary ===
+
+@end smallexample
+@end cartouche
+
+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
+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
+
+@node Adding Targets
+@section Adding a target
+@cindex adding a target
+
+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.
+
+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 (@pxref{DejaGnu
+Builtins, DejaGnu procedures}).
+
+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}.
+
+@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.
+
+@menu
+* Configuring DejaGnu::
+* Installing DejaGnu::
+@end menu
+
+@node Configuring DejaGnu
+@section Configuring the DejaGnu test driver
+
+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.
+
+@node Installing DejaGnu
+@section Installing DejaGnu
+
+@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
+eg$ make install
+@end example
+
+@noindent
+@samp{make install} does these things for DejaGnu:
+
+@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.
+
+@item
+Create another directory in the @file{lib} directory, called
+@file{dejagnu}.
+
+@item
+Copy the @code{runtest} shell script into @file{$exec_prefix/bin}.
+
+@item
+Copy all the library files (used to support the framework) into
+@file{$exec_prefix/lib/dejagnu}.
+
+@item
+Copy @file{runtest.exp} into @file{$exec_prefix/lib/dejagnu}. This is
+the main Tcl code implementing DejaGnu.
+
+@end enumerate
+
+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}.
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@contents
+
+@bye
diff --git a/doc/overview.sgml b/doc/overview.sgml
new file mode 100644
index 0000000..58bce0c
--- /dev/null
+++ b/doc/overview.sgml
@@ -0,0 +1,439 @@
+<!DOCTYPE book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+
+<!-- Begin Document Specific Declarations -->
+
+<?Fm: Validation Off>
+
+<!ENTITY version "0.5">
+<!ENTITY dj "DejaGnu">
+
+<!ENTITY dejagnu-copyright "
+ <YEAR>1998</YEAR>
+ <HOLDER>Free Software Foundation, Inc.</HOLDER>">
+
+<!ENTITY dejagnu-code-copyright "
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+This file documents the GNU Testing Framework ``DejaGnu''
+
+Copyright (C) 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc.
+
+This text may be freely distributed under the terms of the GNU
+General Public License.
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+">
+
+<!ENTITY dejagnu-copyright "
+Copyright 92, 93, 94, 95, 96, 97, 98, 1999 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.
+
+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.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+">
+
+<!-- The reference material -->
+<!entity ref SYSTEM "ref.sgml">
+
+<!-- The user manual -->
+<!entity user SYSTEM "user.sgml">
+
+<!-- End Document Specific Declarations -->
+]>
+
+<book>
+ <bookinfo>
+ <title>&dj;</title>
+ <subtitle>The GNU Testing Framework</subtitle>
+ <date>1998 Nov 24</date>
+ <edition> &version</edition>
+ <releaseinfo> for circulation within Cygnus</releaseinfo>
+ <authorgroup>
+ <author>
+ <firstname>Rob Savoye</firstname>
+ <affiliation>
+ <orgname>Free Software Foundation</orgname></affiliation>
+ <!-- <authorblurb>
+ <title>Rob Savoye</title>
+ <para>
+ His home page is at <ulink>
+ URL="http://www.welcomehome.org/rob.html">this
+ location</ulink>
+ </para>
+ </authorblurb>
+ -->
+ </author>
+ </authorgroup>
+ <address>
+ <email>rob@welcomehome.org</email>
+ </address>
+ <!-- &cygnus-street-address; -->
+ <copyright>&dejagnu-copyright;</copyright>
+ <!-- <legalnotice>
+ <para> -->
+ <!-- [FIXME: must put legal notice here] -->
+ <!-- </para> -->
+ <!-- &cygnus-legal-notice; -->
+ <!-- </legalnotice> -->
+ <revhistory>
+ <revision>
+ <revnumber> 0.1</revnumber>
+ <date>1998-11</date>
+ <authorinitials>rob@welcomehome.org</authorinitials>
+ <revremark>Initial version after conversion to DocBook.</revremark>
+ </revision>
+ </revhistory>
+
+ </bookinfo>
+
+ <toc></toc>
+
+ <preface id=preface>
+ <title>Abstract</title>
+
+ <para>This document attempts to describe the functionality of
+ DejaGnu, the GNU Testing Framework. DejaGnu is entirely written in
+ <productname>Expect</productname>, which uses
+ <productname>Tcl</productname> as a command
+ language. <productname>Expect</productname> 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
+ test script has fully programmable control of
+ its input and output. This does not just apply to the programs
+ under test; <command>expect</command> can also run any auxiliary
+ program, such as <command>diff</command> or <command>sh</command>,
+ with full control over its input and output.</para>
+
+ <para>DejaGnu itself is merely a framework for creation of a test
+ suites. Test suites are distributed separately for each GNU
+ tool.</para>
+
+ </preface>
+
+ <chapter id=overview xreflabel=Overview>
+ <title>Overview</title>
+
+ <sect1 id=whatis xreflabel="What is &dj; ?">
+ <title>What is &dj; ?</title>
+
+ <para><productname>DejaGnu</productname> 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
+ <emphasis>Test Harness</emphasis> is the testing
+ infrastructure that is created to support a specific program
+ or tool. Each program can have multiple test suites, all
+ supported by a single test harness. DejaGnu is written in
+ <productname>Expect</productname>, which in turn uses
+ <productname>Tcl</productname> -- Tool command
+ language. There is more information on Tcl at the <ulink
+ URL="http://www.scriptics.com">Scriptics</ulink> web site, and the
+ Expect web site is at <ulink
+ URL="http://expect.nist.gov">NIST</ulink>.</para>
+
+ <para>DejaGnu offers several advantages for testing:</para>
+
+ <itemizedlist mark="bullet" spacing="compact">
+
+ <listitem><para>The flexibility and consistency of the DejaGnu
+ framework make it easy to write tests for any program, with
+ either batch oriented, or interactive programs.</para>
+ </listitem>
+
+ <listitem><para>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 <command>GDB</command> can run (from any Unix
+ based host) on any target architecture that DejaGnu
+ supports. Currently DejaGnu runs tests on many single board
+ computers, whose operating software ranges from just a boot
+ monitor to a full-fledged, Unix-like realtime OS.</para>
+ </listitem>
+
+ <listitem><para>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.</para>
+ </listitem>
+
+ <listitem><para>Using Tcl and expect, it's easy to create wrappers
+ for existing test suites. By incorporating existing tests under
+ DejaGnu, it's easier to have a single set of report analyse
+ programs..</para>
+
+ </listitem>
+ </itemizedlist>
+
+ <para>Running tests requires two things: the testing framework, and
+ the test suites themselves. Tests are usually written in
+ <productname>Expect</productname> using Tcl, but you can also use a
+ Tcl script to run a test suite that is not based on
+ <productname>Expect</productname>.
+ (<productname>expect</productname> script filenames conventionally
+ use <emphasis>.exp</emphasis> as a suffix; for example, the main
+ implementation of the DejaGnu test driver is in the file
+ <productname>runtest.exp</productname>.)</para>
+
+ <para>Julia Menapace first coined the term ``Deja Gnu'' to describe an
+ earlier testing framework at Cygnus Support she had written for
+ <command>GDB</command>. When we replaced it with the Expect-based
+ framework, it was like DejaGnu all over again... But more importantly, it
+ was also named after my daughter,<ulink
+ URL="mailto:deja@welcomehome.org">Deja Snow Savoye</ulink> (now 9
+ years old in Dec of 1998), who was a toddler during DejaGnu's
+ creation.</para>
+
+ </sect1>
+
+ <sect1 id=new xreflabel="Release Notes">
+ <title>What's New In This Release</title>
+
+ <para>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
+ <productname>iTcl</productname> by the next release. Other changes
+ are:</para>
+
+ <itemizedlist>
+ <listitem><para>More builtin support for building target binaries
+ with the correct linker flags. Currently this only works with
+ <productname>GCC</productname> as the cross compiler,
+ preferably with a target supported by
+ <xref linkend=libgloss>.</para></listitem>
+
+ <listitem><para>Lots of little bug fixes from years of heavy
+ use at Cygnus Solutions.</para></listitem>
+
+ <listitem><para>DejaGnu now uses
+ <productname>Automake</productname> for Makefile
+ configuration.</para></listitem>
+
+ <listitem><para>Updated documentation, now in SGML
+ (using the <ulink
+ URL="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html">free
+ GNU DocBook tools</ulink>) format.</para></listitem>
+
+ <listitem><para>NT support. There is beta level support for NT
+ that is still a work in progress. This requires the <ulink
+ URL=httpd://sourceware.cygnus.com>Cygwin</ulink> POSIX system
+ for NT.</para></listitem>
+
+ </itemizedlist>
+
+ <sect2 id=cygwin xreflabel="NT Support">
+ <title>NT Support</title>
+
+ <para>To use DejaGnu on NT, you need to first install the
+ <ulink URL="http://sourceware.cygnus.com">Cygwin</ulink>
+ release. This works as of the B20.1 release. Cygwin is a POSIX
+ system for NT. This covers both utility programs, and a libray
+ that adds POSIX system calls to NT. Among them is pseudo tty
+ support for NT that emulates the POSIX pty standard. The
+ latest Cygwin is always available from <ulink
+ URL="http://sourceware.cygnus.com">this location</ulink>. This
+ works well enough to run <emphasis>"make check"</emphasis> of
+ the GNU development tree on NT after a native build. But the
+ nature of pty's on NT is still evolving. Your mileage may
+ vary...</para>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id=designgoals xreflabel="Design Goals">
+ <title>Design Goals</title>
+
+ <para>DejaGnu grew out of the internal needs of Cygnus Solutions. (then
+ Cygnus Support). Cygnus maintains and enhances a variety of free programs
+ in many different environments, and we needed a testing tool that:</para>
+
+ <itemizedlist mark="bullet">
+ <listitem><para>is useful to developers while fixing bugs.</para>
+ <listitem><para>automates running many tests during a software
+ release process.</para>
+ <listitem><para>is portable among a variety of host
+ computers.</para>
+ <listitem><para>supports cross-development testing.</para>
+ <listitem><para>permits testing interactive programs, like
+ <command>GDB</command>; and </para>
+ <listitem><para>permits testing batch oriented programs, like
+ <command>GCC</command>.</para>
+ </itemizedlist>
+
+ <para>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 <command>GDB</command> works as well when cross-debugging
+ as it does in a native configuration. </para>
+
+ <para>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
+ <command>rsh</command>, <command>rlogin</command>,
+ <command>telnet</command>, <command>tip</command>,
+ <command>kermit</command>, and <command>mondfe</command> for remote
+ communications.</para>
+
+ </sect1>
+
+ <sect1 id=posix xreflabel="A POSIX Conforming Test Framework">
+ <title>A POSIX conforming test framework</title>
+
+ <para>DejaGnu conforms to the POSIX 1003.3 standard for test
+ frameworks. I was also a member of that committe.</para>
+
+ <para>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.</para>
+
+ <para>The POSIX documentation refers to <firstterm>assertions</firstterm>.
+ 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.</para>
+
+ <para>As there is no test suite 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 test suite
+ that uses exactly these messages can be considered POSIX conforming.
+ These definitions specify the output of a test case:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>PASS</term>
+ <listitem><para>A test has succeeded. That is, it demonstrated that
+ the assertion is true.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>XFAIL</term>
+ <listitem><para>POSIX 1003.3 does not incorporate the notion of
+ expected failures, so <emphasis>PASS</emphasis>, instead of
+ <emphasis>XPASS</emphasis>, must also be returned for test cases
+ which were expected to fail and did not. This means that
+ <emphasis>PASS</emphasis> is in some sense more ambiguous than if
+ <emphasis>XPASS</emphasis> is also used.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>FAIL</term>
+ <listitem><para>A test has produced the bug it was intended to
+ capture. That is, it has demonstrated that the assertion is false.
+ The <emphasis>FAIL</emphasis> message is based on the test case only.
+ Other messages are used to indicate a failure of the framework. As
+ with <emphasis>PASS</emphasis>, POSIX tests must return
+ <emphasis>FAIL</emphasis> rather than <emphasis>XFAIL</emphasis> even
+ if a failure was expected.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>UNRESOLVED</term>
+ <listitem><para>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
+ <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> before a test
+ run can be considered finished.</para>
+
+ <para>Note that for POSIX, each assertion must produce a test result
+ code. If the test isn't actually run, it must produce
+ <emphasis>UNRESOLVED</emphasis> 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
+ <emphasis>return</emphasis>---if you alter the flow of control of the
+ tcl code you must insure that every test still produces some result
+ code.</para>
+
+ <para>Here are some of the ways a test may wind up
+ <emphasis>UNRESOLVED</emphasis>:</para>
+
+ <itemizedlist mark=bullet>
+ <listitem><para>A test's execution is interrupted.</listitem>
+
+ <listitem><para>A test does not produce a clear result. This is
+ usually because there was an <emphasis>ERROR</emphasis> from
+ DejaGnu while processing the test, or because there were three or
+ more <emphasis>WARNING</emphasis> messages. Any
+ <emphasis>WARNING</emphasis> or <emphasis>ERROR</emphasis> 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.</para></listitem>
+
+ <listitem><para>A test depends on a previous test, which
+ fails.</para></listitem>
+
+ <listitem><para>The test was set up incorrectly.</para></listitem>
+ </itemizedlist>
+
+ <varlistentry>
+ <term>UNTESTED</term>
+ <listitem><para>A test was not run. This is a placeholder, used
+ when there is no real test case yet.</para>
+ </varlistentry>
+ </variablelist>
+
+ <para>The only remaining output message left is intended to test
+ features that are specified by the applicable POSIX standard as
+ conditional:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>UNSUPPORTED</term>
+ <listitem><para>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 <emphasis>gethostname</emphasis>
+ would never work on a target board running only a boot monitor.
+ </varlistentry>
+ </variablelist>
+
+ <para>DejaGnu uses the same output procedures to produce these messages
+ for all test suites, and these procedures are already known to conform
+ to POSIX 1003.3. For a DejaGnu test suite to conform to POSIX 1003.3,
+ you must avoid the <emphasis>setup</emphasis>xfail} procedure as
+ described in the <emphasis>PASS</emphasis> section above, and you must
+ be careful to return <emphasis>UNRESOLVED</emphasis> where appropriate,
+ as described in the <emphasis>UNRESOLVED</emphasis> section
+ above.</para>
+ </sect1>
+
+ </chapter>
+
+ <!-- include the user manual -->
+ &user;
+
+ <!-- include the reference manual -->
+ &ref;
+
+</book>
diff --git a/doc/ref.sgml b/doc/ref.sgml
new file mode 100644
index 0000000..6a1a7d6
--- /dev/null
+++ b/doc/ref.sgml
@@ -0,0 +1,4242 @@
+<chapter id=reference>
+ <title>Reference</title>
+
+ <sect1 id=installation xreflabel="Installation">
+ <title>Installation</title>
+
+ <para>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.</para>
+
+ <sect2 id=configuring xreflabel="Configuring DejaGnu">
+ <title>Configuring DejaGnu</title>
+
+ <para>It is usually best to configure in a directory separate from the
+ source tree, specifying where to find the source with the optional
+ <emphasis>--srcdir</emphasis> option to
+ <emphasis>configure</emphasis>. DejaGnu uses the GNU
+ <emphasis>autoconf</emphasis> to configure itself. For more info on using
+ autoconf, read the GNU autoconf manual. To configure, execute the
+ <filename>configure</filename> 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:</para>
+
+ <screen>
+ ../dejagnu-1.4/configure
+ </screen>
+
+ <para>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.</para>
+
+ <para>You may also want to use the <command>configure</command> option
+ <emphasis>--prefix</emphasis> to specify where you want DejaGnu and its
+ supporting code installed. By default, installation is in subdirectories
+ of <filename>/usr/local</filename>, but you can select any alternate
+ directory <symbol>altdir</symbol> by including
+ <option>--prefix</option>{altdir}} on the
+ <command>configure</command> command line. (This value is captured in
+ the Makefile variables <emphasis>prefix</emphasis> and
+ <emphasis>exec</emphasis>prefix}.)</para>
+
+ <para>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 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 <emphasis>make check</emphasis> to build
+ auxiliary programs required by some of the tests, and run the test
+ suites.</para>
+
+ </sect2>
+
+ <sect2 id=installing xreflabel="Installing DejaGnu">
+ <title>Installing DejaGnu</title>
+
+ <para>To install DejaGnu in your filesystem (either in
+ <filename>/usr/local</filename>, or as specified by your
+ <emphasis>--prefix</emphasis> option to <emphasis>configure</emphasis>),
+ execute.</para>
+
+ <screen>
+ eg$ make install
+ </screen>
+
+ <para><emphasis>make install</emphasis>does thes things for
+ DejaGnu:</para>
+
+ <itemizedlist mark=bullet>
+ <listitem><para>Look in the path specified for executables
+ <symbol>$exec_prefix</symbol>) for directories called
+ <filename>lib</filename> and <filename>bin</filename>. If these
+ directories do not exist, <emphasis>make install</emphasis> creates
+ them.</para></listitem>
+
+ <listitem><para>Create another directory in the
+ <filename>share</filename> directory, called
+ <filename>dejagnu</filename>, and copy all the library files into
+ it.</listitem>
+
+ <listitem><para>Create a directory in the
+ <filename>dejagnu/share</filename> directory, called
+ <filename>config</filename>, and copy all the configuration files into
+ it.</listitem>
+
+ <listitem><para>Copy the <emphasis>runtest</emphasis> shell script into
+ <filename>$exec_prefix/bin</filename>.
+
+ <listitem><para>Copy <filename>runtest.exp</filename> into
+ <filename>$exec_prefix/lib/dejagnu</filename>. This is the main Tcl
+ code implementing DejaGnu.</para></listitem>
+
+ </itemizedlist>
+ </sect2>
+ </sect1>
+
+ <sect1 id=builtins xreflabel="Builtin Procedures">
+ <title>Builtin Procedures</title>
+
+ <para>DejaGnu provides these Tcl procedures.</para>
+
+ <sect2 id=coreprocs xreflabel="Core Internal Procedures">
+ <title>Core Internal Procedures</title>
+
+ <sect3 id=mailfile xreflabel="mail_file procedure">
+ <title>Mail_file Procedure</title>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>mail_file</function></funcdef>
+ <paramdef><parameter>file to subject</parameter</paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=openlogs xreflabel="open_logs procedure">
+ <title>Open_logs Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>open_logs</function></funcdef>
+ <paramdef><parameter></parameter</paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=closelogs xreflabel="close_logs procedure">
+ <title>Close_logs Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>close_logs</function></funcdef>
+ <paramdef><parameter></parameter</paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=isbuild xreflabel="isbuild procedure">
+ <title>Isbuild Procedure</title>
+
+ <para>Tests for a particular build host environment. If the
+ currently configured host matches the argument string, the result is
+ <emphasis>1</emphasis>; otherwise the result is
+ <emphasis>0</emphasis>. <emphasis>host</emphasis> 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.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>isbuild</function></funcdef>
+ <paramdef><parameter>pattern</parameter</paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>pattern</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=isremote xreflabel="is_remote procedure">
+ <title>Is_remote Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>is_remote</function></funcdef>
+ <paramdef><parameter>board</parameter</paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=is3way xreflabel="is3way procedure">
+ <title>is3way Procedure</title>
+
+ <para>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 <emphasis>1</emphasis>; otherwise the result is
+ <emphasis>0</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>is3way</function></funcdef>
+ <paramdef><parameter></parameter</paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=ishost xreflabel="ishost procedure">
+ <title>Ishost Procedure</title>
+
+ <para>Tests for a particular host environment. If the currently
+ configured host matches the argument string, the result is
+ <emphasis>1</emphasis>; otherwise the result is
+ <emphasis>0</emphasis>. <emphasis>host</emphasis> 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).</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>ishost</function></funcdef>
+ <paramdef><parameter>pattern</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=istarget xreflabel="istarget procedure">
+ <title>Istarget Procedure</title>
+
+ <para>Tests for a particular target environment. If the currently
+ configured target matches the argument string, the result is
+ <emphasis>1</emphasis> ; otherwise the result is
+ <emphasis>0</emphasis>. 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
+ <emphasis>NULL</emphasis> string, then it returns the name of the
+ build canonical configuration.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>istarget</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=isnative xreflabel="isnative procedure">
+ <title>Isnative Procedure</title>
+
+ <para>Tests whether the current configuration has the same host and
+ target. When it runs in a native configuration this procedure returns
+ a <emphasis>1</emphasis>; otherwise it returns a
+ <emphasis>0</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>isnative</function></funcdef>
+ <paramdef><parameter></parameter</paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=unknown xreflabel="unknown procedure">
+ <title>Unknown Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>unknown</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=cloneoutput xreflabel="clone_output procedure">
+ <title>Clone_output Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>clone_output</function></funcdef>
+ <paramdef><parameter>message</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>message</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=resetvars xreflabel="reset_vars procedure">
+ <title>Reset_vars Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>reset_vars</function></funcdef>
+ <paramdef><parameter></parameter</paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=logandexit xreflabel="log_and_exit procedure">
+ <title>Log_and_exit Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>log_and_exit</function></funcdef>
+ <paramdef><parameter></parameter</paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=logsummary xreflabel="log_summary procedure">
+ <title>Log_summary Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>log_summary</function></funcdef>
+ <paramdef><parameter>args</parameter</paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=cleanup xreflabel="cleanup procedure">
+ <title>Cleanup Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>cleanup</function></funcdef>
+ <paramdef><parameter></parameter</paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=setupxfail xreflabel="setup_xfail procedure">
+ <title>Setup_xfail Procedure</title>
+
+ <para>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
+ <emphasis>bugid</emphasis> argument is optional, and used only in the
+ logging file output; use it as a link to a bug-tracking system such
+ as <productname>GNATS</productname>.</para>
+
+ <para>Once you use <function>setup_xfail</function>, the
+ <function>fail</function> and <function>pass</function> procedures
+ produce the messages <emphasis>XFAIL</emphasis> and
+ <emphasis>XPASS</emphasis> respectively, allowing you to distinguish
+ expected failures (and unexpected success!) from other test
+ outcomes.</para>
+
+ <warning><para>Warning you must clear the expected failure after
+ using setup_xfail in a test case. Any call to <function>pass
+ </function>or <function>fail</function>l clears the expected failure
+ implicitly; if the test has some other outcome, e.g. an error, you
+ can call <function>clear_xfail</function> to clear the expected
+ failure explicitly. Otherwise, the expected-failure declaration
+ applies to whatever test runs next, leading to surprising
+ results.</para></warning>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>setup_xfail</function></funcdef>
+ <paramdef><parameter>config</parameter>
+ <parameter>bugid</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>config</parameter></term>
+ <listitem><para>The config triplet to trigger whether this is an
+ unexpected or expect failure.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>bugid</parameter></term>
+ <listitem><para>The optional bugid, used to tie it this test case
+ to a bug tracking system.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=recordtest xreflabel="record_test procedure">
+ <title>Record_test Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>record_test</function></funcdef>
+ <paramdef><parameter>type</parameter>
+ <parameter>message</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>type</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>message</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=pass xreflabel="pass procedure">
+ <title>Pass Procedure</title>
+
+ <para>Declares a test to have passed. <function>pass</function>
+ writes in the log files a message beginning with
+ <emphasis>PASS</emphasis> (or <emphasis>XPASS</emphasis>, if failure
+ was expected), appending the argument
+ <parameter>string</parameter>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>pass</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this PASS
+ message.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=fail xreflabel="fail procedure">
+ <title>Fail Procedure</title>
+
+ <para>Declares a test to have failed. <function>fail</function>
+ writes in the log files a message beginning with
+ <emphasis>FAIL</emphasis> (or <emphasis>XFAIL</emphasis>, if failure
+ was expected), appending the argument
+ <parameter>string</parameter>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>fail</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this FAIL
+ message.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=xpass xreflabel="xpass procedure">
+ <title>Xpass Procedure</title>
+
+ <para>Declares a test to have unexpectably passed, when it was
+ expected to be a failure. <function>xpass</function>
+ writes in the log files a message beginning with
+ <emphasis>XPASS</emphasis> (or <emphasis>XFAIL</emphasis>, if failure
+ was expected), appending the argument
+ <parameter>string</parameter>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>xpass</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this output
+ state.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=xfail xreflabel="xfail procedure">
+ <title>Xfail Procedure</title>
+
+ <para>Declares a test to have expectably
+ failed. <function>xfail</function>
+ writes in the log files a message beginning with
+ <emphasis>XFAIL</emphasis> (or <emphasis>PASS</emphasis>, if success
+ was expected), appending the argument
+ <parameter>string</parameter>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>xpass</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this output
+ state.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=setwarningthreshold xreflabel="set_warning_threshold procedure">
+ <title>Set_warning_threshold Procedure</title>
+
+ <para>Sets the value of <symbol>warning_threshold</symbol>. A value
+ of <emphasis>0</emphasis> disables it: calls to
+ <function>warning</function> will not turn a
+ <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> into an
+ <emphasis>UNRESOLVED</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>set_warning_threshold</function></funcdef>
+ <paramdef><parameter>threshold</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>threshold</parameter></term>
+ <listitem><para>This is the value of the new warning
+ threshold.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=getwarningthreshold xreflabel="get_warning_threshold procedure">
+ <title>Get_warning_threshold Procedure</title>
+
+ <para>Returns the current value of
+ <symbol>{warning_threshold</symbol>. The default value is 3. This
+ value controls how many <function>warning</function> procedures can
+ be called before becoming <emphasis>UNRESOLVED</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>get_warning_threshold</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+
+ <sect3 id=warning xreflabel="warning procedure">
+ <title>Warning Procedure</title>
+
+ <para>Declares detection of a minor error in the test case
+ itself. <function>warning</function> writes in the log files a message
+ beginning with <emphasis>WARNING</emphasis>, appending the argument
+ <parameter>string</parameter>. Use <function>warning</function> rather
+ than <function>perror</function> for cases (such as communication
+ failure to be followed by a retry) where the test case can recover from
+ the error. If the optional <parameter>number</parameter> is supplied,
+ then this is used to set the internal count of warnings to that
+ value.</para>
+
+ <para>As a side effect, <symbol>warning_threshold</symbol> or more
+ calls to warning in a single test case also changes the effect of the
+ next <function>pass</function> or <function>fail</function> command:
+ the test outcome becomes <emphasis>UNRESOLVED</emphasis> since an
+ automatic <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> may
+ not be trustworthy after many warnings. If the optional numeric value
+ is <emphasis>0</emphasis>, then there are no further side effects to
+ calling this function, and the following test outcome doesn't become
+ <emphasis>UNRESOLVED</emphasis>. This can be used for errors with no
+ known side effects.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>warning</function></funcdef>
+ <paramdef><parameter>string</parameter>
+ <parameter>number</parameter>
+ </paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>number</parameter></term>
+ <listitem><para>The optional number to set the error counter. Thius
+ is only used to fake out the counter when using the
+ <function>xfail</function> procedure to control when it flips the
+ output over to <emphasis>UNRESOLVED</emphasis>
+ state.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <sect3 id=perror xreflabel="perror procedure">
+ <title>Perror Procedure</title>
+
+ <para>Declares a severe error in the testing framework
+ itself. <function>perror</function> writes in the log files a message
+ beginning with <emphasis>ERROR</emphasis>, appending the argument
+ <parameter>string</parameter>.</para>
+
+ <para>As a side effect, perror also changes the effect of the next
+ <function>pass</function> or <function>fail</function> command: the
+ test outcome becomes <emphasis>UNRESOLVED</emphasis>, since an
+ automatic <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> cannot
+ be trusted after a severe error in the test framework. If the optional
+ numeric value is <emphasis>0</emphasis>, then there are no further side
+ effects to calling this function, and the following test outcome
+ doesn't become <emphasis>UNRESOLVED</emphasis>. This can be used for
+ errors with no known side effects.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>perror</function></funcdef>
+ <paramdef><parameter>string</parameter>
+ <parameter>number</parameter>
+ </paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>number</parameter></term>
+ <listitem><para>The optional number to set the error counter. Thius
+ is only used to fake out the counter when using the
+ <function>xfail</function> procedure to control when it flips the
+ output over to <emphasis>UNRESOLVED</emphasis>
+ state.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <sect3 id=note xreflabel="note procedure">
+ <title>Note Procedure</title>
+
+ <para>Appends an informational message to the log
+ file. <function>note</function> writes in the log files a message
+ beginning with <emphasis>NOTE</emphasis>, appending the argument
+ <parameter>string</parameter>. Use <function>note</function>
+ sparingly. The <function>verbose</function> 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 <function>note</function>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>note</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this note.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=untested xreflabel="untested procedure">
+ <title>Untested Procedure</title>
+
+ <para>Declares a test was not run. <function>untested</function> writes
+ in the log file a message beginning with <emphasis>UNTESTED</emphasis>,
+ appending the argument <emphasis>string</emphasis>. 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.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>untested</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this output
+ state.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=unresolved xreflabel="unresolved procedure">
+ <title>Unresolved Procedure</title>
+
+ <para>Declares a test to have an unresolved
+ outcome. <function>unresolved</function> writes in the log file a
+ message beginning with <emphasis>UNRESOLVED</emphasis>, appending the
+ argument <emphasis>string</emphasis>. 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).</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>unresolved</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this output
+ state.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=unsupported xreflabel="unsupported procedure">
+ <title>Unsupported Procedure</title>
+
+ <para>Declares that a test case depends on some facility that does not
+ exist in the testing environment. <function>unsupported</function>
+ writes in the log file a message beginning with
+ <emphasis>UNSUPPORTED</emphasis>, appending the argument string.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>unsupported</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this output
+ state.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=inittestcounts xreflabel="init_testcounts procedure">
+ <title>Init_testcounts Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>init_testcounts</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=incrcount xreflabel="incr_count procedure">
+ <title>Incr_count Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>incr_count</function></funcdef>
+ <paramdef><parameter>name</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=transform xreflabel="transform procedure">
+ <title>transform Procedure</title>
+
+ <para>Generates a string for the name of a tool as it was configured
+ and installed, given its native name (as the argument
+ <parameter>toolname</parameter>). This makes the assumption that all
+ tools are installed using the same naming conventions: For example,
+ for a cross compiler supporting the <emphasis>m68k-vxworks</emphasis>
+ configuration, the result of transform <command>gcc</command> is
+ <command>m68k-vxworks-gcc</command>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>transform</function></funcdef>
+ <paramdef><parameter>toolname</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>toolname</parameter></term>
+ <listitem><para>The name of the cross-development program to
+ transform.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+
+ <sect3 id=checkconditionalxfail xreflabel="check_conditional_xfail procedure">
+ <title>Check_conditional_xfail Procedure</title>
+
+ <para>This procedure adds a condition 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 <emphasis>XFAIL</emphasis>. Otherwise it'll produce
+ an ordinary <emphasis>FAIL</emphasis>. You can also specify flags to
+ exclude. This makes a result be a <emphasis>FAIL</emphasis>, even if
+ the included options are found. To set the conditional, set
+ the variable <symbol>compiler_conditional_xfail_data</symbol> to the
+ fields <programlisting>"[message string] [targets list] [includes
+ list] [excludes list]"</programlisting> (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 <emphasis>1</emphasis> if the
+ conditional is true, or <emphasis>0</emphasis> if the conditional is
+ false.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>check_conditional_xfail</function></funcdef>
+ <paramdef><parameter>message</parameter>
+ <parameter>targets</parameter>
+ <parameter>includes</parameter>
+ <parameter>excludes</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>message</parameter></term>
+ <listitem><para>This is the message to print with the normal test
+ result.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>targets</parameter></term>
+ <listitem><para>This is a string with the list targets to activate
+ this conditional on.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>includes</parameter></term>
+ <listitem><para>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, then this conditional is
+ true.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>excludes</parameter></term>
+ <listitem><para>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.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <example>
+ <title>Specifying the conditional xfail data</title>
+
+ <programlisting>
+ set compiler_conditional_xfail_data { \
+ "I sure wish I knew why this was hosed" \
+ "sparc*-sun*-* *-pc-*-*" \
+ {"-Wall -v" "-O3"} \
+ {"-O1" "-Map"} \
+ }
+ </programlisting>
+
+ </example>
+
+ <para>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.</para>
+
+ </sect3>
+
+ <sect3 id=clearxfail xreflabel="clear_xfail procedure">
+ <title>Clear_xfail Procedure</title>
+
+ <para>Cancel an expected failure (previously declared with
+ <command>setup_xfail</command>) for a particular set of
+ configurations. The <parameter>config</parameter> argument is a list
+ of configuration target names. It is only necessary to call
+ <command>clear_xfail</command> if a test case ends without calling
+ either <command>pass</command> or <command>fail</command>, after
+ calling <command>setup_xfail</command>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>clear_xfail</function></funcdef>
+ <paramdef><parameter>config</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>config</parameter></term>
+ <listitem><para>The configuration triplets to
+ clear.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=verbose xreflabel="verbose procedure">
+ <title>Verbose Procedure</title>
+
+ <para>Test cases can use this function to issue helpful messages
+ depending on the number of <option>--verbose</option> options on the
+ runtest command line. It prints string if the value of the variable
+ <symbol>verbose</symbol> is higher than or equal to the optional
+ number. The default value for number is <emphasis>1</emphasis>. Use
+ the optional <option>-log</option> argument to cause string to always
+ be added to the log file, even if it won't be printed. Use the
+ optional <option>-n</option> argument to print string without a
+ trailing newline. Use the optional <option>--</option> argument if
+ string begins with "-".</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>verbose</function></funcdef>
+ <paramdef><parameter>-log</parameter>
+ <parameter>-n</parameter>
+ <parameter>-r</parameter>
+ <parameter>string</parameter>
+ <parameter>number</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>-log</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>-n</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>--</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>number</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=loadlib xreflabel="load_lib procedure">
+ <title>Load_lib Procedure</title>
+
+ <para>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
+ <command>make install</command>, this path defaults to the current
+ directory. In either case, it then looks in the current directory
+ for a directory called <filename>lib</filename>. If there are
+ duplicate definitions, the last one loaded takes precedence over the
+ earlier ones.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>load_lib</function></funcdef>
+ <paramdef><parameter>filespec</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>filespec</parameter></term>
+ <listitem><para>The name of the DejaGnu library file to
+ load.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id=remoteprocs>
+ <title>Procedures For Remote Communication</title>
+
+ <para><filename>lib/remote.exp</filename> 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 <emphasis>-1</emphasis>, when the
+ connection cannot be established, or the spawn ID returned by
+ the <productname>Expect</productname> command
+ <command>spawn</command>.</para>
+
+ <para>It use the value of the <symbol>connect</symbol> field
+ in the <symbol>target_info</symbol> array (was
+ <symbol>connectmode</symbol> as the type of connection to
+ make. Current supported connection types are tip, kermit,
+ telnet, rsh, rlogin, and netdata. If the <option>--reboot</option>
+ option was used on the runtest command line, then the target
+ is rebooted before the connection is made.</para>
+
+ <sect3 id=callremote xreflabel="call_remote procedure">
+ <title>Call_remote Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>call_remote</function></funcdef>
+ <paramdef><parameter>type</parameter>
+ <parameter>proc</parameter>
+ <parameter>dest</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>proc</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=checkforboardstatus xreflabel="check_for_board_status
+ procedure">
+ <title>Check_for_board_status Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>check_for_board_status</function></funcdef>
+ <paramdef><parameter>variable</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>variable</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=fileonbuild xreflabel="file_on_build procedure">
+ <title>File_on_build Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>file_on_build</function></funcdef>
+ <paramdef><parameter>op</parameter>
+ <parameter>file</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>op</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=fileonhost xreflabel="file_on_host procedure">
+ <title>File_on_host Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>file_on_host</function></funcdef>
+ <paramdef><parameter>op</parameter>
+ <parameter>file</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>op</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=localexec xreflabel="local_exec procedure">
+ <title>Local_exec Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>local_exec</function></funcdef>
+ <paramdef><parameter>commandline</parameter>
+ <parameter>inp</parameter>
+ <parameter>outp</parameter>
+ <parameter>timeout</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>inp</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>outp</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>timeout</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remotebinary xreflabel="remote_binary procedure">
+ <title>Remote_binary Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_binary</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoteclose xreflabel="remote_close procedure">
+ <title>Remote_close Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_close</function></funcdef>
+ <paramdef><parameter>shellid</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>shellid</parameter></term>
+ <listitem><para>This is the value returned by a call
+ to <function>remote_open</function>. This closes the
+ connection to the target so resources can be used by
+ others. This parameter can be left off if the
+ <symbol>fileid</symbol> field in the
+ <symbol>target_info</symbol> array is set.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remotedownload xreflabel="remote_download procedure">
+ <title>Remote_download Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_download</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoteexec xreflabel="remote_exec procedure">
+ <title>Remote_exec Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_exec</function></funcdef>
+ <paramdef><parameter>hostname</parameter>
+ <parameter>program</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>hostname</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>program</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoteexpect xreflabel="remote_expect procedure">
+ <title>Remote_expect Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_expect</function></funcdef>
+ <paramdef><parameter>board</parameter>
+ <parameter>timeout</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>board</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>timeout</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remotefile xreflabel="remote_file procedure">
+ <title>Remote_file Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_file</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>args</parameter</paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoteld xreflabel="remote_ld procedure">
+ <title>Remote_ld Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_ld</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>prog</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>prog</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoteload xreflabel="remote_load procedure">
+ <title>Remote_load Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_load</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>prog</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>prog</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoteopen xreflabel="remote_open procedure">
+ <title>Remote_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_open</function></funcdef>
+ <paramdef><parameter>type</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>type</parameter></term>
+ <listitem><para>This is passed <option>host</option> or
+ <option>target</option>. 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
+ <symbol>spawn_id</symbol> of the process that manages
+ the connection. This value can be used in
+ <productname>Expect</productname> or
+ <command>exp_send</command> statements, or passed to
+ other procedures that need the connection process's
+ id. This also sets the <symbol>fileid</symbol> field in
+ the <symbol>target_info</symbol> array.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remotepopconn xreflabel="remote_pop_conn procedure">
+ <title>Remote_pop_conn Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_pop_conn</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remotepushconn xreflabel="remote_push_conn procedure">
+ <title>Remote_push_conn Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_push_conn</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoterawbinary xreflabel="remote_raw_binary procedure">
+ <title>Remote_raw_binary Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_raw_binary</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoterawclose xreflabel="remote_raw_close procedure">
+ <title>Remote_raw_close Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_raw_close</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoterawfile xreflabel="remote_raw_file procedure">
+ <title>Remote_raw_file Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_raw_file</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoterawld xreflabel="remote_raw_ld procedure">
+ <title>remote_raw_ld Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_raw_ld</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>prog</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>prog</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoterawload xreflabel="remote_raw_load procedure">
+ <title>Remote_raw_load Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_raw_load</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>prog</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>prog</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoterawopen xreflabel="remote_raw_open procedure">
+ <title>Remote_raw_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_raw_open</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoterawsend xreflabel="remote_raw_send procedure">
+ <title>Remote_raw_send Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_raw_send</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>string</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoterawspawn xreflabel="remote_raw_spawn procedure">
+ <title>Remote_raw_spawn Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_raw_spawn</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>commandline</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>commandline</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoterawtransmit xreflabel="remote_raw_transmit
+ procedure">
+ <title>Remote_raw_transmit Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_raw_transmit</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoterawwait xreflabel="remote_raw_wait procedure">
+ <title>Remote_raw_wait Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_raw_wait</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>timeout</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>timeout</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remotereboot xreflabel="remote_reboot procedure">
+ <title>Remote_reboot Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_reboot</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remotesend xreflabel="remote_send procedure">
+ <title>Remote_send Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_send</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>string</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remotespawn xreflabel="remote_spawn procedure">
+ <title>Remote_spawn Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_spawn</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>commandline</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>commandline</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoteswapconn xreflabel="remote_swap_conn procedure">
+ <title>Remote_swap_conn Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_swap_conn</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remotetransmit xreflabel="remote_transmit procedure">
+ <title>Remote_transmit Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_transmit</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remoteupload xreflabel="remote_upload procedure">
+ <title>Remote_upload Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_upload</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>srcfile</parameter>
+ <parameter>arg</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>srcfile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>arg</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=remotewait xreflabel="remote_wait procedure">
+ <title>Remote_wait Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>remote_wait</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>timeout</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>timeout</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=standardclose xreflabel="standard_close procedure">
+ <title>Standard_close Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>standard_close</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=standarddownload xreflabel="standard_download procedure">
+ <title>Standard_download Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>standard_download</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter>
+ <parameter>destfile</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>destfile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=standardexec xreflabel="standard_exec procedure">
+ <title>Standard_exec Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>standard_exec</function></funcdef>
+ <paramdef><parameter>hostname</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>hostname</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=standardfile xreflabel="standard_file procedure">
+ <title>Standard_file Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>standard_file</function></funcdef>
+ <paramdef><parameter>dest</parameter
+ <parameter>op</parameter
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=standardload xreflabel="standard_load procedure">
+ <title>Standard_load Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>standard_load</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>prog</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>prog</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=standardreboot xreflabel="standard_reboot procedure">
+ <title>Standard_reboot Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>standard_reboot</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=standardsend xreflabel="standard_send procedure">
+ <title>Standard_send Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>standard_send</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>string</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=standardspawn xreflabel="standard_spawn procedure">
+ <title>Standard_spawn Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>standard_spawn</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>commandline</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>commndline</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=standardtransmit xreflabel="standard_transmit procedure">
+ <title>Standard_transmit Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>standard_transmit</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=standardupload xreflabel="standard_upload procedure">
+ <title>Standard_upload Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>standard_upload</function></funcdef>
+ <paramdef><parameter>dest srcfile destfile</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>srcfile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>destfile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=standardwait xreflabel="standard_wait procedure">
+ <title>Standard_wait Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>standard_wait</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>timeout</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>timeout</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=unixcleanfilename xreflabel="unix_clean_filename
+ procedure">
+ <title>Unix_clean_filename Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>unix_clean_filename</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+<!-- FIXME: this doesn't seem to exist anymore
+ <sect3 id=exitremoteshell xreflabel="exit_remote_shell procedure">
+ <title>exit_remote_shell Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>exit_remote_shell</function></funcdef>
+ <paramdef><parameter>spawnid</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>spawnid</parameter></term>
+ <listitem><para>Exits a remote process started by any
+ of the connection procedures. <symbol>spawnid</symbol>
+ is the result of the connection procedure that started
+ the remote process.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+-->
+
+ </sect2>
+
+ <sect2 id=connprocs xreflabel="connprocs">
+ <title>Procedures For Using Utilities to Connect</title>
+
+ <para>telnet, rsh, tip, kermit</para>
+
+ <sect3 id=telnet xreflabel="telnet procedure">
+ <title>telnet Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>telnet</function></funcdef>
+ <paramdef><parameter>hostname</parameter>
+ <parameter>port</parameter></paramdef>
+ </funcsynopsis>
+ <funcsynopsis role="tcl">
+ <funcdef><function>rlogin</function></funcdef>
+ <paramdef><parameter>hostname</parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=rsh xreflabel="rsh procedure">
+ <title>rsh Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>rsh</function></funcdef>
+ <paramdef><parameter>hostname</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>hostname</parameter></term>
+ <listitem><para>This refers to the IP address or name
+ (for example, an entry in
+ <filename>/etc/hosts</filename>) for this target. The
+ procedure names reflect the Unix utility used to
+ establish a connection. The optional
+ <parameter>port</parameter> is used to specify the IP
+ port number. The value of the
+ <parameter>netport</parameter> field in the
+ <symbol>target_info</symbol> array is used. (was
+ <symbol>$netport</symbol>) This value has two parts,
+ the hostname and the port number, seperated by a
+ <emphasis>:</emphasis>. If host or target is used in
+ the <symbol>hostname</symbol> field, than the
+ config array is used for all information.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=tip xreflabel="tip procedure">
+ <title>Tip Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>tip</function></funcdef>
+ <paramdef><parameter>port</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>port</parameter></term>
+ <listitem><para>Connect using the Unix utility
+ <command>tip</command>. <parameter>Port</parameter>must
+ be a name from the <productname>tip</productname>
+ configuration file
+ <filename>/etc/remote</filename>. Often, this is called
+ <symbol>hardwire</symbol>, or something like
+ <symbol>ttya</symbol>. This file holds all the
+ configuration data for the serial port. The value of
+ the <symbol>serial</symbol> field in the
+ <symbol>target_info</symbol> array is used. (was
+ <symbol>$serialport</symbol>) If <option>host</option>
+ or <option>target</option> is used in the
+ <parameter>port</parameter> field, than the config
+ array is used for all information. the
+ config array is used for all information.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=kermit xreflabel="kermit procedure">
+ <title>Kermit Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>kermit</function></funcdef>
+ <paramdef><parameter>port</parameter>
+ <parameter>bps</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>port</parameter></term>
+ <listitem><para>Connect using the program
+ <command>kermit</command>. <parameter>Port</parameter>
+ is the device name,
+ e.g. <filename>/dev/ttyb</filename>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>bps</parameter></term>
+ <listitem><para><parameter>bps</parameter> is the line
+ speed to use (in its per second) for the
+ connection. The value of the <symbol>serial</symbol>
+ field in the <symbol>target_info</symbol> array is
+ used. (was <symbol>$serialport</symbol>) If
+ <option>host</option> or <option>target</option> is
+ used in the <parameter>port</parameter> field, than the
+ config array is used for all information. the
+ config array is used for all information.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=kermitopen xreflabel="kermit_open procedure">
+ <title>kermit_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>kermit_open</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=kermitcommand xreflabel="kermit_command procedure">
+ <title>Kermit_command Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>kermit_command</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=kermitsend xreflabel="kermit_send procedure">
+ <title>Kermit_send Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>kermit_send</function></funcdef>
+ <paramdef><parameter>dest string args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=kermittransmit xreflabel="kermit_transmit procedure">
+ <title>Kermit_transmit Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>kermit_transmit</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=telnetopen xreflabel="telnet_open procedure">
+ <title>Telnet_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>telnet_open</function></funcdef>
+ <paramdef><parameter>hostname</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>hostname</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=telnetbinary xreflabel="telnet_binary procedure">
+ <title>Telnet_binary Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>telnet_binary</function></funcdef>
+ <paramdef><parameter>hostname</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>hostname</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=telnettransmit xreflabel="telnet_transmit procedure">
+ <title>Telnet_transmit Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>telnet_transmit</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=tipopen xreflabel="tip_open procedure">
+ <title>Tip_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>tip_open</function></funcdef>
+ <paramdef><parameter>hostname</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>hostname</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=rloginopen xreflabel="rlogin_open procedure">
+ <title>Rlogin_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>rlogin_open</function></funcdef>
+ <paramdef><parameter>arg</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>arg</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=rloginspawn xreflabel="rlogin_spawn procedure">
+ <title>Rlogin_spawn Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>rlogin_spawn</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>cmdline</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dest</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cmdline</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=rshopen xreflabel="rsh_open procedure">
+ <title>Rsh_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>rsh_open</function></funcdef>
+ <paramdef><parameter>hostname</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>hostname</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=rshdownload xreflabel="rsh_download procedure">
+ <title>Rsh_download Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>rsh_download</function></funcdef>
+ <paramdef><parameter>desthost</parameter>
+ <parameter>srcfile</parameter>
+ <parameter>destfile</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>desthost</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>srcfile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>destfile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=rshupload xreflabel="rsh_upload procedure">
+ <title>Rsh_upload Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>rsh_upload</function></funcdef>
+ <paramdef><parameter>desthost</parameter>
+ <parameter>srcfile</parameter>
+ <parameter>destfile</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>desthost</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>srcfile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>destfile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=rshexec xreflabel="rsh_exec procedure">
+ <title>Rsh_exec Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>rsh_exec</function></funcdef>
+ <paramdef><parameter>boardname</parameter>
+ <parameter>cmd</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>boardname</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cmd</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=ftpopen xreflabel="ftp_open procedure">
+ <title>Ftp_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>ftp_open</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=ftpupload xreflabel="ftp_upload procedure">
+ <title>Ftp_upload Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>ftp_upload</function></funcdef>
+ <paramdef><parameter>host</parameter>
+ <parameter>remotefile</parameter>
+ <parameter>localfile</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>remotefile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>localfile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=ftpdownload xreflabel="ftp_download procedure">
+ <title>Ftp_download Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>ftp_download</function></funcdef>
+ <paramdef><parameter>host</parameter>
+ <parameter>localfile</parameter>
+ <parameter>remotefile</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>localfile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>remotefile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=ftpclose xreflabel="ftp_close procedure">
+ <title>Ftp_close Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>ftp_close</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=tipdownload xreflabel="tip_download procedure">
+ <title>Tip_download Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>tip_download</function></funcdef>
+ <paramdef><parameter>spawnid</parameter>
+ <parameter>file</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>spawnid</parameter></term>
+ <listitem><para>Download <option>file</option> to the
+ process <symbol>spawnid</symbol> (the value returned
+ when the connection was established), using the
+ <command>~put</command> command under
+ <productname>tip</productname>. Most often used for
+ single board computers that require downloading
+ programs in ASCII S-records. Returns
+ <emphasis>1</emphasis> if an error occurs,
+ <emphasis>0</emphasis> otherwise.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para>This is the filename to
+ downlaod.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+ </sect2>
+
+ <sect2 id=targetprocs>
+ <title>Procedures For Target Boards</title>
+
+ <para></para>
+
+ <sect3 id=defaultlink xreflabel="default_link procedure">
+ <title>Default_link Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>default_link</function></funcdef>
+ <paramdef><parameter>board</parameter>
+ <parameter>objects</parameter>
+ <parameter>destfile</parameter>
+ <parameter>flags</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>board</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>objects</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>destfile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>flags</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=defaulttargetassemble xreflabel="default_target_assemble
+ procedure">
+ <title>Default_target_assemble Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>default_target_assemble</function></funcdef>
+ <paramdef><parameter>source</parameter>
+ <parameter>destfile</parameter>
+ <parameter>flags</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>source</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>destfile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>flags</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=defaulttargetcompile xreflabel="default_target_compile
+ procedure">
+ <title>default_target_compile Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>default_target_compile</function></funcdef>
+ <paramdef><parameter>source</parameter>
+ <parameter>destfile</parameter>
+ <parameter>type</parameter>
+ <parameter>options</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>source</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>destfile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>type</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>options</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=popconfig xreflabel="pop_config procedure">
+ <title>Pop_config Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>pop_config</function></funcdef>
+ <paramdef><parameter>type</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>type</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=prunewarnings xreflabel="prune_warnings procedure">
+ <title>Prune_warnings Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>prune_warnings</function></funcdef>
+ <paramdef><parameter>text</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>text</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=pushbuild xreflabel="push_build procedure">
+ <title>Push_build Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>push_build</function></funcdef>
+ <paramdef><parameter>name</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=pushconfig xreflabel="push_config procedure">
+ <title>push_config Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>push_config</function></funcdef>
+ <paramdef><parameter>type</parameter>
+ <parameter>name</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>type</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=reboottarget xreflabel="reboot_target procedure">
+ <title>Reboot_target Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>reboot_target</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=targetassemble xreflabel="target_assemble procedure">
+ <title>Target_assemble Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>target_assemble</function></funcdef>
+ <paramdef><parameter>source destfile flags</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>source</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>destfile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>flags</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=targetcompile xreflabel="target_compile procedure">
+ <title>Target_compile Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>target_compile</function></funcdef>
+ <paramdef><parameter>source</parameter>
+ <parameter>destfile</parameter>
+ <parameter>type</parameter>
+ <parameter>options</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>source</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>destfile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>type</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>options</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+ </sect2>
+
+ <sect2 id=targetdb xreflabel="target database library file ">
+ <title>Target Database Procedures</title>
+
+ <sect3 id=boardinfo xreflabel="board_info procedure">
+ <title>Board_info Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>board_info</function></funcdef>
+ <paramdef><parameter>machine</parameter>
+ <parameter>op</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>machine</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>op</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=hostinfo xreflabel="host_info procedure">
+ <title>Host_info Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>host_info</function></funcdef>
+ <paramdef><parameter>op</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>op</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=setboardinfo xreflabel="set_board_info procedure">
+ <title>Set_board_info Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>set_board_info</function></funcdef>
+ <paramdef><parameter>entry</parameter>
+ <parameter>value</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>entry</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>value</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=setcurrtargetinfo xreflabel="set_currtarget_info
+ procedure">
+ <title>Set_currtarget_info Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>set_currtarget_info</function></funcdef>
+ <paramdef><parameter>entry</parameter>
+ <parameter>value</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>entry</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>value</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=targetinfo xreflabel="target_info procedure">
+ <title>Target_info Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>target_info</function></funcdef>
+ <paramdef><parameter>op</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>op</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=unsetboardinfo xreflabel="unset_board_info procedure">
+ <title>Unset_board_info Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>unset_board_info</function></funcdef>
+ <paramdef><parameter>entry</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>entry</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=unsetcurrtargetinfo xreflabel="unset_currtarget_info
+ procedure">
+ <title>Unset_currtarget_info Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>unset_currtarget_info</function></funcdef>
+ <paramdef><parameter>entry</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>entry</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=pushtarget xreflabel="push_target procedure">
+ <title>Push_target Procedure</title>
+
+ <para>This makes the target named <emphasis>name</emphasis> be the
+ current target connection. The value of <emphasis>name</emphasis> is
+ an index into the <symbol>target_info</symbol> array and is set in
+ the global config file.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>push_target</function></funcdef>
+ <paramdef><parameter>name</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem><para>The name of the target to make current
+ connection.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=poptarget xreflabel="poptarget procedure">
+ <title>Pop_target Procedure</title>
+
+ <para>This unsets the current target connection.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>pop_target</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=listtargets xreflabel="list_targets procedure">
+ <title>List_targets Procedure</title>
+
+ <para>This lists all the supported targets for this
+ architecture.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>list_targets</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=pushhost xreflabel="push_host procedure">
+ <title>Push_host Procedure</title>
+
+ <para>This makes the host named <emphasis>name</emphasis> be the
+ current remote host connection. The value of
+ <emphasis>name</emphasis> is an index into the
+ <symbol>target_info</symbol> array and is set in the global config
+ file.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>push_host</function></funcdef>
+ <paramdef><parameter>name</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=pophost xreflabel="pop_host procedure">
+ <title>Pop_host Procedure</title>
+
+ <para>This unsets the current host connection.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>pop_host</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=compile xreflabel="compile procedure">
+ <title>Compile Procedure</title>
+
+ <para>This invokes the compiler as set by CC to compile the
+ file <filename>file</filename>. The default options for many cross
+ compilation targets are <emphasis>guessed</emphasis> by DejaGnu, and
+ these options can be added to by passing in more parameters as
+ arguments to <command>compile</command>. Optionally, this will also
+ use the value of the <emphasis>cflags</emphasis> 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
+ <command>execute_anywhere</command>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>compile</function></funcdef>
+ <paramdef><parameter>file</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=archive xreflabel="archive procedure">
+ <title>Archive Procedure</title>
+
+ <para>This produces an archive file. Any parameters passed to
+ <command>archive</command> are used in addition to the default
+ flags. Optionally, this will also use the value of the
+ <emphasis>arflags</emphasis> 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 <command>execute_anywhere</command>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>archive</function></funcdef>
+ <paramdef><parameter>file</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=ranlib xreflabel="ranlib procedure">
+ <title>Ranlib Procedure</title>
+
+ <para>This generates an index for the archive file for systems that
+ aren't POSIX yet. Any parameters passed to <command>ranlib</command>
+ are used in for the flags.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>ranlib</function></funcdef>
+ <paramdef><parameter>file</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=executeanywhere xreflabel="execute_anywhere procedure">
+ <title>Execute_anywhere Procedure</title>
+
+ <para>This executes the <emphasis>cmdline</emphasis> on the proper
+ host. This should be used as a replacement for the Tcl command
+ <command>exec</command> 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.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>execute_anywhere</function></funcdef>
+ <paramdef><parameter>cmdline</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>cmdline</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect2 id=platformprocs xreflabel="platform dependant procedures">
+ <title>Platform Dependant Procedures</title>
+
+ <para>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
+ <emphasis>_</emphasis>, and finally a suffix describing the
+ procedure's purpose. For example, a procedure to extract the
+ version from <productname>GDB</productname> is called
+ <symbol>gdb_version</symbol>.</para>
+
+ <para><command>runtest</command> itself calls only two of these
+ procedures, <symbol>${tool}_exit</symbol> and
+ <symbol>${tool}_version</symbol>; these procedures use no
+ arguments.</para>
+
+ <para>The other two procedures, <symbol>${tool}_start</symbol>
+ and <symbol>${tool}_load</symbol>}, 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.</para>
+
+ <para>The usual convention for return codes from any of these
+ procedures (although it is not required by
+ <command>runtest</command>) is to return <emphasis>0</emphasis>
+ if the procedure succeeded, <emphasis>1</emphasis> if it failed,
+ and <emphasis>-1</emphasis> if there was a communication error.</para>
+
+ <sect3 id=toolstart xreflabel="${tool}_start procedure">
+ <title>${tool}_start Procedure</title>
+
+ <para>Starts a particular tool. For an interactive tool,
+ <function>${tool}_start</function> starts and initializes the
+ tool, leaving the tool up and running for the test cases; an
+ example is <function>gdb_start</function>, the start function
+ for GDB. For a batch oriented tool,
+ <function>${tool}_start</function> is optional; the recommended
+ convention is to let <function>${tool}_start</function> run the
+ tool, leaving the output in a variable called
+ <function>comp_output</function>. Test scripts can then analyze
+ <function>$comp_output</function> to determine the test results.
+ An example of this second kind of start function is
+ <function>gcc_start</function>, the start function for GCC.</para>
+
+ <para>DejaGnu itself does not call
+ <function>${tool}_start</function>. The initialization
+ module <function>${tool}_init.exp</function> must call
+ <function>${tool}_start</function> for interactive tools;
+ for batch-oriented tools, each individual test script calls
+ <function>${tool}_start</function> (or makes other
+ arrangements to run the tool).</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>${tool}_start</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=toolload xreflabel="${tool}_load procedure">
+ <title>${tool}_load Procedure</title>
+
+ <para>Loads something into a tool. For an interactive tool,
+ this conditions the tool for a particular test case; for
+ example, <function>gdb_load</function> loads a new
+ executable file into the debugger. For batch oriented tools,
+ <function>${tool}_load</function> may do nothing---though,
+ for example, the GCC support uses
+ <function>gcc_load</function> to load and run a binary on
+ the target environment. Conventionally,
+ <function>${tool}_load</function> leaves the output of any
+ program it runs in a variable called
+ <symbol>$exec_output</symbol>. Writing
+ <function>${tool}_load</function> 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
+ <function>${tool}_load</function>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>${tool}_load</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=toolexit xreflabel="${tool}_exit procedure">
+ <title>${tool}_exit Procedure</title>
+
+ <para>Cleans up (if necessary) before DejaGnu exits. For
+ interactive tools, this usually ends the interactive
+ session. You can also use <function>${tool}_exit</function>
+ to remove any temporary files left over from the
+ tests. <command>runtest</command> calls
+ <function>${tool}_exit</function>.<para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>${tool}_exit</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=toolversion xreflabel="${tool}_version procedure">
+ <title>${tool}_version Procedure</title>
+
+ <para>Prints the version label and number for
+ <symbol>${tool}</symbol>. 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.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>${tool}_version</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id=utilprocs>
+ <title>Utility Procedures</title>
+
+ <sect3 id=getdirs xreflabel="getdirs procedure">
+ <title>Getdirs Procedure</title>
+
+ <para>Returns a list of all the directories in the single
+ directory a single directory that match an optional
+ pattern. </para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>getdirs</function></funcdef>
+ <paramdef><parameter>rootdir</parameter>
+ <parameter>pattern</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>pattern</parameter></term>
+ <listitem><para>If you do not specify
+ <parameter>pattern</parameter>,
+ <function>Getdirs</function> assumes a default pattern of
+ <emphasis>*</emphasis>. You may use the common shell
+ wildcard characters in the pattern. If no directories
+ match the pattern, then a NULL string is
+ returned</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=find xreflabel="find procedure">
+ <title>Find Procedure</title>
+
+ <para>Search for files whose names match <emphasis>pattern</emphasis>
+ (using shell wildcard characters for filename expansion). Search
+ subdirectories recursively, starting at
+ <emphasis>rootdir</emphasis>. 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.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>find</function></funcdef>
+ <paramdef><parameter>rootdir</parameter>
+ <parameter>pattern</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>rootdir</parameter></term>
+ <listitem><para>The top level directory to search the search
+ from.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>pattern</parameter></term>
+ <listitem><para>A csh "glob" style regular expression reprsenting
+ the files to find.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=which xreflabel="which procedure">
+ <title>Which Procedure</title>
+
+ <para>Searches the execution path for an executable file
+ <emphasis>binary</emphasis>, like the the BSD <command>which</command>
+ utility. This procedure uses the shell environment variable
+ <emphasis>PATH</emphasis>. It returns <emphasis>0</emphasis> if the
+ binary is not in the path, or if there is no <emphasis>PATH</emphasis>
+ environment variable. If <command>binary</command> is in the path, it
+ returns the full path to <command>binary</command>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>which</function></funcdef>
+ <paramdef><parameter>file</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>binary</parameter></term>
+ <listitem><para>The executable program or shell script to look
+ for.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=grep xreflabel="grep procedure">
+ <title>Grep Procedure</title>
+
+ <para>Search the file called <filename>filename</filename> (a fully
+ specified path) for lines that contain a match for regular expression
+ <emphasis>regexp</emphasis>. The result is a list of all the lines that
+ match. If no lines match, the result is an empty string. Specify
+ <emphasis>regexp</emphasis> using the standard regular expression style
+ used by the Unix utility program grep.</para>
+
+ <para>Use the optional third argument <emphasis>line</emphasis> to
+ start lines in the result with the line number in
+ <filename>filename</filename>. (This argument is simply an option
+ flag; type it just as shown <option>--line</option>.)
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>grep</function></funcdef>
+ <paramdef><parameter>filename</parameter>
+ <parameter>regexp</parameter>
+ <parameter>--line</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>filename</parameter></term>
+ <listitem><para>The file to search.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>regexp</parameter></term>
+ <listitem><para>The Unix style regular expression (as used by the
+ <command>grep</command> Unix utility) to search
+ for.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>--line</parameter></term>
+ <listitem><para>Prefix the line number to each line where the
+ regexp matches.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect3>
+ <sect3 id=prune xreflabel="prune procedure">
+ <title>Prune Procedure</title>
+
+ <para>Remove elements of the Tcl list <emphasis>list</emphasis>.
+ Elements are fields delimited by spaces. The result is a copy of
+ list, without any elements that match <emphasis>pattern</emphasis>.
+ You can use the common shell wildcard characters to specify the
+ pattern.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>prune</function></funcdef>
+ <paramdef><parameter>list</parameter>
+ <parameter>pattern</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>list</parameter></term>
+ <listitem><para>A Tcl list containing the original data. Commonly
+ this is the output of a batch executed command, like running a
+ compiler.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>pattern</parameter></term>
+ <listitem><para>The csh shell "glob" style pattern to search
+ for.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect3>
+
+ <sect3 id=slay xreflabel="slay procedure">
+ <title>Slay Procedure</title>
+
+ <para>This look in the process table for <emphasis>name</emphasis>
+ and send it a unix SIGINT, killing the process. This will only work
+ under NT if you have Cygwin or another Unix system for NT
+ installed.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>slay</function></funcdef>
+ <paramdef><parameter>name</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem><para>The name of the program to kill.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect3>
+
+ <sect3 id=absolute xreflabel="absolute procedure">
+ <title>Absolute Procedure</title>
+
+ <para>This procedure takes the relative <emphasis>path</emphasis>,
+ and converts it to an absolute path.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>absolute</function></funcdef>
+ <paramdef><parameter>path</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>path</parameter></term>
+ <listitem><para>The path to convert.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=psource xreflabel="psource procedure">
+ <title>Psource Procedure</title>
+
+ <para>This sources the file <emphasis>filename</emphasis>, and traps
+ all errors. It also ignores all extraneous output. If there was an
+ error it returns a <emphasis>1</emphasis>, otherwise it returns a
+ <emphasis>0</emphasis>.
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>psource</function></funcdef>
+ <paramdef><parameter>file</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>filename</parameter></term>
+ <listitem><para>The filename to Tcl script to
+ source.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=runtestfilep xreflabel="runtest_file_p procedure">
+ <title>Runtest_file_p Procedure</title>
+
+ <para>Search <emphasis>runtest</emphasis>s for
+ <emphasis>testcase</emphasis> and return <emphasis>1</emphasis> if
+ found, <emphasis>0</emphasis> if not. <emphasis>runtests</emphasis>
+ is a list of two elements. The first is the pathname of the
+ testsuite expect script running. The second is a copy of what was on
+ the right side of the <emphasis>=</emphasis> if
+ <programlisting>foo.exp="..."</programlisting>" was specified, or
+ an empty string if no such argument is present. This is used by tools
+ like compilers where each testcase is a file.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>runtest_file_p</function></funcdef>
+ <paramdef><parameter>runtests</parameter>
+ <parameter>testcase</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>runtests</parameter></term>
+ <listitem><para>The pathname of the testsuite expect script
+ running</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>testcase</parameter></term>
+ <listitem><para>The test case filename.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=diff xreflabel="diff procedure">
+ <title>Diff Procedure</title>
+
+ <para>Compares the two files and returns a <emphasis>1</emphasis> if
+ they match, or a <emphasis>0</emphasis> if they don't. If
+ <symbol>verbose</symbol> is set, then it'll print the differences to
+ the screen.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>diff</function></funcdef>
+ <paramdef><parameter>file_1</parameter>
+ <parameter>file_2</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>file_1</parameter></term>
+ <listitem><para>The first file to compare.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>file_2</parameter></term>
+ <listitem><para>The second file to compare.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=setenv xreflabel="setenv procedure">
+ <title>Setenv Procedure</title>
+
+ <para>Sets the environment variable <emphasis>var</emphasis> to the
+ value <emphasis>val</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>setenv</function></funcdef>
+ <paramdef><parameter>var</parameter>
+ <parameter>val</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>var</parameter></term>
+ <listitem><para>The environment variable to set.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>val</parameter></term>
+ <listitem><para>The value to set the variable to.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <sect3 id=unsetenv xreflabel="unsetenv procedure">
+ <title>unsetenv Procedure</title>
+
+ <para>Unsets the environment variable
+ <emphasis>var</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>unsetenv</function></funcdef>
+ <paramdef><parameter>var</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>var</parameter></term>
+ <listitem><para>The environment variable to
+ unset.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=getenv xreflabel="getenv procedure">
+ <title>Getenv Procedure</title>
+
+ <para>Returns the value of <emphasis>var</emphasis> in the
+ environment if it exists, otherwise it returns NULL.
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>getenv</function></funcdef>
+ <paramdef><parameter>var</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>var</parameter></term>
+ <listitem><para>The environment variable to get the value
+ of.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <sect3 id=prunesystemcrud xreflabel="prune_system_crud procedure">
+ <title>Prune_system_crud Procedure</title>
+
+ <para>For system <emphasis>system</emphasis>, delete text the host or
+ target operating system might issue that will interfere with pattern
+ matching of program output in <emphasis>text</emphasis>. An example
+ is the message that is printed if a shared library is out of
+ date.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>prune_system_crud</function></funcdef>
+ <paramdef><parameter>system</parameter>
+ <parameter>test</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>system</parameter></term>
+ <listitem><para>The system error messages to look for to screen out
+ .</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>text</parameter></term>
+ <listitem><para>The Tcl variable containing the
+ text.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id=libgloss xreflabel="Libgloss">
+ <title>Libgloss, A Free BSP</title>
+
+ <para>Libgloss is a free <firstterm>BSP</firstterm> (Board Support
+ Package) commonly used with GCC and G++ to produce a fully linked
+ executable image for an embedded systems.</para>
+
+ <sect3 id=libglosslinkflags xreflabel="libgloss_link_flags procedure">
+ <title>Libgloss_link_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>libgloss_link_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=libglossincludeflags xreflabel="libgloss_include_flags
+ procedure">
+ <title>Libgloss_include_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>libgloss_include_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=newliblinkflags xreflabel="newlib_link_flags procedure">
+ <title>Newlib_link_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>newlib_link_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=newlibincludeflags xreflabel="newlib_include_flags
+ procedure">
+ <title>Newlib_include_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>newlib_include_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=libioincludeflags xreflabel="libio_include_flags
+ procedure">
+ <title>Libio_include_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>libio_include_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=libiolinkflags xreflabel="libio_link_flags procedure">
+ <title>Libio_link_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>libio_link_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=gxxincludeflags xreflabel="g++_include_flags procedure">
+ <title>G++_include_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>g++_include_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=gxxlinkflags xreflabel="g++_link_flags procedure">
+ <title>G++_link_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>g++_link_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=libstdcxxincludeflags xreflabel="libstdc++_include_flags
+ procedure">
+ <title>Libstdc++_include_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>libstdc++_include_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=libstdcxxlinkflags xreflabel="libstdc++_link_flags
+ procedure">
+ <title>Libstdc++_link_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>libstdc++_link_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=getmultilibs xreflabel="get_multilibs procedure">
+ <title>Get_multilibs Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>get_multilibs</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=findbinutilsprog xreflabel="find_binutils_prog procedure">
+ <title>Find_binutils_prog Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>find_binutils_prog</function></funcdef>
+ <paramdef><parameter>name</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=findgcc xreflabel="find_gcc procedure">
+ <title>Find_gcc Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>find_gcc</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=findgcj xreflabel="find_gcj procedure">
+ <title>Find_gcj Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>find_gcj</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=findgxx xreflabel="find_g++ procedure">
+ <title>Find_g++ Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>find_g++</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=findg77 xreflabel="find_g77 procedure">
+ <title>Find_g77 Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>find_g77</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=processmultiliboptions xreflabel="process_multilib_options
+ procedure">
+ <title>Process_multilib_options Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>process_multilib_options</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=addmultiliboption xreflabel="add_multilib_option
+ procedure">
+ <title>Add_multilib_option Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>add_multilib_option</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=findgas xreflabel="find_gas procedure">
+ <title>Find_gas Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>find_gas</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=findld xreflabel="find_ld procedure">
+ <title>Find_ld Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>find_ld</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id=buildwrapper xreflabel="build_wrapper procedure">
+ <title>Build_wrapper Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>build_wrapper</function></funcdef>
+ <paramdef><parameter>gluefile</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>gluefile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=winsupincludeflags xreflabel="winsup_include_flags
+ procedure">
+ <title>Winsup_include_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>winsup_include_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=winsuplinkflags xreflabel="winsup_link_flags procedure">
+ <title>Winsup_link_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>winsup_link_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+ </sect2>
+
+ <sect2 id=debugprocs xreflabel="Debugging Procedures">
+ <title>Procedures for debugging your Tcl code.</title>
+
+ <para><filename>lib/debugger.exp</filename>defines these utility
+ procedures:</para>
+
+ <sect3 id=dumpvars xreflabel="dumpvars procedure">
+ <title>Dumpvars Procedure</title>
+
+ <para>This takes a csh style regular expression (glob rules) and prints
+ the values of the global variable names that match. It is abbreviated
+ as <emphasis>dv</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>dumpvars</function></funcdef>
+ <paramdef><parameter>vars</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>vars</parameter></term>
+ <listitem><para>The variables to dump.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=dumplocals xreflabel="dumplocals procedure">
+ <title>Dumplocals Procedure</title>
+
+ <para>This takes a csh style regular expression (glob rules) and
+ prints the values of the local variable names that match. It is
+ abbreviated as <emphasis>dl</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>dumplocals</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=dumprocs xreflabel="dumprocs procedure">
+ <title>Dumprocs Procedure</title>
+
+ <para>This takes a csh style regular expression (glob rules) and
+ prints the body of all procs that match. It is abbreviated as
+ <emphasis>dp</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>dumprocs</function></funcdef>
+ <paramdef><parameter>pattern</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>pattern</parameter></term>
+ <listitem><para>The csh "glob" style pattern to look
+ for.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=dumpwatch xreflabel="dumpwatch procedure">
+ <title>Dumpwatch Procedure</title>
+
+ <para>This takes a csh style regular expression (glob rules) and
+ prints all the watchpoints. It is abbreviated as
+ <emphasis>dw</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>dumpwatch</function></funcdef>
+ <paramdef><parameter>pattern</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>pattern</parameter></term>
+ <listitem><para>The csh "glob" style pattern to look
+ for.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=watcharray xreflabel="watcharray procedure">
+ <title>Watcharray Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>watcharray</function></funcdef>
+ <paramdef><parameter>element</parameter>
+ <parameter>type</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>type</parameter></term>
+ <listitem><para>The csh "glob" style pattern to look
+ for.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=watchvar xreflabel="watchvar procedure">
+ <title>Watchvar Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>watchvar</function></funcdef>
+ <paramdef><parameter>var</parameter>
+ <parameter>type</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=watchunset xreflabel="watchunset procedure">
+ <title>Watchunset Procedure</title>
+
+ <para>This breaks program execution when the variable
+ <symbol>var</symbol> is unset. It is abbreviated as
+ <emphasis>wu</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>watchunset</function></funcdef>
+ <paramdef><parameter>arg</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=watchwrite xreflabel="watchwrite procedure">
+ <title>Watchwrite Procedure</title>
+
+ <para>This breaks program execution when the variable
+ <symbol>var</symbol> is written. It is abbreviated as
+ <emphasis>ww</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>watchwrite</function></funcdef>
+ <paramdef><parameter>var</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>var</parameter></term>
+ <listitem><para>The variable to watch.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=watchread xreflabel="watchread procedure">
+ <title>Watchread Procedure</title>
+
+ <para>This breaks program execution when the variable
+ <symbol>var</symbol> is read. It is abbreviated as
+ <emphasis>wr</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>watchread</function></funcdef>
+ <paramdef><parameter>var</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>var</parameter></term>
+ <listitem><para>The variable to watch.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=watchdel xreflabel="watchdel procedure">
+ <title>Watchdel Procedure</title>
+
+ <para>This deletes a the watchpoint from the watch list. It is
+ abbreviated as <emphasis>wd</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>watchdel</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=print xreflabel="print procedure">
+ <title>Print Procedure</title>
+
+ <para>This prints the value of the variable
+ <parameter>var</parameter>. It is abbreviated as
+ <emphasis>p</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>print</function></funcdef>
+ <paramdef><parameter>var</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>var</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id=quit xreflabel="quit procedure">
+ <title>Quit Procedure</title>
+
+ <para>This makes runtest exit. It is abbreviated as
+ <emphasis>q</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcdef><function>quit</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id=filemap>
+ <title>File Map</title>
+
+ <para>This is a map of the files in DejaGnu.</para>
+
+ <itemizedlist>
+ <listitem><para>runtest</para></listitem>
+ <listitem><para>runtest.exp</para></listitem>
+ <listitem><para>stub-loader.c</para></listitem>
+ <listitem><para>testglue.c</para></listitem>
+ <listitem><para>config</para></listitem>
+ <listitem><para>baseboards</para></listitem>
+ <listitem><para>lib/debugger.exp</para></listitem>
+ <listitem><para>lib/dg.exp</para></listitem>
+ <listitem><para>lib/framework.exp</para></listitem>
+ <listitem><para>lib/ftp.exp</para></listitem>
+ <listitem><para>lib/kermit.exp</para></listitem>
+ <listitem><para>lib/libgloss.exp</para></listitem>
+ <listitem><para>lib/mondfe.exp</para></listitem>
+ <listitem><para>lib/remote.exp</para></listitem>
+ <listitem><para>lib/rlogin.exp</para></listitem>
+ <listitem><para>lib/rsh.exp</para></listitem>
+ <listitem><para>lib/standard.exp</para></listitem>
+ <listitem><para>lib/target.exp</para></listitem>
+ <listitem><para>lib/targetdb.exp</para></listitem>
+ <listitem><para>lib/telnet.exp</para></listitem>
+ <listitem><para>lib/tip.exp</para></listitem>
+ <listitem><para>lib/util-defs.exp</para></listitem>
+ <listitem><para>lib/utils.exp</para></listitem>
+ <listitem><para>lib/xsh.exp</para></listitem>
+ </itemizedlist>
+
+ </sect1>
+
+</chapter>
diff --git a/doc/runtest.1 b/doc/runtest.1
new file mode 100644
index 0000000..2c3a357
--- /dev/null
+++ b/doc/runtest.1
@@ -0,0 +1,119 @@
+.TH runtest 1 "08 Dec 1998"
+.SH NAME
+runtest \- the DejaGnu test driver program
+.SH SYNOPSIS
+.B runtest
+[ options ]
+.SH DESCRIPTION
+.I DejaGnu
+is a framework for running test suites on GNU tools. It is written in
+expect, which uses TCL (Tool command language).
+.B runtest
+is the test driver program; use it to control what tests to run,
+and variations on how to run them.
+
+You can find a comprehensive description of DejaGnu and \fBruntest\fR in
+.I
+The DejaGnu Testing Framework
+or its Info version,
+.BR dejagnu.info .
+.SH OPTIONS
+.TP
+.B --all
+Print all test output to screen. By default, only unexpected results are
+displayed.
+.TP
+.BI --baud \ rate
+Set the baud rate for a serial line connection. Some serial interface
+programs (like \fBtip\fR) don't use this value but instead use a separate
+initialization file.
+.TP
+.BI --connect \ type
+The type of connection to use. The choices are
+.BR rlogin ,
+.BR telnet ,
+.BR rsh ,
+.BR kermit ,
+.BR tip
+and
+.BR mondfe .
+.TP
+.B --debug
+Turn on
+.B expect
+internal debugging output. All output is logged to
+a file called \fBdbg.out\fR.
+The output of the \fB--strace\fR also goes into this file.
+.TP
+.B --help
+Prints out a help screen and then exits.
+.TP
+.BI --host \ type
+The configuration string for the host.
+.TP
+.BI --ignore \ test1.exp\ test2.exp\ ...
+Do not run the specified tests.
+.BI --mail \ \'name1\ name2\ ...\'
+Electronic mail addresses to receive test results.
+.TP
+.BI --name \ hostname
+The network hostname of the target board.
+.TP
+.BI --objdir \ path
+\fIpath\fR is a directory containing compiled test code.
+.TP
+.BI --outdir \ directory
+The name of a directory for test log output.
+.TP
+.B --reboot
+Reboot the target board when \fBruntest\fR initializes
+(if supported).
+.TP
+.BI --srcdir \ path
+\fIpath\fR is a directory containing test directories.
+.TP
+.BI --strace \ N
+Turns on
+.B expect
+internal tracing to \fIN\fR levels deep.
+.TP
+.BI --target \ type
+The configuration string for the target.
+.TP
+.BI --tool \ toolname
+Specify the tool to be tested. \fItoolname\fR controls the test suite
+applied, and the associated initialization module.
+.TP
+.B --verbose,\ -v
+Turns on more debugging output from test cases and DejaGnu utility code.
+Use more than once to increase output further.
+.TP
+.B --version,\ -V
+Prints out the versions of DejaGnu, expect and Tcl.
+.TP
+.B -D[number]
+Activate the Tcl debugger.\fBnumber\fR can be either 1 or 0. If it is
+1, then the expect shell will break when it starts to run. All ^C's
+drop DejaGnu back to the debugger prompt. A 0 starts DejaGnu like
+normal, but a ^C drops to the debugger prompt.
+.TP 0
+Any file name on the command line is assumed to be a subset
+of the test names to run. Usually these are the names of the
+expect test driver, ie... special.exp.
+
+Makefile style variables are used to specify tool names and their
+flags; these and other configuration dependent values are saved in the
+file \fBsite.exp\fR, created during configuration.
+.SH EXIT CODES
+.B runtest
+sets the exit code to 1 if any of the tests failed, or
+sets it to 0 if all the tests passed.
+.SH SEE ALSO
+.I The DejaGnu Testing Framework
+.RB ( dejagnu.info ).
+This is the DejaGnu manual; its source is the SGML files
+.B
+doc/*.sgml.
+in the DejaGnu distribution.
+.SH AUTHOR
+Rob Savoye (rob@welcomehome.org)
diff --git a/doc/user.sgml b/doc/user.sgml
new file mode 100644
index 0000000..2154d74
--- /dev/null
+++ b/doc/user.sgml
@@ -0,0 +1,2355 @@
+ <chapter id=runningtests>
+ <title>Running Tests</title>
+
+ <para>There are two ways to execute a test suite. The most
+ common way is when there is existing support in the
+ <filename>Makefile</filename>. This support consists of a
+ <emphasis>check</emphasis> target. The other way is to execute the
+ <command>runtest</command> program directly. To run
+ <command>runtest</command> directcly from the command line requires
+ either all the correct options, or the <xref linkend=local> must be setup
+ correctly.</para>
+
+ <sect1 id=makecheck xreflabel="Make Check">
+ <title>Make check</title>
+
+ <para>To run tests from an existing collection, first use
+ <command>configure</command> as usual to set up the
+ build directory. Then try typing:</para>
+
+ <screen>
+ make check
+ </screen>
+
+ <para>If the <emphasis>check</emphasis> 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
+ <emphasis>site.exp</emphasis>. 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.</para>
+
+ <para>The <emphasis>check</emphasis> target is supported by GNU
+ <productname>Automake</productname>. To have DejaGnu support added to your
+ generated <filename>Makefile.in</filename>, just add the keyword
+ dejagnu to the AUTOMAKE_OPTIONS variable in your
+ <filename>Makefile.am</filename> file.</para>
+
+ <para>Once you have run <emphasis>make check</emphasis> to build
+ any auxiliary files, you can invoke the test driver
+ <command>runtest</command> directly to repeat the tests.
+ You will also have to execute <command>runtest</command>
+ directly for test collections with no
+ <emphasis>check</emphasis> target in the
+ <filename>Makefile</filename>.</para>
+
+ </sect1>
+
+ <sect1 id=runtest xreflabel="Runtest">
+ <title>Runtest</title>
+
+ <para><command>runtest</command> is the executable test driver
+ for DejaGnu. You can specify two kinds of things on the
+ <command>runtest</command> command line: command line options,
+ and Tcl variables for the test scripts. The options are listed
+ alphabetically below.</para>
+
+ <para><command>runtest</command> returns an exit code of
+ <emphasis>1</emphasis> if any test has an unexpected result; otherwise
+ (if all tests pass or fail as expected) it returns <emphasis>0</emphasis>
+ as the exit code.</para>
+
+ <sect2 id=outputs xreflabel="Output States">
+ <title>Output States</title>
+
+ <para><filename>runtest</filename> flags the outcome of each
+ test as one of these cases. <xref linkend=posix> for a
+ discussion of how POSIX specifies the meanings of these
+ cases.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>PASS</term>
+ <listitem><para>The most desirable outcome: the test succeeded, and
+ was expected to succeed.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>XPASS</term>
+ <listitem><para>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.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>FAIL</term>
+ <listitem><para>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.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>XFAIL</term>
+ <listitem><para>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 <emphasis>UNSUPPORTED</emphasis>
+ instead.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>UNRESOLVED</term>
+ <listitem><para>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.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>UNTESTED</term>
+ <listitem><para>A test case is not yet complete, and in particular
+ cannot yet produce a <emphasis>PASS</emphasis> or
+ <emphasis>FAIL</emphasis>. You can also use this outcome in dummy
+ ``tests'' that note explicitly the absence of a real test case for a
+ particular property.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>UNSUPPORTED</term>
+ <listitem><para>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.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>runtest may also display the following messages:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>ERROR</term>
+ <listitem><para>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
+ test suites should not emit this message; use
+ <emphasis>UNSUPPORTED</emphasis>, <emphasis>UNTESTED</emphasis>, or
+ <emphasis>UNRESOLVED</emphasis> instead, as
+ appropriate.)</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>WARNING</term>
+ <listitem><para>Indicates a possible problem in running the
+ test. Usually warnings correspond to recoverable errors, or display
+ an important message about the following tests.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>NOTE</term>
+ <listitem><para>An informational message about the test
+ case.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+ <sect2 id=invoking xreflabel="Invoking Runtest">
+ <title>Invoking Runtest</title>
+
+ <para>This is the full set of command line options that
+ <filename>runtest</filename> recognizes. Arguments may be
+ abbreviated to the shortest unique string.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--all</option> (-a)</term>
+ <listitem><para>Display all test output. By default,
+ <emphasis>runtest</emphasis> shows only the output of tests that
+ produce unexpected results; that is, tests with status
+ <emphasis>FAIL</emphasis> (unexpected failure),
+ <emphasis>XPASS</emphasis> (unexpected success), or
+ <emphasis>ERROR</emphasis> (a severe error in the test case
+ itself). Specify <emphasis>--all</emphasis> to see output for tests
+ with status <emphasis>PASS</emphasis> (success, as expected)
+ <emphasis>XFAIL</emphasis> (failure, as expected), or
+ <emphasis>WARNING</emphasis> (minor error in the test case
+ itself).</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--build [string]</option></term>
+ <listitem><para><emphasis>string</emphasis> is a full configuration
+ ``triple'' name as used by <command>configure</command>. 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.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--host [string]</option></term>
+ <listitem><para><symbol>string</symbol> is a full configuration
+ ``triple'' name as used by <emphasis>configure</emphasis>. 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 <emphasis>only</emphasis> DejaGnu procedures that compare the
+ host string with particular values. The procedures
+ <emphasis>ishost</emphasis>, <emphasis>istarget</emphasis>,
+ <emphasis>isnative</emphasis>, and <emphasis>setup</emphasis>xfail}
+ are affected by <emphasis>--host</emphasis>. In this usage,
+ <emphasis>host</emphasis> refers to the machine that the tests are to
+ be run on, which may not be the same as the
+ <emphasis>build</emphasis> machine. If <emphasis>--build</emphasis>
+ is also specified, then <emphasis>--host</emphasis> refers to the
+ machine that the tests wil, be run on, not the machine DejaGnu is run
+ on.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--host_board [name]</option></term>
+ <listitem><para>The host board to use.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--target [string]</option></term>
+ <listitem><para>Use this option to override the default setting
+ (running native tests). <emphasis>string</emphasis> is a full
+ configuration ``triple'' name of the form
+ <emphasis>cpu-vendor-os</emphasis> as used by
+ <command>configure</command>. This option changes the
+ configuration <emphasis>runtest</emphasis> uses for the default tool
+ names, and other setup information.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--debug</option> (-de)</term>
+ <listitem><para>Turns on the <emphasis>expect</emphasis> internal
+ debugging output. Debugging output is displayed as part of the
+ <emphasis>runtest</emphasis> output, and logged to a file called
+ <filename>dbg.log</filename>. The extra debugging output does
+ <emphasis>not</emphasis> appear on standard output, unless the
+ verbose level is greater than 2 (for instance, to see debug output
+ immediately, specify <emphasis>--debug</emphasis>-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 <emphasis>--strace</emphasis> also goes into
+ <filename>dbg.log</filename>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--help</option> (-he)</term>
+ <listitem><para>Prints out a short summary of the
+ <emphasis>runtest</emphasis> options, then exits (even if you also
+ specify other options).</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--ignore [name(s)] </option></term>
+ <listitem><para>The names of specific tests to
+ ignore.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--objdir [path]</option></term>
+ <listitem><para>Use <emphasis>path</emphasis> as the top directory
+ containing any auxiliary compiled test code. This defaults to
+ <filename>.</filename>. Use this option to locate pre-compiled test
+ code. You can normally prepare any auxiliary files needed with
+ <emphasis>make</emphasis>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--outdir [path]</option></term>
+ <listitem><para>Write output logs in directory
+ <filename>path</filename>. The default is <emphasis>.},
+ the</emphasis> directory where you start
+ <emphasis>runtest</emphasis>. This option affects only the summary
+ and the detailed log files
+ <filename>tool.sum</filename> and
+ <filename>tool.log</filename>. The DejaGnu debug
+ log <filename>dbg.log</filename> always appears (when requested) in
+ the local directory.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--reboot [name]</option></term>
+ <listitem><para>Reboot the target board when
+ <emphasis>runtest</emphasis> 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.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--srcdir [path]</option></term>
+ <listitem><para>Use <filename>path</filename> as the top directory
+ for test scripts to run. <emphasis>runtest</emphasis> looks in this
+ directory for any subdirectory whose name begins with the toolname
+ (specified with <emphasis>--tool</emphasis>). For instance, with
+ <emphasis>--tool</emphasis>gdb}, <emphasis>runtest</emphasis> uses
+ tests in subdirectories <filename>gdb.*</filename> (with the usual
+ shell-like filename expansion). If you do not use
+ <emphasis>--srcdir</emphasis>, <emphasis>runtest</emphasis> looks for
+ test directories under the current working
+ directory.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--strace [number]</option></term>
+ <listitem><para>Turn on internal tracing for
+ <emphasis>expect</emphasis>, 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
+ <emphasis>case</emphasis> or <emphasis>if</emphasis> statements.
+ Each procedure call or control structure counts as one ``level''. The
+ output is recorded in the same file, <filename>dbg.log</filename>,
+ used for output from <emphasis>--debug</emphasis>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--connect [program]</option></term>
+ <listitem><para>Connect to a target testing environment as specified
+ by <emphasis>type</emphasis>, if the target is not the computer
+ running <emphasis>runtest</emphasis>. For example, use
+ <emphasis>--connect</emphasis> to change the program used to connect
+ to a ``bare board'' boot monitor. The choices for
+ <emphasis>type</emphasis> in the DejaGnu 1.4 distribution are
+ <emphasis>rlogin</emphasis>, <emphasis>telnet</emphasis>,
+ <emphasis>rsh</emphasis>, <emphasis>tip</emphasis>,
+ <emphasis>kermit</emphasis>, and <emphasis>mondfe</emphasis>.</para>
+
+ <para>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.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--baud [number]</option></term>
+ <listitem><para>Set the default baud rate to something other than
+ 9600. (Some serial interface programs, like <emphasis>tip</emphasis>,
+ use a separate initialization file instead of this
+ value.)</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--target_board [name(s)]</option></term>
+ <listitem><para>The list of target boards to run tests
+ on.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id=tool-opt>
+ <term><option>--tool[name(s)]</option></term>
+ <listitem><para>Specifies which test suite to run, and what
+ initialization module to use. <option>--tool</option> is used
+ <emphasis>only</emphasis> for these two purposes. It is
+ <emphasis>not</emphasis> used to name the executable program to
+ test. Executable tool names (and paths) are recorded in
+ <filename>site.exp</filename> and you can override them by specifying
+ Tcl variables on the command line.</para>
+
+ <para>For example, including "<option>--tool</option> gcc" on the
+ <emphasis>runtest</emphasis> command line runs tests from all test
+ subdirectories whose names match <filename>gcc.*</filename>, and uses
+ one of the initialization modules named
+ <filename>config/*-gcc.exp</filename>. To specify the name of the
+ compiler (perhaps as an alternative path to what
+ <emphasis>runtest</emphasis> would use by default), use
+ <emphasis>GCC=binname</emphasis> on the <emphasis>runtest</emphasis>
+ command line.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--tool_exec [name]</option></term>
+ <listitem><para>The path to the tool executable to
+ test.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--tool_opts [options]</option></term>
+ <listitem><para>A list of additional options to pass to the
+ tool.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--verbose</option> (-v)</term>
+ <listitem><para>Turns on more output. Repeating this option increases
+ the amount of output displayed. Level one (<emphasis>-v</emphasis>)
+ is simply test output. Level two (<emphasis>-v</emphasis>-v}) shows
+ messages on options, configuration, and process control. Verbose
+ messages appear in the detailed (<filename>*.log</filename>) log
+ file, but not in the summary (<filename>*.sum</filename>) log
+ file.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--version</option> (-V)</term>
+ <listitem><para>Prints out the version numbers of DejaGnu,
+ <emphasis>expect</emphasis> and Tcl, and exits without running any
+ tests.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--D[0-1]</option></term>
+ <listitem><para>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
+ <emphasis>expect</emphasis> as the file
+ <filename>expect/tcl-debug.ps.</filename>. If you specify
+ <emphasis>-D1</emphasis>, the <emphasis>expect</emphasis> shell stops
+ at a breakpoint as soon as DejaGnu invokes it. If you specify
+ <emphasis>-D0</emphasis>, DejaGnu starts as usual, but you can enter
+ the debugger by sending an interrupt (e.g. by typing
+ <keycombo><keycap>C</keycap><keycap>c</keycap></keycombo>).
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>testfile</filename>.exp[=arg(s)]</term>
+ <listitem><para>Specify the names of testsuites to run. By default,
+ <emphasis>runtest</emphasis> runs all tests for the tool, but you can
+ restrict it to particular testsuites by giving the names of the
+ <emphasis>.exp expect</emphasis> scripts that control
+ them. <emphasis>testsuite</emphasis>.exp may not include path
+ information; use plain filenames.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>testfile</filename>.exp="testfile1 ..."</term>
+ <listitem><para>Specify a subset of tests in a suite to run. For
+ compiler or assembler tests, which often use a single
+ <emphasis>.exp</emphasis> 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 <emphasis>?</emphasis>, <emphasis>*</emphasis>,
+ and <emphasis>[chars]</emphasis>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><symbol>tclvar</symbol>=value</term>
+ <listitem><para>You can define Tcl variables for use by your test
+ scripts in the same style used with <emphasis>make</emphasis> for
+ environment variables. For example, <emphasis>runtest
+ GDB=gdb.old</emphasis> defines a variable called
+ <command>GDB</command>; when your scripts refer to
+ <symbol>$GDB</symbol> in this run, they use the value
+ <emphasis>gdb.old</emphasis>.</para>
+
+ <para>The default Tcl variables used for most tools are defined in
+ the main DejaGnu <emphasis>Makefile</emphasis>; their values are
+ captured in the <filename>site.exp</filename> file.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id=common xreflabel="Common Operations">
+ <title>Common Options</title>
+
+ <para>Typically, you don't need must to use any command-line options.
+ <option>--tool</option> used is only required when there are more than
+ one test suite in the same directory. The default options are in the
+ local site.exp file, created by "make site.exp".</para>
+
+ <para>For example, if the directory <filename>gdb/testsuite</filename>
+ contains a collection of DejaGnu tests for GDB, you can run them like
+ this:</para>
+
+ <screen>
+ eg$ cd gdb/testsuite
+ eg$ runtest --tool gdb
+ </screen>
+
+ <para>Test output follows, ending with:</para>
+
+ <screen>
+ === gdb Summary ===
+
+ # of expected passes 508
+ # of expected failures 103
+ /usr/latest/bin/gdb version 4.14.4 -nx
+ </screen>
+
+ <para>You can use the option <emphasis>--srcdir</emphasis> to point to
+ some other directory containing a collection of tests:</para>
+
+ <screen>
+ eg$ runtest--srcdir /devo/gdb/testsuite
+ </screen>
+
+ <para>By default, <command>runtest</command> 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 <emphasis>--all</emphasis> option. For more
+ verbose output about processes being run, communication, and so on, use
+ <emphasis>--verbose</emphasis>. To see even more output, use multiple
+ <emphasis>--verbose</emphasis> options. for a more detailed explanation
+ of each <command>runtest</command> option.
+
+ <para>Test output goes into two files in your current directory:
+ summary output in <filename>tool.sum</filename>,
+ and detailed output in <filename>
+ tool.log</filename>. (<emphasis>tool</emphasis>
+ refers to the collection of tests; for example, after a run with
+ <emphasis>--tool</emphasis> gdb, look for output files
+ <filename>gdb.sum</filename> and <filename>gdb.log</filename>.)
+ </sect2>
+ </sect1>
+
+ <sect1 id=outputfiles xreflabel="Output Files">
+
+ <title>The files DejaGnu produces.</title>
+
+ <para>DejaGnu always writes two kinds of output files: summary
+ logs and detailed logs. The contents of both of these are
+ determined by your tests.</para>
+
+ <para>For troubleshooting, a third kind of output file is useful:
+ use <option>--debug</option> to request an output file showing
+ details of what <productname>Expect</productname> is doing
+ internally.</para>
+
+ <sect2 id=sum xreflabel="Summary File">
+ <title>Summary File</title>
+
+ <para>DejaGnu always produces a summary output file
+ <filename>tool.sum</filename>. This summary shows the names of
+ all test files run; for each test file, one line of output from
+ each <command>pass</command> command (showing status
+ <emphasis>PASS</emphasis> or <emphasis>XPASS</emphasis>) or
+ <command>fail</command> command (status
+ <emphasis>FAIL</emphasis> or <emphasis>XFAIL</emphasis>);
+ 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 <option>--all</option>.)
+
+ <para>If any of your tests use the procedures
+ <command>unresolved</command>, <command>unsupported</command>,
+ or <command>runtested</command>, the summary output also
+ tabulates the corresponding outcomes.</para>
+
+ <para>For example, after <command>runtest --tool
+ binutils</command>, look for a summary log in
+ <filename>binutils.sum</filename>. Normally, DejaGnu writes this
+ file in your current working directory; use the
+ <option>--outdir</option> option to select a different
+ directory.</para>
+
+ <example>
+ <title>Here is a short sample summary log</title>
+
+ <screen>
+ 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
+ </screen>
+ </example>
+
+ </sect2>
+
+ <sect2 id=log xreflabel="Log File">
+ <title>Log File</title>
+
+ <para>DejaGnu also saves a detailed log file
+ <filename>tool.log</filename>, showing any output generated by
+ tests as well as the summary output. For example, after
+ <command>runtest --tool binutils</command>, look for a detailed
+ log in <filename>binutils.log</filename>. Normally, DejaGnu
+ writes this file in your current working directory; use the
+ <option>--outdir</option> option to select a different
+ directory.</para>
+
+
+ <example>
+ <title>Here is a brief example showing a detailed log for
+ <productname>G++</productname> tests</title>
+
+ <screen>
+ 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
+ </screen>
+ </example>
+
+ </sect2>
+
+ <sect2 id=debugfile xreflabel="Debug Log File">
+ <title>Debug Log File</title>
+
+ <para>With the <option>--debug</option> option, you can request
+ a log file showing the output from
+ <productname>Expect</productname> itself, running in debugging
+ mode. This file (<filename>dbg.log</filename>, in the directory
+ where you start <command>runtest</command>) shows each pattern
+ <productname>Expect</productname> considers in analyzing test
+ output.</para>
+
+ <para>This file reflects each <command>send</command> command,
+ showing the string sent as input to the tool under test; and
+ each <productname>Expect</productname> command, showing each
+ pattern it compares with the tool output.</para>
+
+ <example>
+ <title>The log messages begin with a message of the form</title>
+
+ <screen>
+
+ expect: does {<symbol>tool output</symbol>} (spawn_id <symbol>n</symbol>)
+ match pattern {<emphasis>expected pattern</emphasis>}?
+
+ </screen>
+ </example>
+
+ <para>For every unsuccessful match,
+ <productname>Expect</productname> issues a
+ <emphasis>no</emphasis> after this message; if other patterns
+ are specified for the same <productname>Expect</productname>
+ command, they are reflected also, but without the first part of
+ the message (<emphasis>expect... match pattern</emphasis>).</para>
+
+ <para>When <productname>Expect</productname> finds a match, the
+ log for the successful match ends with <emphasis>yes</emphasis>,
+ followed by a record of the <productname>Expect</productname>
+ variables set to describe a successful match.</para>
+
+ <example>
+ <title>Here is an excerpt from the debugging log for a
+ <productname>GDB</productname> test:</title>
+
+ <screen>
+ 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
+ </screen>
+ </example>
+
+ <para>This example exhibits three properties of
+ <productname>Expect</productname> and
+ <productname>DejaGnu</productname> that might be surprising at
+ first glance:</para>
+
+ <itemizedlist mark="bullet">
+ <listitem><para>Empty output for the first attempted match. The
+ first set of attempted matches shown ran against the output
+ <emphasis>{}</emphasis> --- that is, no
+ output. <productname>Expect</productname> 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).</para></listitem>
+
+ <listitem><para>Interspersed tool output. The beginning of
+ the log entry for the second attempted match may be hard to
+ spot: this is because the prompt <emphasis>{(gdb) }</emphasis>
+ appears on the same line, just before the
+ <emphasis>expect:</emphasis> that marks the beginning of the
+ log entry.</para></listitem>
+
+ <listitem><para>Fail-safe patterns. Many of the patterns
+ tested are fail-safe patterns provided by
+ <productname>GDB</productname> testing utilities, to reduce
+ possible indeterminacy. It is useful to anticipate potential
+ variations caused by extreme system conditions
+ (<productname>GDB</productname> might issue the message
+ <emphasis>virtual memory exhausted</emphasis> in rare
+ circumstances), or by changes in the tested program
+ (<emphasis>Undefined command</emphasis> is the likeliest
+ outcome if the name of a tested command changes).</para>
+
+ <para>The pattern <emphasis>{return}</emphasis> is a
+ particularly interesting fail-safe to notice; it checks for an
+ unexpected <keycap>RET</keycap> prompt. This may happen,
+ for example, if the tested tool can filter output through a
+ pager.</para>
+
+ <para>These fail-safe patterns (like the debugging log itself)
+ are primarily useful while developing test scripts. Use the
+ <command>error</command> procedure to make the actions for
+ fail-safe patterns produce messages starting with
+ <emphasis>ERROR</emphasis> on standard output, and in the
+ detailed log file.</para></listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+ </chapter>
+
+ <chapter id=Customizing xreflabel="Customizing DejaGnu">
+ <title>Customizing DejaGnu</title>
+
+ <para>The site configuration file, <filename>site.exp</filename>,
+ captures configuration-dependent values and propagates them to the
+ DejaGnu test environment using Tcl variables. This ties the
+ DejaGnu test scripts into the <command>configure</command> and
+ <command>make</command> programs. If this file is setup correctly,
+ it is possible to execute a test suite merely by typing
+ <command>runtest</command>.</para>
+
+ <para>DejaGnu supports two <filename>site.exp</filename>
+ files. The multiple instances of <filename>site.exp</filename> are
+ loaded in a fixed order built into DejaGnu. The first file loaded
+ is the local file <filename>site.exp</filename>, and then the
+ optional global <filename>site.exp</filename> file as
+ pointed to by the <symbol>DEJAGNU</symbol> environment
+ variable.</para>
+
+ <para>There is an optional <emphasis>master</emphasis>
+ <filename>site.exp</filename>, capturing configuration values that
+ apply to DejaGnu across the board, in each configuration-specific
+ subdirectory of the DejaGnu library directory.
+ <command>runtest</command> loads these values first. The master
+ <filename>site.exp</filename> contains the default values for all
+ targets and hosts supported by DejaGnu. This master file is
+ identified by setting the environment variable
+ <symbol>DEJAGNU</symbol> to the name of the file. This is also
+ refered to as the ``global'' config file.</para>
+
+ <para>Any directory containing a configured test suite also has a
+ local <filename>site.exp</filename>, capturing configuration values
+ specific to the tool under test. Since <command>runtest</command>
+ loads these values last, the individual test configuration can
+ either rely on and use, or override, any of the global values from
+ the global <filename>site.exp</filename> file.</para>
+
+ <para>You can usually generate or update the testsuite's local
+ <filename>site.exp</filename> by typing <command>make
+ site.exp</command> in the test suite directory, after the test
+ suite is configured.</para>
+
+ <para>You can also have a file in your home directory called
+ <filename>.dejagnurc</filename>. This gets loaded first before the
+ other config files. Usually this is used for personal stuff, like
+ setting the <symbol>all_flag</symbol> so all the output gets
+ printed, or your own verbosity levels. This file is usually
+ restricted to setting command line options.</para>
+
+ <para>You can further override the default values in a
+ user-editable section of any <filename>site.exp</filename>, or by
+ setting variables on the <command>runtest</command> command
+ line.</para>
+
+ <sect1 id=local xreflabel="Local Config File">
+ <title>Local Config File</title>
+
+ <para>It is usually more convenient to keep these <emphasis>manual
+ overrides</emphasis> in the <filename>site.exp</filename>
+ local to each test directory, rather than in the global
+ <filename>site.exp</filename> in the installed DejaGnu
+ library. This file is mostly for supplying tool specific info
+ that is required by the test suite.</para>
+
+ <para>All local <filename>site.exp</filename> files have
+ two sections, separated by comment text. The first section is
+ the part that is generated by <command>make</command>. It is
+ essentially a collection of Tcl variable definitions based on
+ <filename>Makefile</filename> environment variables. Since they
+ are generated by <command>make</command>, they contain the
+ values as specified by <command>configure</command>. (You can
+ also customize these values by using the <option>--site</option>
+ option to <command>configure</command>.) In particular, this
+ section contains the <filename>Makefile</filename>
+ variables for host and target configuration data. Do not edit
+ this first section; if you do, your changes are replaced next
+ time you run <command>make</command>.</para>
+
+ <example>
+ <title>The first section starts with</title>
+
+ <programlisting>
+ ## these variables are automatically generated by make ##
+ # Do not edit here. If you wish to override these values
+ # add them to the last section
+ </programlisting>
+ </example>
+
+ <para>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 <command>runtest</command>. This allows you to
+ easily customize <command>runtest</command> 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.)</para>
+
+ <example>
+ <title>The first section ends with this line</title>
+
+ <programlisting>
+ ## All variables above are generated by configure. Do Not Edit ##
+ </programlisting>
+ </example>
+
+ <para>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
+ <symbol>host_triplet</symbol>, <symbol>build_triplet</symbol>,
+ <symbol>target_triplet</symbol>. All other variables are tool
+ dependant. ie for testing a compiler, the value for
+ <symbol>CC</symbol> might be set to a freshly built binary, as
+ opposed to one in the user's path.</para>
+
+ <para>Here's an example local site.exp file, as used for
+ <productname>GCC/G++</productname> testing.</para>
+
+ <example>
+ <title>Local Config File</title>
+
+ <programlisting>
+ ## 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 "-I/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libio -I$srcdir/../libg++/src -I$srcdir/../libio -I$srcdir/../libstdc++ -I$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 ##
+
+ </programlisting>
+ </example>
+
+ <para>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 test suite. 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.</para>
+
+ </sect1>
+ <sect1 id=global xreflabel="Global Config File">
+ <title>Global Config File</title>
+
+ <para>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
+ <emphasis>canadian cross</emphasis>. 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.</para>
+
+ <para>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.</para>
+
+ <example>
+ <title>Global Config file</title>
+
+ <programlisting>
+
+ # 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" }
+ }
+ }
+ </programlisting>
+ </example>
+
+ <para>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.</para>
+
+ <para>As you can see, all one does is set the variable
+ <symbol>target_list</symbol> to the list of targets and options to
+ test. The simple settings, like for
+ <emphasis>sparc64-elf</emphasis> only require setting the name of
+ the single board config file. The <emphasis>mips-elf</emphasis>
+ target is more complicated. Here it sets the list to three target
+ boards. One is the default mips target, and both
+ <emphasis>wilma</emphasis> <emphasis>barney</emphasis> are
+ symbolic names for other mips boards. Symbolic names are covered
+ in the <xref linkend=addboard> chapter. The more complicated
+ example is the one for <emphasis>mips-lsi-elf</emphasis>. This one
+ runs the tests with multiple iterations using all possible
+ combinations of the <option>--soft-float</option> and the
+ <option>--el</option> (little endian) option. Needless to say,
+ this last feature is mostly compiler specific.</para>
+
+ </sect1>
+
+ <sect1 id=boardconfig xreflabel="Board Config File">
+ <title>Board Config File</title>
+
+ <para>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 <xref
+ linkend=addboard> chapter. </para>
+
+ <para>An example board config file for a GNU simulator is as
+ follows. <function>set_board_info</function> is a procedure that sets the
+ field name to the specified value. The procedures in square brackets
+ <emphasis>[]</emphasis> are <emphasis>helper procedures</emphasis>. 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.</para>
+
+ <example>
+ <title>Board Config File</title>
+
+ <programlisting>
+ # 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
+ </programlisting>
+ </example>
+
+ <para>There are five helper procedures used in this example. The first
+ one, <function>find gcc</function> 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
+ <function>libgloss_include_flags</function> &
+ <function>libgloss_link_flags</function>. These return the proper flags to
+ compiler and link an executable image using <xref
+ linkend=libgloss>, the GNU BSP (Board Support Package). The final
+ procedures are <function>newlib_include_flag</function> &
+ <function>newlib_include_flag</function>. These find the Newlib C
+ library, which is a reentrant standard C library for embedded systems
+ comprising of non GPL'd code.</para>
+
+ </sect1>
+
+ <sect1 id=releng xreflabel="Remote Host Testing">
+ <title>Remote Host Testing</title>
+
+ <note><para>Thanks to Dj Delorie for the original paper that
+ this section is based on.</para></note>
+
+ <para>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/Win3.1, MacOS, and
+ win95/win98/NT.</para>
+
+ <para>The recommended source for a win95/win98/NT based ftp
+ server is to get IIS (either IIS 1 or Personal Web Server) from
+ <ulink
+ URL="http://www.microsoft.com">http://www.microsoft.com</ulink>.
+ 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.</para>
+
+ <para>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.</para>
+
+ <para>You'll also need a telnet server. For win95/win98/NT, go
+ to the <ulink URL="http://ataman.com">Ataman</ulink> 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.</para>
+
+ <para>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.</para>
+
+ <para>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:</para>
+
+ <example>
+ <title>Remote host setup</title>
+
+ <screen>
+ 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
+
+ </screen>
+ </example>
+
+ <para>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.</para>
+
+ <para>Edit the global <filename> site.exp</filename> to reflect your
+ boards directory:</para>
+
+ <example>
+ <title>Add The Board Directory</title>
+
+ <programlisting>
+ lappend boards_dir "/usr/local/swamp/testing/boards"
+ </programlisting>
+ </example>
+
+ <para>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:</para>
+
+ <example>
+ <title>Setup Cross Remote Testing</title>
+
+ <programlisting>
+ ./MkTestDir sh-hms /usr/dejagnu/src/devo
+ </programlisting>
+ </example>
+
+ <para>If you are testing a native PC compiler (ex: you have
+ gcc.exe in your PATH on the PC), do this:
+
+ <example>
+ <title>Setup Native Remote Testing</title>
+
+ <programlisting>
+ ./MkTestDir '' /usr/dejagnu/src/devo
+ </programlisting>
+ </example>
+
+ <para>To test the setup, <command>ftp</command> 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.</para>
+
+ <example>
+ <title>Run Test Remotely</title>
+
+ <programlisting>
+ cd /usr/local/swamp/testing
+ make -k -w check RUNTESTFLAGS="--host_board foobar --target_board foobar -v -v" > check.out 2>&1
+ </programlisting>
+ </example>
+
+ <para>To run a specific test, use a command like this (for
+ this example, you'd run this from the gcc directory that
+ MkTestDir created):</para>
+
+ <example>
+ <title>Run a Test Remotely</title>
+
+ <programlisting>
+ make check RUNTESTFLAGS="--host_board sloth --target_board sloth -v compile.exp=921202-1.c"
+ </programlisting>
+ </example>
+
+ <para>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.</para>
+
+ </sect1>
+
+ <sect1 id=configfile xreflabel="Config File Values">
+ <title>Config File Values</title>
+
+ <para>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 <symbol>target_info</symbol>, and it has two indices. The
+ following fields are part of the array.</para>
+
+ <sect1 id=optiondefs xreflabel="Option Variables">
+ <title>Command Line Option Variables</title>
+
+ <para>In the user editable second section of the <xref
+ linkend=personal> you can not only override the configuration
+ variables captured in the first section, but also specify
+ default values for all on the <command>runtest</command>
+ command line options. Save for <option>--debug</option>,
+ <option>--help</option>, and <option>--version</option>, each
+ command line option has an associated Tcl variable. Use the
+ Tcl <command>set</command> 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
+ <filename>site.exp</filename>. <xref linkend=invoking>, for
+ explanations of the command-line options.</para>
+
+ <para><table frame=all rowsep=0 colsep=0>
+ <title>Tcl Variables For Command Line Options</title>
+
+ <tgroup cols=3 align="char" rowsep=1 colsep=0>
+ <thead><row>
+ <entry>runtest</entry><entry>Tcl</entry>
+ <entry>option</entry><entry>variable</entry><entry>description</entry>
+ </row></thead>
+ <tbody>
+
+ <row>
+ <entry>--all</entry>
+ <entry>all_flag</entry>
+ <entry>display all test results if set</entry>
+ </row>
+
+ <row>
+ <entry>--baud</entry>
+ <entry>baud</entry>
+ <entry>set the default baud rate to something other than
+ 9600.</entry>
+ </row>
+
+ <row>
+ <entry>--connect</entry>
+ <entry>connectmode</entry>
+ <entry><command>rlogin</command>,
+ <command>telnet</command>, <command>rsh</command>,
+ <command>kermit</command>, <command>tip</command>, or
+ <command>mondfe</command></entry>
+ </row>
+
+ <row>
+ <entry>--outdir</entry>
+ <entry>outdir</entry>
+ <entry>directory for <filename>tool.sum</filename> and
+ <filename>tool.log.</filename></entry>
+ </row>
+
+ <row>
+ <entry>--objdir</entry>
+ <entry>objdir</entry>
+ <entry>directory for pre-compiled binaries</entry>
+ </row>
+
+ <row>
+ <entry>--reboot</entry>
+ <entry>reboot</entry>
+ <entry>reboot the target if set to
+ <emphasis>"1"</emphasis>; do not reboot if set to
+ <emphasis>"0"</emphasis> (the default).</entry>
+ </row>
+
+ <row>
+ <entry>--srcdir</entry>
+ <entry>srcdir</entry>
+ <entry>directory of test subdirectories</entry>
+ </row>
+
+ <row>
+ <entry>--strace</entry>
+ <entry>tracelevel</entry>
+ <entry>a number: Tcl trace depth</entry>
+ </row>
+
+ <row>
+ <entry>--tool</entry>
+ <entry>tool</entry>
+ <entry>name of tool to test; identifies init, test subdir</entry>
+ </row>
+
+ <row>
+ <entry>--verbose</entry>
+ <entry>verbose</entry>
+ <entry>verbosity level. As option, use multiple times; as
+ variable, set a number, 0 or greater.</entry>
+ </row>
+
+ <row>
+ <entry>--target</entry>
+ <entry>target_triplet</entry>
+ <entry>The canonical configuration string for the target.</entry>
+ </row>
+
+ <row>
+ <entry>--host</entry>
+ <entry>host_triplet</entry>
+ <entry>The canonical configuration string for the host.</entry>
+ </row>
+
+ <row>
+ <entry>--build</entry>
+ <entry>build_triplet</entry>
+ <entry>The canonical configuration string for the build
+ host.</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ </sect1>
+
+ <sect1 id=personal xreflabel="Personal Config File">
+ <title>Personal Config File</title>
+
+ <para>The personal config file is used to customize
+ <command>runtest's</command> behaviour for each person. It's
+ typically used to set the user prefered setting for verbosity,
+ and any experimental Tcl procedures. My personal
+ <filename>~/.dejagnurc</filename> file looks like:</para>
+
+ <example>
+ <title>Personal Config File</title>
+
+ <programlisting>
+ set all_flag 1
+ set RLOGIN /usr/ucb/rlogin
+ set RSH /usr/local/sbin/ssh
+ </programlisting>
+ </example>
+
+ <para>Here I set <symbol>all_flag</symbol> so I see all the test
+ cases that PASS along with the ones that FAIL. I also set
+ <symbol>RLOGIN</symbol> to the BSD version. I have
+ <productname>Kerberos</productname> 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 <symbol>RSH</symbol> to the <productname>SSH</productname>
+ secure shell, as rsh is mostly used to test unix
+ machines within a local network here.</para>
+
+ </sect1>
+
+ </chapter>
+
+ <chapter id=Extending xreflabel="Extending DejaGnu">
+ <title>Extending DejaGnu</title>
+
+ <sect1 id=addsuite xreflabel="Adding a new Test Suite">
+ <title>Adding A New Test Suite</title>
+
+ <para>The testsuite for a new tool should always be located in that tools
+ source directory. DejaGnu require the directory be named
+ <filename>testsuite</filename>. Under this directory, the test cases go
+ in a subdirectory whose name begins with the tool name. For example, for
+ a tool named <emphasis>flubber</emphasis>, each subdirectory containing
+ testsuites must start with <emphasis>"flubber."</emphasis>.</para>
+
+ </sect1>
+
+ <sect1 id=addtool xreflabel="Adding A New Tool">
+ <title>Adding A New Tool</title>
+
+ <para>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
+ <productname>Expect</productname> and <productname>Tcl</productname> in
+ general.</para>
+
+ <para>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.</para>
+
+ <para>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
+ <filename>example/</filename> directory of the DejaGnu distribution
+ contains both an interactive tool called <command>calc</command>, 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 calc and its test suite---and also the first
+ version of this section of the manual!)</para>
+
+ <para>To help orient you further in this task, here is an outline of the
+ steps to begin building a test suite for a program example.</para>
+
+ <itemizedlist mark=bullet>
+
+ <listitem><para>Create or select a directory to contain your new
+ collection of tests. Change into that directory (shown here as
+ <filename>testsuite</filename>):</para>
+
+ <para>Create a <filename>configure.in</filename> 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 <symbol>target_abbrev</symbol>; this value is the link to the
+ init file you will write soon. (For simplicity, we assume the
+ environment is Unix, and use <emphasis>unix</emphasis> as the
+ value.)</para>
+
+ <para>What else is needed in <filename>configure.in</filename> 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 <productname>GNU Autoconf</productname>. </para></listitem>
+
+ <listitem><para>Create <filename>Makefile.in</filename> (if you are using
+ Autoconf), or <filename>Makefile.am</filename>(if you are using
+ Automake), the source file used by configure to build your
+ <filename>Makefile</filename>. If you are using GNU Automake.just add the
+ keyword <emphasis>dejagnu</emphasis> to the
+ <emphasis>AUTOMAKE_OPTIONS</emphasis> variable in your
+ <filename>Makefile.am</filename> file. This will add all the Makefile
+ support needed to run DejaGnu, and support the <xref linkend=makecheck>
+ target.</para>
+
+ <para>You also need to include two targets important to DejaGnu:
+ <emphasis>check</emphasis>, to run the tests, and
+ <emphasis>site.exp</emphasis>, to set up the Tcl copies of
+ configuration-dependent values. This is called the <xref linkend=local>
+ The check target must run the <command>runtest</command> program to
+ execute the tests.</para>
+
+ <para>The <filename>site.exp</filename> 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 <command>runtest</command> on the command
+ line.</para>
+
+ <example>
+ <title>Sample Makefile.in Fragment</title>
+
+ <programlisting>
+ # 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 <symbol>${example}</symbol> --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 <symbol>${examplename}</symbol> <symbol>${example}</symbol>" >> ./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?
+
+ </programlisting>
+ </example>
+ </listitem>
+
+ <listitem><para>Create a directory (in <filename>testsuite</filename>)
+ called <filename>config</filename>. Make a <emphasis>Tool Init
+ File</emphasis> in this directory. Its name must start with the
+ <symbol>target_abbrev</symbol> value, or be named
+ <filename>default.exp</filename> so call it
+ <filename>config/unix.exp</filename> 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 <command>runtest</command> to run.</para>
+
+ <para>If the program being tested is not interactive, you can get
+ away with this minimal <filename>unix.exp</filename> to begin
+ with:</para>
+
+ <example>
+ <title>Simple Batch Program Tool Init File</title>
+
+ <programlisting>
+
+ proc foo_exit {} {}
+ proc foo_version {} {}
+
+ </programlisting>
+ </example>
+
+ <para>If the program being tested is interactive, however, you might
+ as well define a <emphasis>start</emphasis> routine and invoke it by
+ using an init file like this:</para>
+
+ <example>
+ <title>Simple Interactive Program Tool Init File</title>
+
+ <programlisting>
+
+ 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
+
+ </programlisting>
+ </example>
+ </listitem>
+
+ <listitem><para>Create a directory whose name begins with your tool's
+ name, to contain tests. For example, if your tool's name is
+ <emphasis>gcc</emphasis>, then the directories all need to start with
+ <emphasis>"gcc."</emphasis>.</para></listitem>
+
+ <listitem><para>Create a sample test file. Its name must end with
+ <filename>.exp</filename>. You can use
+ <filename>first-try.exp</filename>. To begin with, just write there a
+ line of Tcl code to issue a message.</para>
+
+ <example>
+ <title>Testing A New Tool Config</title>
+
+ <programlisting>
+
+ send_user "Testing: one, two...\n"
+
+ </programlisting>
+ </example>
+ </listitem>
+
+ <listitem><para>Back in the <filename>testsuite</filename> (top
+ level) directory, run <command>configure</command>. 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.</para></listitem>
+
+ <listitem><para>e now ready to triumphantly type <command>make
+ check</command> or <command>runtest</command>. You should see
+ something like this:</para>
+
+ <example>
+ <title>Example Test Case Run</title>
+
+ <screen>
+ 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 ===
+
+ </screen>
+ </example>
+
+ <para>There is no output in the summary, because so far the example
+ does not call any of the procedures that establish a test
+ outcome.</para></listitem>
+
+ <listitem><para>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. </para></listitem>
+
+ </itemizedlist>
+
+ </sect1>
+
+ <sect1 id=addtarget xreflabel="Adding A New Target">
+ <title>Adding A New Target</title>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>When you code an initialization module, be generous in printing
+ information controlled by the <function>verbose</function>
+ procedure.</para>
+
+ <para>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.</para>
+
+ <para>If you suspect a communication problem, try running the connection
+ interactively from <productname>Expect</productname>. (There are three
+ ways of running <productname>Expect</productname> as an interactive
+ interpreter. You can run <productname>Expect</productname> with no
+ arguments, and control it completely interactively; or you can use
+ <command>expect -i</command> together with other command-line options and
+ arguments; or you can run the command <command>interpreter</command> from
+ any <productname>Expect</productname> procedure. Use
+ <command>return</command> to get back to the calling procedure (if any),
+ or <command>return -tcl</command> to make the calling procedure itself
+ return to its caller; use <command>exi</command>t or end-of-file to leave
+ Expect altogether.) Run the program whose name is recorded in
+ <symbol>$connectmode</symbol>, with the arguments in
+ <symbol>$targetname</symbol>, to establish a connection. You should at
+ least be able to get a prompt from any target that is physically
+ connected.</para>
+
+ </sect1>
+
+ <sect1 id=addboard xreflabel="Adding A New Board">
+ <title>Adding A New Board</title>
+
+ <para>Adding a new board consists of creating a new board config
+ file. Examples are in
+ <filename>dejagnu/baseboards</filename>. 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
+ <emphasis>baseboard</emphasis> 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 <symbol>boards_DATA</symbol> list in the
+ <filename>dejagnu/baseboards/Makefile.am</filename>, and regenerate the
+ Makefile.in using automake. Then just rebuild and install DejaGnu. You
+ can test it by:</para>
+
+ <para>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 <function>load_generic_config</function> and
+ <function>load_base_board_description</function>. 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.</para>
+
+ <example>
+ <title>Testing a New Board Config File</title>
+
+ <screen>
+ make check RUNTESTFLAGS="--target_board=<emphasis>newboardfile</emphasis>".
+ </screen>
+ </example>
+
+ <para>Here's an example of a board config file. There are
+ several <emphasis>helper procedures</emphasis> 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
+ <emphasis>[]</emphasis>, which is the Tcl execution characters.</para>
+
+ <example>
+ <title>Example Board Config File</title>
+
+ <programlisting>
+
+ # 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
+
+ </programlisting>
+ </example>
+
+ </sect1>
+
+ <sect1 id=boarddefs xreflabel="Board File Values">
+ <title>Board Config File Values</title>
+
+ <para>These fields are all in the <symbol>board_info</symbol> These are
+ all set by using the <function>set_board_info</function> procedure. The
+ parameters are the field name, followed by the value to set the field
+ to.</para>
+
+ <para><table frame=all rowsep=0 colsep=0>
+ <title>Common Board Info Fields</title>
+
+ <tgroup cols=3 align="char" rowsep=1 colsep=0>
+ <thead><row>
+ <entry>Field</entry>
+ <entry>Sample Value</entry>
+ <entry>Description</entry>
+ </row></thead>
+ <tbody>
+
+ <row>
+ <entry>compiler</entry>
+ <entry>"[find_gcc]"</entry>
+ <entry>The path to the compiler to use.</entry>
+ </row>
+
+ <row>
+ <entry>cflags</entry>
+ <entry>"-mca"</entry>
+ <entry>Compilation flags for the compiler.</entry>
+ </row>
+
+ <row>
+ <entry>ldflags</entry>
+ <entry>"[libgloss_link_flags] [newlib_link_flags]"</entry>
+ <entry>Linking flags for the compiler.</entry>
+ </row>
+
+ <row>
+ <entry>ldscript</entry>
+ <entry>"-Wl,-Tidt.ld"</entry>
+ <entry>The linker script to use when cross compiling.</entry>
+ </row>
+
+ <row>
+ <entry>libs</entry>
+ <entry>"-lgcc"</entry>
+ <entry>Any additional libraries to link in.</entry>
+ </row>
+
+ <row>
+ <entry>shell_prompt</entry>
+ <entry>"cygmon>"</entry>
+ <entry>The command prompt of the remote shell.</entry>
+ </row>
+
+ <row>
+ <entry>hex_startaddr</entry>
+ <entry>"0xa0020000"</entry>
+ <entry>The Starting address as a string.</entry>
+ </row>
+
+ <row>
+ <entry>start_addr</entry>
+ <entry>0xa0008000</entry>
+ <entry>The starting address as a value.</entry>
+ </row>
+
+ <row>
+ <entry>startaddr</entry>
+ <entry>"a0020000"</entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>exit_statuses_bad</entry>
+ <entry>1</entry>
+ <entry>Whether there is an accurate exit status.</entry>
+ </row>
+
+ <row>
+ <entry>reboot_delay</entry>
+ <entry>10</entry>
+ <entry>The delay between power off and power on.</entry>
+ </row>
+
+ <row>
+ <entry>unreliable</entry>
+ <entry>1</entry>
+ <entry>Whether communication with the board is unreliable.</entry>
+ </row>
+
+ <row>
+ <entry>sim</entry>
+ <entry>[find_sim]</entry>
+ <entry>The path to the simulator to use.</entry>
+ </row>
+
+ <row>
+ <entry>objcopy</entry>
+ <entry>$tempfil</entry>
+ <entry>The path to the <command>objcopy</command> program.</entry>
+ </row>
+
+ <row>
+ <entry>support_libs</entry>
+ <entry>"${prefix_dir}/i386-coff/"</entry>
+ <entry>Support libraries needed for cross compiling.</entry>
+ </row>
+
+ <row>
+ <entry>addl_link_flags</entry>
+ <entry>"-N"</entry>
+ <entry>Additional link flags, rarely used.</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ <para>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.</para>
+
+ <para><table frame=all rowsep=0 colsep=0>
+ <title>Board Info Fields For GCC & GDB</title>
+
+ <tgroup cols=3 align="char" rowsep=1 colsep=0>
+ <thead><row>
+ <entry>Field</entry>
+ <entry>Sample Value</entry>
+ <entry>Description</entry>
+ </row></thead>
+ <tbody>
+
+ <row>
+ <entry>strip</entry>
+ <entry>$tempfile</entry>
+ <entry>Strip the executable of symbols.</entry>
+ </row>
+
+ <row>
+ <entry>gdb_load_offset</entry>
+ <entry>"0x40050000"</entry>
+ </row>
+
+ <row>
+ <entry>gdb_protocol</entry>
+ <entry>"remote"</entry>
+ <entry>The GDB debugging protocol to use.</entry>
+ </row>
+
+ <row>
+ <entry>gdb_sect_offset</entry>
+ <entry>"0x41000000";</entry>
+ </row>
+
+ <row>
+ <entry>gdb_stub_ldscript</entry>
+ <entry>"-Wl,-Teva-stub.ld"</entry>
+ <entry>The linker script to use with a GDB stub.</entry>
+ </row>
+
+ <row>
+ <entry>gdb_init_command</entry>
+ <entry>"set mipsfpu none"</entry>
+ </row>
+
+ <row>
+ <entry>gdb,cannot_call_functions</entry>
+ <entry>1</entry>
+ <entry>Whether GDB can call functions on the target,</entry>
+ </row>
+
+ <row>
+ <entry>gdb,noargs</entry>
+ <entry>1</entry>
+ <entry>Whether the target can take command line arguments.</entry>
+ </row>
+
+ <row>
+ <entry>gdb,nosignals</entry>
+ <entry>1</entry>
+ <entry>Whether there are signals on the target.</entry>
+ </row>
+
+ <row>
+ <entry>gdb,short_int</entry>
+ <entry>1</entry>
+ </row>
+
+ <row>
+ <entry>gdb,start_symbol</entry>
+ <entry>"_start";</entry>
+ <entry>The starting symbol in the executable.</entry>
+ </row>
+
+ <row>
+ <entry>gdb,target_sim_options</entry>
+ <entry>"-sparclite"</entry>
+ <entry>Special options to pass to the simulator.</entry>
+ </row>
+
+ <row>
+ <entry>gdb,timeout</entry>
+ <entry>540</entry>
+ <entry>Timeout value to use for remote communication.</entry>
+ </row>
+
+ <row>
+ <entry>gdb_init_command</entry>
+ <entry>"print/x \$fsr = 0x0"</entry>
+ </row>
+
+ <row>
+ <entry>gdb_load_offset</entry>
+ <entry>"0x12020000"</entry>
+ </row>
+
+ <row>
+ <entry>gdb_opts</entry>
+ <entry>"--command gdbinit"</entry>
+ </row>
+
+ <row>
+ <entry>gdb_prompt</entry>
+ <entry>"\\(gdb960\\)"</entry>
+ <entry>The prompt GDB is using.</entry>
+ </row>
+
+ <row>
+ <entry>gdb_run_command</entry>
+ <entry>"jump start"</entry>
+ </row>
+
+ <row>
+ <entry>gdb_stub_offset</entry>
+ <entry>"0x12010000"</entry>
+ </row>
+
+ <row>
+ <entry>use_gdb_stub</entry>
+ <entry>1</entry>
+ <entry>Whether to use a GDB stub.</entry>
+ </row>
+
+ <row>
+ <entry>use_vma_offset</entry>
+ <entry>1</entry>
+ </row>
+
+ <row>
+ <entry>wrap_m68k_aout</entry>
+ <entry>1</entry>
+ </row>
+
+ <row>
+ <entry>gcc,no_label_values</entry>
+ <entry>1</entry>
+ </row>
+
+ <row>
+ <entry>gcc,no_trampolines</entry>
+ <entry>1</entry>
+ </row>
+
+ <row>
+ <entry>gcc,no_varargs</entry>
+ <entry>1</entry>
+ </row>
+
+ <row>
+ <entry>gcc,stack_size</entry>
+ <entry>16384</entry>
+ <entry>Stack size to use with some GCC testcases.</entry>
+ </row>
+
+ <row>
+ <entry>ieee_multilib_flags</entry>
+ <entry>"-mieee";</entry>
+ </row>
+
+ <row>
+ <entry>is_simulator</entry>
+ <entry>1</entry>
+ </row>
+
+ <row>
+ <entry>needs_status_wrapper</entry>
+ <entry>1</entry>
+ </row>
+
+ <row>
+ <entry>no_double</entry>
+ <entry>1</entry>
+ </row>
+
+ <row>
+ <entry>no_long_long</entry>
+ <entry>1</entry>
+ </row>
+
+ <row>
+ <entry>noargs</entry>
+ <entry>1</entry>
+ </row>
+
+ <row>
+ <entry>nullstone,lib</entry>
+ <entry>"mips-clock.c"</entry>
+ </row>
+
+ <row>
+ <entry>nullstone,ticks_per_sec</entry>
+ <entry>3782018</entry>
+ </row>
+
+ <row>
+ <entry>sys_speed_value</entry>
+ <entry>200</entry>
+ </row>
+
+ <row>
+ <entry>target_install</entry>
+ <entry>{sh-hms}</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ </sect1>
+
+ <sect1 id=writing xreflabel="Writing A Test Case">
+ <title>Writing A Test Case</title>
+
+ <para>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.</para>
+
+ <para>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 <filename>lib/c-torture.exp</filename> in the GCC test
+ suite. Most tests of this kind use very few
+ <productname>expect</productname> features, and are coded almost
+ purely in Tcl.</para>
+
+ <para>Writing the complete suite of C tests, then, consisted of
+ these steps:</para>
+
+ <itemizedlist mark=bullet>
+ <listitem><para>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.</para></listitem>
+
+ <listitem><para>Writing (and debugging) the generic Tcl procedures for
+ compilation.</para></listitem>
+
+ <listitem><para>Writing the simple test driver: its main task is to
+ search the directory (using the Tcl procedure
+ <emphasis>glob</emphasis> for filename expansion with wildcards)
+ and call a Tcl procedure with each filename. It also checks for
+ a few errors from the testing procedure.</para></listitem>
+ </itemizedlist>
+
+ <para>Testing interactive programs is intrinsically more
+ complex. Tests for most interactive programs require some trial
+ and error before they are complete.</para>
+
+ <para>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.</para>
+
+ </sect1>
+
+ <sect1 id=debugging xreflabel="Debugging A Test Case">
+ <title>Debugging A Test Case</title>
+
+ <para>These are the kinds of debugging information available
+ from DejaGnu:</para>
+
+ <itemizedlist mark=bullet>
+
+ <listitem><para>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
+ <command>verbose</command> procedure (which in turn uses the
+ variable also called <emphasis>verbose</emphasis>) 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 <emphasis>$verbose</emphasis> is
+ <emphasis>0</emphasis>, there should be no output other than the
+ output from <emphasis>pass</emphasis>,
+ <emphasis>fail</emphasis>, <emphasis>error</emphasis>, and
+ <emphasis>warning</emphasis>. Then, to whatever extent is
+ appropriate for the particular test, allow successively higher
+ values of <emphasis>$verbose</emphasis> to generate more
+ information. Be kind to other programmers who use your tests:
+ provide for a lot of debugging information.</para>
+
+ <listitem><para>Output from the internal debugging functions of
+ Tcl and <productname>Expect</productname>. There is a command
+ line options for each; both forms of debugging output are
+ recorded in the file <filename>dbg.log</filename> in the current
+ directory.</para>
+
+ <para>Use <option>--debug</option> 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
+ <filename>dbg.log</filename> can allow you to create the final
+ patterns by ``cut and paste''. This is sometimes the best way
+ to write a test case.</para>
+
+ <listitem><para>Use <option>--strace</option> 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.</para></listitem>
+
+ <listitem><para>Finally, if the value of
+ <emphasis>verbose</emphasis> is 3 or greater,DejaGnu turns on
+ the expect command <command>log_user</command>. This command
+ prints all expect actions to the expect standard output, to the
+ detailed log file, and (if <option>--debug</option> is on) to
+ <filename>dbg.log</filename>.</para>
+ </itemizedlist>
+
+ </sect1>
+
+ <sect1 id=adding xreflabel="Adding A Test Case To A Test Suite">
+ <title>Adding A Test Case To A Test Suite.</title>
+
+ <para>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.</para>
+
+ <para>Adding a GCC test can be very simple: just add the C code
+ to any directory beginning with <filename>gcc</filename>. and it
+ runs on the next <programlisting>runtest --tool
+ gcc</programlisting>.</para>
+
+ <para>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 <emphasis>.exp</emphasis> 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
+ <filename>Makefile.in</filename> file for that test directory,
+ then run <command>configure</command> and
+ <command>make</command>.</para>
+
+ <para>Adding a test by creating a new directory is very
+ similar:</para>
+
+ <itemizedlist mark=bullet>
+
+ <listitem><para>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 <filename>g++.other</filename>. There can
+ be multiple test directories that start with the same tool name
+ (such as <emphasis>g++</emphasis>).</para></listitem>
+
+ <listitem><para>Add the new directory name to the
+ <symbol>configdirs</symbol> definition in the
+ <filename>configure.in</filename> file for the test suite
+ directory. This way when <command>make</command> and
+ <command>configure</command> next run, they include the new
+ directory.</para></listitem>
+
+ <listitem><para>Add the new test case to the directory, as
+ above. </para>
+
+ <listitem><para>To add support in the new directory for
+ configure and make, you must also create a
+ <filename>Makefile.in</filename> and a
+ <filename>configure.in</filename>.</para></listitem>
+ </itemizedlist>
+
+ </sect1>
+
+ <sect1 id=hints xreflabel="Hints On Writing A Test Case">
+ <title>Hints On Writing A Test Case</title>
+
+ <para>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 <command>expect</command>
+ command. In this situation, the precise boundary that determines
+ which <command>expect</command> 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
+ <option>-re</option> option for the <command>expect</command>
+ command to write the pattern as a full regular expressions; then
+ you can match the end of output using a <emphasis>$</emphasis>.
+ It is also a good idea to write patterns that match all
+ available output by using <emphasis>.*\</emphasis> after the
+ text of interest; this will also match any intervening blank
+ lines. Sometimes an alternative is to match end of line using
+ <emphasis>\r</emphasis> or <emphasis>\n</emphasis>, but this is
+ usually too dependent on terminal settings.</para>
+
+ <para>Always escape punctuation, such as <emphasis>(</emphasis>
+ or <emphasis>"</emphasis>, in your patterns; for example, write
+ <emphasis>\(</emphasis>. If you forget to escape punctuation,
+ you will usually see an error message like <programlisting>extra
+ characters after close-quote.</programlisting></para>
+
+ <para>If you have trouble understanding why a pattern does not
+ match the program output, try using the <option>--debug</option>
+ option to <command>runtest</command>, and examine the debug log
+ carefully.</para>
+
+ <para>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 <emphasis>set height
+ 0\n</emphasis> command. The purpose is simply to make sure GDB
+ never calls a paging program. The <emphasis>set
+ height</emphasis> command in GDB does not generate any
+ output; but running any command makes GDB issue a new
+ <emphasis>(gdb) </emphasis> prompt. If there were no
+ <command>expect</command> command to match this prompt, the
+ output <emphasis>(gdb) </emphasis> begins the text seen by the
+ next <command>expect</command> command---which might make that
+ pattern fail to match.</para>
+
+ <para>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
+ <command>error</command> or <command>warning</command>.</para>
+
+ </sect1>
+
+ <sect1 id=tvariables xreflabel="Test Case Variables">
+ <title>Special variables used by test cases.</title>
+
+ <para>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
+ <filename>site.exp</filename>. You can use the value of these variables,
+ but they should never be changed.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>$prms_id</term>
+ <listitem><para>The tracking system (e.g. GNATS) number identifying
+ a corresponding bugreport. (<emphasis>0</emphasis>} if you do not
+ specify it in the test script.)</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>$item bug_id</term>
+ <listitem><para>An optional bug id; may reflect a bug
+ identification from another organization. (<emphasis>0</emphasis>
+ if you do not specify it.)</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>$subdir</term>
+ <listitem><para>The subdirectory for the current test
+ case.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>$expect_out(buffer)</term>
+ <listitem><para>The output from the last command. This is an
+ internal variable set by Expect. More information can be found in
+ the Expect manual.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>$exec_output</term>
+ <listitem><para>This is the output from a
+ <function>${tool}_load</function> 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.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>$comp_output</term>
+ <listitem><para>This is the output from a
+ <function>${tool}_start</function> command. This is conventionally
+ used for batch oriented programs, like GCC and GAS, that may
+ produce interesting output (warnings, errors) without further
+ interaction.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect1>
+
+</chapter>
+