--- /dev/null
+
+figdir = images
+docname = dejagnu
+lang = C
+omffile = dejagnu.omf
+
+entities = $(srcdir)/legal.xml
+include $(top_srcdir)/doc/xmldocs.make
+dist-hook: app-dist-hook
+gnuae_helpdir = $(datadir)/gnome/help/$(docname)/C
+
+CLEANFILES = \
+ db2texi.refs \
+ DejaGnu.texi \
+ DejaGnu.info \
+ dejagnu.txml \
+ dejagnu.mxml \
+ dejagnu.tex \
+ dejagnu.texi \
+ dejagnu.pdf \
+ dejagnu.ps \
+ dejagnu.rtf \
+ omf_timestamp \
+ manpages.ref
+
+
+gnuae_help_DATA = \
+ topic.dat \
+ dejagnu.xml \
+ ref.xml \
+ user.xml
+
+MAKEINFO = @MAKEINFO@
+
+#html: force
+# mkdir -p html/stylesheet
+# cp -r $(srcdir)/images/*.png html/stylesheet
+# xsltproc -v -o html/ $(srcdir)/stylesheets/general-customization.xsl $(srcdir)/dejagnu.xml
+
+clean-local: force
+ rm -fr html DejaGnu.info*
+
+html: force
+ docbook2html -o html $(srcdir)/dejagnu.xml
+ mv html/t1.html html/index.html
+
+pdf: force
+ docbook2pdf $(srcdir)/dejagnu.xml
+
+ps: force
+ docbook2ps $(srcdir)/dejagu.xml
+
+rtf: force
+ docbook2rtf $(srcdir)/dejagnu.xml
+
+man: force
+ db2x_xsltproc -s man $(srcdir)/dejagnu.xml -o dejagnu.mxml
+ db2x_manxml dejagnu.mxml
+# docbook2man $(srcdir)/dejagnu.xml
+
+texi: force
+ db2x_xsltproc -s texi $(srcdir)/dejagnu.xml -o dejagnu.txml
+ db2x_texixml dejagnu.txml
+# docbook2texi $(srcdir)/dejagnu.xml
+
+info: texi
+ $(MAKEINFO) DejaGnu.texi
+
+lint:
+ xmllint $(srcdir)/dejagnu.xml
+
+# install GNOME help files, which are basically the html output
+install-ghelp: html
+ $(mkinstalldirs) $(gnuae_helpdir)/stylesheet
+ $(mkinstalldirs) $(gnuae_helpdir)/images
+ $(INSTALL_DATA) html/*.html $(gnuae_helpdir)
+ $(INSTALL_DATA) html/stylesheet/*.png $(gnuae_helpdir)/stylesheet
+# cp -r $(srcdir)/images $(gnuae_helpdir)/images
+
+force:
+
+scrollkeeper:
+ scrollkeeper-install $(prefix)/dejagnu.omf
+ scrollkeeper-update $(prefix)/dejagnu.omf
--- /dev/null
+# Makefile.in generated by automake 1.7a from Makefile.am.
+# @configure_input@
+
+# Copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003
+# 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.
+
+@SET_MAKE@
+
+#
+# No modifications of this Makefile should be necessary.
+#
+# To use this template:
+# 1) Define: figdir, docname, lang, omffile, and entities in
+# your Makefile.am file for each document directory,
+# although figdir, omffile, and entities may be empty
+# 2) Make sure the Makefile in (1) also includes
+# "include $(top_srcdir)/doc/xmldocs.make and
+# "dist-hook: app-dist-hook".
+# 3) Optionally define 'entities' to hold xml entities which
+# you would also like installed
+# 4) Figures must go under $(figdir)/ and be in PNG format
+# 5) You should only have one document per directory
+# 6) Note that the figure directory, $(figdir)/, should not have its
+# own Ma fdl-appendix.xmlkefile since this Makefile installs those figures.
+#
+# example Makefile.am:
+# figdir = figures
+# docname = scrollkeeper-manual
+# lang = C
+# omffile=scrollkeeper-manual-C.omf
+# entities = fdl.xml
+# include $(top_srcdir)/help/xmldocs.make
+# dist-hook: app-dist-hook
+#
+# About this file:
+# This file was taken from scrollkeeper_example2, a package illustrating
+# how to install documentation and OMF files for use with ScrollKeeper
+# 0.3.x and 0.4.x. For more information, see:
+# http://scrollkeeper.sourceforge.net/
+# Version: 0.1.2 (last updated: March 20, 2002)
+#
+
+#
+# No modifications of this Makefile should be necessary.
+#
+# This file contains the build instructions for installing OMF files. It is
+# generally called from the makefiles for particular formats of documentation.
+#
+# Note that you must configure your package with --localstatedir=/var/lib
+# so that the scrollkeeper-update command below will update the database
+# in the standard scrollkeeper directory.
+#
+# If it is impossible to configure with --localstatedir=/var/lib, then
+# modify the definition of scrollkeeper_localstate_dir so that
+# it points to the correct location. Note that you must still use
+# $(localstatedir) in this or when people build RPMs it will update
+# the real database on their system instead of the one under RPM_BUILD_ROOT.
+#
+# Note: This make file is not incorporated into xmldocs.make because, in
+# general, there will be other documents install besides XML documents
+# and the makefiles for these formats should also include this file.
+#
+# About this file:
+# This file was taken from scrollkeeper_example2, a package illustrating
+# how to install documentation and OMF files for use with ScrollKeeper
+# 0.3.x and 0.4.x. For more information, see:
+# http://scrollkeeper.sourceforge.net/
+# Version: 0.1.2 (last updated: March 20, 2002)
+#
+
+srcdir = @srcdir@
+top_srcdir = @top_srcdir@
+VPATH = @srcdir@
+pkgdatadir = $(datadir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+top_builddir = ../..
+
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+INSTALL = @INSTALL@
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+install_sh_SCRIPT = $(install_sh) -c
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = $(program_transform_name)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+ACLOCAL = @ACLOCAL@
+AMDEP_FALSE = @AMDEP_FALSE@
+AMDEP_TRUE = @AMDEP_TRUE@
+AMTAR = @AMTAR@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+BOARDS = @BOARDS@
+CC = @CC@
+CCDEPMODE = @CCDEPMODE@
+CFLAGS = @CFLAGS@
+CONFIG = @CONFIG@
+CPPFLAGS = @CPPFLAGS@
+CXX = @CXX@
+CXXDEPMODE = @CXXDEPMODE@
+CXXFLAGS = @CXXFLAGS@
+CYGPATH_W = @CYGPATH_W@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+DOCBOOK = @DOCBOOK@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+EXEEXT = @EXEEXT@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+LDFLAGS = @LDFLAGS@
+LIBOBJS = @LIBOBJS@
+LIBS = @LIBS@
+LTLIBOBJS = @LTLIBOBJS@
+MAINT = @MAINT@
+MAINTAINER_MODE_FALSE = @MAINTAINER_MODE_FALSE@
+MAINTAINER_MODE_TRUE = @MAINTAINER_MODE_TRUE@
+
+MAKEINFO = @MAKEINFO@
+OBJEXT = @OBJEXT@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+STRIP = @STRIP@
+TCLSH = @TCLSH@
+VERSION = @VERSION@
+YACC = @YACC@
+ac_ct_CC = @ac_ct_CC@
+ac_ct_CXX = @ac_ct_CXX@
+ac_ct_STRIP = @ac_ct_STRIP@
+am__fastdepCC_FALSE = @am__fastdepCC_FALSE@
+am__fastdepCC_TRUE = @am__fastdepCC_TRUE@
+am__fastdepCXX_FALSE = @am__fastdepCXX_FALSE@
+am__fastdepCXX_TRUE = @am__fastdepCXX_TRUE@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+bindir = @bindir@
+build_alias = @build_alias@
+datadir = @datadir@
+exec_prefix = @exec_prefix@
+host_alias = @host_alias@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+libdir = @libdir@
+libexecdir = @libexecdir@
+localstatedir = @localstatedir@
+mandir = @mandir@
+oldincludedir = @oldincludedir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+sbindir = @sbindir@
+sharedstatedir = @sharedstatedir@
+subdirs = @subdirs@
+sysconfdir = @sysconfdir@
+target_alias = @target_alias@
+tclsh = @tclsh@
+
+figdir = images
+docname = dejagnu
+lang = C
+omffile = dejagnu.omf
+
+entities = $(srcdir)/legal.xml
+
+# ************* Begin of section some packagers may need to modify **************
+# This variable (docdir) specifies where the documents should be installed.
+# This default value should work for most packages.
+docdir = $(datadir)/@PACKAGE@/doc/$(docname)/$(lang)
+
+# ************** You should not have to edit below this line *******************
+xml_files = $(entities) $(docname).xml
+omf_dir = $(top_srcdir)/omf-install
+
+EXTRA_DIST = $(xml_files) $(omffile)
+
+CLEANFILES = \
+ db2texi.refs \
+ DejaGnu.texi \
+ DejaGnu.info \
+ dejagnu.txml \
+ dejagnu.mxml \
+ dejagnu.tex \
+ dejagnu.texi \
+ dejagnu.pdf \
+ dejagnu.ps \
+ dejagnu.rtf \
+ omf_timestamp \
+ manpages.ref
+
+
+omf_dest_dir = $(datadir)/omf/@PACKAGE@
+scrollkeeper_localstate_dir = $(localstatedir)/scrollkeeper
+gnuae_helpdir = $(datadir)/gnome/help/$(docname)/C
+
+gnuae_help_DATA = \
+ topic.dat \
+ dejagnu.xml \
+ ref.xml \
+ user.xml
+
+subdir = doc/C
+mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs
+CONFIG_CLEAN_FILES =
+DIST_SOURCES =
+DATA = $(gnuae_help_DATA)
+
+DIST_COMMON = $(top_srcdir)/doc/omf.make $(top_srcdir)/doc/xmldocs.make \
+ Makefile.am Makefile.in
+all: all-am
+
+.SUFFIXES:
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ Makefile.am $(top_srcdir)/doc/xmldocs.make $(top_srcdir)/doc/omf.make $(top_srcdir)/configure.in $(ACLOCAL_M4)
+ cd $(top_srcdir) && \
+ $(AUTOMAKE) --gnu doc/C/Makefile
+Makefile: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.in $(top_builddir)/config.status
+ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)
+uninstall-info-am:
+gnuae_helpDATA_INSTALL = $(INSTALL_DATA)
+install-gnuae_helpDATA: $(gnuae_help_DATA)
+ @$(NORMAL_INSTALL)
+ $(mkinstalldirs) $(DESTDIR)$(gnuae_helpdir)
+ @list='$(gnuae_help_DATA)'; for p in $$list; do \
+ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+ f="`echo $$p | sed -e 's|^.*/||'`"; \
+ echo " $(gnuae_helpDATA_INSTALL) $$d$$p $(DESTDIR)$(gnuae_helpdir)/$$f"; \
+ $(gnuae_helpDATA_INSTALL) $$d$$p $(DESTDIR)$(gnuae_helpdir)/$$f; \
+ done
+
+uninstall-gnuae_helpDATA:
+ @$(NORMAL_UNINSTALL)
+ @list='$(gnuae_help_DATA)'; for p in $$list; do \
+ f="`echo $$p | sed -e 's|^.*/||'`"; \
+ echo " rm -f $(DESTDIR)$(gnuae_helpdir)/$$f"; \
+ rm -f $(DESTDIR)$(gnuae_helpdir)/$$f; \
+ done
+tags: TAGS
+TAGS:
+
+ctags: CTAGS
+CTAGS:
+
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+
+distdir: $(DISTFILES)
+ $(mkinstalldirs) $(distdir)/$(srcdir) $(distdir)/../../doc
+ @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
+ topsrcdirstrip=`echo "$(top_srcdir)" | sed 's|.|.|g'`; \
+ list='$(DISTFILES)'; for file in $$list; do \
+ case $$file in \
+ $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \
+ $(top_srcdir)/*) file=`echo "$$file" | sed "s|^$$topsrcdirstrip/|$(top_builddir)/|"`;; \
+ esac; \
+ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
+ dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \
+ if test "$$dir" != "$$file" && test "$$dir" != "."; then \
+ dir="/$$dir"; \
+ $(mkinstalldirs) "$(distdir)$$dir"; \
+ else \
+ dir=''; \
+ fi; \
+ if test -d $$d/$$file; then \
+ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
+ cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \
+ fi; \
+ cp -pR $$d/$$file $(distdir)$$dir || exit 1; \
+ else \
+ test -f $(distdir)/$$file \
+ || cp -p $$d/$$file $(distdir)/$$file \
+ || exit 1; \
+ fi; \
+ done
+ $(MAKE) $(AM_MAKEFLAGS) \
+ top_distdir="$(top_distdir)" distdir="$(distdir)" \
+ dist-hook
+check-am: all-am
+check: check-am
+all-am: Makefile $(DATA)
+
+installdirs:
+ $(mkinstalldirs) $(DESTDIR)$(gnuae_helpdir)
+
+install: install-am
+install-exec: install-exec-am
+install-data: install-data-am
+uninstall: uninstall-am
+
+install-am: all-am
+ @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-am
+install-strip:
+ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+ INSTALL_STRIP_FLAG=-s \
+ `test -z '$(STRIP)' || \
+ echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install
+mostlyclean-generic:
+
+clean-generic:
+ -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
+
+distclean-generic:
+ -rm -f Makefile $(CONFIG_CLEAN_FILES)
+
+maintainer-clean-generic:
+ @echo "This command is intended for maintainers to use"
+ @echo "it deletes files that may require special tools to rebuild."
+clean: clean-am
+
+clean-am: clean-generic clean-local mostlyclean-am
+
+distclean: distclean-am
+
+distclean-am: clean-am distclean-generic
+
+dvi: dvi-am
+
+dvi-am:
+
+info: info-am
+
+info-am:
+
+install-data-am: install-data-local install-gnuae_helpDATA
+ @$(NORMAL_INSTALL)
+ $(MAKE) $(AM_MAKEFLAGS) install-data-hook
+
+install-exec-am:
+
+install-info: install-info-am
+
+install-man:
+
+installcheck-am:
+
+maintainer-clean: maintainer-clean-am
+
+maintainer-clean-am: distclean-am maintainer-clean-generic
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-generic
+
+pdf: pdf-am
+
+pdf-am:
+
+ps: ps-am
+
+ps-am:
+
+uninstall-am: uninstall-gnuae_helpDATA uninstall-info-am uninstall-local
+
+.PHONY: all all-am check check-am clean clean-generic clean-local \
+ distclean distclean-generic distdir dvi dvi-am info info-am \
+ install install-am install-data install-data-am \
+ install-data-local install-exec install-exec-am \
+ install-gnuae_helpDATA install-info install-info-am install-man \
+ install-strip installcheck installcheck-am installdirs \
+ maintainer-clean maintainer-clean-generic mostlyclean \
+ mostlyclean-generic pdf pdf-am ps ps-am uninstall uninstall-am \
+ uninstall-gnuae_helpDATA uninstall-info-am uninstall-local
+
+
+omf: omf_timestamp
+
+omf_timestamp: $(omffile)
+ -for file in $(omffile); do \
+ scrollkeeper-preinstall $(docdir)/$(docname).xml $(srcdir)/$$file $(srcdir)/$$file.out; \
+ done
+ touch omf_timestamp
+
+install-data-hook-omf:
+ $(mkinstalldirs) $(DESTDIR)$(omf_dest_dir)
+ for file in $(omffile); do \
+ $(INSTALL_DATA) $(srcdir)/$$file.out $(DESTDIR)$(omf_dest_dir)/$$file; \
+ done
+ -scrollkeeper-update -p $(scrollkeeper_localstate_dir) -o $(DESTDIR)$(omf_dest_dir)
+
+uninstall-local-omf:
+ -for file in $(srcdir)/*.omf; do \
+ basefile=`basename $$file`; \
+ rm -f $(omf_dest_dir)/$$basefile; \
+ done
+ -rmdir $(omf_dest_dir)
+ -scrollkeeper-update -p $(scrollkeeper_localstate_dir)
+
+all: omf
+
+$(docname).xml: $(entities)
+ -ourdir=`pwd`; \
+ cd $(srcdir); \
+ cp $(entities) $$ourdir
+
+app-dist-hook:
+ if test "$(figdir)"; then \
+ $(mkinstalldirs) $(distdir)/$(figdir); \
+ for file in $(srcdir)/$(figdir)/*.png; do \
+ basefile=`echo $$file | sed -e 's,^.*/,,'`; \
+ $(INSTALL_DATA) $$file $(distdir)/$(figdir)/$$basefile; \
+ done \
+ fi
+
+install-data-local: omf
+ $(mkinstalldirs) $(DESTDIR)$(docdir)
+ for file in $(xml_files); do \
+ cp $(srcdir)/$$file $(DESTDIR)$(docdir); \
+ done
+ if test "$(figdir)"; then \
+ $(mkinstalldirs) $(DESTDIR)$(docdir)/$(figdir); \
+ for file in $(srcdir)/$(figdir)/*.png; do \
+ basefile=`echo $$file | sed -e 's,^.*/,,'`; \
+ $(INSTALL_DATA) $$file $(DESTDIR)$(docdir)/$(figdir)/$$basefile; \
+ done \
+ fi
+
+install-data-hook: install-data-hook-omf
+
+uninstall-local: uninstall-local-doc uninstall-local-omf
+
+uninstall-local-doc:
+ -if test "$(figdir)"; then \
+ for file in $(srcdir)/$(figdir)/*.png; do \
+ basefile=`echo $$file | sed -e 's,^.*/,,'`; \
+ rm -f $(docdir)/$(figdir)/$$basefile; \
+ done; \
+ rmdir $(DESTDIR)$(docdir)/$(figdir); \
+ fi
+ -for file in $(xml_files); do \
+ rm -f $(DESTDIR)$(docdir)/$$file; \
+ done
+ -rmdir $(DESTDIR)$(docdir)
+dist-hook: app-dist-hook
+
+#html: force
+# mkdir -p html/stylesheet
+# cp -r $(srcdir)/images/*.png html/stylesheet
+# xsltproc -v -o html/ $(srcdir)/stylesheets/general-customization.xsl $(srcdir)/dejagnu.xml
+
+clean-local: force
+ rm -fr html DejaGnu.info*
+
+html: force
+ docbook2html -o html $(srcdir)/dejagnu.xml
+ mv html/t1.html html/index.html
+
+pdf: force
+ docbook2pdf $(srcdir)/dejagnu.xml
+
+ps: force
+ docbook2ps $(srcdir)/dejagu.xml
+
+rtf: force
+ docbook2rtf $(srcdir)/dejagnu.xml
+
+man: force
+ db2x_xsltproc -s man $(srcdir)/dejagnu.xml -o dejagnu.mxml
+ db2x_manxml dejagnu.mxml
+# docbook2man $(srcdir)/dejagnu.xml
+
+texi: force
+ db2x_xsltproc -s texi $(srcdir)/dejagnu.xml -o dejagnu.txml
+ db2x_texixml dejagnu.txml
+# docbook2texi $(srcdir)/dejagnu.xml
+
+info: texi
+ $(MAKEINFO) DejaGnu.texi
+
+lint:
+ xmllint $(srcdir)/dejagnu.xml
+
+# install GNOME help files, which are basically the html output
+install-ghelp: html
+ $(mkinstalldirs) $(gnuae_helpdir)/stylesheet
+ $(mkinstalldirs) $(gnuae_helpdir)/images
+ $(INSTALL_DATA) html/*.html $(gnuae_helpdir)
+ $(INSTALL_DATA) html/stylesheet/*.png $(gnuae_helpdir)/stylesheet
+# cp -r $(srcdir)/images $(gnuae_helpdir)/images
+
+force:
+
+scrollkeeper:
+ scrollkeeper-install $(prefix)/dejagnu.omf
+ scrollkeeper-update $(prefix)/dejagnu.omf
+# 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:
--- /dev/null
+<?xml version="1.0" standalone="no"?>
+<omf>
+ <resource>
+ <creator>
+ rob@senecass.com (Rob Savoye)
+ </creator>
+ <title>
+ DejaGnu Manual
+ </title>
+ <date>
+ 2004-02-05
+ </date>
+ <version identifier="1.4.4" date="2004-02-05" description="First release. Updated for new OMF DTD."/>
+ <subject category="System|Other"/>
+ <description>
+ This is the manual for DejaGnu, the GNU regression Testing Framework
+ </description>
+ <type>
+ manual
+ </type>
+ <format mime="text/xml" dtd="-//OASIS//DTD DocBook XML V4.1.2//EN"/>
+ <identifier url=""/>
+ <language code="C"/>
+ <relation seriesid="31a101ca-363a-11d6-93d3-b34a9c6ce2e6"/>
+ <rights type="GNU FDL" license.version="1.1" license="http://www.gnu.org/licenses/fdl.html" holder="Free Software Foundation"/>
+ </resource>
+</omf>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+ <!ENTITY legal SYSTEM "legal.xml">
+ <!ENTITY appversion "1.4.5">
+ <!ENTITY version "1.4.5">
+ <!ENTITY manrevision "1.0">
+ <!ENTITY date "Feb 2004">
+ <!ENTITY app "<application>DejaGnu</application>">
+ <!ENTITY appname "DejaGnu">
+ <!ENTITY dj "DejaGnu">
+ <!-- The reference material -->
+ <!ENTITY ref SYSTEM "ref.xml">
+ <!-- The user manual -->
+ <!ENTITY user SYSTEM "user.xml">
+]>
+<!-- Begin Document Specific Declarations -->
+<article>
+ <articleinfo>
+ <title>&dj;</title>
+ <subtitle>The GNU Testing Framework</subtitle>
+ <date>2004 Feb 04</date>
+ <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>
+ <year>2004</year>
+ <holder>Rob Savoye</holder>
+ </copyright>
+ <!-- <legalnotice>
+ <para> -->
+ <!-- [FIXME: must put legal notice here] -->
+ <!-- </para> -->
+ <!-- &cygnus-legal-notice; -->
+ <!-- </legalnotice> -->
+ <revhistory>
+ <revision>
+ <revnumber>0.6.2</revnumber>
+ <date>2002-7-16</date>
+ <authorinitials>rob@welcomehome.org</authorinitials>
+ <revremark>Add new tutorial as a new sect1.</revremark>
+ </revision>
+ <revision>
+ <revnumber>0.6.1</revnumber>
+ <date>2001-2-16</date>
+ <authorinitials>rob@welcomehome.org</authorinitials>
+ <revremark>Add info on the new dejagnu.h file.</revremark>
+ </revision>
+ <revision>
+ <revnumber>0.6</revnumber>
+ <date>2001-2-16</date>
+ <authorinitials>rob@welcomehome.org</authorinitials>
+ <revremark>Updated for new release.</revremark>
+ </revision>
+ <revision>
+ <revnumber>0.5</revnumber>
+ <date>2000-1-24</date>
+ <authorinitials>rob@welcomehome.org</authorinitials>
+ <revremark>Initial version after conversion to DocBook.</revremark>
+ </revision>
+ </revhistory>
+
+ </articleinfo>
+
+ <sect1 id="preface">
+ <title>Abstract</title>
+
+ <para>This document describes the functionality of DejaGnu, the
+ testing framework of the GNU project. DejaGnu is written in
+ <productname>Expect</productname>, which uses
+ <productname>Tcl</productname> as a command
+ language. <productname>Expect</productname> acts as a very
+ programmable shell. As with other Unix command shells, you can
+ run any program, but once the program is started, your test script
+ has programmable control over its input and output. This does not
+ just apply to the programs under test; <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 the creation of
+ testsuites. Testsuites are distributed with each
+ application.</para>
+
+ </sect1>
+
+ <sect1 id="overview" xreflabel="Overview">
+ <title>Overview</title>
+ <sect2 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 testsuites, 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>Julia Menapace first coined the term ``DejaGnu'' 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.
+ More importantly, it was also named after my daughter, <ulink
+ url="mailto:deja@welcomehome.org">Deja Snow Savoye</ulink>
+ (now 14 years old as of Feb 2004), who was a toddler
+ during DejaGnu's beginnings.</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 supported host
+ system on any supported target system. DejaGnu runs tests on
+ many single board computers, whose operating software ranges
+ from a simple boot monitor to a real-time OS.</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 testsuites. 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 testsuites themselves. Tests are usually written in
+ <productname>Expect</productname> using Tcl, but you can also use
+ a Tcl script to run a testsuite 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>
+
+ </sect2>
+
+ <sect2 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 built-in 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>Windows support. There is beta level support for
+ Windows that is still a work in progress. This requires the
+ <ulink url="http://www.cygwin.com/">Cygwin</ulink> POSIX
+ subsystem for Windows.</para></listitem>
+
+ </itemizedlist>
+
+ <sect3 id="cygwin" xreflabel="Windows Support">
+ <title>Windows Support</title>
+
+ <para>To use DejaGnu on Windows, you need to first install the
+ <ulink url="http://www.cygwin.com/">Cygwin</ulink>
+ release. This works as of the B20.1 release. Cygwin is a POSIX
+ system for Windows. This covers both utility programs and a library
+ that adds POSIX system calls to Windows. Among them is pseudo tty
+ support for Windows that emulates the POSIX pty standard. The
+ latest Cygwin is always available from <ulink
+ url="http://www.cygwin.com/">this location</ulink>. This
+ works well enough to run <emphasis>"make check"</emphasis> of
+ the GNU development tree on Windows after a native build. But the
+ nature of ptys on Windows is still evolving. Your mileage may
+ vary.</para>
+
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="designgoals" xreflabel="Design Goals">
+ <title>Design Goals</title>
+
+ <para>DejaGnu grew out of the internal needs of Cygnus Solutions,
+ the company formerly known as Cygnus Support. Cygnus maintained
+ and enhanced a variety of free programs in many different
+ environments and we needed a testing tool that:</para>
+
+ <itemizedlist mark="bullet">
+ <listitem><para>was useful to developers while fixing
+ bugs;</para></listitem>
+ <listitem><para>automated running many tests during a software
+ release process;</para></listitem>
+ <listitem><para>was portable among a variety of host
+ computers;</para></listitem>
+ <listitem><para>supported cross-development
+ testing;</para></listitem>
+ <listitem><para>permitted testing interactive programs, like
+ <command>GDB</command>; and </para></listitem>
+ <listitem><para>permitted testing batch oriented programs, like
+ <command>GCC</command>.</para></listitem>
+ </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. 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>
+
+ </sect2>
+
+ <sect2 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. Rob Savoye was a member of that committee.</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 day or night. It is important to note
+ that the standard being tested is never 1003.3; the standard being tested
+ is some other standard, for which the assertions were written.</para>
+
+ <para>As there is no testsuite to test testing frameworks for POSIX
+ 1003.3 conformance, verifying conformance to this standard is done by
+ repeatedly reading the standard and experimenting. One of the main
+ things 1003.3 does specify is the set of allowed output messages and
+ their definitions. Four messages are supported for a required feature of
+ POSIX conforming systems and a fifth for a conditional feature. DejaGnu
+ supports the use of all five output messages. In this sense a testsuite
+ that uses exactly these messages can be considered POSIX conforming.
+ These definitions specify the output of a test
+ case:</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 commands 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></listitem>
+
+ </varlistentry>
+ </variablelist>
+
+ <itemizedlist>
+ <listitem><para>A test's execution is
+ interrupted.</para></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>
+
+ <variablelist>
+ <varlistentry>
+ <term>UNTESTED</term>
+ <listitem><para>A test was not run. This is a place-holder, used
+ when there is no real test case yet.</para></listitem>
+ </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.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>DejaGnu uses the same output procedures to produce these messages
+ for all testsuites and these procedures are already known to conform
+ to POSIX 1003.3. For a DejaGnu testsuite to conform to POSIX 1003.3,
+ you must avoid the <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>
+ </sect2>
+ </sect1>
+
+ <!-- include the user manual -->
+ &user;
+
+ <!-- include the reference manual -->
+ &ref;
+
+</article>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
+sgml-general-insert-case:lower
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:nil
+sgml-parent-document:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->
--- /dev/null
+ <legalnotice id="legalnotice">
+ <para>
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation
+ License (GFDL), Version 1.1 or any later version published
+ by the Free Software Foundation with no Invariant Sections,
+ no Front-Cover Texts, and no Back-Cover Texts. You can find
+ a copy of the GFDL at this <ulink type="help"
+ url="ghelp:fdl">link</ulink> or in the file COPYING-DOCS
+ distributed with this manual.
+ </para>
+ <para> This manual is part of a collection of GNOME manuals
+ distributed under the GFDL. If you want to distribute this
+ manual separately from the collection, you can do so by
+ adding a copy of the license to the manual, as described in
+ section 6 of the license.
+ </para>
+
+ <para>
+ Many of the names used by companies to distinguish their
+ products and services are claimed as trademarks. Where those
+ names appear in any GNOME documentation, and the members of
+ the GNOME Documentation Project are made aware of those
+ trademarks, then the names are in capital letters or initial
+ capital letters.
+ </para>
+
+ <para>
+ DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED
+ UNDER THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE
+ WITH THE FURTHER UNDERSTANDING THAT:
+
+ <orderedlist>
+ <listitem>
+ <para>DOCUMENT IS PROVIDED ON AN "AS IS" BASIS,
+ WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR
+ IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES
+ THAT THE DOCUMENT OR MODIFIED VERSION OF THE
+ DOCUMENT IS FREE OF DEFECTS MERCHANTABLE, FIT FOR
+ A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE
+ RISK AS TO THE QUALITY, ACCURACY, AND PERFORMANCE
+ OF THE DOCUMENT OR MODIFIED VERSION OF THE
+ DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR
+ MODIFIED VERSION PROVE DEFECTIVE IN ANY RESPECT,
+ YOU (NOT THE INITIAL WRITER, AUTHOR OR ANY
+ CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY
+ SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER
+ OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS
+ LICENSE. NO USE OF ANY DOCUMENT OR MODIFIED
+ VERSION OF THE DOCUMENT IS AUTHORIZED HEREUNDER
+ EXCEPT UNDER THIS DISCLAIMER; AND
+ </para>
+ </listitem>
+ <listitem>
+ <para>UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL
+ THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE),
+ CONTRACT, OR OTHERWISE, SHALL THE AUTHOR,
+ INITIAL WRITER, ANY CONTRIBUTOR, OR ANY
+ DISTRIBUTOR OF THE DOCUMENT OR MODIFIED VERSION
+ OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH
+ PARTIES, BE LIABLE TO ANY PERSON FOR ANY
+ DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR
+ CONSEQUENTIAL DAMAGES OF ANY CHARACTER
+ INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS
+ OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR
+ MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR
+ LOSSES ARISING OUT OF OR RELATING TO USE OF THE
+ DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT,
+ EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF
+ THE POSSIBILITY OF SUCH DAMAGES.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </legalnotice>
+
--- /dev/null
+
+<sect1 id="reference">
+ <title>Reference</title>
+
+ <sect2 id="obtaining" xreflabel="Obtaining DejaGnu">
+ <title>Obtaining DejaGnu</title>
+
+ <para>You can obtain DejaGnu from the DejaGnu web site at the
+ <ulink url="http://www.gnu.org">Free Software Foundation</ulink>,
+ which is at <ulink
+ url="http://www.gnu.org/software/dejagnu/">www.gnu.org/software/dejagnu/
+ </ulink></para>
+
+ </sect2>
+
+ <sect2 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>
+
+ <sect3 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-&version;/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 testsuites; these are available
+ separately. Testsuites for the GNU development tools are included in
+ those releases. After configuring the top-level DejaGnu directory, unpack
+ and configure the test directories for the tools you want to test; then,
+ in each test directory, run <emphasis>make check</emphasis> to build
+ auxiliary programs required by some of the tests, and run the test
+ suites.</para>
+
+ </sect3>
+
+ <sect3 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.</para></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.</para></listitem>
+
+ <listitem><para>Copy the <emphasis>runtest</emphasis> shell script into
+ <filename>$exec_prefix/bin</filename>.</para></listitem>
+
+ <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>
+ </sect3>
+ </sect2>
+
+ <sect2 id="builtins" xreflabel="Builtin Procedures">
+ <title>Builtin Procedures</title>
+
+ <para>DejaGnu provides these Tcl procedures.</para>
+
+ <sect3 id="coreprocs" xreflabel="Core Internal Procedures">
+ <title>Core Internal Procedures</title>
+
+ <sect4 id="mailfile" xreflabel="mail_file procedure">
+ <title>Mail_file Procedure</title>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>mail_file</function></funcdef>
+ <paramdef><parameter>file to
+ subject</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="openlogs" xreflabel="open_logs procedure">
+ <title>Open_logs Procedure</title>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>open_logs</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 id="closelogs" xreflabel="close_logs procedure">
+ <title>Close_logs Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>close_logs</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>isbuild</function></funcdef>
+ <paramdef><parameter>pattern</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>pattern</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="isremote" xreflabel="is_remote procedure">
+ <title>Is_remote Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>is_remote</function></funcdef>
+ <paramdef><parameter>board</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>is3way</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>ishost</function></funcdef>
+ <paramdef><parameter>pattern</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>istarget</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>isnative</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 id="unknown" xreflabel="unknown procedure">
+ <title>Unknown Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>unknown</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="cloneoutput" xreflabel="clone_output procedure">
+ <title>Clone_output Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>clone_output</function></funcdef>
+ <paramdef><parameter>message</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>message</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="resetvars" xreflabel="reset_vars procedure">
+ <title>Reset_vars Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>reset_vars</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 id="logandexit" xreflabel="log_and_exit procedure">
+ <title>Log_and_exit Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>log_and_exit</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 id="logsummary" xreflabel="log_summary procedure">
+ <title>Log_summary Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>log_summary</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="cleanup" xreflabel="cleanup procedure">
+ <title>Cleanup Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>cleanup</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>setup_xfail</function></funcdef>
+ <paramdef><parameter>config</parameter>
+ <parameter>bugid</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="recordtest" xreflabel="record_test procedure">
+ <title>Record_test Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>record_test</function></funcdef>
+ <paramdef><parameter>type</parameter>
+ <parameter>message</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>pass</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this PASS
+ message.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>fail</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this FAIL
+ message.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>xpass</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this output
+ state.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>xpass</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this output
+ state.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>set_warning_threshold</function></funcdef>
+ <paramdef><parameter>threshold</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>threshold</parameter></term>
+ <listitem><para>This is the value of the new warning
+ threshold.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>get_warning_threshold</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ </sect4>
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>warning</function></funcdef>
+ <paramdef><parameter>string</parameter>
+ <parameter>number</parameter>
+ </paramdef>
+ </funcprototype>
+ </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>
+
+ </sect4>
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>perror</function></funcdef>
+ <paramdef><parameter>string</parameter>
+ <parameter>number</parameter>
+ </paramdef>
+ </funcprototype>
+ </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>
+
+ </sect4>
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>note</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this note.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>untested</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this output
+ state.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>unresolved</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this output
+ state.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>unsupported</function></funcdef>
+ <paramdef><parameter>string</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem><para>The string to use for this output
+ state.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="inittestcounts" xreflabel="init_testcounts procedure">
+ <title>Init_testcounts Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>init_testcounts</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 id="incrcount" xreflabel="incr_count procedure">
+ <title>Incr_count Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>incr_count</function></funcdef>
+ <paramdef><parameter>name</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>transform</function></funcdef>
+ <paramdef><parameter>toolname</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>toolname</parameter></term>
+ <listitem><para>The name of the cross-development program to
+ transform.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+
+ <sect4 id="checkconditionalxfail" xreflabel="check_conditional_xfail procedure">
+ <title>Check_conditional_xfail Procedure</title>
+
+ <para>This procedure adds a conditional xfail, based on compiler
+ options used to create a test case executable. If an include options
+ is found in the compiler flags, and it's the right architecture,
+ it'll trigger an <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">
+ <funcprototype>
+ <funcdef><function>check_conditional_xfail</function></funcdef>
+ <paramdef><parameter>message</parameter>
+ <parameter>targets</parameter>
+ <parameter>includes</parameter>
+ <parameter>excludes</parameter></paramdef>
+ </funcprototype>
+ </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 the list of
+ sets of options is empty or if any set of the options matches,
+ then this conditional is true. (It may be useful to specify an
+ empty list of include sets if the conditional is always true
+ unless one of the exclude sets matches.)</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>
+
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>clear_xfail</function></funcdef>
+ <paramdef><parameter>config</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>config</parameter></term>
+ <listitem><para>The configuration triplets to
+ clear.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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>-x</option> argument to log the test results into
+ a parsable XML file. 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">
+ <funcprototype>
+ <funcdef><function>verbose</function></funcdef>
+ <paramdef><parameter>-log</parameter>
+ <parameter>-x</parameter>
+ <parameter>-n</parameter>
+ <parameter>-r</parameter>
+ <parameter>string</parameter>
+ <parameter>number</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>-x</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ <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>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>load_lib</function></funcdef>
+ <paramdef><parameter>filespec</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>filespec</parameter></term>
+ <listitem><para>The name of the DejaGnu library file to
+ load.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ </sect3>
+
+ <sect3 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>
+
+ <sect4 id="callremote" xreflabel="call_remote procedure">
+ <title>Call_remote Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>call_remote</function></funcdef>
+ <paramdef><parameter>type</parameter>
+ <parameter>proc</parameter>
+ <parameter>dest</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="checkforboardstatus" xreflabel="check_for_board_status
+ procedure">
+ <title>Check_for_board_status Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>check_for_board_status</function></funcdef>
+ <paramdef><parameter>variable</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>variable</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="fileonbuild" xreflabel="file_on_build procedure">
+ <title>File_on_build Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>file_on_build</function></funcdef>
+ <paramdef><parameter>op</parameter>
+ <parameter>file</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="fileonhost" xreflabel="file_on_host procedure">
+ <title>File_on_host Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>file_on_host</function></funcdef>
+ <paramdef><parameter>op</parameter>
+ <parameter>file</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="localexec" xreflabel="local_exec procedure">
+ <title>Local_exec Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>local_exec</function></funcdef>
+ <paramdef><parameter>commandline</parameter>
+ <parameter>inp</parameter>
+ <parameter>outp</parameter>
+ <parameter>timeout</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remotebinary" xreflabel="remote_binary procedure">
+ <title>Remote_binary Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_binary</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="remoteclose" xreflabel="remote_close procedure">
+ <title>Remote_close Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_close</function></funcdef>
+ <paramdef><parameter>shellid</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remotedownload" xreflabel="remote_download procedure">
+ <title>Remote_download Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_download</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remoteexec" xreflabel="remote_exec procedure">
+ <title>Remote_exec Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_exec</function></funcdef>
+ <paramdef><parameter>hostname</parameter>
+ <parameter>program</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remoteexpect" xreflabel="remote_expect procedure">
+ <title>Remote_expect Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_expect</function></funcdef>
+ <paramdef><parameter>board</parameter>
+ <parameter>timeout</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remotefile" xreflabel="remote_file procedure">
+ <title>Remote_file Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_file</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remoteld" xreflabel="remote_ld procedure">
+ <title>Remote_ld Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_ld</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>prog</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remoteload" xreflabel="remote_load procedure">
+ <title>Remote_load Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_load</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>prog</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remoteopen" xreflabel="remote_open procedure">
+ <title>Remote_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_open</function></funcdef>
+ <paramdef><parameter>type</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remotepopconn" xreflabel="remote_pop_conn procedure">
+ <title>Remote_pop_conn Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_pop_conn</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="remotepushconn" xreflabel="remote_push_conn procedure">
+ <title>Remote_push_conn Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_push_conn</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="remoterawbinary" xreflabel="remote_raw_binary procedure">
+ <title>Remote_raw_binary Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_raw_binary</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="remoterawclose" xreflabel="remote_raw_close procedure">
+ <title>Remote_raw_close Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_raw_close</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="remoterawfile" xreflabel="remote_raw_file procedure">
+ <title>Remote_raw_file Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_raw_file</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remoterawld" xreflabel="remote_raw_ld procedure">
+ <title>remote_raw_ld Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_raw_ld</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>prog</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remoterawload" xreflabel="remote_raw_load procedure">
+ <title>Remote_raw_load Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_raw_load</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>prog</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remoterawopen" xreflabel="remote_raw_open procedure">
+ <title>Remote_raw_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_raw_open</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="remoterawsend" xreflabel="remote_raw_send procedure">
+ <title>Remote_raw_send Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_raw_send</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>string</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remoterawspawn" xreflabel="remote_raw_spawn procedure">
+ <title>Remote_raw_spawn Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_raw_spawn</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>commandline</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remoterawtransmit" xreflabel="remote_raw_transmit
+ procedure">
+ <title>Remote_raw_transmit Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_raw_transmit</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remoterawwait" xreflabel="remote_raw_wait procedure">
+ <title>Remote_raw_wait Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_raw_wait</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>timeout</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remotereboot" xreflabel="remote_reboot procedure">
+ <title>Remote_reboot Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_reboot</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="remotesend" xreflabel="remote_send procedure">
+ <title>Remote_send Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_send</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>string</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remotespawn" xreflabel="remote_spawn procedure">
+ <title>Remote_spawn Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_spawn</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>commandline</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remoteswapconn" xreflabel="remote_swap_conn procedure">
+ <title>Remote_swap_conn Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_swap_conn</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="remotetransmit" xreflabel="remote_transmit procedure">
+ <title>Remote_transmit Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_transmit</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remoteupload" xreflabel="remote_upload procedure">
+ <title>Remote_upload Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_upload</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>srcfile</parameter>
+ <parameter>arg</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="remotewait" xreflabel="remote_wait procedure">
+ <title>Remote_wait Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>remote_wait</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>timeout</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="standardclose" xreflabel="standard_close procedure">
+ <title>Standard_close Procedure</title>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>standard_close</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="standarddownload" xreflabel="standard_download procedure">
+ <title>Standard_download Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>standard_download</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter>
+ <parameter>destfile</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="standardexec" xreflabel="standard_exec procedure">
+ <title>Standard_exec Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>standard_exec</function></funcdef>
+ <paramdef><parameter>hostname</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="standardfile" xreflabel="standard_file procedure">
+ <title>Standard_file Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>standard_file</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>op</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="standardload" xreflabel="standard_load procedure">
+ <title>Standard_load Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>standard_load</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>prog</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="standardreboot" xreflabel="standard_reboot procedure">
+ <title>Standard_reboot Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>standard_reboot</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="standardsend" xreflabel="standard_send procedure">
+ <title>Standard_send Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>standard_send</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>string</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="standardspawn" xreflabel="standard_spawn procedure">
+ <title>Standard_spawn Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>standard_spawn</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>commandline</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="standardtransmit" xreflabel="standard_transmit procedure">
+ <title>Standard_transmit Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>standard_transmit</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="standardupload" xreflabel="standard_upload procedure">
+ <title>Standard_upload Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>standard_upload</function></funcdef>
+ <paramdef><parameter>dest srcfile destfile</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="standardwait" xreflabel="standard_wait procedure">
+ <title>Standard_wait Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>standard_wait</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>timeout</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="unixcleanfilename" xreflabel="unix_clean_filename
+ procedure">
+ <title>Unix_clean_filename Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>unix_clean_filename</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+<!-- FIXME: this doesn't seem to exist anymore
+ <sect4 id="exitremoteshell" xreflabel="exit_remote_shell procedure">
+ <title>exit_remote_shell Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>exit_remote_shell</function></funcdef>
+ <paramdef><parameter>spawnid</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+-->
+
+ </sect3>
+
+ <sect3 id="connprocs" xreflabel="connprocs">
+ <title>Procedures For Using Utilities to Connect</title>
+
+ <para>telnet, rsh, tip, kermit</para>
+
+ <sect4 id="telnet" xreflabel="telnet procedure">
+ <title>telnet Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>telnet</function></funcdef>
+ <paramdef><parameter>hostname</parameter>
+ <parameter>port</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>rlogin</function></funcdef>
+ <paramdef><parameter>hostname</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 id="rsh" xreflabel="rsh procedure">
+ <title>rsh Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>rsh</function></funcdef>
+ <paramdef><parameter>hostname</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="tip" xreflabel="tip procedure">
+ <title>Tip Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>tip</function></funcdef>
+ <paramdef><parameter>port</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="kermit" xreflabel="kermit procedure">
+ <title>Kermit Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>kermit</function></funcdef>
+ <paramdef><parameter>port</parameter>
+ <parameter>bps</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="kermitopen" xreflabel="kermit_open procedure">
+ <title>kermit_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>kermit_open</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="kermitcommand" xreflabel="kermit_command procedure">
+ <title>Kermit_command Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>kermit_command</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="kermitsend" xreflabel="kermit_send procedure">
+ <title>Kermit_send Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>kermit_send</function></funcdef>
+ <paramdef><parameter>dest string args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="kermittransmit" xreflabel="kermit_transmit procedure">
+ <title>Kermit_transmit Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>kermit_transmit</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="telnetopen" xreflabel="telnet_open procedure">
+ <title>Telnet_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>telnet_open</function></funcdef>
+ <paramdef><parameter>hostname</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="telnetbinary" xreflabel="telnet_binary procedure">
+ <title>Telnet_binary Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>telnet_binary</function></funcdef>
+ <paramdef><parameter>hostname</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>hostname</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="telnettransmit" xreflabel="telnet_transmit procedure">
+ <title>Telnet_transmit Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>telnet_transmit</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>file</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="tipopen" xreflabel="tip_open procedure">
+ <title>Tip_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>tip_open</function></funcdef>
+ <paramdef><parameter>hostname</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>hostname</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="rloginopen" xreflabel="rlogin_open procedure">
+ <title>Rlogin_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>rlogin_open</function></funcdef>
+ <paramdef><parameter>arg</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>arg</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="rloginspawn" xreflabel="rlogin_spawn procedure">
+ <title>Rlogin_spawn Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>rlogin_spawn</function></funcdef>
+ <paramdef><parameter>dest</parameter>
+ <parameter>cmdline</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="rshopen" xreflabel="rsh_open procedure">
+ <title>Rsh_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>rsh_open</function></funcdef>
+ <paramdef><parameter>hostname</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>hostname</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="rshdownload" xreflabel="rsh_download procedure">
+ <title>Rsh_download Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>rsh_download</function></funcdef>
+ <paramdef><parameter>desthost</parameter>
+ <parameter>srcfile</parameter>
+ <parameter>destfile</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="rshupload" xreflabel="rsh_upload procedure">
+ <title>Rsh_upload Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>rsh_upload</function></funcdef>
+ <paramdef><parameter>desthost</parameter>
+ <parameter>srcfile</parameter>
+ <parameter>destfile</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="rshexec" xreflabel="rsh_exec procedure">
+ <title>Rsh_exec Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>rsh_exec</function></funcdef>
+ <paramdef><parameter>boardname</parameter>
+ <parameter>cmd</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="ftpopen" xreflabel="ftp_open procedure">
+ <title>Ftp_open Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>ftp_open</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="ftpupload" xreflabel="ftp_upload procedure">
+ <title>Ftp_upload Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>ftp_upload</function></funcdef>
+ <paramdef><parameter>host</parameter>
+ <parameter>remotefile</parameter>
+ <parameter>localfile</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="ftpdownload" xreflabel="ftp_download procedure">
+ <title>Ftp_download Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>ftp_download</function></funcdef>
+ <paramdef><parameter>host</parameter>
+ <parameter>localfile</parameter>
+ <parameter>remotefile</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="ftpclose" xreflabel="ftp_close procedure">
+ <title>Ftp_close Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>ftp_close</function></funcdef>
+ <paramdef><parameter>host</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="tipdownload" xreflabel="tip_download procedure">
+ <title>Tip_download Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>tip_download</function></funcdef>
+ <paramdef><parameter>spawnid</parameter>
+ <parameter>file</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+ </sect3>
+
+ <sect3 id="targetprocs">
+ <title>Procedures For Target Boards</title>
+
+ <para></para>
+
+ <sect4 id="defaultlink" xreflabel="default_link procedure">
+ <title>Default_link Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>default_link</function></funcdef>
+ <paramdef><parameter>board</parameter>
+ <parameter>objects</parameter>
+ <parameter>destfile</parameter>
+ <parameter>flags</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="defaulttargetassemble" xreflabel="default_target_assemble
+ procedure">
+ <title>Default_target_assemble Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>default_target_assemble</function></funcdef>
+ <paramdef><parameter>source</parameter>
+ <parameter>destfile</parameter>
+ <parameter>flags</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="defaulttargetcompile" xreflabel="default_target_compile
+ procedure">
+ <title>default_target_compile Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>default_target_compile</function></funcdef>
+ <paramdef><parameter>source</parameter>
+ <parameter>destfile</parameter>
+ <parameter>type</parameter>
+ <parameter>options</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="popconfig" xreflabel="pop_config procedure">
+ <title>Pop_config Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>pop_config</function></funcdef>
+ <paramdef><parameter>type</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>type</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="prunewarnings" xreflabel="prune_warnings procedure">
+ <title>Prune_warnings Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>prune_warnings</function></funcdef>
+ <paramdef><parameter>text</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>text</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="pushbuild" xreflabel="push_build procedure">
+ <title>Push_build Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>push_build</function></funcdef>
+ <paramdef><parameter>name</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="pushconfig" xreflabel="push_config procedure">
+ <title>push_config Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>push_config</function></funcdef>
+ <paramdef><parameter>type</parameter>
+ <parameter>name</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="reboottarget" xreflabel="reboot_target procedure">
+ <title>Reboot_target Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>reboot_target</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 id="targetassemble" xreflabel="target_assemble procedure">
+ <title>Target_assemble Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>target_assemble</function></funcdef>
+ <paramdef><parameter>source destfile flags</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="targetcompile" xreflabel="target_compile procedure">
+ <title>Target_compile Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>target_compile</function></funcdef>
+ <paramdef><parameter>source</parameter>
+ <parameter>destfile</parameter>
+ <parameter>type</parameter>
+ <parameter>options</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+ </sect3>
+
+ <sect3 id="targetdb" xreflabel="target database library file ">
+ <title>Target Database Procedures</title>
+
+ <sect4 id="boardinfo" xreflabel="board_info procedure">
+ <title>Board_info Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>board_info</function></funcdef>
+ <paramdef><parameter>machine</parameter>
+ <parameter>op</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="hostinfo" xreflabel="host_info procedure">
+ <title>Host_info Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>host_info</function></funcdef>
+ <paramdef><parameter>op</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="setboardinfo" xreflabel="set_board_info procedure">
+ <title>Set_board_info Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>set_board_info</function></funcdef>
+ <paramdef><parameter>entry</parameter>
+ <parameter>value</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="setcurrtargetinfo" xreflabel="set_currtarget_info
+ procedure">
+ <title>Set_currtarget_info Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>set_currtarget_info</function></funcdef>
+ <paramdef><parameter>entry</parameter>
+ <parameter>value</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="targetinfo" xreflabel="target_info procedure">
+ <title>Target_info Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>target_info</function></funcdef>
+ <paramdef><parameter>op</parameter>
+ <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 id="unsetboardinfo" xreflabel="unset_board_info procedure">
+ <title>Unset_board_info Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>unset_board_info</function></funcdef>
+ <paramdef><parameter>entry</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>entry</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="unsetcurrtargetinfo" xreflabel="unset_currtarget_info
+ procedure">
+ <title>Unset_currtarget_info Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>unset_currtarget_info</function></funcdef>
+ <paramdef><parameter>entry</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>entry</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>push_target</function></funcdef>
+ <paramdef><parameter>name</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem><para>The name of the target to make current
+ connection.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="poptarget" xreflabel="poptarget procedure">
+ <title>Pop_target Procedure</title>
+
+ <para>This unsets the current target connection.</para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>pop_target</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>list_targets</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>push_host</function></funcdef>
+ <paramdef><parameter>name</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="pophost" xreflabel="pop_host procedure">
+ <title>Pop_host Procedure</title>
+
+ <para>This unsets the current host connection.</para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>pop_host</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>compile</function></funcdef>
+ <paramdef><parameter>file</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>archive</function></funcdef>
+ <paramdef><parameter>file</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>ranlib</function></funcdef>
+ <paramdef><parameter>file</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>file</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>execute_anywhere</function></funcdef>
+ <paramdef><parameter>cmdline</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>cmdline</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ </sect3>
+ <sect3 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 testsuite.</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>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>${tool}_start</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>${tool}_load</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>${tool}_exit</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>${tool}_version</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ </sect3>
+
+ <sect3 id="utilprocs">
+ <title>Utility Procedures</title>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>getdirs</function></funcdef>
+ <paramdef><parameter>rootdir</parameter>
+ <parameter>pattern</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>find</function></funcdef>
+ <paramdef><parameter>rootdir</parameter>
+ <parameter>pattern</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>which</function></funcdef>
+ <paramdef><parameter>file</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>binary</parameter></term>
+ <listitem><para>The executable program or shell script to look
+ for.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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>.)</para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>grep</function></funcdef>
+ <paramdef><parameter>filename</parameter>
+ <parameter>regexp</parameter>
+ <parameter>--line</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>prune</function></funcdef>
+ <paramdef><parameter>list</parameter>
+ <parameter>pattern</parameter></paramdef>
+ </funcprototype>
+ </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>
+
+ </sect4>
+
+ <sect4 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 Windows if you have Cygwin or another Unix subsystem for Windows
+ installed.</para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>slay</function></funcdef>
+ <paramdef><parameter>name</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem><para>The name of the program to kill.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>absolute</function></funcdef>
+ <paramdef><parameter>path</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>path</parameter></term>
+ <listitem><para>The path to convert.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>psource</function></funcdef>
+ <paramdef><parameter>file</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>filename</parameter></term>
+ <listitem><para>The filename to Tcl script to
+ source.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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 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. The second is the
+ pathname of the current testcase under consideration. This is used
+ by tools like compilers where each testcase is a file.</para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>runtest_file_p</function></funcdef>
+ <paramdef><parameter>runtests</parameter>
+ <parameter>testcase</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>runtests</parameter></term>
+ <listitem><para>The list of patterns to compare against.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>testcase</parameter></term>
+ <listitem><para>The test case filename.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>diff</function></funcdef>
+ <paramdef><parameter>file_1</parameter>
+ <parameter>file_2</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>setenv</function></funcdef>
+ <paramdef><parameter>var</parameter>
+ <parameter>val</parameter></paramdef>
+ </funcprototype>
+ </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>
+
+ </sect4>
+ <sect4 id="unsetenv" xreflabel="unsetenv procedure">
+ <title>unsetenv Procedure</title>
+
+ <para>Unsets the environment variable
+ <emphasis>var</emphasis>.</para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>unsetenv</function></funcdef>
+ <paramdef><parameter>var</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>var</parameter></term>
+ <listitem><para>The environment variable to
+ unset.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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.</para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>getenv</function></funcdef>
+ <paramdef><parameter>var</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>var</parameter></term>
+ <listitem><para>The environment variable to get the value
+ of.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect4>
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>prune_system_crud</function></funcdef>
+ <paramdef><parameter>system</parameter>
+ <parameter>test</parameter></paramdef>
+ </funcprototype>
+ </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>
+ </sect4>
+
+ </sect3>
+
+ <sect3 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>
+
+ <sect4 id="libglosslinkflags" xreflabel="libgloss_link_flags procedure">
+ <title>Libgloss_link_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>libgloss_link_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="libglossincludeflags" xreflabel="libgloss_include_flags
+ procedure">
+ <title>Libgloss_include_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>libgloss_include_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="newliblinkflags" xreflabel="newlib_link_flags procedure">
+ <title>Newlib_link_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>newlib_link_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="newlibincludeflags" xreflabel="newlib_include_flags
+ procedure">
+ <title>Newlib_include_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>newlib_include_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="libioincludeflags" xreflabel="libio_include_flags
+ procedure">
+ <title>Libio_include_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>libio_include_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="libiolinkflags" xreflabel="libio_link_flags procedure">
+ <title>Libio_link_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>libio_link_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="gxxincludeflags" xreflabel="g++_include_flags procedure">
+ <title>G++_include_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>g++_include_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="gxxlinkflags" xreflabel="g++_link_flags procedure">
+ <title>G++_link_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>g++_link_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="libstdcxxincludeflags" xreflabel="libstdc++_include_flags
+ procedure">
+ <title>Libstdc++_include_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>libstdc++_include_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="libstdcxxlinkflags" xreflabel="libstdc++_link_flags
+ procedure">
+ <title>Libstdc++_link_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>libstdc++_link_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="getmultilibs" xreflabel="get_multilibs procedure">
+ <title>Get_multilibs Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>get_multilibs</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="findbinutilsprog" xreflabel="find_binutils_prog procedure">
+ <title>Find_binutils_prog Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>find_binutils_prog</function></funcdef>
+ <paramdef><parameter>name</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="findgcc" xreflabel="find_gcc procedure">
+ <title>Find_gcc Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>find_gcc</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 id="findgcj" xreflabel="find_gcj procedure">
+ <title>Find_gcj Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>find_gcj</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 id="findgxx" xreflabel="find_g++ procedure">
+ <title>Find_g++ Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>find_g++</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 id="findg77" xreflabel="find_g77 procedure">
+ <title>Find_g77 Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>find_g77</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 id="processmultiliboptions" xreflabel="process_multilib_options
+ procedure">
+ <title>Process_multilib_options Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>process_multilib_options</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="addmultiliboption" xreflabel="add_multilib_option
+ procedure">
+ <title>Add_multilib_option Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>add_multilib_option</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="findgas" xreflabel="find_gas procedure">
+ <title>Find_gas Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>find_gas</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 id="findld" xreflabel="find_ld procedure">
+ <title>Find_ld Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>find_ld</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect4>
+
+ <sect4 id="buildwrapper" xreflabel="build_wrapper procedure">
+ <title>Build_wrapper Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>build_wrapper</function></funcdef>
+ <paramdef><parameter>gluefile</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>gluefile</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="winsupincludeflags" xreflabel="winsup_include_flags
+ procedure">
+ <title>Winsup_include_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>winsup_include_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="winsuplinkflags" xreflabel="winsup_link_flags procedure">
+ <title>Winsup_link_flags Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>winsup_link_flags</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+ </sect3>
+
+ <sect3 id="debugprocs" xreflabel="Debugging Procedures">
+ <title>Procedures for debugging your Tcl code.</title>
+
+ <para><filename>lib/debugger.exp</filename>defines these utility
+ procedures:</para>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>dumpvars</function></funcdef>
+ <paramdef><parameter>vars</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>vars</parameter></term>
+ <listitem><para>The variables to dump.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>dumplocals</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>dumprocs</function></funcdef>
+ <paramdef><parameter>pattern</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>pattern</parameter></term>
+ <listitem><para>The csh "glob" style pattern to look
+ for.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>dumpwatch</function></funcdef>
+ <paramdef><parameter>pattern</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>pattern</parameter></term>
+ <listitem><para>The csh "glob" style pattern to look
+ for.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="watcharray" xreflabel="watcharray procedure">
+ <title>Watcharray Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>watcharray</function></funcdef>
+ <paramdef><parameter>element</parameter>
+ <parameter>type</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>type</parameter></term>
+ <listitem><para>The csh "glob" style pattern to look
+ for.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 id="watchvar" xreflabel="watchvar procedure">
+ <title>Watchvar Procedure</title>
+
+ <para></para>
+
+ <funcsynopsis role="tcl">
+ <funcprototype>
+ <funcdef><function>watchvar</function></funcdef>
+ <paramdef><parameter>var</parameter>
+ <parameter>type</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>watchunset</function></funcdef>
+ <paramdef><parameter>arg</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>watchwrite</function></funcdef>
+ <paramdef><parameter>var</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>var</parameter></term>
+ <listitem><para>The variable to watch.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>watchread</function></funcdef>
+ <paramdef><parameter>var</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>var</parameter></term>
+ <listitem><para>The variable to watch.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>watchdel</function></funcdef>
+ <paramdef><parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>print</function></funcdef>
+ <paramdef><parameter>var</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>var</parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ <sect4 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">
+ <funcprototype>
+ <funcdef><function>quit</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter></parameter></term>
+ <listitem><para></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect4>
+
+ </sect3>
+
+ </sect2>
+
+ <sect2 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>
+ <listitem><para>lib/dejagnu.exp</para></listitem>
+ </itemizedlist>
+
+ </sect2>
+
+</sect1>
+
+<sect1 id="unittestapi" xreflabel="Unit Testing API">
+ <title>Unit Testing API</title>
+
+ <sect2 id="cunit" xreflabel="C Unit Testing API">
+ <title>C Unit Testing API</title>
+
+ <para>All of the functions that take a
+ <parameter>msg</parameter> parameter use a C char * that is
+ the message to be dislayed. There currently is no support for
+ variable length arguments.</para>
+
+
+ <sect3 id="passfunc" xreflabel="pass function">
+ <title>Pass Function</title>
+
+ <para>This prints a message for a successful test
+ completion.</para>
+
+ <funcsynopsis role="C">
+ <funcprototype>
+ <funcdef><function>pass</function></funcdef>
+ <paramdef><parameter>msg</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ </sect3>
+
+ <sect3 id="failfunc" xreflabel="fail function">
+ <title>Fail Function</title>
+
+ <para>This prints a message for an unsuccessful test
+ completion.</para>
+
+ <funcsynopsis role="C">
+ <funcprototype>
+ <funcdef><function>fail</function></funcdef>
+ <paramdef><parameter>msg</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ </sect3>
+
+ <sect3 id="untestedfunc" xreflabel="untested function">
+ <title>Untested Function</title>
+
+ <para>This prints a message for an test case that isn't run
+ for some technical reason.</para>
+
+ <funcsynopsis role="C">
+ <funcprototype>
+ <funcdef><function>untested</function></funcdef>
+ <paramdef><parameter>msg</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id="unresolvedfunc" xreflabel="unresolved function">
+ <title>Unresolved Function</title>
+
+ <para>This prints a message for an test case that is run,
+ but there is no clear result. These output states require a
+ human to look over the results to determine what happened.
+ </para>
+
+ <funcsynopsis role="C">
+ <funcprototype>
+ <funcdef><function>unresolved</function></funcdef>
+ <paramdef><parameter>msg</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id="totalsfunc" xreflabel="totals function">
+ <title>Totals Function</title>
+
+ <para>This prints out the total numbers of all the test
+ state outputs.</para>
+
+ <funcsynopsis role="C">
+ <funcprototype>
+ <funcdef><function>totals</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="cppunit" xreflabel="C++ Unit Testing API">
+ <title>C++ Unit Testing API</title>
+
+ <para>All of the methods that take a
+ <parameter>msg</parameter> parameter use a C char *
+ or STL string, that is the message to be
+ dislayed. There currently is no support for variable
+ length arguments.</para>
+
+ <sect3 id="passmeth" xreflabel="pass method">
+ <title>Pass Method</title>
+
+ <para>This prints a message for a successful test
+ completion.</para>
+
+ <funcsynopsis role="C++">
+ <funcprototype>
+ <funcdef><function>TestState::pass</function></funcdef>
+ <paramdef><parameter>msg</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id="failmeth" xreflabel="fail method">
+ <title>Fail Method</title>
+
+ <para>This prints a message for an unsuccessful test
+ completion.</para>
+
+ <funcsynopsis role="C++">
+ <funcprototype>
+ <funcdef><function>TestState::fail</function></funcdef>
+ <paramdef><parameter>msg</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id="untestedmeth" xreflabel="untested method">
+ <title>Untested Method</title>
+
+ <para>This prints a message for an test case that isn't run
+ for some technical reason.</para>
+
+ <funcsynopsis role="C++">
+ <funcprototype>
+ <funcdef><function>TestState::untested</function></funcdef>
+ <paramdef><parameter>msg</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id="unresolvedmeth" xreflabel="unresolved method">
+ <title>Unresolved Method</title>
+
+ <para>This prints a message for an test case that is run,
+ but there is no clear result. These output states require a
+ human to look over the results to determine what happened.
+ </para>
+
+ <funcsynopsis role="C++">
+ <funcprototype>
+ <funcdef><function>TestState::unresolved</function></funcdef>
+ <paramdef><parameter>msg</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect3>
+
+ <sect3 id="totalsmeth" xreflabel="totals method">
+ <title>Totals Method</title>
+
+ <para>This prints out the total numbers of all the test
+ state outputs.</para>
+
+ <funcsynopsis role="C++">
+ <funcprototype>
+ <funcdef><function>TestState::totals</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </sect3>
+
+ </sect2>
+
+</sect1>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
+sgml-general-insert-case:lower
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:nil
+sgml-parent-document:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->
--- /dev/null
+html/index.html DejaGnu Manual
--- /dev/null
+
+ <sect1 id="gettingup">
+ <title>Getting DejaGnu up and running</title>
+
+<para>This chapter was originally written by Niklaus Giger
+ (ngiger@mus.ch) because he lost a week to figure out how DejaGnu works
+ and how to write a first test.
+</para>
+
+<para>Follow these instructions as closely a possible in order get a
+good insight into how DejaGnu works, else you might run into a lot of
+subtle problems. You have been warned.</para>
+
+<para>It should be no big problems installing DejaGnu using your
+package manager or from the source code. Under a Debian/GNU/Linux
+systems just type (as root) <programlisting>apt-get
+dejagnu</programlisting>. These examples were run on a primary machine
+with a AMD K6 and a Mac Powerbook G3 serving as a remote
+target.</para>
+
+<para> The tests for Windows were run under Windows NT using the
+actual Cygwin version (1.3.x as of October 2001). It's target system
+was a PPC embedded system running vxWorks.
+</para>
+
+<sect2>
+<title>Test your installation</title>
+
+<para>Create a new user called "dgt" (DejaGnuTest), which uses bash as
+it login shell. PS1 must be set to '\u:\w\$ ' in its ~/.bashrc. Login
+as this user, create an empty directory and change the working
+directory to it. e.g</para>
+
+<programlisting>
+dgt:~$ mkdir ~/dejagnu.test
+dgt:~$ cd ~/dejagnu.test
+</programlisting>
+
+<para>Now you are ready to test DejaGnu's main program called
+runtest. The expecteted output is shown</para>
+
+<example>
+<title>Runtest output in a empty directory
+</title>
+
+<programlisting>
+dgt:~/dejagnu.test$ runtest
+WARNING: Couldn't find the global config file.
+WARNING: No tool specified Test
+Run By dgt on Sun Nov 25 17:07:03 2001 Native configuration is i586-pc-linux-gnu
+=== tests ===
+Schedule of variations: unix
+Running target unix Using /usr/share/dejagnu/baseboards/unix.exp as board description file for target.
+Using /usr/share/dejagnu/config/unix.exp as generic interface file for target.
+ERROR: Couldn't find tool config file for unix.
+=== Summary ===</programlisting>
+
+<para>We will show you later how to get rid of all the WARNING- and
+ERROR-messages. The files testrun.sum and testrun.log have been
+created, which do not interest us at this point. Let's remove
+them.</para>
+
+<programlisting>:~/dejagnu.test$ rm testrun.sum testrun.log
+</programlisting>
+</example>
+
+<sect3>
+<title>Windows</title>
+
+<para>On Windows systems DejaGnu is part of a port of a lot of Unix
+tools to the Windows OS, called Cygwin. Cygwin may be downloaded and
+installed from a mirror of http://www.cygwin.com/. All examples were
+also run on Windows NT. If nothing is said, you can assume that you
+should get the same output as on a Unix system.</para>
+
+<para>You will need a telnet daemon if you want to use a Windows box
+as a remote target. There seems to be a freeware telnet daemon at
+http://www.fictional.net/.</para>
+</sect3>
+
+<sect3>
+<title>Getting the source code for the calc example</title>
+
+<para>If you are running a Debian distribution you can find the
+examples under /usr/share/doc/dejagnu/examples. These examples seem to
+be missing in Red Hat's RPM. In this case download the sources of
+DejaGnu and adjust the pathes to the DejaGnu examples
+accordingly.</para>
+</sect3>
+</sect2>
+
+<sect2>
+<title>Create a minimal project, e.g. calc</title>
+
+<para>In this section you will to start a small project,
+using the sample application calc, which is part of your DejaGnu
+distribution</para>
+
+<sect3><title>A simple project without the GNU autotools</title>
+
+<para>The runtest program can be run standalone. All the
+autoconf/automake support is just cause those programs are commonly
+used for other GNU applications. The key to running runtest standalone
+is having the local site.exp file setup correctly, which automake
+does.</para>
+
+<para>The generated site.exp should like like:</para>
+<programlisting>
+set tool calc
+set srcdir .
+set objdir /home/dgt/dejagnu.test
+</programlisting></sect3>
+
+<sect3>
+<title>Using autoconf/autoheader/automake</title>
+
+<para>We have to prepare some input file in order to run autocon and
+automake. There is book "GNU autoconf, automake and
+libtool" by Garry V. Vaughan, et al. NewRider, ISBN
+1-57870-190-2 which describes this process thoroughly.</para>
+
+<para>From the calc example distributed with the DejaGnu documentation
+you should copy the program file itself (calc.c) and some additional
+files, which you might examine a little bit close to derive their
+meanings.</para>
+
+<programlisting>
+dgt:~/dejagnu.test$ cp -r /usr/share/doc/dejagnu/examples/calc/\
+{configure.in,Makefile.am,calc.c,testsuite} .
+</programlisting>
+
+<para>In Makemake.am note the presence of the AUTOMAKE_OPTIONS = dejagnu. This option is needed.</para>
+
+<para>Run aclocal to generate aclocal.m4, which is a collection of
+macros needed by configure.in</para>
+
+<programlisting>
+dgt:~/dejagnu.test$ aclocal
+</programlisting>
+
+<para>autoconf is another part of the auto-tools. Run it to generate
+configure based on information contained in configure.in.</para>
+
+<programlisting>
+dgt:~/dejagnu.test$ autoconf
+</programlisting>
+
+<para>autoheader is another part of the auto-tools.
+Run it to generate calc.h.in. </para>
+
+<programlisting>
+dgt:~/dejagnu.test$ autoheader
+</programlisting>
+
+<para>The Makefile.am of this example was developed as port of the DejaGnu
+distribution.
+Adapt Makefile.am for this test. Replace the line
+"#noinst_PROGRAMS = calc" to
+"bin_PROGRAMS = calc".
+Change the RUNTESTDEFAULTFLAGS from
+"$$srcdir/testsuite" to
+"./testsuite".</para>
+
+<para>Running automake at this point contains a series of warning in
+its output as shown in the following example:</para>
+
+<example>
+<title>Sample output of automake with missing files</title>
+<programlisting>
+dgt:~/dejagnu.test$ automake --add-missing
+automake: configure.in: installing `./install-sh'
+automake: configure.in: installing `./mkinstalldirs'
+automake: configure.in: installing `./missing'
+automake: Makefile.am: installing `./INSTALL'
+automake: Makefile.am: required file `./NEWS' not found
+automake: Makefile.am: required file `./README' not found
+automake: Makefile.am: installing `./COPYING'
+automake: Makefile.am: required file `./AUTHORS' not found
+automake: Makefile.am: required file `./ChangeLog' not found
+configure.in: 4: required file `./calc.h.in' not found
+Makefile.am:6: required directory ./doc does not exist
+</programlisting>
+</example>
+
+<para>Create a empty directory doc and empty files
+INSTALL, NEWS, README, AUTHORS, ChangeLog and COPYING.
+The default COPYING will point to the GNU Public License (GPL).
+In a real project it would be time to add some meaningfull text in each file.
+</para>
+
+<para>Adapt calc to your environment by calling configure.</para>
+<example>
+<title>Sample output of configure
+</title>
+<programlisting>
+dgt:~/dejagnu.test$ ./configure
+creating cache ./config.cache
+checking whether to enable maintainer-specific portions of Makefiles... no
+checking for a BSD compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+checking whether make sets ${MAKE}... yes
+checking for working aclocal... found
+checking for working autoconf... found
+checking for working automake... found
+checking for working autoheader... found
+checking for working makeinfo... found
+checking for gcc... gcc checking whether the C compiler (gcc ) works... yes
+checking whether the C compiler (gcc ) is a cross-compiler... no
+checking whether we are using GNU C... yes
+checking whether gcc accepts -g... yes
+checking for a BSD compatible install... /usr/bin/install -c
+checking how to run the C preprocessor... gcc -E
+checking for stdlib.h... yes
+checking for strcmp... yes
+updating cache ./config.cache
+creating ./config.status
+creating Makefile creating calc.h
+</programlisting>
+</example>
+
+<para>If you are familiar with GNU software,
+this output should not contain any surprise to you.
+Any errors should be easy to fix for such a simple program.</para>
+
+<para>Build the calc executable:</para>
+
+<example>
+<title>Sample output building calc
+</title>
+<programlisting>
+dgt:~/dejagnu.test$ make
+gcc -DHAVE_CONFIG_H -I. -I. -I. -g -O2 -c calc.c
+gcc -g -O2 -o calc calc.o
+</programlisting>
+</example>
+
+<para>You prepared a few files and then called some
+commands. Respecting the right order assures a automatic and correctly
+compiled calc program. The following example resumes the correct
+order.</para>
+
+<example>
+<title>Creating the calc program using the GNU autotools</title>
+<programlisting>
+dgt:~/dejagnu.test$ aclocal
+dgt:~/dejagnu.test$ autoconf
+dgt:~/dejagnu.test$ autoheader
+dgt:~/dejagnu.test$ automake --add-missing
+dgt:~/dejagnu.test$ ./configure
+dgt:~/dejagnu.test$ make
+
+</programlisting>
+</example>
+
+<para>Play with calc and verify whether it works correctly.
+A sample session might look like this:</para>
+
+<programlisting>
+dgt:~/dejagnu.test$ ./calc
+calc: version
+Version: 1.1
+calc:<emphasis> </emphasis>add 3 4
+7
+calc: multiply 3 4<emphasis> </emphasis>
+12
+calc: multiply 2 4<emphasis> </emphasis>
+12
+calc: quit
+
+</programlisting>
+
+<para>Look at the intentional bug that 2 times 4 equals 12.</para>
+
+<para>The tests run by DejaGnu need a file called site.exp,
+which is automatically generated if we call "make
+site.exp". This was the purpose of the "AUTOMAKE_OPTIONS =
+dejagnu" in Makefile.am.</para>
+
+<example>
+<title>Sample output generating a site.exp</title>
+<programlisting>
+dgt: make site.exp
+dgt:~/dejagnu.test$ make site.exp
+Making a new site.exp file...
+</programlisting>
+</example>
+
+
+</sect3>
+</sect2>
+
+<sect2>
+<title>Our first automated tests</title>
+<sect3><title>Running the test for the calc example</title>
+
+<para>Now we are ready to call the automated tests </para>
+
+<example>
+<title>Sample output of runtest in a configured directory</title>
+
+<programlisting>
+dgt:~/dejagnu.test$ make check
+make check-DEJAGNU
+make[1]: Entering directory `/home/dgt/dejagnu.test' srcdir=`cd . && pwd`; export srcdir; \
+EXPECT=expect; export EXPECT; \ runtest=runtest; \
+if /bin/sh -c "$runtest --version" > /dev/null 2>&1; then \
+$runtest --tool calc CALC=`pwd`/calc --srcdir ./testsuite ; \
+else echo "WARNING: could not find \`runtest'" 1>&2; :;\
+fi
+WARNING: Couldn't find the global config file.
+WARNING: Couldn't find tool init file
+Test Run By dgt on Sun Nov 25 21:42:21 2001
+Native configuration is i586-pc-linux-gnu
+
+ === calc tests ===
+
+Schedule of variations:
+ unix
+
+Running target unix
+Using /usr/share/dejagnu/baseboards/unix.exp as board description file for target.
+Using /usr/share/dejagnu/config/unix.exp as generic interface file for target.
+Using ./testsuite/config/unix.exp as tool-and-target-specific interface file.
+Running ./testsuite/calc.test/calc.exp ...
+FAIL: multiply2 (bad match)
+
+=== calc Summary ===
+
+# of expected passes 5
+# of unexpected failures 1
+/home/Dgt/dejagnu.test/calc version Version: 1.1
+make[1]: *** [check-DEJAGNU] Fehler 1
+make[1]: Leaving directory `/home/Dgt/dejagnu.test' make: *** [check-am] Fehler 2
+</programlisting>
+</example>
+
+<para>Did you see the line "FAIL:"? The test cases for calc catch the bug in the calc.c file. Fix the error in calc.c later as the following examples assume a unchanged calc.c.</para>
+
+<para>Examine the output files calc.sum and calc.log. Try to
+understand the testcases written in
+~/dejagnu.test/testsuite/calc.test/calc.exp. To understand Expect you
+might take a look at the book "Exploring Expect", which is
+an excellent resource for learning and using Expect. (Pub: O'Reilly,
+ISBN 1-56592-090-2) The book contains hundreds of examples and also
+includes a tutorial on Tcl. Exploring Expect is 602 pages
+long.</para>
+
+</sect3>
+
+
+<sect3><title>The various config files or how to avoid warnings</title>
+
+<para>DejaGnu may be customized by each user. It first searches for a
+file called ~/.dejagnurc. Create the file ~/.dejagnurc and insert the
+following line:</para>
+
+<programlisting>
+puts "I am ~/.dejagnurc"
+</programlisting>
+
+<para>Rerun make check. Test whether the output contains "I am ~/.dejagnurc".
+Create ~/my_dejagnu.exp and insert the following line:</para>
+
+<programlisting>
+puts "I am ~/my_dejagnu.exp"
+</programlisting>
+
+<para>In a Bash-Shell enter</para>
+
+<programlisting>
+dgt:~/dejagnu.test$ export DEJAGNU=~/my_dejagnu.exp
+</programlisting>
+
+<para>Run "make check" again. The output should not contain
+"WARNING: Couldn't find the global config file.".
+Create the sub-directory lib. Create the file "calc.exp" in it and insert the following line:</para>
+
+<programlisting>
+puts "I am lib/calc.exp"
+</programlisting>
+
+<para>The last warning "WARNING: Couldn't find tool init file"
+should not be part of the output of make check.
+Create the directory ~/boards. Create the file ~/boards/standard.exp and insert the following line:</para>
+
+<programlisting>
+puts "I am boards/standard.exp"
+</programlisting>
+
+<para>If the variable DEJAGNU is still not empty then the (abbreviated) output of "make check" should look like this:</para>
+
+<example>
+<title>Sample output of runtest with the usual configuration files</title>
+<programlisting>
+dgt:~/dejagnu.test$ make check
+<...>
+fi
+I am ~/.dejagnurc
+I am ~/my_dejagnu.exp
+I am lib/calc.exp
+Test Run By dgt on Sun Nov 25 22:19:14 2001
+Native configuration is i586-pc-linux-gnu
+
+ === calc tests ===
+Using /home/Dgt/boards/standard.exp as standard board description\
+file for build.
+I am ~/boards/standard.exp
+Using /home/Dgt/boards/standard.exp as standard board description\
+ file for host.
+I am ~/boards/standard.exp
+
+Schedule of variations:
+ unix
+
+Running target unix
+Using /home/Dgt/boards/standard.exp as standard board description\
+ file for target.
+I am ~/boards/standard.exp
+Using /usr/share/dejagnu/baseboards/unix.exp as board description file\
+for target.
+<...>
+</programlisting>
+</example>
+
+<para>It is up to you to decide when and where to use any of the above
+mentioned config files for customizing.
+This chapters showed you where and in which order the different config
+files are run.</para>
+</sect3>
+
+<sect3>
+<title>When trouble strikes</title>
+
+<para>Calling runtest with the '-v'-flag shows you in even more details which files are searched in which order. Passing it several times gives more and more details. </para>
+<example>
+<title>Displaying details about runtest execution</title>
+<programlisting>
+runtest -v -v -v --tool calc CALC=`pwd`/calc --srcdir ./testsuite
+</programlisting>
+</example>
+
+<para>Calling runtest with the '--debug'-flag logs a lot of details to dbg.log where you can analyse it afterwards. </para>
+
+<para>In all test cases you can temporary adjust the verbosity of information by adding the following Tcl-command to any tcl file that gets loaded by
+dejagnu, for instance, ~/.dejagnurc:</para>
+
+<programlisting>
+set verbose 9
+</programlisting>
+
+</sect3>
+
+<sect3>
+<title>Testing "Hello world" locally</title>
+
+<para>This test checks, whether the built-in shell command "echo Hello world"
+ will really write "Hello world" on the console.
+Create the file ~/dejagnu.test/testsuite/calc.test/local_echo.exp.
+It should contain the following lines</para>
+
+<example>
+<title>A first (local) test case</title>
+<programlisting>
+set test "Local Hello World"
+send "echo Hello World"
+expect {
+ -re "Hello World" { pass "$test" }
+}
+</programlisting>
+</example>
+
+<para>Run runtest again and verify the output "calc.log"</para>
+</sect3>
+</sect2>
+
+<sect2>
+<title>A first remote test</title>
+
+<para>Testing remote targets is a lot trickier especially if you are using an
+ embedded target
+which has no built in support for things like a compiler, ftp server or a Bash-shell.
+Before you can test calc on a remote target you have to acquire a few basics skills.</para>
+
+<sect3>
+<title>Setup telnet to your own host</title>
+<para>The easiest remote host is usually the host you are working on.
+In this example we will use telnet to login in your own workstation.
+For security reason you should never have a telnet deamon running on
+machine connected on the internet, as password and usernames are transmitted
+ in clear text.
+We assume you know how to setup your machine for a telnet daemon.</para>
+
+<para>Next try whether you may login in your own host by issuing the
+command "telnet localhost.1". In order to be able to
+distinguish between a normal session an a telnet login add the following lines to /home/dgt/.bashrc.</para>
+
+<programlisting>
+if [ "$REMOTEHOST" ]
+then
+ PS1='remote:\w\$ '
+fi
+</programlisting>
+
+<para>Now on the machine a "remote" login looks like this:</para>
+
+<example>
+<title>Sample log of a telnet login to localhost</title>
+<programlisting>
+dgt:~/dejagnu.test$ telnet localhost
+Trying 127.0.0.1...
+Connected to 127.0.0.1.
+Escape character is '^]'.
+Debian GNU/Linux testing/unstable Linux
+K6Linux login: dgt
+Password:
+Last login: Sun Nov 25 22:46:34 2001 from localhost on pts/4
+Linux K6Linux 2.4.14 #1 Fre Nov 16 19:28:25 CET 2001 i586 unknown
+No mail.
+remote:~$ exit
+logout
+Connection closed by foreign host.
+</programlisting>
+</example>
+</sect3>
+
+<sect3>
+<title>A test case for login via telnet</title>
+<para>In order to define a correct setup we have add a line containing
+"set target unix" either to ~/.dejagnurc or to ~/my_dejagnu.exp.
+In ~/boards/standard.exp add the following four lines to define a few patterns for the DejaGnu telnet login procedure.</para>
+
+<example>
+<title>Defining a remote target board</title>
+<programlisting>
+set_board_info shell_prompt "remote:"
+set_board_info telnet_username "dgt"
+set_board_info telnet_password "top_secret"
+set_board_info hostname "localhost"
+
+</programlisting>
+</example>
+
+<para>As DejaGnu will be parsing the telnet session output for some well
+known pattern the output there are a lot of things that can go wrong.
+If you have any problems verify your setup:</para>
+<itemizedlist>
+
+<listitem>
+<para>Is <filename>/etc/motd</filename> empty?</para></listitem>
+
+<listitem>
+<para>Is <filename>/etc/issue.net</filename> empty?</para></listitem>
+
+<listitem>
+<para>Exists a empty <filename>~/.hushlogin</filename>?</para></listitem>
+
+<listitem>
+<para>The LANG environment variable must be either empty or set to "C". </para></listitem>
+
+</itemizedlist>
+<para>To test the login via telnet write a sample test case.
+Create the file ~/dejagnu.test/testsuite/calc.test/remote_echo.exp and
+add the following few lines:</para>
+
+<example>
+<title>DejaGnu script for logging in into a remote target</title>
+<programlisting>
+puts "this is remote_echo.exp target for $target "
+target_info $target
+#set verbose 9
+set shell_id [remote_open $target]
+set test "Remote login to $target"
+#set verbose 0
+puts "Spawn id for remote shell is $shell_id"
+if { $shell_id > 0 } {
+ pass "$test"
+} else {
+ fail "Remote open to $target"
+}
+</programlisting>
+</example>
+
+<para>In the runtest output you should find something like:</para>
+
+<programlisting>
+Running ./testsuite/calc.test/local_echo.exp ...
+Running ./testsuite/calc.test/remote_echoo.exp ...
+this is remote_echo.exp target is unix
+Spawn id for remote shell is exp7
+</programlisting>
+
+<para>Have again a look at calc.log to get a feeling how DejaGnu and expect
+parse the input. </para></sect3>
+
+<sect3>
+<title>Remote testing "Hello world"</title>
+
+<para>Next you will transform the above "hello world" example to
+its remote equivalent.
+This can be done by adding the following lines to our file remote_echo.exp.</para>
+
+<example>
+<title>A first (local) remote "Hello world" test</title>
+<programlisting>
+set test "Remote_send Hello World"
+set status [remote_send $target "echo \"Hello\" \"World\"\n" ]
+pass "$test"
+set test "Remote_expect Hello World"
+remote_expect $target 5 {
+ -re "Hello World" { pass "$test" }
+}
+</programlisting>
+</example>
+
+<para>Call make check. The output should contain
+"# of expected passes 9" and "# of unexcpected failures 1".</para>
+
+<para>Have a look at the procedures in /usr/share/dejagnu/remote.exp to have an overview of the offered procedures and their features. </para>
+
+<para>Now setup a real target.
+In the following example we assume as target a PowerBook running Debian.
+As above add a test user "dgt", install telnet and FTP servers.
+In order to distinguish it from the host add the line
+<programlisting>PS1='test:>'</programlisting> to /home/dgt/.bash_profile.
+Also add a corresponding entry "powerbook" to /etc/hosts and verify that you
+are able to ping, telnet and ftp to the target "powerbook".</para>
+
+<para>In order to let runtest run its test on the "powerbook" target change the following lines in ~/boards/standard.exp:</para>
+
+<example>
+<title>Board definition for a remote target</title>
+<programlisting>
+set_board_info protocol "telnet"
+set_board_info telnet_username "dgt"
+set_board_info telnet_password "top_secret"
+set_board_info shell_prompt "test:> "
+set_board_info hostname "powerbook"
+</programlisting>
+</example>
+
+<para>Now call runtest again with the same arguments and verify whether all went okay by taking a close look at calc.log.</para>
+</sect3>
+
+
+<sect3>
+<title>Transferring files from/to the target</title>
+
+<para>A simple procedure like this will do the job for you:</para>
+
+<example>
+<title>Test script to transfer a file to a remote target</title>
+<programlisting>
+set test "Remote_download"
+puts "Running Remote_download"
+# set verbose 9
+set remfile /home/dgt/dejagnu2
+
+set status [remote_download $target /home/dgt/.dejagnurc $remfile]
+if { "$status" == "" } {
+ fail "Remote download to $remfile on $target"
+} else {
+ pass "$test"
+}
+
+puts "status of remote_download ist $status"
+# set verbose 0
+</programlisting>
+</example>
+
+<para>After running runtest again, check whether the file dejagnu2 exists on the target.
+
+This example will only work if the rcp command works with your target.
+
+If you have a working FTP-server on the target you can use it by adding the
+following lines to ~/boards/standard.exp:</para>
+
+<example>
+<title>Defining a board to use FTP as file transport</title>
+<programlisting>
+set_board_info file_transfer "ftp"
+set_board_info ftp_username "dgt"
+set_board_info ftp_password "1234"
+</programlisting>
+</example>
+
+</sect3>
+
+<sect3>
+<title>Preparing for crosscompilation</title>
+
+<para>For crosscompiling you need working binutils, gcc and a base library like
+libc or glib for your target.
+It is beyond the scope of this document to describe how to get it working.
+The following examples assume a cross compiler for PowerPC which is called linux-powerpc-gcc.
+</para>
+
+<para>Add AC_CANONICAL_TARGET in dejagnu.test/configure.in at the following location. Copy config.guess from /usr/share/automake to dejagnu.test.</para>
+
+<programlisting>
+AM_CONFIG_HEADER(calc.h)
+AC_CANONICAL_TARGET([])
+AM_INIT_AUTOMAKE(calc, 1.1)
+</programlisting>
+
+<para>You need to run automake 2.5 or later.
+Depending on your installation calling autoconf2.5 instead of autoconf is not needed.
+The sequence to regenerate all files is:</para>
+
+<example>
+<title>Using autotools for cross development</title>
+<programlisting>
+$ autoconf2.5
+$ autoheader
+$ automake
+$ ./configure --host=powerpc-linux --target=powerpc-linux
+configure: WARNING: If you wanted to set the --build type, don't use --host.
+ If a cross compiler is detected then cross compile mode will be used.
+checking build system type... ./config.guess: ./config.guess: No such file or directory
+configure: error: cannot guess build type; you must specify one
+$ cp /usr/share/automake/config.guess .
+$ ./configure --host=powerpc-linux --target=powerpc-linux
+configure: WARNING: If you wanted to set the --build type, don't use --host.
+If a cross compiler is detected then cross compile mode will be used. \
+checking build system type... i586-pc-linux-gnu
+checking host system type... powerpc-unknown-linux-gnu
+<...>
+checking whether we are cross compiling... yes
+<...>
+Configuration:
+Source code location: .
+C Compiler: powerpc-linux-gcc
+C Compiler flags: -g -O2
+
+</programlisting>
+</example>
+
+<para>Everything should be ready to recompile for the target:</para>
+
+<programlisting>$ make
+powerpc-linux-gcc -DHAVE_CONFIG_H -I. -I. -I. -g -O2 -c calc.c
+powerpc-linux-gcc -g -O2 -o calc calc.o
+
+</programlisting>
+</sect3>
+
+<sect3>
+<title>Remote testing of calc</title>
+<para>Not yet written, as I have problem getting libc6-dev-powerpc to work. Probably I first have to build my cross compiler. </para>
+</sect3>
+
+<sect3>
+<title>Using Windows as host and vxWorks as target</title>
+
+<para>A more thorough walk-through will be written in a few weeks.</para>
+
+<para>In order to test the vxWorks as a target I changed boards/standards.exp to reflect my settings (IP, username, password). Then I reconfigured vxWorks to include a FTP and telnet server (using the same username/password combination ad in boards/standard.exp).</para>
+
+<para>With this setup and some minor modification (e.g. replacing echo by printf) in my test cases I could test my vxWorks system. It sure does not seem to be a correct setup by DejaGnu standard. For instance, it still loading /usr/share/dejagnu/baseboards/unix.exp instead of vxWorks. In any case I found that (at least under Windows) I did not find out how the command line would let me override settings in my personal config files.</para>
+
+</sect3>
+</sect2>
+</sect1>
+ <sect1 id="runningtests">
+ <title>Running Tests</title>
+
+ <para>There are two ways to execute a testsuite. 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>
+
+ <sect2 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>
+
+ </sect2>
+
+ <sect2 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>
+
+ <sect3 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
+ testsuite 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
+ testsuites 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>
+
+ </sect3>
+
+ <sect3 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 testsuite 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>
+ </sect3>
+
+ <sect3 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 testsuite 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>
+
+ <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>.)</para>
+ </sect3>
+ </sect2>
+
+ <sect2 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>
+
+ <sect3 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>
+
+ <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>
+
+ </sect3>
+
+ <sect3 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>
+
+ </sect3>
+
+ <sect3 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>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1 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 testsuite 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 testsuite 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 testsuite 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>
+
+ <sect2 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 testsuite.</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, i.e., 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 "-isystem /build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libio -isystem $srcdir/../libg++/src -isystem $srcdir/../libio -isystem $srcdir/../libstdc++ -isystem $srcdir/../libstdc++/stl -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libg++ -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libstdc++"
+ append LDFLAGS " -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../ld"
+ set tmpdir /build/devo-builds/i586-pc-linux-gnulibc1/gcc/testsuite
+ set srcdir "${srcdir}/testsuite"
+ ## All variables above are generated by configure. Do Not Edit ##
+
+ </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 testsuite. For most test cases, the CXXFLAGS and LDFLAGS
+ are supplied by DejaGnu itself for cross testing, but to test a
+ compiler, GCC needs to manipulate these itself.</para>
+
+ </sect2>
+ <sect2 id="global" xreflabel="Global Config File">
+ <title>Global Config File</title>
+
+ <para>The master config file is where all the target specific
+ config variables for a whole site get set. The idea is
+ that for a centralized testing lab where people have to share a
+ target between multiple developers. There are settings for both
+ remote targets and remote hosts. Here's an example of a Master
+ Config File (also called the Global config file) for a
+ <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>
+
+ </sect2>
+
+ <sect2 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>
+
+ </sect2>
+
+ <sect2 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/Windows 3.1, MacOS and Windows.</para>
+
+ <para>The recommended source for a Windows-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 Windows, 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:</para>
+
+ <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>
+
+ </sect2>
+
+ <sect2 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>
+
+ <sect3 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>
+
+ <row>
+ <entry>--mail</entry>
+ <entry>address</entry>
+ <entry>Email the output log to the specified address.</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ </sect3>
+
+ <sect3 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>
+
+ </sect3>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="Extending" xreflabel="Extending DejaGnu">
+ <title>Extending DejaGnu</title>
+
+ <sect2 id="addsuite" xreflabel="Adding a new Testsuite">
+ <title>Adding A New Testsuite</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>
+
+ </sect2>
+
+ <sect2 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 testsuites. Unfortunately, well-established testsuites have a way
+ of developing their own conventions: as test writers become more
+ experienced with DejaGnu and with Tcl, they accumulate more utilities,
+ and take advantage of more and more features of
+ <productname>Expect</productname> and <productname>Tcl</productname> in
+ general.</para>
+
+ <para>Inspecting such established testsuites may make the prospect of
+ creating an entirely new testsuite appear overwhelming. Nevertheless,
+ it is quite straightforward to get a new testsuite going.</para>
+
+ <para>There is one testsuite that is guaranteed not to grow more
+ elaborate over time: both it and the tool it tests were created expressly
+ to illustrate what it takes to get started with DejaGnu. The
+ <filename>example/</filename> directory of the DejaGnu distribution
+ contains both an interactive tool called <command>calc</command>, and a
+ testsuite for it. Reading this testsuite, and experimenting with it,
+ is a good way to supplement the information in this section. (Thanks to
+ Robert Lupton for creating calc and its testsuite---and also the first
+ version of this section of the manual!)</para>
+
+ <para>To help orient you further in this task, here is an outline of the
+ steps to begin building a testsuite 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>
+
+ </sect2>
+
+ <sect2 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>
+
+ </sect2>
+
+ <sect2 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>
+
+ </sect2>
+
+ <sect2 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>
+
+ </sect2>
+
+ <sect2 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>
+
+ </sect2>
+
+ <sect2 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>
+
+ <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>
+
+ <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></listitem>
+ </itemizedlist>
+
+ </sect2>
+
+ <sect2 id="adding" xreflabel="Adding A Test Case To A Testsuite">
+ <title>Adding A Test Case To A Testsuite.</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 testsuite
+ 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>
+
+ <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>
+
+ </sect2>
+
+ <sect2 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>
+
+ </sect2>
+
+ <sect2 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>
+
+ </sect2>
+
+</sect1>
+
+ <sect1 id="unit" xreflabel="Unit Testing">
+ <title>Unit Testing</title>
+
+ <sect2 id="unittest" xreflabel="What Is Unit Testing ?">
+ <title>What Is Unit Testing ?</title>
+
+ <para>Most regression testing as done by DejaGnu is system
+ testing. This is the complete application is tested all at
+ once. Unit testing is for testing single files, or small
+ libraries. In this case, each file is linked with a test case in
+ C or C++, and each function or class and method is tested in
+ series, with the test case having to check private data or
+ global variables to see if the function or method worked.</para>
+
+ <para>This works particularly well for testing APIs and at level
+ where it is easier to debug them, than by needing to trace through
+ the entire appication. Also if there is a specification for the
+ API to be tested, the testcase can also function as a compliance
+ test.</para>
+
+ </sect2>
+
+ <sect2 id="djh" xreflabel="The dejagnu.h Header File">
+ <title>The dejagnu.h Header File</title>
+
+ <para>DejaGnu uses a single header file to assist in unit
+ testing. As this file also produces it's one test state output,
+ it can be run standalone, which is very useful for testing on
+ embedded systems. This header file has a C and C++ API for the
+ test states, with simple totals, and standardized
+ output. Because the output has been standardized, DejaGnu can be
+ made to work with this test case, without writing almost any
+ Tcl. The library module, dejagnu.exp, will look for the output
+ messages, and then merge them into DejaGnu's.</para>
+
+ </sect2>
+
+</sect1>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
+sgml-general-insert-case:lower
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:nil
+sgml-parent-document:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->
projects / platform / upstream / dejagnu.git / commitdiff