diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/.cvsignore | 2 | ||||
| -rw-r--r-- | doc/Makefile.am | 47 | ||||
| -rw-r--r-- | doc/Makefile.in | 338 | ||||
| -rw-r--r-- | doc/README | 2 | ||||
| -rwxr-xr-x | doc/configure | 860 | ||||
| -rw-r--r-- | doc/configure.in | 5 | ||||
| -rw-r--r-- | doc/dejagnu.texi | 3572 | ||||
| -rw-r--r-- | doc/overview.sgml | 439 | ||||
| -rw-r--r-- | doc/ref.sgml | 4242 | ||||
| -rw-r--r-- | doc/runtest.1 | 119 | ||||
| -rw-r--r-- | doc/user.sgml | 2355 |
11 files changed, 11981 insertions, 0 deletions
diff --git a/doc/.cvsignore b/doc/.cvsignore new file mode 100644 index 0000000..7abff1d --- /dev/null +++ b/doc/.cvsignore @@ -0,0 +1,2 @@ +Makefile +config.status diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..9521a40 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,47 @@ +## Process this file with automake to generate Makefile.in + +AUTOMAKE_OPTIONS = cygnus + +info_TEXINFOS = dejagnu.texi + +TARGETS = overview.rtf overview.html overview.dvi overview.ps + +docs: $(TARGETS) + +%.ps: %.dvi + dvips -o $@ $< + +%.pdf: %.sgml + db2pdf $< + +%.dvi: %.sgml + db2dvi $< + +%.rtf: %.sgml + db2rtf -o $@ $< + +%.gif: %.fig + convert -transparency white $< $@ # .fig -> .gif + +%.epsi: %.eps + ps2epsi $< # .eps -> .epsi + +%.eps: %.fig + fig2dev -L ps -m 0.7 -p dummy $< > $@ # .fig -> .eps/portrait + +%.html: %.sgml + db2html $< + +# now for some extra dependencies that the automatic rules will not +# catch: + +overview.pdf overview.ps overview.dvi overview.rtf overview.html: overview.sgml ref.sgml user.sgml + +clean: + rm -f $(TARGETS) + +# install-data-local: overview.pdf overview.html +# $(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/html +# $(INSTALL_DATA) overview/*.html $(DESTDIR)$(pkgdatadir)/html +# $(INSTALL_DATA) overview.ps $(DESTDIR)$(pkgdatadir)/dejagnu.ps +# $(INSTALL_DATA) overview.pdf $(DESTDIR)$(pkgdatadir)/dejagnu.pdf diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..31d809b --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,338 @@ +# Makefile.in generated automatically by automake 1.4 from Makefile.am + +# Copyright (C) 1994, 1995-8, 1999 Free Software Foundation, Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + + +SHELL = @SHELL@ + +srcdir = @srcdir@ +top_srcdir = @top_srcdir@ +VPATH = @srcdir@ +prefix = @prefix@ +exec_prefix = @exec_prefix@ + +bindir = @bindir@ +sbindir = @sbindir@ +libexecdir = @libexecdir@ +datadir = @datadir@ +sysconfdir = @sysconfdir@ +sharedstatedir = @sharedstatedir@ +localstatedir = @localstatedir@ +libdir = @libdir@ +infodir = @infodir@ +mandir = @mandir@ +includedir = @includedir@ +oldincludedir = /usr/include + +DESTDIR = + +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ + +top_builddir = .. + +ACLOCAL = @ACLOCAL@ +AUTOCONF = @AUTOCONF@ +AUTOMAKE = @AUTOMAKE@ +AUTOHEADER = @AUTOHEADER@ + +INSTALL = @INSTALL@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ $(AM_INSTALL_PROGRAM_FLAGS) +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +transform = @program_transform_name@ + +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +BOARDS = @BOARDS@ +CC = @CC@ +CONFIG = @CONFIG@ +EXEEXT = @EXEEXT@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +PACKAGE = @PACKAGE@ +VERSION = @VERSION@ + +AUTOMAKE_OPTIONS = cygnus + +info_TEXINFOS = dejagnu.texi + +TARGETS = overview.rtf overview.html overview.dvi overview.ps +mkinstalldirs = $(SHELL) $(top_srcdir)/../mkinstalldirs +CONFIG_CLEAN_FILES = +TEXI2DVI = `if test -f $(top_srcdir)/../texinfo/util/texi2dvi; then echo $(top_srcdir)/../texinfo/util/texi2dvi; else echo texi2dvi; fi` +TEXINFO_TEX = $(top_srcdir)/../texinfo/texinfo.tex +INFO_DEPS = dejagnu.info +DVIS = dejagnu.dvi +TEXINFOS = dejagnu.texi +DIST_COMMON = README Makefile.am Makefile.in configure configure.in + + +DISTFILES = $(DIST_COMMON) $(SOURCES) $(HEADERS) $(TEXINFOS) $(EXTRA_DIST) + +TAR = gtar +GZIP_ENV = --best +all: all-redirect +.SUFFIXES: +.SUFFIXES: .dvi .info .ps .texi .texinfo .txi +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ Makefile.am $(top_srcdir)/configure.in $(ACLOCAL_M4) + cd $(top_srcdir) && $(AUTOMAKE) --cygnus doc/Makefile + +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + cd $(top_builddir) \ + && CONFIG_FILES=$(subdir)/$@ CONFIG_HEADERS= $(SHELL) ./config.status + + +dejagnu.info: dejagnu.texi +dejagnu.dvi: dejagnu.texi + + +DVIPS = dvips + +.texi.info: + @rm -f $@ $@-[0-9] $@-[0-9][0-9] + $(MAKEINFO) -I $(srcdir) $< + +.texi.dvi: + TEXINPUTS=$(top_srcdir)/../texinfo/texinfo.tex:$$TEXINPUTS \ + MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $< + +.texi: + @rm -f $@ $@-[0-9] $@-[0-9][0-9] + $(MAKEINFO) -I $(srcdir) $< + +.texinfo.info: + @rm -f $@ $@-[0-9] $@-[0-9][0-9] + $(MAKEINFO) -I $(srcdir) $< + +.texinfo: + @rm -f $@ $@-[0-9] $@-[0-9][0-9] + $(MAKEINFO) -I $(srcdir) $< + +.texinfo.dvi: + TEXINPUTS=$(top_srcdir)/../texinfo/texinfo.tex:$$TEXINPUTS \ + MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $< + +.txi.info: + @rm -f $@ $@-[0-9] $@-[0-9][0-9] + $(MAKEINFO) -I $(srcdir) $< + +.txi.dvi: + TEXINPUTS=$(top_srcdir)/../texinfo/texinfo.tex:$$TEXINPUTS \ + MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $< + +.txi: + @rm -f $@ $@-[0-9] $@-[0-9][0-9] + $(MAKEINFO) -I $(srcdir) $< +.dvi.ps: + $(DVIPS) $< -o $@ + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + $(mkinstalldirs) $(DESTDIR)$(infodir) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + for ifile in `cd $$d && echo $$file $$file-[0-9] $$file-[0-9][0-9]`; do \ + if test -f $$d/$$ifile; then \ + echo " $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile"; \ + $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile; \ + else : ; fi; \ + done; \ + done + @$(POST_INSTALL) + @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + echo " install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file";\ + install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file || :;\ + done; \ + else : ; fi + +uninstall-info: + $(PRE_UNINSTALL) + @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \ + ii=yes; \ + else ii=; fi; \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + test -z "$ii" \ + || install-info --info-dir=$(DESTDIR)$(infodir) --remove $$file; \ + done + @$(NORMAL_UNINSTALL) + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + (cd $(DESTDIR)$(infodir) && rm -f $$file $$file-[0-9] $$file-[0-9][0-9]); \ + done + +dist-info: $(INFO_DEPS) + list='$(INFO_DEPS)'; \ + for base in $$list; do \ + if test -f $$base; then d=.; else d=$(srcdir); fi; \ + for file in `cd $$d && eval echo $$base*`; do \ + test -f $(distdir)/$$file \ + || ln $$d/$$file $(distdir)/$$file 2> /dev/null \ + || cp -p $$d/$$file $(distdir)/$$file; \ + done; \ + done + +mostlyclean-aminfo: + -rm -f dejagnu.aux dejagnu.cp dejagnu.cps dejagnu.dvi dejagnu.fn \ + dejagnu.fns dejagnu.ky dejagnu.kys dejagnu.ps dejagnu.log \ + dejagnu.pg dejagnu.toc dejagnu.tp dejagnu.tps dejagnu.vr \ + dejagnu.vrs dejagnu.op dejagnu.tr dejagnu.cv dejagnu.cn + +clean-aminfo: + +distclean-aminfo: + +maintainer-clean-aminfo: + for i in $(INFO_DEPS); do \ + rm -f $$i; \ + if test "`echo $$i-[0-9]*`" != "$$i-[0-9]*"; then \ + rm -f $$i-[0-9]*; \ + fi; \ + done +clean-info: mostlyclean-aminfo +tags: TAGS +TAGS: + + +distdir = $(top_builddir)/$(PACKAGE)-$(VERSION)/$(subdir) + +subdir = doc + +distdir: $(DISTFILES) + @for file in $(DISTFILES); do \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + cp -pr $$d/$$file $(distdir)/$$file; \ + else \ + test -f $(distdir)/$$file \ + || ln $$d/$$file $(distdir)/$$file 2> /dev/null \ + || cp -p $$d/$$file $(distdir)/$$file || :; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) top_distdir="$(top_distdir)" distdir="$(distdir)" dist-info +info-am: $(INFO_DEPS) +info: info-am +dvi-am: $(DVIS) +dvi: dvi-am +check-am: +check: check-am +installcheck-am: +installcheck: installcheck-am +install-info-am: +install-info: install-info-am +install-exec-am: +install-exec: install-exec-am + +install-data-am: +install-data: install-data-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am +install: install-am +uninstall-am: +uninstall: uninstall-am +all-am: Makefile +all-redirect: all-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) AM_INSTALL_PROGRAM_FLAGS=-s install +installdirs: + + +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -rm -f Makefile $(CONFIG_CLEAN_FILES) + -rm -f config.cache config.log stamp-h stamp-h[0-9]* + +maintainer-clean-generic: +mostlyclean-am: mostlyclean-aminfo mostlyclean-generic + +mostlyclean: mostlyclean-am + +clean-am: clean-aminfo clean-generic mostlyclean-am + +clean: clean-am + +distclean-am: distclean-aminfo distclean-generic clean-am + +distclean: distclean-am + +maintainer-clean-am: maintainer-clean-aminfo maintainer-clean-generic \ + distclean-am + @echo "This command is intended for maintainers to use;" + @echo "it deletes files that may require special tools to rebuild." + +maintainer-clean: maintainer-clean-am + +.PHONY: install-info-am uninstall-info mostlyclean-aminfo \ +distclean-aminfo clean-aminfo maintainer-clean-aminfo tags distdir \ +info-am info dvi-am dvi check check-am installcheck-am installcheck \ +install-info-am install-info install-exec-am install-exec \ +install-data-am install-data install-am install uninstall-am uninstall \ +all-redirect all-am all installdirs mostlyclean-generic \ +distclean-generic clean-generic maintainer-clean-generic clean \ +mostlyclean distclean maintainer-clean + + +docs: $(TARGETS) + +%.ps: %.dvi + dvips -o $@ $< + +%.pdf: %.sgml + db2pdf $< + +%.dvi: %.sgml + db2dvi $< + +%.rtf: %.sgml + db2rtf -o $@ $< + +%.gif: %.fig + convert -transparency white $< $@ # .fig -> .gif + +%.epsi: %.eps + ps2epsi $< # .eps -> .epsi + +%.eps: %.fig + fig2dev -L ps -m 0.7 -p dummy $< > $@ # .fig -> .eps/portrait + +%.html: %.sgml + db2html $< + +# now for some extra dependencies that the automatic rules will not +# catch: + +overview.pdf overview.ps overview.dvi overview.rtf overview.html: overview.sgml ref.sgml user.sgml + +clean: + rm -f $(TARGETS) + +# install-data-local: overview.pdf overview.html +# $(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/html +# $(INSTALL_DATA) overview/*.html $(DESTDIR)$(pkgdatadir)/html +# $(INSTALL_DATA) overview.ps $(DESTDIR)$(pkgdatadir)/dejagnu.ps +# $(INSTALL_DATA) overview.pdf $(DESTDIR)$(pkgdatadir)/dejagnu.pdf + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/doc/README b/doc/README new file mode 100644 index 0000000..fc8ae45 --- /dev/null +++ b/doc/README @@ -0,0 +1,2 @@ +One can obtain the Free DocBook Tools for Linux and NT at +http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html diff --git a/doc/configure b/doc/configure new file mode 100755 index 0000000..638b3bf --- /dev/null +++ b/doc/configure @@ -0,0 +1,860 @@ +#! /bin/sh + +# Guess values for system-dependent variables and create Makefiles. +# Generated automatically using autoconf version 2.12.1 +# Copyright (C) 1992, 93, 94, 95, 96 Free Software Foundation, Inc. +# +# This configure script is free software; the Free Software Foundation +# gives unlimited permission to copy, distribute and modify it. + +# Defaults: +ac_help= +ac_default_prefix=/usr/local +# Any additions from configure.in: + +# Initialize some variables set by options. +# The variables have the same names as the options, with +# dashes changed to underlines. +build=NONE +cache_file=./config.cache +exec_prefix=NONE +host=NONE +no_create= +nonopt=NONE +no_recursion= +prefix=NONE +program_prefix=NONE +program_suffix=NONE +program_transform_name=s,x,x, +silent= +site= +srcdir= +target=NONE +verbose= +x_includes=NONE +x_libraries=NONE +bindir='${exec_prefix}/bin' +sbindir='${exec_prefix}/sbin' +libexecdir='${exec_prefix}/libexec' +datadir='${prefix}/share' +sysconfdir='${prefix}/etc' +sharedstatedir='${prefix}/com' +localstatedir='${prefix}/var' +libdir='${exec_prefix}/lib' +includedir='${prefix}/include' +oldincludedir='/usr/include' +infodir='${prefix}/info' +mandir='${prefix}/man' + +# Initialize some other variables. +subdirs= +MFLAGS= MAKEFLAGS= +SHELL=${CONFIG_SHELL-/bin/sh} +# Maximum number of lines to put in a shell here document. +ac_max_here_lines=12 + +ac_prev= +for ac_option +do + + # If the previous option needs an argument, assign it. + if test -n "$ac_prev"; then + eval "$ac_prev=\$ac_option" + ac_prev= + continue + fi + + case "$ac_option" in + -*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;; + *) ac_optarg= ;; + esac + + # Accept the important Cygnus configure options, so we can diagnose typos. + + case "$ac_option" in + + -bindir | --bindir | --bindi | --bind | --bin | --bi) + ac_prev=bindir ;; + -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*) + bindir="$ac_optarg" ;; + + -build | --build | --buil | --bui | --bu) + ac_prev=build ;; + -build=* | --build=* | --buil=* | --bui=* | --bu=*) + build="$ac_optarg" ;; + + -cache-file | --cache-file | --cache-fil | --cache-fi \ + | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c) + ac_prev=cache_file ;; + -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \ + | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*) + cache_file="$ac_optarg" ;; + + -datadir | --datadir | --datadi | --datad | --data | --dat | --da) + ac_prev=datadir ;; + -datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \ + | --da=*) + datadir="$ac_optarg" ;; + + -disable-* | --disable-*) + ac_feature=`echo $ac_option|sed -e 's/-*disable-//'` + # Reject names that are not valid shell variable names. + if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then + { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } + fi + ac_feature=`echo $ac_feature| sed 's/-/_/g'` + eval "enable_${ac_feature}=no" ;; + + -enable-* | --enable-*) + ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'` + # Reject names that are not valid shell variable names. + if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then + { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } + fi + ac_feature=`echo $ac_feature| sed 's/-/_/g'` + case "$ac_option" in + *=*) ;; + *) ac_optarg=yes ;; + esac + eval "enable_${ac_feature}='$ac_optarg'" ;; + + -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \ + | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \ + | --exec | --exe | --ex) + ac_prev=exec_prefix ;; + -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \ + | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \ + | --exec=* | --exe=* | --ex=*) + exec_prefix="$ac_optarg" ;; + + -gas | --gas | --ga | --g) + # Obsolete; use --with-gas. + with_gas=yes ;; + + -help | --help | --hel | --he) + # Omit some internal or obsolete options to make the list less imposing. + # This message is too long to be a string in the A/UX 3.1 sh. + cat << EOF +Usage: configure [options] [host] +Options: [defaults in brackets after descriptions] +Configuration: + --cache-file=FILE cache test results in FILE + --help print this message + --no-create do not create output files + --quiet, --silent do not print \`checking...' messages + --version print the version of autoconf that created configure +Directory and file names: + --prefix=PREFIX install architecture-independent files in PREFIX + [$ac_default_prefix] + --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX + [same as prefix] + --bindir=DIR user executables in DIR [EPREFIX/bin] + --sbindir=DIR system admin executables in DIR [EPREFIX/sbin] + --libexecdir=DIR program executables in DIR [EPREFIX/libexec] + --datadir=DIR read-only architecture-independent data in DIR + [PREFIX/share] + --sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc] + --sharedstatedir=DIR modifiable architecture-independent data in DIR + [PREFIX/com] + --localstatedir=DIR modifiable single-machine data in DIR [PREFIX/var] + --libdir=DIR object code libraries in DIR [EPREFIX/lib] + --includedir=DIR C header files in DIR [PREFIX/include] + --oldincludedir=DIR C header files for non-gcc in DIR [/usr/include] + --infodir=DIR info documentation in DIR [PREFIX/info] + --mandir=DIR man documentation in DIR [PREFIX/man] + --srcdir=DIR find the sources in DIR [configure dir or ..] + --program-prefix=PREFIX prepend PREFIX to installed program names + --program-suffix=SUFFIX append SUFFIX to installed program names + --program-transform-name=PROGRAM + run sed PROGRAM on installed program names +EOF + cat << EOF +Host type: + --build=BUILD configure for building on BUILD [BUILD=HOST] + --host=HOST configure for HOST [guessed] + --target=TARGET configure for TARGET [TARGET=HOST] +Features and packages: + --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) + --enable-FEATURE[=ARG] include FEATURE [ARG=yes] + --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] + --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) + --x-includes=DIR X include files are in DIR + --x-libraries=DIR X library files are in DIR +EOF + if test -n "$ac_help"; then + echo "--enable and --with options recognized:$ac_help" + fi + exit 0 ;; + + -host | --host | --hos | --ho) + ac_prev=host ;; + -host=* | --host=* | --hos=* | --ho=*) + host="$ac_optarg" ;; + + -includedir | --includedir | --includedi | --included | --include \ + | --includ | --inclu | --incl | --inc) + ac_prev=includedir ;; + -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \ + | --includ=* | --inclu=* | --incl=* | --inc=*) + includedir="$ac_optarg" ;; + + -infodir | --infodir | --infodi | --infod | --info | --inf) + ac_prev=infodir ;; + -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*) + infodir="$ac_optarg" ;; + + -libdir | --libdir | --libdi | --libd) + ac_prev=libdir ;; + -libdir=* | --libdir=* | --libdi=* | --libd=*) + libdir="$ac_optarg" ;; + + -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \ + | --libexe | --libex | --libe) + ac_prev=libexecdir ;; + -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \ + | --libexe=* | --libex=* | --libe=*) + libexecdir="$ac_optarg" ;; + + -localstatedir | --localstatedir | --localstatedi | --localstated \ + | --localstate | --localstat | --localsta | --localst \ + | --locals | --local | --loca | --loc | --lo) + ac_prev=localstatedir ;; + -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \ + | --localstate=* | --localstat=* | --localsta=* | --localst=* \ + | --locals=* | --local=* | --loca=* | --loc=* | --lo=*) + localstatedir="$ac_optarg" ;; + + -mandir | --mandir | --mandi | --mand | --man | --ma | --m) + ac_prev=mandir ;; + -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*) + mandir="$ac_optarg" ;; + + -nfp | --nfp | --nf) + # Obsolete; use --without-fp. + with_fp=no ;; + + -no-create | --no-create | --no-creat | --no-crea | --no-cre \ + | --no-cr | --no-c) + no_create=yes ;; + + -no-recursion | --no-recursion | --no-recursio | --no-recursi \ + | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) + no_recursion=yes ;; + + -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \ + | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \ + | --oldin | --oldi | --old | --ol | --o) + ac_prev=oldincludedir ;; + -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \ + | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \ + | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*) + oldincludedir="$ac_optarg" ;; + + -prefix | --prefix | --prefi | --pref | --pre | --pr | --p) + ac_prev=prefix ;; + -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*) + prefix="$ac_optarg" ;; + + -program-prefix | --program-prefix | --program-prefi | --program-pref \ + | --program-pre | --program-pr | --program-p) + ac_prev=program_prefix ;; + -program-prefix=* | --program-prefix=* | --program-prefi=* \ + | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*) + program_prefix="$ac_optarg" ;; + + -program-suffix | --program-suffix | --program-suffi | --program-suff \ + | --program-suf | --program-su | --program-s) + ac_prev=program_suffix ;; + -program-suffix=* | --program-suffix=* | --program-suffi=* \ + | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*) + program_suffix="$ac_optarg" ;; + + -program-transform-name | --program-transform-name \ + | --program-transform-nam | --program-transform-na \ + | --program-transform-n | --program-transform- \ + | --program-transform | --program-transfor \ + | --program-transfo | --program-transf \ + | --program-trans | --program-tran \ + | --progr-tra | --program-tr | --program-t) + ac_prev=program_transform_name ;; + -program-transform-name=* | --program-transform-name=* \ + | --program-transform-nam=* | --program-transform-na=* \ + | --program-transform-n=* | --program-transform-=* \ + | --program-transform=* | --program-transfor=* \ + | --program-transfo=* | --program-transf=* \ + | --program-trans=* | --program-tran=* \ + | --progr-tra=* | --program-tr=* | --program-t=*) + program_transform_name="$ac_optarg" ;; + + -q | -quiet | --quiet | --quie | --qui | --qu | --q \ + | -silent | --silent | --silen | --sile | --sil) + silent=yes ;; + + -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb) + ac_prev=sbindir ;; + -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \ + | --sbi=* | --sb=*) + sbindir="$ac_optarg" ;; + + -sharedstatedir | --sharedstatedir | --sharedstatedi \ + | --sharedstated | --sharedstate | --sharedstat | --sharedsta \ + | --sharedst | --shareds | --shared | --share | --shar \ + | --sha | --sh) + ac_prev=sharedstatedir ;; + -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \ + | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \ + | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \ + | --sha=* | --sh=*) + sharedstatedir="$ac_optarg" ;; + + -site | --site | --sit) + ac_prev=site ;; + -site=* | --site=* | --sit=*) + site="$ac_optarg" ;; + + -srcdir | --srcdir | --srcdi | --srcd | --src | --sr) + ac_prev=srcdir ;; + -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) + srcdir="$ac_optarg" ;; + + -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \ + | --syscon | --sysco | --sysc | --sys | --sy) + ac_prev=sysconfdir ;; + -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \ + | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*) + sysconfdir="$ac_optarg" ;; + + -target | --target | --targe | --targ | --tar | --ta | --t) + ac_prev=target ;; + -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*) + target="$ac_optarg" ;; + + -v | -verbose | --verbose | --verbos | --verbo | --verb) + verbose=yes ;; + + -version | --version | --versio | --versi | --vers) + echo "configure generated by autoconf version 2.12.1" + exit 0 ;; + + -with-* | --with-*) + ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'` + # Reject names that are not valid shell variable names. + if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then + { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } + fi + ac_package=`echo $ac_package| sed 's/-/_/g'` + case "$ac_option" in + *=*) ;; + *) ac_optarg=yes ;; + esac + eval "with_${ac_package}='$ac_optarg'" ;; + + -without-* | --without-*) + ac_package=`echo $ac_option|sed -e 's/-*without-//'` + # Reject names that are not valid shell variable names. + if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then + { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } + fi + ac_package=`echo $ac_package| sed 's/-/_/g'` + eval "with_${ac_package}=no" ;; + + --x) + # Obsolete; use --with-x. + with_x=yes ;; + + -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \ + | --x-incl | --x-inc | --x-in | --x-i) + ac_prev=x_includes ;; + -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \ + | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*) + x_includes="$ac_optarg" ;; + + -x-libraries | --x-libraries | --x-librarie | --x-librari \ + | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l) + ac_prev=x_libraries ;; + -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \ + | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*) + x_libraries="$ac_optarg" ;; + + -*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; } + ;; + + *) + if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then + echo "configure: warning: $ac_option: invalid host type" 1>&2 + fi + if test "x$nonopt" != xNONE; then + { echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; } + fi + nonopt="$ac_option" + ;; + + esac +done + +if test -n "$ac_prev"; then + { echo "configure: error: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" 1>&2; exit 1; } +fi + +trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 + +# File descriptor usage: +# 0 standard input +# 1 file creation +# 2 errors and warnings +# 3 some systems may open it to /dev/tty +# 4 used on the Kubota Titan +# 6 checking for... messages and results +# 5 compiler messages saved in config.log +if test "$silent" = yes; then + exec 6>/dev/null +else + exec 6>&1 +fi +exec 5>./config.log + +echo "\ +This file contains any messages produced by compilers while +running configure, to aid debugging if configure makes a mistake. +" 1>&5 + +# Strip out --no-create and --no-recursion so they do not pile up. +# Also quote any args containing shell metacharacters. +ac_configure_args= +for ac_arg +do + case "$ac_arg" in + -no-create | --no-create | --no-creat | --no-crea | --no-cre \ + | --no-cr | --no-c) ;; + -no-recursion | --no-recursion | --no-recursio | --no-recursi \ + | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) ;; + *" "*|*" "*|*[\[\]\~\#\$\^\&\*\(\)\{\}\\\|\;\<\>\?]*) + ac_configure_args="$ac_configure_args '$ac_arg'" ;; + *) ac_configure_args="$ac_configure_args $ac_arg" ;; + esac +done + +# NLS nuisances. +# Only set these to C if already set. These must not be set unconditionally +# because not all systems understand e.g. LANG=C (notably SCO). +# Fixing LC_MESSAGES prevents Solaris sh from translating var values in `set'! +# Non-C LC_CTYPE values break the ctype check. +if test "${LANG+set}" = set; then LANG=C; export LANG; fi +if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi +if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi +if test "${LC_CTYPE+set}" = set; then LC_CTYPE=C; export LC_CTYPE; fi + +# confdefs.h avoids OS command line length limits that DEFS can exceed. +rm -rf conftest* confdefs.h +# AIX cpp loses on an empty file, so make sure it contains at least a newline. +echo > confdefs.h + +# A filename unique to this package, relative to the directory that +# configure is in, which we can look for to find out if srcdir is correct. +ac_unique_file=dejagnu.texi + +# Find the source files, if location was not specified. +if test -z "$srcdir"; then + ac_srcdir_defaulted=yes + # Try the directory containing this script, then its parent. + ac_prog=$0 + ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'` + test "x$ac_confdir" = "x$ac_prog" && ac_confdir=. + srcdir=$ac_confdir + if test ! -r $srcdir/$ac_unique_file; then + srcdir=.. + fi +else + ac_srcdir_defaulted=no +fi +if test ! -r $srcdir/$ac_unique_file; then + if test "$ac_srcdir_defaulted" = yes; then + { echo "configure: error: can not find sources in $ac_confdir or .." 1>&2; exit 1; } + else + { echo "configure: error: can not find sources in $srcdir" 1>&2; exit 1; } + fi +fi +srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'` + +# Prefer explicitly selected file to automatically selected ones. +if test -z "$CONFIG_SITE"; then + if test "x$prefix" != xNONE; then + CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site" + else + CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site" + fi +fi +for ac_site_file in $CONFIG_SITE; do + if test -r "$ac_site_file"; then + echo "loading site script $ac_site_file" + . "$ac_site_file" + fi +done + +if test -r "$cache_file"; then + echo "loading cache $cache_file" + . $cache_file +else + echo "creating cache $cache_file" + > $cache_file +fi + +ac_ext=c +# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. +ac_cpp='$CPP $CPPFLAGS' +ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5' +ac_link='${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5' +cross_compiling=$ac_cv_prog_cc_cross + +if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then + # Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu. + if (echo -n testing; echo 1,2,3) | sed s/-n/xn/ | grep xn >/dev/null; then + ac_n= ac_c=' +' ac_t=' ' + else + ac_n=-n ac_c= ac_t= + fi +else + ac_n= ac_c='\c' ac_t= +fi + + +ac_aux_dir= +for ac_dir in $srcdir $srcdir/.. $srcdir/../..; do + if test -f $ac_dir/install-sh; then + ac_aux_dir=$ac_dir + ac_install_sh="$ac_aux_dir/install-sh -c" + break + elif test -f $ac_dir/install.sh; then + ac_aux_dir=$ac_dir + ac_install_sh="$ac_aux_dir/install.sh -c" + break + fi +done +if test -z "$ac_aux_dir"; then + { echo "configure: error: can not find install-sh or install.sh in $srcdir $srcdir/.. $srcdir/../.." 1>&2; exit 1; } +fi +ac_config_guess=$ac_aux_dir/config.guess +ac_config_sub=$ac_aux_dir/config.sub +ac_configure=$ac_aux_dir/configure # This should be Cygnus configure. + +# Find a good install program. We prefer a C program (faster), +# so one script is as good as another. But avoid the broken or +# incompatible versions: +# SysV /etc/install, /usr/sbin/install +# SunOS /usr/etc/install +# IRIX /sbin/install +# AIX /bin/install +# AIX 4 /usr/bin/installbsd, which doesn't work without a -g flag +# AFS /usr/afsws/bin/install, which mishandles nonexistent args +# SVR4 /usr/ucb/install, which tries to use the nonexistent group "staff" +# ./install, which can be erroneously created by make from ./install.sh. +echo $ac_n "checking for a BSD compatible install""... $ac_c" 1>&6 +echo "configure:554: checking for a BSD compatible install" >&5 +if test -z "$INSTALL"; then +if eval "test \"`echo '$''{'ac_cv_path_install'+set}'`\" = set"; then + echo $ac_n "(cached) $ac_c" 1>&6 +else + IFS="${IFS= }"; ac_save_IFS="$IFS"; IFS="${IFS}:" + for ac_dir in $PATH; do + # Account for people who put trailing slashes in PATH elements. + case "$ac_dir/" in + /|./|.//|/etc/*|/usr/sbin/*|/usr/etc/*|/sbin/*|/usr/afsws/bin/*|/usr/ucb/*) ;; + *) + # OSF1 and SCO ODT 3.0 have their own names for install. + # Don't use installbsd from OSF since it installs stuff as root + # by default. + for ac_prog in ginstall scoinst install; do + if test -f $ac_dir/$ac_prog; then + if test $ac_prog = install && + grep dspmsg $ac_dir/$ac_prog >/dev/null 2>&1; then + # AIX install. It has an incompatible calling convention. + : + else + ac_cv_path_install="$ac_dir/$ac_prog -c" + break 2 + fi + fi + done + ;; + esac + done + IFS="$ac_save_IFS" + +fi + if test "${ac_cv_path_install+set}" = set; then + INSTALL="$ac_cv_path_install" + else + # As a last resort, use the slow shell script. We don't cache a + # path for INSTALL within a source directory, because that will + # break other packages using the cache if that directory is + # removed, or if the path is relative. + INSTALL="$ac_install_sh" + fi +fi +echo "$ac_t""$INSTALL" 1>&6 + +# Use test -z because SunOS4 sh mishandles braces in ${var-val}. +# It thinks the first close brace ends the variable substitution. +test -z "$INSTALL_PROGRAM" && INSTALL_PROGRAM='${INSTALL}' + +test -z "$INSTALL_DATA" && INSTALL_DATA='${INSTALL} -m 644' + +trap '' 1 2 15 +cat > confcache <<\EOF +# This file is a shell script that caches the results of configure +# tests run on this system so they can be shared between configure +# scripts and configure runs. It is not useful on other systems. +# If it contains results you don't want to keep, you may remove or edit it. +# +# By default, configure uses ./config.cache as the cache file, +# creating it if it does not exist already. You can give configure +# the --cache-file=FILE option to use a different cache file; that is +# what configure does when it calls configure scripts in +# subdirectories, so they share the cache. +# Giving --cache-file=/dev/null disables caching, for debugging configure. +# config.status only pays attention to the cache file if you give it the +# --recheck option to rerun configure. +# +EOF +# The following way of writing the cache mishandles newlines in values, +# but we know of no workaround that is simple, portable, and efficient. +# So, don't put newlines in cache variables' values. +# Ultrix sh set writes to stderr and can't be redirected directly, +# and sets the high bit in the cache file unless we assign to the vars. +(set) 2>&1 | + case `(ac_space=' '; set) 2>&1 | grep ac_space` in + *ac_space=\ *) + # `set' does not quote correctly, so add quotes (double-quote substitution + # turns \\\\ into \\, and sed turns \\ into \). + sed -n \ + -e "s/'/'\\\\''/g" \ + -e "s/^\\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\\)=\\(.*\\)/\\1=\${\\1='\\2'}/p" + ;; + *) + # `set' quotes correctly as required by POSIX, so do not add quotes. + sed -n -e 's/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=${\1=\2}/p' + ;; + esac >> confcache +if cmp -s $cache_file confcache; then + : +else + if test -w $cache_file; then + echo "updating cache $cache_file" + cat confcache > $cache_file + else + echo "not updating unwritable cache $cache_file" + fi +fi +rm -f confcache + +trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 + +test "x$prefix" = xNONE && prefix=$ac_default_prefix +# Let make expand exec_prefix. +test "x$exec_prefix" = xNONE && exec_prefix='${prefix}' + +# Any assignment to VPATH causes Sun make to only execute +# the first set of double-colon rules, so remove it if not needed. +# If there is a colon in the path, we need to keep it. +if test "x$srcdir" = x.; then + ac_vpsub='/^[ ]*VPATH[ ]*=[^:]*$/d' +fi + +trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15 + +# Transform confdefs.h into DEFS. +# Protect against shell expansion while executing Makefile rules. +# Protect against Makefile macro expansion. +cat > conftest.defs <<\EOF +s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g +s%[ `~#$^&*(){}\\|;'"<>?]%\\&%g +s%\[%\\&%g +s%\]%\\&%g +s%\$%$$%g +EOF +DEFS=`sed -f conftest.defs confdefs.h | tr '\012' ' '` +rm -f conftest.defs + + +# Without the "./", some shells look in PATH for config.status. +: ${CONFIG_STATUS=./config.status} + +echo creating $CONFIG_STATUS +rm -f $CONFIG_STATUS +cat > $CONFIG_STATUS <<EOF +#! /bin/sh +# Generated automatically by configure. +# Run this file to recreate the current configuration. +# This directory was configured as follows, +# on host `(hostname || uname -n) 2>/dev/null | sed 1q`: +# +# $0 $ac_configure_args +# +# Compiler output produced by configure, useful for debugging +# configure, is in ./config.log if it exists. + +ac_cs_usage="Usage: $CONFIG_STATUS [--recheck] [--version] [--help]" +for ac_option +do + case "\$ac_option" in + -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r) + echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion" + exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;; + -version | --version | --versio | --versi | --vers | --ver | --ve | --v) + echo "$CONFIG_STATUS generated by autoconf version 2.12.1" + exit 0 ;; + -help | --help | --hel | --he | --h) + echo "\$ac_cs_usage"; exit 0 ;; + *) echo "\$ac_cs_usage"; exit 1 ;; + esac +done + +ac_given_srcdir=$srcdir +ac_given_INSTALL="$INSTALL" + +trap 'rm -fr `echo "Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15 +EOF +cat >> $CONFIG_STATUS <<EOF + +# Protect against being on the right side of a sed subst in config.status. +sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g; + s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF +$ac_vpsub +$extrasub +s%@SHELL@%$SHELL%g +s%@CFLAGS@%$CFLAGS%g +s%@CPPFLAGS@%$CPPFLAGS%g +s%@CXXFLAGS@%$CXXFLAGS%g +s%@DEFS@%$DEFS%g +s%@LDFLAGS@%$LDFLAGS%g +s%@LIBS@%$LIBS%g +s%@exec_prefix@%$exec_prefix%g +s%@prefix@%$prefix%g +s%@program_transform_name@%$program_transform_name%g +s%@bindir@%$bindir%g +s%@sbindir@%$sbindir%g +s%@libexecdir@%$libexecdir%g +s%@datadir@%$datadir%g +s%@sysconfdir@%$sysconfdir%g +s%@sharedstatedir@%$sharedstatedir%g +s%@localstatedir@%$localstatedir%g +s%@libdir@%$libdir%g +s%@includedir@%$includedir%g +s%@oldincludedir@%$oldincludedir%g +s%@infodir@%$infodir%g +s%@mandir@%$mandir%g +s%@INSTALL_PROGRAM@%$INSTALL_PROGRAM%g +s%@INSTALL_DATA@%$INSTALL_DATA%g + +CEOF +EOF + +cat >> $CONFIG_STATUS <<\EOF + +# Split the substitutions into bite-sized pieces for seds with +# small command number limits, like on Digital OSF/1 and HP-UX. +ac_max_sed_cmds=90 # Maximum number of lines to put in a sed script. +ac_file=1 # Number of current file. +ac_beg=1 # First line for current file. +ac_end=$ac_max_sed_cmds # Line after last line for current file. +ac_more_lines=: +ac_sed_cmds="" +while $ac_more_lines; do + if test $ac_beg -gt 1; then + sed "1,${ac_beg}d; ${ac_end}q" conftest.subs > conftest.s$ac_file + else + sed "${ac_end}q" conftest.subs > conftest.s$ac_file + fi + if test ! -s conftest.s$ac_file; then + ac_more_lines=false + rm -f conftest.s$ac_file + else + if test -z "$ac_sed_cmds"; then + ac_sed_cmds="sed -f conftest.s$ac_file" + else + ac_sed_cmds="$ac_sed_cmds | sed -f conftest.s$ac_file" + fi + ac_file=`expr $ac_file + 1` + ac_beg=$ac_end + ac_end=`expr $ac_end + $ac_max_sed_cmds` + fi +done +if test -z "$ac_sed_cmds"; then + ac_sed_cmds=cat +fi +EOF + +cat >> $CONFIG_STATUS <<EOF + +CONFIG_FILES=\${CONFIG_FILES-"Makefile"} +EOF +cat >> $CONFIG_STATUS <<\EOF +for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then + # Support "outfile[:infile[:infile...]]", defaulting infile="outfile.in". + case "$ac_file" in + *:*) ac_file_in=`echo "$ac_file"|sed 's%[^:]*:%%'` + ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;; + *) ac_file_in="${ac_file}.in" ;; + esac + + # Adjust a relative srcdir, top_srcdir, and INSTALL for subdirectories. + + # Remove last slash and all that follows it. Not all systems have dirname. + ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'` + if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then + # The file is in a subdirectory. + test ! -d "$ac_dir" && mkdir "$ac_dir" + ac_dir_suffix="/`echo $ac_dir|sed 's%^\./%%'`" + # A "../" for each directory in $ac_dir_suffix. + ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'` + else + ac_dir_suffix= ac_dots= + fi + + case "$ac_given_srcdir" in + .) srcdir=. + if test -z "$ac_dots"; then top_srcdir=. + else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;; + /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;; + *) # Relative path. + srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix" + top_srcdir="$ac_dots$ac_given_srcdir" ;; + esac + + case "$ac_given_INSTALL" in + [/$]*) INSTALL="$ac_given_INSTALL" ;; + *) INSTALL="$ac_dots$ac_given_INSTALL" ;; + esac + + echo creating "$ac_file" + rm -f "$ac_file" + configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure." + case "$ac_file" in + *Makefile*) ac_comsub="1i\\ +# $configure_input" ;; + *) ac_comsub= ;; + esac + + ac_file_inputs=`echo $ac_file_in|sed -e "s%^%$ac_given_srcdir/%" -e "s%:% $ac_given_srcdir/%g"` + sed -e "$ac_comsub +s%@configure_input@%$configure_input%g +s%@srcdir@%$srcdir%g +s%@top_srcdir@%$top_srcdir%g +s%@INSTALL@%$INSTALL%g +" $ac_file_inputs | (eval "$ac_sed_cmds") > $ac_file +fi; done +rm -f conftest.s* + +EOF +cat >> $CONFIG_STATUS <<EOF + +EOF +cat >> $CONFIG_STATUS <<\EOF + +exit 0 +EOF +chmod +x $CONFIG_STATUS +rm -fr confdefs* $ac_clean_files +test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1 + diff --git a/doc/configure.in b/doc/configure.in new file mode 100644 index 0000000..2575d44 --- /dev/null +++ b/doc/configure.in @@ -0,0 +1,5 @@ +dnl Process this file with autoconf to produce a configure script. +AC_PREREQ(2.5) +AC_INIT(dejagnu.texi) +AC_PROG_INSTALL +AC_OUTPUT(Makefile) diff --git a/doc/dejagnu.texi b/doc/dejagnu.texi new file mode 100644 index 0000000..68c4008 --- /dev/null +++ b/doc/dejagnu.texi @@ -0,0 +1,3572 @@ +o\input texinfo @c -*- Texinfo -*- +@finalout +@setfilename dejagnu.info +@c +@c This file documents the GNU Testing Framework ``DejaGnu'' +@c +@c Copyright (C) 92, 93, 94, 95, 1996 Free Software Foundation, Inc. +@c +@c This text may be freely distributed under the terms of the GNU +@c General Public License. +@c + +@c FIXME---MAIN TODO LIST! +@c +@c * Revisit organization. +@c +@c * discuss Tcl/expect basics---enough to get started (see seminar notes). +@c Maybe this would permit abbreviating appendices. + +@ifinfo +@format +START-INFO-DIR-ENTRY +* DejaGnu: (dejagnu). The GNU testing framework. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@syncodeindex ky cp +@syncodeindex fn cp + +@setchapternewpage odd +@settitle DejaGnu Testing Framework +@titlepage +@title The DejaGnu Testing Framework +@subtitle for DejaGnu Version 1.3 +@sp 1 +@subtitle Jan 1996 +@author Rob Savoye +@page + +@tex +{\parskip=0pt \hfill Cygnus Support} +@end tex + +@vskip 0pt plus 1filll +Copyright @copyright{} 92, 93, 94, 95, 1996 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@noindent +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end titlepage + +@ifinfo +Copyright @copyright{} 92, 93, 94, 95, 1996 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. + +@node Top +@top DejaGnu + +DejaGnu is a framework for running test suites on software tools. + +This file describes version 1.3 of DejaGnu. + +@menu +* Overview:: What is DejaGnu? +* What is New:: What is new in this release. +* Invoking runtest:: Using `runtest', the main test driver +* Customizing:: Setting `runtest' defaults +* Internals:: The DejaGnu implementation +* Tests:: How to write a test case +* Extending:: New tools, new targets, and new hosts +* Installation:: Configuring and Installing DejaGnu +* Index:: Index +@end menu +@end ifinfo + +@iftex +@raggedbottom +@end iftex + +@node Overview +@chapter What is DejaGnu? +@cindex overview + +DejaGnu is a framework for testing other programs. Its purpose is to +provide a single front end for all tests. Beyond this, DejaGnu offers +several advantages for testing: + +@enumerate +@item +The flexibility and consistency of the DejaGnu framework make it easy +to write tests for any program. + +@item +DejaGnu provides a layer of abstraction which allows you to write tests +that are portable to any host or target where a program must be tested. + For instance, a test for GDB can run (from any Unix based host) on any +target architecture that DejaGnu supports. Currently DejaGnu runs tests +on several single board computers, whose operating software ranges from +just a boot monitor to a full-fledged, Unix-like realtime OS. + +@item +All tests have the same output format. This makes it easy to integrate +testing into other software development processes. DejaGnu's output is +designed to be parsed by other filtering script, and it is also human +readable. +@end enumerate + +DejaGnu is written in @code{expect}, which in turn uses @dfn{Tcl}---Tool +command language. + +@cindex @code{expect} script names +@kindex .exp +@cindex suffix, @code{expect} scripts +Running tests requires two things: the testing framework, and the test +suites themselves. Tests are usually written in @code{expect} using +Tcl, but you can also use a Tcl script to run a test suite that is not +based on @code{expect}. (@code{expect} script filenames conventionally +use @samp{.exp} as a suffix; for example, the main implementation of the +DejaGnu test driver is in the file @file{runtest.exp}.) + + +@menu +* Running Tests:: A first look at running DejaGnu tests +* Sample Test:: What does a DejaGnu test case look like? +* Design Goals:: Goals behind DejaGnu +* Posix:: DejaGnu conforms to POSIX 1003.3 +* Future Directions:: Where is DejaGnu going? +* Tcl and Expect:: Reading more about Tcl and Expect +@end menu + +@node What is New +@chapter What is new in this release ? +@cindex What is New + +This release has a number of substantial changes over version 1.2. The +most visible change is that the version of expect and Tcl included in +the release are up-to-date with the current stable net releases. Other +changes are: + +@enumerate +@item +@c FIXME: add a link to the config section +The config sub-system in DejaGnu has been completely redesigned. It now +supports testing on remote hosts as well as remote targets. + +@item +More builtin support for building target binaries with the correct +linker flags. Currently this only works with GCC, preferably with a +target support by @code{libgloss}. + +@item +Lots of little bug fixes from a year of heavy use here at Cygnus +Support. + +@item +DejaGnu now uses @code{autoconf} for configuration. + +@item +New test cases for DejaGnu have been added for the new features, plus +the "--tool" option bug in the 1.2 testsuite has been fixed. + +@item +The @code{--tool} option is now optional. + +@item +@code{runtest} when searching for test drivers ignores all directories +named SCCS, RCS, and CVS. + +@item +There is now a generic keyword based test harness that uses comments in +source code to control how each test case gets built and run. + +@item +There is now some support for running a testsuite with multiple passes +and multiple targets. + +@end enumerate + +@node Running Tests +@section Running existing tests +@cindex existing tests, running +@cindex running tests +@cindex tests, running + +@kindex make check +To run tests from an existing collection, first use @code{configure} as +usual to set up the source directory containing the tests. Then try +running + +@example +make check +@end example + +@cindex @code{check} makefile target +If the @code{check} target exists, it usually saves you some +trouble---for instance, it can set up any auxiliary programs or other +files needed by the tests. + +@cindex auxiliary files, building +Once you have run @samp{make check} to build any auxiliary files, you +might want to call the test driver @code{runtest} directly to repeat the +tests. You may also have to call @code{runtest} directly for test +collections with no @code{check} target in the @file{Makefile}. + +@c force page break to avoid losing footnote to another page +@page +@cindex @code{runtest}, most common options +@cindex options for @code{runtest}, common +Typically, you must use two command-line options: @samp{--tool}, to +specify which set of tests to run@footnote{@samp{--tool} selects a +particular suite of tests, @emph{not} the name of the executable program +to run. @xref{Config Values,,Configuration dependent values}, for +information on the variables that you can use to specify the names of +programs to run.}, and @samp{--srcdir}, to specify where to find test +directories. + +For example, if the directory @file{gdb/testsuite} contains a collection +of DejaGnu tests for @sc{gdb}, you can run them like this: + +@example +eg$ cd gdb/testsuite +eg$ runtest --tool gdb +@exdent @emph{Test output follows, ending with:} + + === gdb Summary === + +# of expected passes 508 +# of expected failures 103 +/usr/latest/bin/gdb version 4.14.4 -nx +@end example + +You can use the option @samp{--srcdir} to point to some other directory +containing a collection of tests: + +@smallexample +eg$ runtest --tool gdb --srcdir /devo/gdb/testsuite +@end smallexample + +@cindex native configuration +@cindex cross configuration +These examples assume a @dfn{native} configuration, where the same +computer runs both @code{runtest} and the tests themselves. When you +have a @dfn{cross} configuration, the tests run on a different computer, +controlled by the host running @code{runtest}. In this situation, you +need the option @samp{--name} to specify the network address for the +other computer: + +@smallexample +eg$ runtest --tool gdb --name vx9.munist.com +@end smallexample + +If you always use the same option values, you can record them in a file +called @file{site.exp}, rather than typing them each time. @xref{Config +Values,,Setting defaults for @code{runtest} options}. + +By default, @code{runtest} prints only the names of the tests it runs, +output from any tests that have unexpected results, and a summary +showing how many tests passed and how many failed. To display output +from all tests (whether or not they behave as expected), use the +@samp{--all} option. For more verbose output about processes being run, +communication, and so on, use @samp{--verbose}. To see even more output, +use multiple @samp{--verbose} options. @xref{Invoking runtest,,Using +@code{runtest}}, for a more detailed explanation of each @code{runtest} +option. + +Test output goes into two files in your current directory: summary +output in @file{@var{tool}.sum}, and detailed output in +@file{@var{tool}.log}. (@var{tool} refers to the collection of tests; +for example, after a run with @samp{--tool gdb}, look for output files +@file{gdb.sum} and @file{gdb.log}.) @xref{Output Files,,The files +DejaGnu writes}. + +@node Sample Test +@section What does a DejaGnu test look like? + +@cindex example +Each DejaGnu test is an @code{expect} script; the tests vary widely in +complexity, depending on the nature of the tool and the feature tested. + +@kindex gdb.t00/echo.exp +@kindex echo.exp +Here is a very simple @sc{gdb} test---one of the simplest tests shipped +with DejaGnu (extracted from @file{gdb.t00/echo.exp}):@footnote{More +recent @sc{gdb} tests use the @samp{gdb_test} procedure. +An equivalent test using that procedure is @samp{ gdb_test "echo Hello +world!" "Hello world!" }} +@c FIXME! include xref in footnote, when gdb_test documented in some manual. +@c @xref{}. +@c Extra spaces in @samp above avoid running end ' against " inside. + +@cartouche +@smallexample +# send a string to the GDB stdin: +send "echo Hello world!\n" + +# inspect the GDB stdout for the correct reply, +# and determine whether the test passes or fails: +expect @{ + -re "Hello world.*$prompt $" @{ pass "Echo test" @} + -re "$prompt $" @{ fail "Echo test" @} + timeout @{ fail "(timeout) Echo test" @} + @} +@end smallexample +@end cartouche + +Though brief, this example is a complete test. It illustrates some of +the main features of DejaGnu test scripts: + +@itemize @bullet +@item +The test case does not start the tested program (@sc{gdb} in this case); +all test scripts for interactive tools can assume the corresponding tool +is running. + +@item +Comments start with @samp{#}. + +@item +The main commands you use to control a tested program are @code{send} +(to give it commands) and @code{expect} (to analyze its responses). + +@item +The @code{expect} command uses a list of pairs; a pattern (regular +expression if @samp{-re} specified), followed by an action to run if the +pattern matches output from the program. Only the action for the +@emph{first} matching pattern will execute. + +@item +Test cases use the commands @code{pass} and @code{fail} to record the +test outcome. +@end itemize + +@node Design Goals +@section Design goals +@cindex design goals + +DejaGnu grew out of the internal needs of Cygnus Support. Cygnus +maintains and enhances a variety of free programs in many different +environments, and we needed a testing tool that: + +@itemize @bullet +@item +is useful to developers while fixing bugs; + +@item +automates running many tests during a software release process; + +@item +is portable among a variety of host computers; + +@item +supports cross-development testing; + +@item +permits testing interactive programs, like @sc{gdb}; and + +@item +permits testing batch oriented programs, like @sc{gcc}. +@end itemize + +Some of the requirements proved challenging. For example, interactive +programs do not lend themselves very well to automated testing. But all +the requirements are important: for instance, it is imperative to make +sure that @sc{gdb} works as well when cross-debugging as it does in a +native configuration. + +Probably the greatest challenge was testing in a cross-development +environment (which can be a real nightmare). Most cross-development +environments are customized by each developer. Even when buying +packaged boards from vendors there are many differences. The +communication interfaces vary from a serial line to ethernet. DejaGnu +was designed with a modular communication setup, so that each kind of +communication can be added as required, and supported thereafter. Once +a communication procedure is coded, any test can use it. Currently +DejaGnu can use @code{rsh}, @code{rlogin}, @code{telnet}, @code{tip}, +@code{kermit}, and @code{mondfe} for remote communications. + +@cindex name ``DejaGnu'' +@cindex DejaGnu, the name +@cindex Menapace, Julia +Julia Menapace first coined the term ``Deja Gnu'' to describe an earlier +testing framework at Cygnus Support. When we replaced it with the +Expect-based framework, it was like DejaGnu all over again@dots{} + +@node Posix +@section A POSIX conforming test framework + +@cindex POSIX conformance +@cindex standard conformance: POSIX 1003.3 +DejaGnu conforms to the @sc{posix} standard for test frameworks. + +@cindex TET +@sc{posix} standard 1003.3 defines what a testing framework needs to +provide, in order to permit the creation of @sc{posix} conformance +test suites. This standard is primarily oriented to running @sc{posix} +conformance tests, but its requirements also support testing of features +not related to @sc{posix} conformance. @sc{posix} 1003.3 does not +specify a particular testing framework, but at this time there is only +one other @sc{posix} conforming test framework: +@sc{tet}.@footnote{@sc{tet} was created by Unisoft for a consortium +comprised of X/Open, Unix International, and the Open Software +Foundation.} + +The @sc{posix} documentation refers to @dfn{assertions}. An assertion +is a description of behavior. For example, if a standard says ``The sun +shall shine'', a corresponding assertion might be ``The sun is +shining.'' A test based on this assertion would pass or fail depending +on whether it is daytime or nighttime. It is important to note that the +standard being tested is never 1003.3; the standard being tested is some +other standard, for which the assertions were written. + +As there is no test suite to test @emph{testing frameworks} for +@sc{posix} 1003.3 conformance, verifying conformance to this standard is +done by repeatedly reading the standard and experimenting. One of the +main things 1003.3 does specify is the set of allowed output messages, +and their definitions. Four messages are supported for a required +feature of @sc{posix} conforming systems, and a fifth for a conditional +feature. DejaGnu supports the use of all five output messages; in this +sense a test suite that uses exactly these messages can be considered +@sc{posix} conforming. These definitions specify the output of a test +case: + +@ftable @code +@cindex success, POSIX definition +@item PASS +A test has succeeded. That is, it demonstrated that the assertion is true. + +@cindex XFAIL, avoiding for POSIX +@item XFAIL +@sc{posix} 1003.3 does not incorporate the notion of expected failures, +so @code{PASS}, instead of @code{XPASS}, must also be returned for test +cases which were expected to fail and did not. This means that +@code{PASS} is in some sense more ambiguous than if @code{XPASS} is also +used. For information on @code{XPASS} and @code{XFAIL}, see +@ref{Invoking runtest,,Using @code{runtest}}. + +@item FAIL +@cindex failure, POSIX definition +A test @emph{has} produced the bug it was intended to capture. That is, +it has demonstrated that the assertion is false. The @code{FAIL} +message is based on the test case only. Other messages are used to +indicate a failure of the framework. + +As with @code{PASS}, @sc{posix} tests must return @code{FAIL} rather +than @code{XFAIL} even if a failure was expected. + +@item UNRESOLVED +@cindex ambiguity, required for POSIX +A test produced indeterminate results. Usually, this means the test +executed in an unexpected fashion; this outcome requires that a human +being go over results, to determine if the test should have passed or +failed. This message is also used for any test that requires human +intervention because it is beyond the abilities of the testing +framework. Any unresolved test should resolved to @code{PASS} or +@code{FAIL} before a test run can be considered finished. + +Note that for @sc{posix}, each assertion must produce a test result +code. If the test isn't actually run, it must produce @code{UNRESOLVED} +rather than just leaving that test out of the output. This means that +you have to be careful when writing tests, to not carelessly use tcl +statements like @code{return}---if you alter the flow of control of the +tcl code you must insure that every test still produces some result code. + +Here are some of the ways a test may wind up @code{UNRESOLVED}: + +@itemize @bullet +@item +A test's execution is interrupted. + +@item +A test does not produce a clear result. This is usually because there +was an @code{ERROR} from DejaGnu while processing the test, or because there +were three or more @code{WARNING} messages. Any @code{WARNING} or +@code{ERROR} messages can invalidate the output of the test. This +usually requires a human being to examine the output to +determine what really happened---and to improve the test case. + +@item +A test depends on a previous test, which fails. + +@item +The test was set up incorrectly. +@end itemize + +@item UNTESTED +A test was not run. This is a placeholder, used when there is no +real test case yet. +@end ftable + +@noindent +The only remaining output message left is intended to test features that +are specified by the applicable @sc{posix} standard as conditional: + +@ftable @code +@item UNSUPPORTED +There is no support for the tested case. This may mean that a +conditional feature of an operating system, or of a compiler, is not +implemented. DejaGnu also uses this message when a testing environment +(often a ``bare board'' target) lacks basic support for compiling or +running the test case. For example, a test for the system subroutine +@code{gethostname} would never work on a target board running only a +boot monitor. +@end ftable + +DejaGnu uses the same output procedures to produce these messages for +all test suites, and these procedures are already known to conform to +@sc{posix} 1003.3. For a DejaGnu test suite to conform to @sc{posix} +1003.3, you must avoid the @code{setup_xfail} procedure as described in +the @code{PASS} section above, and you must be careful to return +@code{UNRESOLVED} where appropriate, as described in the +@code{UNRESOLVED} section above. + +@node Future Directions +@section Future directions +@cindex future directions + +In the near future, there are two parallel directions for DejaGnu +development. The first is to add support for more hosts and targets. + +The second would permit testing programs with a more complex interface, +whether text based or GUI based. Two components already exist: a Tcl +based X window toolkit, and a terminal package for @code{expect}. Both +of these could be merged into DejaGnu in a way that permits testing +programs that run in each environment. + +Meanwhile, we hope DejaGnu enables the creation of test suites for +conformance to @sc{ansi} C and C++, to @sc{posix}, and to other +standards. We encourage you to make any test suites you create freely +available, under the same terms as DejaGnu itself. + +@node Tcl and Expect +@section Tcl and Expect +@cindex tool command language +@cindex tcl +@cindex Ousterhout, John K. +Tcl was introduced in a paper by John K. Ousterhout at the 1990 Winter +Usenix conference, @cite{Tcl: An Embeddable Command Language}. That +paper is included in PostScript form in the @file{doc} subdirectory of +the Tcl distribution. The version of Tcl included in DejaGnu at this time is +Tcl 7.4p3. + +@cindex @code{expect} scripting language +@cindex Libes, Don +Don Libes introduced @code{expect} in his paper @cite{expect: Curing +Those Uncontrollable Fits of Interaction} at the 1990 Summer Usenix +conference. The paper is included in PostScript form in the +@code{expect} distribution (as are several other papers about +@code{expect}). The version of expect included in DejaGnu at this time +is expect 5.18.0. + +@node Invoking runtest +@chapter Using @code{runtest} +@cindex invoking +@cindex running +@cindex command line options +@cindex options + +@cindex @code{runtest} description +@cindex DejaGnu test driver +@code{runtest} is the executable test driver for DejaGnu. You can +specify two kinds of things on the @code{runtest} command line: command +line options, and Tcl variables for the test scripts. The options are +listed alphabetically below. + +@cindex exit code from @code{runtest} +@cindex @code{runtest} exit code +@code{runtest} returns an exit code of @code{1} if any test +has an unexpected result; otherwise (if all tests pass or fail as +expected) it returns @code{0} as the exit code. + +@code{runtest} flags the outcome of each test as one of these cases. +(@xref{Posix,,A POSIX conforming test framework}, for a discussion of +how @sc{posix} specifies the meanings of these cases.) + +@table @code +@item PASS +@kindex PASS +@cindex successful test +@cindex test, successful +The most desirable outcome: the test succeeded, and was expected to +succeed. + +@item XPASS +@kindex XPASS +@cindex successful test, unexpected +@cindex unexpected success +A pleasant kind of failure: a test was expected to fail, but succeeded. +This may indicate progress; inspect the test case to determine whether +you should amend it to stop expecting failure. + +@item FAIL +@kindex FAIL +@cindex failing test, unexpected +@cindex test, failing +A test failed, although it was expected to succeed. This may indicate +regress; inspect the test case and the failing software to locate the bug. + +@item XFAIL +@kindex XFAIL +@cindex expected failure +@cindex failing test, expected +A test failed, but it was expected to fail. This result indicates no +change in a known bug. If a test fails because the operating system +where the test runs lacks some facility required by the test, the +outcome is @code{UNSUPPORTED} instead. + +@item UNRESOLVED +@kindex UNRESOLVED +@cindex test, unresolved outcome +Output from a test requires manual inspection; the test suite could not +automatically determine the outcome. For example, your tests can report +this outcome is when a test does not complete as expected. + +@item UNTESTED +@kindex UNTESTED +@cindex untested properties +A test case is not yet complete, and in particular cannot yet produce a +@code{PASS} or @code{FAIL}. You can also use this outcome in dummy +``tests'' that note explicitly the absence of a real test case +for a particular property. + +@item UNSUPPORTED +@kindex UNSUPPORTED +@cindex unsupported test +@cindex test, unsupported +A test depends on a conditionally available feature that does not exist +(in the configured testing environment). For example, you can use this +outcome to report on a test case that does not work on a particular +target because its operating system support does not include a required +subroutine. +@end table + +@code{runtest} may also display the following messages: + +@table @code +@item ERROR +@kindex ERROR +@cindex problem, detected by test case +@cindex test case cannot run +Indicates a major problem (detected by the test case itself) in running +the test. This is usually an unrecoverable error, such as a missing file +or loss of communication to the target. (@sc{posix} test suites should +not emit this message; use @code{UNSUPPORTED}, @code{UNTESTED}, or +@code{UNRESOLVED} instead, as appropriate.) + +@item WARNING +@kindex WARNING +@cindex test case warnings +Indicates a possible problem in running the test. Usually warnings +correspond to recoverable errors, or display an important message about +the following tests. + +@item NOTE +@kindex NOTE +@cindex test case messages +An informational message about the test case. +@end table + +This is the full set of command line options that @code{runtest} +recognizes. Arguments may be abbreviated to the shortest unique string. + +@cindex @code{runtest} option list +@cindex option list, @code{runtest} +@smallexample +runtest --tool @var{tool} [ @var{testsuite}.exp @dots{} ] +[ @var{testsuite}.exp="testfile1 @dots{}" ] +[ @var{tclvar}=@var{value}@dots{} ] +[ --all ] [ --baud @var{baud-rate} ] [ --connect @var{type} ] +[ --debug ] [ --help ] [ --host @var{string} ] +[ --mail "@var{name} @dots{}" ] [ --name @var{string} ] +[ --name @var{name} ] [ --outdir @var{path} ] +[ --objdir @var{path} ] [ --reboot ] +[ --srcdir @var{path} ] [ --strace @var{n} ] +[ --target @var{string} --build @var{string} ] +[ -v | --verbose ] [ -V | --version ] [ --D@var{n} ] +@end smallexample + +@table @code +@item --tool @var{tool} +@cindex selecting tests for a tool +@cindex @code{--tool} (@code{runtest} option) +@var{tool} specifies what set of tests to run, and what initialization +module to use. @var{tool} is used @emph{only} for these two purposes: +it is @emph{not} used to name the executable program to test. +Executable tool names (and paths) are recorded in @file{site.exp} +(@pxref{Config Values,,Configuration dependent values}), and you can +override them by specifying Tcl variables on the command line. + +For example, including @samp{--tool gcc} on the @code{runtest} command +line runs tests from all test subdirectories whose names match +@file{gcc.*}, and uses one of the initialization modules named +@file{config/*-gcc.exp}. To specify the name of the compiler (perhaps +as an alternative path to what @code{runtest} would use by default), use +@samp{GCC=@var{binname}} on the @code{runtest} command line. + +@item @var{testsuite}.exp @dots{} +@cindex selecting a range of tests +@cindex tests, running specifically +@cindex naming tests to run +Specify the names of testsuites to run. +By default, @code{runtest} runs all tests for the tool, but you can +restrict it to particular testsuites by giving the names of the @samp{.exp} +@code{expect} scripts that control them. + +@var{testsuite}.exp may not include path information; use plain filenames. + +@item @var{testfile}.exp="testfile1 @dots{}" +@cindex selecting a range of tests +@cindex tests, running specifically +@cindex naming tests to run +Specify a subset of tests in a suite to run. +For compiler or assembler tests, which often use a single @samp{.exp} +script covering many different source files, this option allows you to +further restrict the tests by listing particular source files to compile. +Some tools even support wildcards here. The wildcards supported depend +upon the tool, but typically they are @code{?}, @code{*}, and @code{[chars]}. + +@item @var{tclvar}=@var{value} +@kindex @var{tclvar}=@var{value} +@cindex Tcl variables, defining for @code{runtest} +@cindex command line Tcl variable definition +@cindex @code{runtest}, variable defns on cmdline +You can define Tcl variables for use by your test scripts in the same +style used with @code{make} for environment variables. For example, +@samp{runtest GDB=gdb.old} defines a variable called @samp{GDB}; when +your scripts refer to @samp{$GDB} in this run, they use the value +@samp{gdb.old}. + +The default Tcl variables used for most tools are defined in the main +DejaGnu @code{Makefile}; their values are captured in the +@file{site.exp} file. @xref{Config Values,,Configuration dependent +values}. + +@item --all +@cindex @code{--all} (@code{runtest} option) +@cindex test output, displaying all +Display all test output. By default, @code{runtest} shows only the +output of tests that produce unexpected results; that is, tests with +status @samp{FAIL} (unexpected failure), @samp{XPASS} (unexpected +success), or @samp{ERROR} (a severe error in the test case itself). +Specify @samp{--all} to see output for tests with status @samp{PASS} +(success, as expected) @samp{XFAIL} (failure, as expected), or +@samp{WARNING} (minor error in the test case itself). + +@item --baud @var{baud-rate} +@itemx -b @var{baud-rate} +@cindex baud rate, specifying +@cindex bps, specifying +@cindex @code{--baud} (@code{runtest} option) +@cindex @code{-b} (@code{runtest} option) +Set the default baud rate to something other than 9600. (Some serial +interface programs, like @code{tip}, use a separate initialization file +instead of this value.) + +@item --connect @var{type} +@cindex connecting to target +@cindex @code{--connect} (@code{runtest} option) +@cindex remote testbed, connecting to +@cindex @code{rlogin}, remote testing via +@cindex @code{telnet}, remote testing via +@cindex @code{rsh}, remote testing via +@cindex @code{tip}, remote testing via +@cindex @code{kermit}, remote testing via +@cindex @code{mondfe}, remote testing via +@cindex remote testing via @code{rlogin} +@cindex remote testing via @code{telnet} +@cindex remote testing via @code{rsh} +@cindex remote testing via @code{tip} +@cindex remote testing via @code{kermit} +@cindex remote testing via @code{mondfe} +Connect to a target testing environment as specified by @var{type}, if +the target is not the computer running @code{runtest}. For example, use +@samp{--connect} to change the program used to connect to a ``bare +board'' boot monitor. The choices for @var{type} in the DejaGnu 1.0 +distribution are @samp{rlogin}, @samp{telnet}, @samp{rsh}, @samp{tip}, +@samp{kermit}, and @samp{mondfe}. + +@noindent +The default for this option depends on the configuration (@pxref{Cross +Targets,,Remote targets supported}). The default is chosen to be the +most convenient communication method available, but often other +alternatives work as well; you may find it useful to try alternative +connect methods if you suspect a communication problem with your testing +target. + +@item --debug +@cindex @code{--debug} (@code{runtest} option) +@cindex debug log for test cases +@cindex test cases, debug log +@cindex @code{dbg.log} file +Turns on the @code{expect} internal debugging output. Debugging output +is displayed as part of the @code{runtest} output, and logged to a file +called @file{dbg.log}. The extra debugging output does @emph{not} +appear on standard output, unless the verbose level is greater than 2 +(for instance, to see debug output immediately, specify @samp{--debug -v +-v}). The debugging output shows all attempts at matching the test +output of the tool with the scripted patterns describing expected +output. The output generated with @samp{--strace} also goes into +@file{dbg.log}. + +@item --help +@itemx -he +@cindex @code{--help} (@code{runtest} option) +@cindex help with @code{runtest} +@cindex @code{runtest}, listing options +Prints out a short summary of the @code{runtest} options, then exits +(even if you also specify other options). + +@item --host @var{string} +@cindex @code{--host} (@code{runtest} option) +@cindex specifying the host config name +@cindex host config name, changing +@var{string} is a full configuration ``triple'' name as used by +@code{configure}. Use this option to override the default string +recorded by your configuration's choice of host. This choice does not +change how anything is actually configured unless --build is also +specified; it affects @emph{only} DejaGnu procedures that compare the +host string with particular values. The procedures @code{ishost}, +@code{istarget}, @code{isnative}, and @code{setup_xfail} are affected by +@samp{--host}. In this usage, @code{host} refers to the machine that the +tests are to be run on, which may not be the same as the @code{build} +machine. If @code{--build} is also specified, then @code{--host} refers +to the machine that the tests wil, be run on, not the machine DejaGnu is +run on. + +@item --build @var{string} +@cindex @code{--build} (@code{runtest} option) +@cindex specifying the build config name +@cindex build config name, changing +@var{string} is a full configuration ``triple'' name as used by +@code{configure}. This is the type of machine DejaGnu and the tools to +be tested are built on. For a normal cross this is the same as the host, +but for a canadian cross, they are seperate. + +@item --name @var{name} +@cindex specifying target name +@cindex target machine name +@cindex @code{--name} (@code{runtest} option) +@var{name} is a name for the particular testing target machine (for +cross testing). If the testing target has IP network support (for +example, @code{RPC} or @code{NFS}), this is the network name for the +target itself. (@var{name} is @emph{not the configuration string} you +specify as a target with @code{configure}; the @samp{--name} option +names a particular target, rather than describing a class of targets.) +For targets that connect in other ways, the meaning of the @var{name} +string depends on the connection method. @xref{Cross Targets,,Remote +targets supported}. + +@item --name @var{string} +@cindex remote test machine name +@cindex name for remote test machine +Specify a network name of testing target or its host. The particular +names that are meaningful with @samp{--name} will depend on your site +configuration, and on the connection protocol: for example, @code{tip} +connections require names from a serial line configuration file (usually +called @file{/etc/remote}), while @code{telnet} connections use IP +hostnames. + +@item --objdir @var{path} +@cindex @code{--objdir} (@code{runtest} option) +@cindex object directory +@cindex test programs, auxiliary +@cindex auxiliary test programs +Use @var{path} as the top directory containing any auxiliary compiled +test code. This defaults to @file{.}. Use this option to locate +pre-compiled test code. You can normally prepare any auxiliary files +needed with @code{make}. + +@item --outdir @var{path} +@cindex output directory +@cindex @code{--outdir} (@code{runtest} option) +@cindex log files, where to write +Write output logs in directory @var{path}. The default is @samp{.}, the +directory where you start @code{runtest}. This option affects only the +summary and the detailed log files @file{@var{tool}.sum} and +@file{@var{tool}.log}. The DejaGnu debug log @file{dbg.log} always +appears (when requested) in the local directory. + +@item --reboot +@cindex rebooting remote targets +@cindex @code{--reboot} (@code{runtest} option) +Reboot the target board when @code{runtest} initializes. +Usually, when running tests on a separate target board, it is safer to +reboot the target to be certain of its state. However, when developing +test scripts, rebooting takes a lot of time. + +@item --srcdir @var{path} +@cindex source directory +@cindex @code{--srcdir} (@code{runtest} option) +Use @var{path} as the top directory for test scripts to run. +@code{runtest} looks in this directory for any subdirectory whose name +begins with the toolname (specified with @samp{--tool}). For instance, +with @samp{--tool gdb}, @code{runtest} uses tests in subdirectories +@file{gdb.*} (with the usual shell-like filename expansion). If you do +not use @samp{--srcdir}, @code{runtest} looks for test directories under +the current working directory. + +@item --strace @var{n} +@cindex @code{--strace} (@code{runtest} option) +@cindex tracing Tcl commands +@cindex @code{expect} internal tracing +Turn on internal tracing for @code{expect}, to @var{n} levels deep. By +adjusting the level, you can control the extent to which your output +expands multi-level Tcl statements. This allows you to ignore some +levels of @code{case} or @code{if} statements. Each procedure call or +control structure counts as one ``level''. + +The output is recorded in the same file, @file{dbg.log}, used for output +from @samp{--debug}. + +@item --target @var{string} +@cindex @code{--target} (@code{runtest} option) +@cindex specifying the target configuration +@cindex target configuration, specifying +Use this option to override the default setting (running native tests). +@var{string} is a full configuration ``triple'' +name@footnote{Configuration triples have the form +@samp{@var{cpu}-@var{vendor}-@var{os}}.} as used by @code{configure}. +This option changes the configuration @code{runtest} uses for the +default tool names, and other setup information. @xref{Using +configure,,Using @code{configure}, configure.info, Cygnus configure}, +for details about @code{configure} names. + +@item --verbose +@itemx -v +@cindex @code{--verbose} (@code{runtest} option) +@cindex @code{-v} (@code{runtest} option) +@cindex turning on output +@cindex output, additional +Turns on more output. Repeating this option increases the amount of +output displayed. Level one (@samp{-v}) is simply test output. Level +two (@samp{-v -v}) shows messages on options, configuration, and process +control. Verbose messages appear in the detailed (@file{*.log}) log +file, but not in the summary (@file{*.sum}) log file. + +@item --version +@itemx -V +@cindex @code{-V} (@code{runtest} option) +@cindex @code{--version} (@code{runtest} option) +@cindex version numbers +Prints out the version numbers of DejaGnu, @code{expect} and Tcl, and +exits without running any tests. + +@item -D0 +@itemx -D1 +@cindex starting the tcl debugger +@cindex tcl debugger +@c FIXME!!! we should say a *lot* more about this debugger +Start the internal Tcl debugger. The Tcl debugger supports breakpoints, +single stepping, and other common debugging activities. (See @cite{A +Debugger for Tcl Applications} by Don Libes. @footnote{Distributed in +PostScript form with @code{expect} as the file@* +@file{expect/tcl-debug.ps}.}) + +If you specify @samp{-D1}, the @code{expect} shell stops at a breakpoint +as soon as DejaGnu invokes it. + +If you specify @samp{-D0}, DejaGnu starts as usual, but you can enter +the debugger by sending an interrupt (e.g. by typing @key{C-c}). +@end table + +@node Customizing +@chapter Setting @code{runtest} defaults + +@kindex site.exp +@cindex variables of DejaGnu, defaults +The site configuration file, @file{site.exp}, captures +configuration-dependent values and propagates them to the DejaGnu test +environment using Tcl variables. This ties the DejaGnu test scripts +into the @code{configure} and @code{make} programs. + +@cindex @file{site.exp}, multiple +@cindex overriding @file{site.exp} +DejaGnu supports more than one @file{site.exp} file. The multiple +instances of @file{site.exp} are loaded in a fixed order built into +DejaGnu (the more local last). The first file loaded is the optional +@code{~/.dejagnurc}, then the local files, and finally the global file. + +@enumerate +@item +There is am optional ``master'' @file{site.exp}, capturing configuration values +that apply to DejaGnu across the board, in each configuration-specific +subdirectory of the DejaGnu library directory. @code{runtest} loads +these values first. @xref{Installation,,Configuring and Installing +DejaGnu}. The master @file{site.exp} contains the default values for +all targets and hosts supported by DejaGnu. This master file is +identified by setting the environment variable @code{DEJAGNU} to the +name of the file. This is also refered to as the ``global'' config file. + +@item +Any directory containing a configured test suite also has a +@file{site.exp}, capturing configuration values specific to the tool +under test. Since @code{runtest} loads these values last, the +individual test configuration can either rely on and use, or override, +any of the global values from the ``master'' @file{site.exp}. + +You can usually generate or update the testsuite @file{site.exp} by +typing @samp{make site.exp} in the test suite directory, after the test +suite is configured. + +@item +You can also have a file in your home directory called +@code{.dejagnurc}. This gets loaded first before the other config +files. Usually this is used for personal stuff, like setting +@code{all_flag} so all the output gets printed, or verbosity levels. +@end enumerate + +You can further override the default values in a user-editable section +of any @file{site.exp}, or by setting variables on the @code{runtest} +command line. + +@menu +* Config Values:: Variables used in the configuration file. +* Master Config File:: The master configuration file. +* Local Config File:: The local configuration file. +* Personal Config File:: The personal configuration file. +@end menu + +@node Config Values, Master Config File, , Customizing +@subsection Config Variables +@cindex configuration dependent defaults +@cindex setting defaults for DejaGnu variables + +@c NOTE: default values are given via @code{"fubar"} rather than the +@c more conventional @samp{fubar} to permit a consistent and clear +@c notation for the empty string (@code{""}), which will work exactly as +@c typed. + +DejaGnu uses a named array in Tcl to hold all the info for each +machine. In the case of a canadian cross, this means host information as +well as target information. The named array is called +@code{target_info}, and it has two indices. The following fields are +part of the array. + +@table @code +@item name +The name of the target. (mostly for error messages) This +should also be the string used for this target's array. +It should also be the same as the linker script so we +can find them dynamically. This should be the same as the argument used +for @code{push_target@{@}}. + +@item ldflags +This is the linker flags required to produce a fully linked +executable. For @code{libgloss} supported targets this is usually just +the name of the linker script. + +@item config +The target canonical for this target. This is used by some init files to +make sure the target is supported. + +@item cflags +The flags required to produce an object file from a source file. + +@item connect +This is the connectmode for this target. This is for both IP and +serial connections. Typically this is either @code{telnet}, +@code{rlogin}, or @code{rsh}. + +@item target +This is the hostname of the target. This is for TCP/IP based connections, +and is also used for version of tip that use /etc/remote. + +@item serial +This is the serial port. This is typically /dev/tty? or com?:. + +@item netport +This is the IP port. This is commonly used for telneting to target +boards that are connected to a terminal server. In that case the IP port +specifies the which serial port to use. + +@item baud +This is the baud rate for a serial port connection. + +@item x10 +This is the parameters for an x10 controller. These are simple devices +that let us power cycle or reset a target board remotely. + +@item fileid +This is the fileid or spawn id of of the connection. + +@item prompt +a glob style pattern to recognize the prompt. + +@item abbrev +abbreviation for tool init files. + +@item ioport +This is the port for I/O on dual port systems. In this configuration, +the main serial port @code{0} is usually used for stdin and stdout, +which the second serial port can be used for debugging. +@end table + +The first index into the array is the same value as used in the +@code{name} field. This is usually a short version of the name of the +target board. For an example, here's the settings I use for my +@code{Motorola's} @code{IDP} board and my @code{Motorola} 6U VME +@code{MVME135-1} board. (both m68k targets) + +@cartouche +@smallexample +# IDP board +set target_info(idp,name) "idp" +set target_info(idp,ldflags) "-Tidp.ld" +set target_info(idp,config) m68k-unknown-aout +set target_info(idp,cflags) "" +set target_info(idp,connect) telnet +set target_info(idp,target) "s7" +set target_info(idp,serial) "tstty7" +set target_info(idp,netport) "wharfrat:1007" +set target_info(idp,baud) "9600" +# MVME 135 board +set target_info(idp,name) "mvme" +set target_info(idp,ldflags) "-Tmvme.ld" +set target_info(idp,config) m68k-unknown-aout +set target_info(idp,cflags) "" +set target_info(idp,connect) telnet +set target_info(idp,target) "s8" +set target_info(idp,serial) "tstty8" +set target_info(idp,netport) "wharfrat:1008" +set target_info(idp,baud) "9600" +@end smallexample +@end cartouche + +DejaGnu can use this information to switch between multiple targets in +one test run. This is done through the use of the @code{push_target} +procedure, which is discussed elsewhere. +@c FIXME: write that section and put an xref here + +This array can also hold information for a remote host, which is used +when testing a candain cross. In this case, the only thing different is +the index is just @code{host}. Here's the settings I use to run tests +on my NT machine while running DejaGnu on a Unix machine. (in this case +a Linux box) + +@cartouche +@smallexample +set target_info(host,name) "nt-host" +set target_info(host,config) "386-unknown-winnt" +set target_info(host,connect) "telnet" +set target_info(host,target) "ripple" +@end smallexample +@end cartouche + +There is more info on how to use these variables in the sections on the +config files. @xref{Master Config File,,Configuration Files}. + +@cindex option defaults +@cindex @code{runtest} option defaults +@cindex variables for option defaults +@cindex defaults, option +In the user editable second section of @file{site.exp}, you can not only +override the configuration variables captured in the first section, but +also specify default values for all the @code{runtest} command line +options. Save for @samp{--debug}, @samp{--help}, and @samp{--version}, +each command line option has an associated Tcl variable. Use the Tcl +@code{set} command to specify a new default value (as for the +configuration variables). The following table describes the +correspondence between command line options and variables you can set in +@file{site.exp}. @xref{Invoking runtest,,Running the Tests}, for +explanations of the command-line options. + +@kindex all_flag +@kindex baud +@kindex reboot +@kindex outdir +@kindex objdir +@kindex runtests +@kindex ignoretests +@kindex srcdir +@kindex tracelevel +@kindex targetname +@kindex connectmode +@kindex tool +@kindex target_triplet +@kindex host_triplet +@kindex build_triplet +@kindex verbose + +@cindex command line option variables +@cindex Tcl variables for option defaults +@cindex default options, controlling +@cindex options, Tcl variables for defaults + +@ifinfo +@display +runtest Tcl +option variable description +__________ ________ ___________________________________________ + +--all all_flag display all test results if set + +--baud baud set the default baud rate to something other + than 9600. +--connect connectmode @samp{rlogin}, @samp{telnet}, @samp{rsh}, + @samp{kermit}, @samp{tip}, or @samp{mondfe} + +--outdir outdir directory for @file{@var{tool}.sum} and @file{@var{tool}.log} + +--objdir objdir directory for pre-compiled binaries + +--reboot reboot reboot the target if set to @code{"1"}; + do not reboot if set to @code{"0"} (the default) + +--srcdir srcdir directory of test subdirectories + +--strace tracelevel a number: Tcl trace depth + +--tool tool name of tool to test; identifies init, test subdir + +--verbose verbose verbosity level. As option, use multiple times; + as variable, set a number, 0 or greater +--target target_triplet The canonical configuration string for the target. +--host host_triplet The canonical configuration string for the host. +--build build_triplet The canonical configuration string for the + build host. + +@end display +@end ifinfo + +@tex +\vbox{\halign{\hfil \tt #\quad &\quad\tt #\hfil &\hbox{\vtop{{\raggedright\parindent=0pt\parskip=5pt\hsize=2.75in\rm#\strut\par}}}\hfill\cr +\cr +{\it runtest}&{\it Tcl}\cr +{\it option}&{\it variable}&{\it description}\cr +\noalign{\hrule width\hsize}\cr +--all &all\_flag &display all test results if set\cr +--baud &baud &set the default baud rate to something other + than 9600.\cr +--connect &connectmode &@samp{rlogin}, @samp{telnet}, @samp{rsh}, + @samp{kermit}, @samp{tip}, or @samp{mondfe}\cr +--mail &mailing\_list&address list for mailing test output\cr +--name &targetname &network name of testing target or its host\cr +--outdir &outdir &directory for @file{@var{tool}.sum} and @file{@var{tool}.log}\cr +--objdir &objdir &directory for compiled binaries\cr +--reboot &reboot &reboot the target if set to @code{"1"}; +do not reboot if set to @code{"0"} (the default)\cr +--srcdir &srcdir &directory of test subdirectories\cr +--strace &tracelevel &a number: Tcl trace depth\cr +--tool &tool &name of tool to test; identifies init, test subdir\cr +--verbose &verbose &verbosity level. As option, use multiple times; + as variable, set a number, 0 or greater\cr +--target &target\_triplet + &The canonical configuration string for the target.\cr +--host &host\_triplet &The canonical configuration string for the host.\cr +--build &build\_triplet &The canonical configuration string for the + build host.\cr +}} +@end tex + +@node Master Config File, Local Config File, Config Values, Customizing +@subsection Master Config File +@cindex master @file{site.exp} +@cindex @file{site.exp} for all of DejaGnu +The master config file is where all the target specific config variables +get set for a whole site get set. The idea is that for a centralized +testing lab where people have to share a target between multiple +developers. There are settings for both remote targets and remote hosts. +Here's an example of a Master Config File (also called the Global config +file) for a @emph{canadian cross}. A canadian cross is when you build +and test a cross compiler on a machine other than the one it's to be +hosted on. + +Here we have the config settings for our California office. Note that +all config values are site dependant. Here we have two sets of values +that we use for testing m68k-aout cross compilers. As both of these +target boards has a different debugging protocol, we test on both of +them in sequence. + +@cartouche +@smallexample +global CFLAGS +global CXXFLAGS + +case "$target_triplet" in @{ + @{ "native" @} @{ + set target_abbrev unix + @} + @{ "m68*-unknown-aout" @} @{ + set target_abbrev "rom68k" + # IDP target # IDP board with rom68k monitor + set target_info(idp,name) "idp" + set target_info(idp,ldflags) "-Tidp.ld" + set target_info(idp,config) m68k-unknown-aout + set target_info(idp,cflags) "" + set target_info(idp,connect) telnet + set target_info(idp,target) "s7" + set target_info(idp,serial) "tstty12" + set target_info(idp,netport) "truckin:1007" + set target_info(idp,baud) "9600" + # MVME target # Motorola MVME 135 with BUG monitor + set target_info(mvme,name) "mvme" + set target_info(mvme,ldflags) "-Tmvme.ld" + set target_info(mvme,config) m68k-unknown-aout + set target_info(mvme,cflags) "" + set target_info(mvme,connect) telnet + set target_info(mvme,target) "s4" + set target_info(mvme,serial) "tstty8" + set target_info(mvme,netport) "truckin:1004" + set target_info(mvme,baud) "9600" + @} +@} +@end smallexample +@end cartouche + + In this case, we have support for several remote hosts for +our m68k-aout cross compiler. Typically the remote Unix hosts run +DejaGnu locally, but we also use them for debugging the testsuites when +we find problems in running on remote hosts. Expect won't run on NT, so +DejaGnu is run on the local build machine, and it'll connect to the NT +host and run all the tests for this cross compiler on that host. + +@smallexample +@cartouche +case "$host_triplet" in @{ + "native" @{ + @} + "i?86-*-linux*" @{ # Linux host + set target_info(host,name) "linux-host" + set target_info(host,config) $host_triplet + set target_info(host,connect) rlogin + set target_info(host,target) chinadoll + @} + "i?86-*-winnt # NT host + set target_info(host,name) "nt-host" + set target_info(host,config) i386-unknown-winnt + set target_info(host,connect) telnet + set target_info(host,target) ripple + @} + "hppa*-hp-hpux*" @{ # HP-UX host + set target_info(host,name) "hpux-host" + set target_info(host,config) $host_triplet + set target_info(host,connect) rlogin + set target_info(host,target) slipknot + @} + "sparc-sun-sunos*" @{ # SunOS (sun4) + set target_info(host,name) "sunos-host" + set target_info(host,config) $host_triplet + set target_info(host,connect) rlogin + set target_info(host,target) darkstar + @} +@} +@end cartouche +@end smallexample + +@node Local Config File, Personal Config File, Master Config File, Customizing +@subsection Local Config File +@cindex local @file{site.exp} +@cindex @file{site.exp} for each tool +It is usually more convenient to keep these ``manual overrides'' in the +@file{site.exp} local to each test directory, rather than in the +``master'' @file{site.exp} in the DejaGnu library. + +All local @file{site.exp} usually files have two sections, separated by +comment text. The first section is the part that is generated by +@code{make}. It is essentially a collection of Tcl variable definitions +based on @file{Makefile} environment variables. Since they are generated +by @code{make}, they contain the values as specified by +@code{configure}. (You can also customize these values by using the +@samp{--site} option to @code{configure}.) In particular, this section +contains the @file{Makefile} variables for host and target configuration +data. Do not edit this first section; if you do, your changes are replaced +next time you run @code{make}. + +The first section starts with: + +@cartouche +@smallexample +## these variables are automatically generated by make ## +# Do not edit here. If you wish to override these values +# add them to the last section +@end smallexample +@end cartouche + +In the second section, you can override any default values (locally to +DejaGnu) for all the variables. The +second section can also contain your preferred defaults for all the +command line options to @code{runtest}. This allows you to easily +customize @code{runtest} for your preferences in each configured +test-suite tree, so that you need not type options repeatedly on the +command line. (The second section may also be empty, if you do not wish +to override any defaults.) + +The first section ends with this line: + +@cartouche +@smallexample +## All variables above are generated by configure. Do Not Edit ## +@end smallexample +@end cartouche + +You can make any changes under this line. If you wish to redefine a +variable in the top section, then just put a duplicate value in this +second section. Usually the values defined in this config file are +related to the configuration of the test run. This is the ideal place to +set the variables @code{host_triplet}, @code{build_triplet}, +@code{target_triplet}. All other variables are tool dependant. ie for +testing a compiler, the value for @var{CC} might be set to a freshly +built binary, as opposed to one in the user's path. + +@node Personal Config File, , Local Config File, Customizing +@subsection Personal Config File +@cindex personal config @file{site.exp} +@cindex @file{site.exp} for each person +The personal config file is used to customize @code{runtest's} behaviour +for each person. It's typically used to set the user prefered setting +for verbosity, and any experimental Tcl procedures. My personal +@file{~/.dejagnurc} file looks like: + +@cartouche +@smallexample +set all_flag 1 +set RLOGIN /usr/ucb/rlogin +set RSH /usr/ucb/rsh +@end smallexample +@end cartouche + +Here I set @code{all_flag} so I see all the test cases that PASS along +with the ones that FAIL. I also set @var{RLOGIN} and @code{RSH} to the +BSD version. I have @code{kerberos} installed, and when I rlogin to a +target board, it usually isn't supported. So I use the non secure +versions of these programs rather than the default that's in my path. + +@node Internals +@chapter The DejaGnu Implementation +@cindex operating principles +@cindex internal details + +DejaGnu is entirely written in @code{expect}, which uses Tcl as a +command language. @code{expect} serves as a very programmable shell; +you can run any program, as with the usual Unix command shells---but +once the program is started, your @code{expect} script has fully +programmable control of its input and output. This does not just apply +to the programs under test; @code{expect} can also run any auxiliary +program, such as @code{diff} or @code{sh}, with full control over its +input and output. + +DejaGnu itself is merely a framework for the set of test suites +distributed separately for each @sc{gnu} tool. Future releases of +@sc{gnu} tools will include even more tests, developed throughout the +free software community. + +@kindex runtest.exp +@code{runtest} is the glue to tie together and manage the test scripts. +The @code{runtest} program is actually a simple Bourne shell script that +locates a copy of the @code{expect} shell and then starts the main Tcl +code, @code{runtest.exp}. @code{runtest.exp} itself has these essential +functions: + +@enumerate +@item +Parse the command line options, load the library files, and load the +default configuration files. + +@item +Locating the individual test scripts. @code{runtest.exp} locates the tests +by exploiting a straightforward naming convention based on the string +you specify with the @samp{--tool} option. + +@item +Providing an extended test environment, by defining additional Tcl +procedures beyond those already in @code{expect}. + +@item +Locating target-dependent functions, to standardize the test environment +across a wide variety of test platforms. +@end enumerate + +@menu +* Names:: Conventions for using tool names +* Init Module:: Initialization module +* DejaGnu Builtins:: DejaGnu provides these Tcl procedures +* Target Dependent:: Procedures supplied by the init module +* Cross Targets:: Remote targets supported +* Input Files:: The files DejaGnu depends on +* Output Files:: The files DejaGnu produces +@end menu + +@node Names +@section Conventions for using tool names + +@cindex @code{--tool} and naming conventions +@cindex tool names and naming conventions +@cindex naming conventions +DejaGnu uses @samp{$tool}, the name of the tool under test, to tie +together the testing configuration in a straightforward but flexible +way. If there is only one testsuite for a particular application, then +@samp{$tool} is optional. + +@samp{$tool} is @emph{not} used to invoke the tool, since sites that run +multiple configurations of a particular tool often call each +configuration by a different name. @code{runtest} uses the +configuration-dependent variables captured in @file{site.exp} to +determine how to call each tool. + +@cindex directory names and @code{--tool} +@cindex test directories, naming +@code{runtest} uses tool names to find directories containing tests. +@code{runtest} scans the source directory (specified with +@code{--srcdir}) for all directories whose names start with the tool +name. It is a common practice to put a period after the tool part of the +name. For instance, directories that start with +@samp{g++.} contain @sc{g++} tests. To add a new test, just put it in +any directory (create an entirely new directory, if you wish) whose name +follows this convention. + +@cindex @code{exp} filename suffix +@cindex test filename +@cindex filename for test files +A test is any file in an appropriately named subdirectory whose name +ends in @samp{.exp} (the conventional way of naming @code{expect} +scripts). These simple naming conventions make it as simple as possible +to install new tests: all you must do is put the test in the right +directory. + +@cindex order of tests +@cindex tests, running order +@code{runtest} sorts the tests in each subdirectory by name (using the +Tcl @code{lsort} command) and runs them in the resulting order. + +@node Init Module +@section Initialization module +@cindex tool initialization +@cindex setting up targets + +@c FIXME! should this node be merged with "Target dependent"? + +@cindex init file, purpose +@cindex starting interactive tools +@cindex initialization +The initialization module (or ``init file'') has two purposes: to +provide tool and target dependent procedures, and to start up an +interactive tool to the point where it is ready to operate. The latter +includes establishing communications with the target. All the tests for +interactive programs assume that the tool is already running and +communicating. Initialization modules for non-interactive programs may +only need to supply the support functions. + +@cindex init file name +@cindex name, initialization module +Each test suite directory must contain (in its @file{config} +subdirectory) a separate initialization module for each target. The +appropriate init file is can be named several ways. The prefered name is +the @emph{os} part of the canonical configuration name with @code{.exp} +as the suffix. An example would be that for an @code{m68k-coff} system, +the @code{target_os} part would be @code{coff}. The next way is for +system where there are short filenames, or a shortcut is desired to +refer to the OS name for that target. This is uses the value of +@code{$target_abbrev} rather than the @code{target_os}. + +The final file looked for is simply @file{default.exp}. If there is only +one operating system to support, then this file can be used. It's main +purpose is to offer some support for new operating systems, or for +unsupported cross targets. The last file looked for is +@file{unknown.exp}. This is usually limited to error handling for +unsupported targets. It's whole contents is typically. + +@cartouche +@smallexample +perror "Sorry, there is no support for this target" +exit 1 +@end smallexample +@end cartouche + +At the beginning of the init file, you must first determine the proper +executable name of the tool to execute, since the actual name of the +tool to be tested my vary from system to system. Here's an example +for the @sc{GNU} C compiler. + +@cartouche +@smallexample +global AR +# look for the archiver ar +if ![info exists AR] @{ + set AR [findfile $base_dir/../../binutils/ar $base_dir/../../binutils/ar [tr +ansform ar]] + verbose "AR defaulting to $AR" 2 +@} +@} + +global CFLAGS +if ![info exists CFLAGS] then @{ + set CFLAGS "" +@} +@end smallexample +@end cartouche + +It is always a good idea to first check the variable, and only set it if +it has not yet been defined. Often the proper value of @code{AR} is set +on the command line that invokes @file{runtest}. + +@kindex findfile +The @code{findfile} procedure takes as it's first argument a file name +to look for. The second argument is returned if the file is found, and +the third argument is returned if the file is not found. @code{base_dir} +is set internally by DejaGnu to the top level directory of the object +tree. + +@kindex transform +The @code{transform} procedure takes as its argument the native name of +a tool (such as @samp{gcc} for the compiler), and returns the name as +configured for that tool in the current installation. (For example, a +cross-compiling version of @sc{gnu} CC that generates MIPS code may be +installed with a name like @code{mips-idt-ecoff-gcc}.) + +In a test running native, writing the Tcl code for initialization is +usually quite simple. For cross configurations, however, more elaborate +instructions are usually needed to describe how to talk to a remote +target. + +Each initialization module defines up to four procedures with standard +names and purposes. The names of these procedures begin with +@samp{$tool}, the string that identifies tests for a particular tool: +@code{$tool_start}, @code{$tool_load}, @code{$tool_exit}, and +@code{$tool_version}. For example, the start procedure for @sc{gdb} is +called @code{gdb_start}. (Since start procedures are used differently +for batch and interactive tools, however, @code{runtest} itself never +calls the start procedure. Init files for interactive tools are +expected to end by running the start procedure.) + +@cindex utilities, loading from init file +@cindex defaults, setting in init file +The initialization module is also a good place to call @code{load_lib} +to get any collections of utility procedures meant for a family of test +cases, and to set up default values for any additional Tcl variables +needed for a specific set of tests. + +@xref{Target Dependent,,Target dependent procedures}, for full +descriptions of these procedures. + +@node DejaGnu Builtins +@section DejaGnu procedures +@cindex built in procedures, DejaGnu + +DejaGnu provides these Tcl procedures for use in test scripts. +You can also use any standard @code{expect} or Tcl function. These +procedures are stored in libraries, which DejaGnu loads at +runtime. Here's explanation of the library procedures that get loaded at +runtime. All other librarys are optional, and need to be loaded by the +testsuite. + +@menu +* framework.exp:: Core Internal Procedures. +* remote.exp:: Procedures for remote communication. +* utils.exp:: Utility procedures. +* target.exp:: Cross target procedures. +* debugger.exp:: Procedures for debugging your Tcl code. +@end menu + +@node framework.exp, remote.exp, ,DejaGnu Builtins +@subsection Core Internal Procedures +@cindex Core Internal Procedures + +@xref{Posix,,A POSIX conforming test framework}, for more detailed +explanations of the test outcomes (@samp{FAIL}, @samp{PASS}, +@samp{UNTESTED}, @samp{UNRESOLVED}, @samp{UNSUPPORTED}). + +@ftable @code +@item perror "@var{string} @var{number}" +@cindex test case, ERROR in +@kindex ERROR +Declares a severe error in the testing framework itself. +@code{perror} writes in the log files a message beginning with +@samp{ERROR}, appending the argument @var{string}. If the optional +@var{number} is supplied, then this is used to set the internal count of +errors to that value. + +As a side effect, @code{perror} also changes the effect of the next +@code{pass} or @code{fail} command: the test outcome becomes +@samp{UNRESOLVED}, since an automatic @samp{PASS} or @samp{FAIL} cannot +be trusted after a severe error in the test framework. If the optional +numeric value is @samp{0}, then there are no further side effects to +calling this function, and the following test outcome doesn't become +@samp{UNRESOLVED}. This can be used for errors with no known side +effects. + +@item warning "@var{string} @var{number}" +@cindex test case, WARNING in +@kindex WARNING +Declares detection of a minor error in the test case itself. +@code{warning} writes in the log files a message beginning with +@samp{WARNING}, appending the argument @var{string}. Use @code{warning} +rather than @code{error} for cases (such as communication failure +to be followed by a retry) where the test case can recover from the +error. If the optional @var{number} is supplied, then this is used to +set the internal count of warnings to that value. + +As a side effect, @code{warning_threshold} or more calls to +@code{warning} in a single test case also changes the effect of the next +@code{pass} or @code{fail} command: the test outcome becomes +@samp{UNRESOLVED} since an automatic @samp{PASS} or @samp{FAIL} may not +be trustworthy after many warnings. If the optional numeric value is +@samp{0}, then there are no further side effects to calling this +function, and the following test outcome doesn't become +@samp{UNRESOLVED}. This can be used for errors with no known side +effects. + +@item note "@var{string}" +@cindex test case, informational messages +@kindex NOTE +Appends an informational message to the log file. +@code{note} writes in the log files a message beginning with +@samp{NOTE}, appending the argument @var{string}. Use @code{note} +sparingly. @code{verbose} should be used for most such messages, +but in cases where a message is needed in the log file regardless of +the verbosity level use @code{note}. + +@item pass "@var{string}" +@cindex test case, declaring success +Declares a test to have passed. @code{pass} writes in the +log files a message beginning with @samp{PASS} (or @code{XPASS}, if +failure was expected), appending the argument @var{string}. + +@item fail "@var{string}" +@cindex test case, declaring failure +Declares a test to have failed. @code{fail} writes in the +log files a message beginning with @samp{FAIL} (or @code{XFAIL}, if +failure was expected), appending the argument @var{string}. + +@item unresolved "@var{string}" +@cindex test case, declaring ambiguity +Declares a test to have an unresolved outcome. @code{unresolved} writes +in the log file a message beginning with @samp{UNRESOLVED}, appending +the argument @var{string}. This usually means the test did not execute +as expected, and a human being must go over results to determine if it +passed or failed (and to improve the test case). + +@item untested "@var{string}" +@cindex test case, declaring no test +Declares a test was not run. @code{untested} writes in the log file a +message beginning with @samp{UNTESTED}, appending the argument +@var{string}. For example, you might use this in a dummy test whose +only role is to record that a test does not yet exist for some feature. + +@item unsupported "@var{string}" +@cindex test case, declaring no support +Declares that a test case depends on some facility that does not exist +in the testing environment. @code{unsupported} writes in the log file a +message beginning with @samp{UNSUPPORTED}, appending the argument +@var{string}. + +@item get_warning_threshold +@cindex test case, WARNING threshold +Returns the current value of @code{warning_threshold}. +The default value is 3. + +@item set_warning_threshold @var{threshold} +@cindex test case, WARNING threshold +Sets the value of @code{warning_threshold}. +A value of @code{0} disables it: calls to @code{warning} will not turn +a @samp{PASS} or @samp{FAIL} into an @samp{UNRESOLVED}. + +@item transform "@var{toolname}" +@cindex transform tool name +@cindex installed tool name +@cindex tool name, as installed +@cindex name transformations +Generates a string for the name of a tool as it was configured and +installed, given its native name (as the argument @var{toolname}). +This makes the assumption that all tools are installed using the same +naming conventions: it extrapolates from the invocation name for +@file{runtest}. For example, if you call @code{runtest} as +@file{m68k-vxworks-runtest}, the result of @w{@samp{ transform "gcc" }} +is @samp{m68k-vxworks-gcc}. + +@item ishost "@var{host}" +@cindex host configuration test +Tests for a particular @emph{host} environment. If the currently +configured host matches the argument string, the result is @code{1}; +otherwise the result is @code{0}. @var{host} must be a full three-part +@code{configure} host name; in particular, you may not use the shorter +nicknames supported by @code{configure} (but you can use wildcard +characters, using shell syntax, to specify sets of names). + +@item istarget "@var{target}" +@cindex target configuration test +Tests for a particular @emph{target} environment. If the currently +configured target matches the argument string, the result is @code{1}; +otherwise the result is @code{0}. @var{target} must be a full +three-part @code{configure} target name; in particular, you may not use +the shorter nicknames supported by @code{configure} (but you can use +wildcard characters, using shell syntax, to specify sets of names). If it is +passed a @code{NULL} string, then it returns the name of the build +canonical configuration. + +@item isbuild "@var{host}" +@cindex build host configuration test +Tests for a particular @emph{build host} environment. If the currently +configured host matches the argument string, the result is @code{1}; +otherwise the result is @code{0}. @var{host} must be a full three-part +@code{configure} host name; in particular, you may not use the shorter +nicknames supported by @code{configure} (but you can use wildcard +characters, using shell syntax, to specify sets of names). If it is +passed a @code{NULL} string, then it returns the name of the build +canonical configuration. + +item is3way "@var{host}" +@cindex canadian cross configuration test +Tests for a canadian cross. This is when the tests will be run on a +remotly hosted cross compiler. If it is a canadian cross, then the +result is @code{1}; otherwise the result is @code{0}. + +@item isnative +@cindex native configuration test +Tests whether the current configuration has the same host and target. +When it runs in a @emph{native} configuration this procedure returns a +@code{1}; otherwise it returns a @code{0}. + +@item load_lib "@var{library-file}" +@cindex load library file +Loads the file @var{library-file} by searching a fixed path built into +@code{runtest}. If DejaGnu has been installed, it looks in a path +starting with the installed library directory. If you are running +DejaGnu directly from a source directory, without first running +@samp{make install}, this path defaults to the current directory. In +either case, it then looks in the current directory for a directory +called @code{lib}. If there are duplicate definitions, the last one +loaded takes precedence over the earlier ones. + +@item setup_xfail "@var{config} @r{[}@var{bugid}@r{]}" +@c two spaces above to make it absolutely clear there's whitespace---a +@c crude sort of italic correction! +@cindex test case, expecting failure +@cindex failure, expected +@cindex expected failure +Declares that the test is expected to fail on a particular set of +configurations. The @var{config} argument must be a list of full +three-part @code{configure} target name; in particular, you may not use +the shorter nicknames supported by @code{configure} (but you can use the +common shell wildcard characters to specify sets of names). The +@var{bugid} argument is optional, and used only in the logging file +output; use it as a link to a bug-tracking system such as @sc{gnats} +(@pxref{Overview,, Overview, gnats.info, Tracking Bugs With GNATS}). + +@cindex @code{XFAIL}, producing +@cindex @code{XPASS}, producing +Once you use @code{setup_xfail}, the @code{fail} and @code{pass} +procedures produce the messages @samp{XFAIL} and @samp{XPASS} +respectively, allowing you to distinguish expected failures (and +unexpected success!) from other test outcomes. + +@emph{Warning:} you must clear the expected failure after using +@code{setup_xfail} in a test case. Any call to @code{pass} or +@code{fail} clears the expected failure implicitly; if the test has some +other outcome, e.g. an error, you can call @code{clear_xfail} to clear +the expected failure explicitly. Otherwise, the expected-failure +declaration applies to whatever test runs next, leading to surprising +results. + +@item check_conditional_xfail @var{message} @var{targets} @var{includes} @var{excludes} +@cindex test case, expecting a conditional failure +@cindex failure, conditional expected +@cindex conditional expected failure + +This procedure adds a condition xfail, based on compiler options used to +create a test case executable. If an include options is found in the +compiler flags, and it's the right architecture, it'll trigger an +XFAIL. Otherwise it'll produce an ordinary FAIL. You can also specify +flags to exclude. This makes a result be a FAIL, even if the included +options are found. To set the conditional, set the variable +@var{compiler_conditional_xfail_data} to the fields "[message string] [targets +list] [includes list] [excludes list]" (descriptions below). This is the +checked at pass/fail decision time, so there is no need to call the +procedure yourself, unless you wish to know if it gets triggered. After +a pass/fail, the variable is reset, so it doesn't effect other tests. + +The parameters are: + +@table @code +@item message +is the message to print with the normal test result + +@item targets +is a string with the targets to activate this conditional on. + +@item includes +is a list of sets of options to search for in the compiler options to +activate this conditional. If any set of the options matches, then this +conditional is true. + +@item excludes +is a list of sets of options to search for in the compiler options to +activate this conditional. If any set of the options matches, +(regardless of whether any of the include sets match) then this +conditional is de-activated. +@end table + +returns: + +@table @code +@item 1 +if the conditional is true +@item 0 +if the conditional is false +@end table + +An example of setting the variable would be: + +@cartouche +@smallexample +set compiler_conditional_xfail_data @{@ \ + "I sure wish I knew why this was hosed" \ + "sparc*-sun*-* *-pc-*-*" \ + @{@"-Wall -v" "-O3"@}@ \ + @{@"-O1" "-Map" @}@ \ + @}@ +@end smallexample +@end cartouche + + What this does is it matches only for these two targets if "-Wall -v" or +"-O3" is set, but neither "-O1" or "-Map" is set. + + For a set to match, the options specified are searched for independantly of +each other, so a "-Wall -v" matches either "-Wall -v" or "-v -Wall". A space +seperates the options in the string. Glob-style regular expressions are also +permitted. + +@item clear_xfail @var{config} +@cindex cancelling expected failure +@cindex expected failure, cancelling +Cancel an expected failure (previously declared with @code{setup_xfail}) +for a particular set of configurations. The @var{config} argument is a +list of configuration target names. It is only necessary to call +@code{clear_xfail} if a test case ends without calling either +@code{pass} or @code{fail}, after calling @code{setup_xfail}. + +@item verbose @r{[}-log@r{]} @r{[}-n@r{]} @r{[}--@r{]} "@var{string}" @var{number} +@cindex @code{verbose} builtin function +Test cases can use this function to issue helpful messages depending on +the number of @samp{--verbose} options on the @code{runtest} command +line. It prints @var{string} if the value of the variable +@code{verbose} is higher than or equal to the optional @var{number}. The +default value for @var{number} is 1. Use the optional @samp{-log} argument +to cause @var{string} to always be added to the log file, even if it won't +be printed. Use the optional @samp{-n} argument to print @var{string} +without a trailing newline. Use the optional @samp{--} argument if +@var{string} begins with "-". + +@end ftable + +@noindent +@node remote.exp, utils.exp, framework.exp, DejaGnu Builtins +@subsection Remote Communication Procedures + +@kindex remote.exp +@kindex lib/remote.exp +@cindex remote connection procedures +@cindex communications procedures +@file{lib/remote.exp} defines these functions, for establishing and +managing communications: + +@emph{Procedures to establish a connection:} Each of these procedures +tries to establish the connection up to three times before returning. +Warnings (if retries will continue) or errors (if the attempt is +abandoned) report on communication failures. The result for any of +these procedures is either @code{-1}, when the connection cannot be +established, or the spawn ID returned by the @code{expect} command +@code{spawn}. + +It use the value of the @code{connect} field in the @code{target_info} +array (was @code{connectmode} as the type of connection to make. Current +supported connection types are tip, kermit, telnet, rsh, rlogin, and +netdata. If the @code{--reboot} option was used on the runtest command +line, then the target is rebooted before the connection is made. + +@ftable @code + +@item remote_open @var{type} +@cindex Opening a remote connection +@emph{Remote Connection Procedure.} This is passed @emph{host} or +@emph{target}. Host or target refers to whether it is a connection to a +remote target, or a remote host. This opens the connection to the +desired target or host using the default values in the configuration +system. It returns that @code{spawn_id} of the process that manages the +connection. This value can be used in @code{expect} or @code{exp_send} +statements, or passed to other procedures that need the connection +process's id. This also sets the @code{fileid} field in the +@code{target_info} array. + + +@item remote_close @var{shellid} +@cindex Closing a remote connection +@emph{shellid} is value returned by a call to @code{remote_open}. This +closes the connection to the target so resources can be used by +others. This parameter can be left off if the @code{fileid} field in the +@code{target_info} array is set. + +@item telnet @var{hostname} @var{port} +@itemx rlogin @var{hostname} +@itemx rsh @var{hostname} +@cindex IP network procedures +@cindex network (IP) procedures +@emph{IP network procedures.} @var{hostname} refers to the IP address or +name (for example, an entry in @file{/etc/hosts}) for this target. The +procedure names reflect the Unix utility used to establish a +connection. The optional @var{port} is used to specify the IP port +number. The value of the @code{netport} field in the @code{target_info} +array is used. (was @code{$netport}) This value has two parts, the +hostname and the port number, seperated by a @emph{:}. If @code{host} or +@code{target} is used in the @code{hostname} field, than the config +array is used for all information. + +@item tip @var{port} +@cindex serial line connection, @code{tip} +@emph{Serial line procedure.} Connect using the Unix utility @code{tip}. +@var{port} must be a name from the @code{tip} configuration file +@file{/etc/remote}. Often, this is called @samp{hardwire}, or something +like @samp{ttya}. This file holds all the configuration data for +the serial port. The value of the @code{serial} field in the +@code{target_info} array is used. (was @code{$serialport}) If +@code{host} or @code{target} is used in the @code{port} field, than +the config array is used for all information. + +@item kermit @var{port} @var{bps} +@cindex serial line connection, @code{kermit} +@emph{Serial line procedure.} Connect using the program @code{kermit}. +@var{port} is the device name, e.g. @file{/dev/ttyb}. @var{bps} is +the line speed to use (in bits per second) for the connection. The value +of the @code{serial} field in the @code{target_info} array is used. (was +@code{$serialport}) If @code{host} or @code{target} is used in the +@code{port} field, than the config array is used for all information. + +@end ftable + +@noindent +@emph{Procedures to manage a connection:} + +@ftable @code +@item tip_download @var{spawnid} @var{file} +@cindex download, @code{tip} +@cindex serial download, @code{tip} +Download @file{@var{file}} to the process @var{spawnid} (the value +returned when the connection was established), using the @code{~put} +command under @code{tip}. Most often used for single board computers +that require downloading programs in @sc{ascii} S-records. Returns +@code{1} if an error occurs, @code{0} otherwise. + +@item exit_remote_shell @var{spawnid} +@cindex terminating remote connection +@cindex remote connection, ending +Exits a remote process started by any of the connection procedures. +@var{spawnid} is the result of the connection procedure that started the +remote process. + +@item download @var{file} @r{[} @var{spawnid} @r{]} +@cindex download a file +After you establish a connection to a target, you can download programs +using this command. @code{download} reads in @var{file} (object code in +S-record format) and writes it to the device controlling this +@var{spawnid}. (From the point of view of the target, the S-record file +comes in via standard input.) + +If you have more than one target active, you can use the optional argument +@var{spawnid} to specify an alternative target (the default is the most +recently established @var{spawnid}.) +@end ftable + +@noindent +@node utils.exp, target.exp, remote.exp, DejaGnu Builtins +@subsection Utility Procedures + +@kindex utils.exp +@kindex lib/utils.exp +@file{lib/utils.exp} defines these utility procedures: + +@ftable @code +@item getdirs @var{dir} +@itemx getdirs @var{dir} @var{pattern} +@cindex directories matching a pattern +@cindex pattern match, directory +Returns a list of all the directories in the single directory @var{dir} +that match @var{pattern}. If you do not specify @var{pattern}, +@code{getdirs} assumes @samp{*}. You may use the common shell wildcard +characters in @var{pattern}. If no directories match the pattern, then a +@code{NULL} string is returned. + +@item find @var{dir} @var{pattern} +@cindex files matching a pattern +@cindex pattern match, filenames +Search for files whose names match @var{pattern} (using shell wildcard +characters for filename expansion). Search subdirectories recursively, +starting at @var{dir}. The result is the list of files whose names +match; if no files match, the result is empty. Filenames in the result +include all intervening subdirectory names. If no files match the +pattern, then a @code{NULL} string is returned. + +@item which @var{binary} +@cindex path lookup +Searches the execution path for an executable file @var{binary}, like +the the BSD @code{which} utility. This procedure uses the shell +environment variable @samp{PATH}. It returns @code{0} if the binary is +not in the path, or if there is no @samp{PATH} environment variable. If +@var{binary} is in the path, it returns the full path to @var{binary}. + +@item grep @var{filename} @var{regexp} +@item grep @var{filename} @var{regexp} line +@cindex regular expression, file contents +@cindex searching file contents +Search the file called @var{filename} (a fully specified path) for lines +that contain a match for regular expression @var{regexp}. The result is +a list of all the lines that match. If no lines match, the result is an +empty string. Specify @var{regexp} using the standard regular +expression style used by the Unix utility program @code{grep}. + +Use the optional third argument @samp{line} to start lines in the result +with the line number in @var{filename}. (This argument is simply an +option flag; type it just as shown---@samp{line}.) + +@item diff @var{filename} @var{filename} +@cindex finding file differences +@cindex comparing files +Compares the two files and returns a 1 if they match, or a 0 if they +don't. If @code{verbose} is set, then it'll print the differences to the +screen. + +@item slay @var{name} +@cindex slaying processes +This look in the process table for @var{name} and send it a unix +@code{SIGINT}, killing the process. + +@item absolute @var{path} +@cindex converting relative paths to absolute +This procedure takes the relative @var{path}, and converts it to an +absolute path. + +@item psource @var{filename} +@cindex sourcing Tcl files +This sources the file @var{filename}, and traps all errors. It also +ignores all extraneous output. If there was an error it returns a 1, +otherwise it returns a 0. + +@item prune @var{list} @var{pattern} +@cindex list, pruning +Remove elements of the Tcl list @var{list}. Elements are fields +delimited by spaces. The result is a copy of @var{list}, without any +elements that match @var{pattern}. You can use the common shell +wildcard characters to specify @var{pattern}. + +@item setenv @var{var} @var{val} +@cindex setting environment variables +Sets the variable @var{var} to the value @var{val}. + +@item unsetenv @var{var} +@cindex unsetting environment variables +Unsets the environment variable @var{var} + +@item getenv @var{var} +@cindex getting environment variables +returns the value of @var{var} in the environment if it exists, +otherwise it returns @code{NULL}. + +@item runtest_file_p @var{runtests} @var{testcase} +@cindex selecting a range of tests +@cindex tests, running specifically +Search @var{runtests} for @var{testcase} and return 1 if found, 0 if not. +@var{runtests} is a list of two elements. The first is the pathname of +the testsuite expect script running. The second is a copy of what was +on the right side of the @code{=} if @samp{foo.exp="@dots{}"} was specified, +or an empty string if no such argument is present. +This is used by tools like compilers where each testcase is a file. + +@item prune_system_crud @var{system} @var{text} +@cindex pruning system output, examining program output +For system @var{system}, delete text the host or target operating system might +issue that will interfere with pattern matching of program output in +@var{text}. An example is the message that is printed if a shared library +is out of date. + +@end ftable + +@noindent +@node target.exp, debugger.exp, utils.exp, DejaGnu Builtins +@subsection Cross target procedure + +@kindex target.exp +@kindex lib/target.exp +@file{lib/target.exp} defines these utility procedures: + +@ftable @code + +@item push_target @emph{name} +@cindex set current target +This makes the target named @emph{name} be the current target +connection. The value of @emph{name} is an index into the +@code{target_info} array and is set in the global config file. + +@item pop_target +@cindex unset current target +This unsets the current target connection. + +@item list_targets +@cindex lists supported targets +This lists all the supported targets for this architecture. + +@item push_host @emph{name} +@cindex set current host +This makes the host named @emph{name} be the current remote host +connection. The value of @emph{name} is an index into the +@code{target_info} array and is set in the global config file. + +@item pop_host +@cindex unset current host +This unsets the current host connection. + +@c @item compile @emph{file} +@cindex compile a file +This invokes the compiler as set by @code{CC} to compile the file +@emph{file}. The default options for many cross compilation targets are +@emph{guessed} by DejaGnu, and these options can be added to by passing +in more parameters as arguments to @code{compile}. Optionally, this will +also use the value of the @code{cflags} field in the target config +array. If the host is not the same as the build machines, then then +compiler is run on the remote host using @code{execute_anywhere}. + +@c @item archive @emph{file} +@cindex archive object files +This produces an archive file. Any parameters passed to @code{archive} +are used in addition to the default flags. Optionally, this will +also use the value of the @code{arflags} field in the target config +array. If the host is not the same as the build machines, then then +archiver is run on the remote host using @code{execute_anywhere}. + +@c @item ranlib @emph{file} +@cindex ranlib a file +This generates an index for the archive file for systems that aren't +POSIX yet. Any parameters passed to @code{ranlib} are used in for the +flags. + +@item execute_anywhere @emph{cmdline} +@cindex executing commands remotely +This executes the @emph{cmdline} on the proper host. This should be used +as a replacement for the Tcl command @code{exec} as this version +utilizes the target config info to execute this command on the build +machine or a remote host. All config information for the remote host +must be setup to have this command work. If this is a canadian cross, +(where we test a cross compiler that runs on a different host then where +DejaGnu is running) then a connection is made to the remote host and +the command is executed there. It returns either @emph{REMOTERROR} (for +an error) or the output produced when the command was executed. This is +used for running the tool to be tested, not a test case. + +@end ftable + +@node debugger.exp, , target.exp, DejaGnu Builtins +@subsection Debugging Procedures + +@kindex debugger.exp +@kindex lib/debugger.exp +@file{lib/debugger.exp} defines these utility procedures: + +@ftable @code + +@item dumpvars @emph{expr} +@cindex Print global variable values +This takes a csh style regular expression (glob rules) and prints the +values of the global variable names that match. It is abbreviated as +@code{dv} + +@item dumplocals @emph{expr} +@cindex Print local variable value +This takes a csh style regular expression (glob rules) and prints the +values of the local variable names that match. It is abbreviated as +@code{dl}. + +@item dumprocs @emph{expr} +@cindex Print procedure bodies +This takes a csh style regular expression (glob rules) and prints the +body of all procs that match. It is abbreviated as @code{dp} + +@item dumpwatch @emph{expr} +@cindex Print watchpoints +This takes a csh style regular expression (glob rules) and prints all +the watchpoints. It is abbreviated as @code{dw}. + +@c FIXME: finish these when the code is fixed. +@c @item watcharray @emph{element} @emph{type} +@c @cindex Set a watchpoint on an array +@c This sets an watchpoint of the @emph{element-type} on the +@c @item watchvar v null type +@c @cindex Set a watchpoint on a variable + +@item watchunset @emph{var} +@cindex Watch when a variable is unset +This breaks program execution when the variable @emph{var} is unset. It +is abbreviated as @code{wu}. + +@item watchwrite @emph{var} +@cindex Watch when a variable is written +This breaks program execution when the variable @emph{var} is +written. It is abbreviated as @code{ww}. + +@item watchread @emph{var} +@cindex Watch when a variable is read +This breaks program execution when the variable @emph{var} is read. It +is abbreviated as @code{wr}. + +@item watchdel @emph{watch} +@cindex Delete a watchpoint. +This deletes a the watchpoint for @emph{watch}. It is abbreviated as +@code{wd}. + +@item print @emph{var} +@cindex Printing variable values +This prints the value of the variable @emph{var}. It is abbreviated as +@code{p}. + +@item quit +@cindex Quiting DejaGnu +This makes runtest exit. It is abbreviated as @code{q}. + +@item bt +@cindex Print a backtrace +This prints a backtrace of the executed Tcl commands. + +@end ftable + +@node Target Dependent +@section Target dependent procedures +@cindex target dependent procedures + +@c FIXME? These may be renamed to just "start", "load", "exit", and +@c "version" eventually. + +Each combination of target and tool requires some target-dependent +procedures. The names of these procedures have a common form: the tool +name, followed by an underbar @samp{_}, and finally a suffix describing +the procedure's purpose. For example, a procedure to extract the +version from @sc{gdb} is called @samp{gdb_version}. @xref{Init Module,, +Initialization Module}, for a discussion of how DejaGnu arranges to find +the right procedures for each target. + +@code{runtest} itself calls only two of these procedures, +@code{@var{tool}_exit} and @code{@var{tool}_version}; these procedures use +no arguments. + +The other two procedures, @code{@var{tool}_start} and +@code{@var{tool}_load}, are only called by the test suites themselves +(or by testsuite-specific initialization code); they may take arguments +or not, depending on the conventions used within each test suite. + +@ftable @code +@item @var{tool}_start +@cindex start procedure, tested tools +Starts a particular tool. For an interactive tool, +@code{@var{tool}_start} starts and initializes the tool, leaving the +tool up and running for the test cases; an example is @code{gdb_start}, +the start function for @sc{gdb}. For a batch oriented tool, +@code{@var{tool}_start} is optional; the recommended convention is to +let @code{@var{tool}_start} run the tool, leaving the output in a +variable called @code{comp_output}. Test scripts can then analyze +@samp{$comp_output} to determine the test results. An example of this +second kind of start function is @code{gcc_start}, the start function +for @sc{gcc}. + +@code{runtest} itself @emph{does not call} @code{@var{tool}_start}. The +initialization module @file{@var{tool}_init.exp} must call +@code{@var{tool}_start} for interactive tools; for batch-oriented tools, +each individual test script calls @code{@var{tool}_start} (or makes +other arrangements to run the tool). + +@item @var{tool}_load +@cindex load procedure, tested tools +Loads something into a tool. For an interactive tool, this conditions +the tool for a particular test case; for example, @code{gdb_load} loads +a new executable file into the debugger. For batch oriented tools, +@code{@var{tool}_load} may do nothing---though, for example, the +@sc{gcc} support uses @code{gcc_load} to load and run a binary on the +target environment. Conventionally, @code{@var{tool}_load} leaves the +output of any program it runs in a variable called @samp{exec_output}. +Writing @code{@var{tool}_load} can be the most complex part of extending +DejaGnu to a new tool or a new target, if it requires much communication +coding or file downloading. + +Test scripts call @code{@var{tool}_load}. + +@item @var{tool}_exit +@cindex exit procedure, tested tools +Cleans up (if necessary) before @code{runtest} exits. For interactive +tools, this usually ends the interactive session. You can also use +@code{@var{tool}_exit} to remove any temporary files left over from the +tests. + +@code{runtest} calls @code{@var{tool}_exit}. + +@item @var{tool}_version +@cindex version procedure, tested tools +Prints the version label and number for @var{tool}. This is called by +the DejaGnu procedure that prints the final summary report. The output +should consist of the full path name used for the tested tool, and its +version number. + +@code{runtest} calls @code{@var{tool}_version}. +@end ftable + +The usual convention for return codes from any of these procedures +(although it is not required by @code{runtest}) is to return @code{0} if +the procedure succeeded, @code{1} if it failed, and @code{-1} if there +was a communication error. + +@node Cross Targets +@section Remote targets supported + +@cindex targets +@cindex remote testing +The DejaGnu distribution includes support for the following remote +targets. You can set the target name and the connect mode in the +@file{site.exp} file (using the Tcl variables @samp{targetname} and +@samp{connectmode}, respectively), or on the @code{runtest} command line +(using @samp{--name} and @samp{--connect}). + +@table @strong +@item @sc{amd} 29000, with UDI protocol +Configure DejaGnu for target @samp{a29k-amd-udi}. (Cygnus +@code{configure} also recognizes the abbreviation @samp{udi29k}.) Then, +to run tests, use the @code{runtest} target name to specify whether you +want to use a simulator, or a particular hardware board. The particular +string to use with @samp{--name} will depend on your UDI setup file, +@file{udi_soc} (if @file{udi_soc} is not in your working directory, the +environment variable @samp{UDICONF} should contain a path to this file). +For example, if your UDI setup file includes these lines: +@end table +@c table "ends" *only* to allow wider example below + +@cartouche +@smallexample +iss AF_UNIX * isstip -r /home/gnu/29k/src/osboot/sim/osboot +mon AF_UNIX * montip -t serial -baud 9600 -com /dev/ttyb +@end smallexample +@end cartouche + +@table @strong +@item @w{ } +@c fake out table/item into continuing w/same margin as before +You can use @samp{--name iss} to run tests on the simulator, and +@samp{--name mon} to run tests on the 29K hardware. See the +manufacturer's manuals for more information on UDI and @file{udi_soc}. +@c FIXME! Is there a better ref than "the manufacturer's manuals"? + +@kindex mondfe +The default connect protocol is @samp{mondfe} with either back end. +@code{mondfe} is the only shell DejaGnu supports for UDI targets. +@code{mondfe} is an @sc{amd} specific monitor program freely available +from @sc{amd}. + +@emph{Warning:} This target requires @sc{gdb} version 4.7.2 (or +greater). Earlier versions of @sc{gdb} do not fully support the +@code{load} command on this target, so DejaGnu has no way to load +executable files from the debugger. + +@item Motorola 680x0 boards, a.out or @sc{coff} object format +Configure DejaGnu for any remote target matching @samp{m68k-*}. + +@emph{Warning:} Most @samp{m68k-*} configurations run all tests only for +native testing (when the target is the same as the host). When you +specify most of these targets for a cross configuration, you will only be +able to use tests that run completely within the host (for example, +tests of the binary utilities such as the archiver; or compiler tests +that only generate code rather than running it). + +To run a.out or @sc{coff} binaries on a remote M68K, you must configure +DejaGnu for a particular target board. @samp{m68k-abug} is an example. +(In general for an embedded environment, because it does not have absolute +addresses, a.out is not a good choice for output format in any case; most +often S-records or Hex-32 are used instead.) + +@item Motorola 68K MVME 135 board running ABug boot monitor +Configure for @samp{m68k-abug-aout} or @samp{m68k-abug-coff} (as a +target). This boot monitor can only download S-records; therefore, the +DejaGnu tests for this environment require a linker command script to +convert either output format to S-records, setting the default addresses +for @code{.text}, @code{.bss}, and @code{.data}. + +With this configuration, the default for @samp{--connect} is @samp{tip}. +@samp{tip} is the only communications protocol supported for connecting +to @samp{m68k-abug-*} targets. @samp{tip} uses an @sc{ascii} downloader +(the @code{~put} command) to load S-records into the target board. The +@samp{--name} string must be a machine name that @code{tip} +understands (for example, on some @code{tip} implementations it must be +an entry from the initialization file for @code{tip}; this file is +sometimes called @file{/etc/remote}). + +See your system documentation for information on how to create new +entries in @file{/etc/remote}. (Some @sc{unix} systems are distributed +with at least one default entry with a name resembling @samp{hardwire}; +if your system has one, you can edit it, or make a modified copy with a +new name.) When you have a working @file{/etc/remote} entry +@var{abugtarget}, you should be able to type @samp{tip +@var{abugtarget}}, and get the prompt @samp{135ABUG>} from the board. +Use the same @var{abugtarget} string with @samp{runtest --name}. + +@item Motorola IDP board running the rom68k boot monitor +@c FIXME 1: this doesn't really say anything! OK, so functionality is +@c the same. Is object code the same (srecords)? Do we configure with +@c the same triplets? What is the default for --connect? Is +@c any comms method other than tip supported? What prompt to expect +@c when tip connected? +@c FIXME 2: should @code{BUG} below be @code{ABUG}? +This is the same in functionality as the MVME board running the +@code{BUG} boot monitor. Only the monitor commands and the addresses are +different. + +@item VxWorks (Motorola 68K or Intel 960) +Configure DejaGnu for either @samp{m68k-wrs-vxworks} (abbreviated +@samp{vxworks68}) or @samp{i960-wrs-vxworks} (abbreviated +@samp{vxworks960}). Since both targets support IP addressing, specify +the network address (for example, a host name from @file{/etc/hosts}) +with @samp{--name}. + +The default connect protocol is @samp{rlogin}, but you can use any of +@samp{--connect rlogin}, @samp{--connect telnet}, or @samp{--connect +rsh}. + +Test scripts need no special code to load programs into these targets; +since VxWorks supports NFS, all you must do is ensure test programs are +on an exported filesystem. + +@cindex VxWorks, link with @samp{-r} +When you compile for VxWorks, use the linker @samp{-r} option to make +the linker output relocatable---at least if you want to use library +routines. Many standard C routines are included in VxWorks; often no +additional libraries are needed. See your VxWorks system documentation +for additional details. +@end table + +@node Input Files +@section The files DejaGnu reads +@cindex input files + +The @code{runtest} program used to invoke DejaGnu is a short shell +script generated by @code{make} during the configuration process. Its +main task is to read the main test framework driver, @file{runtest.exp}. + +@file{runtest.exp}, in turn, reads @code{expect} code from certain other +files, in this order: + +@enumerate +@item +Each of the @file{site.exp} local definition files available. +@xref{Customizing,,Setting @code{runtest} defaults}, for details. + +@item +@file{lib/utils.exp}, a collection of utility procedures. @xref{DejaGnu +Builtins,,DejaGnu Builtins}, for descriptions of these procedures. + +@item +@file{lib/framework.exp}, a file of subroutines meant for @code{runtest} +itself rather than for general-purpose use in both @code{runtest} and +test suites. + +@item +@file{debugger.exp}, Don Libes' Tcl Debugger. (See @cite{A Debugger for +Tcl Applications} by Don Libes. This paper is distributed with +@code{expect} in PostScript form as the file +@file{expect/tcl-debug.ps}.) + +@item +@file{lib/remote.exp}, a collection of subroutines meant for connecting +to remote machines. + +@item +@file{lib/target.exp}, a collection of subroutines used for the +configuration systems in DejaGnu. These procedures typically manipulate +or utilize the configuration system. + +@item +@c FIXME! A comment in runtest.exp claims a system default is used if +@c no tool-specific init file is not available; I couldn't see where +@c the program flow actually does this, though---pesch 30jul1993. +An initialization file @code{@var{tool}_init.exp}. @xref{Init +Module,,Initialization module}, for more discussion of init files. +@end enumerate + +@c This hard page break is mainly intended for smallbook formatting; +@c some examples in this section come out better if this starts at a +@c page boundary. +@page +@node Output Files +@section The files DejaGnu writes +@cindex output files + +@code{runtest} always writes two kinds of output files: summary logs and +detailed logs. The contents of both of these are determined by your +tests. + +For troubleshooting, a third kind of output file is useful: use +@samp{--debug} to request an output file showing details of what +@code{expect} is doing internally. + +@menu +* Summary:: Files that summarize tests +* Detail:: Files that contain complete test results +* Debug:: Logging expect internal actions +@end menu + +@node Summary +@subsection Summary log +@cindex summary log + +@code{runtest} always produces a summary output file +@file{@var{tool}.sum}. This summary shows the names of all test files +run; for each test file, one line of output from each @code{pass} +command (showing status @samp{PASS} or @samp{XPASS}) or @code{fail} +command (status @samp{FAIL} or @samp{XFAIL}); trailing summary +statistics that count passing and failing tests (expected and +unexpected); and the full pathname and version number of the tool +tested. (All possible outcomes, and all errors, are always reflected in +the summary output file, regardless of whether or not you specify +@samp{--all}.) + +If any of your tests use the procedures @code{unresolved}, +@code{unsupported}, or @code{untested}, the summary output also +tabulates the corresponding outcomes. + +For example, after @samp{runtest --tool binutils}, look for a summary +log in @file{binutils.sum}. Normally, @code{runtest} writes this file +in your current working directory; use the @samp{--outdir} option to +select a different directory. + +@need 3500 +@noindent +Here is a short sample summary log: + +@cartouche +@smallexample +Test Run By rob on Mon May 25 21:40:57 PDT 1992 + === gdb tests === +Running ./gdb.t00/echo.exp ... +PASS: Echo test +Running ./gdb.all/help.exp ... +PASS: help add-symbol-file +PASS: help aliases +PASS: help breakpoint "bre" abbreviation +FAIL: help run "r" abbreviation +Running ./gdb.t10/crossload.exp ... +PASS: m68k-elf (elf-big) explicit format; loaded +XFAIL: mips-ecoff (ecoff-bigmips) "ptype v_signed_char" signed +C types + === gdb Summary === +# of expected passes 5 +# of expected failures 1 +# of unexpected failures 1 +/usr/latest/bin/gdb version 4.6.5 -q +@end smallexample +@end cartouche + +@node Detail +@subsection Detailed log +@cindex detailed log + +@code{runtest} also saves a detailed log file @file{@var{tool}.log}, +showing any output generated by tests as well as the summary output. +For example, after @samp{runtest --tool binutils}, look for a detailed +log in @file{binutils.log}. Normally, @code{runtest} writes this file +in your current working directory; use the @samp{--outdir} option to +select a different directory. + +@need 4000 +@noindent +Here is a brief example showing a detailed log for @sc{g++} tests: + +@cartouche +@smallexample +Test Run By rob on Mon May 25 21:40:43 PDT 1992 + + === g++ tests === + +--- Running ./g++.other/t01-1.exp --- + PASS: operate delete + +--- Running ./g++.other/t01-2.exp --- + FAIL: i960 bug EOF +p0000646.C: In function `int warn_return_1 ()': +p0000646.C:109: warning: control reaches end of non-void function +p0000646.C: In function `int warn_return_arg (int)': +p0000646.C:117: warning: control reaches end of non-void function +p0000646.C: In function `int warn_return_sum (int, int)': +p0000646.C:125: warning: control reaches end of non-void function +p0000646.C: In function `struct foo warn_return_foo ()': +p0000646.C:132: warning: control reaches end of non-void function + +--- Running ./g++.other/t01-4.exp --- + FAIL: abort +900403_04.C:8: zero width for bit-field `foo' +--- Running ./g++.other/t01-3.exp --- + FAIL: segment violation +900519_12.C:9: parse error before `;' +900519_12.C:12: Segmentation violation +/usr/latest/bin/gcc: Internal compiler error: program cc1plus got +fatal signal + + === g++ Summary === + +# of expected passes 1 +# of expected failures 3 +/usr/ps/bin/g++ version cygnus-2.0.1 +@end smallexample +@end cartouche + +@node Debug +@subsection Logging @code{expect} internal actions +@cindex debug log + +With the @samp{--debug} option, you can request a log file showing the +output from @code{expect} itself, running in debugging mode. This file +(@file{dbg.log}, in the directory where you start @code{runtest}) shows +each pattern @code{expect} considers in analyzing test output. + +This file reflects each @code{send} command, showing the string sent as +input to the tool under test; and each @code{expect} command, showing +each pattern it compares with the tool output. + +The log messages for @code{expect} begin with a message of the form + +@smallexample +expect: does @{@var{tool output}@} (spawn_id @var{n}) match pattern +@{@var{expected pattern}@}? +@end smallexample + +@noindent +For every unsuccessful match, @code{expect} issues a @samp{no} after +this message; if other patterns are specified for the same +@code{expect} command, they are reflected also, but without the first +part of the message (@samp{expect@dots{}match pattern}). + +When @code{expect} finds a match, the log for the successful match ends +with @samp{yes}, followed by a record of the @code{expect} variables set +to describe a successful match. Here is an excerpt from the debugging +log for a @sc{gdb} test: + +@c FIXME! Why is the second spawn_id shown 0 rather than 6? +@cartouche +@smallexample +send: sent @{break gdbme.c:34\n@} to spawn id 6 +expect: does @{@} (spawn_id 6) match pattern @{Breakpoint.*at.* file + gdbme.c, line 34.*\(gdb\) $@}? no +@{.*\(gdb\) $@}? no +expect: does @{@} (spawn_id 0) match pattern @{<return>@}? no +@{\(y or n\) @}? no +@{buffer_full@}? no +@{virtual@}? no +@{memory@}? no +@{exhausted@}? no +@{Undefined@}? no +@{command@}? no +break gdbme.c:34 +Breakpoint 8 at 0x23d8: file gdbme.c, line 34. +(gdb) expect: does @{break gdbme.c:34\r\nBreakpoint 8 at 0x23d8: +file gdbme.c, line 34.\r\n(gdb) @} (spawn_id 6) match pattern +@{Breakpoint.*at.* file gdbme.c, line 34.*\(gdb\) $@}? yes +expect: set expect_out(0,start) @{18@} +expect: set expect_out(0,end) @{71@} +expect: set expect_out(0,string) @{Breakpoint 8 at 0x23d8: file +gdbme.c, line 34.\r\n(gdb) @} +expect: set expect_out(spawn_id) @{6@} +expect: set expect_out(buffer) @{break gdbme.c:34\r\nBreakpoint 8 +at 0x23d8: file gdbme.c, line 34.\r\n(gdb) @} + PASS: 70 0 breakpoint line number in file +@end smallexample +@end cartouche + +@noindent +This example exhibits three properties of @code{expect} and DejaGnu that +might be surprising at first glance: + +@itemize @bullet +@item +Empty output for the first attempted match. The first set of attempted +matches shown ran against the output @samp{@{@}}---that is, no output. +@code{expect} begins attempting to match the patterns supplied +immediately; often, the first pass is against incomplete output (or +completely before all output, as in this case). + +@item +Interspersed tool output. The beginning of the log entry for the second +attempted match may be hard to spot: this is because the prompt +@samp{(gdb) } appears on the same line, just before the @samp{expect:} +that marks the beginning of the log entry. + +@item +Fail-safe patterns. Many of the patterns tested are fail-safe patterns +provided by @sc{gdb} testing utilities, to reduce possible +indeterminacy. It is useful to anticipate potential variations +caused by extreme system conditions (@sc{gdb} might issue the message +@samp{virtual memory exhausted} in rare circumstances), or by changes in +the tested program (@samp{Undefined command} is the likeliest outcome if +the name of a tested command changes). + +The pattern @samp{@{<return>@}} is a particularly interesting fail-safe +to notice; it checks for an unexpected @key{RET} prompt. This may +happen, for example, if the tested tool can filter output through a +pager. + +These fail-safe patterns (like the debugging log itself) are primarily +useful while developing test scripts. Use the @code{error} procedure to +make the actions for fail-safe patterns produce messages starting with +@samp{ERROR} on the @code{runtest} standard output, and in the detailed +log file. +@end itemize + +@node Tests +@chapter How To Write a Test Cases +@cindex writing a test case +@cindex test case, writing + +@menu +* Writing:: Writing a test case +* Debugging:: Debugging a test case +* Adding:: Adding a test case to a test suite +* Hints:: Hints on writing a test case +* Variables:: Special variables used by test cases +@end menu + +@node Writing +@section Writing a test case + +The easiest way to prepare a new test case is to base it on an existing +one for a similar situation. There are two major categories of tests: +batch or interactive. Batch oriented tests are usually easier to write. + +The @sc{gcc} tests are a good example of batch oriented tests. All +@sc{gcc} tests consist primarily of a call to a single common procedure, +since all the tests either have no output, or only have a few warning +messages when successfully compiled. Any non-warning output is a test +failure. All the C code needed is kept in the test directory. The test +driver, written in @code{expect}, need only get a listing of all the C +files in the directory, and compile them all using a generic procedure. +This procedure and a few others supporting for these tests are kept in +the library module @file{lib/c-torture.exp} in the @sc{gcc} test suite. +Most tests of this kind use very few @code{expect} features, and are +coded almost purely in Tcl. + +@noindent +Writing the complete suite of C tests, then, consisted of these steps: + +@enumerate +@item +@cindex Granlund, Torbjorn +@cindex C torture test +Copying all the C code into the test directory. These tests were based on +the C-torture test created by Torbjorn Granlund (on behalf of the Free +Software Foundation) for @sc{gcc} development. + +@item +Writing (and debugging) the generic @code{expect} procedures for +compilation. + +@item +Writing the simple test driver: its main task is to search the directory +(using the Tcl procedure @code{glob} for filename expansion with +wildcards) and call a Tcl procedure with each filename. It also checks +for a few errors from the testing procedure. +@end enumerate + +Testing interactive programs is intrinsically more complex. Tests for most +interactive programs require some trial and error before they are complete. + +However, some interactive programs can be tested in a simple fashion +reminiscent of batch tests. For example, prior to the creation of +DejaGnu, the @sc{gdb} distribution already included a wide-ranging +testing procedure. This procedure was very robust, and had already +undergone much more debugging and error checking than many recent +DejaGnu test cases. Accordingly, the best approach was simply to +encapsulate the existing @sc{gdb} tests, for reporting purposes. +Thereafter, new @sc{gdb} tests built up a family of @code{expect} +procedures specialized for @sc{gdb} testing. + +@file{gdb.t10/crossload.exp} is a good example of an interactive test. +@c FIXME! Check what *kind* of example it is---work-intensive, or generic... + +@node Debugging +@section Debugging a test case +@cindex debugging a test case +@cindex test case, debugging + +@noindent +These are the kinds of debugging information available from DejaGnu: + +@enumerate +@item +Output controlled by test scripts themselves, explicitly allowed for by +the test author. This kind of debugging output appears in the detailed +output recorded in the @file{@var{tool}.log} file. To do the same for +new tests, use the @code{verbose} procedure (which in turn uses the +variable also called @code{verbose}) to control how much output to +generate. This will make it easier for other people running the test to +debug it if necessary. Whenever possible, if @samp{$verbose} is +@code{0}, there should be no output other than the output from +@code{pass}, @code{fail}, @code{error}, and @code{warning}. Then, to +whatever extent is appropriate for the particular test, allow +successively higher values of @samp{$verbose} to generate more +information. Be kind to other programmers who use your tests: provide +for a lot of debugging information. + +@item +Output from the internal debugging functions of Tcl and @code{expect}. +There is a command line options for each; both forms of debugging output +are recorded in the file @code{dbg.log} in the current directory. + +Use @samp{--debug} for information from the @code{expect} level; it +generates displays of the @code{expect} attempts to match the tool +output with the patterns specified (@pxref{Debug,,Debug Log}). This +output can be very helpful while developing test scripts, since it shows +precisely the characters received. Iterating between the latest attempt +at a new test script and the corresponding @file{dbg.log} can allow you +to create the final patterns by ``cut and paste''. This is sometimes +the best way to write a test case. + +Use @samp{--strace} to see more detail at the Tcl level; this shows how Tcl +procedure definitions expand, as they execute. The associated number +controls the depth of definitions expanded; see the discussion of +@samp{--strace} in @ref{Invoking runtest,,Running the Tests}. + +@item +Finally, if the value of @samp{verbose} is 3 or greater, @code{runtest} +turns on the @code{expect} command @code{log_user}. This command prints +all @code{expect} actions to the @code{expect} standard output, to the +detailed log file, and (if @samp{--debug} is on) to @file{dbg.log}. +@end enumerate + +@node Adding +@section Adding a test case to a test suite +@cindex adding a test case + +There are two slightly different ways to add a test case. One is to add +the test case to an existing directory. The other is to create a new +directory to hold your test. The existing test directories represent +several styles of testing, all of which are slightly different; examine +the directories for the tool of interest to see which (if any) is most +suitable. + +Adding a @sc{gcc} test can be very simple: just add the C code to any +directory beginning with @samp{gcc.} and it runs on the next +@samp{runtest --tool gcc}. + +To add a test to @sc{gdb}, first add any source code you will need to +the test directory. Then you can either create a new @code{expect} file, +or add your test to an existing one (any file with a @samp{.exp} +suffix). Creating a new @samp{.exp} file is probably a better idea if +the test is significantly different from existing tests. Adding it as a +separate file also makes upgrading easier. If the C code has to be +already compiled before the test will run, then you'll have to add it to +the @file{Makefile.in} file for that test directory, then run +@code{configure} and @code{make}. + +Adding a test by creating a new directory is very similar: + +@enumerate +@item +Create the new directory. All subdirectory names begin with the name of +the tool to test; e.g. @sc{g++} tests might be in a directory called +@file{g++.other}. There can be multiple test directories that start with +the same tool name (such as @samp{g++}). + +@item +Add the new directory name to the @samp{configdirs} definition in the +@file{configure.in} file for the test suite directory. This way when +@code{make} and @code{configure} next run, they include the new directory. + +@item +Add the new test case to the directory, as above. + +@item +To add support in the new directory for configure and make, you must +also create a @code{Makefile.in} and a @code{configure.in}. @xref{What +Configure Does,,What Configure Does, configure.info, Cygnus Configure}. +@end enumerate + +@c FIXME! Expand this sentence to at least a section, maybe a chapter... +@c The @file{admin} directory contains templates for a few common forms +@c of test. + +@node Hints +@section Hints on writing a test case +@cindex hints on test case writing + +There may be useful existing procedures already written for your test in +the @file{lib} directory of the DejaGnu distribution. @xref{DejaGnu +Builtins,,DejaGnu Builtins}. + +It is safest to write patterns that match @emph{all} the output +generated by the tested program; this is called @dfn{closure}. If a +pattern does not match the entire output, any output that remains will +be examined by the @emph{next} @code{expect} command. In this +situation, the precise boundary that determines which @code{expect} +command sees what is very sensitive to timing between the @code{expect} +task and the task running the tested tool. As a result, the test may +sometimes appear to work, but is likely to have unpredictable results. +(This problem is particularly likely for interactive tools, but can also +affect batch tools---especially for tests that take a long time to finish.) +The best way to ensure closure is to use the @samp{-re} option for the +@code{expect} command to write the pattern as a full regular +expressions; then you can match the end of output using a @samp{$}. It +is also a good idea to write patterns that match all available output by +using @samp{.*\} after the text of interest; this will also match any +intervening blank lines. Sometimes an alternative is to match end of +line using @samp{\r} or @samp{\n}, but this is usually too dependent on +terminal settings. +@c FIXME!! explain what "end of output" means for interactive task. +@c (Timeout or EOF, right?) + +Always escape punctuation, such as @samp{(} or @samp{"}, in your +patterns; for example, write @samp{\(}. If you forget to escape +punctuation, you will usually see an error message like @samp{extra +characters after close-quote}. + +If you have trouble understanding why a pattern does not match the +program output, try using the @samp{--debug} option to @code{runtest}, +and examine the debug log carefully. @xref{Debug,,Debug Log}. + +Be careful not to neglect output generated by setup rather than by the +interesting parts of a test case. For example, while testing @sc{gdb}, +I issue a send @samp{set height 0\n} command. The purpose is simply to +make sure @sc{gdb} never calls a paging program. The @samp{set height} +command in @sc{gdb} does not generate any output; but running @emph{any} +command makes @sc{gdb} issue a new @samp{(gdb) } prompt. If there were +no @code{expect} command to match this prompt, the output @samp{(gdb) } +begins the text seen by the next @code{expect} command---which might +make @emph{that} pattern fail to match. + +To preserve basic sanity, I also recommended that no test ever pass if +there was any kind of problem in the test case. To take an extreme +case, tests that pass even when the tool will not spawn are misleading. +Ideally, a test in this sort of situation should not fail either. +Instead, print an error message by calling one of the DejaGnu procedures +@code{error} or @code{warning}. + +@node Variables +@section Special variables used by test cases +@cindex special variables + +@cindex variables for all tests +Your test cases can use these variables, with conventional meanings (as +well as the variables saved in @file{site.exp} +@pxref{Customizing,,Setting @code{runtest} defaults}): + +@quotation +@emph{These variables are available to all test cases.} +@end quotation + +@ftable @code +@item prms_id +@cindex PRMS bug number +@cindex GNATS bug number +@cindex bug number +The tracking system (e.g. @sc{gnats}) number identifying a corresponding +bugreport. (@samp{0} if you do not specify it in the test script.) + +@item bug_id +@cindex bug number, extra +An optional bug id; may reflect a bug identification from another +organization. (@samp{0} if you do not specify it.) + +@item subdir +@cindex current test subdirectory +The subdirectory for the current test case. +@end ftable + +@quotation +@emph{These variables should never be changed. They appear in most +tests.} +@end quotation + +@ftable @code +@item expect_out(buffer) +@cindex last command output +The output from the last command. This is an internal variable set by +@code{expect}. + +@item exec_output +This is the output from a @code{@var{tool}_load} command. This only +applies to tools like @sc{gcc} and @sc{gas} which produce an object +file that must in turn be executed to complete a test. + +@item comp_output +This is the output from a @code{@var{tool}_start} command. This is +conventionally used for batch oriented programs, like @sc{gcc} and +@sc{gas}, that may produce interesting output (warnings, errors) without +further interaction. +@end ftable + +@node Extending +@chapter New Tools, Targets, or Hosts + +The most common ways to extend the DejaGnu framework are: adding a suite +of tests for a new tool to be tested; adding support for testing on a +new target; and porting @code{runtest} to a new host. + +@menu +* Adding Tools:: How to add tests for a new tool +* Adding Targets:: How to add a new target +* Porting:: Porting DejaGnu to a new host +@end menu + +@node Adding Tools +@section Writing tests for a new tool + +In general, the best way to learn how to write (code or even prose) is +to read something similar. This principle applies to test cases and to +test suites. Unfortunately, well-established test suites have a way of +developing their own conventions: as test writers become more +experienced with DejaGnu and with Tcl, they accumulate more utilities, +and take advantage of more and more features of @code{expect} and Tcl in +general. + +Inspecting such established test suites may make the prospect of +creating an entirely new test suite appear overwhelming. Nevertheless, +it is quite straightforward to get a new test suite going. + +@cindex Lupton, Robert +There is one test suite that is guaranteed not to grow more elaborate +over time: both it and the tool it tests were created expressly to +illustrate what it takes to get started with DejaGnu. The +@file{example/} directory of the DejaGnu distribution contains both an +interactive tool called @code{calc}, and a test suite for it. Reading +this test suite, and experimenting with it, is a good way to supplement +the information in this section. (Thanks to Robert Lupton for creating +@code{calc} and its test suite---and also the first version of this +section of the manual!) + +To help orient you further in this task, here is an outline of the steps +to begin building a test suite for a program @var{example}. + +@enumerate +@item +Create or select a directory to contain your new collection of tests. +Change to that directory (shown here as @code{testsuite}): + +@example +eg$ cd testsuite/ +@end example + +@item +Create a @file{configure.in} file in this directory, to control +configuration-dependent choices for your tests. So far as DejaGnu is +concerned, the important thing is to set a value for the variable +@code{target_abbrev}; this value is the link to the init file you will +write soon. (For simplicity, we assume the environment is Unix, and use +@samp{unix} as the value.) + +What else is needed in @file{configure.in} depends on the requirements +of your tool, your intended test environments, and which +@code{configure} system you use. This example is a minimal +@code{configure.in} for use with Cygnus Configure. (For an alternative +based on the FSF @code{autoconf} system, see the @code{calc} example +distributed with DejaGnu.) Replace @var{example} with the name of your +program: + +@cartouche +@smallexample +# This file is a shell script fragment +# for use with Cygnus configure. + +srctrigger="@var{example}.0" +srcname="The DejaGnu @var{example} tests" + +# per-host: + +# per-target: + +# everything defaults to unix for a target +target_abbrev=unix + +# post-target: + +@end smallexample +@end cartouche + +@item +Create @file{Makefile.in}, the source file used by @code{configure} to +build your @file{Makefile}. Its leading section should as usual contain +the values that @code{configure} may override: + +@cartouche +@smallexample +srcdir = . +prefix = /usr/local + +exec_prefix = $(prefix) +bindir = $(exec_prefix)/bin +libdir = $(exec_prefix)/lib +tooldir = $(libdir)/$(target_alias) + +datadir = $(exec_prefix)/lib/dejagnu + +RUNTEST = runtest +RUNTESTFLAGS = +FLAGS_TO_PASS = + +#### host, target, site specific Makefile frags come in here. +@end smallexample +@end cartouche + +This should be followed by the standard targets at your site. To begin +with, they need not do anything---for example, these definitions will +do: + +@cartouche +@smallexample + +all: + +info: + +install-info: + +install: +uninstall: + +clean: + -rm -f *~ core *.info* + +@end smallexample +@end cartouche + +It is also a good idea to make sure your @file{Makefile} can rebuild +itself if @file{Makefile.in} changes, with a target like this (which +works for either Cygnus or FSF Configure): + +@cartouche +@smallexample +Makefile : $(srcdir)/Makefile.in $(host_makefile_frag) \ + $(target_makefile_frag) + $(SHELL) ./config.status +@end smallexample +@end cartouche + +You also need to include two targets important to DejaGnu: @code{check}, +to run the tests, and @code{site.exp}, to set up the Tcl copies of +configuration-dependent values. The @code{check} target must run +@samp{runtest --tool @var{example}}: + +@cartouche +@smallexample +check: site.exp all + $(RUNTEST) $(RUNTESTFLAGS) $(FLAGS_TO_PASS) \ + --tool @var{example} --srcdir $(srcdir) +@end smallexample +@end cartouche + +The @code{site.exp} target should usually set up (among other things!) a +Tcl variable for the name of your program: + +@cartouche +@smallexample +site.exp: ./config.status Makefile + @@echo "Making a new config file..." + -@@rm -f ./tmp? + @@touch site.exp + + -@@mv site.exp site.bak + @@echo "## these variables are automatically\ + generated by make ##" > ./tmp0 + @@echo "# Do not edit here. If you wish to\ + override these values" >> ./tmp0 + @@echo "# add them to the last section" >> ./tmp0 + @@echo "set host_os $@{host_os@}" >> ./tmp0 + @@echo "set host_alias $@{host_alias@}" >> ./tmp0 + @@echo "set host_cpu $@{host_cpu@}" >> ./tmp0 + @@echo "set host_vendor $@{host_vendor@}" >> ./tmp0 + @@echo "set target_os $@{target_os@}" >> ./tmp0 + @@echo "set target_alias $@{target_alias@}" >> ./tmp0 + @@echo "set target_cpu $@{target_cpu@}" >> ./tmp0 + @@echo "set target_vendor $@{target_vendor@}" >> ./tmp0 + @@echo "set host_triplet $@{host_canonical@}" >> ./tmp0 + @@echo "set target_triplet $@{target_canonical@}">>./tmp0 + @@echo "set tool binutils" >> ./tmp0 + @@echo "set srcdir $@{srcdir@}" >> ./tmp0 + @@echo "set objdir `pwd`" >> ./tmp0 + @@echo "set @var{examplename} @var{example}" >> ./tmp0 + @@echo "## All variables above are generated by\ + configure. Do Not Edit ##" >> ./tmp0 + @@cat ./tmp0 > site.exp + @@sed < site.bak \ + -e '1,/^## All variables above are.*##/ d' \ + >> site.exp + -@@rm -f ./tmp? +@end smallexample +@end cartouche + +@item +Create a directory (in @file{testsuite/}) called @file{config/}: + +@example +eg$ mkdir config +@end example + +@item +Make an init file in this directory; its name must start with the +@code{target_abbrev} value, so call it @file{config/unix.exp}. +This is the file that contains the target-dependent procedures; +fortunately, most of them do not have to do very much in order for +@code{runtest} to run. + +If @var{example} is not interactive, you can get away with this minimal +@file{unix.exp} to begin with: + +@cartouche +@smallexample +proc foo_exit @{@} @{@} +proc foo_version @{@} @{@} +@end smallexample +@end cartouche + +If @var{example} is interactive, however, you might as well define a +start routine @emph{and invoke it} by using an init file like this: + +@cartouche +@smallexample +proc foo_exit @{@} @{@} +proc foo_version @{@} @{@} + +proc foo_start @{@} @{ + global @var{examplename} + spawn $@var{examplename} + expect @{ + -re "" @{@} + @} +@} +foo_start +@end smallexample +@end cartouche + +@item +Create a directory whose name begins with your tool's name, to contain +tests: + +@example +eg$ mkdir @var{example}.0 +@end example + +@item +Create a sample test file in @file{@var{example}.0}. Its name must end +with @samp{.exp}; you can use @samp{first-try.exp} To begin with, just +write there a line of Tcl code to issue a message: + +@cartouche +@smallexample +send_user "Testing: one, two...\n" +@end smallexample +@end cartouche + +@item +Back in the @file{testsuite/} (top level) directory, run + +@example +eg$ configure +@end example + +(You may have to specify more of a path, if a suitable @code{configure} +is not available in your execution path.) + +@item +You are now ready to triumphantly type @samp{make check} or +@samp{runtest --tool @var{example}}. You should see something like this: + +@cartouche +@smallexample +Test Run By rhl on Fri Jan 29 16:25:44 EST 1993 + + === @var{example} tests === + +Running ./@var{example}.0/first-try.exp ... +Testing: one, two... + + === @var{example} Summary === + +@end smallexample +@end cartouche + +There is no output in the summary, because so far the example does not +call any of the procedures that establish a test outcome. + +@item +Begin writing some real tests. For an interactive tool, you should +probably write a real exit routine in fairly short order; in any case, +you should also write a real version routine soon. +@end enumerate + +@node Adding Targets +@section Adding a target +@cindex adding a target + +DejaGnu has some additional requirements for target support, beyond the +general-purpose provisions of Cygnus @code{configure}. @code{runtest} +must actively communicate with the target, rather than simply generating +or managing code for the target architecture. Therefore, each tool +requires an initialization module for each target. For new targets, you +must supply a few Tcl procedures to adapt DejaGnu to the target. This +permits DejaGnu itself to remain target independent. @xref{Init +Module,,Initialization module}, for a discussion of the naming +conventions that enable DejaGnu to locate and use init files. + +Usually the best way to write a new initialization module is to edit an +existing initialization module; some trial and error will be required. +If necessary, you can use the @samp{--debug} option to see what +is really going on. + +When you code an initialization module, be generous in printing +information controlled by the @code{verbose} procedure (@pxref{DejaGnu +Builtins, DejaGnu procedures}). + +Most of the work is in getting the communications right. Communications +code (for several situations involving IP networks or serial lines) is +available in a DejaGnu library file, @file{lib/remote.exp}. +@xref{DejaGnu Builtins,,DejaGnu Builtins}. + +@c FIXME! Say something about Tcl debugger here. +If you suspect a communication problem, try running the connection +interactively from @code{expect}. (There are three ways of running +@code{expect} as an interactive interpreter. You can run @code{expect} +with no arguments, and control it completely interactively; or you can +use @samp{expect -i} together with other command-line options and +arguments; or you can run the command @code{interpreter} from any +@code{expect} procedure. Use @code{return} to get back to the calling +procedure (if any), or @code{return -tcl} to make the calling procedure +itself return to its caller; use @code{exit} or end-of-file to leave +@code{expect} altogether.) Run the program whose name is recorded in +@samp{$connectmode}, with the arguments in @samp{$targetname}, to +establish a connection. You should at least be able to get a prompt +from any target that is physically connected. + +@node Porting +@section Porting to a new host +@cindex porting to a new host + +The task of porting DejaGnu is basically that of porting Tcl and +@code{expect}. Tcl and @code{expect}, as distributed with DejaGnu, both +use @code{autoconf}; they should port automatically to most Unix +systems. + +Once Tcl and @code{expect} are ported, DejaGnu should run. Most system +dependencies are taken care of by using @code{expect} as the main +command shell. + +@node Installation +@appendix Installing DejaGnu + +@cindex host, explained +@cindex target, explained +@cindex DejaGnu configuration +@cindex configuring DejaGnu +Once you have the DejaGnu source unpacked and available, you must first +configure the software to specify where it is to run (and the associated +defaults); then you can proceed to installing it. + +@menu +* Configuring DejaGnu:: +* Installing DejaGnu:: +@end menu + +@node Configuring DejaGnu +@section Configuring the DejaGnu test driver + +It is usually best to configure in a directory separate +from the source tree, specifying where to find the source with the +optional @samp{--srcdir} option to @code{configure}. DejaGnu uses the +GNU @code{autoconf} to configure itself. For more info on using +autoconf, read the GNU autoconf manual. To configure, execute the +@file{configure} program, no other options are required. For an example, +to configure in a seperate tree for objects, execute the configure +script from the source tree like this: + +@smallexample +../dejagnu-1.3/configure +@end smallexample + +DejaGnu doesn't care at config time if it's for testing a native system +or a cross system. That is determined at runtime by using the config +files. + +@cindex @code{prefix}, configure options +@cindex @code{exec_prefix}, configure options. +You may also want to use the @code{configure} option @samp{--prefix} to +specify where you want DejaGnu and its supporting code installed. By +default, installation is in subdirectories of @file{/usr/local}, but you +can select any alternate directory @var{altdir} by including +@samp{--prefix=@var{altdir}} on the @code{configure} command line. +(This value is captured in the Makefile variables @code{prefix} +and @code{exec_prefix}.) + +@cindex auxiliary programs +@cindex test suite distributions +@cindex @code{make} builds part of tests +Save for a small number of example tests, the DejaGnu distribution +itself does not include any test suites; these are available separately. +Test suites for the @sc{gnu} compiler (testing both GCC and G++) and for +the @sc{gnu} binary utilities are distributed in parallel with the +DejaGnu distribution (but packaged as separate files). The test suite +for the @sc{gnu} debugger is distributed in parallel with each release +of GDB itself, starting with GDB 4.9. After configuring the top-level +DejaGnu directory, unpack and configure the test directories for the +tools you want to test; then, in each test directory, run @code{make} to +build auxiliary programs required by some of the tests. + +@node Installing DejaGnu +@section Installing DejaGnu + +@cindex installing DejaGnu +To install DejaGnu in your filesystem (either in @file{/usr/local}, or +as specified by your @samp{--prefix} option to @code{configure}), execute + +@example +eg$ make install +@end example + +@noindent +@samp{make install} does these things for DejaGnu: + +@enumerate +@item +Look in the path specified for executables (@file{$exec_prefix}) for +directories called @file{lib} and @file{bin}. If these directories do +not exist, @samp{make install} creates them. + +@item +Create another directory in the @file{lib} directory, called +@file{dejagnu}. + +@item +Copy the @code{runtest} shell script into @file{$exec_prefix/bin}. + +@item +Copy all the library files (used to support the framework) into +@file{$exec_prefix/lib/dejagnu}. + +@item +Copy @file{runtest.exp} into @file{$exec_prefix/lib/dejagnu}. This is +the main Tcl code implementing DejaGnu. + +@end enumerate + +Each test suite collection comes with simple installation instructions +in a @file{README} file; in general, the test suites are designed to be +unpacked in the source directory for the corresponding tool, and extract +into a directory called @file{testsuite}. + +@node Index +@unnumbered Index + +@printindex cp + +@contents + +@bye diff --git a/doc/overview.sgml b/doc/overview.sgml new file mode 100644 index 0000000..58bce0c --- /dev/null +++ b/doc/overview.sgml @@ -0,0 +1,439 @@ +<!DOCTYPE book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ + +<!-- Begin Document Specific Declarations --> + +<?Fm: Validation Off> + +<!ENTITY version "0.5"> +<!ENTITY dj "DejaGnu"> + +<!ENTITY dejagnu-copyright " + <YEAR>1998</YEAR> + <HOLDER>Free Software Foundation, Inc.</HOLDER>"> + +<!ENTITY dejagnu-code-copyright " +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +This file documents the GNU Testing Framework ``DejaGnu'' + +Copyright (C) 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc. + +This text may be freely distributed under the terms of the GNU +General Public License. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +"> + +<!ENTITY dejagnu-copyright " +Copyright 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +"> + +<!-- The reference material --> +<!entity ref SYSTEM "ref.sgml"> + +<!-- The user manual --> +<!entity user SYSTEM "user.sgml"> + +<!-- End Document Specific Declarations --> +]> + +<book> + <bookinfo> + <title>&dj;</title> + <subtitle>The GNU Testing Framework</subtitle> + <date>1998 Nov 24</date> + <edition> &version</edition> + <releaseinfo> for circulation within Cygnus</releaseinfo> + <authorgroup> + <author> + <firstname>Rob Savoye</firstname> + <affiliation> + <orgname>Free Software Foundation</orgname></affiliation> + <!-- <authorblurb> + <title>Rob Savoye</title> + <para> + His home page is at <ulink> + URL="http://www.welcomehome.org/rob.html">this + location</ulink> + </para> + </authorblurb> + --> + </author> + </authorgroup> + <address> + <email>rob@welcomehome.org</email> + </address> + <!-- &cygnus-street-address; --> + <copyright>&dejagnu-copyright;</copyright> + <!-- <legalnotice> + <para> --> + <!-- [FIXME: must put legal notice here] --> + <!-- </para> --> + <!-- &cygnus-legal-notice; --> + <!-- </legalnotice> --> + <revhistory> + <revision> + <revnumber> 0.1</revnumber> + <date>1998-11</date> + <authorinitials>rob@welcomehome.org</authorinitials> + <revremark>Initial version after conversion to DocBook.</revremark> + </revision> + </revhistory> + + </bookinfo> + + <toc></toc> + + <preface id=preface> + <title>Abstract</title> + + <para>This document attempts to describe the functionality of + DejaGnu, the GNU Testing Framework. DejaGnu is entirely written in + <productname>Expect</productname>, which uses + <productname>Tcl</productname> as a command + language. <productname>Expect</productname> serves as a very + programmable shell; you can run any program, as with the usual + Unix command shells---but once the program is started, your + test script has fully programmable control of + its input and output. This does not just apply to the programs + under test; <command>expect</command> can also run any auxiliary + program, such as <command>diff</command> or <command>sh</command>, + with full control over its input and output.</para> + + <para>DejaGnu itself is merely a framework for creation of a test + suites. Test suites are distributed separately for each GNU + tool.</para> + + </preface> + + <chapter id=overview xreflabel=Overview> + <title>Overview</title> + + <sect1 id=whatis xreflabel="What is &dj; ?"> + <title>What is &dj; ?</title> + + <para><productname>DejaGnu</productname> is a framework for + testing other programs. Its purpose is to provide a single + front end for all tests. Think of it as a custom library of + Tcl procedures crafted to support writing a test harness. A + <emphasis>Test Harness</emphasis> is the testing + infrastructure that is created to support a specific program + or tool. Each program can have multiple test suites, all + supported by a single test harness. DejaGnu is written in + <productname>Expect</productname>, which in turn uses + <productname>Tcl</productname> -- Tool command + language. There is more information on Tcl at the <ulink + URL="http://www.scriptics.com">Scriptics</ulink> web site, and the + Expect web site is at <ulink + URL="http://expect.nist.gov">NIST</ulink>.</para> + + <para>DejaGnu offers several advantages for testing:</para> + + <itemizedlist mark="bullet" spacing="compact"> + + <listitem><para>The flexibility and consistency of the DejaGnu + framework make it easy to write tests for any program, with + either batch oriented, or interactive programs.</para> + </listitem> + + <listitem><para>DejaGnu provides a layer of abstraction which + allows you to write tests that are portable to any host or + target where a program must be tested. For instance, a test + for <command>GDB</command> can run (from any Unix + based host) on any target architecture that DejaGnu + supports. Currently DejaGnu runs tests on many single board + computers, whose operating software ranges from just a boot + monitor to a full-fledged, Unix-like realtime OS.</para> + </listitem> + + <listitem><para>All tests have the same output format. This + makes it easy to integrate testing into other software + development processes. DejaGnu's output is designed to be + parsed by other filtering script, and it is also human + readable.</para> + </listitem> + + <listitem><para>Using Tcl and expect, it's easy to create wrappers + for existing test suites. By incorporating existing tests under + DejaGnu, it's easier to have a single set of report analyse + programs..</para> + + </listitem> + </itemizedlist> + + <para>Running tests requires two things: the testing framework, and + the test suites themselves. Tests are usually written in + <productname>Expect</productname> using Tcl, but you can also use a + Tcl script to run a test suite that is not based on + <productname>Expect</productname>. + (<productname>expect</productname> script filenames conventionally + use <emphasis>.exp</emphasis> as a suffix; for example, the main + implementation of the DejaGnu test driver is in the file + <productname>runtest.exp</productname>.)</para> + + <para>Julia Menapace first coined the term ``Deja Gnu'' to describe an + earlier testing framework at Cygnus Support she had written for + <command>GDB</command>. When we replaced it with the Expect-based + framework, it was like DejaGnu all over again... But more importantly, it + was also named after my daughter,<ulink + URL="mailto:deja@welcomehome.org">Deja Snow Savoye</ulink> (now 9 + years old in Dec of 1998), who was a toddler during DejaGnu's + creation.</para> + + </sect1> + + <sect1 id=new xreflabel="Release Notes"> + <title>What's New In This Release</title> + + <para>This release has a number of substantial changes over version + 1.3. The most visible change is that the version of Expect and Tcl + included in the release are up-to-date with the current stable net + releases. The biggest change is years of modifications to the + target configuration system, used for cross testing. While this + greatly improved cross testing, is has made that subsystem very + complicated. The goal is to have this entirely rewritten using + <productname>iTcl</productname> by the next release. Other changes + are:</para> + + <itemizedlist> + <listitem><para>More builtin support for building target binaries + with the correct linker flags. Currently this only works with + <productname>GCC</productname> as the cross compiler, + preferably with a target supported by + <xref linkend=libgloss>.</para></listitem> + + <listitem><para>Lots of little bug fixes from years of heavy + use at Cygnus Solutions.</para></listitem> + + <listitem><para>DejaGnu now uses + <productname>Automake</productname> for Makefile + configuration.</para></listitem> + + <listitem><para>Updated documentation, now in SGML + (using the <ulink + URL="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html">free + GNU DocBook tools</ulink>) format.</para></listitem> + + <listitem><para>NT support. There is beta level support for NT + that is still a work in progress. This requires the <ulink + URL=httpd://sourceware.cygnus.com>Cygwin</ulink> POSIX system + for NT.</para></listitem> + + </itemizedlist> + + <sect2 id=cygwin xreflabel="NT Support"> + <title>NT Support</title> + + <para>To use DejaGnu on NT, you need to first install the + <ulink URL="http://sourceware.cygnus.com">Cygwin</ulink> + release. This works as of the B20.1 release. Cygwin is a POSIX + system for NT. This covers both utility programs, and a libray + that adds POSIX system calls to NT. Among them is pseudo tty + support for NT that emulates the POSIX pty standard. The + latest Cygwin is always available from <ulink + URL="http://sourceware.cygnus.com">this location</ulink>. This + works well enough to run <emphasis>"make check"</emphasis> of + the GNU development tree on NT after a native build. But the + nature of pty's on NT is still evolving. Your mileage may + vary...</para> + + </sect2> + + </sect1> + + <sect1 id=designgoals xreflabel="Design Goals"> + <title>Design Goals</title> + + <para>DejaGnu grew out of the internal needs of Cygnus Solutions. (then + Cygnus Support). Cygnus maintains and enhances a variety of free programs + in many different environments, and we needed a testing tool that:</para> + + <itemizedlist mark="bullet"> + <listitem><para>is useful to developers while fixing bugs.</para> + <listitem><para>automates running many tests during a software + release process.</para> + <listitem><para>is portable among a variety of host + computers.</para> + <listitem><para>supports cross-development testing.</para> + <listitem><para>permits testing interactive programs, like + <command>GDB</command>; and </para> + <listitem><para>permits testing batch oriented programs, like + <command>GCC</command>.</para> + </itemizedlist> + + <para>Some of the requirements proved challenging. For example, + interactive programs do not lend themselves very well to automated testing. + But all the requirements are important: for instance, it is imperative to + make sure that <command>GDB</command> works as well when cross-debugging + as it does in a native configuration. </para> + + <para>Probably the greatest challenge was testing in a cross-development + environment (which can be a real nightmare). Most cross-development + environments are customized by each developer. Even when buying packaged + boards from vendors there are many differences. The communication + interfaces vary from a serial line to ethernet. DejaGnu was designed with + a modular communication setup, so that each kind of communication can be + added as required, and supported thereafter. Once a communication + procedure is coded, any test can use it. Currently DejaGnu can use + <command>rsh</command>, <command>rlogin</command>, + <command>telnet</command>, <command>tip</command>, + <command>kermit</command>, and <command>mondfe</command> for remote + communications.</para> + + </sect1> + + <sect1 id=posix xreflabel="A POSIX Conforming Test Framework"> + <title>A POSIX conforming test framework</title> + + <para>DejaGnu conforms to the POSIX 1003.3 standard for test + frameworks. I was also a member of that committe.</para> + + <para>The POSIX standard 1003.3 defines what a testing framework needs to + provide, in order to permit the creation of POSIX conformance test + suites. This standard is primarily oriented to running POSIX conformance + tests, but its requirements also support testing of features not related + to POSIX conformance. POSIX 1003.3 does not specify a particular testing + framework, but at this time there is only one other POSIX conforming test + framework: TET. TET was created by Unisoft for a consortium comprised of + X/Open, Unix International, and the Open Software Foundation.</para> + + <para>The POSIX documentation refers to <firstterm>assertions</firstterm>. + An assertion is a description of behavior. For example, if a standard + says ``The sun shall shine'', a corresponding assertion might be ``The + sun is shining.'' A test based on this assertion would pass or fail + depending on whether it is daytime or nighttime. It is important to note + that the standard being tested is never 1003.3; the standard being tested + is some other standard, for which the assertions were written.</para> + + <para>As there is no test suite to test testing frameworks for POSIX + 1003.3 conformance, verifying conformance to this standard is done by + repeatedly reading the standard and experimenting. One of the main + things 1003.3 does specify is the set of allowed output messages, and + their definitions. Four messages are supported for a required feature of + POSIX conforming systems, and a fifth for a conditional feature. DejaGnu + supports the use of all five output messages; in this sense a test suite + that uses exactly these messages can be considered POSIX conforming. + These definitions specify the output of a test case:</para> + + <variablelist> + <varlistentry> + <term>PASS</term> + <listitem><para>A test has succeeded. That is, it demonstrated that + the assertion is true.</para></listitem> + </varlistentry> + + <varlistentry> + <term>XFAIL</term> + <listitem><para>POSIX 1003.3 does not incorporate the notion of + expected failures, so <emphasis>PASS</emphasis>, instead of + <emphasis>XPASS</emphasis>, must also be returned for test cases + which were expected to fail and did not. This means that + <emphasis>PASS</emphasis> is in some sense more ambiguous than if + <emphasis>XPASS</emphasis> is also used.</para></listitem> + </varlistentry> + + <varlistentry> + <term>FAIL</term> + <listitem><para>A test has produced the bug it was intended to + capture. That is, it has demonstrated that the assertion is false. + The <emphasis>FAIL</emphasis> message is based on the test case only. + Other messages are used to indicate a failure of the framework. As + with <emphasis>PASS</emphasis>, POSIX tests must return + <emphasis>FAIL</emphasis> rather than <emphasis>XFAIL</emphasis> even + if a failure was expected.</para></listitem> + </varlistentry> + + <varlistentry> + <term>UNRESOLVED</term> + <listitem><para>A test produced indeterminate results. Usually, this + means the test executed in an unexpected fashion; this outcome + requires that a human being go over results, to determine if the test + should have passed or failed. This message is also used for any test + that requires human intervention because it is beyond the abilities + of the testing framework. Any unresolved test should resolved to + <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> before a test + run can be considered finished.</para> + + <para>Note that for POSIX, each assertion must produce a test result + code. If the test isn't actually run, it must produce + <emphasis>UNRESOLVED</emphasis> rather than just leaving that test + out of the output. This means that you have to be careful when + writing tests, to not carelessly use tcl statements like + <emphasis>return</emphasis>---if you alter the flow of control of the + tcl code you must insure that every test still produces some result + code.</para> + + <para>Here are some of the ways a test may wind up + <emphasis>UNRESOLVED</emphasis>:</para> + + <itemizedlist mark=bullet> + <listitem><para>A test's execution is interrupted.</listitem> + + <listitem><para>A test does not produce a clear result. This is + usually because there was an <emphasis>ERROR</emphasis> from + DejaGnu while processing the test, or because there were three or + more <emphasis>WARNING</emphasis> messages. Any + <emphasis>WARNING</emphasis> or <emphasis>ERROR</emphasis> messages + can invalidate the output of the test. This usually requires a + human being to examine the output to determine what really + happened---and to improve the test case.</para></listitem> + + <listitem><para>A test depends on a previous test, which + fails.</para></listitem> + + <listitem><para>The test was set up incorrectly.</para></listitem> + </itemizedlist> + + <varlistentry> + <term>UNTESTED</term> + <listitem><para>A test was not run. This is a placeholder, used + when there is no real test case yet.</para> + </varlistentry> + </variablelist> + + <para>The only remaining output message left is intended to test + features that are specified by the applicable POSIX standard as + conditional:</para> + + <variablelist> + <varlistentry> + <term>UNSUPPORTED</term> + <listitem><para>There is no support for the tested case. This may + mean that a conditional feature of an operating system, or of a + compiler, is not implemented. DejaGnu also uses this message when + a testing environment (often a ``bare board'' target) lacks basic + support for compiling or running the test case. For example, a + test for the system subroutine <emphasis>gethostname</emphasis> + would never work on a target board running only a boot monitor. + </varlistentry> + </variablelist> + + <para>DejaGnu uses the same output procedures to produce these messages + for all test suites, and these procedures are already known to conform + to POSIX 1003.3. For a DejaGnu test suite to conform to POSIX 1003.3, + you must avoid the <emphasis>setup</emphasis>xfail} procedure as + described in the <emphasis>PASS</emphasis> section above, and you must + be careful to return <emphasis>UNRESOLVED</emphasis> where appropriate, + as described in the <emphasis>UNRESOLVED</emphasis> section + above.</para> + </sect1> + + </chapter> + + <!-- include the user manual --> + &user; + + <!-- include the reference manual --> + &ref; + +</book> diff --git a/doc/ref.sgml b/doc/ref.sgml new file mode 100644 index 0000000..6a1a7d6 --- /dev/null +++ b/doc/ref.sgml @@ -0,0 +1,4242 @@ +<chapter id=reference> + <title>Reference</title> + + <sect1 id=installation xreflabel="Installation"> + <title>Installation</title> + + <para>Once you have the DejaGnu source unpacked and available, you must + first configure the software to specify where it is to run (and the + associated defaults); then you can proceed to installing it.</para> + + <sect2 id=configuring xreflabel="Configuring DejaGnu"> + <title>Configuring DejaGnu</title> + + <para>It is usually best to configure in a directory separate from the + source tree, specifying where to find the source with the optional + <emphasis>--srcdir</emphasis> option to + <emphasis>configure</emphasis>. DejaGnu uses the GNU + <emphasis>autoconf</emphasis> to configure itself. For more info on using + autoconf, read the GNU autoconf manual. To configure, execute the + <filename>configure</filename> program, no other options are + required. For an example, to configure in a seperate tree for objects, + execute the configure script from the source tree like this:</para> + + <screen> + ../dejagnu-1.4/configure + </screen> + + <para>DejaGnu doesn't care at config time if it's for testing a native + system or a cross system. That is determined at runtime by using the + config files.</para> + + <para>You may also want to use the <command>configure</command> option + <emphasis>--prefix</emphasis> to specify where you want DejaGnu and its + supporting code installed. By default, installation is in subdirectories + of <filename>/usr/local</filename>, but you can select any alternate + directory <symbol>altdir</symbol> by including + <option>--prefix</option>{altdir}} on the + <command>configure</command> command line. (This value is captured in + the Makefile variables <emphasis>prefix</emphasis> and + <emphasis>exec</emphasis>prefix}.)</para> + + <para>Save for a small number of example tests, the DejaGnu distribution + itself does not include any test suites; these are available + separately. Test suites for the GNU development tools are included in + those releases. After configuring the top-level DejaGnu directory, unpack + and configure the test directories for the tools you want to test; then, + in each test directory, run <emphasis>make check</emphasis> to build + auxiliary programs required by some of the tests, and run the test + suites.</para> + + </sect2> + + <sect2 id=installing xreflabel="Installing DejaGnu"> + <title>Installing DejaGnu</title> + + <para>To install DejaGnu in your filesystem (either in + <filename>/usr/local</filename>, or as specified by your + <emphasis>--prefix</emphasis> option to <emphasis>configure</emphasis>), + execute.</para> + + <screen> + eg$ make install + </screen> + + <para><emphasis>make install</emphasis>does thes things for + DejaGnu:</para> + + <itemizedlist mark=bullet> + <listitem><para>Look in the path specified for executables + <symbol>$exec_prefix</symbol>) for directories called + <filename>lib</filename> and <filename>bin</filename>. If these + directories do not exist, <emphasis>make install</emphasis> creates + them.</para></listitem> + + <listitem><para>Create another directory in the + <filename>share</filename> directory, called + <filename>dejagnu</filename>, and copy all the library files into + it.</listitem> + + <listitem><para>Create a directory in the + <filename>dejagnu/share</filename> directory, called + <filename>config</filename>, and copy all the configuration files into + it.</listitem> + + <listitem><para>Copy the <emphasis>runtest</emphasis> shell script into + <filename>$exec_prefix/bin</filename>. + + <listitem><para>Copy <filename>runtest.exp</filename> into + <filename>$exec_prefix/lib/dejagnu</filename>. This is the main Tcl + code implementing DejaGnu.</para></listitem> + + </itemizedlist> + </sect2> + </sect1> + + <sect1 id=builtins xreflabel="Builtin Procedures"> + <title>Builtin Procedures</title> + + <para>DejaGnu provides these Tcl procedures.</para> + + <sect2 id=coreprocs xreflabel="Core Internal Procedures"> + <title>Core Internal Procedures</title> + + <sect3 id=mailfile xreflabel="mail_file procedure"> + <title>Mail_file Procedure</title> + + <funcsynopsis role="tcl"> + <funcdef><function>mail_file</function></funcdef> + <paramdef><parameter>file to subject</parameter</paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter></parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=openlogs xreflabel="open_logs procedure"> + <title>Open_logs Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>open_logs</function></funcdef> + <paramdef><parameter></parameter</paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=closelogs xreflabel="close_logs procedure"> + <title>Close_logs Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>close_logs</function></funcdef> + <paramdef><parameter></parameter</paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=isbuild xreflabel="isbuild procedure"> + <title>Isbuild Procedure</title> + + <para>Tests for a particular build host environment. If the + currently configured host matches the argument string, the result is + <emphasis>1</emphasis>; otherwise the result is + <emphasis>0</emphasis>. <emphasis>host</emphasis> must be a full + three-part configure host name; in particular, you may not use the + shorter nicknames supported by configure (but you can use wildcard + characters, using shell syntax, to specify sets of names). If it is + passed a NULL string, then it returns the name of the build canonical + configuration.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>isbuild</function></funcdef> + <paramdef><parameter>pattern</parameter</paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>pattern</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=isremote xreflabel="is_remote procedure"> + <title>Is_remote Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>is_remote</function></funcdef> + <paramdef><parameter>board</parameter</paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter></parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=is3way xreflabel="is3way procedure"> + <title>is3way Procedure</title> + + <para>Tests for a canadian cross. This is when the tests will be run + on a remotly hosted cross compiler. If it is a canadian cross, then + the result is <emphasis>1</emphasis>; otherwise the result is + <emphasis>0</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>is3way</function></funcdef> + <paramdef><parameter></parameter</paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=ishost xreflabel="ishost procedure"> + <title>Ishost Procedure</title> + + <para>Tests for a particular host environment. If the currently + configured host matches the argument string, the result is + <emphasis>1</emphasis>; otherwise the result is + <emphasis>0</emphasis>. <emphasis>host</emphasis> must be a full + three-part configure host name; in particular, you may not use the + shorter nicknames supported by configure (but you can use wildcard + characters, using shell syntax, to specify sets of names).</para> + + <funcsynopsis role="tcl"> + <funcdef><function>ishost</function></funcdef> + <paramdef><parameter>pattern</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter></parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=istarget xreflabel="istarget procedure"> + <title>Istarget Procedure</title> + + <para>Tests for a particular target environment. If the currently + configured target matches the argument string, the result is + <emphasis>1</emphasis> ; otherwise the result is + <emphasis>0</emphasis>. target must be a full three-part configure + target name; in particular, you may not use the shorter nicknames + supported by configure (but you can use wildcard characters, using + shell syntax, to specify sets of names). If it is passed a + <emphasis>NULL</emphasis> string, then it returns the name of the + build canonical configuration.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>istarget</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter></parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=isnative xreflabel="isnative procedure"> + <title>Isnative Procedure</title> + + <para>Tests whether the current configuration has the same host and + target. When it runs in a native configuration this procedure returns + a <emphasis>1</emphasis>; otherwise it returns a + <emphasis>0</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>isnative</function></funcdef> + <paramdef><parameter></parameter</paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=unknown xreflabel="unknown procedure"> + <title>Unknown Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>unknown</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=cloneoutput xreflabel="clone_output procedure"> + <title>Clone_output Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>clone_output</function></funcdef> + <paramdef><parameter>message</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>message</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=resetvars xreflabel="reset_vars procedure"> + <title>Reset_vars Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>reset_vars</function></funcdef> + <paramdef><parameter></parameter</paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=logandexit xreflabel="log_and_exit procedure"> + <title>Log_and_exit Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>log_and_exit</function></funcdef> + <paramdef><parameter></parameter</paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=logsummary xreflabel="log_summary procedure"> + <title>Log_summary Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>log_summary</function></funcdef> + <paramdef><parameter>args</parameter</paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=cleanup xreflabel="cleanup procedure"> + <title>Cleanup Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>cleanup</function></funcdef> + <paramdef><parameter></parameter</paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=setupxfail xreflabel="setup_xfail procedure"> + <title>Setup_xfail Procedure</title> + + <para>Declares that the test is expected to fail on a particular set + of configurations. The config argument must be a list of full + three-part configure target name; in particular, you may not use the + shorter nicknames supported by configure (but you can use the common + shell wildcard characters to specify sets of names). The + <emphasis>bugid</emphasis> argument is optional, and used only in the + logging file output; use it as a link to a bug-tracking system such + as <productname>GNATS</productname>.</para> + + <para>Once you use <function>setup_xfail</function>, the + <function>fail</function> and <function>pass</function> procedures + produce the messages <emphasis>XFAIL</emphasis> and + <emphasis>XPASS</emphasis> respectively, allowing you to distinguish + expected failures (and unexpected success!) from other test + outcomes.</para> + + <warning><para>Warning you must clear the expected failure after + using setup_xfail in a test case. Any call to <function>pass + </function>or <function>fail</function>l clears the expected failure + implicitly; if the test has some other outcome, e.g. an error, you + can call <function>clear_xfail</function> to clear the expected + failure explicitly. Otherwise, the expected-failure declaration + applies to whatever test runs next, leading to surprising + results.</para></warning> + + <funcsynopsis role="tcl"> + <funcdef><function>setup_xfail</function></funcdef> + <paramdef><parameter>config</parameter> + <parameter>bugid</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>config</parameter></term> + <listitem><para>The config triplet to trigger whether this is an + unexpected or expect failure.</para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>bugid</parameter></term> + <listitem><para>The optional bugid, used to tie it this test case + to a bug tracking system.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=recordtest xreflabel="record_test procedure"> + <title>Record_test Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>record_test</function></funcdef> + <paramdef><parameter>type</parameter> + <parameter>message</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>type</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>message</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=pass xreflabel="pass procedure"> + <title>Pass Procedure</title> + + <para>Declares a test to have passed. <function>pass</function> + writes in the log files a message beginning with + <emphasis>PASS</emphasis> (or <emphasis>XPASS</emphasis>, if failure + was expected), appending the argument + <parameter>string</parameter>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>pass</function></funcdef> + <paramdef><parameter>string</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem><para>The string to use for this PASS + message.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=fail xreflabel="fail procedure"> + <title>Fail Procedure</title> + + <para>Declares a test to have failed. <function>fail</function> + writes in the log files a message beginning with + <emphasis>FAIL</emphasis> (or <emphasis>XFAIL</emphasis>, if failure + was expected), appending the argument + <parameter>string</parameter>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>fail</function></funcdef> + <paramdef><parameter>string</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem><para>The string to use for this FAIL + message.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=xpass xreflabel="xpass procedure"> + <title>Xpass Procedure</title> + + <para>Declares a test to have unexpectably passed, when it was + expected to be a failure. <function>xpass</function> + writes in the log files a message beginning with + <emphasis>XPASS</emphasis> (or <emphasis>XFAIL</emphasis>, if failure + was expected), appending the argument + <parameter>string</parameter>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>xpass</function></funcdef> + <paramdef><parameter>string</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem><para>The string to use for this output + state.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=xfail xreflabel="xfail procedure"> + <title>Xfail Procedure</title> + + <para>Declares a test to have expectably + failed. <function>xfail</function> + writes in the log files a message beginning with + <emphasis>XFAIL</emphasis> (or <emphasis>PASS</emphasis>, if success + was expected), appending the argument + <parameter>string</parameter>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>xpass</function></funcdef> + <paramdef><parameter>string</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem><para>The string to use for this output + state.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=setwarningthreshold xreflabel="set_warning_threshold procedure"> + <title>Set_warning_threshold Procedure</title> + + <para>Sets the value of <symbol>warning_threshold</symbol>. A value + of <emphasis>0</emphasis> disables it: calls to + <function>warning</function> will not turn a + <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> into an + <emphasis>UNRESOLVED</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>set_warning_threshold</function></funcdef> + <paramdef><parameter>threshold</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>threshold</parameter></term> + <listitem><para>This is the value of the new warning + threshold.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=getwarningthreshold xreflabel="get_warning_threshold procedure"> + <title>Get_warning_threshold Procedure</title> + + <para>Returns the current value of + <symbol>{warning_threshold</symbol>. The default value is 3. This + value controls how many <function>warning</function> procedures can + be called before becoming <emphasis>UNRESOLVED</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>get_warning_threshold</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + + <sect3 id=warning xreflabel="warning procedure"> + <title>Warning Procedure</title> + + <para>Declares detection of a minor error in the test case + itself. <function>warning</function> writes in the log files a message + beginning with <emphasis>WARNING</emphasis>, appending the argument + <parameter>string</parameter>. Use <function>warning</function> rather + than <function>perror</function> for cases (such as communication + failure to be followed by a retry) where the test case can recover from + the error. If the optional <parameter>number</parameter> is supplied, + then this is used to set the internal count of warnings to that + value.</para> + + <para>As a side effect, <symbol>warning_threshold</symbol> or more + calls to warning in a single test case also changes the effect of the + next <function>pass</function> or <function>fail</function> command: + the test outcome becomes <emphasis>UNRESOLVED</emphasis> since an + automatic <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> may + not be trustworthy after many warnings. If the optional numeric value + is <emphasis>0</emphasis>, then there are no further side effects to + calling this function, and the following test outcome doesn't become + <emphasis>UNRESOLVED</emphasis>. This can be used for errors with no + known side effects.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>warning</function></funcdef> + <paramdef><parameter>string</parameter> + <parameter>number</parameter> + </paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>number</parameter></term> + <listitem><para>The optional number to set the error counter. Thius + is only used to fake out the counter when using the + <function>xfail</function> procedure to control when it flips the + output over to <emphasis>UNRESOLVED</emphasis> + state.</para></listitem> + </varlistentry> + </variablelist> + + <sect3 id=perror xreflabel="perror procedure"> + <title>Perror Procedure</title> + + <para>Declares a severe error in the testing framework + itself. <function>perror</function> writes in the log files a message + beginning with <emphasis>ERROR</emphasis>, appending the argument + <parameter>string</parameter>.</para> + + <para>As a side effect, perror also changes the effect of the next + <function>pass</function> or <function>fail</function> command: the + test outcome becomes <emphasis>UNRESOLVED</emphasis>, since an + automatic <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> cannot + be trusted after a severe error in the test framework. If the optional + numeric value is <emphasis>0</emphasis>, then there are no further side + effects to calling this function, and the following test outcome + doesn't become <emphasis>UNRESOLVED</emphasis>. This can be used for + errors with no known side effects.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>perror</function></funcdef> + <paramdef><parameter>string</parameter> + <parameter>number</parameter> + </paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>number</parameter></term> + <listitem><para>The optional number to set the error counter. Thius + is only used to fake out the counter when using the + <function>xfail</function> procedure to control when it flips the + output over to <emphasis>UNRESOLVED</emphasis> + state.</para></listitem> + </varlistentry> + </variablelist> + + <sect3 id=note xreflabel="note procedure"> + <title>Note Procedure</title> + + <para>Appends an informational message to the log + file. <function>note</function> writes in the log files a message + beginning with <emphasis>NOTE</emphasis>, appending the argument + <parameter>string</parameter>. Use <function>note</function> + sparingly. The <function>verbose</function> should be used for most + such messages, but in cases where a message is needed in the log file + regardless of the verbosity level use <function>note</function>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>note</function></funcdef> + <paramdef><parameter>string</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem><para>The string to use for this note.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=untested xreflabel="untested procedure"> + <title>Untested Procedure</title> + + <para>Declares a test was not run. <function>untested</function> writes + in the log file a message beginning with <emphasis>UNTESTED</emphasis>, + appending the argument <emphasis>string</emphasis>. For example, you + might use this in a dummy test whose only role is to record that a test + does not yet exist for some feature.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>untested</function></funcdef> + <paramdef><parameter>string</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem><para>The string to use for this output + state.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=unresolved xreflabel="unresolved procedure"> + <title>Unresolved Procedure</title> + + <para>Declares a test to have an unresolved + outcome. <function>unresolved</function> writes in the log file a + message beginning with <emphasis>UNRESOLVED</emphasis>, appending the + argument <emphasis>string</emphasis>. This usually means the test did + not execute as expected, and a human being must go over results to + determine if it passed or failed (and to improve the test case).</para> + + <funcsynopsis role="tcl"> + <funcdef><function>unresolved</function></funcdef> + <paramdef><parameter>string</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem><para>The string to use for this output + state.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=unsupported xreflabel="unsupported procedure"> + <title>Unsupported Procedure</title> + + <para>Declares that a test case depends on some facility that does not + exist in the testing environment. <function>unsupported</function> + writes in the log file a message beginning with + <emphasis>UNSUPPORTED</emphasis>, appending the argument string.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>unsupported</function></funcdef> + <paramdef><parameter>string</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem><para>The string to use for this output + state.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=inittestcounts xreflabel="init_testcounts procedure"> + <title>Init_testcounts Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>init_testcounts</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=incrcount xreflabel="incr_count procedure"> + <title>Incr_count Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>incr_count</function></funcdef> + <paramdef><parameter>name</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>name</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=transform xreflabel="transform procedure"> + <title>transform Procedure</title> + + <para>Generates a string for the name of a tool as it was configured + and installed, given its native name (as the argument + <parameter>toolname</parameter>). This makes the assumption that all + tools are installed using the same naming conventions: For example, + for a cross compiler supporting the <emphasis>m68k-vxworks</emphasis> + configuration, the result of transform <command>gcc</command> is + <command>m68k-vxworks-gcc</command>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>transform</function></funcdef> + <paramdef><parameter>toolname</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>toolname</parameter></term> + <listitem><para>The name of the cross-development program to + transform.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + + <sect3 id=checkconditionalxfail xreflabel="check_conditional_xfail procedure"> + <title>Check_conditional_xfail Procedure</title> + + <para>This procedure adds a condition xfail, based on compiler + options used to create a test case executable. If an include options + is found in the compiler flags, and it's the right architecture, + it'll trigger an <emphasis>XFAIL</emphasis>. Otherwise it'll produce + an ordinary <emphasis>FAIL</emphasis>. You can also specify flags to + exclude. This makes a result be a <emphasis>FAIL</emphasis>, even if + the included options are found. To set the conditional, set + the variable <symbol>compiler_conditional_xfail_data</symbol> to the + fields <programlisting>"[message string] [targets list] [includes + list] [excludes list]"</programlisting> (descriptions below). This is + the checked at pass/fail decision time, so there is no need to call + the procedure yourself, unless you wish to know if it gets + triggered. After a pass/fail, the variable is reset, so it doesn't + effect other tests. It returns <emphasis>1</emphasis> if the + conditional is true, or <emphasis>0</emphasis> if the conditional is + false.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>check_conditional_xfail</function></funcdef> + <paramdef><parameter>message</parameter> + <parameter>targets</parameter> + <parameter>includes</parameter> + <parameter>excludes</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>message</parameter></term> + <listitem><para>This is the message to print with the normal test + result.</para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>targets</parameter></term> + <listitem><para>This is a string with the list targets to activate + this conditional on.</para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>includes</parameter></term> + <listitem><para>This is a list of sets of options to search for in + the compiler options to activate this conditional. If any set of + the options matches, then this conditional is + true.</para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>excludes</parameter></term> + <listitem><para>This is a list of sets of options to search for in + the compiler options to activate this conditional. If any set of + the options matches, (regardless of whether any of the include sets + match) then this conditional is de-activated.</para></listitem> + </varlistentry> + </variablelist> + + <example> + <title>Specifying the conditional xfail data</title> + + <programlisting> + set compiler_conditional_xfail_data { \ + "I sure wish I knew why this was hosed" \ + "sparc*-sun*-* *-pc-*-*" \ + {"-Wall -v" "-O3"} \ + {"-O1" "-Map"} \ + } + </programlisting> + + </example> + + <para>What this does is it matches only for these two targets if + "-Wall -v" or "-O3" is set, but neither "-O1" or "-Map" is set. For + a set to match, the options specified are searched for independantly + of each other, so a "-Wall -v" matches either "-Wall -v" or "-v + -Wall". A space seperates the options in the string. Glob-style + regular expressions are also permitted.</para> + + </sect3> + + <sect3 id=clearxfail xreflabel="clear_xfail procedure"> + <title>Clear_xfail Procedure</title> + + <para>Cancel an expected failure (previously declared with + <command>setup_xfail</command>) for a particular set of + configurations. The <parameter>config</parameter> argument is a list + of configuration target names. It is only necessary to call + <command>clear_xfail</command> if a test case ends without calling + either <command>pass</command> or <command>fail</command>, after + calling <command>setup_xfail</command>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>clear_xfail</function></funcdef> + <paramdef><parameter>config</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>config</parameter></term> + <listitem><para>The configuration triplets to + clear.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=verbose xreflabel="verbose procedure"> + <title>Verbose Procedure</title> + + <para>Test cases can use this function to issue helpful messages + depending on the number of <option>--verbose</option> options on the + runtest command line. It prints string if the value of the variable + <symbol>verbose</symbol> is higher than or equal to the optional + number. The default value for number is <emphasis>1</emphasis>. Use + the optional <option>-log</option> argument to cause string to always + be added to the log file, even if it won't be printed. Use the + optional <option>-n</option> argument to print string without a + trailing newline. Use the optional <option>--</option> argument if + string begins with "-".</para> + + <funcsynopsis role="tcl"> + <funcdef><function>verbose</function></funcdef> + <paramdef><parameter>-log</parameter> + <parameter>-n</parameter> + <parameter>-r</parameter> + <parameter>string</parameter> + <parameter>number</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>-log</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>-n</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>--</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>number</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=loadlib xreflabel="load_lib procedure"> + <title>Load_lib Procedure</title> + + <para>Loads a DejaGnu library file by searching a fixed path built + into DejaGnu. If DejaGnu has been installed, it looks in a path + starting with the installed library directory. If you are running + DejaGnu directly from a source directory, without first running + <command>make install</command>, this path defaults to the current + directory. In either case, it then looks in the current directory + for a directory called <filename>lib</filename>. If there are + duplicate definitions, the last one loaded takes precedence over the + earlier ones.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>load_lib</function></funcdef> + <paramdef><parameter>filespec</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>filespec</parameter></term> + <listitem><para>The name of the DejaGnu library file to + load.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + </sect2> + + <sect2 id=remoteprocs> + <title>Procedures For Remote Communication</title> + + <para><filename>lib/remote.exp</filename> defines these + functions, for establishing and managing communications. Each + of these procedures tries to establish the connection up to + three times before returning. Warnings (if retries will + continue) or errors (if the attempt is abandoned) report on + communication failures. The result for any of these + procedures is either <emphasis>-1</emphasis>, when the + connection cannot be established, or the spawn ID returned by + the <productname>Expect</productname> command + <command>spawn</command>.</para> + + <para>It use the value of the <symbol>connect</symbol> field + in the <symbol>target_info</symbol> array (was + <symbol>connectmode</symbol> as the type of connection to + make. Current supported connection types are tip, kermit, + telnet, rsh, rlogin, and netdata. If the <option>--reboot</option> + option was used on the runtest command line, then the target + is rebooted before the connection is made.</para> + + <sect3 id=callremote xreflabel="call_remote procedure"> + <title>Call_remote Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>call_remote</function></funcdef> + <paramdef><parameter>type</parameter> + <parameter>proc</parameter> + <parameter>dest</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>proc</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=checkforboardstatus xreflabel="check_for_board_status + procedure"> + <title>Check_for_board_status Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>check_for_board_status</function></funcdef> + <paramdef><parameter>variable</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>variable</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=fileonbuild xreflabel="file_on_build procedure"> + <title>File_on_build Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>file_on_build</function></funcdef> + <paramdef><parameter>op</parameter> + <parameter>file</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>op</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>file</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=fileonhost xreflabel="file_on_host procedure"> + <title>File_on_host Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>file_on_host</function></funcdef> + <paramdef><parameter>op</parameter> + <parameter>file</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>op</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>file</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=localexec xreflabel="local_exec procedure"> + <title>Local_exec Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>local_exec</function></funcdef> + <paramdef><parameter>commandline</parameter> + <parameter>inp</parameter> + <parameter>outp</parameter> + <parameter>timeout</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>inp</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>outp</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>timeout</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remotebinary xreflabel="remote_binary procedure"> + <title>Remote_binary Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_binary</function></funcdef> + <paramdef><parameter>host</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>host</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoteclose xreflabel="remote_close procedure"> + <title>Remote_close Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_close</function></funcdef> + <paramdef><parameter>shellid</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>shellid</parameter></term> + <listitem><para>This is the value returned by a call + to <function>remote_open</function>. This closes the + connection to the target so resources can be used by + others. This parameter can be left off if the + <symbol>fileid</symbol> field in the + <symbol>target_info</symbol> array is set.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remotedownload xreflabel="remote_download procedure"> + <title>Remote_download Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_download</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>file</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>file</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoteexec xreflabel="remote_exec procedure"> + <title>Remote_exec Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_exec</function></funcdef> + <paramdef><parameter>hostname</parameter> + <parameter>program</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>hostname</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>program</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoteexpect xreflabel="remote_expect procedure"> + <title>Remote_expect Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_expect</function></funcdef> + <paramdef><parameter>board</parameter> + <parameter>timeout</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>board</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>timeout</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remotefile xreflabel="remote_file procedure"> + <title>Remote_file Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_file</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>args</parameter</paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoteld xreflabel="remote_ld procedure"> + <title>Remote_ld Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_ld</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>prog</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>prog</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoteload xreflabel="remote_load procedure"> + <title>Remote_load Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_load</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>prog</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>prog</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoteopen xreflabel="remote_open procedure"> + <title>Remote_open Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_open</function></funcdef> + <paramdef><parameter>type</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>type</parameter></term> + <listitem><para>This is passed <option>host</option> or + <option>target</option>. Host or target refers to + whether it is a connection to a remote target, or a + remote host. This opens the connection to the desired + target or host using the default values in the + configuration system. It returns that + <symbol>spawn_id</symbol> of the process that manages + the connection. This value can be used in + <productname>Expect</productname> or + <command>exp_send</command> statements, or passed to + other procedures that need the connection process's + id. This also sets the <symbol>fileid</symbol> field in + the <symbol>target_info</symbol> array.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remotepopconn xreflabel="remote_pop_conn procedure"> + <title>Remote_pop_conn Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_pop_conn</function></funcdef> + <paramdef><parameter>host</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>host</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remotepushconn xreflabel="remote_push_conn procedure"> + <title>Remote_push_conn Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_push_conn</function></funcdef> + <paramdef><parameter>host</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>host</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoterawbinary xreflabel="remote_raw_binary procedure"> + <title>Remote_raw_binary Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_raw_binary</function></funcdef> + <paramdef><parameter>host</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>host</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoterawclose xreflabel="remote_raw_close procedure"> + <title>Remote_raw_close Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_raw_close</function></funcdef> + <paramdef><parameter>host</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>host</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoterawfile xreflabel="remote_raw_file procedure"> + <title>Remote_raw_file Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_raw_file</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoterawld xreflabel="remote_raw_ld procedure"> + <title>remote_raw_ld Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_raw_ld</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>prog</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>prog</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoterawload xreflabel="remote_raw_load procedure"> + <title>Remote_raw_load Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_raw_load</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>prog</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>prog</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoterawopen xreflabel="remote_raw_open procedure"> + <title>Remote_raw_open Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_raw_open</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoterawsend xreflabel="remote_raw_send procedure"> + <title>Remote_raw_send Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_raw_send</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>string</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoterawspawn xreflabel="remote_raw_spawn procedure"> + <title>Remote_raw_spawn Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_raw_spawn</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>commandline</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>commandline</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoterawtransmit xreflabel="remote_raw_transmit + procedure"> + <title>Remote_raw_transmit Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_raw_transmit</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>file</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>file</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoterawwait xreflabel="remote_raw_wait procedure"> + <title>Remote_raw_wait Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_raw_wait</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>timeout</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>timeout</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remotereboot xreflabel="remote_reboot procedure"> + <title>Remote_reboot Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_reboot</function></funcdef> + <paramdef><parameter>host</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>host</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remotesend xreflabel="remote_send procedure"> + <title>Remote_send Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_send</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>string</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remotespawn xreflabel="remote_spawn procedure"> + <title>Remote_spawn Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_spawn</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>commandline</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>commandline</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoteswapconn xreflabel="remote_swap_conn procedure"> + <title>Remote_swap_conn Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_swap_conn</function></funcdef> + <paramdef><parameter>host</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter></parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remotetransmit xreflabel="remote_transmit procedure"> + <title>Remote_transmit Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_transmit</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>file</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>file</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remoteupload xreflabel="remote_upload procedure"> + <title>Remote_upload Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_upload</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>srcfile</parameter> + <parameter>arg</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>srcfile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>arg</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=remotewait xreflabel="remote_wait procedure"> + <title>Remote_wait Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>remote_wait</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>timeout</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>timeout</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=standardclose xreflabel="standard_close procedure"> + <title>Standard_close Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>standard_close</function></funcdef> + <paramdef><parameter>host</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>host</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=standarddownload xreflabel="standard_download procedure"> + <title>Standard_download Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>standard_download</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>file</parameter> + <parameter>destfile</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>file</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>destfile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=standardexec xreflabel="standard_exec procedure"> + <title>Standard_exec Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>standard_exec</function></funcdef> + <paramdef><parameter>hostname</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>hostname</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=standardfile xreflabel="standard_file procedure"> + <title>Standard_file Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>standard_file</function></funcdef> + <paramdef><parameter>dest</parameter + <parameter>op</parameter + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter></parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=standardload xreflabel="standard_load procedure"> + <title>Standard_load Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>standard_load</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>prog</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>prog</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=standardreboot xreflabel="standard_reboot procedure"> + <title>Standard_reboot Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>standard_reboot</function></funcdef> + <paramdef><parameter>host</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>host</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=standardsend xreflabel="standard_send procedure"> + <title>Standard_send Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>standard_send</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>string</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=standardspawn xreflabel="standard_spawn procedure"> + <title>Standard_spawn Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>standard_spawn</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>commandline</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>commndline</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=standardtransmit xreflabel="standard_transmit procedure"> + <title>Standard_transmit Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>standard_transmit</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>file</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>file</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=standardupload xreflabel="standard_upload procedure"> + <title>Standard_upload Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>standard_upload</function></funcdef> + <paramdef><parameter>dest srcfile destfile</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>srcfile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>destfile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=standardwait xreflabel="standard_wait procedure"> + <title>Standard_wait Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>standard_wait</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>timeout</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>timeout</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=unixcleanfilename xreflabel="unix_clean_filename + procedure"> + <title>Unix_clean_filename Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>unix_clean_filename</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>file</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>file</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + +<!-- FIXME: this doesn't seem to exist anymore + <sect3 id=exitremoteshell xreflabel="exit_remote_shell procedure"> + <title>exit_remote_shell Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>exit_remote_shell</function></funcdef> + <paramdef><parameter>spawnid</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>spawnid</parameter></term> + <listitem><para>Exits a remote process started by any + of the connection procedures. <symbol>spawnid</symbol> + is the result of the connection procedure that started + the remote process.</para></listitem> + </varlistentry> + </variablelist> + </sect3> +--> + + </sect2> + + <sect2 id=connprocs xreflabel="connprocs"> + <title>Procedures For Using Utilities to Connect</title> + + <para>telnet, rsh, tip, kermit</para> + + <sect3 id=telnet xreflabel="telnet procedure"> + <title>telnet Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>telnet</function></funcdef> + <paramdef><parameter>hostname</parameter> + <parameter>port</parameter></paramdef> + </funcsynopsis> + <funcsynopsis role="tcl"> + <funcdef><function>rlogin</function></funcdef> + <paramdef><parameter>hostname</parameter></paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=rsh xreflabel="rsh procedure"> + <title>rsh Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>rsh</function></funcdef> + <paramdef><parameter>hostname</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>hostname</parameter></term> + <listitem><para>This refers to the IP address or name + (for example, an entry in + <filename>/etc/hosts</filename>) for this target. The + procedure names reflect the Unix utility used to + establish a connection. The optional + <parameter>port</parameter> is used to specify the IP + port number. The value of the + <parameter>netport</parameter> field in the + <symbol>target_info</symbol> array is used. (was + <symbol>$netport</symbol>) This value has two parts, + the hostname and the port number, seperated by a + <emphasis>:</emphasis>. If host or target is used in + the <symbol>hostname</symbol> field, than the + config array is used for all information.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=tip xreflabel="tip procedure"> + <title>Tip Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>tip</function></funcdef> + <paramdef><parameter>port</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>port</parameter></term> + <listitem><para>Connect using the Unix utility + <command>tip</command>. <parameter>Port</parameter>must + be a name from the <productname>tip</productname> + configuration file + <filename>/etc/remote</filename>. Often, this is called + <symbol>hardwire</symbol>, or something like + <symbol>ttya</symbol>. This file holds all the + configuration data for the serial port. The value of + the <symbol>serial</symbol> field in the + <symbol>target_info</symbol> array is used. (was + <symbol>$serialport</symbol>) If <option>host</option> + or <option>target</option> is used in the + <parameter>port</parameter> field, than the config + array is used for all information. the + config array is used for all information.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=kermit xreflabel="kermit procedure"> + <title>Kermit Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>kermit</function></funcdef> + <paramdef><parameter>port</parameter> + <parameter>bps</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>port</parameter></term> + <listitem><para>Connect using the program + <command>kermit</command>. <parameter>Port</parameter> + is the device name, + e.g. <filename>/dev/ttyb</filename>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>bps</parameter></term> + <listitem><para><parameter>bps</parameter> is the line + speed to use (in its per second) for the + connection. The value of the <symbol>serial</symbol> + field in the <symbol>target_info</symbol> array is + used. (was <symbol>$serialport</symbol>) If + <option>host</option> or <option>target</option> is + used in the <parameter>port</parameter> field, than the + config array is used for all information. the + config array is used for all information.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=kermitopen xreflabel="kermit_open procedure"> + <title>kermit_open Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>kermit_open</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=kermitcommand xreflabel="kermit_command procedure"> + <title>Kermit_command Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>kermit_command</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=kermitsend xreflabel="kermit_send procedure"> + <title>Kermit_send Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>kermit_send</function></funcdef> + <paramdef><parameter>dest string args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=kermittransmit xreflabel="kermit_transmit procedure"> + <title>Kermit_transmit Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>kermit_transmit</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>file</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>file</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=telnetopen xreflabel="telnet_open procedure"> + <title>Telnet_open Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>telnet_open</function></funcdef> + <paramdef><parameter>hostname</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>hostname</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=telnetbinary xreflabel="telnet_binary procedure"> + <title>Telnet_binary Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>telnet_binary</function></funcdef> + <paramdef><parameter>hostname</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>hostname</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=telnettransmit xreflabel="telnet_transmit procedure"> + <title>Telnet_transmit Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>telnet_transmit</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>file</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>file</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=tipopen xreflabel="tip_open procedure"> + <title>Tip_open Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>tip_open</function></funcdef> + <paramdef><parameter>hostname</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>hostname</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=rloginopen xreflabel="rlogin_open procedure"> + <title>Rlogin_open Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>rlogin_open</function></funcdef> + <paramdef><parameter>arg</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>arg</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=rloginspawn xreflabel="rlogin_spawn procedure"> + <title>Rlogin_spawn Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>rlogin_spawn</function></funcdef> + <paramdef><parameter>dest</parameter> + <parameter>cmdline</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>dest</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cmdline</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=rshopen xreflabel="rsh_open procedure"> + <title>Rsh_open Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>rsh_open</function></funcdef> + <paramdef><parameter>hostname</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>hostname</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=rshdownload xreflabel="rsh_download procedure"> + <title>Rsh_download Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>rsh_download</function></funcdef> + <paramdef><parameter>desthost</parameter> + <parameter>srcfile</parameter> + <parameter>destfile</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>desthost</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>srcfile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>destfile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=rshupload xreflabel="rsh_upload procedure"> + <title>Rsh_upload Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>rsh_upload</function></funcdef> + <paramdef><parameter>desthost</parameter> + <parameter>srcfile</parameter> + <parameter>destfile</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>desthost</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>srcfile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>destfile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=rshexec xreflabel="rsh_exec procedure"> + <title>Rsh_exec Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>rsh_exec</function></funcdef> + <paramdef><parameter>boardname</parameter> + <parameter>cmd</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>boardname</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cmd</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=ftpopen xreflabel="ftp_open procedure"> + <title>Ftp_open Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>ftp_open</function></funcdef> + <paramdef><parameter>host</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>host</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=ftpupload xreflabel="ftp_upload procedure"> + <title>Ftp_upload Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>ftp_upload</function></funcdef> + <paramdef><parameter>host</parameter> + <parameter>remotefile</parameter> + <parameter>localfile</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>host</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>remotefile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>localfile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=ftpdownload xreflabel="ftp_download procedure"> + <title>Ftp_download Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>ftp_download</function></funcdef> + <paramdef><parameter>host</parameter> + <parameter>localfile</parameter> + <parameter>remotefile</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>host</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>localfile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>remotefile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=ftpclose xreflabel="ftp_close procedure"> + <title>Ftp_close Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>ftp_close</function></funcdef> + <paramdef><parameter>host</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>host</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=tipdownload xreflabel="tip_download procedure"> + <title>Tip_download Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>tip_download</function></funcdef> + <paramdef><parameter>spawnid</parameter> + <parameter>file</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>spawnid</parameter></term> + <listitem><para>Download <option>file</option> to the + process <symbol>spawnid</symbol> (the value returned + when the connection was established), using the + <command>~put</command> command under + <productname>tip</productname>. Most often used for + single board computers that require downloading + programs in ASCII S-records. Returns + <emphasis>1</emphasis> if an error occurs, + <emphasis>0</emphasis> otherwise.</para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>file</parameter></term> + <listitem><para>This is the filename to + downlaod.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + </sect2> + + <sect2 id=targetprocs> + <title>Procedures For Target Boards</title> + + <para></para> + + <sect3 id=defaultlink xreflabel="default_link procedure"> + <title>Default_link Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>default_link</function></funcdef> + <paramdef><parameter>board</parameter> + <parameter>objects</parameter> + <parameter>destfile</parameter> + <parameter>flags</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>board</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>objects</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>destfile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=defaulttargetassemble xreflabel="default_target_assemble + procedure"> + <title>Default_target_assemble Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>default_target_assemble</function></funcdef> + <paramdef><parameter>source</parameter> + <parameter>destfile</parameter> + <parameter>flags</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>source</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>destfile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=defaulttargetcompile xreflabel="default_target_compile + procedure"> + <title>default_target_compile Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>default_target_compile</function></funcdef> + <paramdef><parameter>source</parameter> + <parameter>destfile</parameter> + <parameter>type</parameter> + <parameter>options</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>source</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>destfile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>type</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>options</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=popconfig xreflabel="pop_config procedure"> + <title>Pop_config Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>pop_config</function></funcdef> + <paramdef><parameter>type</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>type</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=prunewarnings xreflabel="prune_warnings procedure"> + <title>Prune_warnings Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>prune_warnings</function></funcdef> + <paramdef><parameter>text</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>text</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=pushbuild xreflabel="push_build procedure"> + <title>Push_build Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>push_build</function></funcdef> + <paramdef><parameter>name</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>name</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=pushconfig xreflabel="push_config procedure"> + <title>push_config Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>push_config</function></funcdef> + <paramdef><parameter>type</parameter> + <parameter>name</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>type</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>name</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=reboottarget xreflabel="reboot_target procedure"> + <title>Reboot_target Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>reboot_target</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=targetassemble xreflabel="target_assemble procedure"> + <title>Target_assemble Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>target_assemble</function></funcdef> + <paramdef><parameter>source destfile flags</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>source</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>destfile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=targetcompile xreflabel="target_compile procedure"> + <title>Target_compile Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>target_compile</function></funcdef> + <paramdef><parameter>source</parameter> + <parameter>destfile</parameter> + <parameter>type</parameter> + <parameter>options</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>source</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>destfile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>type</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>options</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + </sect2> + + <sect2 id=targetdb xreflabel="target database library file "> + <title>Target Database Procedures</title> + + <sect3 id=boardinfo xreflabel="board_info procedure"> + <title>Board_info Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>board_info</function></funcdef> + <paramdef><parameter>machine</parameter> + <parameter>op</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>machine</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>op</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=hostinfo xreflabel="host_info procedure"> + <title>Host_info Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>host_info</function></funcdef> + <paramdef><parameter>op</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>op</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=setboardinfo xreflabel="set_board_info procedure"> + <title>Set_board_info Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>set_board_info</function></funcdef> + <paramdef><parameter>entry</parameter> + <parameter>value</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>entry</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=setcurrtargetinfo xreflabel="set_currtarget_info + procedure"> + <title>Set_currtarget_info Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>set_currtarget_info</function></funcdef> + <paramdef><parameter>entry</parameter> + <parameter>value</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>entry</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=targetinfo xreflabel="target_info procedure"> + <title>Target_info Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>target_info</function></funcdef> + <paramdef><parameter>op</parameter> + <parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>op</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=unsetboardinfo xreflabel="unset_board_info procedure"> + <title>Unset_board_info Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>unset_board_info</function></funcdef> + <paramdef><parameter>entry</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>entry</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=unsetcurrtargetinfo xreflabel="unset_currtarget_info + procedure"> + <title>Unset_currtarget_info Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>unset_currtarget_info</function></funcdef> + <paramdef><parameter>entry</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>entry</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=pushtarget xreflabel="push_target procedure"> + <title>Push_target Procedure</title> + + <para>This makes the target named <emphasis>name</emphasis> be the + current target connection. The value of <emphasis>name</emphasis> is + an index into the <symbol>target_info</symbol> array and is set in + the global config file.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>push_target</function></funcdef> + <paramdef><parameter>name</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>name</parameter></term> + <listitem><para>The name of the target to make current + connection.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=poptarget xreflabel="poptarget procedure"> + <title>Pop_target Procedure</title> + + <para>This unsets the current target connection.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>pop_target</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=listtargets xreflabel="list_targets procedure"> + <title>List_targets Procedure</title> + + <para>This lists all the supported targets for this + architecture.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>list_targets</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=pushhost xreflabel="push_host procedure"> + <title>Push_host Procedure</title> + + <para>This makes the host named <emphasis>name</emphasis> be the + current remote host connection. The value of + <emphasis>name</emphasis> is an index into the + <symbol>target_info</symbol> array and is set in the global config + file.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>push_host</function></funcdef> + <paramdef><parameter>name</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>name</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=pophost xreflabel="pop_host procedure"> + <title>Pop_host Procedure</title> + + <para>This unsets the current host connection.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>pop_host</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=compile xreflabel="compile procedure"> + <title>Compile Procedure</title> + + <para>This invokes the compiler as set by CC to compile the + file <filename>file</filename>. The default options for many cross + compilation targets are <emphasis>guessed</emphasis> by DejaGnu, and + these options can be added to by passing in more parameters as + arguments to <command>compile</command>. Optionally, this will also + use the value of the <emphasis>cflags</emphasis> field in the target + config array. If the host is not the same as the build machines, then + then compiler is run on the remote host using + <command>execute_anywhere</command>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>compile</function></funcdef> + <paramdef><parameter>file</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>file</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=archive xreflabel="archive procedure"> + <title>Archive Procedure</title> + + <para>This produces an archive file. Any parameters passed to + <command>archive</command> are used in addition to the default + flags. Optionally, this will also use the value of the + <emphasis>arflags</emphasis> field in the target config array. If the + host is not the same as the build machines, then then archiver is run + on the remote host using <command>execute_anywhere</command>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>archive</function></funcdef> + <paramdef><parameter>file</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>file</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=ranlib xreflabel="ranlib procedure"> + <title>Ranlib Procedure</title> + + <para>This generates an index for the archive file for systems that + aren't POSIX yet. Any parameters passed to <command>ranlib</command> + are used in for the flags.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>ranlib</function></funcdef> + <paramdef><parameter>file</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>file</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=executeanywhere xreflabel="execute_anywhere procedure"> + <title>Execute_anywhere Procedure</title> + + <para>This executes the <emphasis>cmdline</emphasis> on the proper + host. This should be used as a replacement for the Tcl command + <command>exec</command> as this version utilizes the target config + info to execute this command on the build machine or a remote + host. All config information for the remote host must be setup to + have this command work. If this is a canadian cross, (where we test a + cross compiler that runs on a different host then where DejaGnu is + running) then a connection is made to the remote host and the command + is executed there. It returns either REMOTERROR (for an error) or the + output produced when the command was executed. This is used for + running the tool to be tested, not a test case.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>execute_anywhere</function></funcdef> + <paramdef><parameter>cmdline</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>cmdline</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect2 id=platformprocs xreflabel="platform dependant procedures"> + <title>Platform Dependant Procedures</title> + + <para>Each combination of target and tool requires some + target-dependent procedures. The names of these procedures have + a common form: the tool name, followed by an underbar + <emphasis>_</emphasis>, and finally a suffix describing the + procedure's purpose. For example, a procedure to extract the + version from <productname>GDB</productname> is called + <symbol>gdb_version</symbol>.</para> + + <para><command>runtest</command> itself calls only two of these + procedures, <symbol>${tool}_exit</symbol> and + <symbol>${tool}_version</symbol>; these procedures use no + arguments.</para> + + <para>The other two procedures, <symbol>${tool}_start</symbol> + and <symbol>${tool}_load</symbol>}, are only called by the test + suites themselves (or by testsuite-specific initialization + code); they may take arguments or not, depending on the + conventions used within each test suite.</para> + + <para>The usual convention for return codes from any of these + procedures (although it is not required by + <command>runtest</command>) is to return <emphasis>0</emphasis> + if the procedure succeeded, <emphasis>1</emphasis> if it failed, + and <emphasis>-1</emphasis> if there was a communication error.</para> + + <sect3 id=toolstart xreflabel="${tool}_start procedure"> + <title>${tool}_start Procedure</title> + + <para>Starts a particular tool. For an interactive tool, + <function>${tool}_start</function> starts and initializes the + tool, leaving the tool up and running for the test cases; an + example is <function>gdb_start</function>, the start function + for GDB. For a batch oriented tool, + <function>${tool}_start</function> is optional; the recommended + convention is to let <function>${tool}_start</function> run the + tool, leaving the output in a variable called + <function>comp_output</function>. Test scripts can then analyze + <function>$comp_output</function> to determine the test results. + An example of this second kind of start function is + <function>gcc_start</function>, the start function for GCC.</para> + + <para>DejaGnu itself does not call + <function>${tool}_start</function>. The initialization + module <function>${tool}_init.exp</function> must call + <function>${tool}_start</function> for interactive tools; + for batch-oriented tools, each individual test script calls + <function>${tool}_start</function> (or makes other + arrangements to run the tool).</para> + + <funcsynopsis role="tcl"> + <funcdef><function>${tool}_start</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=toolload xreflabel="${tool}_load procedure"> + <title>${tool}_load Procedure</title> + + <para>Loads something into a tool. For an interactive tool, + this conditions the tool for a particular test case; for + example, <function>gdb_load</function> loads a new + executable file into the debugger. For batch oriented tools, + <function>${tool}_load</function> may do nothing---though, + for example, the GCC support uses + <function>gcc_load</function> to load and run a binary on + the target environment. Conventionally, + <function>${tool}_load</function> leaves the output of any + program it runs in a variable called + <symbol>$exec_output</symbol>. Writing + <function>${tool}_load</function> can be the most complex + part of extending DejaGnu to a new tool or a new target, if + it requires much communication coding or file + downloading. Test scripts call + <function>${tool}_load</function>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>${tool}_load</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=toolexit xreflabel="${tool}_exit procedure"> + <title>${tool}_exit Procedure</title> + + <para>Cleans up (if necessary) before DejaGnu exits. For + interactive tools, this usually ends the interactive + session. You can also use <function>${tool}_exit</function> + to remove any temporary files left over from the + tests. <command>runtest</command> calls + <function>${tool}_exit</function>.<para> + + <funcsynopsis role="tcl"> + <funcdef><function>${tool}_exit</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=toolversion xreflabel="${tool}_version procedure"> + <title>${tool}_version Procedure</title> + + <para>Prints the version label and number for + <symbol>${tool}</symbol>. This is called by the DejaGnu + procedure that prints the final summary report. The output + should consist of the full path name used for the tested + tool, and its version number.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>${tool}_version</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + </sect3> + + </sect2> + + <sect2 id=utilprocs> + <title>Utility Procedures</title> + + <sect3 id=getdirs xreflabel="getdirs procedure"> + <title>Getdirs Procedure</title> + + <para>Returns a list of all the directories in the single + directory a single directory that match an optional + pattern. </para> + + <funcsynopsis role="tcl"> + <funcdef><function>getdirs</function></funcdef> + <paramdef><parameter>rootdir</parameter> + <parameter>pattern</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>pattern</parameter></term> + <listitem><para>If you do not specify + <parameter>pattern</parameter>, + <function>Getdirs</function> assumes a default pattern of + <emphasis>*</emphasis>. You may use the common shell + wildcard characters in the pattern. If no directories + match the pattern, then a NULL string is + returned</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=find xreflabel="find procedure"> + <title>Find Procedure</title> + + <para>Search for files whose names match <emphasis>pattern</emphasis> + (using shell wildcard characters for filename expansion). Search + subdirectories recursively, starting at + <emphasis>rootdir</emphasis>. The result is the list of files whose + names match; if no files match, the result is empty. Filenames in the + result include all intervening subdirectory names. If no files match + the pattern, then a NULL string is returned.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>find</function></funcdef> + <paramdef><parameter>rootdir</parameter> + <parameter>pattern</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>rootdir</parameter></term> + <listitem><para>The top level directory to search the search + from.</para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>pattern</parameter></term> + <listitem><para>A csh "glob" style regular expression reprsenting + the files to find.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=which xreflabel="which procedure"> + <title>Which Procedure</title> + + <para>Searches the execution path for an executable file + <emphasis>binary</emphasis>, like the the BSD <command>which</command> + utility. This procedure uses the shell environment variable + <emphasis>PATH</emphasis>. It returns <emphasis>0</emphasis> if the + binary is not in the path, or if there is no <emphasis>PATH</emphasis> + environment variable. If <command>binary</command> is in the path, it + returns the full path to <command>binary</command>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>which</function></funcdef> + <paramdef><parameter>file</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>binary</parameter></term> + <listitem><para>The executable program or shell script to look + for.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=grep xreflabel="grep procedure"> + <title>Grep Procedure</title> + + <para>Search the file called <filename>filename</filename> (a fully + specified path) for lines that contain a match for regular expression + <emphasis>regexp</emphasis>. The result is a list of all the lines that + match. If no lines match, the result is an empty string. Specify + <emphasis>regexp</emphasis> using the standard regular expression style + used by the Unix utility program grep.</para> + + <para>Use the optional third argument <emphasis>line</emphasis> to + start lines in the result with the line number in + <filename>filename</filename>. (This argument is simply an option + flag; type it just as shown <option>--line</option>.) + + <funcsynopsis role="tcl"> + <funcdef><function>grep</function></funcdef> + <paramdef><parameter>filename</parameter> + <parameter>regexp</parameter> + <parameter>--line</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>filename</parameter></term> + <listitem><para>The file to search.</para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>regexp</parameter></term> + <listitem><para>The Unix style regular expression (as used by the + <command>grep</command> Unix utility) to search + for.</para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>--line</parameter></term> + <listitem><para>Prefix the line number to each line where the + regexp matches.</para></listitem> + </varlistentry> + </variablelist> + + </sect3> + <sect3 id=prune xreflabel="prune procedure"> + <title>Prune Procedure</title> + + <para>Remove elements of the Tcl list <emphasis>list</emphasis>. + Elements are fields delimited by spaces. The result is a copy of + list, without any elements that match <emphasis>pattern</emphasis>. + You can use the common shell wildcard characters to specify the + pattern.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>prune</function></funcdef> + <paramdef><parameter>list</parameter> + <parameter>pattern</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>list</parameter></term> + <listitem><para>A Tcl list containing the original data. Commonly + this is the output of a batch executed command, like running a + compiler.</para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>pattern</parameter></term> + <listitem><para>The csh shell "glob" style pattern to search + for.</para></listitem> + </varlistentry> + </variablelist> + + </sect3> + + <sect3 id=slay xreflabel="slay procedure"> + <title>Slay Procedure</title> + + <para>This look in the process table for <emphasis>name</emphasis> + and send it a unix SIGINT, killing the process. This will only work + under NT if you have Cygwin or another Unix system for NT + installed.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>slay</function></funcdef> + <paramdef><parameter>name</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>name</parameter></term> + <listitem><para>The name of the program to kill.</para></listitem> + </varlistentry> + </variablelist> + + </sect3> + + <sect3 id=absolute xreflabel="absolute procedure"> + <title>Absolute Procedure</title> + + <para>This procedure takes the relative <emphasis>path</emphasis>, + and converts it to an absolute path.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>absolute</function></funcdef> + <paramdef><parameter>path</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>path</parameter></term> + <listitem><para>The path to convert.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=psource xreflabel="psource procedure"> + <title>Psource Procedure</title> + + <para>This sources the file <emphasis>filename</emphasis>, and traps + all errors. It also ignores all extraneous output. If there was an + error it returns a <emphasis>1</emphasis>, otherwise it returns a + <emphasis>0</emphasis>. + + <funcsynopsis role="tcl"> + <funcdef><function>psource</function></funcdef> + <paramdef><parameter>file</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>filename</parameter></term> + <listitem><para>The filename to Tcl script to + source.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=runtestfilep xreflabel="runtest_file_p procedure"> + <title>Runtest_file_p Procedure</title> + + <para>Search <emphasis>runtest</emphasis>s for + <emphasis>testcase</emphasis> and return <emphasis>1</emphasis> if + found, <emphasis>0</emphasis> if not. <emphasis>runtests</emphasis> + is a list of two elements. The first is the pathname of the + testsuite expect script running. The second is a copy of what was on + the right side of the <emphasis>=</emphasis> if + <programlisting>foo.exp="..."</programlisting>" was specified, or + an empty string if no such argument is present. This is used by tools + like compilers where each testcase is a file.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>runtest_file_p</function></funcdef> + <paramdef><parameter>runtests</parameter> + <parameter>testcase</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>runtests</parameter></term> + <listitem><para>The pathname of the testsuite expect script + running</para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>testcase</parameter></term> + <listitem><para>The test case filename.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=diff xreflabel="diff procedure"> + <title>Diff Procedure</title> + + <para>Compares the two files and returns a <emphasis>1</emphasis> if + they match, or a <emphasis>0</emphasis> if they don't. If + <symbol>verbose</symbol> is set, then it'll print the differences to + the screen.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>diff</function></funcdef> + <paramdef><parameter>file_1</parameter> + <parameter>file_2</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>file_1</parameter></term> + <listitem><para>The first file to compare.</para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>file_2</parameter></term> + <listitem><para>The second file to compare.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=setenv xreflabel="setenv procedure"> + <title>Setenv Procedure</title> + + <para>Sets the environment variable <emphasis>var</emphasis> to the + value <emphasis>val</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>setenv</function></funcdef> + <paramdef><parameter>var</parameter> + <parameter>val</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>var</parameter></term> + <listitem><para>The environment variable to set.</para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>val</parameter></term> + <listitem><para>The value to set the variable to.</para></listitem> + </varlistentry> + </variablelist> + + <sect3 id=unsetenv xreflabel="unsetenv procedure"> + <title>unsetenv Procedure</title> + + <para>Unsets the environment variable + <emphasis>var</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>unsetenv</function></funcdef> + <paramdef><parameter>var</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>var</parameter></term> + <listitem><para>The environment variable to + unset.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=getenv xreflabel="getenv procedure"> + <title>Getenv Procedure</title> + + <para>Returns the value of <emphasis>var</emphasis> in the + environment if it exists, otherwise it returns NULL. + + <funcsynopsis role="tcl"> + <funcdef><function>getenv</function></funcdef> + <paramdef><parameter>var</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>var</parameter></term> + <listitem><para>The environment variable to get the value + of.</para></listitem> + </varlistentry> + </variablelist> + + <sect3 id=prunesystemcrud xreflabel="prune_system_crud procedure"> + <title>Prune_system_crud Procedure</title> + + <para>For system <emphasis>system</emphasis>, delete text the host or + target operating system might issue that will interfere with pattern + matching of program output in <emphasis>text</emphasis>. An example + is the message that is printed if a shared library is out of + date.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>prune_system_crud</function></funcdef> + <paramdef><parameter>system</parameter> + <parameter>test</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>system</parameter></term> + <listitem><para>The system error messages to look for to screen out + .</para></listitem> + </varlistentry> + <varlistentry> + <term><parameter>text</parameter></term> + <listitem><para>The Tcl variable containing the + text.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + </sect2> + + <sect2 id=libgloss xreflabel="Libgloss"> + <title>Libgloss, A Free BSP</title> + + <para>Libgloss is a free <firstterm>BSP</firstterm> (Board Support + Package) commonly used with GCC and G++ to produce a fully linked + executable image for an embedded systems.</para> + + <sect3 id=libglosslinkflags xreflabel="libgloss_link_flags procedure"> + <title>Libgloss_link_flags Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>libgloss_link_flags</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=libglossincludeflags xreflabel="libgloss_include_flags + procedure"> + <title>Libgloss_include_flags Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>libgloss_include_flags</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=newliblinkflags xreflabel="newlib_link_flags procedure"> + <title>Newlib_link_flags Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>newlib_link_flags</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=newlibincludeflags xreflabel="newlib_include_flags + procedure"> + <title>Newlib_include_flags Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>newlib_include_flags</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=libioincludeflags xreflabel="libio_include_flags + procedure"> + <title>Libio_include_flags Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>libio_include_flags</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=libiolinkflags xreflabel="libio_link_flags procedure"> + <title>Libio_link_flags Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>libio_link_flags</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=gxxincludeflags xreflabel="g++_include_flags procedure"> + <title>G++_include_flags Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>g++_include_flags</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=gxxlinkflags xreflabel="g++_link_flags procedure"> + <title>G++_link_flags Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>g++_link_flags</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=libstdcxxincludeflags xreflabel="libstdc++_include_flags + procedure"> + <title>Libstdc++_include_flags Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>libstdc++_include_flags</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=libstdcxxlinkflags xreflabel="libstdc++_link_flags + procedure"> + <title>Libstdc++_link_flags Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>libstdc++_link_flags</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=getmultilibs xreflabel="get_multilibs procedure"> + <title>Get_multilibs Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>get_multilibs</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=findbinutilsprog xreflabel="find_binutils_prog procedure"> + <title>Find_binutils_prog Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>find_binutils_prog</function></funcdef> + <paramdef><parameter>name</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>name</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=findgcc xreflabel="find_gcc procedure"> + <title>Find_gcc Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>find_gcc</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=findgcj xreflabel="find_gcj procedure"> + <title>Find_gcj Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>find_gcj</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=findgxx xreflabel="find_g++ procedure"> + <title>Find_g++ Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>find_g++</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=findg77 xreflabel="find_g77 procedure"> + <title>Find_g77 Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>find_g77</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=processmultiliboptions xreflabel="process_multilib_options + procedure"> + <title>Process_multilib_options Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>process_multilib_options</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=addmultiliboption xreflabel="add_multilib_option + procedure"> + <title>Add_multilib_option Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>add_multilib_option</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=findgas xreflabel="find_gas procedure"> + <title>Find_gas Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>find_gas</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=findld xreflabel="find_ld procedure"> + <title>Find_ld Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>find_ld</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + </sect3> + + <sect3 id=buildwrapper xreflabel="build_wrapper procedure"> + <title>Build_wrapper Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>build_wrapper</function></funcdef> + <paramdef><parameter>gluefile</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>gluefile</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=winsupincludeflags xreflabel="winsup_include_flags + procedure"> + <title>Winsup_include_flags Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>winsup_include_flags</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=winsuplinkflags xreflabel="winsup_link_flags procedure"> + <title>Winsup_link_flags Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>winsup_link_flags</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + </sect2> + + <sect2 id=debugprocs xreflabel="Debugging Procedures"> + <title>Procedures for debugging your Tcl code.</title> + + <para><filename>lib/debugger.exp</filename>defines these utility + procedures:</para> + + <sect3 id=dumpvars xreflabel="dumpvars procedure"> + <title>Dumpvars Procedure</title> + + <para>This takes a csh style regular expression (glob rules) and prints + the values of the global variable names that match. It is abbreviated + as <emphasis>dv</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>dumpvars</function></funcdef> + <paramdef><parameter>vars</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>vars</parameter></term> + <listitem><para>The variables to dump.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=dumplocals xreflabel="dumplocals procedure"> + <title>Dumplocals Procedure</title> + + <para>This takes a csh style regular expression (glob rules) and + prints the values of the local variable names that match. It is + abbreviated as <emphasis>dl</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>dumplocals</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=dumprocs xreflabel="dumprocs procedure"> + <title>Dumprocs Procedure</title> + + <para>This takes a csh style regular expression (glob rules) and + prints the body of all procs that match. It is abbreviated as + <emphasis>dp</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>dumprocs</function></funcdef> + <paramdef><parameter>pattern</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>pattern</parameter></term> + <listitem><para>The csh "glob" style pattern to look + for.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=dumpwatch xreflabel="dumpwatch procedure"> + <title>Dumpwatch Procedure</title> + + <para>This takes a csh style regular expression (glob rules) and + prints all the watchpoints. It is abbreviated as + <emphasis>dw</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>dumpwatch</function></funcdef> + <paramdef><parameter>pattern</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>pattern</parameter></term> + <listitem><para>The csh "glob" style pattern to look + for.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=watcharray xreflabel="watcharray procedure"> + <title>Watcharray Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>watcharray</function></funcdef> + <paramdef><parameter>element</parameter> + <parameter>type</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>type</parameter></term> + <listitem><para>The csh "glob" style pattern to look + for.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=watchvar xreflabel="watchvar procedure"> + <title>Watchvar Procedure</title> + + <para></para> + + <funcsynopsis role="tcl"> + <funcdef><function>watchvar</function></funcdef> + <paramdef><parameter>var</parameter> + <parameter>type</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter></parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=watchunset xreflabel="watchunset procedure"> + <title>Watchunset Procedure</title> + + <para>This breaks program execution when the variable + <symbol>var</symbol> is unset. It is abbreviated as + <emphasis>wu</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>watchunset</function></funcdef> + <paramdef><parameter>arg</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=watchwrite xreflabel="watchwrite procedure"> + <title>Watchwrite Procedure</title> + + <para>This breaks program execution when the variable + <symbol>var</symbol> is written. It is abbreviated as + <emphasis>ww</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>watchwrite</function></funcdef> + <paramdef><parameter>var</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>var</parameter></term> + <listitem><para>The variable to watch.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=watchread xreflabel="watchread procedure"> + <title>Watchread Procedure</title> + + <para>This breaks program execution when the variable + <symbol>var</symbol> is read. It is abbreviated as + <emphasis>wr</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>watchread</function></funcdef> + <paramdef><parameter>var</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>var</parameter></term> + <listitem><para>The variable to watch.</para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=watchdel xreflabel="watchdel procedure"> + <title>Watchdel Procedure</title> + + <para>This deletes a the watchpoint from the watch list. It is + abbreviated as <emphasis>wd</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>watchdel</function></funcdef> + <paramdef><parameter>args</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=print xreflabel="print procedure"> + <title>Print Procedure</title> + + <para>This prints the value of the variable + <parameter>var</parameter>. It is abbreviated as + <emphasis>p</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>print</function></funcdef> + <paramdef><parameter>var</parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter>var</parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id=quit xreflabel="quit procedure"> + <title>Quit Procedure</title> + + <para>This makes runtest exit. It is abbreviated as + <emphasis>q</emphasis>.</para> + + <funcsynopsis role="tcl"> + <funcdef><function>quit</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcsynopsis> + <variablelist> + <varlistentry> + <term><parameter></parameter></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </sect3> + + </sect2> + + </sect1> + + <sect1 id=filemap> + <title>File Map</title> + + <para>This is a map of the files in DejaGnu.</para> + + <itemizedlist> + <listitem><para>runtest</para></listitem> + <listitem><para>runtest.exp</para></listitem> + <listitem><para>stub-loader.c</para></listitem> + <listitem><para>testglue.c</para></listitem> + <listitem><para>config</para></listitem> + <listitem><para>baseboards</para></listitem> + <listitem><para>lib/debugger.exp</para></listitem> + <listitem><para>lib/dg.exp</para></listitem> + <listitem><para>lib/framework.exp</para></listitem> + <listitem><para>lib/ftp.exp</para></listitem> + <listitem><para>lib/kermit.exp</para></listitem> + <listitem><para>lib/libgloss.exp</para></listitem> + <listitem><para>lib/mondfe.exp</para></listitem> + <listitem><para>lib/remote.exp</para></listitem> + <listitem><para>lib/rlogin.exp</para></listitem> + <listitem><para>lib/rsh.exp</para></listitem> + <listitem><para>lib/standard.exp</para></listitem> + <listitem><para>lib/target.exp</para></listitem> + <listitem><para>lib/targetdb.exp</para></listitem> + <listitem><para>lib/telnet.exp</para></listitem> + <listitem><para>lib/tip.exp</para></listitem> + <listitem><para>lib/util-defs.exp</para></listitem> + <listitem><para>lib/utils.exp</para></listitem> + <listitem><para>lib/xsh.exp</para></listitem> + </itemizedlist> + + </sect1> + +</chapter> diff --git a/doc/runtest.1 b/doc/runtest.1 new file mode 100644 index 0000000..2c3a357 --- /dev/null +++ b/doc/runtest.1 @@ -0,0 +1,119 @@ +.TH runtest 1 "08 Dec 1998" +.SH NAME +runtest \- the DejaGnu test driver program +.SH SYNOPSIS +.B runtest +[ options ] +.SH DESCRIPTION +.I DejaGnu +is a framework for running test suites on GNU tools. It is written in +expect, which uses TCL (Tool command language). +.B runtest +is the test driver program; use it to control what tests to run, +and variations on how to run them. + +You can find a comprehensive description of DejaGnu and \fBruntest\fR in +.I +The DejaGnu Testing Framework +or its Info version, +.BR dejagnu.info . +.SH OPTIONS +.TP +.B --all +Print all test output to screen. By default, only unexpected results are +displayed. +.TP +.BI --baud \ rate +Set the baud rate for a serial line connection. Some serial interface +programs (like \fBtip\fR) don't use this value but instead use a separate +initialization file. +.TP +.BI --connect \ type +The type of connection to use. The choices are +.BR rlogin , +.BR telnet , +.BR rsh , +.BR kermit , +.BR tip +and +.BR mondfe . +.TP +.B --debug +Turn on +.B expect +internal debugging output. All output is logged to +a file called \fBdbg.out\fR. +The output of the \fB--strace\fR also goes into this file. +.TP +.B --help +Prints out a help screen and then exits. +.TP +.BI --host \ type +The configuration string for the host. +.TP +.BI --ignore \ test1.exp\ test2.exp\ ... +Do not run the specified tests. +.BI --mail \ \'name1\ name2\ ...\' +Electronic mail addresses to receive test results. +.TP +.BI --name \ hostname +The network hostname of the target board. +.TP +.BI --objdir \ path +\fIpath\fR is a directory containing compiled test code. +.TP +.BI --outdir \ directory +The name of a directory for test log output. +.TP +.B --reboot +Reboot the target board when \fBruntest\fR initializes +(if supported). +.TP +.BI --srcdir \ path +\fIpath\fR is a directory containing test directories. +.TP +.BI --strace \ N +Turns on +.B expect +internal tracing to \fIN\fR levels deep. +.TP +.BI --target \ type +The configuration string for the target. +.TP +.BI --tool \ toolname +Specify the tool to be tested. \fItoolname\fR controls the test suite +applied, and the associated initialization module. +.TP +.B --verbose,\ -v +Turns on more debugging output from test cases and DejaGnu utility code. +Use more than once to increase output further. +.TP +.B --version,\ -V +Prints out the versions of DejaGnu, expect and Tcl. +.TP +.B -D[number] +Activate the Tcl debugger.\fBnumber\fR can be either 1 or 0. If it is +1, then the expect shell will break when it starts to run. All ^C's +drop DejaGnu back to the debugger prompt. A 0 starts DejaGnu like +normal, but a ^C drops to the debugger prompt. +.TP 0 +Any file name on the command line is assumed to be a subset +of the test names to run. Usually these are the names of the +expect test driver, ie... special.exp. + +Makefile style variables are used to specify tool names and their +flags; these and other configuration dependent values are saved in the +file \fBsite.exp\fR, created during configuration. +.SH EXIT CODES +.B runtest +sets the exit code to 1 if any of the tests failed, or +sets it to 0 if all the tests passed. +.SH SEE ALSO +.I The DejaGnu Testing Framework +.RB ( dejagnu.info ). +This is the DejaGnu manual; its source is the SGML files +.B +doc/*.sgml. +in the DejaGnu distribution. +.SH AUTHOR +Rob Savoye (rob@welcomehome.org) diff --git a/doc/user.sgml b/doc/user.sgml new file mode 100644 index 0000000..2154d74 --- /dev/null +++ b/doc/user.sgml @@ -0,0 +1,2355 @@ + <chapter id=runningtests> + <title>Running Tests</title> + + <para>There are two ways to execute a test suite. The most + common way is when there is existing support in the + <filename>Makefile</filename>. This support consists of a + <emphasis>check</emphasis> target. The other way is to execute the + <command>runtest</command> program directly. To run + <command>runtest</command> directcly from the command line requires + either all the correct options, or the <xref linkend=local> must be setup + correctly.</para> + + <sect1 id=makecheck xreflabel="Make Check"> + <title>Make check</title> + + <para>To run tests from an existing collection, first use + <command>configure</command> as usual to set up the + build directory. Then try typing:</para> + + <screen> + make check + </screen> + + <para>If the <emphasis>check</emphasis> target exists, it + usually saves you some trouble. For instance, it can set up any + auxiliary programs or other files needed by the tests. The most + common file the check builds is the + <emphasis>site.exp</emphasis>. The site.exp file contains + various variables that DejaGnu used to dertermine the + configuration of the program being tested. This is mostly for + supporting remote testing.</para> + + <para>The <emphasis>check</emphasis> target is supported by GNU + <productname>Automake</productname>. To have DejaGnu support added to your + generated <filename>Makefile.in</filename>, just add the keyword + dejagnu to the AUTOMAKE_OPTIONS variable in your + <filename>Makefile.am</filename> file.</para> + + <para>Once you have run <emphasis>make check</emphasis> to build + any auxiliary files, you can invoke the test driver + <command>runtest</command> directly to repeat the tests. + You will also have to execute <command>runtest</command> + directly for test collections with no + <emphasis>check</emphasis> target in the + <filename>Makefile</filename>.</para> + + </sect1> + + <sect1 id=runtest xreflabel="Runtest"> + <title>Runtest</title> + + <para><command>runtest</command> is the executable test driver + for DejaGnu. You can specify two kinds of things on the + <command>runtest</command> command line: command line options, + and Tcl variables for the test scripts. The options are listed + alphabetically below.</para> + + <para><command>runtest</command> returns an exit code of + <emphasis>1</emphasis> if any test has an unexpected result; otherwise + (if all tests pass or fail as expected) it returns <emphasis>0</emphasis> + as the exit code.</para> + + <sect2 id=outputs xreflabel="Output States"> + <title>Output States</title> + + <para><filename>runtest</filename> flags the outcome of each + test as one of these cases. <xref linkend=posix> for a + discussion of how POSIX specifies the meanings of these + cases.</para> + + <variablelist> + <varlistentry> + <term>PASS</term> + <listitem><para>The most desirable outcome: the test succeeded, and + was expected to succeed.</para></listitem> + </varlistentry> + + <varlistentry> + <term>XPASS</term> + <listitem><para>A pleasant kind of failure: a test was expected to + fail, but succeeded. This may indicate progress; inspect the test + case to determine whether you should amend it to stop expecting + failure.</para></listitem> + </varlistentry> + + <varlistentry> + <term>FAIL</term> + <listitem><para>A test failed, although it was expected to succeed. + This may indicate regress; inspect the test case and the failing + software to ocate the bug.</para></listitem> + </varlistentry> + + <varlistentry> + <term>XFAIL</term> + <listitem><para>A test failed, but it was expected to fail. This + result indicates no change in a known bug. If a test fails because + the operating system where the test runs lacks some facility required + by the test, the outcome is <emphasis>UNSUPPORTED</emphasis> + instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term>UNRESOLVED</term> + <listitem><para>Output from a test requires manual inspection; the + test suite could not automatically determine the outcome. For + example, your tests can report this outcome is when a test does not + complete as expected.</para></listitem> + </varlistentry> + + <varlistentry> + <term>UNTESTED</term> + <listitem><para>A test case is not yet complete, and in particular + cannot yet produce a <emphasis>PASS</emphasis> or + <emphasis>FAIL</emphasis>. You can also use this outcome in dummy + ``tests'' that note explicitly the absence of a real test case for a + particular property.</para></listitem> + </varlistentry> + + <varlistentry> + <term>UNSUPPORTED</term> + <listitem><para>A test depends on a conditionally available feature + that does not exist (in the configured testing environment). For + example, you can use this outcome to report on a test case that does + not work on a particular target because its operating system support + does not include a required subroutine.</para></listitem> + </varlistentry> + </variablelist> + + <para>runtest may also display the following messages:</para> + + <variablelist> + <varlistentry> + <term>ERROR</term> + <listitem><para>Indicates a major problem (detected by the test case + itself) in running the test. This is usually an unrecoverable error, + such as a missing file or loss of communication to the target. (POSIX + test suites should not emit this message; use + <emphasis>UNSUPPORTED</emphasis>, <emphasis>UNTESTED</emphasis>, or + <emphasis>UNRESOLVED</emphasis> instead, as + appropriate.)</para></listitem> + </varlistentry> + + <varlistentry> + <term>WARNING</term> + <listitem><para>Indicates a possible problem in running the + test. Usually warnings correspond to recoverable errors, or display + an important message about the following tests.</para></listitem> + </varlistentry> + + <varlistentry> + <term>NOTE</term> + <listitem><para>An informational message about the test + case.</para></listitem> + </varlistentry> + </variablelist> + + </sect2> + + <sect2 id=invoking xreflabel="Invoking Runtest"> + <title>Invoking Runtest</title> + + <para>This is the full set of command line options that + <filename>runtest</filename> recognizes. Arguments may be + abbreviated to the shortest unique string.</para> + + <variablelist> + <varlistentry> + <term><option>--all</option> (-a)</term> + <listitem><para>Display all test output. By default, + <emphasis>runtest</emphasis> shows only the output of tests that + produce unexpected results; that is, tests with status + <emphasis>FAIL</emphasis> (unexpected failure), + <emphasis>XPASS</emphasis> (unexpected success), or + <emphasis>ERROR</emphasis> (a severe error in the test case + itself). Specify <emphasis>--all</emphasis> to see output for tests + with status <emphasis>PASS</emphasis> (success, as expected) + <emphasis>XFAIL</emphasis> (failure, as expected), or + <emphasis>WARNING</emphasis> (minor error in the test case + itself).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--build [string]</option></term> + <listitem><para><emphasis>string</emphasis> is a full configuration + ``triple'' name as used by <command>configure</command>. This + is the type of machine DejaGnu and the tools to be tested are built + on. For a normal cross this is the same as the host, but for a + canadian cross, they are seperate.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--host [string]</option></term> + <listitem><para><symbol>string</symbol> is a full configuration + ``triple'' name as used by <emphasis>configure</emphasis>. Use this + option to override the default string recorded by your + configuration's choice of host. This choice does not change how + anything is actually configured unless --build is also specified; it + affects <emphasis>only</emphasis> DejaGnu procedures that compare the + host string with particular values. The procedures + <emphasis>ishost</emphasis>, <emphasis>istarget</emphasis>, + <emphasis>isnative</emphasis>, and <emphasis>setup</emphasis>xfail} + are affected by <emphasis>--host</emphasis>. In this usage, + <emphasis>host</emphasis> refers to the machine that the tests are to + be run on, which may not be the same as the + <emphasis>build</emphasis> machine. If <emphasis>--build</emphasis> + is also specified, then <emphasis>--host</emphasis> refers to the + machine that the tests wil, be run on, not the machine DejaGnu is run + on.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--host_board [name]</option></term> + <listitem><para>The host board to use.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--target [string]</option></term> + <listitem><para>Use this option to override the default setting + (running native tests). <emphasis>string</emphasis> is a full + configuration ``triple'' name of the form + <emphasis>cpu-vendor-os</emphasis> as used by + <command>configure</command>. This option changes the + configuration <emphasis>runtest</emphasis> uses for the default tool + names, and other setup information.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--debug</option> (-de)</term> + <listitem><para>Turns on the <emphasis>expect</emphasis> internal + debugging output. Debugging output is displayed as part of the + <emphasis>runtest</emphasis> output, and logged to a file called + <filename>dbg.log</filename>. The extra debugging output does + <emphasis>not</emphasis> appear on standard output, unless the + verbose level is greater than 2 (for instance, to see debug output + immediately, specify <emphasis>--debug</emphasis>-v -v}). The + debugging output shows all attempts at matching the test output of + the tool with the scripted patterns describing expected output. The + output generated with <emphasis>--strace</emphasis> also goes into + <filename>dbg.log</filename>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--help</option> (-he)</term> + <listitem><para>Prints out a short summary of the + <emphasis>runtest</emphasis> options, then exits (even if you also + specify other options).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--ignore [name(s)] </option></term> + <listitem><para>The names of specific tests to + ignore.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--objdir [path]</option></term> + <listitem><para>Use <emphasis>path</emphasis> as the top directory + containing any auxiliary compiled test code. This defaults to + <filename>.</filename>. Use this option to locate pre-compiled test + code. You can normally prepare any auxiliary files needed with + <emphasis>make</emphasis>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--outdir [path]</option></term> + <listitem><para>Write output logs in directory + <filename>path</filename>. The default is <emphasis>.}, + the</emphasis> directory where you start + <emphasis>runtest</emphasis>. This option affects only the summary + and the detailed log files + <filename>tool.sum</filename> and + <filename>tool.log</filename>. The DejaGnu debug + log <filename>dbg.log</filename> always appears (when requested) in + the local directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--reboot [name]</option></term> + <listitem><para>Reboot the target board when + <emphasis>runtest</emphasis> initializes. Usually, when running tests + on a separate target board, it is safer to reboot the target to be + certain of its state. However, when developing test scripts, + rebooting takes a lot of time.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--srcdir [path]</option></term> + <listitem><para>Use <filename>path</filename> as the top directory + for test scripts to run. <emphasis>runtest</emphasis> looks in this + directory for any subdirectory whose name begins with the toolname + (specified with <emphasis>--tool</emphasis>). For instance, with + <emphasis>--tool</emphasis>gdb}, <emphasis>runtest</emphasis> uses + tests in subdirectories <filename>gdb.*</filename> (with the usual + shell-like filename expansion). If you do not use + <emphasis>--srcdir</emphasis>, <emphasis>runtest</emphasis> looks for + test directories under the current working + directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--strace [number]</option></term> + <listitem><para>Turn on internal tracing for + <emphasis>expect</emphasis>, to n levels deep. By adjusting the + level, you can control the extent to which your output expands + multi-level Tcl statements. This allows you to ignore some levels of + <emphasis>case</emphasis> or <emphasis>if</emphasis> statements. + Each procedure call or control structure counts as one ``level''. The + output is recorded in the same file, <filename>dbg.log</filename>, + used for output from <emphasis>--debug</emphasis>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--connect [program]</option></term> + <listitem><para>Connect to a target testing environment as specified + by <emphasis>type</emphasis>, if the target is not the computer + running <emphasis>runtest</emphasis>. For example, use + <emphasis>--connect</emphasis> to change the program used to connect + to a ``bare board'' boot monitor. The choices for + <emphasis>type</emphasis> in the DejaGnu 1.4 distribution are + <emphasis>rlogin</emphasis>, <emphasis>telnet</emphasis>, + <emphasis>rsh</emphasis>, <emphasis>tip</emphasis>, + <emphasis>kermit</emphasis>, and <emphasis>mondfe</emphasis>.</para> + + <para>The default for this option depends on the configuration most + convenient communication method available, but often other + alternatives work as well; you may find it useful to try alternative + connect methods if you suspect a communication problem with your + testing target.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--baud [number]</option></term> + <listitem><para>Set the default baud rate to something other than + 9600. (Some serial interface programs, like <emphasis>tip</emphasis>, + use a separate initialization file instead of this + value.)</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--target_board [name(s)]</option></term> + <listitem><para>The list of target boards to run tests + on.</para></listitem> + </varlistentry> + + <varlistentry id=tool-opt> + <term><option>--tool[name(s)]</option></term> + <listitem><para>Specifies which test suite to run, and what + initialization module to use. <option>--tool</option> is used + <emphasis>only</emphasis> for these two purposes. It is + <emphasis>not</emphasis> used to name the executable program to + test. Executable tool names (and paths) are recorded in + <filename>site.exp</filename> and you can override them by specifying + Tcl variables on the command line.</para> + + <para>For example, including "<option>--tool</option> gcc" on the + <emphasis>runtest</emphasis> command line runs tests from all test + subdirectories whose names match <filename>gcc.*</filename>, and uses + one of the initialization modules named + <filename>config/*-gcc.exp</filename>. To specify the name of the + compiler (perhaps as an alternative path to what + <emphasis>runtest</emphasis> would use by default), use + <emphasis>GCC=binname</emphasis> on the <emphasis>runtest</emphasis> + command line.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--tool_exec [name]</option></term> + <listitem><para>The path to the tool executable to + test.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--tool_opts [options]</option></term> + <listitem><para>A list of additional options to pass to the + tool.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--verbose</option> (-v)</term> + <listitem><para>Turns on more output. Repeating this option increases + the amount of output displayed. Level one (<emphasis>-v</emphasis>) + is simply test output. Level two (<emphasis>-v</emphasis>-v}) shows + messages on options, configuration, and process control. Verbose + messages appear in the detailed (<filename>*.log</filename>) log + file, but not in the summary (<filename>*.sum</filename>) log + file.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--version</option> (-V)</term> + <listitem><para>Prints out the version numbers of DejaGnu, + <emphasis>expect</emphasis> and Tcl, and exits without running any + tests.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--D[0-1]</option></term> + <listitem><para>Start the internal Tcl debugger. The Tcl debugger + supports breakpoints, single stepping, and other common debugging + activities. See the document "Debugger for Tcl Applications} by Don + Libes. (Distributed in PostScript form with + <emphasis>expect</emphasis> as the file + <filename>expect/tcl-debug.ps.</filename>. If you specify + <emphasis>-D1</emphasis>, the <emphasis>expect</emphasis> shell stops + at a breakpoint as soon as DejaGnu invokes it. If you specify + <emphasis>-D0</emphasis>, DejaGnu starts as usual, but you can enter + the debugger by sending an interrupt (e.g. by typing + <keycombo><keycap>C</keycap><keycap>c</keycap></keycombo>). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>testfile</filename>.exp[=arg(s)]</term> + <listitem><para>Specify the names of testsuites to run. By default, + <emphasis>runtest</emphasis> runs all tests for the tool, but you can + restrict it to particular testsuites by giving the names of the + <emphasis>.exp expect</emphasis> scripts that control + them. <emphasis>testsuite</emphasis>.exp may not include path + information; use plain filenames.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>testfile</filename>.exp="testfile1 ..."</term> + <listitem><para>Specify a subset of tests in a suite to run. For + compiler or assembler tests, which often use a single + <emphasis>.exp</emphasis> script covering many different source + files, this option allows you to further restrict the tests by + listing particular source files to compile. Some tools even support + wildcards here. The wildcards supported depend upon the tool, but + typically they are <emphasis>?</emphasis>, <emphasis>*</emphasis>, + and <emphasis>[chars]</emphasis>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><symbol>tclvar</symbol>=value</term> + <listitem><para>You can define Tcl variables for use by your test + scripts in the same style used with <emphasis>make</emphasis> for + environment variables. For example, <emphasis>runtest + GDB=gdb.old</emphasis> defines a variable called + <command>GDB</command>; when your scripts refer to + <symbol>$GDB</symbol> in this run, they use the value + <emphasis>gdb.old</emphasis>.</para> + + <para>The default Tcl variables used for most tools are defined in + the main DejaGnu <emphasis>Makefile</emphasis>; their values are + captured in the <filename>site.exp</filename> file.</para></listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 id=common xreflabel="Common Operations"> + <title>Common Options</title> + + <para>Typically, you don't need must to use any command-line options. + <option>--tool</option> used is only required when there are more than + one test suite in the same directory. The default options are in the + local site.exp file, created by "make site.exp".</para> + + <para>For example, if the directory <filename>gdb/testsuite</filename> + contains a collection of DejaGnu tests for GDB, you can run them like + this:</para> + + <screen> + eg$ cd gdb/testsuite + eg$ runtest --tool gdb + </screen> + + <para>Test output follows, ending with:</para> + + <screen> + === gdb Summary === + + # of expected passes 508 + # of expected failures 103 + /usr/latest/bin/gdb version 4.14.4 -nx + </screen> + + <para>You can use the option <emphasis>--srcdir</emphasis> to point to + some other directory containing a collection of tests:</para> + + <screen> + eg$ runtest--srcdir /devo/gdb/testsuite + </screen> + + <para>By default, <command>runtest</command> prints only the + names of the tests it runs, output from any tests that have unexpected + results, and a summary showing how many tests passed and how many + failed. To display output from all tests (whether or not they behave + as expected), use the <emphasis>--all</emphasis> option. For more + verbose output about processes being run, communication, and so on, use + <emphasis>--verbose</emphasis>. To see even more output, use multiple + <emphasis>--verbose</emphasis> options. for a more detailed explanation + of each <command>runtest</command> option. + + <para>Test output goes into two files in your current directory: + summary output in <filename>tool.sum</filename>, + and detailed output in <filename> + tool.log</filename>. (<emphasis>tool</emphasis> + refers to the collection of tests; for example, after a run with + <emphasis>--tool</emphasis> gdb, look for output files + <filename>gdb.sum</filename> and <filename>gdb.log</filename>.) + </sect2> + </sect1> + + <sect1 id=outputfiles xreflabel="Output Files"> + + <title>The files DejaGnu produces.</title> + + <para>DejaGnu always writes two kinds of output files: summary + logs and detailed logs. The contents of both of these are + determined by your tests.</para> + + <para>For troubleshooting, a third kind of output file is useful: + use <option>--debug</option> to request an output file showing + details of what <productname>Expect</productname> is doing + internally.</para> + + <sect2 id=sum xreflabel="Summary File"> + <title>Summary File</title> + + <para>DejaGnu always produces a summary output file + <filename>tool.sum</filename>. This summary shows the names of + all test files run; for each test file, one line of output from + each <command>pass</command> command (showing status + <emphasis>PASS</emphasis> or <emphasis>XPASS</emphasis>) or + <command>fail</command> command (status + <emphasis>FAIL</emphasis> or <emphasis>XFAIL</emphasis>); + trailing summary statistics that count passing and failing tests + (expected and unexpected); and the full pathname and version + number of the tool tested. (All possible outcomes, and all + errors, are always reflected in the summary output file, + regardless of whether or not you specify <option>--all</option>.) + + <para>If any of your tests use the procedures + <command>unresolved</command>, <command>unsupported</command>, + or <command>runtested</command>, the summary output also + tabulates the corresponding outcomes.</para> + + <para>For example, after <command>runtest --tool + binutils</command>, look for a summary log in + <filename>binutils.sum</filename>. Normally, DejaGnu writes this + file in your current working directory; use the + <option>--outdir</option> option to select a different + directory.</para> + + <example> + <title>Here is a short sample summary log</title> + + <screen> + Test Run By rob on Mon May 25 21:40:57 PDT 1992 + === gdb tests === + Running ./gdb.t00/echo.exp ... + PASS: Echo test + Running ./gdb.all/help.exp ... + PASS: help add-symbol-file + PASS: help aliases + PASS: help breakpoint "bre" abbreviation + FAIL: help run "r" abbreviation + Running ./gdb.t10/crossload.exp ... + PASS: m68k-elf (elf-big) explicit format; loaded + XFAIL: mips-ecoff (ecoff-bigmips) "ptype v_signed_char" signed C types + === gdb Summary === + # of expected passes 5 + # of expected failures 1 + # of unexpected failures 1 + /usr/latest/bin/gdb version 4.6.5 -q + </screen> + </example> + + </sect2> + + <sect2 id=log xreflabel="Log File"> + <title>Log File</title> + + <para>DejaGnu also saves a detailed log file + <filename>tool.log</filename>, showing any output generated by + tests as well as the summary output. For example, after + <command>runtest --tool binutils</command>, look for a detailed + log in <filename>binutils.log</filename>. Normally, DejaGnu + writes this file in your current working directory; use the + <option>--outdir</option> option to select a different + directory.</para> + + + <example> + <title>Here is a brief example showing a detailed log for + <productname>G++</productname> tests</title> + + <screen> + Test Run By rob on Mon May 25 21:40:43 PDT 1992 + + === g++ tests === + + --- Running ./g++.other/t01-1.exp --- + PASS: operate delete + + --- Running ./g++.other/t01-2.exp --- + FAIL: i960 bug EOF + p0000646.C: In function `int warn_return_1 ()': + p0000646.C:109: warning: control reaches end of non-void function + p0000646.C: In function `int warn_return_arg (int)': + p0000646.C:117: warning: control reaches end of non-void function + p0000646.C: In function `int warn_return_sum (int, int)': + p0000646.C:125: warning: control reaches end of non-void function + p0000646.C: In function `struct foo warn_return_foo ()': + p0000646.C:132: warning: control reaches end of non-void function + + --- Running ./g++.other/t01-4.exp --- + FAIL: abort + 900403_04.C:8: zero width for bit-field `foo' + --- Running ./g++.other/t01-3.exp --- + FAIL: segment violation + 900519_12.C:9: parse error before `;' + 900519_12.C:12: Segmentation violation + /usr/latest/bin/gcc: Internal compiler error: program cc1plus got fatal signal + + === g++ Summary === + + # of expected passes 1 + # of expected failures 3 + /usr/latest/bin/g++ version cygnus-2.0.1 + </screen> + </example> + + </sect2> + + <sect2 id=debugfile xreflabel="Debug Log File"> + <title>Debug Log File</title> + + <para>With the <option>--debug</option> option, you can request + a log file showing the output from + <productname>Expect</productname> itself, running in debugging + mode. This file (<filename>dbg.log</filename>, in the directory + where you start <command>runtest</command>) shows each pattern + <productname>Expect</productname> considers in analyzing test + output.</para> + + <para>This file reflects each <command>send</command> command, + showing the string sent as input to the tool under test; and + each <productname>Expect</productname> command, showing each + pattern it compares with the tool output.</para> + + <example> + <title>The log messages begin with a message of the form</title> + + <screen> + + expect: does {<symbol>tool output</symbol>} (spawn_id <symbol>n</symbol>) + match pattern {<emphasis>expected pattern</emphasis>}? + + </screen> + </example> + + <para>For every unsuccessful match, + <productname>Expect</productname> issues a + <emphasis>no</emphasis> after this message; if other patterns + are specified for the same <productname>Expect</productname> + command, they are reflected also, but without the first part of + the message (<emphasis>expect... match pattern</emphasis>).</para> + + <para>When <productname>Expect</productname> finds a match, the + log for the successful match ends with <emphasis>yes</emphasis>, + followed by a record of the <productname>Expect</productname> + variables set to describe a successful match.</para> + + <example> + <title>Here is an excerpt from the debugging log for a + <productname>GDB</productname> test:</title> + + <screen> + send: sent {break gdbme.c:34\n} to spawn id 6 + expect: does {} (spawn_id 6) match pattern {Breakpoint.*at.* file + gdbme.c, line 34.*\(gdb\) $}? no + {.*\(gdb\) $}? no + expect: does {} (spawn_id 0) match pattern {return} ? no + {\(y or n\) }? no + {buffer_full}? no + {virtual}? no + {memory}? no + {exhausted}? no + {Undefined}? no + {command}? no + break gdbme.c:34 + Breakpoint 8 at 0x23d8: file gdbme.c, line 34. + (gdb) expect: does {break gdbme.c:34\r\nBreakpoint 8 at 0x23d8: + file gdbme.c, line 34.\r\n(gdb) } (spawn_id 6) match pattern + {Breakpoint.*at.* file gdbme.c, line 34.*\(gdb\) $}? yes + expect: set expect_out(0,start) {18} + expect: set expect_out(0,end) {71} + expect: set expect_out(0,string) {Breakpoint 8 at 0x23d8: file + gdbme.c, line 34.\r\n(gdb) } + epect: set expect_out(spawn_id) {6} + expect: set expect_out(buffer) {break gdbme.c:34\r\nBreakpoint 8 + at 0x23d8: file gdbme.c, line 34.\r\n(gdb) } + PASS: 70 0 breakpoint line number in file + </screen> + </example> + + <para>This example exhibits three properties of + <productname>Expect</productname> and + <productname>DejaGnu</productname> that might be surprising at + first glance:</para> + + <itemizedlist mark="bullet"> + <listitem><para>Empty output for the first attempted match. The + first set of attempted matches shown ran against the output + <emphasis>{}</emphasis> --- that is, no + output. <productname>Expect</productname> begins + attempting to match the patterns supplied immediately; often, + the first pass is against incomplete output (or completely + before all output, as in this case).</para></listitem> + + <listitem><para>Interspersed tool output. The beginning of + the log entry for the second attempted match may be hard to + spot: this is because the prompt <emphasis>{(gdb) }</emphasis> + appears on the same line, just before the + <emphasis>expect:</emphasis> that marks the beginning of the + log entry.</para></listitem> + + <listitem><para>Fail-safe patterns. Many of the patterns + tested are fail-safe patterns provided by + <productname>GDB</productname> testing utilities, to reduce + possible indeterminacy. It is useful to anticipate potential + variations caused by extreme system conditions + (<productname>GDB</productname> might issue the message + <emphasis>virtual memory exhausted</emphasis> in rare + circumstances), or by changes in the tested program + (<emphasis>Undefined command</emphasis> is the likeliest + outcome if the name of a tested command changes).</para> + + <para>The pattern <emphasis>{return}</emphasis> is a + particularly interesting fail-safe to notice; it checks for an + unexpected <keycap>RET</keycap> prompt. This may happen, + for example, if the tested tool can filter output through a + pager.</para> + + <para>These fail-safe patterns (like the debugging log itself) + are primarily useful while developing test scripts. Use the + <command>error</command> procedure to make the actions for + fail-safe patterns produce messages starting with + <emphasis>ERROR</emphasis> on standard output, and in the + detailed log file.</para></listitem> + </itemizedlist> + </sect2> + </sect1> + </chapter> + + <chapter id=Customizing xreflabel="Customizing DejaGnu"> + <title>Customizing DejaGnu</title> + + <para>The site configuration file, <filename>site.exp</filename>, + captures configuration-dependent values and propagates them to the + DejaGnu test environment using Tcl variables. This ties the + DejaGnu test scripts into the <command>configure</command> and + <command>make</command> programs. If this file is setup correctly, + it is possible to execute a test suite merely by typing + <command>runtest</command>.</para> + + <para>DejaGnu supports two <filename>site.exp</filename> + files. The multiple instances of <filename>site.exp</filename> are + loaded in a fixed order built into DejaGnu. The first file loaded + is the local file <filename>site.exp</filename>, and then the + optional global <filename>site.exp</filename> file as + pointed to by the <symbol>DEJAGNU</symbol> environment + variable.</para> + + <para>There is an optional <emphasis>master</emphasis> + <filename>site.exp</filename>, capturing configuration values that + apply to DejaGnu across the board, in each configuration-specific + subdirectory of the DejaGnu library directory. + <command>runtest</command> loads these values first. The master + <filename>site.exp</filename> contains the default values for all + targets and hosts supported by DejaGnu. This master file is + identified by setting the environment variable + <symbol>DEJAGNU</symbol> to the name of the file. This is also + refered to as the ``global'' config file.</para> + + <para>Any directory containing a configured test suite also has a + local <filename>site.exp</filename>, capturing configuration values + specific to the tool under test. Since <command>runtest</command> + loads these values last, the individual test configuration can + either rely on and use, or override, any of the global values from + the global <filename>site.exp</filename> file.</para> + + <para>You can usually generate or update the testsuite's local + <filename>site.exp</filename> by typing <command>make + site.exp</command> in the test suite directory, after the test + suite is configured.</para> + + <para>You can also have a file in your home directory called + <filename>.dejagnurc</filename>. This gets loaded first before the + other config files. Usually this is used for personal stuff, like + setting the <symbol>all_flag</symbol> so all the output gets + printed, or your own verbosity levels. This file is usually + restricted to setting command line options.</para> + + <para>You can further override the default values in a + user-editable section of any <filename>site.exp</filename>, or by + setting variables on the <command>runtest</command> command + line.</para> + + <sect1 id=local xreflabel="Local Config File"> + <title>Local Config File</title> + + <para>It is usually more convenient to keep these <emphasis>manual + overrides</emphasis> in the <filename>site.exp</filename> + local to each test directory, rather than in the global + <filename>site.exp</filename> in the installed DejaGnu + library. This file is mostly for supplying tool specific info + that is required by the test suite.</para> + + <para>All local <filename>site.exp</filename> files have + two sections, separated by comment text. The first section is + the part that is generated by <command>make</command>. It is + essentially a collection of Tcl variable definitions based on + <filename>Makefile</filename> environment variables. Since they + are generated by <command>make</command>, they contain the + values as specified by <command>configure</command>. (You can + also customize these values by using the <option>--site</option> + option to <command>configure</command>.) In particular, this + section contains the <filename>Makefile</filename> + variables for host and target configuration data. Do not edit + this first section; if you do, your changes are replaced next + time you run <command>make</command>.</para> + + <example> + <title>The first section starts with</title> + + <programlisting> + ## these variables are automatically generated by make ## + # Do not edit here. If you wish to override these values + # add them to the last section + </programlisting> + </example> + + <para>In the second section, you can override any default values + (locally to DejaGnu) for all the variables. The second section + can also contain your preferred defaults for all the command + line options to <command>runtest</command>. This allows you to + easily customize <command>runtest</command> for your preferences + in each configured test-suite tree, so that you need not type + options repeatedly on the command line. (The second section may + also be empty, if you do not wish to override any defaults.)</para> + + <example> + <title>The first section ends with this line</title> + + <programlisting> + ## All variables above are generated by configure. Do Not Edit ## + </programlisting> + </example> + + <para>You can make any changes under this line. If you wish to + redefine a variable in the top section, then just put a + duplicate value in this second section. Usually the values + defined in this config file are related to the configuration of + the test run. This is the ideal place to set the variables + <symbol>host_triplet</symbol>, <symbol>build_triplet</symbol>, + <symbol>target_triplet</symbol>. All other variables are tool + dependant. ie for testing a compiler, the value for + <symbol>CC</symbol> might be set to a freshly built binary, as + opposed to one in the user's path.</para> + + <para>Here's an example local site.exp file, as used for + <productname>GCC/G++</productname> testing.</para> + + <example> + <title>Local Config File</title> + + <programlisting> + ## these variables are automatically generated by make ## + # Do not edit here. If you wish to override these values + # add them to the last section + set rootme "/build/devo-builds/i586-pc-linux-gnulibc1/gcc" + set host_triplet i586-pc-linux-gnulibc1 + set build_triplet i586-pc-linux-gnulibc1 + set target_triplet i586-pc-linux-gnulibc1 + set target_alias i586-pc-linux-gnulibc1 + set CFLAGS "" + set CXXFLAGS "-I/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libio -I$srcdir/../libg++/src -I$srcdir/../libio -I$srcdir/../libstdc++ -I$srcdir/../libstdc++/stl -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libg++ -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libstdc++" + append LDFLAGS " -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../ld" + set tmpdir /build/devo-builds/i586-pc-linux-gnulibc1/gcc/testsuite + set srcdir "${srcdir}/testsuite" + ## All variables above are generated by configure. Do Not Edit ## + + </programlisting> + </example> + + <para>This file defines the required fields for a local config + file, namely the three config triplets, and the srcdir. It also + defines several other Tcl variables that are used exclusivly by + the GCC test suite. For most test cases, the CXXFLAGS and LDFLAGS + are supplied by DejaGnu itself for cross testing, but to test a + compiler, GCC needs to manipulate these itself.</para> + + </sect1> + <sect1 id=global xreflabel="Global Config File"> + <title>Global Config File</title> + + <para>The master config file is where all the target specific + config variables get set for a whole site get set. The idea is + that for a centralized testing lab where people have to share a + target between multiple developers. There are settings for both + remote targets and remote hosts. Here's an example of a Master + Config File (also called the Global config file) for a + <emphasis>canadian cross</emphasis>. A canadian cross is when + you build and test a cross compiler on a machine other than the + one it's to be hosted on.</para> + + <para>Here we have the config settings for our California + office. Note that all config values are site dependant. Here we + have two sets of values that we use for testing m68k-aout cross + compilers. As both of these target boards has a different + debugging protocol, we test on both of them in sequence.</para> + + <example> + <title>Global Config file</title> + + <programlisting> + + # Make sure we look in the right place for the board description files. + if ![info exists boards_dir] { + set boards_dir {} + } + lappend boards_dir "/nfs/cygint/s1/cygnus/dejagnu/boards" + + verbose "Global Config File: target_triplet is $target_triplet" 2 + global target_list + + case "$target_triplet" in { + { "native" } { + set target_list "unix" + } + { "sparc64-*elf" } { + set target_list "sparc64-sim" + } + { "mips-*elf" } { + set target_list "mips-sim wilma barney" + } + { "mips-lsi-elf" } { + set target_list "mips-lsi-sim{,soft-float,el}" + } + { "sh-*hms" } { + set target_list { "sh-hms-sim" "bloozy" } + } + } + </programlisting> + </example> + + <para>In this case, we have support for several cross compilers, + that all run on this host. For testing on operating systems that + don't support Expect, DejaGnu can be run on the local build + machine, and it can connect to the remote host and run all the + tests for this cross compiler on that host. All the remote OS + requires is a working telnetd.</para> + + <para>As you can see, all one does is set the variable + <symbol>target_list</symbol> to the list of targets and options to + test. The simple settings, like for + <emphasis>sparc64-elf</emphasis> only require setting the name of + the single board config file. The <emphasis>mips-elf</emphasis> + target is more complicated. Here it sets the list to three target + boards. One is the default mips target, and both + <emphasis>wilma</emphasis> <emphasis>barney</emphasis> are + symbolic names for other mips boards. Symbolic names are covered + in the <xref linkend=addboard> chapter. The more complicated + example is the one for <emphasis>mips-lsi-elf</emphasis>. This one + runs the tests with multiple iterations using all possible + combinations of the <option>--soft-float</option> and the + <option>--el</option> (little endian) option. Needless to say, + this last feature is mostly compiler specific.</para> + + </sect1> + + <sect1 id=boardconfig xreflabel="Board Config File"> + <title>Board Config File</title> + + <para>The board config file is where board specfic config data + is stored. A board config file contains all the higher-level + configuration settings. There is a rough inheritance scheme, where it is + possible to base a new board description file on an existing one. There + are also collections of custom procedures for common environments. For + more information on adding a new board config file, go to the <xref + linkend=addboard> chapter. </para> + + <para>An example board config file for a GNU simulator is as + follows. <function>set_board_info</function> is a procedure that sets the + field name to the specified value. The procedures in square brackets + <emphasis>[]</emphasis> are <emphasis>helper procedures</emphasis>. Thes + are used to find parts of a tool chain required to build an executable + image that may reside in various locations. This is mostly of use for + when the startup code, the standard C lobraries, or the tool chain itself + is part of your build tree.</para> + + <example> + <title>Board Config File</title> + + <programlisting> + # This is a list of toolchains that are supported on this board. + set_board_info target_install {sparc64-elf} + + # Load the generic configuration for this board. This will define any + # routines needed by the tool to communicate with the board. + load_generic_config "sim" + + # We need this for find_gcc and *_include_flags/*_link_flags. + load_base_board_description "basic-sim" + + # Use long64 by default. + process_multilib_options "long64" + + setup_sim sparc64 + + # We only support newlib on this target. We assume that all multilib + # options have been specified before we get here. + set_board_info compiler "[find_gcc]" + set_board_info cflags "[libgloss_include_flags] [newlib_include_flags]" + set_board_info ldflags "[libgloss_link_flags] [newlib_link_flags]" + # No linker script. + set_board_info ldscript ""; + + # Used by a few gcc.c-torture testcases to delimit how large the + # stack can be. + set_board_info gcc,stack_size 16384 + # The simulator doesn't return exit statuses and we need to indicate this + # the standard GCC wrapper will work with this target. + set_board_info needs_status_wrapper 1 + # We can't pass arguments to programs. + set_board_info noargs 1 + </programlisting> + </example> + + <para>There are five helper procedures used in this example. The first + one, <function>find gcc</function> looks for a copy of the GNU compiler in + your build tree, or it uses the one in your path. This will also return + the proper transformed name for a cross compiler if you whole build tree + is configured for one. The next helper procedures are + <function>libgloss_include_flags</function> & + <function>libgloss_link_flags</function>. These return the proper flags to + compiler and link an executable image using <xref + linkend=libgloss>, the GNU BSP (Board Support Package). The final + procedures are <function>newlib_include_flag</function> & + <function>newlib_include_flag</function>. These find the Newlib C + library, which is a reentrant standard C library for embedded systems + comprising of non GPL'd code.</para> + + </sect1> + + <sect1 id=releng xreflabel="Remote Host Testing"> + <title>Remote Host Testing</title> + + <note><para>Thanks to Dj Delorie for the original paper that + this section is based on.</para></note> + + <para>DejaGnu also supports running the tests on a remote + host. To set this up, the remote host needs an ftp server, and a + telnet server. Currently foreign operating systems used as + remote hosts are VxWorks, VRTX, Dos/Win3.1, MacOS, and + win95/win98/NT.</para> + + <para>The recommended source for a win95/win98/NT based ftp + server is to get IIS (either IIS 1 or Personal Web Server) from + <ulink + URL="http://www.microsoft.com">http://www.microsoft.com</ulink>. + When you install it, make sure you install the FTP server - it's + not selected by default. Go into the IIS manager and change the + FTP server so that it does not allow anonymous ftp. Set the home + directory to the root directory (i.e. c:\) of a suitable + drive. Allow writing via ftp.</para> + + <para>It will create an account like IUSR_FOOBAR where foobar is + the name of your machine. Go into the user editor and give that + account a password that you don't mind hanging around in the + clear (i.e. not the same as your admin or personal + passwords). Also, add it to all the various permission groups.</para> + + <para>You'll also need a telnet server. For win95/win98/NT, go + to the <ulink URL="http://ataman.com">Ataman</ulink> web site, + pick up the Ataman Remote Logon Services for Windows, and + install it. You can get started on the eval period anyway. Add + IUSR_FOOBAR to the list of allowed users, set the HOME directory + to be the same as the FTP default directory. Change the Mode + prompt to simple.</para> + + <para>Ok, now you need to pick a directory name to do all the + testing in. For the sake of this example, we'll call it piggy + (i.e. c:\piggy). Create this directory.</para> + + <para>You'll need a unix machine. Create a directory for the + scripts you'll need. For this example, we'll use + /usr/local/swamp/testing. You'll need to have a source tree + somewhere, say /usr/src/devo. Now, copy some files from + releng's area in SV to your machine:</para> + + <example> + <title>Remote host setup</title> + + <screen> + cd /usr/local/swamp/testing + mkdir boards + scp darkstar.welcomehome.org:/dejagnu/cst/bin/MkTestDir . + scp darkstar.welcomehome.org:/dejagnu/site.exp . + scp darkstar.welcomehome.org:/dejagnu/boards/useless98r2.exp boards/foobar.exp + export DEJAGNU=/usr/local/swamp/testing/site.exp + + </screen> + </example> + + <para>You must edit the boards/foobar.exp file to reflect your + machine; change the hostname (foobar.com), username + (iusr_foobar), password, and ftp_directory (c:/piggy) to match + what you selected.</para> + + <para>Edit the global <filename> site.exp</filename> to reflect your + boards directory:</para> + + <example> + <title>Add The Board Directory</title> + + <programlisting> + lappend boards_dir "/usr/local/swamp/testing/boards" + </programlisting> + </example> + + <para>Now run MkTestDir, which is in the contrib + directory. The first parameter is the toolchain prefix, the + second is the location of your devo tree. If you are testing a + cross compiler (ex: you have sh-hms-gcc.exe in your PATH on + the PC), do something like this:</para> + + <example> + <title>Setup Cross Remote Testing</title> + + <programlisting> + ./MkTestDir sh-hms /usr/dejagnu/src/devo + </programlisting> + </example> + + <para>If you are testing a native PC compiler (ex: you have + gcc.exe in your PATH on the PC), do this: + + <example> + <title>Setup Native Remote Testing</title> + + <programlisting> + ./MkTestDir '' /usr/dejagnu/src/devo + </programlisting> + </example> + + <para>To test the setup, <command>ftp</command> to your PC + using the username (iusr_foobar) and password you selected. CD + to the test directory. Upload a file to the PC. Now telnet to + your PC using the same username and password. CD to the test + directory. Make sure the file is there. Type "set" and/or "gcc + -v" (or sh-hms-gcc -v) and make sure the default PATH contains + the installation you want to test.</para> + + <example> + <title>Run Test Remotely</title> + + <programlisting> + cd /usr/local/swamp/testing + make -k -w check RUNTESTFLAGS="--host_board foobar --target_board foobar -v -v" > check.out 2>&1 + </programlisting> + </example> + + <para>To run a specific test, use a command like this (for + this example, you'd run this from the gcc directory that + MkTestDir created):</para> + + <example> + <title>Run a Test Remotely</title> + + <programlisting> + make check RUNTESTFLAGS="--host_board sloth --target_board sloth -v compile.exp=921202-1.c" + </programlisting> + </example> + + <para>Note: if you are testing a cross-compiler, put in the + correct target board. You'll also have to download more .exp + files and modify them for your local configuration. The -v's + are optional.</para> + + </sect1> + + <sect1 id=configfile xreflabel="Config File Values"> + <title>Config File Values</title> + + <para>DejaGnu uses a named array in Tcl to hold all the info for + each machine. In the case of a canadian cross, this means host + information as well as target information. The named array is + called <symbol>target_info</symbol>, and it has two indices. The + following fields are part of the array.</para> + + <sect1 id=optiondefs xreflabel="Option Variables"> + <title>Command Line Option Variables</title> + + <para>In the user editable second section of the <xref + linkend=personal> you can not only override the configuration + variables captured in the first section, but also specify + default values for all on the <command>runtest</command> + command line options. Save for <option>--debug</option>, + <option>--help</option>, and <option>--version</option>, each + command line option has an associated Tcl variable. Use the + Tcl <command>set</command> command to specify a new default + value (as for the configuration variables). The following + table describes the correspondence between command line + options and variables you can set in + <filename>site.exp</filename>. <xref linkend=invoking>, for + explanations of the command-line options.</para> + + <para><table frame=all rowsep=0 colsep=0> + <title>Tcl Variables For Command Line Options</title> + + <tgroup cols=3 align="char" rowsep=1 colsep=0> + <thead><row> + <entry>runtest</entry><entry>Tcl</entry> + <entry>option</entry><entry>variable</entry><entry>description</entry> + </row></thead> + <tbody> + + <row> + <entry>--all</entry> + <entry>all_flag</entry> + <entry>display all test results if set</entry> + </row> + + <row> + <entry>--baud</entry> + <entry>baud</entry> + <entry>set the default baud rate to something other than + 9600.</entry> + </row> + + <row> + <entry>--connect</entry> + <entry>connectmode</entry> + <entry><command>rlogin</command>, + <command>telnet</command>, <command>rsh</command>, + <command>kermit</command>, <command>tip</command>, or + <command>mondfe</command></entry> + </row> + + <row> + <entry>--outdir</entry> + <entry>outdir</entry> + <entry>directory for <filename>tool.sum</filename> and + <filename>tool.log.</filename></entry> + </row> + + <row> + <entry>--objdir</entry> + <entry>objdir</entry> + <entry>directory for pre-compiled binaries</entry> + </row> + + <row> + <entry>--reboot</entry> + <entry>reboot</entry> + <entry>reboot the target if set to + <emphasis>"1"</emphasis>; do not reboot if set to + <emphasis>"0"</emphasis> (the default).</entry> + </row> + + <row> + <entry>--srcdir</entry> + <entry>srcdir</entry> + <entry>directory of test subdirectories</entry> + </row> + + <row> + <entry>--strace</entry> + <entry>tracelevel</entry> + <entry>a number: Tcl trace depth</entry> + </row> + + <row> + <entry>--tool</entry> + <entry>tool</entry> + <entry>name of tool to test; identifies init, test subdir</entry> + </row> + + <row> + <entry>--verbose</entry> + <entry>verbose</entry> + <entry>verbosity level. As option, use multiple times; as + variable, set a number, 0 or greater.</entry> + </row> + + <row> + <entry>--target</entry> + <entry>target_triplet</entry> + <entry>The canonical configuration string for the target.</entry> + </row> + + <row> + <entry>--host</entry> + <entry>host_triplet</entry> + <entry>The canonical configuration string for the host.</entry> + </row> + + <row> + <entry>--build</entry> + <entry>build_triplet</entry> + <entry>The canonical configuration string for the build + host.</entry> + </row> + + </tbody> + </tgroup> + </table> + </para> + + </sect1> + + <sect1 id=personal xreflabel="Personal Config File"> + <title>Personal Config File</title> + + <para>The personal config file is used to customize + <command>runtest's</command> behaviour for each person. It's + typically used to set the user prefered setting for verbosity, + and any experimental Tcl procedures. My personal + <filename>~/.dejagnurc</filename> file looks like:</para> + + <example> + <title>Personal Config File</title> + + <programlisting> + set all_flag 1 + set RLOGIN /usr/ucb/rlogin + set RSH /usr/local/sbin/ssh + </programlisting> + </example> + + <para>Here I set <symbol>all_flag</symbol> so I see all the test + cases that PASS along with the ones that FAIL. I also set + <symbol>RLOGIN</symbol> to the BSD version. I have + <productname>Kerberos</productname> installed, and when I rlogin + to a target board, it usually isn't supported. So I use the non + secure version rather than the default that's in my path. I also + set <symbol>RSH</symbol> to the <productname>SSH</productname> + secure shell, as rsh is mostly used to test unix + machines within a local network here.</para> + + </sect1> + + </chapter> + + <chapter id=Extending xreflabel="Extending DejaGnu"> + <title>Extending DejaGnu</title> + + <sect1 id=addsuite xreflabel="Adding a new Test Suite"> + <title>Adding A New Test Suite</title> + + <para>The testsuite for a new tool should always be located in that tools + source directory. DejaGnu require the directory be named + <filename>testsuite</filename>. Under this directory, the test cases go + in a subdirectory whose name begins with the tool name. For example, for + a tool named <emphasis>flubber</emphasis>, each subdirectory containing + testsuites must start with <emphasis>"flubber."</emphasis>.</para> + + </sect1> + + <sect1 id=addtool xreflabel="Adding A New Tool"> + <title>Adding A New Tool</title> + + <para>In general, the best way to learn how to write (code or even prose) + is to read something similar. This principle applies to test cases and + to test suites. Unfortunately, well-established test suites have a way + of developing their own conventions: as test writers become more + experienced with DejaGnu and with Tcl, they accumulate more utilities, + and take advantage of more and more features of + <productname>Expect</productname> and <productname>Tcl</productname> in + general.</para> + + <para>Inspecting such established test suites may make the prospect of + creating an entirely new test suite appear overwhelming. Nevertheless, + it is quite straightforward to get a new test suite going.</para> + + <para>There is one test suite that is guaranteed not to grow more + elaborate over time: both it and the tool it tests were created expressly + to illustrate what it takes to get started with DejaGnu. The + <filename>example/</filename> directory of the DejaGnu distribution + contains both an interactive tool called <command>calc</command>, and a + test suite for it. Reading this test suite, and experimenting with it, + is a good way to supplement the information in this section. (Thanks to + Robert Lupton for creating calc and its test suite---and also the first + version of this section of the manual!)</para> + + <para>To help orient you further in this task, here is an outline of the + steps to begin building a test suite for a program example.</para> + + <itemizedlist mark=bullet> + + <listitem><para>Create or select a directory to contain your new + collection of tests. Change into that directory (shown here as + <filename>testsuite</filename>):</para> + + <para>Create a <filename>configure.in</filename> file in this directory, + to control configuration-dependent choices for your tests. So far as + DejaGnu is concerned, the important thing is to set a value for the + variable <symbol>target_abbrev</symbol>; this value is the link to the + init file you will write soon. (For simplicity, we assume the + environment is Unix, and use <emphasis>unix</emphasis> as the + value.)</para> + + <para>What else is needed in <filename>configure.in</filename> depends on + the requirements of your tool, your intended test environments, and which + configure system you use. This example is a minimal configure.in for use + with <productname>GNU Autoconf</productname>. </para></listitem> + + <listitem><para>Create <filename>Makefile.in</filename> (if you are using + Autoconf), or <filename>Makefile.am</filename>(if you are using + Automake), the source file used by configure to build your + <filename>Makefile</filename>. If you are using GNU Automake.just add the + keyword <emphasis>dejagnu</emphasis> to the + <emphasis>AUTOMAKE_OPTIONS</emphasis> variable in your + <filename>Makefile.am</filename> file. This will add all the Makefile + support needed to run DejaGnu, and support the <xref linkend=makecheck> + target.</para> + + <para>You also need to include two targets important to DejaGnu: + <emphasis>check</emphasis>, to run the tests, and + <emphasis>site.exp</emphasis>, to set up the Tcl copies of + configuration-dependent values. This is called the <xref linkend=local> + The check target must run the <command>runtest</command> program to + execute the tests.</para> + + <para>The <filename>site.exp</filename> target should usually set up + (among other things) the $tool variable for the name of your program. If + the local site.exp file is setup correctly, it is possible to execute the + tests by merely typing <command>runtest</command> on the command + line.</para> + + <example> + <title>Sample Makefile.in Fragment</title> + + <programlisting> + # Look for a local version of DejaGnu, otherwise use one in the path + RUNTEST = `if test -f $(top_srcdir)/../dejagnu/runtest; then \ + echo $(top_srcdir) ../dejagnu/runtest; \ + else \ + echo runtest; \ + fi` + + # The flags to pass to runtest + RUNTESTFLAGS = + + # Execute the tests + check: site.exp all + $(RUNTEST) $(RUNTESTFLAGS) \ + --tool <symbol>${example}</symbol> --srcdir $(srcdir) + + # Make the local config file + site.exp: ./config.status Makefile + @echo "Making a new config file..." + -@rm -f ./tmp? + @touch site.exp + + -@mv site.exp site.bak + @echo "## these variables are automatically\ + generated by make ##" > ./tmp0 + @echo "# Do not edit here. If you wish to\ + override these values" >> ./tmp0 + @echo "# add them to the last section" >> ./tmp0 + @echo "set host_os ${host_os}" >> ./tmp0 + @echo "set host_alias ${host_alias}" >> ./tmp0 + @echo "set host_cpu ${host_cpu}" >> ./tmp0 + @echo "set host_vendor ${host_vendor}" >> ./tmp0 + @echo "set target_os ${target_os}" >> ./tmp0 + @echo "set target_alias ${target_alias}" >> ./tmp0 + @echo "set target_cpu ${target_cpu}" >> ./tmp0 + @echo "set target_vendor ${target_vendor}" >> ./tmp0 + @echo "set host_triplet ${host_canonical}" >> ./tmp0 + @echo "set target_triplet ${target_canonical}">>./tmp0 + @echo "set tool binutils" >> ./tmp0 + @echo "set srcdir ${srcdir}" >> ./tmp0 + @echo "set objdir `pwd`" >> ./tmp0 + @echo "set <symbol>${examplename}</symbol> <symbol>${example}</symbol>" >> ./tmp0 + @echo "## All variables above are generated by\ + configure. Do Not Edit ##" >> ./tmp0 + @cat ./tmp0 > site.exp + @sed < site.bak \ + -e '1,/^## All variables above are.*##/ d' \ + >> site.exp + -@rm -f ./tmp? + + </programlisting> + </example> + </listitem> + + <listitem><para>Create a directory (in <filename>testsuite</filename>) + called <filename>config</filename>. Make a <emphasis>Tool Init + File</emphasis> in this directory. Its name must start with the + <symbol>target_abbrev</symbol> value, or be named + <filename>default.exp</filename> so call it + <filename>config/unix.exp</filename> for our Unix based example. This + is the file that contains the target-dependent procedures. + Fortunately, on Unix, most of them do not have to do very much in + order for <command>runtest</command> to run.</para> + + <para>If the program being tested is not interactive, you can get + away with this minimal <filename>unix.exp</filename> to begin + with:</para> + + <example> + <title>Simple Batch Program Tool Init File</title> + + <programlisting> + + proc foo_exit {} {} + proc foo_version {} {} + + </programlisting> + </example> + + <para>If the program being tested is interactive, however, you might + as well define a <emphasis>start</emphasis> routine and invoke it by + using an init file like this:</para> + + <example> + <title>Simple Interactive Program Tool Init File</title> + + <programlisting> + + proc foo_exit {} {} + proc foo_version {} {} + + proc foo_start {} { + global ${examplename} + spawn ${examplename} + expect { + -re "" {} + } + } + + # Start the program running we want to test + foo_start + + </programlisting> + </example> + </listitem> + + <listitem><para>Create a directory whose name begins with your tool's + name, to contain tests. For example, if your tool's name is + <emphasis>gcc</emphasis>, then the directories all need to start with + <emphasis>"gcc."</emphasis>.</para></listitem> + + <listitem><para>Create a sample test file. Its name must end with + <filename>.exp</filename>. You can use + <filename>first-try.exp</filename>. To begin with, just write there a + line of Tcl code to issue a message.</para> + + <example> + <title>Testing A New Tool Config</title> + + <programlisting> + + send_user "Testing: one, two...\n" + + </programlisting> + </example> + </listitem> + + <listitem><para>Back in the <filename>testsuite</filename> (top + level) directory, run <command>configure</command>. Typically you do + this while in the build directory. You may have to specify more of a + path, if a suitable configure is not available in your execution + path.</para></listitem> + + <listitem><para>e now ready to triumphantly type <command>make + check</command> or <command>runtest</command>. You should see + something like this:</para> + + <example> + <title>Example Test Case Run</title> + + <screen> + Test Run By rhl on Fri Jan 29 16:25:44 EST 1993 + + === example tests === + + Running ./example.0/first-try.exp ... + Testing: one, two... + + === example Summary === + + </screen> + </example> + + <para>There is no output in the summary, because so far the example + does not call any of the procedures that establish a test + outcome.</para></listitem> + + <listitem><para>Write some real tests. For an interactive tool, you + should probably write a real exit routine in fairly short order. In + any case, you should also write a real version routine + soon. </para></listitem> + + </itemizedlist> + + </sect1> + + <sect1 id=addtarget xreflabel="Adding A New Target"> + <title>Adding A New Target</title> + + <para>DejaGnu has some additional requirements for target support, beyond + the general-purpose provisions of configure. DejaGnu must actively + communicate with the target, rather than simply generating or managing + code for the target architecture. Therefore, each tool requires an + initialization module for each target. For new targets, you must supply + a few Tcl procedures to adapt DejaGnu to the target. This permits + DejaGnu itself to remain target independent.</para> + + <para>Usually the best way to write a new initialization module is to + edit an existing initialization module; some trial and error will be + required. If necessary, you can use the @samp{--debug} option to see what + is really going on.</para> + + <para>When you code an initialization module, be generous in printing + information controlled by the <function>verbose</function> + procedure.</para> + + <para>For cross targets, most of the work is in getting the + communications right. Communications code (for several situations + involving IP networks or serial lines) is available in a DejaGnu library + file.</para> + + <para>If you suspect a communication problem, try running the connection + interactively from <productname>Expect</productname>. (There are three + ways of running <productname>Expect</productname> as an interactive + interpreter. You can run <productname>Expect</productname> with no + arguments, and control it completely interactively; or you can use + <command>expect -i</command> together with other command-line options and + arguments; or you can run the command <command>interpreter</command> from + any <productname>Expect</productname> procedure. Use + <command>return</command> to get back to the calling procedure (if any), + or <command>return -tcl</command> to make the calling procedure itself + return to its caller; use <command>exi</command>t or end-of-file to leave + Expect altogether.) Run the program whose name is recorded in + <symbol>$connectmode</symbol>, with the arguments in + <symbol>$targetname</symbol>, to establish a connection. You should at + least be able to get a prompt from any target that is physically + connected.</para> + + </sect1> + + <sect1 id=addboard xreflabel="Adding A New Board"> + <title>Adding A New Board</title> + + <para>Adding a new board consists of creating a new board config + file. Examples are in + <filename>dejagnu/baseboards</filename>. Usually to make a new + board file, it's easiest to copy an existing one. It is also + possible to have your file be based on a + <emphasis>baseboard</emphasis> file with only one or two + changes needed. Typically, this can be as simple as just + changing the linker script. Once the new baseboard file is done, + add it to the <symbol>boards_DATA</symbol> list in the + <filename>dejagnu/baseboards/Makefile.am</filename>, and regenerate the + Makefile.in using automake. Then just rebuild and install DejaGnu. You + can test it by:</para> + + <para>There is a crude inheritance scheme going on with board files, so + you can include one board file into another, The two main procedures used + to do this are <function>load_generic_config</function> and + <function>load_base_board_description</function>. The generic config file + contains other procedures used for a certain class of target. The + board description file is where the board specfic settings go. Commonly + there are similar target environments with just different + processors.</para> + + <example> + <title>Testing a New Board Config File</title> + + <screen> + make check RUNTESTFLAGS="--target_board=<emphasis>newboardfile</emphasis>". + </screen> + </example> + + <para>Here's an example of a board config file. There are + several <emphasis>helper procedures</emphasis> used in this + example. A helper procedure is one that look for a tool of files + in commonly installed locations. These are mostly used when + testing in the build tree, because the executables to be tested + are in the same tree as the new dejagnu files. The helper + procedures are the ones in square braces + <emphasis>[]</emphasis>, which is the Tcl execution characters.</para> + + <example> + <title>Example Board Config File</title> + + <programlisting> + + # Load the generic configuration for this board. This will define a basic + # set of routines needed by the tool to communicate with the board. + load_generic_config "sim" + + # basic-sim.exp is a basic description for the standard Cygnus simulator. + load_base_board_description "basic-sim" + + # The compiler used to build for this board. This has *nothing* to do + # with what compiler is tested if we're testing gcc. + set_board_info compiler "[find_gcc]" + + # We only support newlib on this target. + # However, we include libgloss so we can find the linker scripts. + set_board_info cflags "[newlib_include_flags] [libgloss_include_flags]" + set_board_info ldflags "[newlib_link_flags]" + + # No linker script for this board. + set_board_info ldscript "-Tsim.ld"; + + # The simulator doesn't return exit statuses and we need to indicate this. + set_board_info needs_status_wrapper 1 + + # Can't pass arguments to this target. + set_board_info noargs 1 + + # No signals. + set_board_info gdb,nosignals 1 + + # And it can't call functions. + set_board_info gdb,cannot_call_functions 1 + + </programlisting> + </example> + + </sect1> + + <sect1 id=boarddefs xreflabel="Board File Values"> + <title>Board Config File Values</title> + + <para>These fields are all in the <symbol>board_info</symbol> These are + all set by using the <function>set_board_info</function> procedure. The + parameters are the field name, followed by the value to set the field + to.</para> + + <para><table frame=all rowsep=0 colsep=0> + <title>Common Board Info Fields</title> + + <tgroup cols=3 align="char" rowsep=1 colsep=0> + <thead><row> + <entry>Field</entry> + <entry>Sample Value</entry> + <entry>Description</entry> + </row></thead> + <tbody> + + <row> + <entry>compiler</entry> + <entry>"[find_gcc]"</entry> + <entry>The path to the compiler to use.</entry> + </row> + + <row> + <entry>cflags</entry> + <entry>"-mca"</entry> + <entry>Compilation flags for the compiler.</entry> + </row> + + <row> + <entry>ldflags</entry> + <entry>"[libgloss_link_flags] [newlib_link_flags]"</entry> + <entry>Linking flags for the compiler.</entry> + </row> + + <row> + <entry>ldscript</entry> + <entry>"-Wl,-Tidt.ld"</entry> + <entry>The linker script to use when cross compiling.</entry> + </row> + + <row> + <entry>libs</entry> + <entry>"-lgcc"</entry> + <entry>Any additional libraries to link in.</entry> + </row> + + <row> + <entry>shell_prompt</entry> + <entry>"cygmon>"</entry> + <entry>The command prompt of the remote shell.</entry> + </row> + + <row> + <entry>hex_startaddr</entry> + <entry>"0xa0020000"</entry> + <entry>The Starting address as a string.</entry> + </row> + + <row> + <entry>start_addr</entry> + <entry>0xa0008000</entry> + <entry>The starting address as a value.</entry> + </row> + + <row> + <entry>startaddr</entry> + <entry>"a0020000"</entry> + <entry></entry> + </row> + + <row> + <entry>exit_statuses_bad</entry> + <entry>1</entry> + <entry>Whether there is an accurate exit status.</entry> + </row> + + <row> + <entry>reboot_delay</entry> + <entry>10</entry> + <entry>The delay between power off and power on.</entry> + </row> + + <row> + <entry>unreliable</entry> + <entry>1</entry> + <entry>Whether communication with the board is unreliable.</entry> + </row> + + <row> + <entry>sim</entry> + <entry>[find_sim]</entry> + <entry>The path to the simulator to use.</entry> + </row> + + <row> + <entry>objcopy</entry> + <entry>$tempfil</entry> + <entry>The path to the <command>objcopy</command> program.</entry> + </row> + + <row> + <entry>support_libs</entry> + <entry>"${prefix_dir}/i386-coff/"</entry> + <entry>Support libraries needed for cross compiling.</entry> + </row> + + <row> + <entry>addl_link_flags</entry> + <entry>"-N"</entry> + <entry>Additional link flags, rarely used.</entry> + </row> + + </tbody> + </tgroup> + </table> + </para> + + <para>These fields are used by the GCC and GDB tests, and are mostly + only useful to somewhat trying to debug a new board file for one of + these tools. Many of these are used only by a few testcases, and their + purpose is esoteric. These are listed with sample values as a guide to + better guessing if you need to change any of these.</para> + + <para><table frame=all rowsep=0 colsep=0> + <title>Board Info Fields For GCC & GDB</title> + + <tgroup cols=3 align="char" rowsep=1 colsep=0> + <thead><row> + <entry>Field</entry> + <entry>Sample Value</entry> + <entry>Description</entry> + </row></thead> + <tbody> + + <row> + <entry>strip</entry> + <entry>$tempfile</entry> + <entry>Strip the executable of symbols.</entry> + </row> + + <row> + <entry>gdb_load_offset</entry> + <entry>"0x40050000"</entry> + </row> + + <row> + <entry>gdb_protocol</entry> + <entry>"remote"</entry> + <entry>The GDB debugging protocol to use.</entry> + </row> + + <row> + <entry>gdb_sect_offset</entry> + <entry>"0x41000000";</entry> + </row> + + <row> + <entry>gdb_stub_ldscript</entry> + <entry>"-Wl,-Teva-stub.ld"</entry> + <entry>The linker script to use with a GDB stub.</entry> + </row> + + <row> + <entry>gdb_init_command</entry> + <entry>"set mipsfpu none"</entry> + </row> + + <row> + <entry>gdb,cannot_call_functions</entry> + <entry>1</entry> + <entry>Whether GDB can call functions on the target,</entry> + </row> + + <row> + <entry>gdb,noargs</entry> + <entry>1</entry> + <entry>Whether the target can take command line arguments.</entry> + </row> + + <row> + <entry>gdb,nosignals</entry> + <entry>1</entry> + <entry>Whether there are signals on the target.</entry> + </row> + + <row> + <entry>gdb,short_int</entry> + <entry>1</entry> + </row> + + <row> + <entry>gdb,start_symbol</entry> + <entry>"_start";</entry> + <entry>The starting symbol in the executable.</entry> + </row> + + <row> + <entry>gdb,target_sim_options</entry> + <entry>"-sparclite"</entry> + <entry>Special options to pass to the simulator.</entry> + </row> + + <row> + <entry>gdb,timeout</entry> + <entry>540</entry> + <entry>Timeout value to use for remote communication.</entry> + </row> + + <row> + <entry>gdb_init_command</entry> + <entry>"print/x \$fsr = 0x0"</entry> + </row> + + <row> + <entry>gdb_load_offset</entry> + <entry>"0x12020000"</entry> + </row> + + <row> + <entry>gdb_opts</entry> + <entry>"--command gdbinit"</entry> + </row> + + <row> + <entry>gdb_prompt</entry> + <entry>"\\(gdb960\\)"</entry> + <entry>The prompt GDB is using.</entry> + </row> + + <row> + <entry>gdb_run_command</entry> + <entry>"jump start"</entry> + </row> + + <row> + <entry>gdb_stub_offset</entry> + <entry>"0x12010000"</entry> + </row> + + <row> + <entry>use_gdb_stub</entry> + <entry>1</entry> + <entry>Whether to use a GDB stub.</entry> + </row> + + <row> + <entry>use_vma_offset</entry> + <entry>1</entry> + </row> + + <row> + <entry>wrap_m68k_aout</entry> + <entry>1</entry> + </row> + + <row> + <entry>gcc,no_label_values</entry> + <entry>1</entry> + </row> + + <row> + <entry>gcc,no_trampolines</entry> + <entry>1</entry> + </row> + + <row> + <entry>gcc,no_varargs</entry> + <entry>1</entry> + </row> + + <row> + <entry>gcc,stack_size</entry> + <entry>16384</entry> + <entry>Stack size to use with some GCC testcases.</entry> + </row> + + <row> + <entry>ieee_multilib_flags</entry> + <entry>"-mieee";</entry> + </row> + + <row> + <entry>is_simulator</entry> + <entry>1</entry> + </row> + + <row> + <entry>needs_status_wrapper</entry> + <entry>1</entry> + </row> + + <row> + <entry>no_double</entry> + <entry>1</entry> + </row> + + <row> + <entry>no_long_long</entry> + <entry>1</entry> + </row> + + <row> + <entry>noargs</entry> + <entry>1</entry> + </row> + + <row> + <entry>nullstone,lib</entry> + <entry>"mips-clock.c"</entry> + </row> + + <row> + <entry>nullstone,ticks_per_sec</entry> + <entry>3782018</entry> + </row> + + <row> + <entry>sys_speed_value</entry> + <entry>200</entry> + </row> + + <row> + <entry>target_install</entry> + <entry>{sh-hms}</entry> + </row> + + </tbody> + </tgroup> + </table> + </para> + + </sect1> + + <sect1 id=writing xreflabel="Writing A Test Case"> + <title>Writing A Test Case</title> + + <para>The easiest way to prepare a new test case is to base it + on an existing one for a similar situation. There are two major + categories of tests: batch or interactive. Batch oriented tests + are usually easier to write.</para> + + <para>The GCC tests are a good example of batch oriented tests. + All GCC tests consist primarily of a call to a single common + procedure, Since all the tests either have no output, or only + have a few warning messages when successfully compiled. Any + non-warning output is a test failure. All the C code needed is + kept in the test directory. The test driver, written in Tcl, + need only get a listing of all the C files in the directory, and + compile them all using a generic procedure. This procedure and a + few others supporting for these tests are kept in the library + module <filename>lib/c-torture.exp</filename> in the GCC test + suite. Most tests of this kind use very few + <productname>expect</productname> features, and are coded almost + purely in Tcl.</para> + + <para>Writing the complete suite of C tests, then, consisted of + these steps:</para> + + <itemizedlist mark=bullet> + <listitem><para>Copying all the C code into the test directory. + These tests were based on the C-torture test created by Torbjorn + Granlund (on behalf of the Free Software Foundation) for GCC + development.</para></listitem> + + <listitem><para>Writing (and debugging) the generic Tcl procedures for + compilation.</para></listitem> + + <listitem><para>Writing the simple test driver: its main task is to + search the directory (using the Tcl procedure + <emphasis>glob</emphasis> for filename expansion with wildcards) + and call a Tcl procedure with each filename. It also checks for + a few errors from the testing procedure.</para></listitem> + </itemizedlist> + + <para>Testing interactive programs is intrinsically more + complex. Tests for most interactive programs require some trial + and error before they are complete.</para> + + <para>However, some interactive programs can be tested in a + simple fashion reminiscent of batch tests. For example, prior + to the creation of DejaGnu, the GDB distribution already + included a wide-ranging testing procedure. This procedure was + very robust, and had already undergone much more debugging and + error checking than many recent DejaGnu test cases. + Accordingly, the best approach was simply to encapsulate the + existing GDB tests, for reporting purposes. Thereafter, new GDB + tests built up a family of Tcl procedures specialized for GDB + testing.</para> + + </sect1> + + <sect1 id=debugging xreflabel="Debugging A Test Case"> + <title>Debugging A Test Case</title> + + <para>These are the kinds of debugging information available + from DejaGnu:</para> + + <itemizedlist mark=bullet> + + <listitem><para>Output controlled by test scripts themselves, + explicitly allowed for by the test author. This kind of + debugging output appears in the detailed output recorded in the + DejaGnu log file. To do the same for new tests, use the + <command>verbose</command> procedure (which in turn uses the + variable also called <emphasis>verbose</emphasis>) to control + how much output to generate. This will make it easier for other + people running the test to debug it if necessary. Whenever + possible, if <emphasis>$verbose</emphasis> is + <emphasis>0</emphasis>, there should be no output other than the + output from <emphasis>pass</emphasis>, + <emphasis>fail</emphasis>, <emphasis>error</emphasis>, and + <emphasis>warning</emphasis>. Then, to whatever extent is + appropriate for the particular test, allow successively higher + values of <emphasis>$verbose</emphasis> to generate more + information. Be kind to other programmers who use your tests: + provide for a lot of debugging information.</para> + + <listitem><para>Output from the internal debugging functions of + Tcl and <productname>Expect</productname>. There is a command + line options for each; both forms of debugging output are + recorded in the file <filename>dbg.log</filename> in the current + directory.</para> + + <para>Use <option>--debug</option> for information from the + expect level; it generates displays of the expect attempts to + match the tool output with the patterns specified. This output + can be very helpful while developing test scripts, since it + shows precisely the characters received. Iterating between the + latest attempt at a new test script and the corresponding + <filename>dbg.log</filename> can allow you to create the final + patterns by ``cut and paste''. This is sometimes the best way + to write a test case.</para> + + <listitem><para>Use <option>--strace</option> to see more + detail at the Tcl level; this shows how Tcl procedure + definitions expand, as they execute. The associated number + controls the depth of definitions expanded.</para></listitem> + + <listitem><para>Finally, if the value of + <emphasis>verbose</emphasis> is 3 or greater,DejaGnu turns on + the expect command <command>log_user</command>. This command + prints all expect actions to the expect standard output, to the + detailed log file, and (if <option>--debug</option> is on) to + <filename>dbg.log</filename>.</para> + </itemizedlist> + + </sect1> + + <sect1 id=adding xreflabel="Adding A Test Case To A Test Suite"> + <title>Adding A Test Case To A Test Suite.</title> + + <para>There are two slightly different ways to add a test + case. One is to add the test case to an existing directory. The + other is to create a new directory to hold your test. The + existing test directories represent several styles of testing, + all of which are slightly different; examine the directories for + the tool of interest to see which (if any) is most suitable.</para> + + <para>Adding a GCC test can be very simple: just add the C code + to any directory beginning with <filename>gcc</filename>. and it + runs on the next <programlisting>runtest --tool + gcc</programlisting>.</para> + + <para>To add a test to GDB, first add any source code you will + need to the test directory. Then you can either create a new + expect file, or add your test to an existing one (any + file with a <emphasis>.exp</emphasis> suffix). Creating a new + .exp file is probably a better idea if the test is significantly + different from existing tests. Adding it as a separate file also + makes upgrading easier. If the C code has to be already compiled + before the test will run, then you'll have to add it to the + <filename>Makefile.in</filename> file for that test directory, + then run <command>configure</command> and + <command>make</command>.</para> + + <para>Adding a test by creating a new directory is very + similar:</para> + + <itemizedlist mark=bullet> + + <listitem><para>Create the new directory. All subdirectory names + begin with the name of the tool to test; e.g. G++ tests might be + in a directory called <filename>g++.other</filename>. There can + be multiple test directories that start with the same tool name + (such as <emphasis>g++</emphasis>).</para></listitem> + + <listitem><para>Add the new directory name to the + <symbol>configdirs</symbol> definition in the + <filename>configure.in</filename> file for the test suite + directory. This way when <command>make</command> and + <command>configure</command> next run, they include the new + directory.</para></listitem> + + <listitem><para>Add the new test case to the directory, as + above. </para> + + <listitem><para>To add support in the new directory for + configure and make, you must also create a + <filename>Makefile.in</filename> and a + <filename>configure.in</filename>.</para></listitem> + </itemizedlist> + + </sect1> + + <sect1 id=hints xreflabel="Hints On Writing A Test Case"> + <title>Hints On Writing A Test Case</title> + + <para>It is safest to write patterns that match all the output + generated by the tested program; this is called closure. + If a pattern does not match the entire output, any output that + remains will be examined by the next <command>expect</command> + command. In this situation, the precise boundary that determines + which <command>expect</command> command sees what is very + sensitive to timing between the Expect task and the task running + the tested tool. As a result, the test may sometimes appear to + work, but is likely to have unpredictable results. (This problem + is particularly likely for interactive tools, but can also + affect batch tools---especially for tests that take a long time + to finish.) The best way to ensure closure is to use the + <option>-re</option> option for the <command>expect</command> + command to write the pattern as a full regular expressions; then + you can match the end of output using a <emphasis>$</emphasis>. + It is also a good idea to write patterns that match all + available output by using <emphasis>.*\</emphasis> after the + text of interest; this will also match any intervening blank + lines. Sometimes an alternative is to match end of line using + <emphasis>\r</emphasis> or <emphasis>\n</emphasis>, but this is + usually too dependent on terminal settings.</para> + + <para>Always escape punctuation, such as <emphasis>(</emphasis> + or <emphasis>"</emphasis>, in your patterns; for example, write + <emphasis>\(</emphasis>. If you forget to escape punctuation, + you will usually see an error message like <programlisting>extra + characters after close-quote.</programlisting></para> + + <para>If you have trouble understanding why a pattern does not + match the program output, try using the <option>--debug</option> + option to <command>runtest</command>, and examine the debug log + carefully.</para> + + <para>Be careful not to neglect output generated by setup rather + than by the interesting parts of a test case. For example, + while testing GDB, I issue a send <emphasis>set height + 0\n</emphasis> command. The purpose is simply to make sure GDB + never calls a paging program. The <emphasis>set + height</emphasis> command in GDB does not generate any + output; but running any command makes GDB issue a new + <emphasis>(gdb) </emphasis> prompt. If there were no + <command>expect</command> command to match this prompt, the + output <emphasis>(gdb) </emphasis> begins the text seen by the + next <command>expect</command> command---which might make that + pattern fail to match.</para> + + <para>To preserve basic sanity, I also recommended that no test + ever pass if there was any kind of problem in the test case. To + take an extreme case, tests that pass even when the tool will + not spawn are misleading. Ideally, a test in this sort of + situation should not fail either. Instead, print an error + message by calling one of the DejaGnu procedures + <command>error</command> or <command>warning</command>.</para> + + </sect1> + + <sect1 id=tvariables xreflabel="Test Case Variables"> + <title>Special variables used by test cases.</title> + + <para>There are special variables used by test cases. These contain + other information from DejaGnu. Your test cases can use these variables, + with conventional meanings (as well as the variables saved in + <filename>site.exp</filename>. You can use the value of these variables, + but they should never be changed.</para> + + <variablelist> + <varlistentry> + <term>$prms_id</term> + <listitem><para>The tracking system (e.g. GNATS) number identifying + a corresponding bugreport. (<emphasis>0</emphasis>} if you do not + specify it in the test script.)</para></listitem> + </varlistentry> + + <varlistentry> + <term>$item bug_id</term> + <listitem><para>An optional bug id; may reflect a bug + identification from another organization. (<emphasis>0</emphasis> + if you do not specify it.)</para></listitem> + </varlistentry> + + <varlistentry> + <term>$subdir</term> + <listitem><para>The subdirectory for the current test + case.</para></listitem> + </varlistentry> + + <varlistentry> + <term>$expect_out(buffer)</term> + <listitem><para>The output from the last command. This is an + internal variable set by Expect. More information can be found in + the Expect manual.</para></listitem> + </varlistentry> + + <varlistentry> + <term>$exec_output</term> + <listitem><para>This is the output from a + <function>${tool}_load</function> command. This only applies to + tools like GCC and GAS which produce an object file that must in + turn be executed to complete a test.</para></listitem> + </varlistentry> + + <varlistentry> + <term>$comp_output</term> + <listitem><para>This is the output from a + <function>${tool}_start</function> command. This is conventionally + used for batch oriented programs, like GCC and GAS, that may + produce interesting output (warnings, errors) without further + interaction.</para></listitem> + </varlistentry> + </variablelist> + + </sect1> + +</chapter> + |