From: Ben Elliston Date: Fri, 23 Dec 2005 20:39:29 +0000 (+0000) Subject: * Makefile.am (SUBDIRS): Remove. X-Git-Tag: upstream/1.6.2~386 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=7f69ac779dd79b8123b5691bc22f9797e8d04144;p=platform%2Fupstream%2Fdejagnu.git * Makefile.am (SUBDIRS): Remove. (EXTRA_DIST): Append $(XML). (dist_man_MANS): Define. (info_TEXINFOS): Likewise. (XML): List XML source files. (dejagnu.pdf): New target. (dejagnu.ps): Likewise. (dejagnu.rtf): Likewise. (html): Likewise. (dejagnu.texi): Special rule to build Texinfo source. * Makefile.in: Regenerate. * configure.ac: Don't search for docbook2dvi. Search for docbook2rtf and docbook2pdf. Don't output doc/Makefile or doc/C/Makefile. * configure: Regenerate. * doc/texinfo.tex: Move from here .. * texinfo.tex: .. to here. * doc/Makefile.am: Remove. * doc/Makefile.in: Likewise. * doc/C/dejagnu.omf: Likewise. * doc/C/topic.dat: Likewise. * doc/C/dejagnu.xml: Move from here .. * doc/dejagnu.xml: .. to here. * doc/C/legal.xml: Move from here .. * doc/legal.xml: .. to here. * doc/C/ref.xml: Move from here .. * doc/ref.xml: .. to here. * doc/C/user.xml: Move from here .. * doc/user.xml: .. to here. * doc/dejagnu.texi: Rebuild from XML source. --- diff --git a/Makefile.am b/Makefile.am index dbf4e1c..54f542e 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,7 +1,6 @@ # Process this file with automake to generate Makefile.in AUTOMAKE_OPTIONS = dejagnu -SUBDIRS = doc EXTRA_DIST = ChangeLog.0 MAINTAINERS runtest site.tmpl \ $(pkgdata_DATA) $(pkgdata_SCRIPTS) \ @@ -9,6 +8,7 @@ EXTRA_DIST = ChangeLog.0 MAINTAINERS runtest site.tmpl \ $(baseboard_DATA) $(baseboard_SCRIPTS) \ $(PACKAGING_METAFILES) $(TESTSUITE_FILES) + $(XML) bin_SCRIPTS = runtest include_HEADERS = dejagnu.h @@ -167,6 +167,8 @@ pkgdata_DATA = stub-loader.c testglue.c djlibexecdir = $(pkgdatadir)/libexec djlibexec_SCRIPTS = config.guess +# Testsuite. + TESTSUITE_FILES = \ testsuite/runtest.all/topdir/subdir1/subsubdir1/subsubfile1 \ testsuite/runtest.all/topdir/subdir1/subfile1 \ @@ -187,19 +189,55 @@ TESTSUITE_FILES = \ testsuite/lib/util-defs.exp \ testsuite/libdejagnu/tunit.exp +RUNTEST = `if [ -f ${top_srcdir}/runtest$(EXEEXT) ] ; then \ + echo ${top_srcdir}/runtest$(EXEEXT); \ + else echo "ERROR: runtest not found" ; exit 1; fi` + +RUNTESTDEFAULTFLAGS = --tool runtest --srcdir $(srcdir)/testsuite RUNTEST=$(RUNTEST) +AM_CXXFLAGS = -I$(top_srcdir) -g +check_PROGRAMS = unit +unit_SOURCES = testsuite/libdejagnu/unit.cc + +# Documentation. + +dist_man_MANS = doc/runtest.1 +info_TEXINFOS = doc/dejagnu.texi + +XML = doc/dejagnu.xml doc/legal.xml doc/ref.xml doc/user.xml + +dejagnu.pdf: $(XML) + docbook2pdf $(srcdir)/doc/dejagnu.xml + +dejagnu.ps: $(XML) + docbook2ps $(srcdir)/doc/dejagnu.xml + +dejagnu.rtf: $(XML) + docbook2rtf $(srcdir)/doc/dejagnu.xml + +html: + docbook2html -o html $(srcdir)/doc/dejagnu.xml + +doc/dejagnu.texi: $(XML) + db2x_xsltproc -s texi $(srcdir)/doc/dejagnu.xml -o dejagnu.txml + db2x_texixml dejagnu.txml + mv dejagnu.texi $(srcdir)/doc + rm dejagnu.txml + +# Packaging. + PACKAGING_METAFILES = packaging/depot/dejagnu.psf \ packaging/deb/site.exp packaging/deb/changelog packaging/deb/conffiles \ packaging/deb/control packaging/deb/copyright packaging/deb/postinst \ packaging/deb/preinst packaging/deb/rules packaging/pkg/pkginfo \ packaging/pkg/prototype packaging/rpm/dejagnu.spec -# Build an RPM package +# RPM rpm: dist $(srcdir)/packaging/rpm/dejagnu.spec cp -f $(srcdir)/packaging/rpm/dejagnu.spec /usr/src/redhat/SPECS/ cp -f dejagnu-${VERSION}.tar.gz /usr/src/redhat/SOURCES/ rpm -ba /usr/src/redhat/SPECS/dejagnu.spec -# Build a Debian GNU/Linux package +# Debian GNU/Linux package deb: dist rm -rf dejagnu-${VERSION} tar xfz dejagnu-${VERSION}.tar.gz @@ -216,7 +254,7 @@ $(PKGDIR)/dejagnu: $(srcdir)/configure -v --prefix $@ make install -# Build a Solaris package +# Solaris package solpkg: $(PKGDIR)/dejagnu cp $(srcdir)/packaging/pkg/prototype /tmp cp $(srcdir)/packaging/pkg/pkginfo /tmp @@ -227,7 +265,7 @@ solpkg: $(PKGDIR)/dejagnu gzip -9fv $$here/dejagnu-${VERSION}.SPARC.2.8.pkg.tar rm -rf /tmp/prototype /tmp/pkginfo /tmp/DejaGnu -# Build a HP depot package +# HP depot package hpdepot: $(PKGDIR)/dejagnu swpackage -s $(srcdir)/packaging/depot/dejagnu.psf -x target_type=directory -d /tmp here=`pwd`; \ @@ -235,12 +273,3 @@ hpdepot: $(PKGDIR)/dejagnu tar cf $$here/dejagnu-${VERSION}.hpux11.depot dejagnu; \ gzip -9fv $$here/dejagnu-${VERSION}.hpux11.depot; \ rm -rf /tmp/dejagnu - -RUNTEST = `if [ -f ${top_srcdir}/runtest$(EXEEXT) ] ; then \ - echo ${top_srcdir}/runtest$(EXEEXT); \ - else echo "ERROR: runtest not found" ; exit 1; fi` - -RUNTESTDEFAULTFLAGS = --tool runtest --srcdir $(srcdir)/testsuite RUNTEST=$(RUNTEST) -AM_CXXFLAGS = -I$(top_srcdir) -g -check_PROGRAMS = unit -unit_SOURCES = testsuite/libdejagnu/unit.cc diff --git a/Makefile.in b/Makefile.in index 9deaba6..501ea53 100644 --- a/Makefile.in +++ b/Makefile.in @@ -40,11 +40,11 @@ PRE_UNINSTALL = : POST_UNINSTALL = : check_PROGRAMS = unit$(EXEEXT) subdir = . -DIST_COMMON = README $(am__configure_deps) $(include_HEADERS) \ - $(srcdir)/Makefile.am $(srcdir)/Makefile.in \ +DIST_COMMON = README $(am__configure_deps) $(dist_man_MANS) \ + $(include_HEADERS) $(srcdir)/Makefile.am $(srcdir)/Makefile.in \ $(top_srcdir)/configure AUTHORS COPYING ChangeLog INSTALL NEWS \ TODO config.guess config.sub depcomp install-sh missing \ - mkinstalldirs + mkinstalldirs texinfo.tex ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/configure.ac am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ @@ -58,7 +58,8 @@ unit_OBJECTS = $(am_unit_OBJECTS) unit_LDADD = $(LDADD) am__installdirs = "$(DESTDIR)$(baseboarddir)" "$(DESTDIR)$(bindir)" \ "$(DESTDIR)$(configdir)" "$(DESTDIR)$(djlibexecdir)" \ - "$(DESTDIR)$(pkgdatadir)" "$(DESTDIR)$(baseboarddir)" \ + "$(DESTDIR)$(pkgdatadir)" "$(DESTDIR)$(infodir)" \ + "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(baseboarddir)" \ "$(DESTDIR)$(configdir)" "$(DESTDIR)$(pkgdatadir)" \ "$(DESTDIR)$(includedir)" baseboardSCRIPT_INSTALL = $(INSTALL_SCRIPT) @@ -78,12 +79,22 @@ CXXLINK = $(CXXLD) $(AM_CXXFLAGS) $(CXXFLAGS) $(AM_LDFLAGS) $(LDFLAGS) \ -o $@ SOURCES = $(unit_SOURCES) DIST_SOURCES = $(unit_SOURCES) -RECURSIVE_TARGETS = all-recursive check-recursive dvi-recursive \ - html-recursive info-recursive install-data-recursive \ - install-exec-recursive install-info-recursive \ - install-recursive installcheck-recursive installdirs-recursive \ - pdf-recursive ps-recursive uninstall-info-recursive \ - uninstall-recursive +am__dirstamp = $(am__leading_dot)dirstamp +INFO_DEPS = $(srcdir)/doc/dejagnu.info +am__TEXINFO_TEX_DIR = $(srcdir) +DVIS = doc/dejagnu.dvi +PDFS = doc/dejagnu.pdf +PSS = doc/dejagnu.ps +HTMLS = doc/dejagnu.html +TEXINFOS = doc/dejagnu.texi +TEXI2DVI = texi2dvi +TEXI2PDF = $(TEXI2DVI) --pdf --batch +MAKEINFOHTML = $(MAKEINFO) --html +AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) +DVIPS = dvips +man1dir = $(mandir)/man1 +NROFF = nroff +MANS = $(dist_man_MANS) am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; am__vpath_adj = case $$p in \ $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ @@ -99,7 +110,6 @@ HEADERS = $(include_HEADERS) ETAGS = etags CTAGS = ctags DEJATOOL = $(PACKAGE) -DIST_SUBDIRS = $(SUBDIRS) DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) distdir = $(PACKAGE)-$(VERSION) top_distdir = $(distdir) @@ -129,9 +139,10 @@ CXXFLAGS = @CXXFLAGS@ CYGPATH_W = @CYGPATH_W@ DEFS = @DEFS@ DEPDIR = @DEPDIR@ -DOCBOOK2DVI = @DOCBOOK2DVI@ DOCBOOK2HTML = @DOCBOOK2HTML@ DOCBOOK2PDF = @DOCBOOK2PDF@ +DOCBOOK2PS = @DOCBOOK2PS@ +DOCBOOK2RTF = @DOCBOOK2RTF@ ECHO_C = @ECHO_C@ ECHO_N = @ECHO_N@ ECHO_T = @ECHO_T@ @@ -195,7 +206,6 @@ subdirs = @subdirs@ sysconfdir = @sysconfdir@ target_alias = @target_alias@ AUTOMAKE_OPTIONS = dejagnu -SUBDIRS = doc EXTRA_DIST = ChangeLog.0 MAINTAINERS runtest site.tmpl \ $(pkgdata_DATA) $(pkgdata_SCRIPTS) \ $(config_DATA) $(config_SCRIPTS) \ @@ -356,6 +366,8 @@ baseboard_SCRIPTS = \ pkgdata_DATA = stub-loader.c testglue.c djlibexecdir = $(pkgdatadir)/libexec djlibexec_SCRIPTS = config.guess + +# Testsuite. TESTSUITE_FILES = \ testsuite/runtest.all/topdir/subdir1/subsubdir1/subsubfile1 \ testsuite/runtest.all/topdir/subdir1/subfile1 \ @@ -376,6 +388,20 @@ TESTSUITE_FILES = \ testsuite/lib/util-defs.exp \ testsuite/libdejagnu/tunit.exp +RUNTEST = `if [ -f ${top_srcdir}/runtest$(EXEEXT) ] ; then \ + echo ${top_srcdir}/runtest$(EXEEXT); \ + else echo "ERROR: runtest not found" ; exit 1; fi` + +RUNTESTDEFAULTFLAGS = --tool runtest --srcdir $(srcdir)/testsuite RUNTEST=$(RUNTEST) +AM_CXXFLAGS = -I$(top_srcdir) -g +unit_SOURCES = testsuite/libdejagnu/unit.cc + +# Documentation. +dist_man_MANS = doc/runtest.1 +info_TEXINFOS = doc/dejagnu.texi +XML = doc/dejagnu.xml doc/legal.xml doc/ref.xml doc/user.xml + +# Packaging. PACKAGING_METAFILES = packaging/depot/dejagnu.psf \ packaging/deb/site.exp packaging/deb/changelog packaging/deb/conffiles \ packaging/deb/control packaging/deb/copyright packaging/deb/postinst \ @@ -385,17 +411,10 @@ PACKAGING_METAFILES = packaging/depot/dejagnu.psf \ # Most proprietary Unices use /opt for optional packages. PKGDIR = /opt -RUNTEST = `if [ -f ${top_srcdir}/runtest$(EXEEXT) ] ; then \ - echo ${top_srcdir}/runtest$(EXEEXT); \ - else echo "ERROR: runtest not found" ; exit 1; fi` - -RUNTESTDEFAULTFLAGS = --tool runtest --srcdir $(srcdir)/testsuite RUNTEST=$(RUNTEST) -AM_CXXFLAGS = -I$(top_srcdir) -g -unit_SOURCES = testsuite/libdejagnu/unit.cc -all: all-recursive +all: all-am .SUFFIXES: -.SUFFIXES: .cc .o .obj +.SUFFIXES: .cc .dvi .o .obj .ps am--refresh: @: $(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) @@ -566,7 +585,153 @@ unit.obj: testsuite/libdejagnu/unit.cc @AMDEP_TRUE@@am__fastdepCXX_FALSE@ source='testsuite/libdejagnu/unit.cc' object='unit.obj' libtool=no @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCXX_FALSE@ DEPDIR=$(DEPDIR) $(CXXDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCXX_FALSE@ $(CXX) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CXXFLAGS) $(CXXFLAGS) -c -o unit.obj `if test -f 'testsuite/libdejagnu/unit.cc'; then $(CYGPATH_W) 'testsuite/libdejagnu/unit.cc'; else $(CYGPATH_W) '$(srcdir)/testsuite/libdejagnu/unit.cc'; fi` +doc/$(am__dirstamp): + @$(mkdir_p) doc + @: > doc/$(am__dirstamp) + +$(srcdir)/doc/dejagnu.info: doc/dejagnu.texi + restore=: && backupdir="$(am__leading_dot)am$$$$" && \ + am__cwd=`pwd` && cd $(srcdir) && \ + rm -rf $$backupdir && mkdir $$backupdir && \ + if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ + for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ + if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ + done; \ + else :; fi && \ + cd "$$am__cwd"; \ + if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I doc -I $(srcdir)/doc \ + -o $@ $(srcdir)/doc/dejagnu.texi; \ + then \ + rc=0; \ + cd $(srcdir); \ + else \ + rc=$$?; \ + cd $(srcdir) && \ + $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -rf $$backupdir; exit $$rc + +doc/dejagnu.dvi: doc/dejagnu.texi doc/$(am__dirstamp) + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I doc -I $(srcdir)/doc' \ + $(TEXI2DVI) -o $@ `test -f 'doc/dejagnu.texi' || echo '$(srcdir)/'`doc/dejagnu.texi + +doc/dejagnu.pdf: doc/dejagnu.texi doc/$(am__dirstamp) + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I doc -I $(srcdir)/doc' \ + $(TEXI2PDF) -o $@ `test -f 'doc/dejagnu.texi' || echo '$(srcdir)/'`doc/dejagnu.texi + +doc/dejagnu.html: doc/dejagnu.texi doc/$(am__dirstamp) + rm -rf $(@:.html=.htp) + if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I doc -I $(srcdir)/doc \ + -o $(@:.html=.htp) `test -f 'doc/dejagnu.texi' || echo '$(srcdir)/'`doc/dejagnu.texi; \ + then \ + rm -rf $@; \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \ + else \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \ + exit 1; \ + fi +.dvi.ps: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + $(DVIPS) -o $@ $< + uninstall-info-am: + @$(PRE_UNINSTALL) + @if (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ + install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ + done; \ + else :; fi + @$(NORMAL_UNINSTALL) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ + (if cd "$(DESTDIR)$(infodir)"; then \ + echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \ + rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ + else :; fi); \ + done + +dist-info: $(INFO_DEPS) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + for base in $$list; do \ + case $$base in \ + $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$base; then d=.; else d=$(srcdir); fi; \ + for file in $$d/$$base*; do \ + relfile=`expr "$$file" : "$$d/\(.*\)"`; \ + test -f $(distdir)/$$relfile || \ + cp -p $$file $(distdir)/$$relfile; \ + done; \ + done + +mostlyclean-aminfo: + -rm -rf dejagnu.aux dejagnu.cp dejagnu.cps dejagnu.fn dejagnu.ky dejagnu.log \ + dejagnu.pg dejagnu.pgs dejagnu.tmp dejagnu.toc dejagnu.tp \ + dejagnu.tps dejagnu.vr dejagnu.vrs doc/dejagnu.dvi \ + doc/dejagnu.pdf doc/dejagnu.ps doc/dejagnu.html + +maintainer-clean-aminfo: + @list='$(INFO_DEPS)'; for i in $$list; do \ + i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ + echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ + rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ + done +install-man1: $(man1_MANS) $(man_MANS) + @$(NORMAL_INSTALL) + test -z "$(man1dir)" || $(mkdir_p) "$(DESTDIR)$(man1dir)" + @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.1*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \ + else file=$$i; fi; \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 1*) ;; \ + *) ext='1' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst"; \ + done +uninstall-man1: + @$(NORMAL_UNINSTALL) + @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.1*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 1*) ;; \ + *) ext='1' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " rm -f '$(DESTDIR)$(man1dir)/$$inst'"; \ + rm -f "$(DESTDIR)$(man1dir)/$$inst"; \ + done install-baseboardDATA: $(baseboard_DATA) @$(NORMAL_INSTALL) test -z "$(baseboarddir)" || $(mkdir_p) "$(DESTDIR)$(baseboarddir)" @@ -636,77 +801,6 @@ uninstall-includeHEADERS: rm -f "$(DESTDIR)$(includedir)/$$f"; \ done -# This directory's subdirectories are mostly independent; you can cd -# into them and run `make' without going through this Makefile. -# To change the values of `make' variables: instead of editing Makefiles, -# (1) if the variable is set in `config.status', edit `config.status' -# (which will cause the Makefiles to be regenerated when you run `make'); -# (2) otherwise, pass the desired values on the `make' command line. -$(RECURSIVE_TARGETS): - @failcom='exit 1'; \ - for f in x $$MAKEFLAGS; do \ - case $$f in \ - *=* | --[!k]*);; \ - *k*) failcom='fail=yes';; \ - esac; \ - done; \ - dot_seen=no; \ - target=`echo $@ | sed s/-recursive//`; \ - list='$(SUBDIRS)'; for subdir in $$list; do \ - echo "Making $$target in $$subdir"; \ - if test "$$subdir" = "."; then \ - dot_seen=yes; \ - local_target="$$target-am"; \ - else \ - local_target="$$target"; \ - fi; \ - (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \ - || eval $$failcom; \ - done; \ - if test "$$dot_seen" = "no"; then \ - $(MAKE) $(AM_MAKEFLAGS) "$$target-am" || exit 1; \ - fi; test -z "$$fail" - -mostlyclean-recursive clean-recursive distclean-recursive \ -maintainer-clean-recursive: - @failcom='exit 1'; \ - for f in x $$MAKEFLAGS; do \ - case $$f in \ - *=* | --[!k]*);; \ - *k*) failcom='fail=yes';; \ - esac; \ - done; \ - dot_seen=no; \ - case "$@" in \ - distclean-* | maintainer-clean-*) list='$(DIST_SUBDIRS)' ;; \ - *) list='$(SUBDIRS)' ;; \ - esac; \ - rev=''; for subdir in $$list; do \ - if test "$$subdir" = "."; then :; else \ - rev="$$subdir $$rev"; \ - fi; \ - done; \ - rev="$$rev ."; \ - target=`echo $@ | sed s/-recursive//`; \ - for subdir in $$rev; do \ - echo "Making $$target in $$subdir"; \ - if test "$$subdir" = "."; then \ - local_target="$$target-am"; \ - else \ - local_target="$$target"; \ - fi; \ - (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \ - || eval $$failcom; \ - done && test -z "$$fail" -tags-recursive: - list='$(SUBDIRS)'; for subdir in $$list; do \ - test "$$subdir" = . || (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) tags); \ - done -ctags-recursive: - list='$(SUBDIRS)'; for subdir in $$list; do \ - test "$$subdir" = . || (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) ctags); \ - done - ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES) list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ unique=`for i in $$list; do \ @@ -717,23 +811,10 @@ ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES) mkid -fID $$unique tags: TAGS -TAGS: tags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ +TAGS: $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ $(TAGS_FILES) $(LISP) tags=; \ here=`pwd`; \ - if ($(ETAGS) --etags-include --version) >/dev/null 2>&1; then \ - include_option=--etags-include; \ - empty_fix=.; \ - else \ - include_option=--include; \ - empty_fix=; \ - fi; \ - list='$(SUBDIRS)'; for subdir in $$list; do \ - if test "$$subdir" = .; then :; else \ - test ! -f $$subdir/TAGS || \ - tags="$$tags $$include_option=$$here/$$subdir/TAGS"; \ - fi; \ - done; \ list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ unique=`for i in $$list; do \ if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ @@ -746,7 +827,7 @@ TAGS: tags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ $$tags $$unique; \ fi ctags: CTAGS -CTAGS: ctags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ +CTAGS: $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ $(TAGS_FILES) $(LISP) tags=; \ here=`pwd`; \ @@ -801,7 +882,7 @@ distclean-DEJAGNU: distdir: $(DISTFILES) $(am__remove_distdir) mkdir $(distdir) - $(mkdir_p) $(distdir)/baseboards $(distdir)/config $(distdir)/lib $(distdir)/packaging/deb $(distdir)/packaging/depot $(distdir)/packaging/pkg $(distdir)/packaging/rpm + $(mkdir_p) $(distdir)/baseboards $(distdir)/config $(distdir)/doc $(distdir)/lib $(distdir)/packaging/deb $(distdir)/packaging/depot $(distdir)/packaging/pkg $(distdir)/packaging/rpm @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ topsrcdirstrip=`echo "$(top_srcdir)" | sed 's|.|.|g'`; \ list='$(DISTFILES)'; for file in $$list; do \ @@ -828,21 +909,9 @@ distdir: $(DISTFILES) || exit 1; \ fi; \ done - list='$(DIST_SUBDIRS)'; for subdir in $$list; do \ - if test "$$subdir" = .; then :; else \ - test -d "$(distdir)/$$subdir" \ - || $(mkdir_p) "$(distdir)/$$subdir" \ - || exit 1; \ - distdir=`$(am__cd) $(distdir) && pwd`; \ - top_distdir=`$(am__cd) $(top_distdir) && pwd`; \ - (cd $$subdir && \ - $(MAKE) $(AM_MAKEFLAGS) \ - top_distdir="$$top_distdir" \ - distdir="$$distdir/$$subdir" \ - distdir) \ - || exit 1; \ - fi; \ - done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ + dist-info -find $(distdir) -type d ! -perm -777 -exec chmod a+rwx {} \; -o \ ! -type d ! -perm -444 -links 1 -exec chmod a+r {} \; -o \ ! -type d ! -perm -400 -exec chmod a+r {} \; -o \ @@ -943,22 +1012,21 @@ distcleancheck: distclean check-am: all-am $(MAKE) $(AM_MAKEFLAGS) $(check_PROGRAMS) $(MAKE) $(AM_MAKEFLAGS) check-DEJAGNU -check: check-recursive -all-am: Makefile $(SCRIPTS) $(DATA) $(HEADERS) -installdirs: installdirs-recursive -installdirs-am: - for dir in "$(DESTDIR)$(baseboarddir)" "$(DESTDIR)$(bindir)" "$(DESTDIR)$(configdir)" "$(DESTDIR)$(djlibexecdir)" "$(DESTDIR)$(pkgdatadir)" "$(DESTDIR)$(baseboarddir)" "$(DESTDIR)$(configdir)" "$(DESTDIR)$(pkgdatadir)" "$(DESTDIR)$(includedir)"; do \ +check: check-am +all-am: Makefile $(INFO_DEPS) $(SCRIPTS) $(MANS) $(DATA) $(HEADERS) +installdirs: + for dir in "$(DESTDIR)$(baseboarddir)" "$(DESTDIR)$(bindir)" "$(DESTDIR)$(configdir)" "$(DESTDIR)$(djlibexecdir)" "$(DESTDIR)$(pkgdatadir)" "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(baseboarddir)" "$(DESTDIR)$(configdir)" "$(DESTDIR)$(pkgdatadir)" "$(DESTDIR)$(includedir)"; do \ test -z "$$dir" || $(mkdir_p) "$$dir"; \ done -install: install-recursive -install-exec: install-exec-recursive -install-data: install-data-recursive -uninstall: uninstall-recursive +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am install-am: all-am @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am -installcheck: installcheck-recursive +installcheck: installcheck-am install-strip: $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ @@ -970,104 +1038,155 @@ clean-generic: distclean-generic: -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -rm -f doc/$(am__dirstamp) maintainer-clean-generic: @echo "This command is intended for maintainers to use" @echo "it deletes files that may require special tools to rebuild." -clean: clean-recursive +clean: clean-am clean-am: clean-checkPROGRAMS clean-generic mostlyclean-am -distclean: distclean-recursive +distclean: distclean-am -rm -f $(am__CONFIG_DISTCLEAN_FILES) -rm -rf ./$(DEPDIR) -rm -f Makefile distclean-am: clean-am distclean-DEJAGNU distclean-compile \ distclean-generic distclean-tags -dvi: dvi-recursive +dvi: dvi-am -dvi-am: +dvi-am: $(DVIS) -html: html-recursive +html-am: $(HTMLS) -info: info-recursive +info: info-am -info-am: +info-am: $(INFO_DEPS) install-data-am: install-baseboardDATA install-baseboardSCRIPTS \ install-configDATA install-configSCRIPTS \ - install-includeHEADERS install-pkgdataDATA \ - install-pkgdataSCRIPTS + install-includeHEADERS install-info-am install-man \ + install-pkgdataDATA install-pkgdataSCRIPTS install-exec-am: install-binSCRIPTS install-djlibexecSCRIPTS -install-info: install-info-recursive +install-info: install-info-am -install-man: +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + test -z "$(infodir)" || $(mkdir_p) "$(DESTDIR)$(infodir)" + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ + for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ + $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ + if test -f $$ifile; then \ + relfile=`echo "$$ifile" | sed 's|^.*/||'`; \ + echo " $(INSTALL_DATA) '$$ifile' '$(DESTDIR)$(infodir)/$$relfile'"; \ + $(INSTALL_DATA) "$$ifile" "$(DESTDIR)$(infodir)/$$relfile"; \ + else : ; fi; \ + done; \ + done + @$(POST_INSTALL) + @if (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ + install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ + done; \ + else : ; fi +install-man: install-man1 installcheck-am: -maintainer-clean: maintainer-clean-recursive +maintainer-clean: maintainer-clean-am -rm -f $(am__CONFIG_DISTCLEAN_FILES) -rm -rf $(top_srcdir)/autom4te.cache -rm -rf ./$(DEPDIR) -rm -f Makefile -maintainer-clean-am: distclean-am maintainer-clean-generic +maintainer-clean-am: distclean-am maintainer-clean-aminfo \ + maintainer-clean-generic -mostlyclean: mostlyclean-recursive +mostlyclean: mostlyclean-am -mostlyclean-am: mostlyclean-compile mostlyclean-generic +mostlyclean-am: mostlyclean-aminfo mostlyclean-compile \ + mostlyclean-generic -pdf: pdf-recursive +pdf: pdf-am -pdf-am: +pdf-am: $(PDFS) -ps: ps-recursive +ps: ps-am -ps-am: +ps-am: $(PSS) uninstall-am: uninstall-baseboardDATA uninstall-baseboardSCRIPTS \ uninstall-binSCRIPTS uninstall-configDATA \ uninstall-configSCRIPTS uninstall-djlibexecSCRIPTS \ - uninstall-includeHEADERS uninstall-info-am \ + uninstall-includeHEADERS uninstall-info-am uninstall-man \ uninstall-pkgdataDATA uninstall-pkgdataSCRIPTS -uninstall-info: uninstall-info-recursive +uninstall-man: uninstall-man1 -.PHONY: $(RECURSIVE_TARGETS) CTAGS GTAGS all all-am am--refresh check \ - check-DEJAGNU check-am clean clean-checkPROGRAMS clean-generic \ - clean-recursive ctags ctags-recursive dist dist-all dist-bzip2 \ - dist-gzip dist-shar dist-tarZ dist-zip distcheck distclean \ - distclean-DEJAGNU distclean-compile distclean-generic \ - distclean-recursive distclean-tags distcleancheck distdir \ - distuninstallcheck dvi dvi-am html html-am info info-am \ - install install-am install-baseboardDATA \ +.PHONY: CTAGS GTAGS all all-am am--refresh check check-DEJAGNU \ + check-am clean clean-checkPROGRAMS clean-generic ctags dist \ + dist-all dist-bzip2 dist-gzip dist-info dist-shar dist-tarZ \ + dist-zip distcheck distclean distclean-DEJAGNU \ + distclean-compile distclean-generic distclean-tags \ + distcleancheck distdir distuninstallcheck dvi dvi-am html \ + html-am info info-am install install-am install-baseboardDATA \ install-baseboardSCRIPTS install-binSCRIPTS install-configDATA \ install-configSCRIPTS install-data install-data-am \ install-djlibexecSCRIPTS install-exec install-exec-am \ install-includeHEADERS install-info install-info-am \ - install-man install-pkgdataDATA install-pkgdataSCRIPTS \ - install-strip installcheck installcheck-am installdirs \ - installdirs-am maintainer-clean maintainer-clean-generic \ - maintainer-clean-recursive mostlyclean mostlyclean-compile \ - mostlyclean-generic mostlyclean-recursive pdf pdf-am ps ps-am \ - tags tags-recursive uninstall uninstall-am \ + install-man install-man1 install-pkgdataDATA \ + install-pkgdataSCRIPTS install-strip installcheck \ + installcheck-am installdirs maintainer-clean \ + maintainer-clean-aminfo maintainer-clean-generic mostlyclean \ + mostlyclean-aminfo mostlyclean-compile mostlyclean-generic pdf \ + pdf-am ps ps-am tags uninstall uninstall-am \ uninstall-baseboardDATA uninstall-baseboardSCRIPTS \ uninstall-binSCRIPTS uninstall-configDATA \ uninstall-configSCRIPTS uninstall-djlibexecSCRIPTS \ - uninstall-includeHEADERS uninstall-info-am \ - uninstall-pkgdataDATA uninstall-pkgdataSCRIPTS + uninstall-includeHEADERS uninstall-info-am uninstall-man \ + uninstall-man1 uninstall-pkgdataDATA uninstall-pkgdataSCRIPTS $(TESTSUITE_FILES) + $(XML) + +dejagnu.pdf: $(XML) + docbook2pdf $(srcdir)/doc/dejagnu.xml + +dejagnu.ps: $(XML) + docbook2ps $(srcdir)/doc/dejagnu.xml + +dejagnu.rtf: $(XML) + docbook2rtf $(srcdir)/doc/dejagnu.xml + +html: + docbook2html -o html $(srcdir)/doc/dejagnu.xml + +dejagnu.texi: $(XML) + db2x_xsltproc -s texi $(srcdir)/doc/dejagnu.xml -o dejagnu.txml + db2x_texixml dejagnu.txml + mv dejagnu.texi $(srcdir)/doc + rm dejagnu.txml -# Build an RPM package +# RPM rpm: dist $(srcdir)/packaging/rpm/dejagnu.spec cp -f $(srcdir)/packaging/rpm/dejagnu.spec /usr/src/redhat/SPECS/ cp -f dejagnu-${VERSION}.tar.gz /usr/src/redhat/SOURCES/ rpm -ba /usr/src/redhat/SPECS/dejagnu.spec -# Build a Debian GNU/Linux package +# Debian GNU/Linux package deb: dist rm -rf dejagnu-${VERSION} tar xfz dejagnu-${VERSION}.tar.gz @@ -1081,7 +1200,7 @@ $(PKGDIR)/dejagnu: $(srcdir)/configure -v --prefix $@ make install -# Build a Solaris package +# Solaris package solpkg: $(PKGDIR)/dejagnu cp $(srcdir)/packaging/pkg/prototype /tmp cp $(srcdir)/packaging/pkg/pkginfo /tmp @@ -1092,7 +1211,7 @@ solpkg: $(PKGDIR)/dejagnu gzip -9fv $$here/dejagnu-${VERSION}.SPARC.2.8.pkg.tar rm -rf /tmp/prototype /tmp/pkginfo /tmp/DejaGnu -# Build a HP depot package +# HP depot package hpdepot: $(PKGDIR)/dejagnu swpackage -s $(srcdir)/packaging/depot/dejagnu.psf -x target_type=directory -d /tmp here=`pwd`; \ diff --git a/configure b/configure index a20b30d..87675e9 100755 --- a/configure +++ b/configure @@ -1,6 +1,6 @@ #! /bin/sh # Guess values for system-dependent variables and create Makefiles. -# Generated by GNU Autoconf 2.59 for GNU DejaGnu 1.4.4. +# Generated by GNU Autoconf 2.59 for GNU DejaGnu 1.4.99. # # Report bugs to . # @@ -269,12 +269,12 @@ SHELL=${CONFIG_SHELL-/bin/sh} # Identity of this package. PACKAGE_NAME='GNU DejaGnu' PACKAGE_TARNAME='dejagnu' -PACKAGE_VERSION='1.4.4' -PACKAGE_STRING='GNU DejaGnu 1.4.4' +PACKAGE_VERSION='1.4.99' +PACKAGE_STRING='GNU DejaGnu 1.4.99' PACKAGE_BUGREPORT='bug-dejagnu@gnu.org' ac_subdirs_all="$ac_subdirs_all example/calc example/hello example/mathhelper" -ac_subst_vars='SHELL PATH_SEPARATOR PACKAGE_NAME PACKAGE_TARNAME PACKAGE_VERSION PACKAGE_STRING PACKAGE_BUGREPORT exec_prefix prefix program_transform_name bindir sbindir libexecdir datadir sysconfdir sharedstatedir localstatedir libdir includedir oldincludedir infodir mandir build_alias host_alias target_alias DEFS ECHO_C ECHO_N ECHO_T LIBS INSTALL_PROGRAM INSTALL_SCRIPT INSTALL_DATA CYGPATH_W PACKAGE VERSION ACLOCAL AUTOCONF AUTOMAKE AUTOHEADER MAKEINFO install_sh STRIP ac_ct_STRIP INSTALL_STRIP_PROGRAM mkdir_p AWK SET_MAKE am__leading_dot AMTAR am__tar am__untar MAINTAINER_MODE_TRUE MAINTAINER_MODE_FALSE MAINT CC CFLAGS LDFLAGS CPPFLAGS ac_ct_CC EXEEXT OBJEXT DEPDIR am__include am__quote AMDEP_TRUE AMDEP_FALSE AMDEPBACKSLASH CCDEPMODE am__fastdepCC_TRUE am__fastdepCC_FALSE CXX CXXFLAGS ac_ct_CXX CXXDEPMODE am__fastdepCXX_TRUE am__fastdepCXX_FALSE DOCBOOK2DVI DOCBOOK2PDF DOCBOOK2HTML EXPECT subdirs LIBOBJS LTLIBOBJS' +ac_subst_vars='SHELL PATH_SEPARATOR PACKAGE_NAME PACKAGE_TARNAME PACKAGE_VERSION PACKAGE_STRING PACKAGE_BUGREPORT exec_prefix prefix program_transform_name bindir sbindir libexecdir datadir sysconfdir sharedstatedir localstatedir libdir includedir oldincludedir infodir mandir build_alias host_alias target_alias DEFS ECHO_C ECHO_N ECHO_T LIBS INSTALL_PROGRAM INSTALL_SCRIPT INSTALL_DATA CYGPATH_W PACKAGE VERSION ACLOCAL AUTOCONF AUTOMAKE AUTOHEADER MAKEINFO install_sh STRIP ac_ct_STRIP INSTALL_STRIP_PROGRAM mkdir_p AWK SET_MAKE am__leading_dot AMTAR am__tar am__untar MAINTAINER_MODE_TRUE MAINTAINER_MODE_FALSE MAINT CC CFLAGS LDFLAGS CPPFLAGS ac_ct_CC EXEEXT OBJEXT DEPDIR am__include am__quote AMDEP_TRUE AMDEP_FALSE AMDEPBACKSLASH CCDEPMODE am__fastdepCC_TRUE am__fastdepCC_FALSE CXX CXXFLAGS ac_ct_CXX CXXDEPMODE am__fastdepCXX_TRUE am__fastdepCXX_FALSE DOCBOOK2HTML DOCBOOK2RTF DOCBOOK2PDF DOCBOOK2PS EXPECT subdirs LIBOBJS LTLIBOBJS' ac_subst_files='' # Initialize some variables set by options. @@ -747,7 +747,7 @@ if test "$ac_init_help" = "long"; then # 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 <<_ACEOF -\`configure' configures GNU DejaGnu 1.4.4 to adapt to many kinds of systems. +\`configure' configures GNU DejaGnu 1.4.99 to adapt to many kinds of systems. Usage: $0 [OPTION]... [VAR=VALUE]... @@ -809,7 +809,7 @@ fi if test -n "$ac_init_help"; then case $ac_init_help in - short | recursive ) echo "Configuration of GNU DejaGnu 1.4.4:";; + short | recursive ) echo "Configuration of GNU DejaGnu 1.4.99:";; esac cat <<\_ACEOF @@ -923,14 +923,14 @@ esac else echo "$as_me: WARNING: no configuration information is in $ac_dir" >&2 fi - cd $ac_popdir + cd "$ac_popdir" done fi test -n "$ac_init_help" && exit 0 if $ac_init_version; then cat <<\_ACEOF -GNU DejaGnu configure 1.4.4 +GNU DejaGnu configure 1.4.99 generated by GNU Autoconf 2.59 Copyright (C) 2003 Free Software Foundation, Inc. @@ -944,7 +944,7 @@ cat >&5 <<_ACEOF This file contains any messages produced by compilers while running configure, to aid debugging if configure makes a mistake. -It was created by GNU DejaGnu $as_me 1.4.4, which was +It was created by GNU DejaGnu $as_me 1.4.99, which was generated by GNU Autoconf 2.59. Invocation command line was $ $0 $@ @@ -1587,7 +1587,7 @@ fi # Define the identity of the package. PACKAGE='dejagnu' - VERSION='1.4.4' + VERSION='1.4.99' cat >>confdefs.h <<_ACEOF @@ -2339,8 +2339,7 @@ if { (eval echo "$as_me:$LINENO: \"$ac_compile\"") >&5 cat conftest.err >&5 echo "$as_me:$LINENO: \$? = $ac_status" >&5 (exit $ac_status); } && - { ac_try='test -z "$ac_c_werror_flag" - || test ! -s conftest.err' + { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 (eval $ac_try) 2>&5 ac_status=$? @@ -2398,8 +2397,7 @@ if { (eval echo "$as_me:$LINENO: \"$ac_compile\"") >&5 cat conftest.err >&5 echo "$as_me:$LINENO: \$? = $ac_status" >&5 (exit $ac_status); } && - { ac_try='test -z "$ac_c_werror_flag" - || test ! -s conftest.err' + { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 (eval $ac_try) 2>&5 ac_status=$? @@ -2515,8 +2513,7 @@ if { (eval echo "$as_me:$LINENO: \"$ac_compile\"") >&5 cat conftest.err >&5 echo "$as_me:$LINENO: \$? = $ac_status" >&5 (exit $ac_status); } && - { ac_try='test -z "$ac_c_werror_flag" - || test ! -s conftest.err' + { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 (eval $ac_try) 2>&5 ac_status=$? @@ -2570,8 +2567,7 @@ if { (eval echo "$as_me:$LINENO: \"$ac_compile\"") >&5 cat conftest.err >&5 echo "$as_me:$LINENO: \$? = $ac_status" >&5 (exit $ac_status); } && - { ac_try='test -z "$ac_c_werror_flag" - || test ! -s conftest.err' + { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 (eval $ac_try) 2>&5 ac_status=$? @@ -2616,8 +2612,7 @@ if { (eval echo "$as_me:$LINENO: \"$ac_compile\"") >&5 cat conftest.err >&5 echo "$as_me:$LINENO: \$? = $ac_status" >&5 (exit $ac_status); } && - { ac_try='test -z "$ac_c_werror_flag" - || test ! -s conftest.err' + { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 (eval $ac_try) 2>&5 ac_status=$? @@ -2661,8 +2656,7 @@ if { (eval echo "$as_me:$LINENO: \"$ac_compile\"") >&5 cat conftest.err >&5 echo "$as_me:$LINENO: \$? = $ac_status" >&5 (exit $ac_status); } && - { ac_try='test -z "$ac_c_werror_flag" - || test ! -s conftest.err' + { ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err' { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 (eval $ac_try) 2>&5 ac_status=$? @@ -3020,8 +3014,7 @@ if { (eval echo "$as_me:$LINENO: \"$ac_compile\"") >&5 cat conftest.err >&5 echo "$as_me:$LINENO: \$? = $ac_status" >&5 (exit $ac_status); } && - { ac_try='test -z "$ac_cxx_werror_flag" - || test ! -s conftest.err' + { ac_try='test -z "$ac_cxx_werror_flag" || test ! -s conftest.err' { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 (eval $ac_try) 2>&5 ac_status=$? @@ -3079,8 +3072,7 @@ if { (eval echo "$as_me:$LINENO: \"$ac_compile\"") >&5 cat conftest.err >&5 echo "$as_me:$LINENO: \$? = $ac_status" >&5 (exit $ac_status); } && - { ac_try='test -z "$ac_cxx_werror_flag" - || test ! -s conftest.err' + { ac_try='test -z "$ac_cxx_werror_flag" || test ! -s conftest.err' { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 (eval $ac_try) 2>&5 ac_status=$? @@ -3151,8 +3143,7 @@ if { (eval echo "$as_me:$LINENO: \"$ac_compile\"") >&5 cat conftest.err >&5 echo "$as_me:$LINENO: \$? = $ac_status" >&5 (exit $ac_status); } && - { ac_try='test -z "$ac_cxx_werror_flag" - || test ! -s conftest.err' + { ac_try='test -z "$ac_cxx_werror_flag" || test ! -s conftest.err' { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 (eval $ac_try) 2>&5 ac_status=$? @@ -3196,8 +3187,7 @@ if { (eval echo "$as_me:$LINENO: \"$ac_compile\"") >&5 cat conftest.err >&5 echo "$as_me:$LINENO: \$? = $ac_status" >&5 (exit $ac_status); } && - { ac_try='test -z "$ac_cxx_werror_flag" - || test ! -s conftest.err' + { ac_try='test -z "$ac_cxx_werror_flag" || test ! -s conftest.err' { (eval echo "$as_me:$LINENO: \"$ac_try\"") >&5 (eval $ac_try) 2>&5 ac_status=$? @@ -3420,16 +3410,16 @@ test -z "$INSTALL_DATA" && INSTALL_DATA='${INSTALL} -m 644' -# Extract the first word of "docbook2dvi", so it can be a program name with args. -set dummy docbook2dvi; ac_word=$2 +# Extract the first word of "docbook2html", so it can be a program name with args. +set dummy docbook2html; ac_word=$2 echo "$as_me:$LINENO: checking for $ac_word" >&5 echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6 -if test "${ac_cv_path_DOCBOOK2DVI+set}" = set; then +if test "${ac_cv_path_DOCBOOK2HTML+set}" = set; then echo $ECHO_N "(cached) $ECHO_C" >&6 else - case $DOCBOOK2DVI in + case $DOCBOOK2HTML in [\\/]* | ?:[\\/]*) - ac_cv_path_DOCBOOK2DVI="$DOCBOOK2DVI" # Let the user override the test with a path. + ac_cv_path_DOCBOOK2HTML="$DOCBOOK2HTML" # Let the user override the test with a path. ;; *) as_save_IFS=$IFS; IFS=$PATH_SEPARATOR @@ -3439,22 +3429,62 @@ do test -z "$as_dir" && as_dir=. for ac_exec_ext in '' $ac_executable_extensions; do if $as_executable_p "$as_dir/$ac_word$ac_exec_ext"; then - ac_cv_path_DOCBOOK2DVI="$as_dir/$ac_word$ac_exec_ext" + ac_cv_path_DOCBOOK2HTML="$as_dir/$ac_word$ac_exec_ext" echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 break 2 fi done done - test -z "$ac_cv_path_DOCBOOK2DVI" && ac_cv_path_DOCBOOK2DVI="false" + test -z "$ac_cv_path_DOCBOOK2HTML" && ac_cv_path_DOCBOOK2HTML="false" ;; esac fi -DOCBOOK2DVI=$ac_cv_path_DOCBOOK2DVI +DOCBOOK2HTML=$ac_cv_path_DOCBOOK2HTML -if test -n "$DOCBOOK2DVI"; then - echo "$as_me:$LINENO: result: $DOCBOOK2DVI" >&5 -echo "${ECHO_T}$DOCBOOK2DVI" >&6 +if test -n "$DOCBOOK2HTML"; then + echo "$as_me:$LINENO: result: $DOCBOOK2HTML" >&5 +echo "${ECHO_T}$DOCBOOK2HTML" >&6 +else + echo "$as_me:$LINENO: result: no" >&5 +echo "${ECHO_T}no" >&6 +fi + +# Extract the first word of "docbook2rtf", so it can be a program name with args. +set dummy docbook2rtf; ac_word=$2 +echo "$as_me:$LINENO: checking for $ac_word" >&5 +echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6 +if test "${ac_cv_path_DOCBOOK2RTF+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + case $DOCBOOK2RTF in + [\\/]* | ?:[\\/]*) + ac_cv_path_DOCBOOK2RTF="$DOCBOOK2RTF" # Let the user override the test with a path. + ;; + *) + as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_exec_ext in '' $ac_executable_extensions; do + if $as_executable_p "$as_dir/$ac_word$ac_exec_ext"; then + ac_cv_path_DOCBOOK2RTF="$as_dir/$ac_word$ac_exec_ext" + echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi +done +done + + test -z "$ac_cv_path_DOCBOOK2RTF" && ac_cv_path_DOCBOOK2RTF="false" + ;; +esac +fi +DOCBOOK2RTF=$ac_cv_path_DOCBOOK2RTF + +if test -n "$DOCBOOK2RTF"; then + echo "$as_me:$LINENO: result: $DOCBOOK2RTF" >&5 +echo "${ECHO_T}$DOCBOOK2RTF" >&6 else echo "$as_me:$LINENO: result: no" >&5 echo "${ECHO_T}no" >&6 @@ -3500,16 +3530,16 @@ else echo "${ECHO_T}no" >&6 fi -# Extract the first word of "docbook2html", so it can be a program name with args. -set dummy docbook2html; ac_word=$2 +# Extract the first word of "docbook2ps", so it can be a program name with args. +set dummy docbook2ps; ac_word=$2 echo "$as_me:$LINENO: checking for $ac_word" >&5 echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6 -if test "${ac_cv_path_DOCBOOK2HTML+set}" = set; then +if test "${ac_cv_path_DOCBOOK2PS+set}" = set; then echo $ECHO_N "(cached) $ECHO_C" >&6 else - case $DOCBOOK2HTML in + case $DOCBOOK2PS in [\\/]* | ?:[\\/]*) - ac_cv_path_DOCBOOK2HTML="$DOCBOOK2HTML" # Let the user override the test with a path. + ac_cv_path_DOCBOOK2PS="$DOCBOOK2PS" # Let the user override the test with a path. ;; *) as_save_IFS=$IFS; IFS=$PATH_SEPARATOR @@ -3519,22 +3549,22 @@ do test -z "$as_dir" && as_dir=. for ac_exec_ext in '' $ac_executable_extensions; do if $as_executable_p "$as_dir/$ac_word$ac_exec_ext"; then - ac_cv_path_DOCBOOK2HTML="$as_dir/$ac_word$ac_exec_ext" + ac_cv_path_DOCBOOK2PS="$as_dir/$ac_word$ac_exec_ext" echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 break 2 fi done done - test -z "$ac_cv_path_DOCBOOK2HTML" && ac_cv_path_DOCBOOK2HTML="false" + test -z "$ac_cv_path_DOCBOOK2PS" && ac_cv_path_DOCBOOK2PS="false" ;; esac fi -DOCBOOK2HTML=$ac_cv_path_DOCBOOK2HTML +DOCBOOK2PS=$ac_cv_path_DOCBOOK2PS -if test -n "$DOCBOOK2HTML"; then - echo "$as_me:$LINENO: result: $DOCBOOK2HTML" >&5 -echo "${ECHO_T}$DOCBOOK2HTML" >&6 +if test -n "$DOCBOOK2PS"; then + echo "$as_me:$LINENO: result: $DOCBOOK2PS" >&5 +echo "${ECHO_T}$DOCBOOK2PS" >&6 else echo "$as_me:$LINENO: result: no" >&5 echo "${ECHO_T}no" >&6 @@ -3611,8 +3641,7 @@ fi subdirs="$subdirs example/calc example/hello example/mathhelper" - - ac_config_files="$ac_config_files Makefile doc/Makefile doc/C/Makefile" + ac_config_files="$ac_config_files Makefile" cat >confcache <<\_ACEOF # This file is a shell script that caches the results of configure # tests run on this system so they can be shared between configure @@ -4034,7 +4063,7 @@ _ASBOX } >&5 cat >&5 <<_CSEOF -This file was extended by GNU DejaGnu $as_me 1.4.4, which was +This file was extended by GNU DejaGnu $as_me 1.4.99, which was generated by GNU Autoconf 2.59. Invocation command line was CONFIG_FILES = $CONFIG_FILES @@ -4092,7 +4121,7 @@ _ACEOF cat >>$CONFIG_STATUS <<_ACEOF ac_cs_version="\\ -GNU DejaGnu config.status 1.4.4 +GNU DejaGnu config.status 1.4.99 configured by $0, generated by GNU Autoconf 2.59, with options \\"`echo "$ac_configure_args" | sed 's/[\\""\`\$]/\\\\&/g'`\\" @@ -4203,8 +4232,6 @@ do case "$ac_config_target" in # Handling of arguments. "Makefile" ) CONFIG_FILES="$CONFIG_FILES Makefile" ;; - "doc/Makefile" ) CONFIG_FILES="$CONFIG_FILES doc/Makefile" ;; - "doc/C/Makefile" ) CONFIG_FILES="$CONFIG_FILES doc/C/Makefile" ;; "depfiles" ) CONFIG_COMMANDS="$CONFIG_COMMANDS depfiles" ;; *) { { echo "$as_me:$LINENO: error: invalid argument: $ac_config_target" >&5 echo "$as_me: error: invalid argument: $ac_config_target" >&2;} @@ -4337,9 +4364,10 @@ s,@ac_ct_CXX@,$ac_ct_CXX,;t t s,@CXXDEPMODE@,$CXXDEPMODE,;t t s,@am__fastdepCXX_TRUE@,$am__fastdepCXX_TRUE,;t t s,@am__fastdepCXX_FALSE@,$am__fastdepCXX_FALSE,;t t -s,@DOCBOOK2DVI@,$DOCBOOK2DVI,;t t -s,@DOCBOOK2PDF@,$DOCBOOK2PDF,;t t s,@DOCBOOK2HTML@,$DOCBOOK2HTML,;t t +s,@DOCBOOK2RTF@,$DOCBOOK2RTF,;t t +s,@DOCBOOK2PDF@,$DOCBOOK2PDF,;t t +s,@DOCBOOK2PS@,$DOCBOOK2PS,;t t s,@EXPECT@,$EXPECT,;t t s,@subdirs@,$subdirs,;t t s,@LIBOBJS@,$LIBOBJS,;t t @@ -4510,11 +4538,6 @@ esac *) ac_INSTALL=$ac_top_builddir$INSTALL ;; esac - if test x"$ac_file" != x-; then - { echo "$as_me:$LINENO: creating $ac_file" >&5 -echo "$as_me: creating $ac_file" >&6;} - rm -f "$ac_file" - fi # Let's still pretend it is `configure' which instantiates (i.e., don't # use $as_me), people would be surprised to read: # /* config.h. Generated by config.status. */ @@ -4553,6 +4576,12 @@ echo "$as_me: error: cannot find input file: $f" >&2;} fi;; esac done` || { (exit 1); exit 1; } + + if test x"$ac_file" != x-; then + { echo "$as_me:$LINENO: creating $ac_file" >&5 +echo "$as_me: creating $ac_file" >&6;} + rm -f "$ac_file" + fi _ACEOF cat >>$CONFIG_STATUS <<_ACEOF sed "$ac_vpsub @@ -4987,7 +5016,7 @@ echo "$as_me: error: $ac_sub_configure failed for $ac_dir" >&2;} { (exit 1); exit 1; }; } fi - cd $ac_popdir + cd "$ac_popdir" done fi diff --git a/configure.ac b/configure.ac index d8a9b11..64e50ed 100644 --- a/configure.ac +++ b/configure.ac @@ -12,9 +12,10 @@ AC_PROG_INSTALL AC_EXEEXT dnl Search for the Docbook utilities. -AC_PATH_PROG([DOCBOOK2DVI], [docbook2dvi], [false]) -AC_PATH_PROG([DOCBOOK2PDF], [docbook2pdf], [false]) AC_PATH_PROG([DOCBOOK2HTML], [docbook2html], [false]) +AC_PATH_PROG([DOCBOOK2RTF], [docbook2rtf], [false]) +AC_PATH_PROG([DOCBOOK2PDF], [docbook2pdf], [false]) +AC_PATH_PROG([DOCBOOK2PS], [docbook2ps], [false]) dnl Search for expect. AC_PATH_PROG([EXPECT], [expect]) @@ -36,5 +37,4 @@ else fi AC_CONFIG_SUBDIRS([example/calc example/hello example/mathhelper]) - -AC_OUTPUT([Makefile doc/Makefile doc/C/Makefile]) +AC_OUTPUT([Makefile]) diff --git a/doc/C/dejagnu.omf b/doc/C/dejagnu.omf deleted file mode 100644 index ddbedb0..0000000 --- a/doc/C/dejagnu.omf +++ /dev/null @@ -1,27 +0,0 @@ - - - - - rob@senecass.com (Rob Savoye) - - - DejaGnu Manual - - - 2004-02-05 - - - - - This is the manual for DejaGnu, the GNU regression Testing Framework - - - manual - - - - - - - - diff --git a/doc/C/topic.dat b/doc/C/topic.dat deleted file mode 100644 index 5291acd..0000000 --- a/doc/C/topic.dat +++ /dev/null @@ -1 +0,0 @@ -html/index.html DejaGnu Manual diff --git a/doc/Makefile.am b/doc/Makefile.am deleted file mode 100644 index 6199be0..0000000 --- a/doc/Makefile.am +++ /dev/null @@ -1,86 +0,0 @@ -## Process this file with automake to generate Makefile.in - -dist_man_MANS = runtest.1 -info_TEXINFOS = dejagnu.texi - -DOCBOOK = @DOCBOOK@ -TARGETS = book1.html overview.ps overview.pdf - -EXTRA_DIST = overview.sgml user.sgml ref.sgml \ - overview.pdf \ - overview.ps \ - html/book1.html \ - html/x953.html \ - html/x935.html \ - html/x916.html \ - html/x81.html \ - html/x755.html \ - html/x5158.html \ - html/x5058.html \ - html/x428.html \ - html/x319.html \ - html/x276.html \ - html/x227.html \ - html/x1655.html \ - html/x1600.html \ - html/x1590.html \ - html/x1551.html \ - html/x1522.html \ - html/x1493.html \ - html/x1462.html \ - html/x1445.html \ - html/x134.html \ - html/x1234.html \ - html/x1214.html \ - html/x1195.html \ - html/x1107.html \ - html/x107.html \ - html/f40.html \ - html/c848.html \ - html/c5112.html \ - html/c50.html \ - html/c401.html \ - html/c203.html \ - html/c1593.html \ - html/c1584.html \ - html/c1099.html \ - html/x992.html - -docs: $(TARGETS) - -%.ps: %.dvi - src=$(srcdir); \ - dir=`(cd $${src}; pwd)`; \ - dvips -o $@ $*.dvi - -%.pdf: %.sgml - src=$(srcdir); \ - dir=`(cd $${src}; pwd)`; \ - $(DOCBOOK2PDF) $${dir}/$*.sgml - -%.dvi: %.sgml - src=$(srcdir); \ - dir=`(cd $${src}; pwd)`; \ - $(DOCBOOK2DVI) $${dir}/$*.sgml - -%.html: %.sgml - src=$(srcdir); \ - dir=`(cd $${src}; pwd)`; \ - mkdir html; \ - $(DOCBOOK2HTML) $${dir}/$*.sgml - -# Now for some extra dependencies that the automatic rules will not -# catch: - -book1.html: html/book1.html - -html/book1.html overview.pdf overview.ps overview.html: overview.sgml ref.sgml user.sgml - -html/book1.html: overview.sgml ref.sgml user.sgml - -install-doc: $(TARGETS) - $(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/html $(DESTDIR)$(pkgdatadir)/html/stylesheet-images - $(INSTALL_DATA) html/*.html $(DESTDIR)$(pkgdatadir)/html - $(INSTALL_DATA) overview.ps $(DESTDIR)$(pkgdatadir)/dejagnu.ps - $(INSTALL_DATA) overview.pdf $(DESTDIR)$(pkgdatadir)/dejagnu.pdf - $(INSTALL_DATA) $(srcdir)/runtest.1 $(mandir)/man1/ diff --git a/doc/Makefile.in b/doc/Makefile.in deleted file mode 100644 index 8ff1494..0000000 --- a/doc/Makefile.in +++ /dev/null @@ -1,574 +0,0 @@ -# Makefile.in generated by automake 1.9.6 from Makefile.am. -# @configure_input@ - -# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -# 2003, 2004, 2005 Free Software Foundation, Inc. -# This Makefile.in is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. - -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY, to the extent permitted by law; without -# even the implied warranty of MERCHANTABILITY or FITNESS FOR A -# PARTICULAR PURPOSE. - -@SET_MAKE@ -srcdir = @srcdir@ -top_srcdir = @top_srcdir@ -VPATH = @srcdir@ -pkgdatadir = $(datadir)/@PACKAGE@ -pkglibdir = $(libdir)/@PACKAGE@ -pkgincludedir = $(includedir)/@PACKAGE@ -top_builddir = .. -am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd -INSTALL = @INSTALL@ -install_sh_DATA = $(install_sh) -c -m 644 -install_sh_PROGRAM = $(install_sh) -c -install_sh_SCRIPT = $(install_sh) -c -INSTALL_HEADER = $(INSTALL_DATA) -transform = $(program_transform_name) -NORMAL_INSTALL = : -PRE_INSTALL = : -POST_INSTALL = : -NORMAL_UNINSTALL = : -PRE_UNINSTALL = : -POST_UNINSTALL = : -subdir = doc -DIST_COMMON = $(dist_man_MANS) $(srcdir)/Makefile.am \ - $(srcdir)/Makefile.in texinfo.tex -ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 -am__aclocal_m4_deps = $(top_srcdir)/configure.ac -am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ - $(ACLOCAL_M4) -mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs -CONFIG_CLEAN_FILES = -SOURCES = -DIST_SOURCES = -INFO_DEPS = $(srcdir)/dejagnu.info -am__TEXINFO_TEX_DIR = $(srcdir) -DVIS = dejagnu.dvi -PDFS = dejagnu.pdf -PSS = dejagnu.ps -HTMLS = dejagnu.html -TEXINFOS = dejagnu.texi -TEXI2DVI = texi2dvi -TEXI2PDF = $(TEXI2DVI) --pdf --batch -MAKEINFOHTML = $(MAKEINFO) --html -AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) -DVIPS = dvips -am__installdirs = "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)" -man1dir = $(mandir)/man1 -NROFF = nroff -MANS = $(dist_man_MANS) -DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) -ACLOCAL = @ACLOCAL@ -AMDEP_FALSE = @AMDEP_FALSE@ -AMDEP_TRUE = @AMDEP_TRUE@ -AMTAR = @AMTAR@ -AUTOCONF = @AUTOCONF@ -AUTOHEADER = @AUTOHEADER@ -AUTOMAKE = @AUTOMAKE@ -AWK = @AWK@ -CC = @CC@ -CCDEPMODE = @CCDEPMODE@ -CFLAGS = @CFLAGS@ -CPPFLAGS = @CPPFLAGS@ -CXX = @CXX@ -CXXDEPMODE = @CXXDEPMODE@ -CXXFLAGS = @CXXFLAGS@ -CYGPATH_W = @CYGPATH_W@ -DEFS = @DEFS@ -DEPDIR = @DEPDIR@ -DOCBOOK2DVI = @DOCBOOK2DVI@ -DOCBOOK2HTML = @DOCBOOK2HTML@ -DOCBOOK2PDF = @DOCBOOK2PDF@ -ECHO_C = @ECHO_C@ -ECHO_N = @ECHO_N@ -ECHO_T = @ECHO_T@ -EXEEXT = @EXEEXT@ -EXPECT = @EXPECT@ -INSTALL_DATA = @INSTALL_DATA@ -INSTALL_PROGRAM = @INSTALL_PROGRAM@ -INSTALL_SCRIPT = @INSTALL_SCRIPT@ -INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ -LDFLAGS = @LDFLAGS@ -LIBOBJS = @LIBOBJS@ -LIBS = @LIBS@ -LTLIBOBJS = @LTLIBOBJS@ -MAINT = @MAINT@ -MAINTAINER_MODE_FALSE = @MAINTAINER_MODE_FALSE@ -MAINTAINER_MODE_TRUE = @MAINTAINER_MODE_TRUE@ -MAKEINFO = @MAKEINFO@ -OBJEXT = @OBJEXT@ -PACKAGE = @PACKAGE@ -PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ -PACKAGE_NAME = @PACKAGE_NAME@ -PACKAGE_STRING = @PACKAGE_STRING@ -PACKAGE_TARNAME = @PACKAGE_TARNAME@ -PACKAGE_VERSION = @PACKAGE_VERSION@ -PATH_SEPARATOR = @PATH_SEPARATOR@ -SET_MAKE = @SET_MAKE@ -SHELL = @SHELL@ -STRIP = @STRIP@ -VERSION = @VERSION@ -ac_ct_CC = @ac_ct_CC@ -ac_ct_CXX = @ac_ct_CXX@ -ac_ct_STRIP = @ac_ct_STRIP@ -am__fastdepCC_FALSE = @am__fastdepCC_FALSE@ -am__fastdepCC_TRUE = @am__fastdepCC_TRUE@ -am__fastdepCXX_FALSE = @am__fastdepCXX_FALSE@ -am__fastdepCXX_TRUE = @am__fastdepCXX_TRUE@ -am__include = @am__include@ -am__leading_dot = @am__leading_dot@ -am__quote = @am__quote@ -am__tar = @am__tar@ -am__untar = @am__untar@ -bindir = @bindir@ -build_alias = @build_alias@ -datadir = @datadir@ -exec_prefix = @exec_prefix@ -host_alias = @host_alias@ -includedir = @includedir@ -infodir = @infodir@ -install_sh = @install_sh@ -libdir = @libdir@ -libexecdir = @libexecdir@ -localstatedir = @localstatedir@ -mandir = @mandir@ -mkdir_p = @mkdir_p@ -oldincludedir = @oldincludedir@ -prefix = @prefix@ -program_transform_name = @program_transform_name@ -sbindir = @sbindir@ -sharedstatedir = @sharedstatedir@ -subdirs = @subdirs@ -sysconfdir = @sysconfdir@ -target_alias = @target_alias@ -dist_man_MANS = runtest.1 -info_TEXINFOS = dejagnu.texi -DOCBOOK = @DOCBOOK@ -TARGETS = book1.html overview.ps overview.pdf -EXTRA_DIST = overview.sgml user.sgml ref.sgml \ - overview.pdf \ - overview.ps \ - html/book1.html \ - html/x953.html \ - html/x935.html \ - html/x916.html \ - html/x81.html \ - html/x755.html \ - html/x5158.html \ - html/x5058.html \ - html/x428.html \ - html/x319.html \ - html/x276.html \ - html/x227.html \ - html/x1655.html \ - html/x1600.html \ - html/x1590.html \ - html/x1551.html \ - html/x1522.html \ - html/x1493.html \ - html/x1462.html \ - html/x1445.html \ - html/x134.html \ - html/x1234.html \ - html/x1214.html \ - html/x1195.html \ - html/x1107.html \ - html/x107.html \ - html/f40.html \ - html/c848.html \ - html/c5112.html \ - html/c50.html \ - html/c401.html \ - html/c203.html \ - html/c1593.html \ - html/c1584.html \ - html/c1099.html \ - html/x992.html - -all: all-am - -.SUFFIXES: -.SUFFIXES: .dvi .html .info .pdf .ps .texi -$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) - @for dep in $?; do \ - case '$(am__configure_deps)' in \ - *$$dep*) \ - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ - && exit 0; \ - exit 1;; \ - esac; \ - done; \ - echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \ - cd $(top_srcdir) && \ - $(AUTOMAKE) --gnu doc/Makefile -.PRECIOUS: Makefile -Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status - @case '$?' in \ - *config.status*) \ - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ - *) \ - echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ - cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ - esac; - -$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh - -$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh -$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh - -.texi.info: - restore=: && backupdir="$(am__leading_dot)am$$$$" && \ - am__cwd=`pwd` && cd $(srcdir) && \ - rm -rf $$backupdir && mkdir $$backupdir && \ - if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ - for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ - if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ - done; \ - else :; fi && \ - cd "$$am__cwd"; \ - if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ - -o $@ $<; \ - then \ - rc=0; \ - cd $(srcdir); \ - else \ - rc=$$?; \ - cd $(srcdir) && \ - $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ - fi; \ - rm -rf $$backupdir; exit $$rc - -.texi.dvi: - TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ - $(TEXI2DVI) $< - -.texi.pdf: - TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ - $(TEXI2PDF) $< - -.texi.html: - rm -rf $(@:.html=.htp) - if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ - -o $(@:.html=.htp) $<; \ - then \ - rm -rf $@; \ - if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ - mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \ - else \ - if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ - rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \ - exit 1; \ - fi -$(srcdir)/dejagnu.info: dejagnu.texi -dejagnu.dvi: dejagnu.texi -dejagnu.pdf: dejagnu.texi -dejagnu.html: dejagnu.texi -.dvi.ps: - TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - $(DVIPS) -o $@ $< - -uninstall-info-am: - @$(PRE_UNINSTALL) - @if (install-info --version && \ - install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ - list='$(INFO_DEPS)'; \ - for file in $$list; do \ - relfile=`echo "$$file" | sed 's|^.*/||'`; \ - echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ - install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ - done; \ - else :; fi - @$(NORMAL_UNINSTALL) - @list='$(INFO_DEPS)'; \ - for file in $$list; do \ - relfile=`echo "$$file" | sed 's|^.*/||'`; \ - relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ - (if cd "$(DESTDIR)$(infodir)"; then \ - echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \ - rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ - else :; fi); \ - done - -dist-info: $(INFO_DEPS) - @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ - list='$(INFO_DEPS)'; \ - for base in $$list; do \ - case $$base in \ - $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \ - esac; \ - if test -f $$base; then d=.; else d=$(srcdir); fi; \ - for file in $$d/$$base*; do \ - relfile=`expr "$$file" : "$$d/\(.*\)"`; \ - test -f $(distdir)/$$relfile || \ - cp -p $$file $(distdir)/$$relfile; \ - done; \ - done - -mostlyclean-aminfo: - -rm -rf dejagnu.aux dejagnu.cp dejagnu.cps dejagnu.fn dejagnu.ky dejagnu.log \ - dejagnu.pg dejagnu.pgs dejagnu.tmp dejagnu.toc dejagnu.tp \ - dejagnu.tps dejagnu.vr dejagnu.vrs dejagnu.dvi dejagnu.pdf \ - dejagnu.ps dejagnu.html - -maintainer-clean-aminfo: - @list='$(INFO_DEPS)'; for i in $$list; do \ - i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ - echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ - rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ - done -install-man1: $(man1_MANS) $(man_MANS) - @$(NORMAL_INSTALL) - test -z "$(man1dir)" || $(mkdir_p) "$(DESTDIR)$(man1dir)" - @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ - l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ - for i in $$l2; do \ - case "$$i" in \ - *.1*) list="$$list $$i" ;; \ - esac; \ - done; \ - for i in $$list; do \ - if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \ - else file=$$i; fi; \ - ext=`echo $$i | sed -e 's/^.*\\.//'`; \ - case "$$ext" in \ - 1*) ;; \ - *) ext='1' ;; \ - esac; \ - inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ - inst=`echo $$inst | sed -e 's/^.*\///'`; \ - inst=`echo $$inst | sed '$(transform)'`.$$ext; \ - echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \ - $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst"; \ - done -uninstall-man1: - @$(NORMAL_UNINSTALL) - @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ - l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ - for i in $$l2; do \ - case "$$i" in \ - *.1*) list="$$list $$i" ;; \ - esac; \ - done; \ - for i in $$list; do \ - ext=`echo $$i | sed -e 's/^.*\\.//'`; \ - case "$$ext" in \ - 1*) ;; \ - *) ext='1' ;; \ - esac; \ - inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ - inst=`echo $$inst | sed -e 's/^.*\///'`; \ - inst=`echo $$inst | sed '$(transform)'`.$$ext; \ - echo " rm -f '$(DESTDIR)$(man1dir)/$$inst'"; \ - rm -f "$(DESTDIR)$(man1dir)/$$inst"; \ - done -tags: TAGS -TAGS: - -ctags: CTAGS -CTAGS: - - -distdir: $(DISTFILES) - $(mkdir_p) $(distdir)/html - @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ - topsrcdirstrip=`echo "$(top_srcdir)" | sed 's|.|.|g'`; \ - list='$(DISTFILES)'; for file in $$list; do \ - case $$file in \ - $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ - $(top_srcdir)/*) file=`echo "$$file" | sed "s|^$$topsrcdirstrip/|$(top_builddir)/|"`;; \ - esac; \ - if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ - dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \ - if test "$$dir" != "$$file" && test "$$dir" != "."; then \ - dir="/$$dir"; \ - $(mkdir_p) "$(distdir)$$dir"; \ - else \ - dir=''; \ - fi; \ - if test -d $$d/$$file; then \ - if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ - cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ - fi; \ - cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ - else \ - test -f $(distdir)/$$file \ - || cp -p $$d/$$file $(distdir)/$$file \ - || exit 1; \ - fi; \ - done - $(MAKE) $(AM_MAKEFLAGS) \ - top_distdir="$(top_distdir)" distdir="$(distdir)" \ - dist-info -check-am: all-am -check: check-am -all-am: Makefile $(INFO_DEPS) $(MANS) -installdirs: - for dir in "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"; do \ - test -z "$$dir" || $(mkdir_p) "$$dir"; \ - done -install: install-am -install-exec: install-exec-am -install-data: install-data-am -uninstall: uninstall-am - -install-am: all-am - @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am - -installcheck: installcheck-am -install-strip: - $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ - install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ - `test -z '$(STRIP)' || \ - echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install -mostlyclean-generic: - -clean-generic: - -distclean-generic: - -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) - -maintainer-clean-generic: - @echo "This command is intended for maintainers to use" - @echo "it deletes files that may require special tools to rebuild." -clean: clean-am - -clean-am: clean-generic mostlyclean-am - -distclean: distclean-am - -rm -f Makefile -distclean-am: clean-am distclean-generic - -dvi: dvi-am - -dvi-am: $(DVIS) - -html: html-am - -html-am: $(HTMLS) - -info: info-am - -info-am: $(INFO_DEPS) - -install-data-am: install-info-am install-man - -install-exec-am: - -install-info: install-info-am - -install-info-am: $(INFO_DEPS) - @$(NORMAL_INSTALL) - test -z "$(infodir)" || $(mkdir_p) "$(DESTDIR)$(infodir)" - @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ - list='$(INFO_DEPS)'; \ - for file in $$list; do \ - case $$file in \ - $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ - esac; \ - if test -f $$file; then d=.; else d=$(srcdir); fi; \ - file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ - for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ - $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ - if test -f $$ifile; then \ - relfile=`echo "$$ifile" | sed 's|^.*/||'`; \ - echo " $(INSTALL_DATA) '$$ifile' '$(DESTDIR)$(infodir)/$$relfile'"; \ - $(INSTALL_DATA) "$$ifile" "$(DESTDIR)$(infodir)/$$relfile"; \ - else : ; fi; \ - done; \ - done - @$(POST_INSTALL) - @if (install-info --version && \ - install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ - list='$(INFO_DEPS)'; \ - for file in $$list; do \ - relfile=`echo "$$file" | sed 's|^.*/||'`; \ - echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ - install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ - done; \ - else : ; fi -install-man: install-man1 - -installcheck-am: - -maintainer-clean: maintainer-clean-am - -rm -f Makefile -maintainer-clean-am: distclean-am maintainer-clean-aminfo \ - maintainer-clean-generic - -mostlyclean: mostlyclean-am - -mostlyclean-am: mostlyclean-aminfo mostlyclean-generic - -pdf: pdf-am - -pdf-am: $(PDFS) - -ps: ps-am - -ps-am: $(PSS) - -uninstall-am: uninstall-info-am uninstall-man - -uninstall-man: uninstall-man1 - -.PHONY: all all-am check check-am clean clean-generic dist-info \ - distclean distclean-generic distdir dvi dvi-am html html-am \ - info info-am install install-am install-data install-data-am \ - install-exec install-exec-am install-info install-info-am \ - install-man install-man1 install-strip installcheck \ - installcheck-am installdirs maintainer-clean \ - maintainer-clean-aminfo maintainer-clean-generic mostlyclean \ - mostlyclean-aminfo mostlyclean-generic pdf pdf-am ps ps-am \ - uninstall uninstall-am uninstall-info-am uninstall-man \ - uninstall-man1 - - -docs: $(TARGETS) - -%.ps: %.dvi - src=$(srcdir); \ - dir=`(cd $${src}; pwd)`; \ - dvips -o $@ $*.dvi - -%.pdf: %.sgml - src=$(srcdir); \ - dir=`(cd $${src}; pwd)`; \ - $(DOCBOOK2PDF) $${dir}/$*.sgml - -%.dvi: %.sgml - src=$(srcdir); \ - dir=`(cd $${src}; pwd)`; \ - $(DOCBOOK2DVI) $${dir}/$*.sgml - -%.html: %.sgml - src=$(srcdir); \ - dir=`(cd $${src}; pwd)`; \ - mkdir html; \ - $(DOCBOOK2HTML) $${dir}/$*.sgml - -# Now for some extra dependencies that the automatic rules will not -# catch: - -book1.html: html/book1.html - -html/book1.html overview.pdf overview.ps overview.html: overview.sgml ref.sgml user.sgml - -html/book1.html: overview.sgml ref.sgml user.sgml - -install-doc: $(TARGETS) - $(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/html $(DESTDIR)$(pkgdatadir)/html/stylesheet-images - $(INSTALL_DATA) html/*.html $(DESTDIR)$(pkgdatadir)/html - $(INSTALL_DATA) overview.ps $(DESTDIR)$(pkgdatadir)/dejagnu.ps - $(INSTALL_DATA) overview.pdf $(DESTDIR)$(pkgdatadir)/dejagnu.pdf - $(INSTALL_DATA) $(srcdir)/runtest.1 $(mandir)/man1/ -# 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/dejagnu.texi b/doc/dejagnu.texi index 1fea03a..1705dc5 100644 --- a/doc/dejagnu.texi +++ b/doc/dejagnu.texi @@ -1,3706 +1,7365 @@ -\input texinfo @c -*- Texinfo -*- -@finalout +\input texinfo @setfilename dejagnu.info -@c -@c This file documents the GNU Testing Framework ``DejaGnu'' -@c -@c Copyright (C) 92 - 2000, 2001 Free Software Foundation, Inc. -@c -@c This text may be freely distributed under the terms of the GNU -@c General Public License. -@c - -@c FIXME---MAIN TODO LIST! -@c -@c * Revisit organization. -@c -@c * discuss Tcl/expect basics---enough to get started (see seminar notes). -@c Maybe this would permit abbreviating appendices. - -@ifinfo -@format -START-INFO-DIR-ENTRY -* DejaGnu: (dejagnu). The GNU testing framework. -END-INFO-DIR-ENTRY -@end format -@end ifinfo - -@syncodeindex ky cp -@syncodeindex fn cp - -@setchapternewpage odd -@settitle DejaGnu Testing Framework -@titlepage -@title The DejaGnu Testing Framework -@subtitle for DejaGnu Version 1.3 -@sp 1 -@subtitle Jan 1996 -@author Rob Savoye -@page - -@tex -{\parskip=0pt \hfill Cygnus Support} -@end tex - -@vskip 0pt plus 1filll -Copyright @copyright{} 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. +@documentencoding us-ascii +@direntry +* DejaGnu: . ??? +@end direntry -@noindent -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. +@node Top, Abstract, , (dir) +@top DejaGnu -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions. -@end titlepage +@menu +* Abstract:: +* Overview:: +* Getting DejaGnu up and running:: +* Running Tests:: +* Customizing DejaGnu:: +* Extending DejaGnu:: +* Unit Testing:: +* Reference:: +* Unit Testing API:: -@ifinfo -Copyright @copyright{} 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software Foundation, Inc. +@detailmenu +--- The Detailed Node Listing --- -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. +Overview -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries a copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). -@end ignore +* What is DejaGnu ?:: +* What_s New In This Release: Release Notes. +* Design Goals:: +* A POSIX conforming test framework: A POSIX Conforming Test Framework. -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. +Getting DejaGnu up and running -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions. +* Test your installation:: +* Create a minimal project; e_g_ calc:: +* Our first automated tests:: +* A first remote test:: -@node Top +Running Tests -@top DejaGnu +* Make check: Make Check. +* Runtest:: +* The files DejaGnu produces_: Output Files. -DejaGnu is a framework for running test suites on software tools. +Customizing DejaGnu -This file describes version 1.3 of DejaGnu. +* Local Config File:: +* Global Config File:: +* Board Config File:: +* Remote Host Testing:: +* Config File Values:: -@menu -* Overview:: What is DejaGnu? -* What is New:: What is new in this release. -* Invoking runtest:: Using `runtest', the main test driver -* Customizing:: Setting `runtest' defaults -* Internals:: The DejaGnu implementation -* Tests:: How to write a test case -* Extending:: New tools, new targets, and new hosts -* Installation:: Configuring and Installing DejaGnu -* Index:: Index -@end menu -@end ifinfo +Extending DejaGnu -@iftex -@raggedbottom -@end iftex +* Adding A New Testsuite: Adding a new Testsuite. +* Adding A New Tool:: +* Adding A New Target:: +* Adding A New Board:: +* Board Config File Values: Board File Values. +* Writing A Test Case:: +* Debugging A Test Case:: +* Adding A Test Case To A Testsuite_: Adding A Test Case To A Testsuite. +* Hints On Writing A Test Case:: +* Special variables used by test cases_: Test Case Variables. -@node Overview -@chapter What is DejaGnu? -@cindex overview +Unit Testing -DejaGnu is a framework for testing other programs. Its purpose is to -provide a single front end for all tests. Beyond this, DejaGnu offers -several advantages for testing: +* What Is Unit Testing ?:: +* The dejagnu_h Header File:: -@enumerate -@item -The flexibility and consistency of the DejaGnu framework make it easy -to write tests for any program. +Reference -@item -DejaGnu provides a layer of abstraction which allows you to write tests -that are portable to any host or target where a program must be tested. - For instance, a test for GDB can run (from any Unix based host) on any -target architecture that DejaGnu supports. Currently DejaGnu runs tests -on several single board computers, whose operating software ranges from -just a boot monitor to a full-fledged, Unix-like realtime OS. +* Obtaining DejaGnu:: +* Installation:: +* Builtin Procedures:: +* File Map:: -@item -All tests have the same output format. This makes it easy to integrate -testing into other software development processes. DejaGnu's output is -designed to be parsed by other filtering script, and it is also human -readable. -@end enumerate +Unit Testing API -DejaGnu is written in @code{expect}, which in turn uses @dfn{Tcl}---Tool -command language. +* C Unit Testing API:: +* C++ Unit Testing API:: -@cindex @code{expect} script names -@kindex .exp -@cindex suffix, @code{expect} scripts -Running tests requires two things: the testing framework, and the test -suites themselves. Tests are usually written in @code{expect} using -Tcl, but you can also use a Tcl script to run a test suite that is not -based on @code{expect}. (@code{expect} script filenames conventionally -use @samp{.exp} as a suffix; for example, the main implementation of the -DejaGnu test driver is in the file @file{runtest.exp}.) +@end detailmenu +@end menu +@node Abstract, Overview, Top, Top +@chapter Abstract + +This document describes the functionality of DejaGnu, the +testing framework of the GNU project. DejaGnu is written in +Expect, which uses +Tcl as a command +language. Expect acts as a very +programmable shell. As with other Unix command shells, you can +run any program, but once the program is started, your test script +has programmable control over its input and output. This does not +just apply to the programs under test; @code{expect} +can also run any auxiliary program, such as +@code{diff} or @code{sh}, with full +control over its input and output. + +DejaGnu itself is merely a framework for the creation of +testsuites. Testsuites are distributed with each +application. + +@node Overview, Getting DejaGnu up and running, Abstract, Top +@chapter Overview @menu -* Running Tests:: A first look at running DejaGnu tests -* Sample Test:: What does a DejaGnu test case look like? -* Design Goals:: Goals behind DejaGnu -* Posix:: DejaGnu conforms to POSIX 1003.3 -* Future Directions:: Where is DejaGnu going? -* Tcl and Expect:: Reading more about Tcl and Expect +* What is DejaGnu ?:: +* What_s New In This Release: Release Notes. +* Design Goals:: +* A POSIX conforming test framework: A POSIX Conforming Test Framework. @end menu -@node What is New -@chapter What is new in this release ? -@cindex What is New - -This release has a number of substantial changes over version 1.2. The -most visible change is that the version of expect and Tcl included in -the release are up-to-date with the current stable net releases. Other -changes are: +@node What is DejaGnu ?, Release Notes, , Overview +@section What is DejaGnu ? + +DejaGnu is a framework for +testing other programs. Its purpose is to provide a single +front end for all tests. Think of it as a custom library of +Tcl procedures crafted to support writing a test harness. A +@i{Test Harness} is the testing +infrastructure that is created to support a specific program +or tool. Each program can have multiple testsuites, all +supported by a single test harness. DejaGnu is written in +Expect, which in turn uses +Tcl -- Tool command +language. There is more information on Tcl at the @uref{http://www.scriptics.com,Scriptics} web site and the +Expect web site is at @uref{http://expect.nist.gov,NIST}. + +Julia Menapace first coined the term ``DejaGnu'' to describe +an earlier testing framework at Cygnus Support she had written +for @code{GDB}. When we replaced it with the +Expect-based framework, it was like DejaGnu all over again. +More importantly, it was also named after my daughter, @uref{http://www.welcomehome.org/deja/,Deja Snow Savoye} +(now 14 years old as of Feb 2004), who was a toddler +during DejaGnu's beginnings. + +DejaGnu offers several advantages for testing: + +@itemize @bullet{} -@enumerate @item -@c FIXME: add a link to the config section -The config sub-system in DejaGnu has been completely redesigned. It now -supports testing on remote hosts as well as remote targets. +The flexibility and consistency of the DejaGnu +framework make it easy to write tests for any program, with +either batch oriented, or interactive programs. @item -More builtin support for building target binaries with the correct -linker flags. Currently this only works with GCC, preferably with a -target support by @code{libgloss}. +DejaGnu provides a layer of abstraction which +allows you to write tests that are portable to any host or +target where a program must be tested. For instance, a test +for @code{GDB} can run from any supported host +system on any supported target system. DejaGnu runs tests on +many single board computers, whose operating software ranges +from a simple boot monitor to a real-time OS. @item -Lots of little bug fixes from a year of heavy use here at Cygnus -Support. +All tests have the same output format. This +makes it easy to integrate testing into other software +development processes. DejaGnu's output is designed to be +parsed by other filtering script and it is also human +readable. @item -DejaGnu now uses @code{autoconf} for configuration. +Using Tcl and Expect, it's easy to create wrappers +for existing testsuites. By incorporating existing tests under +DejaGnu, it's easier to have a single set of report analyse +programs.. +@end itemize -@item -New test cases for DejaGnu have been added for the new features, plus -the "--tool" option bug in the 1.2 testsuite has been fixed. +Running tests requires two things: the testing framework and +the testsuites themselves. Tests are usually written in +Expect using Tcl, but you can also use +a Tcl script to run a testsuite that is not based on +Expect. Expect +script filenames conventionally use @i{.exp} as a +suffix; for example, the main implementation of the DejaGnu test +driver is in the file +runtest.exp.) + +@node Release Notes, Design Goals, What is DejaGnu ?, Overview +@section What's New In This Release + +This release has a number of substantial changes over version +1.3. The most visible change is that the version of Expect and Tcl +included in the release are up-to-date with the current stable net +releases. The biggest change is years of modifications to the +target configuration system, used for cross testing. While this +greatly improved cross testing, is has made that subsystem very +complicated. The goal is to have this entirely rewritten using +iTcl by the next release. Other changes +are: + +@itemize @bullet{} @item -The @code{--tool} option is now optional. +More built-in support for building target binaries +with the correct linker flags. Currently this only works with +GCC as the cross compiler, +preferably with a target supported by +@ref{Libgloss,,Libgloss}.. @item -@code{runtest} when searching for test drivers ignores all directories -named SCCS, RCS, and CVS. +Lots of little bug fixes from years of heavy +use at Cygnus Solutions. @item -There is now a generic keyword based test harness that uses comments in -source code to control how each test case gets built and run. +DejaGnu now uses +Automake for Makefile +configuration. @item -There is now some support for running a testsuite with multiple passes -and multiple targets. - -@end enumerate - -@node Running Tests -@section Running existing tests -@cindex existing tests, running -@cindex running tests -@cindex tests, running - -@kindex make check -To run tests from an existing collection, first use @code{configure} as -usual to set up the source directory containing the tests. Then try -running - -@example -make check -@end example - -@cindex @code{check} makefile target -If the @code{check} target exists, it usually saves you some -trouble---for instance, it can set up any auxiliary programs or other -files needed by the tests. - -@cindex auxiliary files, building -Once you have run @samp{make check} to build any auxiliary files, you -might want to call the test driver @code{runtest} directly to repeat the -tests. You may also have to call @code{runtest} directly for test -collections with no @code{check} target in the @file{Makefile}. - -@c force page break to avoid losing footnote to another page -@page -@cindex @code{runtest}, most common options -@cindex options for @code{runtest}, common -Typically, you must use two command-line options: @samp{--tool}, to -specify which set of tests to run@footnote{@samp{--tool} selects a -particular suite of tests, @emph{not} the name of the executable program -to run. @xref{Config Values,,Configuration dependent values}, for -information on the variables that you can use to specify the names of -programs to run.}, and @samp{--srcdir}, to specify where to find test -directories. - -For example, if the directory @file{gdb/testsuite} contains a collection -of DejaGnu tests for @sc{gdb}, you can run them like this: - -@example -eg$ cd gdb/testsuite -eg$ runtest --tool gdb -@exdent @emph{Test output follows, ending with:} - - === gdb Summary === - -# of expected passes 508 -# of expected failures 103 -/usr/latest/bin/gdb version 4.14.4 -nx -@end example - -You can use the option @samp{--srcdir} to point to some other directory -containing a collection of tests: - -@smallexample -eg$ runtest --tool gdb --srcdir /devo/gdb/testsuite -@end smallexample - -@cindex native configuration -@cindex cross configuration -These examples assume a @dfn{native} configuration, where the same -computer runs both @code{runtest} and the tests themselves. When you -have a @dfn{cross} configuration, the tests run on a different computer, -controlled by the host running @code{runtest}. In this situation, you -need the option @samp{--name} to specify the network address for the -other computer: - -@smallexample -eg$ runtest --tool gdb --name vx9.munist.com -@end smallexample - -If you always use the same option values, you can record them in a file -called @file{site.exp}, rather than typing them each time. @xref{Config -Values,,Setting defaults for @code{runtest} options}. - -By default, @code{runtest} prints only the names of the tests it runs, -output from any tests that have unexpected results, and a summary -showing how many tests passed and how many failed. To display output -from all tests (whether or not they behave as expected), use the -@samp{--all} option. For more verbose output about processes being run, -communication, and so on, use @samp{--verbose}. To see even more output, -use multiple @samp{--verbose} options. @xref{Invoking runtest,,Using -@code{runtest}}, for a more detailed explanation of each @code{runtest} -option. - -Test output goes into two files in your current directory: summary -output in @file{@var{tool}.sum}, and detailed output in -@file{@var{tool}.log}. (@var{tool} refers to the collection of tests; -for example, after a run with @samp{--tool gdb}, look for output files -@file{gdb.sum} and @file{gdb.log}.) @xref{Output Files,,The files -DejaGnu writes}. - -@node Sample Test -@section What does a DejaGnu test look like? - -@cindex example -Each DejaGnu test is an @code{expect} script; the tests vary widely in -complexity, depending on the nature of the tool and the feature tested. - -@kindex gdb.t00/echo.exp -@kindex echo.exp -Here is a very simple @sc{gdb} test---one of the simplest tests shipped -with DejaGnu (extracted from @file{gdb.t00/echo.exp}):@footnote{More -recent @sc{gdb} tests use the @samp{gdb_test} procedure. -An equivalent test using that procedure is @samp{ gdb_test "echo Hello -world!" "Hello world!" }} -@c FIXME! include xref in footnote, when gdb_test documented in some manual. -@c @xref{}. -@c Extra spaces in @samp above avoid running end ' against " inside. - -@cartouche -@smallexample -# send a string to the GDB stdin: -send "echo Hello world!\n" - -# inspect the GDB stdout for the correct reply, -# and determine whether the test passes or fails: -expect @{ - -re "Hello world.*$prompt $" @{ pass "Echo test" @} - -re "$prompt $" @{ fail "Echo test" @} - timeout @{ fail "(timeout) Echo test" @} - @} -@end smallexample -@end cartouche - -Though brief, this example is a complete test. It illustrates some of -the main features of DejaGnu test scripts: +Updated documentation, now in DocBook XML. -@itemize @bullet @item -The test case does not start the tested program (@sc{gdb} in this case); -all test scripts for interactive tools can assume the corresponding tool -is running. +Windows support. There is beta level support for +Windows that is still a work in progress. This requires the +@uref{http://www.cygwin.com/,Cygwin} POSIX +subsystem for Windows. +@end itemize -@item -Comments start with @samp{#}. +@menu +* Windows Support:: +@end menu -@item -The main commands you use to control a tested program are @code{send} -(to give it commands) and @code{expect} (to analyze its responses). +@node Windows Support, , , Release Notes +@subsection Windows Support -@item -The @code{expect} command uses a list of pairs; a pattern (regular -expression if @samp{-re} specified), followed by an action to run if the -pattern matches output from the program. Only the action for the -@emph{first} matching pattern will execute. +To use DejaGnu on Windows, you need to first install the +@uref{http://www.cygwin.com/,Cygwin} +release. This works as of the B20.1 release. Cygwin is a POSIX +system for Windows. This covers both utility programs and a library +that adds POSIX system calls to Windows. Among them is pseudo tty +support for Windows that emulates the POSIX pty standard. The +latest Cygwin is always available from @uref{http://www.cygwin.com/,this location}. This +works well enough to run @i{"make check"} of +the GNU development tree on Windows after a native build. But the +nature of ptys on Windows is still evolving. Your mileage may +vary. -@item -Test cases use the commands @code{pass} and @code{fail} to record the -test outcome. -@end itemize +@node Design Goals, A POSIX Conforming Test Framework, Release Notes, Overview +@section Design Goals -@node Design Goals -@section Design goals -@cindex design goals +DejaGnu grew out of the internal needs of Cygnus Solutions, +the company formerly known as Cygnus Support. Cygnus maintained +and enhanced a variety of free programs in many different +environments and we needed a testing tool that: -DejaGnu grew out of the internal needs of Cygnus Support. Cygnus -maintains and enhances a variety of free programs in many different -environments, and we needed a testing tool that: +@itemize @bullet{} -@itemize @bullet @item -is useful to developers while fixing bugs; +was useful to developers while fixing +bugs; @item -automates running many tests during a software release process; +automated running many tests during a software +release process; @item -is portable among a variety of host computers; +was portable among a variety of host +computers; @item -supports cross-development testing; +supported cross-development +testing; @item -permits testing interactive programs, like @sc{gdb}; and +permitted testing interactive programs, like +@code{GDB}; and @item -permits testing batch oriented programs, like @sc{gcc}. +permitted testing batch oriented programs, like +@code{GCC}. @end itemize -Some of the requirements proved challenging. For example, interactive -programs do not lend themselves very well to automated testing. But all -the requirements are important: for instance, it is imperative to make -sure that @sc{gdb} works as well when cross-debugging as it does in a -native configuration. - -Probably the greatest challenge was testing in a cross-development -environment (which can be a real nightmare). Most cross-development -environments are customized by each developer. Even when buying -packaged boards from vendors there are many differences. The -communication interfaces vary from a serial line to ethernet. DejaGnu -was designed with a modular communication setup, so that each kind of -communication can be added as required, and supported thereafter. Once -a communication procedure is coded, any test can use it. Currently -DejaGnu can use @code{rsh}, @code{rlogin}, @code{telnet}, @code{tip}, -@code{kermit}, and @code{mondfe} for remote communications. - -@cindex name ``DejaGnu'' -@cindex DejaGnu, the name -@cindex Menapace, Julia -Julia Menapace first coined the term ``DejaGnu'' to describe an earlier -testing framework at Cygnus Support. When we replaced it with the -Expect-based framework, it was like DejaGnu all over again@dots{} - -@node Posix +Some of the requirements proved challenging. For example, +interactive programs do not lend themselves very well to automated testing. +But all the requirements are important: for instance, it is imperative to +make sure that @code{GDB} works as well when cross-debugging +as it does in a native configuration. + +Probably the greatest challenge was testing in a +cross-development environment. Most cross-development +environments are customized by each developer. Even when buying +packaged boards from vendors there are many differences. The +communication interfaces vary from a serial line to Ethernet. +DejaGnu was designed with a modular communication setup, so that +each kind of communication can be added as required and supported +thereafter. Once a communication procedure is coded, any test can +use it. Currently DejaGnu can use @code{rsh}, +@code{rlogin}, @code{telnet}, +@code{tip}, @code{kermit} and +@code{mondfe} for remote communications. + +@node A POSIX Conforming Test Framework, , Design Goals, Overview @section A POSIX conforming test framework -@cindex POSIX conformance -@cindex standard conformance: POSIX 1003.3 -DejaGnu conforms to the @sc{posix} standard for test frameworks. - -@cindex TET -@sc{posix} standard 1003.3 defines what a testing framework needs to -provide, in order to permit the creation of @sc{posix} conformance -test suites. This standard is primarily oriented to running @sc{posix} -conformance tests, but its requirements also support testing of features -not related to @sc{posix} conformance. @sc{posix} 1003.3 does not -specify a particular testing framework, but at this time there is only -one other @sc{posix} conforming test framework: -@sc{tet}.@footnote{@sc{tet} was created by Unisoft for a consortium -comprised of X/Open, Unix International, and the Open Software -Foundation.} - -The @sc{posix} documentation refers to @dfn{assertions}. An assertion -is a description of behavior. For example, if a standard says ``The sun -shall shine'', a corresponding assertion might be ``The sun is -shining.'' A test based on this assertion would pass or fail depending -on whether it is daytime or nighttime. It is important to note that the -standard being tested is never 1003.3; the standard being tested is some -other standard, for which the assertions were written. - -As there is no test suite to test @emph{testing frameworks} for -@sc{posix} 1003.3 conformance, verifying conformance to this standard is -done by repeatedly reading the standard and experimenting. One of the -main things 1003.3 does specify is the set of allowed output messages, -and their definitions. Four messages are supported for a required -feature of @sc{posix} conforming systems, and a fifth for a conditional -feature. DejaGnu supports the use of all five output messages; in this -sense a test suite that uses exactly these messages can be considered -@sc{posix} conforming. These definitions specify the output of a test +DejaGnu conforms to the POSIX 1003.3 standard for test +frameworks. Rob Savoye was a member of that committee. + +The POSIX standard 1003.3 defines what a testing framework needs to +provide, in order to permit the creation of POSIX conformance test +suites. This standard is primarily oriented to running POSIX conformance +tests, but its requirements also support testing of features not related +to POSIX conformance. POSIX 1003.3 does not specify a particular testing +framework, but at this time there is only one other POSIX conforming test +framework: TET. TET was created by Unisoft for a consortium comprised of +X/Open, Unix International and the Open Software Foundation. + +The POSIX documentation refers to @i{assertions}. +An assertion is a description of behavior. For example, if a standard +says ``The sun shall shine'', a corresponding assertion might be ``The +sun is shining.'' A test based on this assertion would pass or fail +depending on whether it is day or night. It is important to note +that the standard being tested is never 1003.3; the standard being tested +is some other standard, for which the assertions were written. + +As there is no testsuite to test testing frameworks for POSIX +1003.3 conformance, verifying conformance to this standard is done by +repeatedly reading the standard and experimenting. One of the main +things 1003.3 does specify is the set of allowed output messages and +their definitions. Four messages are supported for a required feature of +POSIX conforming systems and a fifth for a conditional feature. DejaGnu +supports the use of all five output messages. In this sense a testsuite +that uses exactly these messages can be considered POSIX conforming. +These definitions specify the output of a test case: -@ftable @code -@cindex success, POSIX definition +@table @asis + @item PASS -A test has succeeded. That is, it demonstrated that the assertion is true. +A test has succeeded. That is, it demonstrated that +the assertion is true. + +@item XFAIL +POSIX 1003.3 does not incorporate the notion of +expected failures, so @i{PASS}, instead of +@i{XPASS}, must also be returned for test cases +which were expected to fail and did not. This means that +@i{PASS} is in some sense more ambiguous than if +@i{XPASS} is also used. @item FAIL -@cindex failure, POSIX definition -A test @emph{has} produced the bug it was intended to capture. That is, -it has demonstrated that the assertion is false. The @code{FAIL} -message is based on the test case only. Other messages are used to -indicate a failure of the framework. +A test has produced the bug it was intended to +capture. That is, it has demonstrated that the assertion is false. +The @i{FAIL} message is based on the test case only. +Other messages are used to indicate a failure of the framework. As +with @i{PASS}, POSIX tests must return +@i{FAIL} rather than @i{XFAIL} even +if a failure was expected. @item UNRESOLVED -@cindex ambiguity, required for POSIX -A test produced indeterminate results. Usually, this means the test -executed in an unexpected fashion; this outcome requires that a human -being go over results, to determine if the test should have passed or -failed. This message is also used for any test that requires human -intervention because it is beyond the abilities of the testing -framework. Any unresolved test should resolved to @code{PASS} or -@code{FAIL} before a test run can be considered finished. - -Note that for @sc{posix}, each assertion must produce a test result -code. If the test isn't actually run, it must produce @code{UNRESOLVED} -rather than just leaving that test out of the output. This means that -you have to be careful when writing tests, to not carelessly use tcl -statements like @code{return}---if you alter the flow of control of the -tcl code you must insure that every test still produces some result code. +A test produced indeterminate results. Usually, this +means the test executed in an unexpected fashion; this outcome +requires that a human being go over results, to determine if the test +should have passed or failed. This message is also used for any test +that requires human intervention because it is beyond the abilities +of the testing framework. Any unresolved test should resolved to +@i{PASS} or @i{FAIL} before a test +run can be considered finished. + +Note that for POSIX, each assertion must produce a test result +code. If the test isn't actually run, it must produce +@i{UNRESOLVED} rather than just leaving that test +out of the output. This means that you have to be careful when +writing tests to not carelessly use Tcl commands like +@i{return}---if you alter the flow of control of the +Tcl code you must insure that every test still produces some result +code. + +Here are some of the ways a test may wind up +@i{UNRESOLVED}: +@end table -Here are some of the ways a test may wind up @code{UNRESOLVED}: +@itemize @bullet{} -@itemize @bullet @item -A test's execution is interrupted. +A test's execution is +interrupted. @item -A test does not produce a clear result. This is usually because there -was an @code{ERROR} from DejaGnu while processing the test, or because there -were three or more @code{WARNING} messages. Any @code{WARNING} or -@code{ERROR} messages can invalidate the output of the test. This +A test does not produce a clear +result. This is usually because there was an +@i{ERROR} from DejaGnu while processing +the test, or because there were three or more +@i{WARNING} messages. Any +@i{WARNING} or @i{ERROR} +messages can invalidate the output of the test. This usually requires a human being to examine the output to -determine what really happened---and to improve the test case. +determine what really happened---and to improve the test +case. @item -A test depends on a previous test, which fails. +A test depends on a previous test, which +fails. @item -The test was set up incorrectly. +The test was set up +incorrectly. @end itemize +@table @asis + @item UNTESTED -A test was not run. This is a placeholder, used when there is no -real test case yet. -@end ftable +A test was not run. This is a place-holder, used +when there is no real test case yet. +@end table -@noindent -The only remaining @sc{posix} output message left is intended to test -features that are specified by the applicable @sc{posix} standard as +The only remaining output message left is intended to test +features that are specified by the applicable POSIX standard as conditional: -@ftable @code +@table @asis + @item UNSUPPORTED -There is no support for the tested case. This may mean that a -conditional feature of an operating system, or of a compiler, is not -implemented. DejaGnu also uses this message when a testing environment -(often a ``bare board'' target) lacks basic support for compiling or -running the test case. For example, a test for the system subroutine -@code{gethostname} would never work on a target board running only a -boot monitor. -@end ftable - -DejaGnu uses the same output procedures to produce these messages for -all test suites, and these procedures are already known to conform to -@sc{posix} 1003.3. For a DejaGnu test suite to conform to @sc{posix} -1003.3, you must avoid the @code{setup_xfail} and @code{setup_kfail} -procedures (see below), and you must be careful to return -@code{UNRESOLVED} where appropriate, as described in the -@code{UNRESOLVED} section above. - -Besides the @sc{posix} messages, DejaGnu provides for variations of the -PASS and FAIL messages that can be helpful for the tool maintainers. -It must be noted, however, that this feature is not @sc{posix} 1003.3 -compliant, so its use should be avoided if compliance is necessary. - -The additional messages are: - -@ftable @code +There is no support for the tested case. This may +mean that a conditional feature of an operating system, or of a +compiler, is not implemented. DejaGnu also uses this message when +a testing environment (often a ``bare board'' target) lacks basic +support for compiling or running the test case. For example, a +test for the system subroutine @i{gethostname} +would never work on a target board running only a boot +monitor. +@end table -@item XFAIL -A test is expected to fail in some environment(s) due to some bug -in the environment that we hope is fixed someday (but we can't do -nothing about as it is not a bug in the tool that we are testing). -The procedure @code{setup_xfail} is used to indicate that a failure -is expected. - -@cindex XFAIL, avoiding for POSIX -@sc{posix} 1003.3 does not incorporate the notion of expected failures, -so @sc{posix} tests must return @code{FAIL} rather -than @code{XFAIL} even if a failure was expected. - -@item KFAIL -A test is known to fail in some environment(s) due to a known bug -in the tool being tested (identified by a bug id string). This -exists so that, after a bug is identified and properly registered -in a bug tracking database (Gnats, for instance), the count of -failures can be kept as zero. Having zero as a baseline in all -platforms allow the tool developers to immediately detect regressions -caused by changes (which may affect some platforms and not others). -The connection with a bug tracking database allows for automatic -generation of the BUGS section of man pages or Release Notes, as -well as a "Bugs Fixed this Release" section (by comparing to a -previous release set of known failures). -The procedure @code{setup_kfail} is used to indicate a failure is -known to exist. - -@cindex KFAIL, avoiding for POSIX -As with @code{XFAIL}, @sc{posix} tests must return @code{FAIL} rather -than @code{KFAIL} even if a failure was due to a known bug. +DejaGnu uses the same output procedures to produce these messages +for all testsuites and these procedures are already known to conform +to POSIX 1003.3. For a DejaGnu testsuite to conform to POSIX 1003.3, +you must avoid the @i{setup}xfail@} procedure as +described in the @i{PASS} section above and you must +be careful to return @i{UNRESOLVED} where appropriate, +as described in the @i{UNRESOLVED} section +above. +@node Getting DejaGnu up and running, Running Tests, Overview, Top +@chapter Getting DejaGnu up and running -@item XPASS -A test was expected to fail with @code{XFAIL} but passed instead. -Whatever problem that used to exist in the environment was corrected -The test may also be failing to detect the failure due to some -environment or output changes, so this possibility must be investigated -as well. - -@item KPASS -A test was expected to fail with @code{KFAIL} but passed instead. -Someone may have fixed the bug and failed to unmark the test. -As for XPASS, the test may also be failing to detect the -failure due to some environment or output changes, so this possibility -must also be checked. - -@code{PASS}, instead of @code{XPASS} or @code{KPASS}, must also be -returned for test cases which were expected to fail and did not, -if @sc{posix} 1003.3 compliance is required. -This means that @code{PASS} is in some sense more ambiguous than if -@code{XPASS} and @code{KPASS} are also used. - -@end ftable - -See also @ref{Invoking runtest,,Using @code{runtest}}. -For information on how to mark tests as expected/known to fail by using -@code{setup_xfail} and @code{setup_kfail}, see -@ref{framework.exp,,Core Internal Procedures}. - - -@node Future Directions -@section Future directions -@cindex future directions - -In the near future, there are two parallel directions for DejaGnu -development. The first is to add support for more hosts and targets. - -The second would permit testing programs with a more complex interface, -whether text based or GUI based. Two components already exist: a Tcl -based X window toolkit, and a terminal package for @code{expect}. Both -of these could be merged into DejaGnu in a way that permits testing -programs that run in each environment. - -Meanwhile, we hope DejaGnu enables the creation of test suites for -conformance to @sc{ansi} C and C++, to @sc{posix}, and to other -standards. We encourage you to make any test suites you create freely -available, under the same terms as DejaGnu itself. - -@node Tcl and Expect -@section Tcl and Expect -@cindex tool command language -@cindex tcl -@cindex Ousterhout, John K. -Tcl was introduced in a paper by John K. Ousterhout at the 1990 Winter -Usenix conference, @cite{Tcl: An Embeddable Command Language}. That -paper is included in PostScript form in the @file{doc} subdirectory of -the Tcl distribution. The version of Tcl included in DejaGnu at this time is -Tcl 7.4p3. - -@cindex @code{expect} scripting language -@cindex Libes, Don -Don Libes introduced @code{expect} in his paper @cite{expect: Curing -Those Uncontrollable Fits of Interaction} at the 1990 Summer Usenix -conference. The paper is included in PostScript form in the -@code{expect} distribution (as are several other papers about -@code{expect}). The version of expect included in DejaGnu at this time -is expect 5.18.0. - -@node Invoking runtest -@chapter Using @code{runtest} -@cindex invoking -@cindex running -@cindex command line options -@cindex options - -@cindex @code{runtest} description -@cindex DejaGnu test driver -@code{runtest} is the executable test driver for DejaGnu. You can -specify two kinds of things on the @code{runtest} command line: command -line options, and Tcl variables for the test scripts. The options are -listed alphabetically below. - -@cindex exit code from @code{runtest} -@cindex @code{runtest} exit code -@code{runtest} returns an exit code of @code{1} if any test -has an unexpected result; otherwise (if all tests pass or fail as -expected) it returns @code{0} as the exit code. - -@code{runtest} flags the outcome of each test as one of these cases. -(@xref{Posix,,A POSIX conforming test framework}, for a discussion of -how @sc{posix} specifies the meanings of these cases.) - -@table @code -@item PASS -@kindex PASS -@cindex successful test -@cindex test, successful -The most desirable outcome: the test succeeded, and was expected to -succeed. +This chapter was originally written by Niklaus Giger +(ngiger@@mus.ch) because he lost a week to figure out how DejaGnu works +and how to write a first test. -@item XPASS -@kindex XPASS -@cindex successful test, unexpected -@cindex unexpected success -A pleasant kind of failure: a test was expected to fail, but succeeded. -This may indicate progress; inspect the test case to determine whether -you should amend it to stop expecting failure. - -@item KPASS -@kindex KPASS -@cindex successful test, unexpected -@cindex unexpected success -A pleasant kind of failure: a test was known to fail, but succeeded. -This may indicate progress; inspect the test case to determine whether -you should amend it to stop expecting failure. - -@item KPASS -@kindex KPASS -@cindex successful test, unexpected -@cindex unexpected success -A pleasant kind of failure: a test was known to fail, but succeeded. -This may indicate progress; inspect the test case to determine whether -you should amend it to stop expecting failure. +Follow these instructions as closely a possible in order get a +good insight into how DejaGnu works, else you might run into a lot of +subtle problems. You have been warned. -@item FAIL -@kindex FAIL -@cindex failing test, unexpected -@cindex test, failing -A test failed, although it was expected to succeed. This may indicate -regress; inspect the test case and the failing software to locate the bug. +It should be no big problems installing DejaGnu using your +package manager or from the source code. Under a Debian/GNU/Linux +systems just type (as root) -@item XFAIL -@kindex XFAIL -@cindex expected failure -@cindex failing test, expected -A test failed, but it was expected to fail. This result indicates no -change in a known environment bug. If a test fails because the operating -system where the test runs lacks some facility required by the test -(i.e. failure is due to the lack of a feature, not the existence of a bug), -the outcome is @code{UNSUPPORTED} instead. - -@item KFAIL -@kindex KFAIL -@cindex known failure -@cindex failing test, known -A test failed, but it was known to fail. This result indicates no -change in a known bug. If a test fails because of a problem in the -environment, not in the tool being tested, that is expected to be -fixed one day, the outcome is @code{XFAIL} instead. +@example +apt-get +dejagnu +@end example -@item UNRESOLVED -@kindex UNRESOLVED -@cindex test, unresolved outcome -Output from a test requires manual inspection; the test suite could not -automatically determine the outcome. For example, your tests can report -this outcome is when a test does not complete as expected. +@noindent +. These examples were run on a primary machine +with a AMD K6 and a Mac Powerbook G3 serving as a remote +target. -@item UNTESTED -@kindex UNTESTED -@cindex untested properties -A test case is not yet complete, and in particular cannot yet produce a -@code{PASS} or @code{FAIL}. You can also use this outcome in dummy -``tests'' that note explicitly the absence of a real test case -for a particular property. +The tests for Windows were run under Windows NT using the +actual Cygwin version (1.3.x as of October 2001). It's target system +was a PPC embedded system running vxWorks. -@item UNSUPPORTED -@kindex UNSUPPORTED -@cindex unsupported test -@cindex test, unsupported -A test depends on a conditionally available feature that does not exist -(in the configured testing environment). For example, you can use this -outcome to report on a test case that does not work on a particular -target because its operating system support does not include a required -subroutine. -@end table +@menu +* Test your installation:: +* Create a minimal project; e_g_ calc:: +* Our first automated tests:: +* A first remote test:: +@end menu -@code{runtest} may also display the following messages: +@node Test your installation, Create a minimal project; e_g_ calc, , Getting DejaGnu up and running +@section Test your installation -@table @code -@item ERROR -@kindex ERROR -@cindex problem, detected by test case -@cindex test case cannot run -Indicates a major problem (detected by the test case itself) in running -the test. This is usually an unrecoverable error, such as a missing file -or loss of communication to the target. (@sc{posix} test suites should -not emit this message; use @code{UNSUPPORTED}, @code{UNTESTED}, or -@code{UNRESOLVED} instead, as appropriate.) +Create a new user called "dgt" (DejaGnuTest), which uses bash as +it login shell. PS1 must be set to '\u:\w\$ ' in its ~/.bashrc. Login +as this user, create an empty directory and change the working +directory to it. e.g -@item WARNING -@kindex WARNING -@cindex test case warnings -Indicates a possible problem in running the test. Usually warnings -correspond to recoverable errors, or display an important message about -the following tests. +@example -@item NOTE -@kindex NOTE -@cindex test case messages -An informational message about the test case. -@end table - -This is the full set of command line options that @code{runtest} -recognizes. Arguments may be abbreviated to the shortest unique string. - -@cindex @code{runtest} option list -@cindex option list, @code{runtest} -@smallexample -runtest --tool @var{tool} [ @var{testsuite}.exp @dots{} ] -[ @var{testsuite}.exp="testfile1 @dots{}" ] -[ @var{tclvar}=@var{value}@dots{} ] -[ --all ] [ --baud @var{baud-rate} ] [ --connect @var{type} ] -[ --debug ] [ --help ] [ --host @var{string} ] -[ --mail "@var{name} @dots{}" ] [ --name @var{string} ] -[ --name @var{name} ] [ --outdir @var{path} ] -[ --objdir @var{path} ] [ --reboot ] -[ --srcdir @var{path} ] [ --strace @var{n} ] -[ --target @var{string} --build @var{string} ] -[ -v | --verbose ] [ -V | --version ] [ --D@var{n} ] -@end smallexample - -@table @code -@item --tool @var{tool} -@cindex selecting tests for a tool -@cindex @code{--tool} (@code{runtest} option) -@var{tool} specifies what set of tests to run, and what initialization -module to use. @var{tool} is used @emph{only} for these two purposes: -it is @emph{not} used to name the executable program to test. -Executable tool names (and paths) are recorded in @file{site.exp} -(@pxref{Config Values,,Configuration dependent values}), and you can -override them by specifying Tcl variables on the command line. - -For example, including @samp{--tool gcc} on the @code{runtest} command -line runs tests from all test subdirectories whose names match -@file{gcc.*}, and uses one of the initialization modules named -@file{config/*-gcc.exp}. To specify the name of the compiler (perhaps -as an alternative path to what @code{runtest} would use by default), use -@samp{GCC=@var{binname}} on the @code{runtest} command line. - -@item @var{testsuite}.exp @dots{} -@cindex selecting a range of tests -@cindex tests, running specifically -@cindex naming tests to run -Specify the names of testsuites to run. -By default, @code{runtest} runs all tests for the tool, but you can -restrict it to particular testsuites by giving the names of the @samp{.exp} -@code{expect} scripts that control them. - -@var{testsuite}.exp may not include path information; use plain filenames. - -@item @var{testfile}.exp="testfile1 @dots{}" -@cindex selecting a range of tests -@cindex tests, running specifically -@cindex naming tests to run -Specify a subset of tests in a suite to run. -For compiler or assembler tests, which often use a single @samp{.exp} -script covering many different source files, this option allows you to -further restrict the tests by listing particular source files to compile. -Some tools even support wildcards here. The wildcards supported depend -upon the tool, but typically they are @code{?}, @code{*}, and @code{[chars]}. - -@item @var{tclvar}=@var{value} -@kindex @var{tclvar}=@var{value} -@cindex Tcl variables, defining for @code{runtest} -@cindex command line Tcl variable definition -@cindex @code{runtest}, variable defns on cmdline -You can define Tcl variables for use by your test scripts in the same -style used with @code{make} for environment variables. For example, -@samp{runtest GDB=gdb.old} defines a variable called @samp{GDB}; when -your scripts refer to @samp{$GDB} in this run, they use the value -@samp{gdb.old}. - -The default Tcl variables used for most tools are defined in the main -DejaGnu @code{Makefile}; their values are captured in the -@file{site.exp} file. @xref{Config Values,,Configuration dependent -values}. - -@item --all -@cindex @code{--all} (@code{runtest} option) -@cindex test output, displaying all -Display all test output. By default, @code{runtest} shows only the -output of tests that produce unexpected results; that is, tests with -status @samp{FAIL} (unexpected failure), @samp{XPASS} or @samp{KPASS} -(unexpected success), or @samp{ERROR} (a severe error in the test case itself). -Specify @samp{--all} to see output for tests with status @samp{PASS} -(success, as expected) @samp{XFAIL} (failure, as expected), or -@samp{WARNING} (minor error in the test case itself). - -@item --baud @var{baud-rate} -@itemx -b @var{baud-rate} -@cindex baud rate, specifying -@cindex bps, specifying -@cindex @code{--baud} (@code{runtest} option) -@cindex @code{-b} (@code{runtest} option) -Set the default baud rate to something other than 9600. (Some serial -interface programs, like @code{tip}, use a separate initialization file -instead of this value.) - -@item --connect @var{type} -@cindex connecting to target -@cindex @code{--connect} (@code{runtest} option) -@cindex remote testbed, connecting to -@cindex @code{rlogin}, remote testing via -@cindex @code{telnet}, remote testing via -@cindex @code{rsh}, remote testing via -@cindex @code{tip}, remote testing via -@cindex @code{kermit}, remote testing via -@cindex @code{mondfe}, remote testing via -@cindex remote testing via @code{rlogin} -@cindex remote testing via @code{telnet} -@cindex remote testing via @code{rsh} -@cindex remote testing via @code{tip} -@cindex remote testing via @code{kermit} -@cindex remote testing via @code{mondfe} -Connect to a target testing environment as specified by @var{type}, if -the target is not the computer running @code{runtest}. For example, use -@samp{--connect} to change the program used to connect to a ``bare -board'' boot monitor. The choices for @var{type} in the DejaGnu 1.0 -distribution are @samp{rlogin}, @samp{telnet}, @samp{rsh}, @samp{tip}, -@samp{kermit}, and @samp{mondfe}. +dgt:~$ mkdir ~/dejagnu.test +dgt:~$ cd ~/dejagnu.test +@end example -@noindent -The default for this option depends on the configuration (@pxref{Cross -Targets,,Remote targets supported}). The default is chosen to be the -most convenient communication method available, but often other -alternatives work as well; you may find it useful to try alternative -connect methods if you suspect a communication problem with your testing -target. +Now you are ready to test DejaGnu's main program called +runtest. The expecteted output is shown -@item --debug -@cindex @code{--debug} (@code{runtest} option) -@cindex debug log for test cases -@cindex test cases, debug log -@cindex @code{dbg.log} file -Turns on the @code{expect} internal debugging output. Debugging output -is displayed as part of the @code{runtest} output, and logged to a file -called @file{dbg.log}. The extra debugging output does @emph{not} -appear on standard output, unless the verbose level is greater than 2 -(for instance, to see debug output immediately, specify @samp{--debug -v --v}). The debugging output shows all attempts at matching the test -output of the tool with the scripted patterns describing expected -output. The output generated with @samp{--strace} also goes into -@file{dbg.log}. +@strong{Runtest output in a empty directory +} -@item --help -@itemx -he -@cindex @code{--help} (@code{runtest} option) -@cindex help with @code{runtest} -@cindex @code{runtest}, listing options -Prints out a short summary of the @code{runtest} options, then exits -(even if you also specify other options). - -@item --host @var{string} -@cindex @code{--host} (@code{runtest} option) -@cindex specifying the host config name -@cindex host config name, changing -@var{string} is a full configuration ``triple'' name as used by -@code{configure}. Use this option to override the default string -recorded by your configuration's choice of host. This choice does not -change how anything is actually configured unless --build is also -specified; it affects @emph{only} DejaGnu procedures that compare the -host string with particular values. The procedures @code{ishost}, -@code{istarget}, @code{isnative}, @code{setup_xfail} and -@code{setup_kfail} are affected by @samp{--host}. -In this usage, @code{host} refers to the machine that the -tests are to be run on, which may not be the same as the @code{build} -machine. If @code{--build} is also specified, then @code{--host} refers -to the machine that the tests wil, be run on, not the machine DejaGnu is -run on. - -@item --build @var{string} -@cindex @code{--build} (@code{runtest} option) -@cindex specifying the build config name -@cindex build config name, changing -@var{string} is a full configuration ``triple'' name as used by -@code{configure}. This is the type of machine DejaGnu and the tools to -be tested are built on. For a normal cross this is the same as the host, -but for a canadian cross, they are seperate. - -@item --name @var{name} -@cindex specifying target name -@cindex target machine name -@cindex @code{--name} (@code{runtest} option) -@var{name} is a name for the particular testing target machine (for -cross testing). If the testing target has IP network support (for -example, @code{RPC} or @code{NFS}), this is the network name for the -target itself. (@var{name} is @emph{not the configuration string} you -specify as a target with @code{configure}; the @samp{--name} option -names a particular target, rather than describing a class of targets.) -For targets that connect in other ways, the meaning of the @var{name} -string depends on the connection method. @xref{Cross Targets,,Remote -targets supported}. - -@item --name @var{string} -@cindex remote test machine name -@cindex name for remote test machine -Specify a network name of testing target or its host. The particular -names that are meaningful with @samp{--name} will depend on your site -configuration, and on the connection protocol: for example, @code{tip} -connections require names from a serial line configuration file (usually -called @file{/etc/remote}), while @code{telnet} connections use IP -hostnames. - -@item --objdir @var{path} -@cindex @code{--objdir} (@code{runtest} option) -@cindex object directory -@cindex test programs, auxiliary -@cindex auxiliary test programs -Use @var{path} as the top directory containing any auxiliary compiled -test code. This defaults to @file{.}. Use this option to locate -pre-compiled test code. You can normally prepare any auxiliary files -needed with @code{make}. - -@item --outdir @var{path} -@cindex output directory -@cindex @code{--outdir} (@code{runtest} option) -@cindex log files, where to write -Write output logs in directory @var{path}. The default is @samp{.}, the -directory where you start @code{runtest}. This option affects only the -summary and the detailed log files @file{@var{tool}.sum} and -@file{@var{tool}.log}. The DejaGnu debug log @file{dbg.log} always -appears (when requested) in the local directory. - -@item --reboot -@cindex rebooting remote targets -@cindex @code{--reboot} (@code{runtest} option) -Reboot the target board when @code{runtest} initializes. -Usually, when running tests on a separate target board, it is safer to -reboot the target to be certain of its state. However, when developing -test scripts, rebooting takes a lot of time. - -@item --srcdir @var{path} -@cindex source directory -@cindex @code{--srcdir} (@code{runtest} option) -Use @var{path} as the top directory for test scripts to run. -@code{runtest} looks in this directory for any subdirectory whose name -begins with the toolname (specified with @samp{--tool}). For instance, -with @samp{--tool gdb}, @code{runtest} uses tests in subdirectories -@file{gdb.*} (with the usual shell-like filename expansion). If you do -not use @samp{--srcdir}, @code{runtest} looks for test directories under -the current working directory. - -@item --strace @var{n} -@cindex @code{--strace} (@code{runtest} option) -@cindex tracing Tcl commands -@cindex @code{expect} internal tracing -Turn on internal tracing for @code{expect}, to @var{n} levels deep. By -adjusting the level, you can control the extent to which your output -expands multi-level Tcl statements. This allows you to ignore some -levels of @code{case} or @code{if} statements. Each procedure call or -control structure counts as one ``level''. - -The output is recorded in the same file, @file{dbg.log}, used for output -from @samp{--debug}. - -@item --target @var{string} -@cindex @code{--target} (@code{runtest} option) -@cindex specifying the target configuration -@cindex target configuration, specifying -Use this option to override the default setting (running native tests). -@var{string} is a full configuration ``triple'' -name@footnote{Configuration triples have the form -@samp{@var{cpu}-@var{vendor}-@var{os}}.} as used by @code{configure}. -This option changes the configuration @code{runtest} uses for the -default tool names, and other setup information. @xref{Using -configure,,Using @code{configure}, configure.info, Cygnus configure}, -for details about @code{configure} names. - -@item --verbose -@itemx -v -@cindex @code{--verbose} (@code{runtest} option) -@cindex @code{-v} (@code{runtest} option) -@cindex turning on output -@cindex output, additional -Turns on more output. Repeating this option increases the amount of -output displayed. Level one (@samp{-v}) is simply test output. Level -two (@samp{-v -v}) shows messages on options, configuration, and process -control. Verbose messages appear in the detailed (@file{*.log}) log -file, but not in the summary (@file{*.sum}) log file. - -@item --version -@itemx -V -@cindex @code{-V} (@code{runtest} option) -@cindex @code{--version} (@code{runtest} option) -@cindex version numbers -Prints out the version numbers of DejaGnu, @code{expect} and Tcl, and -exits without running any tests. - -@item -D0 -@itemx -D1 -@cindex starting the tcl debugger -@cindex tcl debugger -@c FIXME!!! we should say a *lot* more about this debugger -Start the internal Tcl debugger. The Tcl debugger supports breakpoints, -single stepping, and other common debugging activities. (See @cite{A -Debugger for Tcl Applications} by Don Libes. @footnote{Distributed in -PostScript form with @code{expect} as the file@* -@file{expect/tcl-debug.ps}.}) - -If you specify @samp{-D1}, the @code{expect} shell stops at a breakpoint -as soon as DejaGnu invokes it. - -If you specify @samp{-D0}, DejaGnu starts as usual, but you can enter -the debugger by sending an interrupt (e.g. by typing @key{C-c}). -@end table - -@node Customizing -@chapter Setting @code{runtest} defaults - -@kindex site.exp -@cindex variables of DejaGnu, defaults -The site configuration file, @file{site.exp}, captures -configuration-dependent values and propagates them to the DejaGnu test -environment using Tcl variables. This ties the DejaGnu test scripts -into the @code{configure} and @code{make} programs. - -@cindex @file{site.exp}, multiple -@cindex overriding @file{site.exp} -DejaGnu supports more than one @file{site.exp} file. The multiple -instances of @file{site.exp} are loaded in a fixed order built into -DejaGnu (the more local last). The first file loaded is the optional -@code{~/.dejagnurc}, then the local files, and finally the global file. - -@enumerate -@item -There is am optional ``master'' @file{site.exp}, capturing configuration values -that apply to DejaGnu across the board, in each configuration-specific -subdirectory of the DejaGnu library directory. @code{runtest} loads -these values first. @xref{Installation,,Configuring and Installing -DejaGnu}. The master @file{site.exp} contains the default values for -all targets and hosts supported by DejaGnu. This master file is -identified by setting the environment variable @code{DEJAGNU} to the -name of the file. This is also refered to as the ``global'' config file. - -@item -Any directory containing a configured test suite also has a -@file{site.exp}, capturing configuration values specific to the tool -under test. Since @code{runtest} loads these values last, the -individual test configuration can either rely on and use, or override, -any of the global values from the ``master'' @file{site.exp}. - -You can usually generate or update the testsuite @file{site.exp} by -typing @samp{make site.exp} in the test suite directory, after the test -suite is configured. +@example -@item -You can also have a file in your home directory called -@code{.dejagnurc}. This gets loaded first before the other config -files. Usually this is used for personal stuff, like setting -@code{all_flag} so all the output gets printed, or verbosity levels. -@end enumerate +dgt:~/dejagnu.test$ runtest +WARNING: Couldn't find the global config file. +WARNING: No tool specified Test +Run By dgt on Sun Nov 25 17:07:03 2001 Native configuration is i586-pc-linux-gnu +=== tests === +Schedule of variations: unix +Running target unix Using /usr/share/dejagnu/baseboards/unix.exp as board description file for target. +Using /usr/share/dejagnu/config/unix.exp as generic interface file for target. +ERROR: Couldn't find tool config file for unix. +=== Summary === +@end example -You can further override the default values in a user-editable section -of any @file{site.exp}, or by setting variables on the @code{runtest} -command line. +We will show you later how to get rid of all the WARNING- and +ERROR-messages. The files testrun.sum and testrun.log have been +created, which do not interest us at this point. Let's remove +them. + +@example +:~/dejagnu.test$ rm testrun.sum testrun.log +@end example @menu -* Config Values:: Variables used in the configuration file. -* Master Config File:: The master configuration file. -* Local Config File:: The local configuration file. -* Personal Config File:: The personal configuration file. +* Windows:: +* Getting the source code for the calc example:: @end menu -@node Config Values, Master Config File, , Customizing -@subsection Config Variables -@cindex configuration dependent defaults -@cindex setting defaults for DejaGnu variables - -@c NOTE: default values are given via @code{"fubar"} rather than the -@c more conventional @samp{fubar} to permit a consistent and clear -@c notation for the empty string (@code{""}), which will work exactly as -@c typed. - -DejaGnu uses a named array in Tcl to hold all the info for each -machine. In the case of a canadian cross, this means host information as -well as target information. The named array is called -@code{target_info}, and it has two indices. The following fields are -part of the array. - -@table @code -@item name -The name of the target. (mostly for error messages) This -should also be the string used for this target's array. -It should also be the same as the linker script so we -can find them dynamically. This should be the same as the argument used -for @code{push_target@{@}}. - -@item ldflags -This is the linker flags required to produce a fully linked -executable. For @code{libgloss} supported targets this is usually just -the name of the linker script. - -@item config -The target canonical for this target. This is used by some init files to -make sure the target is supported. - -@item cflags -The flags required to produce an object file from a source file. - -@item connect -This is the connectmode for this target. This is for both IP and -serial connections. Typically this is either @code{telnet}, -@code{rlogin}, or @code{rsh}. - -@item target -This is the hostname of the target. This is for TCP/IP based connections, -and is also used for version of tip that use /etc/remote. - -@item serial -This is the serial port. This is typically /dev/tty? or com?:. - -@item netport -This is the IP port. This is commonly used for telneting to target -boards that are connected to a terminal server. In that case the IP port -specifies the which serial port to use. - -@item baud -This is the baud rate for a serial port connection. - -@item x10 -This is the parameters for an x10 controller. These are simple devices -that let us power cycle or reset a target board remotely. - -@item fileid -This is the fileid or spawn id of of the connection. - -@item prompt -a glob style pattern to recognize the prompt. - -@item abbrev -abbreviation for tool init files. - -@item ioport -This is the port for I/O on dual port systems. In this configuration, -the main serial port @code{0} is usually used for stdin and stdout, -which the second serial port can be used for debugging. -@end table - -The first index into the array is the same value as used in the -@code{name} field. This is usually a short version of the name of the -target board. For an example, here's the settings I use for my -@code{Motorola's} @code{IDP} board and my @code{Motorola} 6U VME -@code{MVME135-1} board. (both m68k targets) - -@cartouche -@smallexample -# IDP board -set target_info(idp,name) "idp" -set target_info(idp,ldflags) "-Tidp.ld" -set target_info(idp,config) m68k-unknown-aout -set target_info(idp,cflags) "" -set target_info(idp,connect) telnet -set target_info(idp,target) "s7" -set target_info(idp,serial) "tstty7" -set target_info(idp,netport) "wharfrat:1007" -set target_info(idp,baud) "9600" -# MVME 135 board -set target_info(idp,name) "mvme" -set target_info(idp,ldflags) "-Tmvme.ld" -set target_info(idp,config) m68k-unknown-aout -set target_info(idp,cflags) "" -set target_info(idp,connect) telnet -set target_info(idp,target) "s8" -set target_info(idp,serial) "tstty8" -set target_info(idp,netport) "wharfrat:1008" -set target_info(idp,baud) "9600" -@end smallexample -@end cartouche - -DejaGnu can use this information to switch between multiple targets in -one test run. This is done through the use of the @code{push_target} -procedure, which is discussed elsewhere. -@c FIXME: write that section and put an xref here - -This array can also hold information for a remote host, which is used -when testing a candain cross. In this case, the only thing different is -the index is just @code{host}. Here's the settings I use to run tests -on my NT machine while running DejaGnu on a Unix machine. (in this case -a Linux box) - -@cartouche -@smallexample -set target_info(host,name) "nt-host" -set target_info(host,config) "386-unknown-winnt" -set target_info(host,connect) "telnet" -set target_info(host,target) "ripple" -@end smallexample -@end cartouche - -There is more info on how to use these variables in the sections on the -config files. @xref{Master Config File,,Configuration Files}. - -@cindex option defaults -@cindex @code{runtest} option defaults -@cindex variables for option defaults -@cindex defaults, option -In the user editable second section of @file{site.exp}, you can not only -override the configuration variables captured in the first section, but -also specify default values for all the @code{runtest} command line -options. Save for @samp{--debug}, @samp{--help}, and @samp{--version}, -each command line option has an associated Tcl variable. Use the Tcl -@code{set} command to specify a new default value (as for the -configuration variables). The following table describes the -correspondence between command line options and variables you can set in -@file{site.exp}. @xref{Invoking runtest,,Running the Tests}, for -explanations of the command-line options. - -@kindex all_flag -@kindex baud -@kindex reboot -@kindex outdir -@kindex objdir -@kindex runtests -@kindex ignoretests -@kindex srcdir -@kindex tracelevel -@kindex targetname -@kindex connectmode -@kindex tool -@kindex target_triplet -@kindex host_triplet -@kindex build_triplet -@kindex verbose - -@cindex command line option variables -@cindex Tcl variables for option defaults -@cindex default options, controlling -@cindex options, Tcl variables for defaults - -@ifinfo -@display -runtest Tcl -option variable description -__________ ________ ___________________________________________ - ---all all_flag display all test results if set - ---baud baud set the default baud rate to something other - than 9600. ---connect connectmode @samp{rlogin}, @samp{telnet}, @samp{rsh}, - @samp{kermit}, @samp{tip}, or @samp{mondfe} - ---outdir outdir directory for @file{@var{tool}.sum} and @file{@var{tool}.log} - ---objdir objdir directory for pre-compiled binaries - ---reboot reboot reboot the target if set to @code{"1"}; - do not reboot if set to @code{"0"} (the default) - ---srcdir srcdir directory of test subdirectories - ---strace tracelevel a number: Tcl trace depth - ---tool tool name of tool to test; identifies init, test subdir - ---verbose verbose verbosity level. As option, use multiple times; - as variable, set a number, 0 or greater ---target target_triplet The canonical configuration string for the target. ---host host_triplet The canonical configuration string for the host. ---build build_triplet The canonical configuration string for the - build host. - -@end display -@end ifinfo - -@tex -\vbox{\halign{\hfil \tt #\quad &\quad\tt #\hfil &\hbox{\vtop{{\raggedright\parindent=0pt\parskip=5pt\hsize=2.75in\rm#\strut\par}}}\hfill\cr -\cr -{\it runtest}&{\it Tcl}\cr -{\it option}&{\it variable}&{\it description}\cr -\noalign{\hrule width\hsize}\cr ---all &all\_flag &display all test results if set\cr ---baud &baud &set the default baud rate to something other - than 9600.\cr ---connect &connectmode &@samp{rlogin}, @samp{telnet}, @samp{rsh}, - @samp{kermit}, @samp{tip}, or @samp{mondfe}\cr ---mail &mailing\_list&address list for mailing test output\cr ---name &targetname &network name of testing target or its host\cr ---outdir &outdir &directory for @file{@var{tool}.sum} and @file{@var{tool}.log}\cr ---objdir &objdir &directory for compiled binaries\cr ---reboot &reboot &reboot the target if set to @code{"1"}; -do not reboot if set to @code{"0"} (the default)\cr ---srcdir &srcdir &directory of test subdirectories\cr ---strace &tracelevel &a number: Tcl trace depth\cr ---tool &tool &name of tool to test; identifies init, test subdir\cr ---verbose &verbose &verbosity level. As option, use multiple times; - as variable, set a number, 0 or greater\cr ---target &target\_triplet - &The canonical configuration string for the target.\cr ---host &host\_triplet &The canonical configuration string for the host.\cr ---build &build\_triplet &The canonical configuration string for the - build host.\cr -}} -@end tex - -@node Master Config File, Local Config File, Config Values, Customizing -@subsection Master Config File -@cindex master @file{site.exp} -@cindex @file{site.exp} for all of DejaGnu -The master config file is where all the target specific config variables -get set for a whole site get set. The idea is that for a centralized -testing lab where people have to share a target between multiple -developers. There are settings for both remote targets and remote hosts. -Here's an example of a Master Config File (also called the Global config -file) for a @emph{canadian cross}. A canadian cross is when you build -and test a cross compiler on a machine other than the one it's to be -hosted on. - -Here we have the config settings for our California office. Note that -all config values are site dependant. Here we have two sets of values -that we use for testing m68k-aout cross compilers. As both of these -target boards has a different debugging protocol, we test on both of -them in sequence. - -@cartouche -@smallexample -global CFLAGS -global CXXFLAGS - -case "$target_triplet" in @{ - @{ "native" @} @{ - set target_abbrev unix - @} - @{ "m68*-unknown-aout" @} @{ - set target_abbrev "rom68k" - # IDP target # IDP board with rom68k monitor - set target_info(idp,name) "idp" - set target_info(idp,ldflags) "-Tidp.ld" - set target_info(idp,config) m68k-unknown-aout - set target_info(idp,cflags) "" - set target_info(idp,connect) telnet - set target_info(idp,target) "s7" - set target_info(idp,serial) "tstty12" - set target_info(idp,netport) "truckin:1007" - set target_info(idp,baud) "9600" - # MVME target # Motorola MVME 135 with BUG monitor - set target_info(mvme,name) "mvme" - set target_info(mvme,ldflags) "-Tmvme.ld" - set target_info(mvme,config) m68k-unknown-aout - set target_info(mvme,cflags) "" - set target_info(mvme,connect) telnet - set target_info(mvme,target) "s4" - set target_info(mvme,serial) "tstty8" - set target_info(mvme,netport) "truckin:1004" - set target_info(mvme,baud) "9600" - @} -@} -@end smallexample -@end cartouche - - In this case, we have support for several remote hosts for -our m68k-aout cross compiler. Typically the remote Unix hosts run -DejaGnu locally, but we also use them for debugging the testsuites when -we find problems in running on remote hosts. Expect won't run on NT, so -DejaGnu is run on the local build machine, and it'll connect to the NT -host and run all the tests for this cross compiler on that host. - -@smallexample -@cartouche -case "$host_triplet" in @{ - "native" @{ - @} - "i?86-*-linux*" @{ # Linux host - set target_info(host,name) "linux-host" - set target_info(host,config) $host_triplet - set target_info(host,connect) rlogin - set target_info(host,target) chinadoll - @} - "i?86-*-winnt # NT host - set target_info(host,name) "nt-host" - set target_info(host,config) i386-unknown-winnt - set target_info(host,connect) telnet - set target_info(host,target) ripple - @} - "hppa*-hp-hpux*" @{ # HP-UX host - set target_info(host,name) "hpux-host" - set target_info(host,config) $host_triplet - set target_info(host,connect) rlogin - set target_info(host,target) slipknot - @} - "sparc-sun-sunos*" @{ # SunOS (sun4) - set target_info(host,name) "sunos-host" - set target_info(host,config) $host_triplet - set target_info(host,connect) rlogin - set target_info(host,target) darkstar - @} -@} -@end cartouche -@end smallexample - -@node Local Config File, Personal Config File, Master Config File, Customizing -@subsection Local Config File -@cindex local @file{site.exp} -@cindex @file{site.exp} for each tool -It is usually more convenient to keep these ``manual overrides'' in the -@file{site.exp} local to each test directory, rather than in the -``master'' @file{site.exp} in the DejaGnu library. - -All local @file{site.exp} usually files have two sections, separated by -comment text. The first section is the part that is generated by -@code{make}. It is essentially a collection of Tcl variable definitions -based on @file{Makefile} environment variables. Since they are generated -by @code{make}, they contain the values as specified by -@code{configure}. (You can also customize these values by using the -@samp{--site} option to @code{configure}.) In particular, this section -contains the @file{Makefile} variables for host and target configuration -data. Do not edit this first section; if you do, your changes are replaced -next time you run @code{make}. - -The first section starts with: - -@cartouche -@smallexample -## these variables are automatically generated by make ## -# Do not edit here. If you wish to override these values -# add them to the last section -@end smallexample -@end cartouche - -In the second section, you can override any default values (locally to -DejaGnu) for all the variables. The -second section can also contain your preferred defaults for all the -command line options to @code{runtest}. This allows you to easily -customize @code{runtest} for your preferences in each configured -test-suite tree, so that you need not type options repeatedly on the -command line. (The second section may also be empty, if you do not wish -to override any defaults.) - -The first section ends with this line: - -@cartouche -@smallexample -## All variables above are generated by configure. Do Not Edit ## -@end smallexample -@end cartouche - -You can make any changes under this line. If you wish to redefine a -variable in the top section, then just put a duplicate value in this -second section. Usually the values defined in this config file are -related to the configuration of the test run. This is the ideal place to -set the variables @code{host_triplet}, @code{build_triplet}, -@code{target_triplet}. All other variables are tool dependant, i.e., for -testing a compiler, the value for @var{CC} might be set to a freshly -built binary, as opposed to one in the user's path. - -@node Personal Config File, , Local Config File, Customizing -@subsection Personal Config File -@cindex personal config @file{site.exp} -@cindex @file{site.exp} for each person -The personal config file is used to customize @code{runtest's} behaviour -for each person. It's typically used to set the user prefered setting -for verbosity, and any experimental Tcl procedures. My personal -@file{~/.dejagnurc} file looks like: - -@cartouche -@smallexample -set all_flag 1 -set RLOGIN /usr/ucb/rlogin -set RSH /usr/ucb/rsh -@end smallexample -@end cartouche - -Here I set @code{all_flag} so I see all the test cases that PASS along -with the ones that FAIL. I also set @var{RLOGIN} and @code{RSH} to the -BSD version. I have @code{kerberos} installed, and when I rlogin to a -target board, it usually isn't supported. So I use the non secure -versions of these programs rather than the default that's in my path. +@node Windows, Getting the source code for the calc example, , Test your installation +@subsection Windows -@node Internals -@chapter The DejaGnu Implementation -@cindex operating principles -@cindex internal details +On Windows systems DejaGnu is part of a port of a lot of Unix +tools to the Windows OS, called Cygwin. Cygwin may be downloaded and +installed from a mirror of http://www.cygwin.com/. All examples were +also run on Windows NT. If nothing is said, you can assume that you +should get the same output as on a Unix system. -DejaGnu is entirely written in @code{expect}, which uses Tcl as a -command language. @code{expect} serves as a very programmable shell; -you can run any program, as with the usual Unix command shells---but -once the program is started, your @code{expect} script has fully -programmable control of its input and output. This does not just apply -to the programs under test; @code{expect} can also run any auxiliary -program, such as @code{diff} or @code{sh}, with full control over its -input and output. +You will need a telnet daemon if you want to use a Windows box +as a remote target. There seems to be a freeware telnet daemon at +http://www.fictional.net/. -DejaGnu itself is merely a framework for the set of test suites -distributed separately for each @sc{gnu} tool. Future releases of -@sc{gnu} tools will include even more tests, developed throughout the -free software community. +@node Getting the source code for the calc example, , Windows, Test your installation +@subsection Getting the source code for the calc example -@kindex runtest.exp -@code{runtest} is the glue to tie together and manage the test scripts. -The @code{runtest} program is actually a simple Bourne shell script that -locates a copy of the @code{expect} shell and then starts the main Tcl -code, @code{runtest.exp}. @code{runtest.exp} itself has these essential -functions: - -@enumerate -@item -Parse the command line options, load the library files, and load the -default configuration files. - -@item -Locating the individual test scripts. @code{runtest.exp} locates the tests -by exploiting a straightforward naming convention based on the string -you specify with the @samp{--tool} option. +If you are running a Debian distribution you can find the +examples under /usr/share/doc/dejagnu/examples. These examples seem to +be missing in Red Hat's RPM. In this case download the sources of +DejaGnu and adjust the pathes to the DejaGnu examples +accordingly. -@item -Providing an extended test environment, by defining additional Tcl -procedures beyond those already in @code{expect}. +@node Create a minimal project; e_g_ calc, Our first automated tests, Test your installation, Getting DejaGnu up and running +@section Create a minimal project, e.g. calc -@item -Locating target-dependent functions, to standardize the test environment -across a wide variety of test platforms. -@end enumerate +In this section you will to start a small project, +using the sample application calc, which is part of your DejaGnu +distribution @menu -* Names:: Conventions for using tool names -* Init Module:: Initialization module -* DejaGnu Builtins:: DejaGnu provides these Tcl procedures -* Target Dependent:: Procedures supplied by the init module -* Cross Targets:: Remote targets supported -* Input Files:: The files DejaGnu depends on -* Output Files:: The files DejaGnu produces +* A simple project without the GNU autotools:: +* Using autoconf/autoheader/automake:: @end menu -@node Names -@section Conventions for using tool names - -@cindex @code{--tool} and naming conventions -@cindex tool names and naming conventions -@cindex naming conventions -DejaGnu uses @samp{$tool}, the name of the tool under test, to tie -together the testing configuration in a straightforward but flexible -way. If there is only one testsuite for a particular application, then -@samp{$tool} is optional. - -@samp{$tool} is @emph{not} used to invoke the tool, since sites that run -multiple configurations of a particular tool often call each -configuration by a different name. @code{runtest} uses the -configuration-dependent variables captured in @file{site.exp} to -determine how to call each tool. - -@cindex directory names and @code{--tool} -@cindex test directories, naming -@code{runtest} uses tool names to find directories containing tests. -@code{runtest} scans the source directory (specified with -@code{--srcdir}) for all directories whose names start with the tool -name. It is a common practice to put a period after the tool part of the -name. For instance, directories that start with -@samp{g++.} contain @sc{g++} tests. To add a new test, just put it in -any directory (create an entirely new directory, if you wish) whose name -follows this convention. - -@cindex @code{exp} filename suffix -@cindex test filename -@cindex filename for test files -A test is any file in an appropriately named subdirectory whose name -ends in @samp{.exp} (the conventional way of naming @code{expect} -scripts). These simple naming conventions make it as simple as possible -to install new tests: all you must do is put the test in the right -directory. +@node A simple project without the GNU autotools, Using autoconf/autoheader/automake, , Create a minimal project; e_g_ calc +@subsection A simple project without the GNU autotools -@cindex order of tests -@cindex tests, running order -@code{runtest} sorts the tests in each subdirectory by name (using the -Tcl @code{lsort} command) and runs them in the resulting order. - -@node Init Module -@section Initialization module -@cindex tool initialization -@cindex setting up targets - -@c FIXME! should this node be merged with "Target dependent"? - -@cindex init file, purpose -@cindex starting interactive tools -@cindex initialization -The initialization module (or ``init file'') has two purposes: to -provide tool and target dependent procedures, and to start up an -interactive tool to the point where it is ready to operate. The latter -includes establishing communications with the target. All the tests for -interactive programs assume that the tool is already running and -communicating. Initialization modules for non-interactive programs may -only need to supply the support functions. - -@cindex init file name -@cindex name, initialization module -Each test suite directory must contain (in its @file{config} -subdirectory) a separate initialization module for each target. The -appropriate init file is can be named several ways. The prefered name is -the @emph{os} part of the canonical configuration name with @code{.exp} -as the suffix. An example would be that for an @code{m68k-coff} system, -the @code{target_os} part would be @code{coff}. The next way is for -system where there are short filenames, or a shortcut is desired to -refer to the OS name for that target. This is uses the value of -@code{$target_abbrev} rather than the @code{target_os}. - -The final file looked for is simply @file{default.exp}. If there is only -one operating system to support, then this file can be used. It's main -purpose is to offer some support for new operating systems, or for -unsupported cross targets. The last file looked for is -@file{unknown.exp}. This is usually limited to error handling for -unsupported targets. It's whole contents is typically. - -@cartouche -@smallexample -perror "Sorry, there is no support for this target" -exit 1 -@end smallexample -@end cartouche - -At the beginning of the init file, you must first determine the proper -executable name of the tool to execute, since the actual name of the -tool to be tested my vary from system to system. Here's an example -for the @sc{gnu} C compiler. - -@cartouche -@smallexample -global AR -# look for the archiver ar -if ![info exists AR] @{ - set AR [findfile $base_dir/../../binutils/ar $base_dir/../../binutils/ar [tr -ansform ar]] - verbose "AR defaulting to $AR" 2 -@} -@} +The runtest program can be run standalone. All the +autoconf/automake support is just cause those programs are commonly +used for other GNU applications. The key to running runtest standalone +is having the local site.exp file setup correctly, which automake +does. -global CFLAGS -if ![info exists CFLAGS] then @{ - set CFLAGS "" -@} -@end smallexample -@end cartouche - -It is always a good idea to first check the variable, and only set it if -it has not yet been defined. Often the proper value of @code{AR} is set -on the command line that invokes @file{runtest}. - -@kindex findfile -The @code{findfile} procedure takes as it's first argument a file name -to look for. The second argument is returned if the file is found, and -the third argument is returned if the file is not found. @code{base_dir} -is set internally by DejaGnu to the top level directory of the object -tree. - -@kindex transform -The @code{transform} procedure takes as its argument the native name of -a tool (such as @samp{gcc} for the compiler), and returns the name as -configured for that tool in the current installation. (For example, a -cross-compiling version of @sc{gnu} CC that generates MIPS code may be -installed with a name like @code{mips-idt-ecoff-gcc}.) - -In a test running native, writing the Tcl code for initialization is -usually quite simple. For cross configurations, however, more elaborate -instructions are usually needed to describe how to talk to a remote -target. +The generated site.exp should like like: -Each initialization module defines up to four procedures with standard -names and purposes. The names of these procedures begin with -@samp{$tool}, the string that identifies tests for a particular tool: -@code{$tool_start}, @code{$tool_load}, @code{$tool_exit}, and -@code{$tool_version}. For example, the start procedure for @sc{gdb} is -called @code{gdb_start}. (Since start procedures are used differently -for batch and interactive tools, however, @code{runtest} itself never -calls the start procedure. Init files for interactive tools are -expected to end by running the start procedure.) - -@cindex utilities, loading from init file -@cindex defaults, setting in init file -The initialization module is also a good place to call @code{load_lib} -to get any collections of utility procedures meant for a family of test -cases, and to set up default values for any additional Tcl variables -needed for a specific set of tests. - -@xref{Target Dependent,,Target dependent procedures}, for full -descriptions of these procedures. - -@node DejaGnu Builtins -@section DejaGnu procedures -@cindex built in procedures, DejaGnu - -DejaGnu provides these Tcl procedures for use in test scripts. -You can also use any standard @code{expect} or Tcl function. These -procedures are stored in libraries, which DejaGnu loads at -runtime. Here's explanation of the library procedures that get loaded at -runtime. All other librarys are optional, and need to be loaded by the -testsuite. +@example -@menu -* framework.exp:: Core Internal Procedures. -* remote.exp:: Procedures for remote communication. -* utils.exp:: Utility procedures. -* target.exp:: Cross target procedures. -* debugger.exp:: Procedures for debugging your Tcl code. -@end menu +set tool calc +set srcdir . +set objdir /home/dgt/dejagnu.test +@end example -@node framework.exp, remote.exp, ,DejaGnu Builtins -@subsection Core Internal Procedures -@cindex Core Internal Procedures - -@xref{Posix,,A POSIX conforming test framework}, for more detailed -explanations of the test outcomes (@samp{FAIL}, @samp{PASS}, -@samp{UNTESTED}, @samp{UNRESOLVED}, @samp{UNSUPPORTED}). - -@ftable @code -@item perror "@var{string} @var{number}" -@cindex test case, ERROR in -@kindex ERROR -Declares a severe error in the testing framework itself. -@code{perror} writes in the log files a message beginning with -@samp{ERROR}, appending the argument @var{string}. If the optional -@var{number} is supplied, then this is used to set the internal count of -errors to that value. - -As a side effect, @code{perror} also changes the effect of the next -@code{pass} or @code{fail} command: the test outcome becomes -@samp{UNRESOLVED}, since an automatic @samp{PASS} or @samp{FAIL} cannot -be trusted after a severe error in the test framework. If the optional -numeric value is @samp{0}, then there are no further side effects to -calling this function, and the following test outcome doesn't become -@samp{UNRESOLVED}. This can be used for errors with no known side -effects. - -@item warning "@var{string} @var{number}" -@cindex test case, WARNING in -@kindex WARNING -Declares detection of a minor error in the test case itself. -@code{warning} writes in the log files a message beginning with -@samp{WARNING}, appending the argument @var{string}. Use @code{warning} -rather than @code{error} for cases (such as communication failure -to be followed by a retry) where the test case can recover from the -error. If the optional @var{number} is supplied, then this is used to -set the internal count of warnings to that value. - -As a side effect, @code{warning_threshold} or more calls to -@code{warning} in a single test case also changes the effect of the next -@code{pass} or @code{fail} command: the test outcome becomes -@samp{UNRESOLVED} since an automatic @samp{PASS} or @samp{FAIL} may not -be trustworthy after many warnings. If the optional numeric value is -@samp{0}, then there are no further side effects to calling this -function, and the following test outcome doesn't become -@samp{UNRESOLVED}. This can be used for errors with no known side -effects. - -@item note "@var{string}" -@cindex test case, informational messages -@kindex NOTE -Appends an informational message to the log file. -@code{note} writes in the log files a message beginning with -@samp{NOTE}, appending the argument @var{string}. Use @code{note} -sparingly. @code{verbose} should be used for most such messages, -but in cases where a message is needed in the log file regardless of -the verbosity level use @code{note}. - -@item pass "@var{string}" -@cindex test case, declaring success -Declares a test to have passed. @code{pass} writes in the -log files a message beginning with @samp{PASS} -(or @code{XPASS}/@code{KPASS}, if failure was expected), -appending the argument @var{string}. - -@item fail "@var{string}" -@cindex test case, declaring failure -Declares a test to have failed. @code{fail} writes in the -log files a message beginning with @samp{FAIL} (or @code{XFAIL}, if -failure was expected), appending the argument @var{string}. - -@item unresolved "@var{string}" -@cindex test case, declaring ambiguity -Declares a test to have an unresolved outcome. @code{unresolved} writes -in the log file a message beginning with @samp{UNRESOLVED}, appending -the argument @var{string}. This usually means the test did not execute -as expected, and a human being must go over results to determine if it -passed or failed (and to improve the test case). - -@item untested "@var{string}" -@cindex test case, declaring no test -Declares a test was not run. @code{untested} writes in the log file a -message beginning with @samp{UNTESTED}, appending the argument -@var{string}. For example, you might use this in a dummy test whose -only role is to record that a test does not yet exist for some feature. - -@item unsupported "@var{string}" -@cindex test case, declaring no support -Declares that a test case depends on some facility that does not exist -in the testing environment. @code{unsupported} writes in the log file a -message beginning with @samp{UNSUPPORTED}, appending the argument -@var{string}. - -@item get_warning_threshold -@cindex test case, WARNING threshold -Returns the current value of @code{warning_threshold}. -The default value is 3. - -@item set_warning_threshold @var{threshold} -@cindex test case, WARNING threshold -Sets the value of @code{warning_threshold}. -A value of @code{0} disables it: calls to @code{warning} will not turn -a @samp{PASS} or @samp{FAIL} into an @samp{UNRESOLVED}. - -@item transform "@var{toolname}" -@cindex transform tool name -@cindex installed tool name -@cindex tool name, as installed -@cindex name transformations -Generates a string for the name of a tool as it was configured and -installed, given its native name (as the argument @var{toolname}). -This makes the assumption that all tools are installed using the same -naming conventions: it extrapolates from the invocation name for -@file{runtest}. For example, if you call @code{runtest} as -@file{m68k-vxworks-runtest}, the result of @w{@samp{ transform "gcc" }} -is @samp{m68k-vxworks-gcc}. - -@item ishost "@var{host}" -@cindex host configuration test -Tests for a particular @emph{host} environment. If the currently -configured host matches the argument string, the result is @code{1}; -otherwise the result is @code{0}. @var{host} must be a full three-part -@code{configure} host name; in particular, you may not use the shorter -nicknames supported by @code{configure} (but you can use wildcard -characters, using shell syntax, to specify sets of names). +@node Using autoconf/autoheader/automake, , A simple project without the GNU autotools, Create a minimal project; e_g_ calc +@subsection Using autoconf/autoheader/automake -@item istarget "@var{target}" -@cindex target configuration test -Tests for a particular @emph{target} environment. If the currently -configured target matches the argument string, the result is @code{1}; -otherwise the result is @code{0}. @var{target} must be a full -three-part @code{configure} target name; in particular, you may not use -the shorter nicknames supported by @code{configure} (but you can use -wildcard characters, using shell syntax, to specify sets of names). If it is -passed a @code{NULL} string, then it returns the name of the build -canonical configuration. - -@item isbuild "@var{host}" -@cindex build host configuration test -Tests for a particular @emph{build host} environment. If the currently -configured host matches the argument string, the result is @code{1}; -otherwise the result is @code{0}. @var{host} must be a full three-part -@code{configure} host name; in particular, you may not use the shorter -nicknames supported by @code{configure} (but you can use wildcard -characters, using shell syntax, to specify sets of names). If it is -passed a @code{NULL} string, then it returns the name of the build -canonical configuration. - -item is3way "@var{host}" -@cindex canadian cross configuration test -Tests for a canadian cross. This is when the tests will be run on a -remotly hosted cross compiler. If it is a canadian cross, then the -result is @code{1}; otherwise the result is @code{0}. - -@item isnative -@cindex native configuration test -Tests whether the current configuration has the same host and target. -When it runs in a @emph{native} configuration this procedure returns a -@code{1}; otherwise it returns a @code{0}. - -@item load_lib "@var{library-file}" -@cindex load library file -Loads the file @var{library-file} by searching a fixed path built into -@code{runtest}. If DejaGnu has been installed, it looks in a path -starting with the installed library directory. If you are running -DejaGnu directly from a source directory, without first running -@samp{make install}, this path defaults to the current directory. In -either case, it then looks in the current directory for a directory -called @code{lib}. If there are duplicate definitions, the last one -loaded takes precedence over the earlier ones. - -@item setup_xfail "@var{config} @r{[}@var{bugid}@r{]}" -@c two spaces above to make it absolutely clear there's whitespace---a -@c crude sort of italic correction! -@cindex test case, expecting failure -@cindex failure, expected -@cindex expected failure -Declares that the test is expected to fail on a particular set of -configurations. The @var{config} argument must be a list of full -three-part @code{configure} target name; in particular, you may not use -the shorter nicknames supported by @code{configure} (but you can use the -common shell wildcard characters to specify sets of names). The -@var{bugid} argument is optional, and used only in the logging file -output; use it as a link to a bug-tracking system such as @sc{gnats} -(@pxref{Overview,, Overview, gnats.info, Tracking Bugs With GNATS}). - -See notes under setup_kfail (below). - -@item setup_kfail "@var{config} @r{[}@var{bugid}@r{]}" -@c two spaces above to make it absolutely clear there's whitespace---a -@c crude sort of italic correction! -@cindex test case, known failure -@cindex failure, known -@cindex known failure -Declares that the test is known to fail on a particular set of -configurations. The @var{config} argument must be a list of full -three-part @code{configure} target name; in particular, you may not use -the shorter nicknames supported by @code{configure} (but you can use the -common shell wildcard characters to specify sets of names). The -@var{bugid} argument is mandatory, and used only in the logging file -output; use it as a link to a bug-tracking system such as @sc{gnats} -(@pxref{Overview,, Overview, gnats.info, Tracking Bugs With GNATS}). - -@cindex @code{XFAIL}, producing -@cindex @code{KFAIL}, producing -@cindex @code{XPASS}, producing -@cindex @code{KPASS}, producing -Once you use @code{setup_xfail} or @code{setup_kfail}, the @code{fail} -and @code{pass} procedures produce the messages @samp{XFAIL} or @samp{KFAIL} -and @samp{XPASS} or @samp{KPASS} respectively, allowing you to distinguish -expected/known failures (and unexpected success!) from other test outcomes. - -If a test is marked as both expected to fail and known to fail for a -certain configuration, a @samp{KFAIL} message will be generated. -As @samp{KFAIL} messages are expected to draw more attention than -the @samp{XFAIL} ones this will hopefuly ensure the test result is not -overlooked. - -@emph{Warning:} you must clear the expected/known failure after using -@code{setup_xfail} or @code{setup_kfail} in a test case. Any call to -@code{pass} or @code{fail} clears the expectedknown failure implicitly; -if the test has some other outcome, e.g. an error, you can call -@code{clear_xfail} to clear the expected failure or @code{clear_kfail} -to clear the known failure explicitly. Otherwise, the expected-failure -declaration applies to whatever test runs next, leading to surprising -results. +We have to prepare some input file in order to run autocon and +automake. There is book "GNU autoconf, automake and +libtool" by Garry V. Vaughan, et al. NewRider, ISBN +1-57870-190-2 which describes this process thoroughly. -@item check_conditional_xfail @var{message} @var{targets} @var{includes} @var{excludes} -@cindex test case, expecting a conditional failure -@cindex failure, conditional expected -@cindex conditional expected failure - -This procedure adds a conditional xfail, based on compiler options used to -create a test case executable. If an include options is found in the -compiler flags, and it's the right architecture, it'll trigger an -XFAIL. Otherwise it'll produce an ordinary FAIL. You can also specify -flags to exclude. This makes a result be a FAIL, even if the included -options are found. To set the conditional, set the variable -@var{compiler_conditional_xfail_data} to the fields "[message string] [targets -list] [includes list] [excludes list]" (descriptions below). This is the -checked at pass/fail decision time, so there is no need to call the -procedure yourself, unless you wish to know if it gets triggered. After -a pass/fail, the variable is reset, so it doesn't effect other tests. - -The parameters are: - -@table @code -@item message -is the message to print with the normal test result - -@item targets -is a string with the targets to activate this conditional on. - -@item includes -is a list of sets of options to search for in the compiler options to -activate this conditional. If the list of sets of options is empty or -if any set of the options matches, then this conditional is true. -(It may be useful to specify an empty list of include sets if the -conditional is always true unless one of the exclude sets matches.) - -@item excludes -is a list of sets of options to search for in the compiler options to -activate this conditional. If any set of the options matches, -(regardless of whether any of the include sets match) then this -conditional is de-activated. -@end table - -returns: - -@table @code -@item 1 -if the conditional is true -@item 0 -if the conditional is false -@end table - -An example of setting the variable would be: - -@cartouche -@smallexample -set compiler_conditional_xfail_data @{@ \ - "I sure wish I knew why this was hosed" \ - "sparc*-sun*-* *-pc-*-*" \ - @{@"-Wall -v" "-O3"@}@ \ - @{@"-O1" "-Map" @}@ \ - @}@ -@end smallexample -@end cartouche - - What this does is it matches only for these two targets if "-Wall -v" or -"-O3" is set, but neither "-O1" or "-Map" is set. - - For a set to match, the options specified are searched for independantly of -each other, so a "-Wall -v" matches either "-Wall -v" or "-v -Wall". A space -seperates the options in the string. Glob-style regular expressions are also -permitted. - -@item clear_xfail @var{config} -@cindex cancelling expected failure -@cindex expected failure, cancelling -Cancel an expected failure (previously declared with @code{setup_xfail}) -for a particular set of configurations. The @var{config} argument is a -list of configuration target names. It is only necessary to call -@code{clear_xfail} if a test case ends without calling either -@code{pass} or @code{fail}, after calling @code{setup_xfail}. - -@item clear_kfail @var{config} -@cindex cancelling known failure -@cindex known failure, cancelling -Cancel a known failure (previously declared with @code{setup_kfail}) -for a particular set of configurations. The @var{config} argument is a -list of configuration target names. It is only necessary to call -@code{clear_kfail} if a test case ends without calling either -@code{pass} or @code{fail}, after calling @code{setup_kfail}. - -@item clear_kfail @var{config} -@cindex cancelling known failure -@cindex known failure, cancelling -Cancel a known failure (previously declared with @code{setup_kfail}) -for a particular set of configurations. The @var{config} argument is a -list of configuration target names. It is only necessary to call -@code{clear_kfail} if a test case ends without calling either -@code{pass} or @code{fail}, after calling @code{setup_kfail}. - -@item verbose @r{[}-log@r{]} @r{[}-n@r{]} @r{[}--@r{]} @r{[}--@r{]} "@var{string}" @var{number} -@cindex @code{verbose} builtin function -Test cases can use this function to issue helpful messages depending on -the number of @samp{--verbose} options on the @code{runtest} command -line. It prints @var{string} if the value of the variable -@code{verbose} is higher than or equal to the optional @var{number}. The -default value for @var{number} is 1. Use the optional @samp{-log} argument -to cause @var{string} to always be added to the log file, even if it won't -be printed. Use the optional @samp{-n} argument to print @var{string} -without a trailing newline. Use the optional @samp{--} argument if -@var{string} begins with "-". To log test results to a XML file use the -@samp{-x} argument. - -@end ftable +From the calc example distributed with the DejaGnu documentation +you should copy the program file itself (calc.c) and some additional +files, which you might examine a little bit close to derive their +meanings. -@noindent -@node remote.exp, utils.exp, framework.exp, DejaGnu Builtins -@subsection Remote Communication Procedures - -@kindex remote.exp -@kindex lib/remote.exp -@cindex remote connection procedures -@cindex communications procedures -@file{lib/remote.exp} defines these functions, for establishing and -managing communications: - -@emph{Procedures to establish a connection:} Each of these procedures -tries to establish the connection up to three times before returning. -Warnings (if retries will continue) or errors (if the attempt is -abandoned) report on communication failures. The result for any of -these procedures is either @code{-1}, when the connection cannot be -established, or the spawn ID returned by the @code{expect} command -@code{spawn}. +@example -It use the value of the @code{connect} field in the @code{target_info} -array (was @code{connectmode} as the type of connection to make. Current -supported connection types are tip, kermit, telnet, rsh, rlogin, and -netdata. If the @code{--reboot} option was used on the runtest command -line, then the target is rebooted before the connection is made. - -@ftable @code - -@item remote_open @var{type} -@cindex Opening a remote connection -@emph{Remote Connection Procedure.} This is passed @emph{host} or -@emph{target}. Host or target refers to whether it is a connection to a -remote target, or a remote host. This opens the connection to the -desired target or host using the default values in the configuration -system. It returns that @code{spawn_id} of the process that manages the -connection. This value can be used in @code{expect} or @code{exp_send} -statements, or passed to other procedures that need the connection -process's id. This also sets the @code{fileid} field in the -@code{target_info} array. - - -@item remote_close @var{shellid} -@cindex Closing a remote connection -@emph{shellid} is value returned by a call to @code{remote_open}. This -closes the connection to the target so resources can be used by -others. This parameter can be left off if the @code{fileid} field in the -@code{target_info} array is set. +dgt:~/dejagnu.test$ cp -r /usr/share/doc/dejagnu/examples/calc/\ +@{configure.in,Makefile.am,calc.c,testsuite@} . +@end example -@item telnet @var{hostname} @var{port} -@itemx rlogin @var{hostname} -@itemx rsh @var{hostname} -@cindex IP network procedures -@cindex network (IP) procedures -@emph{IP network procedures.} @var{hostname} refers to the IP address or -name (for example, an entry in @file{/etc/hosts}) for this target. The -procedure names reflect the Unix utility used to establish a -connection. The optional @var{port} is used to specify the IP port -number. The value of the @code{netport} field in the @code{target_info} -array is used. (was @code{$netport}) This value has two parts, the -hostname and the port number, seperated by a @emph{:}. If @code{host} or -@code{target} is used in the @code{hostname} field, than the config -array is used for all information. - -@item tip @var{port} -@cindex serial line connection, @code{tip} -@emph{Serial line procedure.} Connect using the Unix utility @code{tip}. -@var{port} must be a name from the @code{tip} configuration file -@file{/etc/remote}. Often, this is called @samp{hardwire}, or something -like @samp{ttya}. This file holds all the configuration data for -the serial port. The value of the @code{serial} field in the -@code{target_info} array is used. (was @code{$serialport}) If -@code{host} or @code{target} is used in the @code{port} field, than -the config array is used for all information. - -@item kermit @var{port} @var{bps} -@cindex serial line connection, @code{kermit} -@emph{Serial line procedure.} Connect using the program @code{kermit}. -@var{port} is the device name, e.g. @file{/dev/ttyb}. @var{bps} is -the line speed to use (in bits per second) for the connection. The value -of the @code{serial} field in the @code{target_info} array is used. (was -@code{$serialport}) If @code{host} or @code{target} is used in the -@code{port} field, than the config array is used for all information. - -@end ftable +In Makemake.am note the presence of the AUTOMAKE_OPTIONS = dejagnu. This option is needed. -@noindent -@emph{Procedures to manage a connection:} - -@ftable @code -@item tip_download @var{spawnid} @var{file} -@cindex download, @code{tip} -@cindex serial download, @code{tip} -Download @file{@var{file}} to the process @var{spawnid} (the value -returned when the connection was established), using the @code{~put} -command under @code{tip}. Most often used for single board computers -that require downloading programs in @sc{ascii} S-records. Returns -@code{1} if an error occurs, @code{0} otherwise. - -@item exit_remote_shell @var{spawnid} -@cindex terminating remote connection -@cindex remote connection, ending -Exits a remote process started by any of the connection procedures. -@var{spawnid} is the result of the connection procedure that started the -remote process. - -@item download @var{file} @r{[} @var{spawnid} @r{]} -@cindex download a file -After you establish a connection to a target, you can download programs -using this command. @code{download} reads in @var{file} (object code in -S-record format) and writes it to the device controlling this -@var{spawnid}. (From the point of view of the target, the S-record file -comes in via standard input.) - -If you have more than one target active, you can use the optional argument -@var{spawnid} to specify an alternative target (the default is the most -recently established @var{spawnid}.) -@end ftable +Run aclocal to generate aclocal.m4, which is a collection of +macros needed by configure.in -@noindent -@node utils.exp, target.exp, remote.exp, DejaGnu Builtins -@subsection Utility Procedures +@example -@kindex utils.exp -@kindex lib/utils.exp -@file{lib/utils.exp} defines these utility procedures: - -@ftable @code -@item getdirs @var{dir} -@itemx getdirs @var{dir} @var{pattern} -@cindex directories matching a pattern -@cindex pattern match, directory -Returns a list of all the directories in the single directory @var{dir} -that match @var{pattern}. If you do not specify @var{pattern}, -@code{getdirs} assumes @samp{*}. You may use the common shell wildcard -characters in @var{pattern}. If no directories match the pattern, then a -@code{NULL} string is returned. - -@item find @var{dir} @var{pattern} -@cindex files matching a pattern -@cindex pattern match, filenames -Search for files whose names match @var{pattern} (using shell wildcard -characters for filename expansion). Search subdirectories recursively, -starting at @var{dir}. The result is the list of files whose names -match; if no files match, the result is empty. Filenames in the result -include all intervening subdirectory names. If no files match the -pattern, then a @code{NULL} string is returned. - -@item which @var{binary} -@cindex path lookup -Searches the execution path for an executable file @var{binary}, like -the the BSD @code{which} utility. This procedure uses the shell -environment variable @samp{PATH}. It returns @code{0} if the binary is -not in the path, or if there is no @samp{PATH} environment variable. If -@var{binary} is in the path, it returns the full path to @var{binary}. - -@item grep @var{filename} @var{regexp} -@item grep @var{filename} @var{regexp} line -@cindex regular expression, file contents -@cindex searching file contents -Search the file called @var{filename} (a fully specified path) for lines -that contain a match for regular expression @var{regexp}. The result is -a list of all the lines that match. If no lines match, the result is an -empty string. Specify @var{regexp} using the standard regular -expression style used by the Unix utility program @code{grep}. - -Use the optional third argument @samp{line} to start lines in the result -with the line number in @var{filename}. (This argument is simply an -option flag; type it just as shown---@samp{line}.) - -@item diff @var{filename} @var{filename} -@cindex finding file differences -@cindex comparing files -Compares the two files and returns a 1 if they match, or a 0 if they -don't. If @code{verbose} is set, then it'll print the differences to the -screen. - -@item slay @var{name} -@cindex slaying processes -This look in the process table for @var{name} and send it a unix -@code{SIGINT}, killing the process. - -@item absolute @var{path} -@cindex converting relative paths to absolute -This procedure takes the relative @var{path}, and converts it to an -absolute path. - -@item psource @var{filename} -@cindex sourcing Tcl files -This sources the file @var{filename}, and traps all errors. It also -ignores all extraneous output. If there was an error it returns a 1, -otherwise it returns a 0. - -@item prune @var{list} @var{pattern} -@cindex list, pruning -Remove elements of the Tcl list @var{list}. Elements are fields -delimited by spaces. The result is a copy of @var{list}, without any -elements that match @var{pattern}. You can use the common shell -wildcard characters to specify @var{pattern}. - -@item setenv @var{var} @var{val} -@cindex setting environment variables -Sets the variable @var{var} to the value @var{val}. - -@item unsetenv @var{var} -@cindex unsetting environment variables -Unsets the environment variable @var{var} - -@item getenv @var{var} -@cindex getting environment variables -returns the value of @var{var} in the environment if it exists, -otherwise it returns @code{NULL}. - -@item runtest_file_p @var{runtests} @var{testcase} -@cindex selecting a range of tests -@cindex tests, running specifically -Search @var{runtests} for @var{testcase} and return 1 if found, 0 if not. -@var{runtests} is a list of two elements. The first is a copy of what was -on the right side of the @code{=} if @samp{foo.exp="@dots{}"} was specified, -or an empty string if no such argument is present. The second is the -pathname of the current testcase under consideration. -This is used by tools like compilers where each testcase is a file. - -@item prune_system_crud @var{system} @var{text} -@cindex pruning system output, examining program output -For system @var{system}, delete text the host or target operating system might -issue that will interfere with pattern matching of program output in -@var{text}. An example is the message that is printed if a shared library -is out of date. - -@end ftable +dgt:~/dejagnu.test$ aclocal +@end example -@noindent -@node target.exp, debugger.exp, utils.exp, DejaGnu Builtins -@subsection Cross target procedure +autoconf is another part of the auto-tools. Run it to generate +configure based on information contained in configure.in. -@kindex target.exp -@kindex lib/target.exp -@file{lib/target.exp} defines these utility procedures: +@example -@ftable @code +dgt:~/dejagnu.test$ autoconf +@end example -@item push_target @emph{name} -@cindex set current target -This makes the target named @emph{name} be the current target -connection. The value of @emph{name} is an index into the -@code{target_info} array and is set in the global config file. +autoheader is another part of the auto-tools. +Run it to generate calc.h.in. -@item pop_target -@cindex unset current target -This unsets the current target connection. +@example -@item list_targets -@cindex lists supported targets -This lists all the supported targets for this architecture. +dgt:~/dejagnu.test$ autoheader +@end example -@item push_host @emph{name} -@cindex set current host -This makes the host named @emph{name} be the current remote host -connection. The value of @emph{name} is an index into the -@code{target_info} array and is set in the global config file. +The Makefile.am of this example was developed as port of the DejaGnu +distribution. +Adapt Makefile.am for this test. Replace the line +"#noinst_PROGRAMS = calc" to +"bin_PROGRAMS = calc". +Change the RUNTESTDEFAULTFLAGS from +"$$srcdir/testsuite" to +"./testsuite". -@item pop_host -@cindex unset current host -This unsets the current host connection. +Running automake at this point contains a series of warning in +its output as shown in the following example: -@c @item compile @emph{file} -@cindex compile a file -This invokes the compiler as set by @code{CC} to compile the file -@emph{file}. The default options for many cross compilation targets are -@emph{guessed} by DejaGnu, and these options can be added to by passing -in more parameters as arguments to @code{compile}. Optionally, this will -also use the value of the @code{cflags} field in the target config -array. If the host is not the same as the build machines, then then -compiler is run on the remote host using @code{execute_anywhere}. - -@c @item archive @emph{file} -@cindex archive object files -This produces an archive file. Any parameters passed to @code{archive} -are used in addition to the default flags. Optionally, this will -also use the value of the @code{arflags} field in the target config -array. If the host is not the same as the build machines, then then -archiver is run on the remote host using @code{execute_anywhere}. - -@c @item ranlib @emph{file} -@cindex ranlib a file -This generates an index for the archive file for systems that aren't -POSIX yet. Any parameters passed to @code{ranlib} are used in for the -flags. - -@item execute_anywhere @emph{cmdline} -@cindex executing commands remotely -This executes the @emph{cmdline} on the proper host. This should be used -as a replacement for the Tcl command @code{exec} as this version -utilizes the target config info to execute this command on the build -machine or a remote host. All config information for the remote host -must be setup to have this command work. If this is a canadian cross, -(where we test a cross compiler that runs on a different host then where -DejaGnu is running) then a connection is made to the remote host and -the command is executed there. It returns either @emph{REMOTERROR} (for -an error) or the output produced when the command was executed. This is -used for running the tool to be tested, not a test case. - -@end ftable - -@node debugger.exp, , target.exp, DejaGnu Builtins -@subsection Debugging Procedures - -@kindex debugger.exp -@kindex lib/debugger.exp -@file{lib/debugger.exp} defines these utility procedures: - -@ftable @code - -@item dumpvars @emph{expr} -@cindex Print global variable values -This takes a csh style regular expression (glob rules) and prints the -values of the global variable names that match. It is abbreviated as -@code{dv} - -@item dumplocals @emph{expr} -@cindex Print local variable value -This takes a csh style regular expression (glob rules) and prints the -values of the local variable names that match. It is abbreviated as -@code{dl}. - -@item dumprocs @emph{expr} -@cindex Print procedure bodies -This takes a csh style regular expression (glob rules) and prints the -body of all procs that match. It is abbreviated as @code{dp} - -@item dumpwatch @emph{expr} -@cindex Print watchpoints -This takes a csh style regular expression (glob rules) and prints all -the watchpoints. It is abbreviated as @code{dw}. - -@c FIXME: finish these when the code is fixed. -@c @item watcharray @emph{element} @emph{type} -@c @cindex Set a watchpoint on an array -@c This sets an watchpoint of the @emph{element-type} on the -@c @item watchvar v null type -@c @cindex Set a watchpoint on a variable - -@item watchunset @emph{var} -@cindex Watch when a variable is unset -This breaks program execution when the variable @emph{var} is unset. It -is abbreviated as @code{wu}. - -@item watchwrite @emph{var} -@cindex Watch when a variable is written -This breaks program execution when the variable @emph{var} is -written. It is abbreviated as @code{ww}. - -@item watchread @emph{var} -@cindex Watch when a variable is read -This breaks program execution when the variable @emph{var} is read. It -is abbreviated as @code{wr}. - -@item watchdel @emph{watch} -@cindex Delete a watchpoint. -This deletes a the watchpoint for @emph{watch}. It is abbreviated as -@code{wd}. - -@item print @emph{var} -@cindex Printing variable values -This prints the value of the variable @emph{var}. It is abbreviated as -@code{p}. - -@item quit -@cindex Quiting DejaGnu -This makes runtest exit. It is abbreviated as @code{q}. - -@item bt -@cindex Print a backtrace -This prints a backtrace of the executed Tcl commands. - -@end ftable - -@node Target Dependent -@section Target dependent procedures -@cindex target dependent procedures - -@c FIXME? These may be renamed to just "start", "load", "exit", and -@c "version" eventually. - -Each combination of target and tool requires some target-dependent -procedures. The names of these procedures have a common form: the tool -name, followed by an underbar @samp{_}, and finally a suffix describing -the procedure's purpose. For example, a procedure to extract the -version from @sc{gdb} is called @samp{gdb_version}. @xref{Init Module,, -Initialization Module}, for a discussion of how DejaGnu arranges to find -the right procedures for each target. - -@code{runtest} itself calls only two of these procedures, -@code{@var{tool}_exit} and @code{@var{tool}_version}; these procedures use -no arguments. - -The other two procedures, @code{@var{tool}_start} and -@code{@var{tool}_load}, are only called by the test suites themselves -(or by testsuite-specific initialization code); they may take arguments -or not, depending on the conventions used within each test suite. - -@ftable @code -@item @var{tool}_start -@cindex start procedure, tested tools -Starts a particular tool. For an interactive tool, -@code{@var{tool}_start} starts and initializes the tool, leaving the -tool up and running for the test cases; an example is @code{gdb_start}, -the start function for @sc{gdb}. For a batch oriented tool, -@code{@var{tool}_start} is optional; the recommended convention is to -let @code{@var{tool}_start} run the tool, leaving the output in a -variable called @code{comp_output}. Test scripts can then analyze -@samp{$comp_output} to determine the test results. An example of this -second kind of start function is @code{gcc_start}, the start function -for @sc{gcc}. - -@code{runtest} itself @emph{does not call} @code{@var{tool}_start}. The -initialization module @file{@var{tool}_init.exp} must call -@code{@var{tool}_start} for interactive tools; for batch-oriented tools, -each individual test script calls @code{@var{tool}_start} (or makes -other arrangements to run the tool). - -@item @var{tool}_load -@cindex load procedure, tested tools -Loads something into a tool. For an interactive tool, this conditions -the tool for a particular test case; for example, @code{gdb_load} loads -a new executable file into the debugger. For batch oriented tools, -@code{@var{tool}_load} may do nothing---though, for example, the -@sc{gcc} support uses @code{gcc_load} to load and run a binary on the -target environment. Conventionally, @code{@var{tool}_load} leaves the -output of any program it runs in a variable called @samp{exec_output}. -Writing @code{@var{tool}_load} can be the most complex part of extending -DejaGnu to a new tool or a new target, if it requires much communication -coding or file downloading. - -Test scripts call @code{@var{tool}_load}. - -@item @var{tool}_exit -@cindex exit procedure, tested tools -Cleans up (if necessary) before @code{runtest} exits. For interactive -tools, this usually ends the interactive session. You can also use -@code{@var{tool}_exit} to remove any temporary files left over from the -tests. +@strong{Sample output of automake with missing files} -@code{runtest} calls @code{@var{tool}_exit}. - -@item @var{tool}_version -@cindex version procedure, tested tools -Prints the version label and number for @var{tool}. This is called by -the DejaGnu procedure that prints the final summary report. The output -should consist of the full path name used for the tested tool, and its -version number. - -@code{runtest} calls @code{@var{tool}_version}. -@end ftable - -The usual convention for return codes from any of these procedures -(although it is not required by @code{runtest}) is to return @code{0} if -the procedure succeeded, @code{1} if it failed, and @code{-1} if there -was a communication error. - -@node Cross Targets -@section Remote targets supported - -@cindex targets -@cindex remote testing -The DejaGnu distribution includes support for the following remote -targets. You can set the target name and the connect mode in the -@file{site.exp} file (using the Tcl variables @samp{targetname} and -@samp{connectmode}, respectively), or on the @code{runtest} command line -(using @samp{--name} and @samp{--connect}). - -@table @strong -@item @sc{amd} 29000, with UDI protocol -Configure DejaGnu for target @samp{a29k-amd-udi}. (Cygnus -@code{configure} also recognizes the abbreviation @samp{udi29k}.) Then, -to run tests, use the @code{runtest} target name to specify whether you -want to use a simulator, or a particular hardware board. The particular -string to use with @samp{--name} will depend on your UDI setup file, -@file{udi_soc} (if @file{udi_soc} is not in your working directory, the -environment variable @samp{UDICONF} should contain a path to this file). -For example, if your UDI setup file includes these lines: -@end table -@c table "ends" *only* to allow wider example below - -@cartouche -@smallexample -iss AF_UNIX * isstip -r /home/gnu/29k/src/osboot/sim/osboot -mon AF_UNIX * montip -t serial -baud 9600 -com /dev/ttyb -@end smallexample -@end cartouche - -@table @strong -@item @w{ } -@c fake out table/item into continuing w/same margin as before -You can use @samp{--name iss} to run tests on the simulator, and -@samp{--name mon} to run tests on the 29K hardware. See the -manufacturer's manuals for more information on UDI and @file{udi_soc}. -@c FIXME! Is there a better ref than "the manufacturer's manuals"? - -@kindex mondfe -The default connect protocol is @samp{mondfe} with either back end. -@code{mondfe} is the only shell DejaGnu supports for UDI targets. -@code{mondfe} is an @sc{amd} specific monitor program freely available -from @sc{amd}. - -@emph{Warning:} This target requires @sc{gdb} version 4.7.2 (or -greater). Earlier versions of @sc{gdb} do not fully support the -@code{load} command on this target, so DejaGnu has no way to load -executable files from the debugger. - -@item Motorola 680x0 boards, a.out or @sc{coff} object format -Configure DejaGnu for any remote target matching @samp{m68k-*}. - -@emph{Warning:} Most @samp{m68k-*} configurations run all tests only for -native testing (when the target is the same as the host). When you -specify most of these targets for a cross configuration, you will only be -able to use tests that run completely within the host (for example, -tests of the binary utilities such as the archiver; or compiler tests -that only generate code rather than running it). - -To run a.out or @sc{coff} binaries on a remote M68K, you must configure -DejaGnu for a particular target board. @samp{m68k-abug} is an example. -(In general for an embedded environment, because it does not have absolute -addresses, a.out is not a good choice for output format in any case; most -often S-records or Hex-32 are used instead.) - -@item Motorola 68K MVME 135 board running ABug boot monitor -Configure for @samp{m68k-abug-aout} or @samp{m68k-abug-coff} (as a -target). This boot monitor can only download S-records; therefore, the -DejaGnu tests for this environment require a linker command script to -convert either output format to S-records, setting the default addresses -for @code{.text}, @code{.bss}, and @code{.data}. - -With this configuration, the default for @samp{--connect} is @samp{tip}. -@samp{tip} is the only communications protocol supported for connecting -to @samp{m68k-abug-*} targets. @samp{tip} uses an @sc{ascii} downloader -(the @code{~put} command) to load S-records into the target board. The -@samp{--name} string must be a machine name that @code{tip} -understands (for example, on some @code{tip} implementations it must be -an entry from the initialization file for @code{tip}; this file is -sometimes called @file{/etc/remote}). - -See your system documentation for information on how to create new -entries in @file{/etc/remote}. (Some @sc{unix} systems are distributed -with at least one default entry with a name resembling @samp{hardwire}; -if your system has one, you can edit it, or make a modified copy with a -new name.) When you have a working @file{/etc/remote} entry -@var{abugtarget}, you should be able to type @samp{tip -@var{abugtarget}}, and get the prompt @samp{135ABUG>} from the board. -Use the same @var{abugtarget} string with @samp{runtest --name}. - -@item Motorola IDP board running the rom68k boot monitor -@c FIXME 1: this doesn't really say anything! OK, so functionality is -@c the same. Is object code the same (srecords)? Do we configure with -@c the same triplets? What is the default for --connect? Is -@c any comms method other than tip supported? What prompt to expect -@c when tip connected? -@c FIXME 2: should @code{BUG} below be @code{ABUG}? -This is the same in functionality as the MVME board running the -@code{BUG} boot monitor. Only the monitor commands and the addresses are -different. - -@item VxWorks (Motorola 68K or Intel 960) -Configure DejaGnu for either @samp{m68k-wrs-vxworks} (abbreviated -@samp{vxworks68}) or @samp{i960-wrs-vxworks} (abbreviated -@samp{vxworks960}). Since both targets support IP addressing, specify -the network address (for example, a host name from @file{/etc/hosts}) -with @samp{--name}. - -The default connect protocol is @samp{rlogin}, but you can use any of -@samp{--connect rlogin}, @samp{--connect telnet}, or @samp{--connect -rsh}. - -Test scripts need no special code to load programs into these targets; -since VxWorks supports NFS, all you must do is ensure test programs are -on an exported filesystem. - -@cindex VxWorks, link with @samp{-r} -When you compile for VxWorks, use the linker @samp{-r} option to make -the linker output relocatable---at least if you want to use library -routines. Many standard C routines are included in VxWorks; often no -additional libraries are needed. See your VxWorks system documentation -for additional details. -@end table - -@node Input Files -@section The files DejaGnu reads -@cindex input files - -The @code{runtest} program used to invoke DejaGnu is a short shell -script generated by @code{make} during the configuration process. Its -main task is to read the main test framework driver, @file{runtest.exp}. - -@file{runtest.exp}, in turn, reads @code{expect} code from certain other -files, in this order: - -@enumerate -@item -Each of the @file{site.exp} local definition files available. -@xref{Customizing,,Setting @code{runtest} defaults}, for details. - -@item -@file{lib/utils.exp}, a collection of utility procedures. @xref{DejaGnu -Builtins,,DejaGnu Builtins}, for descriptions of these procedures. - -@item -@file{lib/framework.exp}, a file of subroutines meant for @code{runtest} -itself rather than for general-purpose use in both @code{runtest} and -test suites. - -@item -@file{debugger.exp}, Don Libes' Tcl Debugger. (See @cite{A Debugger for -Tcl Applications} by Don Libes. This paper is distributed with -@code{expect} in PostScript form as the file -@file{expect/tcl-debug.ps}.) - -@item -@file{lib/remote.exp}, a collection of subroutines meant for connecting -to remote machines. - -@item -@file{lib/target.exp}, a collection of subroutines used for the -configuration systems in DejaGnu. These procedures typically manipulate -or utilize the configuration system. - -@item -@c FIXME! A comment in runtest.exp claims a system default is used if -@c no tool-specific init file is not available; I couldn't see where -@c the program flow actually does this, though---pesch 30jul1993. -An initialization file @code{@var{tool}_init.exp}. @xref{Init -Module,,Initialization module}, for more discussion of init files. -@end enumerate +@example -@c This hard page break is mainly intended for smallbook formatting; -@c some examples in this section come out better if this starts at a -@c page boundary. -@page -@node Output Files -@section The files DejaGnu writes -@cindex output files +dgt:~/dejagnu.test$ automake --add-missing +automake: configure.in: installing `./install-sh' +automake: configure.in: installing `./mkinstalldirs' +automake: configure.in: installing `./missing' +automake: Makefile.am: installing `./INSTALL' +automake: Makefile.am: required file `./NEWS' not found +automake: Makefile.am: required file `./README' not found +automake: Makefile.am: installing `./COPYING' +automake: Makefile.am: required file `./AUTHORS' not found +automake: Makefile.am: required file `./ChangeLog' not found +configure.in: 4: required file `./calc.h.in' not found +Makefile.am:6: required directory ./doc does not exist +@end example -@code{runtest} always writes two kinds of output files: summary logs and -detailed logs. The contents of both of these are determined by your -tests. +Create a empty directory doc and empty files +INSTALL, NEWS, README, AUTHORS, ChangeLog and COPYING. +The default COPYING will point to the GNU Public License (GPL). +In a real project it would be time to add some meaningfull text in each file. -For troubleshooting, a third kind of output file is useful: use -@samp{--debug} to request an output file showing details of what -@code{expect} is doing internally. +Adapt calc to your environment by calling configure. -@menu -* Summary:: Files that summarize tests -* Detail:: Files that contain complete test results -* Debug:: Logging expect internal actions -@end menu +@strong{Sample output of configure +} -@node Summary -@subsection Summary log -@cindex summary log - -@code{runtest} always produces a summary output file -@file{@var{tool}.sum}. This summary shows the names of all test files -run; for each test file, one line of output from each @code{pass} -command (showing status @samp{PASS}, @samp{XPASS} or @samp{KPASS}) or -@code{fail} command (status @samp{FAIL}, @samp{XFAIL} or @samp{KFAIL}); -trailing summary statistics that count passing and failing tests (expected and -unexpected); and the full pathname and version number of the tool -tested. (All possible outcomes, and all errors, are always reflected in -the summary output file, regardless of whether or not you specify -@samp{--all}.) - -If any of your tests use the procedures @code{unresolved}, -@code{unsupported}, or @code{untested}, the summary output also -tabulates the corresponding outcomes. +@example -For example, after @samp{runtest --tool binutils}, look for a summary -log in @file{binutils.sum}. Normally, @code{runtest} writes this file -in your current working directory; use the @samp{--outdir} option to -select a different directory. +dgt:~/dejagnu.test$ ./configure +creating cache ./config.cache +checking whether to enable maintainer-specific portions of Makefiles... no +checking for a BSD compatible install... /usr/bin/install -c +checking whether build environment is sane... yes +checking whether make sets $@{MAKE@}... yes +checking for working aclocal... found +checking for working autoconf... found +checking for working automake... found +checking for working autoheader... found +checking for working makeinfo... found +checking for gcc... gcc checking whether the C compiler (gcc ) works... yes +checking whether the C compiler (gcc ) is a cross-compiler... no +checking whether we are using GNU C... yes +checking whether gcc accepts -g... yes +checking for a BSD compatible install... /usr/bin/install -c +checking how to run the C preprocessor... gcc -E +checking for stdlib.h... yes +checking for strcmp... yes +updating cache ./config.cache +creating ./config.status +creating Makefile creating calc.h +@end example -@need 3500 -@noindent -Here is a short sample summary log: - -@cartouche -@smallexample -Test Run By rob on Mon May 25 21:40:57 PDT 1992 - === gdb tests === -Running ./gdb.t00/echo.exp ... -PASS: Echo test -Running ./gdb.all/help.exp ... -PASS: help add-symbol-file -PASS: help aliases -PASS: help breakpoint "bre" abbreviation -FAIL: help run "r" abbreviation -Running ./gdb.t10/crossload.exp ... -PASS: m68k-elf (elf-big) explicit format; loaded -XFAIL: mips-ecoff (ecoff-bigmips) "ptype v_signed_char" signed -C types - === gdb Summary === -# of expected passes 5 -# of expected failures 1 -# of unexpected failures 1 -/usr/latest/bin/gdb version 4.6.5 -q -@end smallexample -@end cartouche - -@node Detail -@subsection Detailed log -@cindex detailed log - -@code{runtest} also saves a detailed log file @file{@var{tool}.log}, -showing any output generated by tests as well as the summary output. -For example, after @samp{runtest --tool binutils}, look for a detailed -log in @file{binutils.log}. Normally, @code{runtest} writes this file -in your current working directory; use the @samp{--outdir} option to -select a different directory. - -@need 4000 -@noindent -Here is a brief example showing a detailed log for @sc{g++} tests: +If you are familiar with GNU software, +this output should not contain any surprise to you. +Any errors should be easy to fix for such a simple program. -@cartouche -@smallexample -Test Run By rob on Mon May 25 21:40:43 PDT 1992 +Build the calc executable: - === g++ tests === +@strong{Sample output building calc +} ---- Running ./g++.other/t01-1.exp --- - PASS: operate delete +@example ---- Running ./g++.other/t01-2.exp --- - FAIL: i960 bug EOF -p0000646.C: In function `int warn_return_1 ()': -p0000646.C:109: warning: control reaches end of non-void function -p0000646.C: In function `int warn_return_arg (int)': -p0000646.C:117: warning: control reaches end of non-void function -p0000646.C: In function `int warn_return_sum (int, int)': -p0000646.C:125: warning: control reaches end of non-void function -p0000646.C: In function `struct foo warn_return_foo ()': -p0000646.C:132: warning: control reaches end of non-void function - ---- Running ./g++.other/t01-4.exp --- - FAIL: abort -900403_04.C:8: zero width for bit-field `foo' ---- Running ./g++.other/t01-3.exp --- - FAIL: segment violation -900519_12.C:9: parse error before `;' -900519_12.C:12: Segmentation violation -/usr/latest/bin/gcc: Internal compiler error: program cc1plus got -fatal signal +dgt:~/dejagnu.test$ make +gcc -DHAVE_CONFIG_H -I. -I. -I. -g -O2 -c calc.c +gcc -g -O2 -o calc calc.o +@end example - === g++ Summary === +You prepared a few files and then called some +commands. Respecting the right order assures a automatic and correctly +compiled calc program. The following example resumes the correct +order. -# of expected passes 1 -# of expected failures 3 -/usr/ps/bin/g++ version cygnus-2.0.1 -@end smallexample -@end cartouche +@strong{Creating the calc program using the GNU autotools} -@node Debug -@subsection Logging @code{expect} internal actions -@cindex debug log +@example -With the @samp{--debug} option, you can request a log file showing the -output from @code{expect} itself, running in debugging mode. This file -(@file{dbg.log}, in the directory where you start @code{runtest}) shows -each pattern @code{expect} considers in analyzing test output. +dgt:~/dejagnu.test$ aclocal +dgt:~/dejagnu.test$ autoconf +dgt:~/dejagnu.test$ autoheader +dgt:~/dejagnu.test$ automake --add-missing +dgt:~/dejagnu.test$ ./configure +dgt:~/dejagnu.test$ make -This file reflects each @code{send} command, showing the string sent as -input to the tool under test; and each @code{expect} command, showing -each pattern it compares with the tool output. +@end example -The log messages for @code{expect} begin with a message of the form +Play with calc and verify whether it works correctly. +A sample session might look like this: -@smallexample -expect: does @{@var{tool output}@} (spawn_id @var{n}) match pattern -@{@var{expected pattern}@}? -@end smallexample +@example -@noindent -For every unsuccessful match, @code{expect} issues a @samp{no} after -this message; if other patterns are specified for the same -@code{expect} command, they are reflected also, but without the first -part of the message (@samp{expect@dots{}match pattern}). - -When @code{expect} finds a match, the log for the successful match ends -with @samp{yes}, followed by a record of the @code{expect} variables set -to describe a successful match. Here is an excerpt from the debugging -log for a @sc{gdb} test: - -@c FIXME! Why is the second spawn_id shown 0 rather than 6? -@cartouche -@smallexample -send: sent @{break gdbme.c:34\n@} to spawn id 6 -expect: does @{@} (spawn_id 6) match pattern @{Breakpoint.*at.* file - gdbme.c, line 34.*\(gdb\) $@}? no -@{.*\(gdb\) $@}? no -expect: does @{@} (spawn_id 0) match pattern @{@}? no -@{\(y or n\) @}? no -@{buffer_full@}? no -@{virtual@}? no -@{memory@}? no -@{exhausted@}? no -@{Undefined@}? no -@{command@}? no -break gdbme.c:34 -Breakpoint 8 at 0x23d8: file gdbme.c, line 34. -(gdb) expect: does @{break gdbme.c:34\r\nBreakpoint 8 at 0x23d8: -file gdbme.c, line 34.\r\n(gdb) @} (spawn_id 6) match pattern -@{Breakpoint.*at.* file gdbme.c, line 34.*\(gdb\) $@}? yes -expect: set expect_out(0,start) @{18@} -expect: set expect_out(0,end) @{71@} -expect: set expect_out(0,string) @{Breakpoint 8 at 0x23d8: file -gdbme.c, line 34.\r\n(gdb) @} -expect: set expect_out(spawn_id) @{6@} -expect: set expect_out(buffer) @{break gdbme.c:34\r\nBreakpoint 8 -at 0x23d8: file gdbme.c, line 34.\r\n(gdb) @} - PASS: 70 0 breakpoint line number in file -@end smallexample -@end cartouche +dgt:~/dejagnu.test$ ./calc +calc: version +Version: 1.1 +calc: add 3 4 +7 +calc: multiply 3 4 +12 +calc: multiply 2 4 +12 +calc: quit -@noindent -This example exhibits three properties of @code{expect} and DejaGnu that -might be surprising at first glance: +@end example -@itemize @bullet -@item -Empty output for the first attempted match. The first set of attempted -matches shown ran against the output @samp{@{@}}---that is, no output. -@code{expect} begins attempting to match the patterns supplied -immediately; often, the first pass is against incomplete output (or -completely before all output, as in this case). +Look at the intentional bug that 2 times 4 equals 12. -@item -Interspersed tool output. The beginning of the log entry for the second -attempted match may be hard to spot: this is because the prompt -@samp{(gdb) } appears on the same line, just before the @samp{expect:} -that marks the beginning of the log entry. +The tests run by DejaGnu need a file called site.exp, +which is automatically generated if we call "make +site.exp". This was the purpose of the "AUTOMAKE_OPTIONS = +dejagnu" in Makefile.am. -@item -Fail-safe patterns. Many of the patterns tested are fail-safe patterns -provided by @sc{gdb} testing utilities, to reduce possible -indeterminacy. It is useful to anticipate potential variations -caused by extreme system conditions (@sc{gdb} might issue the message -@samp{virtual memory exhausted} in rare circumstances), or by changes in -the tested program (@samp{Undefined command} is the likeliest outcome if -the name of a tested command changes). +@strong{Sample output generating a site.exp} -The pattern @samp{@{@}} is a particularly interesting fail-safe -to notice; it checks for an unexpected @key{RET} prompt. This may -happen, for example, if the tested tool can filter output through a -pager. +@example -These fail-safe patterns (like the debugging log itself) are primarily -useful while developing test scripts. Use the @code{error} procedure to -make the actions for fail-safe patterns produce messages starting with -@samp{ERROR} on the @code{runtest} standard output, and in the detailed -log file. -@end itemize +dgt: make site.exp +dgt:~/dejagnu.test$ make site.exp +Making a new site.exp file... +@end example -@node Tests -@chapter How To Write a Test Cases -@cindex writing a test case -@cindex test case, writing +@node Our first automated tests, A first remote test, Create a minimal project; e_g_ calc, Getting DejaGnu up and running +@section Our first automated tests @menu -* Writing:: Writing a test case -* Debugging:: Debugging a test case -* Adding:: Adding a test case to a test suite -* Hints:: Hints on writing a test case -* Variables:: Special variables used by test cases +* Running the test for the calc example:: +* The various config files or how to avoid warnings:: +* When trouble strikes:: +* Testing "Hello world" locally:: @end menu -@node Writing -@section Writing a test case - -The easiest way to prepare a new test case is to base it on an existing -one for a similar situation. There are two major categories of tests: -batch or interactive. Batch oriented tests are usually easier to write. - -The @sc{gcc} tests are a good example of batch oriented tests. All -@sc{gcc} tests consist primarily of a call to a single common procedure, -since all the tests either have no output, or only have a few warning -messages when successfully compiled. Any non-warning output is a test -failure. All the C code needed is kept in the test directory. The test -driver, written in @code{expect}, need only get a listing of all the C -files in the directory, and compile them all using a generic procedure. -This procedure and a few others supporting for these tests are kept in -the library module @file{lib/c-torture.exp} in the @sc{gcc} test suite. -Most tests of this kind use very few @code{expect} features, and are -coded almost purely in Tcl. +@node Running the test for the calc example, The various config files or how to avoid warnings, , Our first automated tests +@subsection Running the test for the calc example -@noindent -Writing the complete suite of C tests, then, consisted of these steps: +Now we are ready to call the automated tests -@enumerate -@item -@cindex Granlund, Torbjorn -@cindex C torture test -Copying all the C code into the test directory. These tests were based on -the C-torture test created by Torbjorn Granlund (on behalf of the Free -Software Foundation) for @sc{gcc} development. +@strong{Sample output of runtest in a configured directory} -@item -Writing (and debugging) the generic @code{expect} procedures for -compilation. +@example -@item -Writing the simple test driver: its main task is to search the directory -(using the Tcl procedure @code{glob} for filename expansion with -wildcards) and call a Tcl procedure with each filename. It also checks -for a few errors from the testing procedure. -@end enumerate +dgt:~/dejagnu.test$ make check +make check-DEJAGNU +make[1]: Entering directory `/home/dgt/dejagnu.test' srcdir=`cd . && pwd`; export srcdir; \ +EXPECT=expect; export EXPECT; \ runtest=runtest; \ +if /bin/sh -c "$runtest --version" > /dev/null 2>&1; then \ +$runtest --tool calc CALC=`pwd`/calc --srcdir ./testsuite ; \ +else echo "WARNING: could not find \`runtest'" 1>&2; :;\ +fi +WARNING: Couldn't find the global config file. +WARNING: Couldn't find tool init file +Test Run By dgt on Sun Nov 25 21:42:21 2001 +Native configuration is i586-pc-linux-gnu + + === calc tests === + +Schedule of variations: + unix + +Running target unix +Using /usr/share/dejagnu/baseboards/unix.exp as board description file for target. +Using /usr/share/dejagnu/config/unix.exp as generic interface file for target. +Using ./testsuite/config/unix.exp as tool-and-target-specific interface file. +Running ./testsuite/calc.test/calc.exp ... +FAIL: multiply2 (bad match) + +=== calc Summary === -Testing interactive programs is intrinsically more complex. Tests for most -interactive programs require some trial and error before they are complete. +# of expected passes 5 +# of unexpected failures 1 +/home/Dgt/dejagnu.test/calc version Version: 1.1 +make[1]: *** [check-DEJAGNU] Fehler 1 +make[1]: Leaving directory `/home/Dgt/dejagnu.test' make: *** [check-am] Fehler 2 +@end example -However, some interactive programs can be tested in a simple fashion -reminiscent of batch tests. For example, prior to the creation of -DejaGnu, the @sc{gdb} distribution already included a wide-ranging -testing procedure. This procedure was very robust, and had already -undergone much more debugging and error checking than many recent -DejaGnu test cases. Accordingly, the best approach was simply to -encapsulate the existing @sc{gdb} tests, for reporting purposes. -Thereafter, new @sc{gdb} tests built up a family of @code{expect} -procedures specialized for @sc{gdb} testing. +Did you see the line "FAIL:"? The test cases for calc catch the bug in the calc.c file. Fix the error in calc.c later as the following examples assume a unchanged calc.c. -@file{gdb.t10/crossload.exp} is a good example of an interactive test. -@c FIXME! Check what *kind* of example it is---work-intensive, or generic... +Examine the output files calc.sum and calc.log. Try to +understand the testcases written in +~/dejagnu.test/testsuite/calc.test/calc.exp. To understand Expect you +might take a look at the book "Exploring Expect", which is +an excellent resource for learning and using Expect. (Pub: O'Reilly, +ISBN 1-56592-090-2) The book contains hundreds of examples and also +includes a tutorial on Tcl. Exploring Expect is 602 pages +long. -@node Debugging -@section Debugging a test case -@cindex debugging a test case -@cindex test case, debugging +@node The various config files or how to avoid warnings, When trouble strikes, Running the test for the calc example, Our first automated tests +@subsection The various config files or how to avoid warnings -@noindent -These are the kinds of debugging information available from DejaGnu: - -@enumerate -@item -Output controlled by test scripts themselves, explicitly allowed for by -the test author. This kind of debugging output appears in the detailed -output recorded in the @file{@var{tool}.log} file. To do the same for -new tests, use the @code{verbose} procedure (which in turn uses the -variable also called @code{verbose}) to control how much output to -generate. This will make it easier for other people running the test to -debug it if necessary. Whenever possible, if @samp{$verbose} is -@code{0}, there should be no output other than the output from -@code{pass}, @code{fail}, @code{error}, and @code{warning}. Then, to -whatever extent is appropriate for the particular test, allow -successively higher values of @samp{$verbose} to generate more -information. Be kind to other programmers who use your tests: provide -for a lot of debugging information. - -@item -Output from the internal debugging functions of Tcl and @code{expect}. -There is a command line options for each; both forms of debugging output -are recorded in the file @code{dbg.log} in the current directory. - -Use @samp{--debug} for information from the @code{expect} level; it -generates displays of the @code{expect} attempts to match the tool -output with the patterns specified (@pxref{Debug,,Debug Log}). This -output can be very helpful while developing test scripts, since it shows -precisely the characters received. Iterating between the latest attempt -at a new test script and the corresponding @file{dbg.log} can allow you -to create the final patterns by ``cut and paste''. This is sometimes -the best way to write a test case. - -Use @samp{--strace} to see more detail at the Tcl level; this shows how Tcl -procedure definitions expand, as they execute. The associated number -controls the depth of definitions expanded; see the discussion of -@samp{--strace} in @ref{Invoking runtest,,Running the Tests}. - -@item -Finally, if the value of @samp{verbose} is 3 or greater, @code{runtest} -turns on the @code{expect} command @code{log_user}. This command prints -all @code{expect} actions to the @code{expect} standard output, to the -detailed log file, and (if @samp{--debug} is on) to @file{dbg.log}. -@end enumerate - -@node Adding -@section Adding a test case to a test suite -@cindex adding a test case - -There are two slightly different ways to add a test case. One is to add -the test case to an existing directory. The other is to create a new -directory to hold your test. The existing test directories represent -several styles of testing, all of which are slightly different; examine -the directories for the tool of interest to see which (if any) is most -suitable. - -Adding a @sc{gcc} test can be very simple: just add the C code to any -directory beginning with @samp{gcc.} and it runs on the next -@samp{runtest --tool gcc}. - -To add a test to @sc{gdb}, first add any source code you will need to -the test directory. Then you can either create a new @code{expect} file, -or add your test to an existing one (any file with a @samp{.exp} -suffix). Creating a new @samp{.exp} file is probably a better idea if -the test is significantly different from existing tests. Adding it as a -separate file also makes upgrading easier. If the C code has to be -already compiled before the test will run, then you'll have to add it to -the @file{Makefile.in} file for that test directory, then run -@code{configure} and @code{make}. - -Adding a test by creating a new directory is very similar: - -@enumerate -@item -Create the new directory. All subdirectory names begin with the name of -the tool to test; e.g. @sc{g++} tests might be in a directory called -@file{g++.other}. There can be multiple test directories that start with -the same tool name (such as @samp{g++}). - -@item -Add the new directory name to the @samp{configdirs} definition in the -@file{configure.in} file for the test suite directory. This way when -@code{make} and @code{configure} next run, they include the new directory. - -@item -Add the new test case to the directory, as above. - -@item -To add support in the new directory for configure and make, you must -also create a @code{Makefile.in} and a @code{configure.in}. @xref{What -Configure Does,,What Configure Does, configure.info, Cygnus Configure}. -@end enumerate - -@c FIXME! Expand this sentence to at least a section, maybe a chapter... -@c The @file{admin} directory contains templates for a few common forms -@c of test. - -@node Hints -@section Hints on writing a test case -@cindex hints on test case writing - -There may be useful existing procedures already written for your test in -the @file{lib} directory of the DejaGnu distribution. @xref{DejaGnu -Builtins,,DejaGnu Builtins}. - -It is safest to write patterns that match @emph{all} the output -generated by the tested program; this is called @dfn{closure}. If a -pattern does not match the entire output, any output that remains will -be examined by the @emph{next} @code{expect} command. In this -situation, the precise boundary that determines which @code{expect} -command sees what is very sensitive to timing between the @code{expect} -task and the task running the tested tool. As a result, the test may -sometimes appear to work, but is likely to have unpredictable results. -(This problem is particularly likely for interactive tools, but can also -affect batch tools---especially for tests that take a long time to finish.) -The best way to ensure closure is to use the @samp{-re} option for the -@code{expect} command to write the pattern as a full regular -expressions; then you can match the end of output using a @samp{$}. It -is also a good idea to write patterns that match all available output by -using @samp{.*\} after the text of interest; this will also match any -intervening blank lines. Sometimes an alternative is to match end of -line using @samp{\r} or @samp{\n}, but this is usually too dependent on -terminal settings. -@c FIXME!! explain what "end of output" means for interactive task. -@c (Timeout or EOF, right?) - -Always escape punctuation, such as @samp{(} or @samp{"}, in your -patterns; for example, write @samp{\(}. If you forget to escape -punctuation, you will usually see an error message like @samp{extra -characters after close-quote}. - -If you have trouble understanding why a pattern does not match the -program output, try using the @samp{--debug} option to @code{runtest}, -and examine the debug log carefully. @xref{Debug,,Debug Log}. - -Be careful not to neglect output generated by setup rather than by the -interesting parts of a test case. For example, while testing @sc{gdb}, -I issue a send @samp{set height 0\n} command. The purpose is simply to -make sure @sc{gdb} never calls a paging program. The @samp{set height} -command in @sc{gdb} does not generate any output; but running @emph{any} -command makes @sc{gdb} issue a new @samp{(gdb) } prompt. If there were -no @code{expect} command to match this prompt, the output @samp{(gdb) } -begins the text seen by the next @code{expect} command---which might -make @emph{that} pattern fail to match. - -To preserve basic sanity, I also recommended that no test ever pass if -there was any kind of problem in the test case. To take an extreme -case, tests that pass even when the tool will not spawn are misleading. -Ideally, a test in this sort of situation should not fail either. -Instead, print an error message by calling one of the DejaGnu procedures -@code{error} or @code{warning}. +DejaGnu may be customized by each user. It first searches for a +file called ~/.dejagnurc. Create the file ~/.dejagnurc and insert the +following line: -@node Variables -@section Special variables used by test cases -@cindex special variables +@example -@cindex variables for all tests -Your test cases can use these variables, with conventional meanings (as -well as the variables saved in @file{site.exp} -@pxref{Customizing,,Setting @code{runtest} defaults}): +puts "I am ~/.dejagnurc" +@end example -@quotation -@emph{These variables are available to all test cases.} -@end quotation +Rerun make check. Test whether the output contains "I am ~/.dejagnurc". +Create ~/my_dejagnu.exp and insert the following line: -@ftable @code -@item prms_id -@cindex PRMS bug number -@cindex GNATS bug number -@cindex bug number -The tracking system (e.g. @sc{gnats}) number identifying a corresponding -bugreport. (@samp{0} if you do not specify it in the test script.) +@example -@item bug_id -@cindex bug number, extra -An optional bug id; may reflect a bug identification from another -organization. (@samp{0} if you do not specify it.) +puts "I am ~/my_dejagnu.exp" +@end example -@item subdir -@cindex current test subdirectory -The subdirectory for the current test case. -@end ftable +In a Bash-Shell enter -@quotation -@emph{These variables should never be changed. They appear in most -tests.} -@end quotation +@example -@ftable @code -@item expect_out(buffer) -@cindex last command output -The output from the last command. This is an internal variable set by -@code{expect}. +dgt:~/dejagnu.test$ export DEJAGNU=~/my_dejagnu.exp +@end example -@item exec_output -This is the output from a @code{@var{tool}_load} command. This only -applies to tools like @sc{gcc} and @sc{gas} which produce an object -file that must in turn be executed to complete a test. +Run "make check" again. The output should not contain +"WARNING: Couldn't find the global config file.". +Create the sub-directory lib. Create the file "calc.exp" in it and insert the following line: -@item comp_output -This is the output from a @code{@var{tool}_start} command. This is -conventionally used for batch oriented programs, like @sc{gcc} and -@sc{gas}, that may produce interesting output (warnings, errors) without -further interaction. -@end ftable +@example -@node Extending -@chapter New Tools, Targets, or Hosts +puts "I am lib/calc.exp" +@end example -The most common ways to extend the DejaGnu framework are: adding a suite -of tests for a new tool to be tested; adding support for testing on a -new target; and porting @code{runtest} to a new host. +The last warning "WARNING: Couldn't find tool init file" +should not be part of the output of make check. +Create the directory ~/boards. Create the file ~/boards/standard.exp and insert the following line: -@menu -* Adding Tools:: How to add tests for a new tool -* Adding Targets:: How to add a new target -* Porting:: Porting DejaGnu to a new host -@end menu +@example -@node Adding Tools -@section Writing tests for a new tool +puts "I am boards/standard.exp" +@end example -In general, the best way to learn how to write (code or even prose) is -to read something similar. This principle applies to test cases and to -test suites. Unfortunately, well-established test suites have a way of -developing their own conventions: as test writers become more -experienced with DejaGnu and with Tcl, they accumulate more utilities, -and take advantage of more and more features of @code{expect} and Tcl in -general. +If the variable DEJAGNU is still not empty then the (abbreviated) output of "make check" should look like this: + +@strong{Sample output of runtest with the usual configuration files} -Inspecting such established test suites may make the prospect of -creating an entirely new test suite appear overwhelming. Nevertheless, -it is quite straightforward to get a new test suite going. +@example + +dgt:~/dejagnu.test$ make check +<...> +fi +I am ~/.dejagnurc +I am ~/my_dejagnu.exp +I am lib/calc.exp +Test Run By dgt on Sun Nov 25 22:19:14 2001 +Native configuration is i586-pc-linux-gnu + + === calc tests === +Using /home/Dgt/boards/standard.exp as standard board description\ +file for build. +I am ~/boards/standard.exp +Using /home/Dgt/boards/standard.exp as standard board description\ + file for host. +I am ~/boards/standard.exp + +Schedule of variations: + unix + +Running target unix +Using /home/Dgt/boards/standard.exp as standard board description\ + file for target. +I am ~/boards/standard.exp +Using /usr/share/dejagnu/baseboards/unix.exp as board description file\ +for target. +<...> +@end example -@cindex Lupton, Robert -There is one test suite that is guaranteed not to grow more elaborate -over time: both it and the tool it tests were created expressly to -illustrate what it takes to get started with DejaGnu. The -@file{example/} directory of the DejaGnu distribution contains both an -interactive tool called @code{calc}, and a test suite for it. Reading -this test suite, and experimenting with it, is a good way to supplement -the information in this section. (Thanks to Robert Lupton for creating -@code{calc} and its test suite---and also the first version of this -section of the manual!) +It is up to you to decide when and where to use any of the above +mentioned config files for customizing. +This chapters showed you where and in which order the different config +files are run. -To help orient you further in this task, here is an outline of the steps -to begin building a test suite for a program @var{example}. +@node When trouble strikes, Testing "Hello world" locally, The various config files or how to avoid warnings, Our first automated tests +@subsection When trouble strikes -@enumerate -@item -Create or select a directory to contain your new collection of tests. -Change to that directory (shown here as @code{testsuite}): +Calling runtest with the '-v'-flag shows you in even more details which files are searched in which order. Passing it several times gives more and more details. + +@strong{Displaying details about runtest execution} @example -eg$ cd testsuite/ + +runtest -v -v -v --tool calc CALC=`pwd`/calc --srcdir ./testsuite @end example -@item -Create a @file{configure.in} file in this directory, to control -configuration-dependent choices for your tests. So far as DejaGnu is -concerned, the important thing is to set a value for the variable -@code{target_abbrev}; this value is the link to the init file you will -write soon. (For simplicity, we assume the environment is Unix, and use -@samp{unix} as the value.) +Calling runtest with the '--debug'-flag logs a lot of details to dbg.log where you can analyse it afterwards. -What else is needed in @file{configure.in} depends on the requirements -of your tool, your intended test environments, and which -@code{configure} system you use. This example is a minimal -@code{configure.in} for use with Cygnus Configure. (For an alternative -based on the FSF @code{autoconf} system, see the @code{calc} example -distributed with DejaGnu.) Replace @var{example} with the name of your -program: +In all test cases you can temporary adjust the verbosity of information by adding the following Tcl-command to any tcl file that gets loaded by +dejagnu, for instance, ~/.dejagnurc: -@cartouche -@smallexample -# This file is a shell script fragment -# for use with Cygnus configure. +@example -srctrigger="@var{example}.0" -srcname="The DejaGnu @var{example} tests" +set verbose 9 +@end example -# per-host: +@node Testing "Hello world" locally, , When trouble strikes, Our first automated tests +@subsection Testing "Hello world" locally -# per-target: +This test checks, whether the built-in shell command "echo Hello world" +will really write "Hello world" on the console. +Create the file ~/dejagnu.test/testsuite/calc.test/local_echo.exp. +It should contain the following lines -# everything defaults to unix for a target -target_abbrev=unix +@strong{A first (local) test case} -# post-target: +@example -@end smallexample -@end cartouche +set test "Local Hello World" +send "echo Hello World" +expect @{ + -re "Hello World" @{ pass "$test" @} +@} +@end example -@item -Create @file{Makefile.in}, the source file used by @code{configure} to -build your @file{Makefile}. Its leading section should as usual contain -the values that @code{configure} may override: +Run runtest again and verify the output "calc.log" -@cartouche -@smallexample -srcdir = . -prefix = /usr/local +@node A first remote test, , Our first automated tests, Getting DejaGnu up and running +@section A first remote test -exec_prefix = $(prefix) -bindir = $(exec_prefix)/bin -libdir = $(exec_prefix)/lib -tooldir = $(libdir)/$(target_alias) +Testing remote targets is a lot trickier especially if you are using an +embedded target +which has no built in support for things like a compiler, ftp server or a Bash-shell. +Before you can test calc on a remote target you have to acquire a few basics skills. -datadir = $(exec_prefix)/lib/dejagnu +@menu +* Setup telnet to your own host:: +* A test case for login via telnet:: +* Remote testing "Hello world":: +* Transferring files from/to the target:: +* Preparing for crosscompilation:: +* Remote testing of calc:: +* Using Windows as host and vxWorks as target:: +@end menu -RUNTEST = runtest -RUNTESTFLAGS = -FLAGS_TO_PASS = +@node Setup telnet to your own host, A test case for login via telnet, , A first remote test +@subsection Setup telnet to your own host -#### host, target, site specific Makefile frags come in here. -@end smallexample -@end cartouche +The easiest remote host is usually the host you are working on. +In this example we will use telnet to login in your own workstation. +For security reason you should never have a telnet deamon running on +machine connected on the internet, as password and usernames are transmitted +in clear text. +We assume you know how to setup your machine for a telnet daemon. -This should be followed by the standard targets at your site. To begin -with, they need not do anything---for example, these definitions will -do: +Next try whether you may login in your own host by issuing the +command "telnet localhost.1". In order to be able to +distinguish between a normal session an a telnet login add the following lines to /home/dgt/.bashrc. -@cartouche -@smallexample +@example -all: +if [ "$REMOTEHOST" ] +then + PS1='remote:\w\$ ' +fi +@end example -info: +Now on the machine a "remote" login looks like this: -install-info: +@strong{Sample log of a telnet login to localhost} -install: -uninstall: +@example -clean: - -rm -f *~ core *.info* +dgt:~/dejagnu.test$ telnet localhost +Trying 127.0.0.1... +Connected to 127.0.0.1. +Escape character is '^]'. +Debian GNU/Linux testing/unstable Linux +K6Linux login: dgt +Password: +Last login: Sun Nov 25 22:46:34 2001 from localhost on pts/4 +Linux K6Linux 2.4.14 #1 Fre Nov 16 19:28:25 CET 2001 i586 unknown +No mail. +remote:~$ exit +logout +Connection closed by foreign host. +@end example -@end smallexample -@end cartouche +@node A test case for login via telnet, Remote testing "Hello world", Setup telnet to your own host, A first remote test +@subsection A test case for login via telnet -It is also a good idea to make sure your @file{Makefile} can rebuild -itself if @file{Makefile.in} changes, with a target like this (which -works for either Cygnus or FSF Configure): +In order to define a correct setup we have add a line containing +"set target unix" either to ~/.dejagnurc or to ~/my_dejagnu.exp. +In ~/boards/standard.exp add the following four lines to define a few patterns for the DejaGnu telnet login procedure. -@cartouche -@smallexample -Makefile : $(srcdir)/Makefile.in $(host_makefile_frag) \ - $(target_makefile_frag) - $(SHELL) ./config.status -@end smallexample -@end cartouche +@strong{Defining a remote target board} -You also need to include two targets important to DejaGnu: @code{check}, -to run the tests, and @code{site.exp}, to set up the Tcl copies of -configuration-dependent values. The @code{check} target must run -@samp{runtest --tool @var{example}}: +@example -@cartouche -@smallexample -check: site.exp all - $(RUNTEST) $(RUNTESTFLAGS) $(FLAGS_TO_PASS) \ - --tool @var{example} --srcdir $(srcdir) -@end smallexample -@end cartouche +set_board_info shell_prompt "remote:" +set_board_info telnet_username "dgt" +set_board_info telnet_password "top_secret" +set_board_info hostname "localhost" -The @code{site.exp} target should usually set up (among other things!) a -Tcl variable for the name of your program: +@end example -@cartouche -@smallexample -site.exp: ./config.status Makefile - @@echo "Making a new config file..." - -@@rm -f ./tmp? - @@touch site.exp +As DejaGnu will be parsing the telnet session output for some well +known pattern the output there are a lot of things that can go wrong. +If you have any problems verify your setup: - -@@mv site.exp site.bak - @@echo "## these variables are automatically\ - generated by make ##" > ./tmp0 - @@echo "# Do not edit here. If you wish to\ - override these values" >> ./tmp0 - @@echo "# add them to the last section" >> ./tmp0 - @@echo "set host_os $@{host_os@}" >> ./tmp0 - @@echo "set host_alias $@{host_alias@}" >> ./tmp0 - @@echo "set host_cpu $@{host_cpu@}" >> ./tmp0 - @@echo "set host_vendor $@{host_vendor@}" >> ./tmp0 - @@echo "set target_os $@{target_os@}" >> ./tmp0 - @@echo "set target_alias $@{target_alias@}" >> ./tmp0 - @@echo "set target_cpu $@{target_cpu@}" >> ./tmp0 - @@echo "set target_vendor $@{target_vendor@}" >> ./tmp0 - @@echo "set host_triplet $@{host_canonical@}" >> ./tmp0 - @@echo "set target_triplet $@{target_canonical@}">>./tmp0 - @@echo "set tool binutils" >> ./tmp0 - @@echo "set srcdir $@{srcdir@}" >> ./tmp0 - @@echo "set objdir `pwd`" >> ./tmp0 - @@echo "set @var{examplename} @var{example}" >> ./tmp0 - @@echo "## All variables above are generated by\ - configure. Do Not Edit ##" >> ./tmp0 - @@cat ./tmp0 > site.exp - @@sed < site.bak \ - -e '1,/^## All variables above are.*##/ d' \ - >> site.exp - -@@rm -f ./tmp? -@end smallexample -@end cartouche +@itemize @bullet{} @item -Create a directory (in @file{testsuite/}) called @file{config/}: +Is @file{/etc/motd} empty? -@example -eg$ mkdir config -@end example +@item +Is @file{/etc/issue.net} empty? @item -Make an init file in this directory; its name must start with the -@code{target_abbrev} value, so call it @file{config/unix.exp}. -This is the file that contains the target-dependent procedures; -fortunately, most of them do not have to do very much in order for -@code{runtest} to run. +Exists a empty @file{~/.hushlogin}? -If @var{example} is not interactive, you can get away with this minimal -@file{unix.exp} to begin with: +@item +The LANG environment variable must be either empty or set to "C". +@end itemize -@cartouche -@smallexample -proc foo_exit @{@} @{@} -proc foo_version @{@} @{@} -@end smallexample -@end cartouche +To test the login via telnet write a sample test case. +Create the file ~/dejagnu.test/testsuite/calc.test/remote_echo.exp and +add the following few lines: -If @var{example} is interactive, however, you might as well define a -start routine @emph{and invoke it} by using an init file like this: +@strong{DejaGnu script for logging in into a remote target} -@cartouche -@smallexample -proc foo_exit @{@} @{@} -proc foo_version @{@} @{@} +@example -proc foo_start @{@} @{ - global @var{examplename} - spawn $@var{examplename} - expect @{ - -re "" @{@} - @} +puts "this is remote_echo.exp target for $target " +target_info $target +#set verbose 9 +set shell_id [remote_open $target] +set test "Remote login to $target" +#set verbose 0 +puts "Spawn id for remote shell is $shell_id" +if @{ $shell_id > 0 @} @{ + pass "$test" +@} else @{ + fail "Remote open to $target" @} -foo_start -@end smallexample -@end cartouche +@end example -@item -Create a directory whose name begins with your tool's name, to contain -tests: +In the runtest output you should find something like: @example -eg$ mkdir @var{example}.0 + +Running ./testsuite/calc.test/local_echo.exp ... +Running ./testsuite/calc.test/remote_echoo.exp ... +this is remote_echo.exp target is unix +Spawn id for remote shell is exp7 @end example -@item -Create a sample test file in @file{@var{example}.0}. Its name must end -with @samp{.exp}; you can use @samp{first-try.exp} To begin with, just -write there a line of Tcl code to issue a message: +Have again a look at calc.log to get a feeling how DejaGnu and expect +parse the input. -@cartouche -@smallexample -send_user "Testing: one, two...\n" -@end smallexample -@end cartouche +@node Remote testing "Hello world", Transferring files from/to the target, A test case for login via telnet, A first remote test +@subsection Remote testing "Hello world" -@item -Back in the @file{testsuite/} (top level) directory, run +Next you will transform the above "hello world" example to +its remote equivalent. +This can be done by adding the following lines to our file remote_echo.exp. + +@strong{A first (local) remote "Hello world" test} @example -eg$ configure + +set test "Remote_send Hello World" +set status [remote_send $target "echo \"Hello\" \"World\"\n" ] +pass "$test" +set test "Remote_expect Hello World" +remote_expect $target 5 @{ + -re "Hello World" @{ pass "$test" @} +@} @end example -(You may have to specify more of a path, if a suitable @code{configure} -is not available in your execution path.) +Call make check. The output should contain +"# of expected passes 9" and "# of unexcpected failures 1". -@item -You are now ready to triumphantly type @samp{make check} or -@samp{runtest --tool @var{example}}. You should see something like this: +Have a look at the procedures in /usr/share/dejagnu/remote.exp to have an overview of the offered procedures and their features. -@cartouche -@smallexample -Test Run By rhl on Fri Jan 29 16:25:44 EST 1993 +Now setup a real target. +In the following example we assume as target a PowerBook running Debian. +As above add a test user "dgt", install telnet and FTP servers. +In order to distinguish it from the host add the line - === @var{example} tests === +@example +PS1='test:>' +@end example -Running ./@var{example}.0/first-try.exp ... -Testing: one, two... +@noindent +to /home/dgt/.bash_profile. +Also add a corresponding entry "powerbook" to /etc/hosts and verify that you +are able to ping, telnet and ftp to the target "powerbook". - === @var{example} Summary === +In order to let runtest run its test on the "powerbook" target change the following lines in ~/boards/standard.exp: -@end smallexample -@end cartouche +@strong{Board definition for a remote target} -There is no output in the summary, because so far the example does not -call any of the procedures that establish a test outcome. +@example -@item -Begin writing some real tests. For an interactive tool, you should -probably write a real exit routine in fairly short order; in any case, -you should also write a real version routine soon. -@end enumerate +set_board_info protocol "telnet" +set_board_info telnet_username "dgt" +set_board_info telnet_password "top_secret" +set_board_info shell_prompt "test:> " +set_board_info hostname "powerbook" +@end example -@node Adding Targets -@section Adding a target -@cindex adding a target +Now call runtest again with the same arguments and verify whether all went okay by taking a close look at calc.log. -DejaGnu has some additional requirements for target support, beyond the -general-purpose provisions of Cygnus @code{configure}. @code{runtest} -must actively communicate with the target, rather than simply generating -or managing code for the target architecture. Therefore, each tool -requires an initialization module for each target. For new targets, you -must supply a few Tcl procedures to adapt DejaGnu to the target. This -permits DejaGnu itself to remain target independent. @xref{Init -Module,,Initialization module}, for a discussion of the naming -conventions that enable DejaGnu to locate and use init files. +@node Transferring files from/to the target, Preparing for crosscompilation, Remote testing "Hello world", A first remote test +@subsection Transferring files from/to the target -Usually the best way to write a new initialization module is to edit an -existing initialization module; some trial and error will be required. -If necessary, you can use the @samp{--debug} option to see what -is really going on. +A simple procedure like this will do the job for you: -When you code an initialization module, be generous in printing -information controlled by the @code{verbose} procedure (@pxref{DejaGnu -Builtins, DejaGnu procedures}). +@strong{Test script to transfer a file to a remote target} -Most of the work is in getting the communications right. Communications -code (for several situations involving IP networks or serial lines) is -available in a DejaGnu library file, @file{lib/remote.exp}. -@xref{DejaGnu Builtins,,DejaGnu Builtins}. +@example -@c FIXME! Say something about Tcl debugger here. -If you suspect a communication problem, try running the connection -interactively from @code{expect}. (There are three ways of running -@code{expect} as an interactive interpreter. You can run @code{expect} -with no arguments, and control it completely interactively; or you can -use @samp{expect -i} together with other command-line options and -arguments; or you can run the command @code{interpreter} from any -@code{expect} procedure. Use @code{return} to get back to the calling -procedure (if any), or @code{return -tcl} to make the calling procedure -itself return to its caller; use @code{exit} or end-of-file to leave -@code{expect} altogether.) Run the program whose name is recorded in -@samp{$connectmode}, with the arguments in @samp{$targetname}, to -establish a connection. You should at least be able to get a prompt -from any target that is physically connected. - -@node Porting -@section Porting to a new host -@cindex porting to a new host - -The task of porting DejaGnu is basically that of porting Tcl and -@code{expect}. Tcl and @code{expect}, as distributed with DejaGnu, both -use @code{autoconf}; they should port automatically to most Unix -systems. - -Once Tcl and @code{expect} are ported, DejaGnu should run. Most system -dependencies are taken care of by using @code{expect} as the main -command shell. - -@node Installation -@appendix Installing DejaGnu - -@cindex host, explained -@cindex target, explained -@cindex DejaGnu configuration -@cindex configuring DejaGnu -Once you have the DejaGnu source unpacked and available, you must first -configure the software to specify where it is to run (and the associated -defaults); then you can proceed to installing it. +set test "Remote_download" +puts "Running Remote_download" +# set verbose 9 +set remfile /home/dgt/dejagnu2 -@menu -* Configuring DejaGnu:: -* Installing DejaGnu:: -@end menu +set status [remote_download $target /home/dgt/.dejagnurc $remfile] +if @{ "$status" == "" @} @{ + fail "Remote download to $remfile on $target" +@} else @{ + pass "$test" +@} -@node Configuring DejaGnu -@section Configuring the DejaGnu test driver +puts "status of remote_download ist $status" +# set verbose 0 +@end example -It is usually best to configure in a directory separate -from the source tree, specifying where to find the source with the -optional @samp{--srcdir} option to @code{configure}. DejaGnu uses the -GNU @code{autoconf} to configure itself. For more info on using -autoconf, read the GNU autoconf manual. To configure, execute the -@file{configure} program, no other options are required. For an example, -to configure in a seperate tree for objects, execute the configure -script from the source tree like this: - -@smallexample -../dejagnu-1.3/configure -@end smallexample - -DejaGnu doesn't care at config time if it's for testing a native system -or a cross system. That is determined at runtime by using the config -files. - -@cindex @code{prefix}, configure options -@cindex @code{exec_prefix}, configure options. -You may also want to use the @code{configure} option @samp{--prefix} to -specify where you want DejaGnu and its supporting code installed. By -default, installation is in subdirectories of @file{/usr/local}, but you -can select any alternate directory @var{altdir} by including -@samp{--prefix=@var{altdir}} on the @code{configure} command line. -(This value is captured in the Makefile variables @code{prefix} -and @code{exec_prefix}.) - -@cindex auxiliary programs -@cindex test suite distributions -@cindex @code{make} builds part of tests -Save for a small number of example tests, the DejaGnu distribution -itself does not include any test suites; these are available separately. -Test suites for the @sc{gnu} compiler (testing both GCC and G++) and for -the @sc{gnu} binary utilities are distributed in parallel with the -DejaGnu distribution (but packaged as separate files). The test suite -for the @sc{gnu} debugger is distributed in parallel with each release -of GDB itself, starting with GDB 4.9. After configuring the top-level -DejaGnu directory, unpack and configure the test directories for the -tools you want to test; then, in each test directory, run @code{make} to -build auxiliary programs required by some of the tests. +After running runtest again, check whether the file dejagnu2 exists on the target. +This example will only work if the rcp command works with your target. +If you have a working FTP-server on the target you can use it by adding the +following lines to ~/boards/standard.exp: -@node Installing DejaGnu -@section Installing DejaGnu +@strong{Defining a board to use FTP as file transport} -@cindex installing DejaGnu -To install DejaGnu in your filesystem (either in @file{/usr/local}, or -as specified by your @samp{--prefix} option to @code{configure}), execute +@example + +set_board_info file_transfer "ftp" +set_board_info ftp_username "dgt" +set_board_info ftp_password "1234" +@end example + +@node Preparing for crosscompilation, Remote testing of calc, Transferring files from/to the target, A first remote test +@subsection Preparing for crosscompilation + +For crosscompiling you need working binutils, gcc and a base library like +libc or glib for your target. +It is beyond the scope of this document to describe how to get it working. +The following examples assume a cross compiler for PowerPC which is called linux-powerpc-gcc. + +Add AC_CANONICAL_TARGET in dejagnu.test/configure.in at the following location. Copy config.guess from /usr/share/automake to dejagnu.test. + +@example + +AM_CONFIG_HEADER(calc.h) +AC_CANONICAL_TARGET([]) +AM_INIT_AUTOMAKE(calc, 1.1) +@end example + +You need to run automake 2.5 or later. +Depending on your installation calling autoconf2.5 instead of autoconf is not needed. +The sequence to regenerate all files is: + +@strong{Using autotools for cross development} + +@example + +$ autoconf2.5 +$ autoheader +$ automake +$ ./configure --host=powerpc-linux --target=powerpc-linux +configure: WARNING: If you wanted to set the --build type, don't use --host. + If a cross compiler is detected then cross compile mode will be used. +checking build system type... ./config.guess: ./config.guess: No such file or directory +configure: error: cannot guess build type; you must specify one +$ cp /usr/share/automake/config.guess . +$ ./configure --host=powerpc-linux --target=powerpc-linux +configure: WARNING: If you wanted to set the --build type, don't use --host. +If a cross compiler is detected then cross compile mode will be used. \ +checking build system type... i586-pc-linux-gnu +checking host system type... powerpc-unknown-linux-gnu +<...> +checking whether we are cross compiling... yes +<...> +Configuration: +Source code location: . +C Compiler: powerpc-linux-gcc +C Compiler flags: -g -O2 + +@end example + +Everything should be ready to recompile for the target: + +@example +$ make +powerpc-linux-gcc -DHAVE_CONFIG_H -I. -I. -I. -g -O2 -c calc.c +powerpc-linux-gcc -g -O2 -o calc calc.o + +@end example + +@node Remote testing of calc, Using Windows as host and vxWorks as target, Preparing for crosscompilation, A first remote test +@subsection Remote testing of calc + +Not yet written, as I have problem getting libc6-dev-powerpc to work. Probably I first have to build my cross compiler. + +@node Using Windows as host and vxWorks as target, , Remote testing of calc, A first remote test +@subsection Using Windows as host and vxWorks as target + +A more thorough walk-through will be written in a few weeks. + +In order to test the vxWorks as a target I changed boards/standards.exp to reflect my settings (IP, username, password). Then I reconfigured vxWorks to include a FTP and telnet server (using the same username/password combination ad in boards/standard.exp). + +With this setup and some minor modification (e.g. replacing echo by printf) in my test cases I could test my vxWorks system. It sure does not seem to be a correct setup by DejaGnu standard. For instance, it still loading /usr/share/dejagnu/baseboards/unix.exp instead of vxWorks. In any case I found that (at least under Windows) I did not find out how the command line would let me override settings in my personal config files. + +@node Running Tests, Customizing DejaGnu, Getting DejaGnu up and running, Top +@chapter Running Tests + +There are two ways to execute a testsuite. The most +common way is when there is existing support in the +@file{Makefile}. This support consists of a +@i{check} target. The other way is to execute the +@code{runtest} program directly. To run +@code{runtest} directcly from the command line requires +either all the correct options, or the @ref{Local Config File,,Local Config File}. must be setup +correctly. + +@menu +* Make check: Make Check. +* Runtest:: +* The files DejaGnu produces_: Output Files. +@end menu + +@node Make Check, Runtest, , Running Tests +@section Make check + +To run tests from an existing collection, first use +@code{configure} as usual to set up the +build directory. Then try typing: + +@example + + make check + +@end example + +If the @i{check} target exists, it +usually saves you some trouble. For instance, it can set up any +auxiliary programs or other files needed by the tests. The most +common file the check builds is the +@i{site.exp}. The site.exp file contains +various variables that DejaGnu used to dertermine the +configuration of the program being tested. This is mostly for +supporting remote testing. + +The @i{check} target is supported by GNU +Automake. To have DejaGnu support added to your +generated @file{Makefile.in}, just add the keyword +dejagnu to the AUTOMAKE_OPTIONS variable in your +@file{Makefile.am} file. + +Once you have run @i{make check} to build +any auxiliary files, you can invoke the test driver +@code{runtest} directly to repeat the tests. +You will also have to execute @code{runtest} +directly for test collections with no +@i{check} target in the +@file{Makefile}. + +@node Runtest, Output Files, Make Check, Running Tests +@section Runtest + +@code{runtest} is the executable test driver +for DejaGnu. You can specify two kinds of things on the +@code{runtest} command line: command line options, +and Tcl variables for the test scripts. The options are listed +alphabetically below. + +@code{runtest} returns an exit code of +@i{1} if any test has an unexpected result; otherwise +(if all tests pass or fail as expected) it returns @i{0} +as the exit code. + +@menu +* Output States:: +* Invoking Runtest:: +* Common Options: Common Operations. +@end menu + +@node Output States, Invoking Runtest, , Runtest +@subsection Output States + +@file{runtest} flags the outcome of each +test as one of these cases. @ref{A POSIX Conforming Test Framework,,A POSIX Conforming Test Framework}. for a +discussion of how POSIX specifies the meanings of these +cases. + +@table @asis + +@item PASS +The most desirable outcome: the test succeeded, and +was expected to succeed. + +@item XPASS +A pleasant kind of failure: a test was expected to +fail, but succeeded. This may indicate progress; inspect the test +case to determine whether you should amend it to stop expecting +failure. + +@item FAIL +A test failed, although it was expected to succeed. +This may indicate regress; inspect the test case and the failing +software to ocate the bug. + +@item XFAIL +A test failed, but it was expected to fail. This +result indicates no change in a known bug. If a test fails because +the operating system where the test runs lacks some facility required +by the test, the outcome is @i{UNSUPPORTED} +instead. + +@item UNRESOLVED +Output from a test requires manual inspection; the +testsuite could not automatically determine the outcome. For +example, your tests can report this outcome is when a test does not +complete as expected. + +@item UNTESTED +A test case is not yet complete, and in particular +cannot yet produce a @i{PASS} or +@i{FAIL}. You can also use this outcome in dummy +``tests'' that note explicitly the absence of a real test case for a +particular property. + +@item UNSUPPORTED +A test depends on a conditionally available feature +that does not exist (in the configured testing environment). For +example, you can use this outcome to report on a test case that does +not work on a particular target because its operating system support +does not include a required subroutine. +@end table + +runtest may also display the following messages: + +@table @asis + +@item ERROR +Indicates a major problem (detected by the test case +itself) in running the test. This is usually an unrecoverable error, +such as a missing file or loss of communication to the target. (POSIX +testsuites should not emit this message; use +@i{UNSUPPORTED}, @i{UNTESTED}, or +@i{UNRESOLVED} instead, as +appropriate.) + +@item WARNING +Indicates a possible problem in running the +test. Usually warnings correspond to recoverable errors, or display +an important message about the following tests. + +@item NOTE +An informational message about the test +case. +@end table + +@node Invoking Runtest, Common Operations, Output States, Runtest +@subsection Invoking Runtest + +This is the full set of command line options that +@file{runtest} recognizes. Arguments may be +abbreviated to the shortest unique string. + +@table @asis + +@item @code{--all} (-a) +Display all test output. By default, +@i{runtest} shows only the output of tests that +produce unexpected results; that is, tests with status +@i{FAIL} (unexpected failure), +@i{XPASS} (unexpected success), or +@i{ERROR} (a severe error in the test case +itself). Specify @i{--all} to see output for tests +with status @i{PASS} (success, as expected) +@i{XFAIL} (failure, as expected), or +@i{WARNING} (minor error in the test case +itself). + +@item @code{--build [string]} +@i{string} is a full configuration +``triple'' name as used by @code{configure}. This +is the type of machine DejaGnu and the tools to be tested are built +on. For a normal cross this is the same as the host, but for a +canadian cross, they are seperate. + +@item @code{--host [string]} +@code{string} is a full configuration +``triple'' name as used by @i{configure}. Use this +option to override the default string recorded by your +configuration's choice of host. This choice does not change how +anything is actually configured unless --build is also specified; it +affects @i{only} DejaGnu procedures that compare the +host string with particular values. The procedures +@i{ishost}, @i{istarget}, +@i{isnative}, and @i{setup}xfail@} +are affected by @i{--host}. In this usage, +@i{host} refers to the machine that the tests are to +be run on, which may not be the same as the +@i{build} machine. If @i{--build} +is also specified, then @i{--host} refers to the +machine that the tests wil, be run on, not the machine DejaGnu is run +on. + +@item @code{--host_board [name]} +The host board to use. + +@item @code{--target [string]} +Use this option to override the default setting +(running native tests). @i{string} is a full +configuration ``triple'' name of the form +@i{cpu-vendor-os} as used by +@code{configure}. This option changes the +configuration @i{runtest} uses for the default tool +names, and other setup information. + +@item @code{--debug} (-de) +Turns on the @i{expect} internal +debugging output. Debugging output is displayed as part of the +@i{runtest} output, and logged to a file called +@file{dbg.log}. The extra debugging output does +@i{not} appear on standard output, unless the +verbose level is greater than 2 (for instance, to see debug output +immediately, specify @i{--debug}-v -v@}). The +debugging output shows all attempts at matching the test output of +the tool with the scripted patterns describing expected output. The +output generated with @i{--strace} also goes into +@file{dbg.log}. + +@item @code{--help} (-he) +Prints out a short summary of the +@i{runtest} options, then exits (even if you also +specify other options). + +@item @code{--ignore [name(s)] } +The names of specific tests to +ignore. + +@item @code{--objdir [path]} +Use @i{path} as the top directory +containing any auxiliary compiled test code. This defaults to +@file{.}. Use this option to locate pre-compiled test +code. You can normally prepare any auxiliary files needed with +@i{make}. + +@item @code{--outdir [path]} +Write output logs in directory +@file{path}. The default is @i{.@}, +the} directory where you start +@i{runtest}. This option affects only the summary +and the detailed log files +@file{tool.sum} and +@file{tool.log}. The DejaGnu debug +log @file{dbg.log} always appears (when requested) in +the local directory. + +@item @code{--reboot [name]} +Reboot the target board when +@i{runtest} initializes. Usually, when running tests +on a separate target board, it is safer to reboot the target to be +certain of its state. However, when developing test scripts, +rebooting takes a lot of time. + +@item @code{--srcdir [path]} +Use @file{path} as the top directory +for test scripts to run. @i{runtest} looks in this +directory for any subdirectory whose name begins with the toolname +(specified with @i{--tool}). For instance, with +@i{--tool}gdb@}, @i{runtest} uses +tests in subdirectories @file{gdb.*} (with the usual +shell-like filename expansion). If you do not use +@i{--srcdir}, @i{runtest} looks for +test directories under the current working +directory. + +@item @code{--strace [number]} +Turn on internal tracing for +@i{expect}, to n levels deep. By adjusting the +level, you can control the extent to which your output expands +multi-level Tcl statements. This allows you to ignore some levels of +@i{case} or @i{if} statements. +Each procedure call or control structure counts as one ``level''. The +output is recorded in the same file, @file{dbg.log}, +used for output from @i{--debug}. + +@item @code{--connect [program]} +Connect to a target testing environment as specified +by @i{type}, if the target is not the computer +running @i{runtest}. For example, use +@i{--connect} to change the program used to connect +to a ``bare board'' boot monitor. The choices for +@i{type} in the DejaGnu 1.4 distribution are +@i{rlogin}, @i{telnet}, +@i{rsh}, @i{tip}, +@i{kermit}, and @i{mondfe}. + +The default for this option depends on the configuration most +convenient communication method available, but often other +alternatives work as well; you may find it useful to try alternative +connect methods if you suspect a communication problem with your +testing target. + +@item @code{--baud [number]} +Set the default baud rate to something other than +9600. (Some serial interface programs, like @i{tip}, +use a separate initialization file instead of this +value.) + +@item @code{--target_board [name(s)]} +The list of target boards to run tests +on. + +@item @code{--tool[name(s)]} +Specifies which testsuite to run, and what +initialization module to use. @code{--tool} is used +@i{only} for these two purposes. It is +@i{not} used to name the executable program to +test. Executable tool names (and paths) are recorded in +@file{site.exp} and you can override them by specifying +Tcl variables on the command line. + +For example, including "@code{--tool} gcc" on the +@i{runtest} command line runs tests from all test +subdirectories whose names match @file{gcc.*}, and uses +one of the initialization modules named +@file{config/*-gcc.exp}. To specify the name of the +compiler (perhaps as an alternative path to what +@i{runtest} would use by default), use +@i{GCC=binname} on the @i{runtest} +command line. + +@item @code{--tool_exec [name]} +The path to the tool executable to +test. + +@item @code{--tool_opts [options]} +A list of additional options to pass to the +tool. + +@item @code{--verbose} (-v) +Turns on more output. Repeating this option increases +the amount of output displayed. Level one (@i{-v}) +is simply test output. Level two (@i{-v}-v@}) shows +messages on options, configuration, and process control. Verbose +messages appear in the detailed (@file{*.log}) log +file, but not in the summary (@file{*.sum}) log +file. + +@item @code{--version} (-V) +Prints out the version numbers of DejaGnu, +@i{expect} and Tcl, and exits without running any +tests. + +@item @code{--D[0-1]} +Start the internal Tcl debugger. The Tcl debugger +supports breakpoints, single stepping, and other common debugging +activities. See the document "Debugger for Tcl Applications" by Don +Libes. (Distributed in PostScript form with +@i{expect} as the file +@file{expect/tcl-debug.ps.}. If you specify +@i{-D1}, the @i{expect} shell stops +at a breakpoint as soon as DejaGnu invokes it. If you specify +@i{-D0}, DejaGnu starts as usual, but you can enter +the debugger by sending an interrupt (e.g. by typing +@key{C}@key{c}). + +@item @file{testfile}.exp[=arg(s)] +Specify the names of testsuites to run. By default, +@i{runtest} runs all tests for the tool, but you can +restrict it to particular testsuites by giving the names of the +@i{.exp expect} scripts that control +them. @i{testsuite}.exp may not include path +information; use plain filenames. + +@item @file{testfile}.exp="testfile1 ..." +Specify a subset of tests in a suite to run. For +compiler or assembler tests, which often use a single +@i{.exp} script covering many different source +files, this option allows you to further restrict the tests by +listing particular source files to compile. Some tools even support +wildcards here. The wildcards supported depend upon the tool, but +typically they are @i{?}, @i{*}, +and @i{[chars]}. + +@item @code{tclvar}=value +You can define Tcl variables for use by your test +scripts in the same style used with @i{make} for +environment variables. For example, @i{runtest +GDB=gdb.old} defines a variable called +@code{GDB}; when your scripts refer to +@code{$GDB} in this run, they use the value +@i{gdb.old}. + +The default Tcl variables used for most tools are defined in +the main DejaGnu @i{Makefile}; their values are +captured in the @file{site.exp} file. +@end table + +@node Common Operations, , Invoking Runtest, Runtest +@subsection Common Options + +Typically, you don't need must to use any command-line options. +@code{--tool} used is only required when there are more than +one testsuite in the same directory. The default options are in the +local site.exp file, created by "make site.exp". + +For example, if the directory @file{gdb/testsuite} +contains a collection of DejaGnu tests for GDB, you can run them like +this: + +@example + + eg$ cd gdb/testsuite + eg$ runtest --tool gdb + +@end example + +Test output follows, ending with: + +@example + + === gdb Summary === + + # of expected passes 508 + # of expected failures 103 + /usr/latest/bin/gdb version 4.14.4 -nx + +@end example + +You can use the option @i{--srcdir} to point to +some other directory containing a collection of tests: + +@example + + eg$ runtest--srcdir /devo/gdb/testsuite + +@end example + +By default, @code{runtest} prints only the +names of the tests it runs, output from any tests that have unexpected +results, and a summary showing how many tests passed and how many +failed. To display output from all tests (whether or not they behave +as expected), use the @i{--all} option. For more +verbose output about processes being run, communication, and so on, use +@i{--verbose}. To see even more output, use multiple +@i{--verbose} options. for a more detailed explanation +of each @code{runtest} option. + +Test output goes into two files in your current directory: +summary output in @file{tool.sum}, +and detailed output in @file{ +tool.log}. (@i{tool} +refers to the collection of tests; for example, after a run with +@i{--tool} gdb, look for output files +@file{gdb.sum} and +@file{gdb.log}.) + +@node Output Files, , Runtest, Running Tests +@section The files DejaGnu produces. + +DejaGnu always writes two kinds of output files: summary +logs and detailed logs. The contents of both of these are +determined by your tests. + +For troubleshooting, a third kind of output file is useful: +use @code{--debug} to request an output file showing +details of what Expect is doing +internally. + +@menu +* Summary File:: +* Log File:: +* Debug Log File:: +@end menu + +@node Summary File, Log File, , Output Files +@subsection Summary File + +DejaGnu always produces a summary output file +@file{tool.sum}. This summary shows the names of +all test files run; for each test file, one line of output from +each @code{pass} command (showing status +@i{PASS} or @i{XPASS}) or +@code{fail} command (status +@i{FAIL} or @i{XFAIL}); +trailing summary statistics that count passing and failing tests +(expected and unexpected); and the full pathname and version +number of the tool tested. (All possible outcomes, and all +errors, are always reflected in the summary output file, +regardless of whether or not you specify +@code{--all}.) + +If any of your tests use the procedures +@code{unresolved}, @code{unsupported}, +or @code{runtested}, the summary output also +tabulates the corresponding outcomes. + +For example, after @code{runtest --tool +binutils}, look for a summary log in +@file{binutils.sum}. Normally, DejaGnu writes this +file in your current working directory; use the +@code{--outdir} option to select a different +directory. + +@strong{Here is a short sample summary log} + +@example + + Test Run By rob on Mon May 25 21:40:57 PDT 1992 + === gdb tests === + Running ./gdb.t00/echo.exp ... + PASS: Echo test + Running ./gdb.all/help.exp ... + PASS: help add-symbol-file + PASS: help aliases + PASS: help breakpoint "bre" abbreviation + FAIL: help run "r" abbreviation + Running ./gdb.t10/crossload.exp ... + PASS: m68k-elf (elf-big) explicit format; loaded + XFAIL: mips-ecoff (ecoff-bigmips) "ptype v_signed_char" signed C types + === gdb Summary === + # of expected passes 5 + # of expected failures 1 + # of unexpected failures 1 + /usr/latest/bin/gdb version 4.6.5 -q + +@end example + +@node Log File, Debug Log File, Summary File, Output Files +@subsection Log File + +DejaGnu also saves a detailed log file +@file{tool.log}, showing any output generated by +tests as well as the summary output. For example, after +@code{runtest --tool binutils}, look for a detailed +log in @file{binutils.log}. Normally, DejaGnu +writes this file in your current working directory; use the +@code{--outdir} option to select a different +directory. + +@strong{Here is a brief example showing a detailed log for +G++ tests} + +@example + + Test Run By rob on Mon May 25 21:40:43 PDT 1992 + + === g++ tests === + + --- Running ./g++.other/t01-1.exp --- + PASS: operate delete + + --- Running ./g++.other/t01-2.exp --- + FAIL: i960 bug EOF + p0000646.C: In function `int warn_return_1 ()': + p0000646.C:109: warning: control reaches end of non-void function + p0000646.C: In function `int warn_return_arg (int)': + p0000646.C:117: warning: control reaches end of non-void function + p0000646.C: In function `int warn_return_sum (int, int)': + p0000646.C:125: warning: control reaches end of non-void function + p0000646.C: In function `struct foo warn_return_foo ()': + p0000646.C:132: warning: control reaches end of non-void function + + --- Running ./g++.other/t01-4.exp --- + FAIL: abort + 900403_04.C:8: zero width for bit-field `foo' + --- Running ./g++.other/t01-3.exp --- + FAIL: segment violation + 900519_12.C:9: parse error before `;' + 900519_12.C:12: Segmentation violation + /usr/latest/bin/gcc: Internal compiler error: program cc1plus got fatal signal + + === g++ Summary === + + # of expected passes 1 + # of expected failures 3 + /usr/latest/bin/g++ version cygnus-2.0.1 + +@end example + +@node Debug Log File, , Log File, Output Files +@subsection Debug Log File + +With the @code{--debug} option, you can request +a log file showing the output from +Expect itself, running in debugging +mode. This file (@file{dbg.log}, in the directory +where you start @code{runtest}) shows each pattern +Expect considers in analyzing test +output. + +This file reflects each @code{send} command, +showing the string sent as input to the tool under test; and +each Expect command, showing each +pattern it compares with the tool output. + +@strong{The log messages begin with a message of the form} + +@example + + + expect: does @{tool output@} (spawn_id n) + match pattern @{expected pattern@}? + + +@end example + +For every unsuccessful match, +Expect issues a +@i{no} after this message; if other patterns +are specified for the same Expect +command, they are reflected also, but without the first part of +the message (@i{expect... match pattern}). + +When Expect finds a match, the +log for the successful match ends with @i{yes}, +followed by a record of the Expect +variables set to describe a successful match. + +@strong{Here is an excerpt from the debugging log for a +GDB test:} + +@example + + send: sent @{break gdbme.c:34\n@} to spawn id 6 + expect: does @{@} (spawn_id 6) match pattern @{Breakpoint.*at.* file + gdbme.c, line 34.*\(gdb\) $@}? no + @{.*\(gdb\) $@}? no + expect: does @{@} (spawn_id 0) match pattern @{return@} ? no + @{\(y or n\) @}? no + @{buffer_full@}? no + @{virtual@}? no + @{memory@}? no + @{exhausted@}? no + @{Undefined@}? no + @{command@}? no + break gdbme.c:34 + Breakpoint 8 at 0x23d8: file gdbme.c, line 34. + (gdb) expect: does @{break gdbme.c:34\r\nBreakpoint 8 at 0x23d8: + file gdbme.c, line 34.\r\n(gdb) @} (spawn_id 6) match pattern + @{Breakpoint.*at.* file gdbme.c, line 34.*\(gdb\) $@}? yes + expect: set expect_out(0,start) @{18@} + expect: set expect_out(0,end) @{71@} + expect: set expect_out(0,string) @{Breakpoint 8 at 0x23d8: file + gdbme.c, line 34.\r\n(gdb) @} + epect: set expect_out(spawn_id) @{6@} + expect: set expect_out(buffer) @{break gdbme.c:34\r\nBreakpoint 8 + at 0x23d8: file gdbme.c, line 34.\r\n(gdb) @} + PASS: 70 0 breakpoint line number in file + +@end example + +This example exhibits three properties of +Expect and +DejaGnu that might be surprising at +first glance: + +@itemize @bullet{} + +@item +Empty output for the first attempted match. The +first set of attempted matches shown ran against the output +@i{@{@}} --- that is, no +output. Expect begins +attempting to match the patterns supplied immediately; often, +the first pass is against incomplete output (or completely +before all output, as in this case). + +@item +Interspersed tool output. The beginning of +the log entry for the second attempted match may be hard to +spot: this is because the prompt @i{@{(gdb) @}} +appears on the same line, just before the +@i{expect:} that marks the beginning of the +log entry. + +@item +Fail-safe patterns. Many of the patterns +tested are fail-safe patterns provided by +GDB testing utilities, to reduce +possible indeterminacy. It is useful to anticipate potential +variations caused by extreme system conditions +(GDB might issue the message +@i{virtual memory exhausted} in rare +circumstances), or by changes in the tested program +(@i{Undefined command} is the likeliest +outcome if the name of a tested command changes). + +The pattern @i{@{return@}} is a +particularly interesting fail-safe to notice; it checks for an +unexpected @key{RET} prompt. This may happen, +for example, if the tested tool can filter output through a +pager. + +These fail-safe patterns (like the debugging log itself) +are primarily useful while developing test scripts. Use the +@code{error} procedure to make the actions for +fail-safe patterns produce messages starting with +@i{ERROR} on standard output, and in the +detailed log file. +@end itemize + +@node Customizing DejaGnu, Extending DejaGnu, Running Tests, Top +@chapter Customizing DejaGnu + +The site configuration file, @file{site.exp}, +captures configuration-dependent values and propagates them to the +DejaGnu test environment using Tcl variables. This ties the +DejaGnu test scripts into the @code{configure} and +@code{make} programs. If this file is setup correctly, +it is possible to execute a testsuite merely by typing +@code{runtest}. + +DejaGnu supports two @file{site.exp} +files. The multiple instances of @file{site.exp} are +loaded in a fixed order built into DejaGnu. The first file loaded +is the local file @file{site.exp}, and then the +optional global @file{site.exp} file as +pointed to by the @code{DEJAGNU} environment +variable. + +There is an optional @i{master} +@file{site.exp}, capturing configuration values that +apply to DejaGnu across the board, in each configuration-specific +subdirectory of the DejaGnu library directory. +@code{runtest} loads these values first. The master +@file{site.exp} contains the default values for all +targets and hosts supported by DejaGnu. This master file is +identified by setting the environment variable +@code{DEJAGNU} to the name of the file. This is also +refered to as the ``global'' config file. + +Any directory containing a configured testsuite also has a +local @file{site.exp}, capturing configuration values +specific to the tool under test. Since @code{runtest} +loads these values last, the individual test configuration can +either rely on and use, or override, any of the global values from +the global @file{site.exp} file. + +You can usually generate or update the testsuite's local +@file{site.exp} by typing @code{make +site.exp} in the testsuite directory, after the test +suite is configured. + +You can also have a file in your home directory called +@file{.dejagnurc}. This gets loaded first before the +other config files. Usually this is used for personal stuff, like +setting the @code{all_flag} so all the output gets +printed, or your own verbosity levels. This file is usually +restricted to setting command line options. + +You can further override the default values in a +user-editable section of any @file{site.exp}, or by +setting variables on the @code{runtest} command +line. + +@menu +* Local Config File:: +* Global Config File:: +* Board Config File:: +* Remote Host Testing:: +* Config File Values:: +@end menu + +@node Local Config File, Global Config File, , Customizing DejaGnu +@section Local Config File + +It is usually more convenient to keep these @i{manual +overrides} in the @file{site.exp} +local to each test directory, rather than in the global +@file{site.exp} in the installed DejaGnu +library. This file is mostly for supplying tool specific info +that is required by the testsuite. + +All local @file{site.exp} files have +two sections, separated by comment text. The first section is +the part that is generated by @code{make}. It is +essentially a collection of Tcl variable definitions based on +@file{Makefile} environment variables. Since they +are generated by @code{make}, they contain the +values as specified by @code{configure}. (You can +also customize these values by using the @code{--site} +option to @code{configure}.) In particular, this +section contains the @file{Makefile} +variables for host and target configuration data. Do not edit +this first section; if you do, your changes are replaced next +time you run @code{make}. + +@strong{The first section starts with} + +@example + + ## these variables are automatically generated by make ## + # Do not edit here. If you wish to override these values + # add them to the last section + +@end example + +In the second section, you can override any default values +(locally to DejaGnu) for all the variables. The second section +can also contain your preferred defaults for all the command +line options to @code{runtest}. This allows you to +easily customize @code{runtest} for your preferences +in each configured test-suite tree, so that you need not type +options repeatedly on the command line. (The second section may +also be empty, if you do not wish to override any defaults.) + +@strong{The first section ends with this line} + +@example + + ## All variables above are generated by configure. Do Not Edit ## + +@end example + +You can make any changes under this line. If you wish to +redefine a variable in the top section, then just put a +duplicate value in this second section. Usually the values +defined in this config file are related to the configuration of +the test run. This is the ideal place to set the variables +@code{host_triplet}, @code{build_triplet}, +@code{target_triplet}. All other variables are tool +dependant, i.e., for testing a compiler, the value for +@code{CC} might be set to a freshly built binary, as +opposed to one in the user's path. + +Here's an example local site.exp file, as used for +GCC/G++ testing. + +@strong{Local Config File} + +@example + + ## these variables are automatically generated by make ## + # Do not edit here. If you wish to override these values + # add them to the last section + set rootme "/build/devo-builds/i586-pc-linux-gnulibc1/gcc" + set host_triplet i586-pc-linux-gnulibc1 + set build_triplet i586-pc-linux-gnulibc1 + set target_triplet i586-pc-linux-gnulibc1 + set target_alias i586-pc-linux-gnulibc1 + set CFLAGS "" + set CXXFLAGS "-isystem /build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libio -isystem $srcdir/../libg++/src -isystem $srcdir/../libio -isystem $srcdir/../libstdc++ -isystem $srcdir/../libstdc++/stl -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libg++ -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libstdc++" + append LDFLAGS " -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../ld" + set tmpdir /build/devo-builds/i586-pc-linux-gnulibc1/gcc/testsuite + set srcdir "$@{srcdir@}/testsuite" + ## All variables above are generated by configure. Do Not Edit ## + + +@end example + +This file defines the required fields for a local config +file, namely the three config triplets, and the srcdir. It also +defines several other Tcl variables that are used exclusivly by +the GCC testsuite. For most test cases, the CXXFLAGS and LDFLAGS +are supplied by DejaGnu itself for cross testing, but to test a +compiler, GCC needs to manipulate these itself. + +@node Global Config File, Board Config File, Local Config File, Customizing DejaGnu +@section Global Config File + +The master config file is where all the target specific +config variables for a whole site get set. The idea is +that for a centralized testing lab where people have to share a +target between multiple developers. There are settings for both +remote targets and remote hosts. Here's an example of a Master +Config File (also called the Global config file) for a +@i{canadian cross}. A canadian cross is when +you build and test a cross compiler on a machine other than the +one it's to be hosted on. + +Here we have the config settings for our California +office. Note that all config values are site dependant. Here we +have two sets of values that we use for testing m68k-aout cross +compilers. As both of these target boards has a different +debugging protocol, we test on both of them in sequence. + +@strong{Global Config file} + +@example + + + # Make sure we look in the right place for the board description files. + if ![info exists boards_dir] @{ + set boards_dir @{@} + @} + lappend boards_dir "/nfs/cygint/s1/cygnus/dejagnu/boards" + + verbose "Global Config File: target_triplet is $target_triplet" 2 + global target_list + + case "$target_triplet" in @{ + @{ "native" @} @{ + set target_list "unix" + @} + @{ "sparc64-*elf" @} @{ + set target_list "sparc64-sim" + @} + @{ "mips-*elf" @} @{ + set target_list "mips-sim wilma barney" + @} + @{ "mips-lsi-elf" @} @{ + set target_list "mips-lsi-sim@{,soft-float,el@}" + @} + @{ "sh-*hms" @} @{ + set target_list @{ "sh-hms-sim" "bloozy" @} + @} + @} + +@end example + +In this case, we have support for several cross compilers, +that all run on this host. For testing on operating systems that +don't support Expect, DejaGnu can be run on the local build +machine, and it can connect to the remote host and run all the +tests for this cross compiler on that host. All the remote OS +requires is a working telnetd. + +As you can see, all one does is set the variable +@code{target_list} to the list of targets and options to +test. The simple settings, like for +@i{sparc64-elf} only require setting the name of +the single board config file. The @i{mips-elf} +target is more complicated. Here it sets the list to three target +boards. One is the default mips target, and both +@i{wilma} @i{barney} are +symbolic names for other mips boards. Symbolic names are covered +in the @ref{Adding A New Board,,Adding A New Board}. chapter. The more complicated +example is the one for @i{mips-lsi-elf}. This one +runs the tests with multiple iterations using all possible +combinations of the @code{--soft-float} and the +@code{--el} (little endian) option. Needless to say, +this last feature is mostly compiler specific. + +@node Board Config File, Remote Host Testing, Global Config File, Customizing DejaGnu +@section Board Config File + +The board config file is where board specfic config data +is stored. A board config file contains all the higher-level +configuration settings. There is a rough inheritance scheme, where it is +possible to base a new board description file on an existing one. There +are also collections of custom procedures for common environments. For +more information on adding a new board config file, go to the @ref{Adding A New Board,,Adding A New Board}. chapter. + +An example board config file for a GNU simulator is as +follows. @code{set_board_info} is a procedure that sets the +field name to the specified value. The procedures in square brackets +@i{[]} are @i{helper procedures}. Thes +are used to find parts of a tool chain required to build an executable +image that may reside in various locations. This is mostly of use for +when the startup code, the standard C lobraries, or the tool chain itself +is part of your build tree. + +@strong{Board Config File} + +@example + + # This is a list of toolchains that are supported on this board. + set_board_info target_install @{sparc64-elf@} + + # Load the generic configuration for this board. This will define any + # routines needed by the tool to communicate with the board. + load_generic_config "sim" + + # We need this for find_gcc and *_include_flags/*_link_flags. + load_base_board_description "basic-sim" + + # Use long64 by default. + process_multilib_options "long64" + + setup_sim sparc64 + + # We only support newlib on this target. We assume that all multilib + # options have been specified before we get here. + set_board_info compiler "[find_gcc]" + set_board_info cflags "[libgloss_include_flags] [newlib_include_flags]" + set_board_info ldflags "[libgloss_link_flags] [newlib_link_flags]" + # No linker script. + set_board_info ldscript ""; + + # Used by a few gcc.c-torture testcases to delimit how large the + # stack can be. + set_board_info gcc,stack_size 16384 + # The simulator doesn't return exit statuses and we need to indicate this + # the standard GCC wrapper will work with this target. + set_board_info needs_status_wrapper 1 + # We can't pass arguments to programs. + set_board_info noargs 1 + +@end example + +There are five helper procedures used in this example. The first +one, @code{find gcc} looks for a copy of the GNU compiler in +your build tree, or it uses the one in your path. This will also return +the proper transformed name for a cross compiler if you whole build tree +is configured for one. The next helper procedures are +@code{libgloss_include_flags} & +@code{libgloss_link_flags}. These return the proper flags to +compiler and link an executable image using @ref{Libgloss,,Libgloss}., the GNU BSP (Board Support Package). The final +procedures are @code{newlib_include_flag} & +@code{newlib_include_flag}. These find the Newlib C +library, which is a reentrant standard C library for embedded systems +comprising of non GPL'd code. + +@node Remote Host Testing, Config File Values, Board Config File, Customizing DejaGnu +@section Remote Host Testing + +@quotation + +@strong{Note} + +Thanks to Dj Delorie for the original paper that +this section is based on. +@end quotation + +DejaGnu also supports running the tests on a remote +host. To set this up, the remote host needs an ftp server, and a +telnet server. Currently foreign operating systems used as +remote hosts are VxWorks, VRTX, DOS/Windows 3.1, MacOS and Windows. + +The recommended source for a Windows-based FTP +server is to get IIS (either IIS 1 or Personal Web Server) from +@uref{http://www.microsoft.com,http://www.microsoft.com}. +When you install it, make sure you install the FTP server - it's +not selected by default. Go into the IIS manager and change the +FTP server so that it does not allow anonymous FTP. Set the home +directory to the root directory (i.e. c:\) of a suitable +drive. Allow writing via FTP. + +It will create an account like IUSR_FOOBAR where foobar is +the name of your machine. Go into the user editor and give that +account a password that you don't mind hanging around in the +clear (i.e. not the same as your admin or personal +passwords). Also, add it to all the various permission groups. + +You'll also need a telnet server. For Windows, go +to the @uref{http://ataman.com,Ataman} web site, +pick up the Ataman Remote Logon Services for Windows, and +install it. You can get started on the eval period anyway. Add +IUSR_FOOBAR to the list of allowed users, set the HOME directory +to be the same as the FTP default directory. Change the Mode +prompt to simple. + +Ok, now you need to pick a directory name to do all the +testing in. For the sake of this example, we'll call it piggy +(i.e. c:\piggy). Create this directory. + +You'll need a unix machine. Create a directory for the +scripts you'll need. For this example, we'll use +/usr/local/swamp/testing. You'll need to have a source tree +somewhere, say /usr/src/devo. Now, copy some files from +releng's area in SV to your machine: + +@strong{Remote host setup} + +@example + + cd /usr/local/swamp/testing + mkdir boards + scp darkstar.welcomehome.org:/dejagnu/cst/bin/MkTestDir . + scp darkstar.welcomehome.org:/dejagnu/site.exp . + scp darkstar.welcomehome.org:/dejagnu/boards/useless98r2.exp boards/foobar.exp + export DEJAGNU=/usr/local/swamp/testing/site.exp + + +@end example + +You must edit the boards/foobar.exp file to reflect your +machine; change the hostname (foobar.com), username +(iusr_foobar), password, and ftp_directory (c:/piggy) to match +what you selected. + +Edit the global @file{ site.exp} to reflect your +boards directory: + +@strong{Add The Board Directory} + +@example + + lappend boards_dir "/usr/local/swamp/testing/boards" + +@end example + +Now run MkTestDir, which is in the contrib +directory. The first parameter is the toolchain prefix, the +second is the location of your devo tree. If you are testing a +cross compiler (ex: you have sh-hms-gcc.exe in your PATH on +the PC), do something like this: + +@strong{Setup Cross Remote Testing} + +@example + + ./MkTestDir sh-hms /usr/dejagnu/src/devo + +@end example + +If you are testing a native PC compiler (ex: you have +gcc.exe in your PATH on the PC), do this: + +@strong{Setup Native Remote Testing} + +@example + + ./MkTestDir '' /usr/dejagnu/src/devo + +@end example + +To test the setup, @code{ftp} to your PC +using the username (iusr_foobar) and password you selected. CD +to the test directory. Upload a file to the PC. Now telnet to +your PC using the same username and password. CD to the test +directory. Make sure the file is there. Type "set" and/or "gcc +-v" (or sh-hms-gcc -v) and make sure the default PATH contains +the installation you want to test. + +@strong{Run Test Remotely} + +@example + + cd /usr/local/swamp/testing + make -k -w check RUNTESTFLAGS="--host_board foobar --target_board foobar -v -v" > check.out 2>&1 + +@end example + +To run a specific test, use a command like this (for +this example, you'd run this from the gcc directory that +MkTestDir created): + +@strong{Run a Test Remotely} + +@example + + make check RUNTESTFLAGS="--host_board sloth --target_board sloth -v compile.exp=921202-1.c" + +@end example + +Note: if you are testing a cross-compiler, put in the +correct target board. You'll also have to download more .exp +files and modify them for your local configuration. The -v's +are optional. + +@node Config File Values, , Remote Host Testing, Customizing DejaGnu +@section Config File Values + +DejaGnu uses a named array in Tcl to hold all the info for +each machine. In the case of a canadian cross, this means host +information as well as target information. The named array is +called @code{target_info}, and it has two indices. The +following fields are part of the array. + +@menu +* Command Line Option Variables: Option Variables. +* Personal Config File:: +@end menu + +@node Option Variables, Personal Config File, , Config File Values +@subsection Command Line Option Variables + +In the user editable second section of the @ref{Personal Config File,,Personal Config File}. you can not only override the configuration +variables captured in the first section, but also specify +default values for all on the @code{runtest} +command line options. Save for @code{--debug}, +@code{--help}, and @code{--version}, each +command line option has an associated Tcl variable. Use the +Tcl @code{set} command to specify a new default +value (as for the configuration variables). The following +table describes the correspondence between command line +options and variables you can set in +@file{site.exp}. @ref{Invoking Runtest,,Invoking Runtest}., for +explanations of the command-line options. + + +@strong{Tcl Variables For Command Line Options} + +@multitable @columnfractions 0.333333333333333 0.333333333333333 0.333333333333333 +@item +runtest@tab Tcl@tab optionvariabledescription +@item +--all@tab all_flag@tab display all test results if set +@item +--baud@tab baud@tab set the default baud rate to something other than +9600. +@item +--connect@tab connectmode@tab @code{rlogin}, +@code{telnet}, @code{rsh}, +@code{kermit}, @code{tip}, or +@code{mondfe} +@item +--outdir@tab outdir@tab directory for @file{tool.sum} and +@file{tool.log.} +@item +--objdir@tab objdir@tab directory for pre-compiled binaries +@item +--reboot@tab reboot@tab reboot the target if set to +@i{"1"}; do not reboot if set to +@i{"0"} (the default). +@item +--srcdir@tab srcdir@tab directory of test subdirectories +@item +--strace@tab tracelevel@tab a number: Tcl trace depth +@item +--tool@tab tool@tab name of tool to test; identifies init, test subdir +@item +--verbose@tab verbose@tab verbosity level. As option, use multiple times; as +variable, set a number, 0 or greater. +@item +--target@tab target_triplet@tab The canonical configuration string for the target. +@item +--host@tab host_triplet@tab The canonical configuration string for the host. +@item +--build@tab build_triplet@tab The canonical configuration string for the build +host. +@item +--mail@tab address@tab Email the output log to the specified address. +@end multitable + +@node Personal Config File, , Option Variables, Config File Values +@subsection Personal Config File + +The personal config file is used to customize +@code{runtest's} behaviour for each person. It's +typically used to set the user prefered setting for verbosity, +and any experimental Tcl procedures. My personal +@file{~/.dejagnurc} file looks like: + +@strong{Personal Config File} + +@example + + set all_flag 1 + set RLOGIN /usr/ucb/rlogin + set RSH /usr/local/sbin/ssh + +@end example + +Here I set @code{all_flag} so I see all the test +cases that PASS along with the ones that FAIL. I also set +@code{RLOGIN} to the BSD version. I have +Kerberos installed, and when I rlogin +to a target board, it usually isn't supported. So I use the non +secure version rather than the default that's in my path. I also +set @code{RSH} to the SSH +secure shell, as rsh is mostly used to test unix +machines within a local network here. + +@node Extending DejaGnu, Unit Testing, Customizing DejaGnu, Top +@chapter Extending DejaGnu + +@menu +* Adding A New Testsuite: Adding a new Testsuite. +* Adding A New Tool:: +* Adding A New Target:: +* Adding A New Board:: +* Board Config File Values: Board File Values. +* Writing A Test Case:: +* Debugging A Test Case:: +* Adding A Test Case To A Testsuite_: Adding A Test Case To A Testsuite. +* Hints On Writing A Test Case:: +* Special variables used by test cases_: Test Case Variables. +@end menu + +@node Adding a new Testsuite, Adding A New Tool, , Extending DejaGnu +@section Adding A New Testsuite + +The testsuite for a new tool should always be located in that tools +source directory. DejaGnu require the directory be named +@file{testsuite}. Under this directory, the test cases go +in a subdirectory whose name begins with the tool name. For example, for +a tool named @i{flubber}, each subdirectory containing +testsuites must start with @i{"flubber."}. + +@node Adding A New Tool, Adding A New Target, Adding a new Testsuite, Extending DejaGnu +@section Adding A New Tool + +In general, the best way to learn how to write (code or even prose) +is to read something similar. This principle applies to test cases and +to testsuites. Unfortunately, well-established testsuites have a way +of developing their own conventions: as test writers become more +experienced with DejaGnu and with Tcl, they accumulate more utilities, +and take advantage of more and more features of +Expect and Tcl in +general. + +Inspecting such established testsuites may make the prospect of +creating an entirely new testsuite appear overwhelming. Nevertheless, +it is quite straightforward to get a new testsuite going. + +There is one testsuite that is guaranteed not to grow more +elaborate over time: both it and the tool it tests were created expressly +to illustrate what it takes to get started with DejaGnu. The +@file{example/} directory of the DejaGnu distribution +contains both an interactive tool called @code{calc}, and a +testsuite for it. Reading this testsuite, and experimenting with it, +is a good way to supplement the information in this section. (Thanks to +Robert Lupton for creating calc and its testsuite---and also the first +version of this section of the manual!) + +To help orient you further in this task, here is an outline of the +steps to begin building a testsuite for a program example. + +@itemize @bullet{} + +@item +Create or select a directory to contain your new +collection of tests. Change into that directory (shown here as +@file{testsuite}): + +Create a @file{configure.in} file in this directory, +to control configuration-dependent choices for your tests. So far as +DejaGnu is concerned, the important thing is to set a value for the +variable @code{target_abbrev}; this value is the link to the +init file you will write soon. (For simplicity, we assume the +environment is Unix, and use @i{unix} as the +value.) + +What else is needed in @file{configure.in} depends on +the requirements of your tool, your intended test environments, and which +configure system you use. This example is a minimal configure.in for use +with GNU Autoconf. + +@item +Create @file{Makefile.in} (if you are using +Autoconf), or @file{Makefile.am}(if you are using +Automake), the source file used by configure to build your +@file{Makefile}. If you are using GNU Automake.just add the +keyword @i{dejagnu} to the +@i{AUTOMAKE_OPTIONS} variable in your +@file{Makefile.am} file. This will add all the Makefile +support needed to run DejaGnu, and support the @ref{Make Check,,Make Check}. +target. + +You also need to include two targets important to DejaGnu: +@i{check}, to run the tests, and +@i{site.exp}, to set up the Tcl copies of +configuration-dependent values. This is called the @ref{Local Config File,,Local Config File}. +The check target must run the @code{runtest} program to +execute the tests. + +The @file{site.exp} target should usually set up +(among other things) the $tool variable for the name of your program. If +the local site.exp file is setup correctly, it is possible to execute the +tests by merely typing @code{runtest} on the command +line. + +@strong{Sample Makefile.in Fragment} + +@example + + # Look for a local version of DejaGnu, otherwise use one in the path + RUNTEST = `if test -f $(top_srcdir)/../dejagnu/runtest; then \ + echo $(top_srcdir) ../dejagnu/runtest; \ + else \ + echo runtest; \ + fi` + + # The flags to pass to runtest + RUNTESTFLAGS = + + # Execute the tests + check: site.exp all + $(RUNTEST) $(RUNTESTFLAGS) \ + --tool $@{example@} --srcdir $(srcdir) + + # Make the local config file + site.exp: ./config.status Makefile + @@echo "Making a new config file..." + -@@rm -f ./tmp? + @@touch site.exp + + -@@mv site.exp site.bak + @@echo "## these variables are automatically\ + generated by make ##" > ./tmp0 + @@echo "# Do not edit here. If you wish to\ + override these values" >> ./tmp0 + @@echo "# add them to the last section" >> ./tmp0 + @@echo "set host_os $@{host_os@}" >> ./tmp0 + @@echo "set host_alias $@{host_alias@}" >> ./tmp0 + @@echo "set host_cpu $@{host_cpu@}" >> ./tmp0 + @@echo "set host_vendor $@{host_vendor@}" >> ./tmp0 + @@echo "set target_os $@{target_os@}" >> ./tmp0 + @@echo "set target_alias $@{target_alias@}" >> ./tmp0 + @@echo "set target_cpu $@{target_cpu@}" >> ./tmp0 + @@echo "set target_vendor $@{target_vendor@}" >> ./tmp0 + @@echo "set host_triplet $@{host_canonical@}" >> ./tmp0 + @@echo "set target_triplet $@{target_canonical@}">>./tmp0 + @@echo "set tool binutils" >> ./tmp0 + @@echo "set srcdir $@{srcdir@}" >> ./tmp0 + @@echo "set objdir `pwd`" >> ./tmp0 + @@echo "set $@{examplename@} $@{example@}" >> ./tmp0 + @@echo "## All variables above are generated by\ + configure. Do Not Edit ##" >> ./tmp0 + @@cat ./tmp0 > site.exp + @@sed < site.bak \ + -e '1,/^## All variables above are.*##/ d' \ + >> site.exp + -@@rm -f ./tmp? + + +@end example + +@item +Create a directory (in @file{testsuite}) +called @file{config}. Make a @i{Tool Init +File} in this directory. Its name must start with the +@code{target_abbrev} value, or be named +@file{default.exp} so call it +@file{config/unix.exp} for our Unix based example. This +is the file that contains the target-dependent procedures. +Fortunately, on Unix, most of them do not have to do very much in +order for @code{runtest} to run. + +If the program being tested is not interactive, you can get +away with this minimal @file{unix.exp} to begin +with: + +@strong{Simple Batch Program Tool Init File} + +@example + + + proc foo_exit @{@} @{@} + proc foo_version @{@} @{@} + + +@end example + +If the program being tested is interactive, however, you might +as well define a @i{start} routine and invoke it by +using an init file like this: + +@strong{Simple Interactive Program Tool Init File} + +@example + + + proc foo_exit @{@} @{@} + proc foo_version @{@} @{@} + + proc foo_start @{@} @{ + global $@{examplename@} + spawn $@{examplename@} + expect @{ + -re "" @{@} + @} + @} + + # Start the program running we want to test + foo_start + + +@end example + +@item +Create a directory whose name begins with your tool's +name, to contain tests. For example, if your tool's name is +@i{gcc}, then the directories all need to start with +@i{"gcc."}. + +@item +Create a sample test file. Its name must end with +@file{.exp}. You can use +@file{first-try.exp}. To begin with, just write there a +line of Tcl code to issue a message. + +@strong{Testing A New Tool Config} + +@example + + + send_user "Testing: one, two...\n" + + +@end example + +@item +Back in the @file{testsuite} (top +level) directory, run @code{configure}. Typically you do +this while in the build directory. You may have to specify more of a +path, if a suitable configure is not available in your execution +path. + +@item +e now ready to triumphantly type @code{make +check} or @code{runtest}. You should see +something like this: + +@strong{Example Test Case Run} + +@example + + Test Run By rhl on Fri Jan 29 16:25:44 EST 1993 + + === example tests === + + Running ./example.0/first-try.exp ... + Testing: one, two... + + === example Summary === + + +@end example + +There is no output in the summary, because so far the example +does not call any of the procedures that establish a test +outcome. + +@item +Write some real tests. For an interactive tool, you +should probably write a real exit routine in fairly short order. In +any case, you should also write a real version routine +soon. +@end itemize + +@node Adding A New Target, Adding A New Board, Adding A New Tool, Extending DejaGnu +@section Adding A New Target + +DejaGnu has some additional requirements for target support, beyond +the general-purpose provisions of configure. DejaGnu must actively +communicate with the target, rather than simply generating or managing +code for the target architecture. Therefore, each tool requires an +initialization module for each target. For new targets, you must supply +a few Tcl procedures to adapt DejaGnu to the target. This permits +DejaGnu itself to remain target independent. + +Usually the best way to write a new initialization module is to +edit an existing initialization module; some trial and error will be +required. If necessary, you can use the @@samp@{--debug@} option to see what +is really going on. + +When you code an initialization module, be generous in printing +information controlled by the @code{verbose} +procedure. + +For cross targets, most of the work is in getting the +communications right. Communications code (for several situations +involving IP networks or serial lines) is available in a DejaGnu library +file. + +If you suspect a communication problem, try running the connection +interactively from Expect. (There are three +ways of running Expect as an interactive +interpreter. You can run Expect with no +arguments, and control it completely interactively; or you can use +@code{expect -i} together with other command-line options and +arguments; or you can run the command @code{interpreter} from +any Expect procedure. Use +@code{return} to get back to the calling procedure (if any), +or @code{return -tcl} to make the calling procedure itself +return to its caller; use @code{exi}t or end-of-file to leave +Expect altogether.) Run the program whose name is recorded in +@code{$connectmode}, with the arguments in +@code{$targetname}, to establish a connection. You should at +least be able to get a prompt from any target that is physically +connected. + +@node Adding A New Board, Board File Values, Adding A New Target, Extending DejaGnu +@section Adding A New Board + +Adding a new board consists of creating a new board config +file. Examples are in +@file{dejagnu/baseboards}. Usually to make a new +board file, it's easiest to copy an existing one. It is also +possible to have your file be based on a +@i{baseboard} file with only one or two +changes needed. Typically, this can be as simple as just +changing the linker script. Once the new baseboard file is done, +add it to the @code{boards_DATA} list in the +@file{dejagnu/baseboards/Makefile.am}, and regenerate the +Makefile.in using automake. Then just rebuild and install DejaGnu. You +can test it by: + +There is a crude inheritance scheme going on with board files, so +you can include one board file into another, The two main procedures used +to do this are @code{load_generic_config} and +@code{load_base_board_description}. The generic config file +contains other procedures used for a certain class of target. The +board description file is where the board specfic settings go. Commonly +there are similar target environments with just different +processors. + +@strong{Testing a New Board Config File} + +@example + + make check RUNTESTFLAGS="--target_board=newboardfile". + +@end example + +Here's an example of a board config file. There are +several @i{helper procedures} used in this +example. A helper procedure is one that look for a tool of files +in commonly installed locations. These are mostly used when +testing in the build tree, because the executables to be tested +are in the same tree as the new dejagnu files. The helper +procedures are the ones in square braces +@i{[]}, which is the Tcl execution characters. + +@strong{Example Board Config File} + +@example + + + # Load the generic configuration for this board. This will define a basic + # set of routines needed by the tool to communicate with the board. + load_generic_config "sim" + + # basic-sim.exp is a basic description for the standard Cygnus simulator. + load_base_board_description "basic-sim" + + # The compiler used to build for this board. This has *nothing* to do + # with what compiler is tested if we're testing gcc. + set_board_info compiler "[find_gcc]" + + # We only support newlib on this target. + # However, we include libgloss so we can find the linker scripts. + set_board_info cflags "[newlib_include_flags] [libgloss_include_flags]" + set_board_info ldflags "[newlib_link_flags]" + + # No linker script for this board. + set_board_info ldscript "-Tsim.ld"; + + # The simulator doesn't return exit statuses and we need to indicate this. + set_board_info needs_status_wrapper 1 + + # Can't pass arguments to this target. + set_board_info noargs 1 + + # No signals. + set_board_info gdb,nosignals 1 + + # And it can't call functions. + set_board_info gdb,cannot_call_functions 1 + + +@end example + +@node Board File Values, Writing A Test Case, Adding A New Board, Extending DejaGnu +@section Board Config File Values + +These fields are all in the @code{board_info} These are +all set by using the @code{set_board_info} procedure. The +parameters are the field name, followed by the value to set the field +to. + + +@strong{Common Board Info Fields} + +@multitable @columnfractions 0.333333333333333 0.333333333333333 0.333333333333333 +@item +Field@tab Sample Value@tab Description +@item +compiler@tab "[find_gcc]"@tab The path to the compiler to use. +@item +cflags@tab "-mca"@tab Compilation flags for the compiler. +@item +ldflags@tab "[libgloss_link_flags] [newlib_link_flags]"@tab Linking flags for the compiler. +@item +ldscript@tab "-Wl,-Tidt.ld"@tab The linker script to use when cross compiling. +@item +libs@tab "-lgcc"@tab Any additional libraries to link in. +@item +shell_prompt@tab "cygmon>"@tab The command prompt of the remote shell. +@item +hex_startaddr@tab "0xa0020000"@tab The Starting address as a string. +@item +start_addr@tab 0xa0008000@tab The starting address as a value. +@item +startaddr@tab "a0020000"@tab +@item +exit_statuses_bad@tab 1@tab Whether there is an accurate exit status. +@item +reboot_delay@tab 10@tab The delay between power off and power on. +@item +unreliable@tab 1@tab Whether communication with the board is unreliable. +@item +sim@tab [find_sim]@tab The path to the simulator to use. +@item +objcopy@tab $tempfil@tab The path to the @code{objcopy} program. +@item +support_libs@tab "$@{prefix_dir@}/i386-coff/"@tab Support libraries needed for cross compiling. +@item +addl_link_flags@tab "-N"@tab Additional link flags, rarely used. +@end multitable + +These fields are used by the GCC and GDB tests, and are mostly +only useful to somewhat trying to debug a new board file for one of +these tools. Many of these are used only by a few testcases, and their +purpose is esoteric. These are listed with sample values as a guide to +better guessing if you need to change any of these. + + +@strong{Board Info Fields For GCC & GDB} + +@multitable @columnfractions 0.333333333333333 0.333333333333333 0.333333333333333 +@item +Field@tab Sample Value@tab Description +@item +strip@tab $tempfile@tab Strip the executable of symbols. +@item +gdb_load_offset@tab "0x40050000"@tab +@item +gdb_protocol@tab "remote"@tab The GDB debugging protocol to use. +@item +gdb_sect_offset@tab "0x41000000";@tab +@item +gdb_stub_ldscript@tab "-Wl,-Teva-stub.ld"@tab The linker script to use with a GDB stub. +@item +gdb_init_command@tab "set mipsfpu none"@tab +@item +gdb,cannot_call_functions@tab 1@tab Whether GDB can call functions on the target, +@item +gdb,noargs@tab 1@tab Whether the target can take command line arguments. +@item +gdb,nosignals@tab 1@tab Whether there are signals on the target. +@item +gdb,short_int@tab 1@tab +@item +gdb,start_symbol@tab "_start";@tab The starting symbol in the executable. +@item +gdb,target_sim_options@tab "-sparclite"@tab Special options to pass to the simulator. +@item +gdb,timeout@tab 540@tab Timeout value to use for remote communication. +@item +gdb_init_command@tab "print/x \$fsr = 0x0"@tab +@item +gdb_load_offset@tab "0x12020000"@tab +@item +gdb_opts@tab "--command gdbinit"@tab +@item +gdb_prompt@tab "\\(gdb960\\)"@tab The prompt GDB is using. +@item +gdb_run_command@tab "jump start"@tab +@item +gdb_stub_offset@tab "0x12010000"@tab +@item +use_gdb_stub@tab 1@tab Whether to use a GDB stub. +@item +use_vma_offset@tab 1@tab +@item +wrap_m68k_aout@tab 1@tab +@item +gcc,no_label_values@tab 1@tab +@item +gcc,no_trampolines@tab 1@tab +@item +gcc,no_varargs@tab 1@tab +@item +gcc,stack_size@tab 16384@tab Stack size to use with some GCC testcases. +@item +ieee_multilib_flags@tab "-mieee";@tab +@item +is_simulator@tab 1@tab +@item +needs_status_wrapper@tab 1@tab +@item +no_double@tab 1@tab +@item +no_long_long@tab 1@tab +@item +noargs@tab 1@tab +@item +nullstone,lib@tab "mips-clock.c"@tab +@item +nullstone,ticks_per_sec@tab 3782018@tab +@item +sys_speed_value@tab 200@tab +@item +target_install@tab @{sh-hms@}@tab +@end multitable + +@node Writing A Test Case, Debugging A Test Case, Board File Values, Extending DejaGnu +@section Writing A Test Case + +The easiest way to prepare a new test case is to base it +on an existing one for a similar situation. There are two major +categories of tests: batch or interactive. Batch oriented tests +are usually easier to write. + +The GCC tests are a good example of batch oriented tests. +All GCC tests consist primarily of a call to a single common +procedure, Since all the tests either have no output, or only +have a few warning messages when successfully compiled. Any +non-warning output is a test failure. All the C code needed is +kept in the test directory. The test driver, written in Tcl, +need only get a listing of all the C files in the directory, and +compile them all using a generic procedure. This procedure and a +few others supporting for these tests are kept in the library +module @file{lib/c-torture.exp} in the GCC test +suite. Most tests of this kind use very few +expect features, and are coded almost +purely in Tcl. + +Writing the complete suite of C tests, then, consisted of +these steps: + +@itemize @bullet{} + +@item +Copying all the C code into the test directory. +These tests were based on the C-torture test created by Torbjorn +Granlund (on behalf of the Free Software Foundation) for GCC +development. + +@item +Writing (and debugging) the generic Tcl procedures for +compilation. + +@item +Writing the simple test driver: its main task is to +search the directory (using the Tcl procedure +@i{glob} for filename expansion with wildcards) +and call a Tcl procedure with each filename. It also checks for +a few errors from the testing procedure. +@end itemize + +Testing interactive programs is intrinsically more +complex. Tests for most interactive programs require some trial +and error before they are complete. + +However, some interactive programs can be tested in a +simple fashion reminiscent of batch tests. For example, prior +to the creation of DejaGnu, the GDB distribution already +included a wide-ranging testing procedure. This procedure was +very robust, and had already undergone much more debugging and +error checking than many recent DejaGnu test cases. +Accordingly, the best approach was simply to encapsulate the +existing GDB tests, for reporting purposes. Thereafter, new GDB +tests built up a family of Tcl procedures specialized for GDB +testing. + +@node Debugging A Test Case, Adding A Test Case To A Testsuite, Writing A Test Case, Extending DejaGnu +@section Debugging A Test Case + +These are the kinds of debugging information available +from DejaGnu: + +@itemize @bullet{} + +@item +Output controlled by test scripts themselves, +explicitly allowed for by the test author. This kind of +debugging output appears in the detailed output recorded in the +DejaGnu log file. To do the same for new tests, use the +@code{verbose} procedure (which in turn uses the +variable also called @i{verbose}) to control +how much output to generate. This will make it easier for other +people running the test to debug it if necessary. Whenever +possible, if @i{$verbose} is +@i{0}, there should be no output other than the +output from @i{pass}, +@i{fail}, @i{error}, and +@i{warning}. Then, to whatever extent is +appropriate for the particular test, allow successively higher +values of @i{$verbose} to generate more +information. Be kind to other programmers who use your tests: +provide for a lot of debugging information. + +@item +Output from the internal debugging functions of +Tcl and Expect. There is a command +line options for each; both forms of debugging output are +recorded in the file @file{dbg.log} in the current +directory. + +Use @code{--debug} for information from the +expect level; it generates displays of the expect attempts to +match the tool output with the patterns specified. This output +can be very helpful while developing test scripts, since it +shows precisely the characters received. Iterating between the +latest attempt at a new test script and the corresponding +@file{dbg.log} can allow you to create the final +patterns by ``cut and paste''. This is sometimes the best way +to write a test case. + +@item +Use @code{--strace} to see more +detail at the Tcl level; this shows how Tcl procedure +definitions expand, as they execute. The associated number +controls the depth of definitions expanded. + +@item +Finally, if the value of +@i{verbose} is 3 or greater,DejaGnu turns on +the expect command @code{log_user}. This command +prints all expect actions to the expect standard output, to the +detailed log file, and (if @code{--debug} is on) to +@file{dbg.log}. +@end itemize + +@node Adding A Test Case To A Testsuite, Hints On Writing A Test Case, Debugging A Test Case, Extending DejaGnu +@section Adding A Test Case To A Testsuite. + +There are two slightly different ways to add a test +case. One is to add the test case to an existing directory. The +other is to create a new directory to hold your test. The +existing test directories represent several styles of testing, +all of which are slightly different; examine the directories for +the tool of interest to see which (if any) is most suitable. + +Adding a GCC test can be very simple: just add the C code +to any directory beginning with @file{gcc}. and it +runs on the next + +@example +runtest --tool + gcc +@end example + +@noindent +. + +To add a test to GDB, first add any source code you will +need to the test directory. Then you can either create a new +expect file, or add your test to an existing one (any +file with a @i{.exp} suffix). Creating a new +.exp file is probably a better idea if the test is significantly +different from existing tests. Adding it as a separate file also +makes upgrading easier. If the C code has to be already compiled +before the test will run, then you'll have to add it to the +@file{Makefile.in} file for that test directory, +then run @code{configure} and +@code{make}. + +Adding a test by creating a new directory is very +similar: + +@itemize @bullet{} + +@item +Create the new directory. All subdirectory names +begin with the name of the tool to test; e.g. G++ tests might be +in a directory called @file{g++.other}. There can +be multiple test directories that start with the same tool name +(such as @i{g++}). + +@item +Add the new directory name to the +@code{configdirs} definition in the +@file{configure.in} file for the testsuite +directory. This way when @code{make} and +@code{configure} next run, they include the new +directory. + +@item +Add the new test case to the directory, as +above. + +@item +To add support in the new directory for +configure and make, you must also create a +@file{Makefile.in} and a +@file{configure.in}. +@end itemize + +@node Hints On Writing A Test Case, Test Case Variables, Adding A Test Case To A Testsuite, Extending DejaGnu +@section Hints On Writing A Test Case + +It is safest to write patterns that match all the output +generated by the tested program; this is called closure. +If a pattern does not match the entire output, any output that +remains will be examined by the next @code{expect} +command. In this situation, the precise boundary that determines +which @code{expect} command sees what is very +sensitive to timing between the Expect task and the task running +the tested tool. As a result, the test may sometimes appear to +work, but is likely to have unpredictable results. (This problem +is particularly likely for interactive tools, but can also +affect batch tools---especially for tests that take a long time +to finish.) The best way to ensure closure is to use the +@code{-re} option for the @code{expect} +command to write the pattern as a full regular expressions; then +you can match the end of output using a @i{$}. +It is also a good idea to write patterns that match all +available output by using @i{.*\} after the +text of interest; this will also match any intervening blank +lines. Sometimes an alternative is to match end of line using +@i{\r} or @i{\n}, but this is +usually too dependent on terminal settings. + +Always escape punctuation, such as @i{(} +or @i{"}, in your patterns; for example, write +@i{\(}. If you forget to escape punctuation, +you will usually see an error message like + +@example +extra + characters after close-quote. +@end example + +If you have trouble understanding why a pattern does not +match the program output, try using the @code{--debug} +option to @code{runtest}, and examine the debug log +carefully. + +Be careful not to neglect output generated by setup rather +than by the interesting parts of a test case. For example, +while testing GDB, I issue a send @i{set height +0\n} command. The purpose is simply to make sure GDB +never calls a paging program. The @i{set +height} command in GDB does not generate any +output; but running any command makes GDB issue a new +@i{(gdb) } prompt. If there were no +@code{expect} command to match this prompt, the +output @i{(gdb) } begins the text seen by the +next @code{expect} command---which might make that +pattern fail to match. + +To preserve basic sanity, I also recommended that no test +ever pass if there was any kind of problem in the test case. To +take an extreme case, tests that pass even when the tool will +not spawn are misleading. Ideally, a test in this sort of +situation should not fail either. Instead, print an error +message by calling one of the DejaGnu procedures +@code{error} or @code{warning}. + +@node Test Case Variables, , Hints On Writing A Test Case, Extending DejaGnu +@section Special variables used by test cases. + +There are special variables used by test cases. These contain +other information from DejaGnu. Your test cases can use these variables, +with conventional meanings (as well as the variables saved in +@file{site.exp}. You can use the value of these variables, +but they should never be changed. + +@table @asis + +@item $prms_id +The tracking system (e.g. GNATS) number identifying +a corresponding bugreport. (@i{0}@} if you do not +specify it in the test script.) + +@item $item bug_id +An optional bug id; may reflect a bug +identification from another organization. (@i{0} +if you do not specify it.) + +@item $subdir +The subdirectory for the current test +case. + +@item $expect_out(buffer) +The output from the last command. This is an +internal variable set by Expect. More information can be found in +the Expect manual. + +@item $exec_output +This is the output from a +@code{$@{tool@}_load} command. This only applies to +tools like GCC and GAS which produce an object file that must in +turn be executed to complete a test. + +@item $comp_output +This is the output from a +@code{$@{tool@}_start} command. This is conventionally +used for batch oriented programs, like GCC and GAS, that may +produce interesting output (warnings, errors) without further +interaction. +@end table + +@node Unit Testing, Reference, Extending DejaGnu, Top +@chapter Unit Testing + +@menu +* What Is Unit Testing ?:: +* The dejagnu_h Header File:: +@end menu + +@node What Is Unit Testing ?, The dejagnu_h Header File, , Unit Testing +@section What Is Unit Testing ? + +Most regression testing as done by DejaGnu is system +testing. This is the complete application is tested all at +once. Unit testing is for testing single files, or small +libraries. In this case, each file is linked with a test case in +C or C++, and each function or class and method is tested in +series, with the test case having to check private data or +global variables to see if the function or method worked. + +This works particularly well for testing APIs and at level +where it is easier to debug them, than by needing to trace through +the entire appication. Also if there is a specification for the +API to be tested, the testcase can also function as a compliance +test. + +@node The dejagnu_h Header File, , What Is Unit Testing ?, Unit Testing +@section The dejagnu.h Header File + +DejaGnu uses a single header file to assist in unit +testing. As this file also produces it's one test state output, +it can be run standalone, which is very useful for testing on +embedded systems. This header file has a C and C++ API for the +test states, with simple totals, and standardized +output. Because the output has been standardized, DejaGnu can be +made to work with this test case, without writing almost any +Tcl. The library module, dejagnu.exp, will look for the output +messages, and then merge them into DejaGnu's. + +@node Reference, Unit Testing API, Unit Testing, Top +@chapter Reference + +@menu +* Obtaining DejaGnu:: +* Installation:: +* Builtin Procedures:: +* File Map:: +@end menu + +@node Obtaining DejaGnu, Installation, , Reference +@section Obtaining DejaGnu + +You can obtain DejaGnu from the DejaGnu web site at the +@uref{http://www.gnu.org,Free Software Foundation}, +which is at @uref{http://www.gnu.org/software/dejagnu/,www.gnu.org/software/dejagnu/ } + +@node Installation, Builtin Procedures, Obtaining DejaGnu, Reference +@section Installation + +Once you have the DejaGnu source unpacked and available, you must +first configure the software to specify where it is to run (and the +associated defaults); then you can proceed to installing it. + +@menu +* Configuring DejaGnu:: +* Installing DejaGnu:: +@end menu + +@node Configuring DejaGnu, Installing DejaGnu, , Installation +@subsection Configuring DejaGnu + +It is usually best to configure in a directory separate from the +source tree, specifying where to find the source with the optional +@i{--srcdir} option to +@i{configure}. DejaGnu uses the GNU +@i{autoconf} to configure itself. For more info on using +autoconf, read the GNU autoconf manual. To configure, execute the +@file{configure} program, no other options are +required. For an example, to configure in a seperate tree for objects, +execute the configure script from the source tree like this: + +@example + + ../dejagnu-1.4.5/configure + +@end example + +DejaGnu doesn't care at config time if it's for testing a native +system or a cross system. That is determined at runtime by using the +config files. + +You may also want to use the @code{configure} option +@i{--prefix} to specify where you want DejaGnu and its +supporting code installed. By default, installation is in subdirectories +of @file{/usr/local}, but you can select any alternate +directory @code{altdir} by including +@code{--prefix}@{altdir@}@} on the +@code{configure} command line. (This value is captured in +the Makefile variables @i{prefix} and +@i{exec}prefix@}.) + +Save for a small number of example tests, the DejaGnu distribution +itself does not include any testsuites; these are available +separately. Testsuites for the GNU development tools are included in +those releases. After configuring the top-level DejaGnu directory, unpack +and configure the test directories for the tools you want to test; then, +in each test directory, run @i{make check} to build +auxiliary programs required by some of the tests, and run the test +suites. + +@node Installing DejaGnu, , Configuring DejaGnu, Installation +@subsection Installing DejaGnu + +To install DejaGnu in your filesystem (either in +@file{/usr/local}, or as specified by your +@i{--prefix} option to @i{configure}), +execute. + +@example + + eg$ make install + +@end example + +@i{make install}does thes things for +DejaGnu: + +@itemize @bullet{} + +@item +Look in the path specified for executables +@code{$exec_prefix}) for directories called +@file{lib} and @file{bin}. If these +directories do not exist, @i{make install} creates +them. + +@item +Create another directory in the +@file{share} directory, called +@file{dejagnu}, and copy all the library files into +it. + +@item +Create a directory in the +@file{dejagnu/share} directory, called +@file{config}, and copy all the configuration files into +it. + +@item +Copy the @i{runtest} shell script into +@file{$exec_prefix/bin}. + +@item +Copy @file{runtest.exp} into +@file{$exec_prefix/lib/dejagnu}. This is the main Tcl +code implementing DejaGnu. +@end itemize + +@node Builtin Procedures, File Map, Installation, Reference +@section Builtin Procedures + +DejaGnu provides these Tcl procedures. + +@menu +* Core Internal Procedures:: +* Procedures For Remote Communication:: +* Procedures For Using Utilities to Connect: connprocs. +* Procedures For Target Boards:: +* Target Database Procedures: target database library file. +* Platform Dependant Procedures: platform dependant procedures. +* Utility Procedures:: +* Libgloss; A Free BSP: Libgloss. +* Procedures for debugging your Tcl code_: Debugging Procedures. +@end menu + +@node Core Internal Procedures, Procedures For Remote Communication, , Builtin Procedures +@subsection Core Internal Procedures + +@menu +* Mail_file Procedure: mail_file procedure. +* Open_logs Procedure: open_logs procedure. +* Close_logs Procedure: close_logs procedure. +* Isbuild Procedure: isbuild procedure. +* Is_remote Procedure: is_remote procedure. +* is3way Procedure: is3way procedure. +* Ishost Procedure: ishost procedure. +* Istarget Procedure: istarget procedure. +* Isnative Procedure: isnative procedure. +* Unknown Procedure: unknown procedure. +* Clone_output Procedure: clone_output procedure. +* Reset_vars Procedure: reset_vars procedure. +* Log_and_exit Procedure: log_and_exit procedure. +* Log_summary Procedure: log_summary procedure. +* Cleanup Procedure: cleanup procedure. +* Setup_xfail Procedure: setup_xfail procedure. +* Record_test Procedure: record_test procedure. +* Pass Procedure: pass procedure. +* Fail Procedure: fail procedure. +* Xpass Procedure: xpass procedure. +* Xfail Procedure: xfail procedure. +* Set_warning_threshold Procedure: set_warning_threshold procedure. +* Get_warning_threshold Procedure: get_warning_threshold procedure. +* Warning Procedure: warning procedure. +* Perror Procedure: perror procedure. +* Note Procedure: note procedure. +* Untested Procedure: untested procedure. +* Unresolved Procedure: unresolved procedure. +* Unsupported Procedure: unsupported procedure. +* Init_testcounts Procedure: init_testcounts procedure. +* Incr_count Procedure: incr_count procedure. +* transform Procedure: transform procedure. +* Check_conditional_xfail Procedure: check_conditional_xfail procedure. +* Clear_xfail Procedure: clear_xfail procedure. +* Verbose Procedure: verbose procedure. +* Load_lib Procedure: load_lib procedure. +@end menu + +@node mail_file procedure, open_logs procedure, , Core Internal Procedures +@subsubsection Mail_file Procedure + +@quotation + +@t{@b{mail_file}(@i{file to +subject});} +@end quotation + +@table @asis + +@item @code{} +@end table + +@node open_logs procedure, close_logs procedure, mail_file procedure, Core Internal Procedures +@subsubsection Open_logs Procedure + +@quotation + +@t{@b{open_logs}(@i{});} +@end quotation + +@node close_logs procedure, isbuild procedure, open_logs procedure, Core Internal Procedures +@subsubsection Close_logs Procedure + + +@quotation + +@t{@b{close_logs}(@i{});} +@end quotation + +@node isbuild procedure, is_remote procedure, close_logs procedure, Core Internal Procedures +@subsubsection Isbuild Procedure + +Tests for a particular build host environment. If the +currently configured host matches the argument string, the result is +@i{1}; otherwise the result is +@i{0}. @i{host} must be a full +three-part configure host name; in particular, you may not use the +shorter nicknames supported by configure (but you can use wildcard +characters, using shell syntax, to specify sets of names). If it is +passed a NULL string, then it returns the name of the build canonical +configuration. + +@quotation + +@t{@b{isbuild}(@i{pattern});} +@end quotation + +@table @asis + +@item @code{pattern} +@end table + +@node is_remote procedure, is3way procedure, isbuild procedure, Core Internal Procedures +@subsubsection Is_remote Procedure + + +@quotation + +@t{@b{is_remote}(@i{board});} +@end quotation + +@table @asis + +@item @code{} +@end table + +@node is3way procedure, ishost procedure, is_remote procedure, Core Internal Procedures +@subsubsection is3way Procedure + +Tests for a canadian cross. This is when the tests will be run +on a remotly hosted cross compiler. If it is a canadian cross, then +the result is @i{1}; otherwise the result is +@i{0}. + +@quotation + +@t{@b{is3way}(@i{});} +@end quotation + +@node ishost procedure, istarget procedure, is3way procedure, Core Internal Procedures +@subsubsection Ishost Procedure + +Tests for a particular host environment. If the currently +configured host matches the argument string, the result is +@i{1}; otherwise the result is +@i{0}. @i{host} must be a full +three-part configure host name; in particular, you may not use the +shorter nicknames supported by configure (but you can use wildcard +characters, using shell syntax, to specify sets of names). + +@quotation + +@t{@b{ishost}(@i{pattern});} +@end quotation + +@table @asis + +@item @code{} +@end table + +@node istarget procedure, isnative procedure, ishost procedure, Core Internal Procedures +@subsubsection Istarget Procedure + +Tests for a particular target environment. If the currently +configured target matches the argument string, the result is +@i{1} ; otherwise the result is +@i{0}. target must be a full three-part configure +target name; in particular, you may not use the shorter nicknames +supported by configure (but you can use wildcard characters, using +shell syntax, to specify sets of names). If it is passed a +@i{NULL} string, then it returns the name of the +build canonical configuration. + +@quotation + +@t{@b{istarget}(@i{args});} +@end quotation + +@table @asis + +@item @code{} +@end table + +@node isnative procedure, unknown procedure, istarget procedure, Core Internal Procedures +@subsubsection Isnative Procedure + +Tests whether the current configuration has the same host and +target. When it runs in a native configuration this procedure returns +a @i{1}; otherwise it returns a +@i{0}. + +@quotation + +@t{@b{isnative}(@i{});} +@end quotation + +@node unknown procedure, clone_output procedure, isnative procedure, Core Internal Procedures +@subsubsection Unknown Procedure + + +@quotation + +@t{@b{unknown}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node clone_output procedure, reset_vars procedure, unknown procedure, Core Internal Procedures +@subsubsection Clone_output Procedure + + +@quotation + +@t{@b{clone_output}(@i{message});} +@end quotation + +@table @asis + +@item @code{message} +@end table + +@node reset_vars procedure, log_and_exit procedure, clone_output procedure, Core Internal Procedures +@subsubsection Reset_vars Procedure + + +@quotation + +@t{@b{reset_vars}(@i{});} +@end quotation + +@node log_and_exit procedure, log_summary procedure, reset_vars procedure, Core Internal Procedures +@subsubsection Log_and_exit Procedure + + +@quotation + +@t{@b{log_and_exit}(@i{});} +@end quotation + +@node log_summary procedure, cleanup procedure, log_and_exit procedure, Core Internal Procedures +@subsubsection Log_summary Procedure + + +@quotation + +@t{@b{log_summary}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node cleanup procedure, setup_xfail procedure, log_summary procedure, Core Internal Procedures +@subsubsection Cleanup Procedure + + +@quotation + +@t{@b{cleanup}(@i{});} +@end quotation + +@node setup_xfail procedure, record_test procedure, cleanup procedure, Core Internal Procedures +@subsubsection Setup_xfail Procedure + +Declares that the test is expected to fail on a particular set +of configurations. The config argument must be a list of full +three-part configure target name; in particular, you may not use the +shorter nicknames supported by configure (but you can use the common +shell wildcard characters to specify sets of names). The +@i{bugid} argument is optional, and used only in the +logging file output; use it as a link to a bug-tracking system such +as GNATS. + +Once you use @code{setup_xfail}, the +@code{fail} and @code{pass} procedures +produce the messages @i{XFAIL} and +@i{XPASS} respectively, allowing you to distinguish +expected failures (and unexpected success!) from other test +outcomes. + +@quotation + +@strong{Warning} + +Warning you must clear the expected failure after +using setup_xfail in a test case. Any call to @code{pass +}or @code{fail}l clears the expected failure +implicitly; if the test has some other outcome, e.g. an error, you +can call @code{clear_xfail} to clear the expected +failure explicitly. Otherwise, the expected-failure declaration +applies to whatever test runs next, leading to surprising +results. +@end quotation + +@quotation + +@t{@b{setup_xfail}(@i{config} +@i{bugid});} +@end quotation + +@table @asis + +@item @code{config} +The config triplet to trigger whether this is an +unexpected or expect failure. + +@item @code{bugid} +The optional bugid, used to tie it this test case +to a bug tracking system. +@end table + +@node record_test procedure, pass procedure, setup_xfail procedure, Core Internal Procedures +@subsubsection Record_test Procedure + + +@quotation + +@t{@b{record_test}(@i{type} +@i{message} +@i{args});} +@end quotation + +@table @asis + +@item @code{type} + +@item @code{message} + +@item @code{args} +@end table + +@node pass procedure, fail procedure, record_test procedure, Core Internal Procedures +@subsubsection Pass Procedure + +Declares a test to have passed. @code{pass} +writes in the log files a message beginning with +@i{PASS} (or @i{XPASS}, if failure +was expected), appending the argument +@code{string}. + +@quotation + +@t{@b{pass}(@i{string});} +@end quotation + +@table @asis + +@item @code{string} +The string to use for this PASS +message. +@end table + +@node fail procedure, xpass procedure, pass procedure, Core Internal Procedures +@subsubsection Fail Procedure + +Declares a test to have failed. @code{fail} +writes in the log files a message beginning with +@i{FAIL} (or @i{XFAIL}, if failure +was expected), appending the argument +@code{string}. + +@quotation + +@t{@b{fail}(@i{string});} +@end quotation + +@table @asis + +@item @code{string} +The string to use for this FAIL +message. +@end table + +@node xpass procedure, xfail procedure, fail procedure, Core Internal Procedures +@subsubsection Xpass Procedure + +Declares a test to have unexpectably passed, when it was +expected to be a failure. @code{xpass} +writes in the log files a message beginning with +@i{XPASS} (or @i{XFAIL}, if failure +was expected), appending the argument +@code{string}. + +@quotation + +@t{@b{xpass}(@i{string});} +@end quotation + +@table @asis + +@item @code{string} +The string to use for this output +state. +@end table + +@node xfail procedure, set_warning_threshold procedure, xpass procedure, Core Internal Procedures +@subsubsection Xfail Procedure + +Declares a test to have expectably +failed. @code{xfail} +writes in the log files a message beginning with +@i{XFAIL} (or @i{PASS}, if success +was expected), appending the argument +@code{string}. + +@quotation + +@t{@b{xpass}(@i{string});} +@end quotation + +@table @asis + +@item @code{string} +The string to use for this output +state. +@end table + +@node set_warning_threshold procedure, get_warning_threshold procedure, xfail procedure, Core Internal Procedures +@subsubsection Set_warning_threshold Procedure + +Sets the value of @code{warning_threshold}. A value +of @i{0} disables it: calls to +@code{warning} will not turn a +@i{PASS} or @i{FAIL} into an +@i{UNRESOLVED}. + +@quotation + +@t{@b{set_warning_threshold}(@i{threshold});} +@end quotation + +@table @asis + +@item @code{threshold} +This is the value of the new warning +threshold. +@end table + +@node get_warning_threshold procedure, warning procedure, set_warning_threshold procedure, Core Internal Procedures +@subsubsection Get_warning_threshold Procedure + +Returns the current value of +@code{@{warning_threshold}. The default value is 3. This +value controls how many @code{warning} procedures can +be called before becoming @i{UNRESOLVED}. + +@quotation + +@t{@b{get_warning_threshold}(@i{});} +@end quotation + +@node warning procedure, perror procedure, get_warning_threshold procedure, Core Internal Procedures +@subsubsection Warning Procedure + +Declares detection of a minor error in the test case +itself. @code{warning} writes in the log files a message +beginning with @i{WARNING}, appending the argument +@code{string}. Use @code{warning} rather +than @code{perror} for cases (such as communication +failure to be followed by a retry) where the test case can recover from +the error. If the optional @code{number} is supplied, +then this is used to set the internal count of warnings to that +value. + +As a side effect, @code{warning_threshold} or more +calls to warning in a single test case also changes the effect of the +next @code{pass} or @code{fail} command: +the test outcome becomes @i{UNRESOLVED} since an +automatic @i{PASS} or @i{FAIL} may +not be trustworthy after many warnings. If the optional numeric value +is @i{0}, then there are no further side effects to +calling this function, and the following test outcome doesn't become +@i{UNRESOLVED}. This can be used for errors with no +known side effects. + +@quotation + +@t{@b{warning}(@i{string} +@i{number} +);} +@end quotation + +@table @asis + +@item @code{string} + +@item @code{number} +The optional number to set the error counter. Thius +is only used to fake out the counter when using the +@code{xfail} procedure to control when it flips the +output over to @i{UNRESOLVED} +state. +@end table + +@node perror procedure, note procedure, warning procedure, Core Internal Procedures +@subsubsection Perror Procedure + +Declares a severe error in the testing framework +itself. @code{perror} writes in the log files a message +beginning with @i{ERROR}, appending the argument +@code{string}. + +As a side effect, perror also changes the effect of the next +@code{pass} or @code{fail} command: the +test outcome becomes @i{UNRESOLVED}, since an +automatic @i{PASS} or @i{FAIL} cannot +be trusted after a severe error in the test framework. If the optional +numeric value is @i{0}, then there are no further side +effects to calling this function, and the following test outcome +doesn't become @i{UNRESOLVED}. This can be used for +errors with no known side effects. + +@quotation + +@t{@b{perror}(@i{string} +@i{number} +);} +@end quotation + +@table @asis + +@item @code{string} + +@item @code{number} +The optional number to set the error counter. Thius +is only used to fake out the counter when using the +@code{xfail} procedure to control when it flips the +output over to @i{UNRESOLVED} +state. +@end table + +@node note procedure, untested procedure, perror procedure, Core Internal Procedures +@subsubsection Note Procedure + +Appends an informational message to the log +file. @code{note} writes in the log files a message +beginning with @i{NOTE}, appending the argument +@code{string}. Use @code{note} +sparingly. The @code{verbose} should be used for most +such messages, but in cases where a message is needed in the log file +regardless of the verbosity level use @code{note}. + +@quotation + +@t{@b{note}(@i{string});} +@end quotation + +@table @asis + +@item @code{string} +The string to use for this note. +@end table + +@node untested procedure, unresolved procedure, note procedure, Core Internal Procedures +@subsubsection Untested Procedure + +Declares a test was not run. @code{untested} writes +in the log file a message beginning with @i{UNTESTED}, +appending the argument @i{string}. For example, you +might use this in a dummy test whose only role is to record that a test +does not yet exist for some feature. + +@quotation + +@t{@b{untested}(@i{string});} +@end quotation + +@table @asis + +@item @code{string} +The string to use for this output +state. +@end table + +@node unresolved procedure, unsupported procedure, untested procedure, Core Internal Procedures +@subsubsection Unresolved Procedure + +Declares a test to have an unresolved +outcome. @code{unresolved} writes in the log file a +message beginning with @i{UNRESOLVED}, appending the +argument @i{string}. This usually means the test did +not execute as expected, and a human being must go over results to +determine if it passed or failed (and to improve the test case). + +@quotation + +@t{@b{unresolved}(@i{string});} +@end quotation + +@table @asis + +@item @code{string} +The string to use for this output +state. +@end table + +@node unsupported procedure, init_testcounts procedure, unresolved procedure, Core Internal Procedures +@subsubsection Unsupported Procedure + +Declares that a test case depends on some facility that does not +exist in the testing environment. @code{unsupported} +writes in the log file a message beginning with +@i{UNSUPPORTED}, appending the argument string. + +@quotation + +@t{@b{unsupported}(@i{string});} +@end quotation + +@table @asis + +@item @code{string} +The string to use for this output +state. +@end table + +@node init_testcounts procedure, incr_count procedure, unsupported procedure, Core Internal Procedures +@subsubsection Init_testcounts Procedure + + +@quotation + +@t{@b{init_testcounts}(@i{});} +@end quotation + +@node incr_count procedure, transform procedure, init_testcounts procedure, Core Internal Procedures +@subsubsection Incr_count Procedure + + +@quotation + +@t{@b{incr_count}(@i{name} +@i{args});} +@end quotation + +@table @asis + +@item @code{name} + +@item @code{args} +@end table + +@node transform procedure, check_conditional_xfail procedure, incr_count procedure, Core Internal Procedures +@subsubsection transform Procedure + +Generates a string for the name of a tool as it was configured +and installed, given its native name (as the argument +@code{toolname}). This makes the assumption that all +tools are installed using the same naming conventions: For example, +for a cross compiler supporting the @i{m68k-vxworks} +configuration, the result of transform @code{gcc} is +@code{m68k-vxworks-gcc}. + +@quotation + +@t{@b{transform}(@i{toolname});} +@end quotation + +@table @asis + +@item @code{toolname} +The name of the cross-development program to +transform. +@end table + +@node check_conditional_xfail procedure, clear_xfail procedure, transform procedure, Core Internal Procedures +@subsubsection Check_conditional_xfail Procedure + +This procedure adds a conditional xfail, based on compiler +options used to create a test case executable. If an include options +is found in the compiler flags, and it's the right architecture, +it'll trigger an @i{XFAIL}. Otherwise it'll produce +an ordinary @i{FAIL}. You can also specify flags to +exclude. This makes a result be a @i{FAIL}, even if +the included options are found. To set the conditional, set +the variable @code{compiler_conditional_xfail_data} to the +fields + +@example +"[message string] [targets list] [includes + list] [excludes list]" +@end example + +@noindent +(descriptions below). This is +the checked at pass/fail decision time, so there is no need to call +the procedure yourself, unless you wish to know if it gets +triggered. After a pass/fail, the variable is reset, so it doesn't +effect other tests. It returns @i{1} if the +conditional is true, or @i{0} if the conditional is +false. + +@quotation + +@t{@b{check_conditional_xfail}(@i{message} +@i{targets} +@i{includes} +@i{excludes});} +@end quotation + +@table @asis + +@item @code{message} +This is the message to print with the normal test +result. + +@item @code{targets} +This is a string with the list targets to activate +this conditional on. + +@item @code{includes} +This is a list of sets of options to search for in +the compiler options to activate this conditional. If the list of +sets of options is empty or if any set of the options matches, +then this conditional is true. (It may be useful to specify an +empty list of include sets if the conditional is always true +unless one of the exclude sets matches.) + +@item @code{excludes} +This is a list of sets of options to search for in +the compiler options to activate this conditional. If any set of +the options matches, (regardless of whether any of the include sets +match) then this conditional is de-activated. +@end table + +@strong{Specifying the conditional xfail data} + +@example + + set compiler_conditional_xfail_data @{ \ + "I sure wish I knew why this was hosed" \ + "sparc*-sun*-* *-pc-*-*" \ + @{"-Wall -v" "-O3"@} \ + @{"-O1" "-Map"@} \ + @} + +@end example + +What this does is it matches only for these two targets if +"-Wall -v" or "-O3" is set, but neither "-O1" or "-Map" is set. For +a set to match, the options specified are searched for independantly +of each other, so a "-Wall -v" matches either "-Wall -v" or "-v +-Wall". A space seperates the options in the string. Glob-style +regular expressions are also permitted. + +@node clear_xfail procedure, verbose procedure, check_conditional_xfail procedure, Core Internal Procedures +@subsubsection Clear_xfail Procedure + +Cancel an expected failure (previously declared with +@code{setup_xfail}) for a particular set of +configurations. The @code{config} argument is a list +of configuration target names. It is only necessary to call +@code{clear_xfail} if a test case ends without calling +either @code{pass} or @code{fail}, after +calling @code{setup_xfail}. + +@quotation + +@t{@b{clear_xfail}(@i{config});} +@end quotation + +@table @asis + +@item @code{config} +The configuration triplets to +clear. +@end table + +@node verbose procedure, load_lib procedure, clear_xfail procedure, Core Internal Procedures +@subsubsection Verbose Procedure + +Test cases can use this function to issue helpful messages +depending on the number of @code{--verbose} options on the +runtest command line. It prints string if the value of the variable +@code{verbose} is higher than or equal to the optional +number. The default value for number is @i{1}. Use +the optional @code{-log} argument to cause string to always +be added to the log file, even if it won't be printed. Use the +optional @code{-x} argument to log the test results into +a parsable XML file. Use the optional @code{-n} argument +to print string without a trailing newline. Use the optional +@code{--} argument if string begins with "-". + +@quotation + +@t{@b{verbose}(@i{-log} +@i{-x} +@i{-n} +@i{-r} +@i{string} +@i{number});} +@end quotation + +@table @asis + +@item @code{-x} + +@item @code{-log} + +@item @code{-n} + +@item @code{--} + +@item @code{string} + +@item @code{number} +@end table + +@node load_lib procedure, , verbose procedure, Core Internal Procedures +@subsubsection Load_lib Procedure + +Loads a DejaGnu library file by searching a fixed path built +into DejaGnu. If DejaGnu has been installed, it looks in a path +starting with the installed library directory. If you are running +DejaGnu directly from a source directory, without first running +@code{make install}, this path defaults to the current +directory. In either case, it then looks in the current directory +for a directory called @file{lib}. If there are +duplicate definitions, the last one loaded takes precedence over the +earlier ones. + +@quotation + +@t{@b{load_lib}(@i{filespec});} +@end quotation + +@table @asis + +@item @code{filespec} +The name of the DejaGnu library file to +load. +@end table + +@node Procedures For Remote Communication, connprocs, Core Internal Procedures, Builtin Procedures +@subsection Procedures For Remote Communication + +@file{lib/remote.exp} defines these +functions, for establishing and managing communications. Each +of these procedures tries to establish the connection up to +three times before returning. Warnings (if retries will +continue) or errors (if the attempt is abandoned) report on +communication failures. The result for any of these +procedures is either @i{-1}, when the +connection cannot be established, or the spawn ID returned by +the Expect command +@code{spawn}. + +It use the value of the @code{connect} field +in the @code{target_info} array (was +@code{connectmode} as the type of connection to +make. Current supported connection types are tip, kermit, +telnet, rsh, rlogin, and netdata. If the @code{--reboot} +option was used on the runtest command line, then the target +is rebooted before the connection is made. + +@menu +* Call_remote Procedure: call_remote procedure. +* Check_for_board_status Procedure: check_for_board_status procedure. +* File_on_build Procedure: file_on_build procedure. +* File_on_host Procedure: file_on_host procedure. +* Local_exec Procedure: local_exec procedure. +* Remote_binary Procedure: remote_binary procedure. +* Remote_close Procedure: remote_close procedure. +* Remote_download Procedure: remote_download procedure. +* Remote_exec Procedure: remote_exec procedure. +* Remote_expect Procedure: remote_expect procedure. +* Remote_file Procedure: remote_file procedure. +* Remote_ld Procedure: remote_ld procedure. +* Remote_load Procedure: remote_load procedure. +* Remote_open Procedure: remote_open procedure. +* Remote_pop_conn Procedure: remote_pop_conn procedure. +* Remote_push_conn Procedure: remote_push_conn procedure. +* Remote_raw_binary Procedure: remote_raw_binary procedure. +* Remote_raw_close Procedure: remote_raw_close procedure. +* Remote_raw_file Procedure: remote_raw_file procedure. +* remote_raw_ld Procedure: remote_raw_ld procedure. +* Remote_raw_load Procedure: remote_raw_load procedure. +* Remote_raw_open Procedure: remote_raw_open procedure. +* Remote_raw_send Procedure: remote_raw_send procedure. +* Remote_raw_spawn Procedure: remote_raw_spawn procedure. +* Remote_raw_transmit Procedure: remote_raw_transmit procedure. +* Remote_raw_wait Procedure: remote_raw_wait procedure. +* Remote_reboot Procedure: remote_reboot procedure. +* Remote_send Procedure: remote_send procedure. +* Remote_spawn Procedure: remote_spawn procedure. +* Remote_swap_conn Procedure: remote_swap_conn procedure. +* Remote_transmit Procedure: remote_transmit procedure. +* Remote_upload Procedure: remote_upload procedure. +* Remote_wait Procedure: remote_wait procedure. +* Standard_close Procedure: standard_close procedure. +* Standard_download Procedure: standard_download procedure. +* Standard_exec Procedure: standard_exec procedure. +* Standard_file Procedure: standard_file procedure. +* Standard_load Procedure: standard_load procedure. +* Standard_reboot Procedure: standard_reboot procedure. +* Standard_send Procedure: standard_send procedure. +* Standard_spawn Procedure: standard_spawn procedure. +* Standard_transmit Procedure: standard_transmit procedure. +* Standard_upload Procedure: standard_upload procedure. +* Standard_wait Procedure: standard_wait procedure. +* Unix_clean_filename Procedure: unix_clean_filename procedure. +@end menu + +@node call_remote procedure, check_for_board_status procedure, , Procedures For Remote Communication +@subsubsection Call_remote Procedure + + +@quotation + +@t{@b{call_remote}(@i{type} +@i{proc} +@i{dest} +@i{args});} +@end quotation + +@table @asis + +@item @code{proc} + +@item @code{dest} + +@item @code{args} +@end table + +@node check_for_board_status procedure, file_on_build procedure, call_remote procedure, Procedures For Remote Communication +@subsubsection Check_for_board_status Procedure + + +@quotation + +@t{@b{check_for_board_status}(@i{variable});} +@end quotation + +@table @asis + +@item @code{variable} +@end table + +@node file_on_build procedure, file_on_host procedure, check_for_board_status procedure, Procedures For Remote Communication +@subsubsection File_on_build Procedure + + +@quotation + +@t{@b{file_on_build}(@i{op} +@i{file} +@i{args});} +@end quotation + +@table @asis + +@item @code{op} + +@item @code{file} + +@item @code{args} +@end table + +@node file_on_host procedure, local_exec procedure, file_on_build procedure, Procedures For Remote Communication +@subsubsection File_on_host Procedure + + +@quotation + +@t{@b{file_on_host}(@i{op} +@i{file} +@i{args});} +@end quotation + +@table @asis + +@item @code{op} + +@item @code{file} + +@item @code{args} +@end table + +@node local_exec procedure, remote_binary procedure, file_on_host procedure, Procedures For Remote Communication +@subsubsection Local_exec Procedure + + +@quotation + +@t{@b{local_exec}(@i{commandline} +@i{inp} +@i{outp} +@i{timeout});} +@end quotation + +@table @asis + +@item @code{inp} + +@item @code{outp} + +@item @code{timeout} +@end table + +@node remote_binary procedure, remote_close procedure, local_exec procedure, Procedures For Remote Communication +@subsubsection Remote_binary Procedure + + +@quotation + +@t{@b{remote_binary}(@i{host});} +@end quotation + +@table @asis + +@item @code{host} +@end table + +@node remote_close procedure, remote_download procedure, remote_binary procedure, Procedures For Remote Communication +@subsubsection Remote_close Procedure + + +@quotation + +@t{@b{remote_close}(@i{shellid});} +@end quotation + +@table @asis + +@item @code{shellid} +This is the value returned by a call +to @code{remote_open}. This closes the +connection to the target so resources can be used by +others. This parameter can be left off if the +@code{fileid} field in the +@code{target_info} array is set. +@end table + +@node remote_download procedure, remote_exec procedure, remote_close procedure, Procedures For Remote Communication +@subsubsection Remote_download Procedure + + +@quotation + +@t{@b{remote_download}(@i{dest} +@i{file} +@i{args});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{file} + +@item @code{args} +@end table + +@node remote_exec procedure, remote_expect procedure, remote_download procedure, Procedures For Remote Communication +@subsubsection Remote_exec Procedure + + +@quotation + +@t{@b{remote_exec}(@i{hostname} +@i{program} +@i{args});} +@end quotation + +@table @asis + +@item @code{hostname} + +@item @code{program} + +@item @code{args} +@end table + +@node remote_expect procedure, remote_file procedure, remote_exec procedure, Procedures For Remote Communication +@subsubsection Remote_expect Procedure + + +@quotation + +@t{@b{remote_expect}(@i{board} +@i{timeout} +@i{args});} +@end quotation + +@table @asis + +@item @code{board} + +@item @code{timeout} + +@item @code{args} +@end table + +@node remote_file procedure, remote_ld procedure, remote_expect procedure, Procedures For Remote Communication +@subsubsection Remote_file Procedure + + +@quotation + +@t{@b{remote_file}(@i{dest} +@i{args});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{args} +@end table + +@node remote_ld procedure, remote_load procedure, remote_file procedure, Procedures For Remote Communication +@subsubsection Remote_ld Procedure + + +@quotation + +@t{@b{remote_ld}(@i{dest} +@i{prog});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{prog} +@end table + +@node remote_load procedure, remote_open procedure, remote_ld procedure, Procedures For Remote Communication +@subsubsection Remote_load Procedure + + +@quotation + +@t{@b{remote_load}(@i{dest} +@i{prog} +@i{args});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{prog} + +@item @code{args} +@end table + +@node remote_open procedure, remote_pop_conn procedure, remote_load procedure, Procedures For Remote Communication +@subsubsection Remote_open Procedure + + +@quotation + +@t{@b{remote_open}(@i{type});} +@end quotation + +@table @asis + +@item @code{type} +This is passed @code{host} or +@code{target}. Host or target refers to +whether it is a connection to a remote target, or a +remote host. This opens the connection to the desired +target or host using the default values in the +configuration system. It returns that +@code{spawn_id} of the process that manages +the connection. This value can be used in +Expect or +@code{exp_send} statements, or passed to +other procedures that need the connection process's +id. This also sets the @code{fileid} field in +the @code{target_info} array. +@end table + +@node remote_pop_conn procedure, remote_push_conn procedure, remote_open procedure, Procedures For Remote Communication +@subsubsection Remote_pop_conn Procedure + + +@quotation + +@t{@b{remote_pop_conn}(@i{host});} +@end quotation + +@table @asis + +@item @code{host} +@end table + +@node remote_push_conn procedure, remote_raw_binary procedure, remote_pop_conn procedure, Procedures For Remote Communication +@subsubsection Remote_push_conn Procedure + + +@quotation + +@t{@b{remote_push_conn}(@i{host});} +@end quotation + +@table @asis + +@item @code{host} +@end table + +@node remote_raw_binary procedure, remote_raw_close procedure, remote_push_conn procedure, Procedures For Remote Communication +@subsubsection Remote_raw_binary Procedure + + +@quotation + +@t{@b{remote_raw_binary}(@i{host});} +@end quotation + +@table @asis + +@item @code{host} +@end table + +@node remote_raw_close procedure, remote_raw_file procedure, remote_raw_binary procedure, Procedures For Remote Communication +@subsubsection Remote_raw_close Procedure + + +@quotation + +@t{@b{remote_raw_close}(@i{host});} +@end quotation + +@table @asis + +@item @code{host} +@end table + +@node remote_raw_file procedure, remote_raw_ld procedure, remote_raw_close procedure, Procedures For Remote Communication +@subsubsection Remote_raw_file Procedure + + +@quotation + +@t{@b{remote_raw_file}(@i{dest} +@i{args});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{args} +@end table + +@node remote_raw_ld procedure, remote_raw_load procedure, remote_raw_file procedure, Procedures For Remote Communication +@subsubsection remote_raw_ld Procedure + + +@quotation + +@t{@b{remote_raw_ld}(@i{dest} +@i{prog});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{prog} +@end table + +@node remote_raw_load procedure, remote_raw_open procedure, remote_raw_ld procedure, Procedures For Remote Communication +@subsubsection Remote_raw_load Procedure + + +@quotation + +@t{@b{remote_raw_load}(@i{dest} +@i{prog} +@i{args});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{prog} + +@item @code{args} +@end table + +@node remote_raw_open procedure, remote_raw_send procedure, remote_raw_load procedure, Procedures For Remote Communication +@subsubsection Remote_raw_open Procedure + + +@quotation + +@t{@b{remote_raw_open}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node remote_raw_send procedure, remote_raw_spawn procedure, remote_raw_open procedure, Procedures For Remote Communication +@subsubsection Remote_raw_send Procedure + + +@quotation + +@t{@b{remote_raw_send}(@i{dest} +@i{string});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{string} +@end table + +@node remote_raw_spawn procedure, remote_raw_transmit procedure, remote_raw_send procedure, Procedures For Remote Communication +@subsubsection Remote_raw_spawn Procedure + + +@quotation + +@t{@b{remote_raw_spawn}(@i{dest} +@i{commandline});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{commandline} +@end table + +@node remote_raw_transmit procedure, remote_raw_wait procedure, remote_raw_spawn procedure, Procedures For Remote Communication +@subsubsection Remote_raw_transmit Procedure + + +@quotation + +@t{@b{remote_raw_transmit}(@i{dest} +@i{file});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{file} +@end table + +@node remote_raw_wait procedure, remote_reboot procedure, remote_raw_transmit procedure, Procedures For Remote Communication +@subsubsection Remote_raw_wait Procedure + + +@quotation + +@t{@b{remote_raw_wait}(@i{dest} +@i{timeout});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{timeout} +@end table + +@node remote_reboot procedure, remote_send procedure, remote_raw_wait procedure, Procedures For Remote Communication +@subsubsection Remote_reboot Procedure + + +@quotation + +@t{@b{remote_reboot}(@i{host});} +@end quotation + +@table @asis + +@item @code{host} +@end table + +@node remote_send procedure, remote_spawn procedure, remote_reboot procedure, Procedures For Remote Communication +@subsubsection Remote_send Procedure + + +@quotation + +@t{@b{remote_send}(@i{dest} +@i{string});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{string} +@end table + +@node remote_spawn procedure, remote_swap_conn procedure, remote_send procedure, Procedures For Remote Communication +@subsubsection Remote_spawn Procedure + + +@quotation + +@t{@b{remote_spawn}(@i{dest} +@i{commandline} +@i{args});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{commandline} + +@item @code{args} +@end table + +@node remote_swap_conn procedure, remote_transmit procedure, remote_spawn procedure, Procedures For Remote Communication +@subsubsection Remote_swap_conn Procedure + + +@quotation + +@t{@b{remote_swap_conn}(@i{host});} +@end quotation + +@table @asis + +@item @code{} +@end table + +@node remote_transmit procedure, remote_upload procedure, remote_swap_conn procedure, Procedures For Remote Communication +@subsubsection Remote_transmit Procedure + + +@quotation + +@t{@b{remote_transmit}(@i{dest} +@i{file});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{file} +@end table + +@node remote_upload procedure, remote_wait procedure, remote_transmit procedure, Procedures For Remote Communication +@subsubsection Remote_upload Procedure + + +@quotation + +@t{@b{remote_upload}(@i{dest} +@i{srcfile} +@i{arg});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{srcfile} + +@item @code{arg} +@end table + +@node remote_wait procedure, standard_close procedure, remote_upload procedure, Procedures For Remote Communication +@subsubsection Remote_wait Procedure + + +@quotation + +@t{@b{remote_wait}(@i{dest} +@i{timeout});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{timeout} +@end table + +@node standard_close procedure, standard_download procedure, remote_wait procedure, Procedures For Remote Communication +@subsubsection Standard_close Procedure + +@quotation + +@t{@b{standard_close}(@i{host});} +@end quotation + +@table @asis + +@item @code{host} +@end table + +@node standard_download procedure, standard_exec procedure, standard_close procedure, Procedures For Remote Communication +@subsubsection Standard_download Procedure + + +@quotation + +@t{@b{standard_download}(@i{dest} +@i{file} +@i{destfile});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{file} + +@item @code{destfile} +@end table + +@node standard_exec procedure, standard_file procedure, standard_download procedure, Procedures For Remote Communication +@subsubsection Standard_exec Procedure + + +@quotation + +@t{@b{standard_exec}(@i{hostname} +@i{args});} +@end quotation + +@table @asis + +@item @code{hostname} + +@item @code{args} +@end table + +@node standard_file procedure, standard_load procedure, standard_exec procedure, Procedures For Remote Communication +@subsubsection Standard_file Procedure + + +@quotation + +@t{@b{standard_file}(@i{dest} +@i{op} +@i{args});} +@end quotation + +@table @asis + +@item @code{} +@end table + +@node standard_load procedure, standard_reboot procedure, standard_file procedure, Procedures For Remote Communication +@subsubsection Standard_load Procedure + + +@quotation + +@t{@b{standard_load}(@i{dest} +@i{prog} +@i{args});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{prog} + +@item @code{args} +@end table + +@node standard_reboot procedure, standard_send procedure, standard_load procedure, Procedures For Remote Communication +@subsubsection Standard_reboot Procedure + + +@quotation + +@t{@b{standard_reboot}(@i{host});} +@end quotation + +@table @asis + +@item @code{host} +@end table + +@node standard_send procedure, standard_spawn procedure, standard_reboot procedure, Procedures For Remote Communication +@subsubsection Standard_send Procedure + + +@quotation + +@t{@b{standard_send}(@i{dest} +@i{string});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{string} +@end table + +@node standard_spawn procedure, standard_transmit procedure, standard_send procedure, Procedures For Remote Communication +@subsubsection Standard_spawn Procedure + + +@quotation + +@t{@b{standard_spawn}(@i{dest} +@i{commandline});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{commndline} +@end table + +@node standard_transmit procedure, standard_upload procedure, standard_spawn procedure, Procedures For Remote Communication +@subsubsection Standard_transmit Procedure + + +@quotation + +@t{@b{standard_transmit}(@i{dest} +@i{file});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{file} +@end table + +@node standard_upload procedure, standard_wait procedure, standard_transmit procedure, Procedures For Remote Communication +@subsubsection Standard_upload Procedure + + +@quotation + +@t{@b{standard_upload}(@i{dest srcfile destfile});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{srcfile} + +@item @code{destfile} +@end table + +@node standard_wait procedure, unix_clean_filename procedure, standard_upload procedure, Procedures For Remote Communication +@subsubsection Standard_wait Procedure + + +@quotation + +@t{@b{standard_wait}(@i{dest} +@i{timeout});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{timeout} +@end table + +@node unix_clean_filename procedure, , standard_wait procedure, Procedures For Remote Communication +@subsubsection Unix_clean_filename Procedure + + +@quotation + +@t{@b{unix_clean_filename}(@i{dest} +@i{file});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{file} +@end table + +@node connprocs, Procedures For Target Boards, Procedures For Remote Communication, Builtin Procedures +@subsection Procedures For Using Utilities to Connect + +telnet, rsh, tip, kermit + +@menu +* telnet Procedure: telnet procedure. +* rsh Procedure: rsh procedure. +* Tip Procedure: tip procedure. +* Kermit Procedure: kermit procedure. +* kermit_open Procedure: kermit_open procedure. +* Kermit_command Procedure: kermit_command procedure. +* Kermit_send Procedure: kermit_send procedure. +* Kermit_transmit Procedure: kermit_transmit procedure. +* Telnet_open Procedure: telnet_open procedure. +* Telnet_binary Procedure: telnet_binary procedure. +* Telnet_transmit Procedure: telnet_transmit procedure. +* Tip_open Procedure: tip_open procedure. +* Rlogin_open Procedure: rlogin_open procedure. +* Rlogin_spawn Procedure: rlogin_spawn procedure. +* Rsh_open Procedure: rsh_open procedure. +* Rsh_download Procedure: rsh_download procedure. +* Rsh_upload Procedure: rsh_upload procedure. +* Rsh_exec Procedure: rsh_exec procedure. +* Ftp_open Procedure: ftp_open procedure. +* Ftp_upload Procedure: ftp_upload procedure. +* Ftp_download Procedure: ftp_download procedure. +* Ftp_close Procedure: ftp_close procedure. +* Tip_download Procedure: tip_download procedure. +@end menu + +@node telnet procedure, rsh procedure, , connprocs +@subsubsection telnet Procedure + + +@quotation + +@t{@b{telnet}(@i{hostname} +@i{port});} +@end quotation + +@quotation + +@t{@b{rlogin}(@i{hostname});} +@end quotation + +@node rsh procedure, tip procedure, telnet procedure, connprocs +@subsubsection rsh Procedure + + +@quotation + +@t{@b{rsh}(@i{hostname});} +@end quotation + +@table @asis + +@item @code{hostname} +This refers to the IP address or name +(for example, an entry in +@file{/etc/hosts}) for this target. The +procedure names reflect the Unix utility used to +establish a connection. The optional +@code{port} is used to specify the IP +port number. The value of the +@code{netport} field in the +@code{target_info} array is used. (was +@code{$netport}) This value has two parts, +the hostname and the port number, seperated by a +@i{:}. If host or target is used in +the @code{hostname} field, than the +config array is used for all information. +@end table + +@node tip procedure, kermit procedure, rsh procedure, connprocs +@subsubsection Tip Procedure + + +@quotation + +@t{@b{tip}(@i{port});} +@end quotation + +@table @asis + +@item @code{port} +Connect using the Unix utility +@code{tip}. @code{Port}must +be a name from the tip +configuration file +@file{/etc/remote}. Often, this is called +@code{hardwire}, or something like +@code{ttya}. This file holds all the +configuration data for the serial port. The value of +the @code{serial} field in the +@code{target_info} array is used. (was +@code{$serialport}) If @code{host} +or @code{target} is used in the +@code{port} field, than the config +array is used for all information. the +config array is used for all information. +@end table + +@node kermit procedure, kermit_open procedure, tip procedure, connprocs +@subsubsection Kermit Procedure + + +@quotation + +@t{@b{kermit}(@i{port} +@i{bps});} +@end quotation + +@table @asis + +@item @code{port} +Connect using the program +@code{kermit}. @code{Port} +is the device name, +e.g. @file{/dev/ttyb}. + +@item @code{bps} +@code{bps} is the line +speed to use (in its per second) for the +connection. The value of the @code{serial} +field in the @code{target_info} array is +used. (was @code{$serialport}) If +@code{host} or @code{target} is +used in the @code{port} field, than the +config array is used for all information. the +config array is used for all information. +@end table + +@node kermit_open procedure, kermit_command procedure, kermit procedure, connprocs +@subsubsection kermit_open Procedure + + +@quotation + +@t{@b{kermit_open}(@i{dest} +@i{args});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{args} +@end table + +@node kermit_command procedure, kermit_send procedure, kermit_open procedure, connprocs +@subsubsection Kermit_command Procedure + + +@quotation + +@t{@b{kermit_command}(@i{dest} +@i{args});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{args} +@end table + +@node kermit_send procedure, kermit_transmit procedure, kermit_command procedure, connprocs +@subsubsection Kermit_send Procedure + + +@quotation + +@t{@b{kermit_send}(@i{dest string args});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{string} + +@item @code{args} +@end table + +@node kermit_transmit procedure, telnet_open procedure, kermit_send procedure, connprocs +@subsubsection Kermit_transmit Procedure + + +@quotation + +@t{@b{kermit_transmit}(@i{dest} +@i{file} +@i{args});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{file} + +@item @code{args} +@end table + +@node telnet_open procedure, telnet_binary procedure, kermit_transmit procedure, connprocs +@subsubsection Telnet_open Procedure + + +@quotation + +@t{@b{telnet_open}(@i{hostname} +@i{args});} +@end quotation + +@table @asis + +@item @code{hostname} + +@item @code{args} +@end table + +@node telnet_binary procedure, telnet_transmit procedure, telnet_open procedure, connprocs +@subsubsection Telnet_binary Procedure + + +@quotation + +@t{@b{telnet_binary}(@i{hostname});} +@end quotation + +@table @asis + +@item @code{hostname} +@end table + +@node telnet_transmit procedure, tip_open procedure, telnet_binary procedure, connprocs +@subsubsection Telnet_transmit Procedure + + +@quotation + +@t{@b{telnet_transmit}(@i{dest} +@i{file} +@i{args});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{file} + +@item @code{args} +@end table + +@node tip_open procedure, rlogin_open procedure, telnet_transmit procedure, connprocs +@subsubsection Tip_open Procedure + + +@quotation + +@t{@b{tip_open}(@i{hostname});} +@end quotation + +@table @asis + +@item @code{hostname} +@end table + +@node rlogin_open procedure, rlogin_spawn procedure, tip_open procedure, connprocs +@subsubsection Rlogin_open Procedure + + +@quotation + +@t{@b{rlogin_open}(@i{arg});} +@end quotation + +@table @asis + +@item @code{arg} +@end table + +@node rlogin_spawn procedure, rsh_open procedure, rlogin_open procedure, connprocs +@subsubsection Rlogin_spawn Procedure + + +@quotation + +@t{@b{rlogin_spawn}(@i{dest} +@i{cmdline});} +@end quotation + +@table @asis + +@item @code{dest} + +@item @code{cmdline} +@end table + +@node rsh_open procedure, rsh_download procedure, rlogin_spawn procedure, connprocs +@subsubsection Rsh_open Procedure + + +@quotation + +@t{@b{rsh_open}(@i{hostname});} +@end quotation + +@table @asis + +@item @code{hostname} +@end table + +@node rsh_download procedure, rsh_upload procedure, rsh_open procedure, connprocs +@subsubsection Rsh_download Procedure + + +@quotation + +@t{@b{rsh_download}(@i{desthost} +@i{srcfile} +@i{destfile});} +@end quotation + +@table @asis + +@item @code{desthost} + +@item @code{srcfile} + +@item @code{destfile} +@end table + +@node rsh_upload procedure, rsh_exec procedure, rsh_download procedure, connprocs +@subsubsection Rsh_upload Procedure + + +@quotation + +@t{@b{rsh_upload}(@i{desthost} +@i{srcfile} +@i{destfile});} +@end quotation + +@table @asis + +@item @code{desthost} + +@item @code{srcfile} + +@item @code{destfile} +@end table + +@node rsh_exec procedure, ftp_open procedure, rsh_upload procedure, connprocs +@subsubsection Rsh_exec Procedure + + +@quotation + +@t{@b{rsh_exec}(@i{boardname} +@i{cmd} +@i{args});} +@end quotation + +@table @asis + +@item @code{boardname} + +@item @code{cmd} + +@item @code{args} +@end table + +@node ftp_open procedure, ftp_upload procedure, rsh_exec procedure, connprocs +@subsubsection Ftp_open Procedure + + +@quotation + +@t{@b{ftp_open}(@i{host});} +@end quotation + +@table @asis + +@item @code{host} +@end table + +@node ftp_upload procedure, ftp_download procedure, ftp_open procedure, connprocs +@subsubsection Ftp_upload Procedure + + +@quotation + +@t{@b{ftp_upload}(@i{host} +@i{remotefile} +@i{localfile});} +@end quotation + +@table @asis + +@item @code{host} + +@item @code{remotefile} + +@item @code{localfile} +@end table + +@node ftp_download procedure, ftp_close procedure, ftp_upload procedure, connprocs +@subsubsection Ftp_download Procedure + + +@quotation + +@t{@b{ftp_download}(@i{host} +@i{localfile} +@i{remotefile});} +@end quotation + +@table @asis + +@item @code{host} + +@item @code{localfile} + +@item @code{remotefile} +@end table + +@node ftp_close procedure, tip_download procedure, ftp_download procedure, connprocs +@subsubsection Ftp_close Procedure + + +@quotation + +@t{@b{ftp_close}(@i{host});} +@end quotation + +@table @asis + +@item @code{host} +@end table + +@node tip_download procedure, , ftp_close procedure, connprocs +@subsubsection Tip_download Procedure + + +@quotation + +@t{@b{tip_download}(@i{spawnid} +@i{file});} +@end quotation + +@table @asis + +@item @code{spawnid} +Download @code{file} to the +process @code{spawnid} (the value returned +when the connection was established), using the +@code{~put} command under +tip. Most often used for +single board computers that require downloading +programs in ASCII S-records. Returns +@i{1} if an error occurs, +@i{0} otherwise. + +@item @code{file} +This is the filename to +downlaod. +@end table + +@node Procedures For Target Boards, target database library file, connprocs, Builtin Procedures +@subsection Procedures For Target Boards + + +@menu +* Default_link Procedure: default_link procedure. +* Default_target_assemble Procedure: default_target_assemble procedure. +* default_target_compile Procedure: default_target_compile procedure. +* Pop_config Procedure: pop_config procedure. +* Prune_warnings Procedure: prune_warnings procedure. +* Push_build Procedure: push_build procedure. +* push_config Procedure: push_config procedure. +* Reboot_target Procedure: reboot_target procedure. +* Target_assemble Procedure: target_assemble procedure. +* Target_compile Procedure: target_compile procedure. +@end menu + +@node default_link procedure, default_target_assemble procedure, , Procedures For Target Boards +@subsubsection Default_link Procedure + + +@quotation + +@t{@b{default_link}(@i{board} +@i{objects} +@i{destfile} +@i{flags});} +@end quotation + +@table @asis + +@item @code{board} + +@item @code{objects} + +@item @code{destfile} + +@item @code{flags} +@end table + +@node default_target_assemble procedure, default_target_compile procedure, default_link procedure, Procedures For Target Boards +@subsubsection Default_target_assemble Procedure + + +@quotation + +@t{@b{default_target_assemble}(@i{source} +@i{destfile} +@i{flags});} +@end quotation + +@table @asis + +@item @code{source} + +@item @code{destfile} + +@item @code{flags} +@end table + +@node default_target_compile procedure, pop_config procedure, default_target_assemble procedure, Procedures For Target Boards +@subsubsection default_target_compile Procedure + + +@quotation + +@t{@b{default_target_compile}(@i{source} +@i{destfile} +@i{type} +@i{options});} +@end quotation + +@table @asis + +@item @code{source} + +@item @code{destfile} + +@item @code{type} + +@item @code{options} +@end table + +@node pop_config procedure, prune_warnings procedure, default_target_compile procedure, Procedures For Target Boards +@subsubsection Pop_config Procedure + + +@quotation + +@t{@b{pop_config}(@i{type});} +@end quotation + +@table @asis + +@item @code{type} +@end table + +@node prune_warnings procedure, push_build procedure, pop_config procedure, Procedures For Target Boards +@subsubsection Prune_warnings Procedure + + +@quotation + +@t{@b{prune_warnings}(@i{text});} +@end quotation + +@table @asis + +@item @code{text} +@end table + +@node push_build procedure, push_config procedure, prune_warnings procedure, Procedures For Target Boards +@subsubsection Push_build Procedure + + +@quotation + +@t{@b{push_build}(@i{name});} +@end quotation + +@table @asis + +@item @code{name} +@end table + +@node push_config procedure, reboot_target procedure, push_build procedure, Procedures For Target Boards +@subsubsection push_config Procedure + + +@quotation + +@t{@b{push_config}(@i{type} +@i{name});} +@end quotation + +@table @asis + +@item @code{type} + +@item @code{name} +@end table + +@node reboot_target procedure, target_assemble procedure, push_config procedure, Procedures For Target Boards +@subsubsection Reboot_target Procedure + + +@quotation + +@t{@b{reboot_target}(@i{});} +@end quotation + +@node target_assemble procedure, target_compile procedure, reboot_target procedure, Procedures For Target Boards +@subsubsection Target_assemble Procedure + + +@quotation + +@t{@b{target_assemble}(@i{source destfile flags});} +@end quotation + +@table @asis + +@item @code{source} + +@item @code{destfile} + +@item @code{flags} +@end table + +@node target_compile procedure, , target_assemble procedure, Procedures For Target Boards +@subsubsection Target_compile Procedure + + +@quotation + +@t{@b{target_compile}(@i{source} +@i{destfile} +@i{type} +@i{options});} +@end quotation + +@table @asis + +@item @code{source} + +@item @code{destfile} + +@item @code{type} + +@item @code{options} +@end table + +@node target database library file, platform dependant procedures, Procedures For Target Boards, Builtin Procedures +@subsection Target Database Procedures + +@menu +* Board_info Procedure: board_info procedure. +* Host_info Procedure: host_info procedure. +* Set_board_info Procedure: set_board_info procedure. +* Set_currtarget_info Procedure: set_currtarget_info procedure. +* Target_info Procedure: target_info procedure. +* Unset_board_info Procedure: unset_board_info procedure. +* Unset_currtarget_info Procedure: unset_currtarget_info procedure. +* Push_target Procedure: push_target procedure. +* Pop_target Procedure: poptarget procedure. +* List_targets Procedure: list_targets procedure. +* Push_host Procedure: push_host procedure. +* Pop_host Procedure: pop_host procedure. +* Compile Procedure: compile procedure. +* Archive Procedure: archive procedure. +* Ranlib Procedure: ranlib procedure. +* Execute_anywhere Procedure: execute_anywhere procedure. +@end menu + +@node board_info procedure, host_info procedure, , target database library file +@subsubsection Board_info Procedure + + +@quotation + +@t{@b{board_info}(@i{machine} +@i{op} +@i{args});} +@end quotation + +@table @asis + +@item @code{machine} + +@item @code{op} + +@item @code{args} +@end table + +@node host_info procedure, set_board_info procedure, board_info procedure, target database library file +@subsubsection Host_info Procedure + + +@quotation + +@t{@b{host_info}(@i{op} +@i{args});} +@end quotation + +@table @asis + +@item @code{op} + +@item @code{args} +@end table + +@node set_board_info procedure, set_currtarget_info procedure, host_info procedure, target database library file +@subsubsection Set_board_info Procedure + + +@quotation + +@t{@b{set_board_info}(@i{entry} +@i{value});} +@end quotation + +@table @asis + +@item @code{entry} + +@item @code{value} +@end table + +@node set_currtarget_info procedure, target_info procedure, set_board_info procedure, target database library file +@subsubsection Set_currtarget_info Procedure + + +@quotation + +@t{@b{set_currtarget_info}(@i{entry} +@i{value});} +@end quotation + +@table @asis + +@item @code{entry} + +@item @code{value} +@end table + +@node target_info procedure, unset_board_info procedure, set_currtarget_info procedure, target database library file +@subsubsection Target_info Procedure + + +@quotation + +@t{@b{target_info}(@i{op} +@i{args});} +@end quotation + +@table @asis + +@item @code{op} + +@item @code{args} +@end table + +@node unset_board_info procedure, unset_currtarget_info procedure, target_info procedure, target database library file +@subsubsection Unset_board_info Procedure + + +@quotation + +@t{@b{unset_board_info}(@i{entry});} +@end quotation + +@table @asis + +@item @code{entry} +@end table + +@node unset_currtarget_info procedure, push_target procedure, unset_board_info procedure, target database library file +@subsubsection Unset_currtarget_info Procedure + + +@quotation + +@t{@b{unset_currtarget_info}(@i{entry});} +@end quotation + +@table @asis + +@item @code{entry} +@end table + +@node push_target procedure, poptarget procedure, unset_currtarget_info procedure, target database library file +@subsubsection Push_target Procedure + +This makes the target named @i{name} be the +current target connection. The value of @i{name} is +an index into the @code{target_info} array and is set in +the global config file. + +@quotation + +@t{@b{push_target}(@i{name});} +@end quotation + +@table @asis + +@item @code{name} +The name of the target to make current +connection. +@end table + +@node poptarget procedure, list_targets procedure, push_target procedure, target database library file +@subsubsection Pop_target Procedure + +This unsets the current target connection. + +@quotation + +@t{@b{pop_target}(@i{});} +@end quotation + +@node list_targets procedure, push_host procedure, poptarget procedure, target database library file +@subsubsection List_targets Procedure + +This lists all the supported targets for this +architecture. + +@quotation + +@t{@b{list_targets}(@i{});} +@end quotation + +@node push_host procedure, pop_host procedure, list_targets procedure, target database library file +@subsubsection Push_host Procedure + +This makes the host named @i{name} be the +current remote host connection. The value of +@i{name} is an index into the +@code{target_info} array and is set in the global config +file. + +@quotation + +@t{@b{push_host}(@i{name});} +@end quotation + +@table @asis + +@item @code{name} +@end table + +@node pop_host procedure, compile procedure, push_host procedure, target database library file +@subsubsection Pop_host Procedure + +This unsets the current host connection. + +@quotation + +@t{@b{pop_host}(@i{});} +@end quotation + +@node compile procedure, archive procedure, pop_host procedure, target database library file +@subsubsection Compile Procedure + +This invokes the compiler as set by CC to compile the +file @file{file}. The default options for many cross +compilation targets are @i{guessed} by DejaGnu, and +these options can be added to by passing in more parameters as +arguments to @code{compile}. Optionally, this will also +use the value of the @i{cflags} field in the target +config array. If the host is not the same as the build machines, then +then compiler is run on the remote host using +@code{execute_anywhere}. + +@quotation + +@t{@b{compile}(@i{file});} +@end quotation + +@table @asis + +@item @code{file} +@end table + +@node archive procedure, ranlib procedure, compile procedure, target database library file +@subsubsection Archive Procedure + +This produces an archive file. Any parameters passed to +@code{archive} are used in addition to the default +flags. Optionally, this will also use the value of the +@i{arflags} field in the target config array. If the +host is not the same as the build machines, then then archiver is run +on the remote host using @code{execute_anywhere}. + +@quotation + +@t{@b{archive}(@i{file});} +@end quotation + +@table @asis + +@item @code{file} +@end table + +@node ranlib procedure, execute_anywhere procedure, archive procedure, target database library file +@subsubsection Ranlib Procedure + +This generates an index for the archive file for systems that +aren't POSIX yet. Any parameters passed to @code{ranlib} +are used in for the flags. + +@quotation + +@t{@b{ranlib}(@i{file});} +@end quotation + +@table @asis + +@item @code{file} +@end table + +@node execute_anywhere procedure, , ranlib procedure, target database library file +@subsubsection Execute_anywhere Procedure + +This executes the @i{cmdline} on the proper +host. This should be used as a replacement for the Tcl command +@code{exec} as this version utilizes the target config +info to execute this command on the build machine or a remote +host. All config information for the remote host must be setup to +have this command work. If this is a canadian cross, (where we test a +cross compiler that runs on a different host then where DejaGnu is +running) then a connection is made to the remote host and the command +is executed there. It returns either REMOTERROR (for an error) or the +output produced when the command was executed. This is used for +running the tool to be tested, not a test case. + +@quotation + +@t{@b{execute_anywhere}(@i{cmdline});} +@end quotation + +@table @asis + +@item @code{cmdline} +@end table + +@node platform dependant procedures, Utility Procedures, target database library file, Builtin Procedures +@subsection Platform Dependant Procedures + +Each combination of target and tool requires some +target-dependent procedures. The names of these procedures have +a common form: the tool name, followed by an underbar +@i{_}, and finally a suffix describing the +procedure's purpose. For example, a procedure to extract the +version from GDB is called +@code{gdb_version}. + +@code{runtest} itself calls only two of these +procedures, @code{$@{tool@}_exit} and +@code{$@{tool@}_version}; these procedures use no +arguments. + +The other two procedures, @code{$@{tool@}_start} +and @code{$@{tool@}_load}@}, are only called by the test +suites themselves (or by testsuite-specific initialization +code); they may take arguments or not, depending on the +conventions used within each testsuite. + +The usual convention for return codes from any of these +procedures (although it is not required by +@code{runtest}) is to return @i{0} +if the procedure succeeded, @i{1} if it failed, +and @i{-1} if there was a communication error. + +@menu +* $@{tool@}_start Procedure: $@{tool@}_start procedure. +* $@{tool@}_load Procedure: $@{tool@}_load procedure. +* $@{tool@}_exit Procedure: $@{tool@}_exit procedure. +* $@{tool@}_version Procedure: $@{tool@}_version procedure. +@end menu + +@node $@{tool@}_start procedure, $@{tool@}_load procedure, , platform dependant procedures +@subsubsection $@{tool@}_start Procedure + +Starts a particular tool. For an interactive tool, +@code{$@{tool@}_start} starts and initializes the +tool, leaving the tool up and running for the test cases; an +example is @code{gdb_start}, the start function +for GDB. For a batch oriented tool, +@code{$@{tool@}_start} is optional; the recommended +convention is to let @code{$@{tool@}_start} run the +tool, leaving the output in a variable called +@code{comp_output}. Test scripts can then analyze +@code{$comp_output} to determine the test results. +An example of this second kind of start function is +@code{gcc_start}, the start function for GCC. + +DejaGnu itself does not call +@code{$@{tool@}_start}. The initialization +module @code{$@{tool@}_init.exp} must call +@code{$@{tool@}_start} for interactive tools; +for batch-oriented tools, each individual test script calls +@code{$@{tool@}_start} (or makes other +arrangements to run the tool). + +@quotation + +@t{@b{$@{tool@}_start}(@i{});} +@end quotation + +@node $@{tool@}_load procedure, $@{tool@}_exit procedure, $@{tool@}_start procedure, platform dependant procedures +@subsubsection $@{tool@}_load Procedure + +Loads something into a tool. For an interactive tool, +this conditions the tool for a particular test case; for +example, @code{gdb_load} loads a new +executable file into the debugger. For batch oriented tools, +@code{$@{tool@}_load} may do nothing---though, +for example, the GCC support uses +@code{gcc_load} to load and run a binary on +the target environment. Conventionally, +@code{$@{tool@}_load} leaves the output of any +program it runs in a variable called +@code{$exec_output}. Writing +@code{$@{tool@}_load} can be the most complex +part of extending DejaGnu to a new tool or a new target, if +it requires much communication coding or file +downloading. Test scripts call +@code{$@{tool@}_load}. + +@quotation + +@t{@b{$@{tool@}_load}(@i{});} +@end quotation + +@node $@{tool@}_exit procedure, $@{tool@}_version procedure, $@{tool@}_load procedure, platform dependant procedures +@subsubsection $@{tool@}_exit Procedure + +Cleans up (if necessary) before DejaGnu exits. For +interactive tools, this usually ends the interactive +session. You can also use @code{$@{tool@}_exit} +to remove any temporary files left over from the +tests. @code{runtest} calls +@code{$@{tool@}_exit}. + +@quotation + +@t{@b{$@{tool@}_exit}(@i{});} +@end quotation + +@node $@{tool@}_version procedure, , $@{tool@}_exit procedure, platform dependant procedures +@subsubsection $@{tool@}_version Procedure + +Prints the version label and number for +@code{$@{tool@}}. This is called by the DejaGnu +procedure that prints the final summary report. The output +should consist of the full path name used for the tested +tool, and its version number. + +@quotation + +@t{@b{$@{tool@}_version}(@i{});} +@end quotation + +@node Utility Procedures, Libgloss, platform dependant procedures, Builtin Procedures +@subsection Utility Procedures + +@menu +* Getdirs Procedure: getdirs procedure. +* Find Procedure: find procedure. +* Which Procedure: which procedure. +* Grep Procedure: grep procedure. +* Prune Procedure: prune procedure. +* Slay Procedure: slay procedure. +* Absolute Procedure: absolute procedure. +* Psource Procedure: psource procedure. +* Runtest_file_p Procedure: runtest_file_p procedure. +* Diff Procedure: diff procedure. +* Setenv Procedure: setenv procedure. +* unsetenv Procedure: unsetenv procedure. +* Getenv Procedure: getenv procedure. +* Prune_system_crud Procedure: prune_system_crud procedure. +@end menu + +@node getdirs procedure, find procedure, , Utility Procedures +@subsubsection Getdirs Procedure + +Returns a list of all the directories in the single +directory a single directory that match an optional +pattern. + +@quotation + +@t{@b{getdirs}(@i{rootdir} +@i{pattern});} +@end quotation + +@table @asis + +@item @code{args} + +@item @code{pattern} +If you do not specify +@code{pattern}, +@code{Getdirs} assumes a default pattern of +@i{*}. You may use the common shell +wildcard characters in the pattern. If no directories +match the pattern, then a NULL string is +returned +@end table + +@node find procedure, which procedure, getdirs procedure, Utility Procedures +@subsubsection Find Procedure + +Search for files whose names match @i{pattern} +(using shell wildcard characters for filename expansion). Search +subdirectories recursively, starting at +@i{rootdir}. The result is the list of files whose +names match; if no files match, the result is empty. Filenames in the +result include all intervening subdirectory names. If no files match +the pattern, then a NULL string is returned. + +@quotation + +@t{@b{find}(@i{rootdir} +@i{pattern});} +@end quotation + +@table @asis + +@item @code{rootdir} +The top level directory to search the search +from. + +@item @code{pattern} +A csh "glob" style regular expression reprsenting +the files to find. +@end table + +@node which procedure, grep procedure, find procedure, Utility Procedures +@subsubsection Which Procedure + +Searches the execution path for an executable file +@i{binary}, like the the BSD @code{which} +utility. This procedure uses the shell environment variable +@i{PATH}. It returns @i{0} if the +binary is not in the path, or if there is no @i{PATH} +environment variable. If @code{binary} is in the path, it +returns the full path to @code{binary}. + +@quotation + +@t{@b{which}(@i{file});} +@end quotation + +@table @asis + +@item @code{binary} +The executable program or shell script to look +for. +@end table + +@node grep procedure, prune procedure, which procedure, Utility Procedures +@subsubsection Grep Procedure + +Search the file called @file{filename} (a fully +specified path) for lines that contain a match for regular expression +@i{regexp}. The result is a list of all the lines that +match. If no lines match, the result is an empty string. Specify +@i{regexp} using the standard regular expression style +used by the Unix utility program grep. + +Use the optional third argument @i{line} to +start lines in the result with the line number in +@file{filename}. (This argument is simply an option +flag; type it just as shown @code{--line}.) + +@quotation + +@t{@b{grep}(@i{filename} +@i{regexp} +@i{--line});} +@end quotation + +@table @asis + +@item @code{filename} +The file to search. + +@item @code{regexp} +The Unix style regular expression (as used by the +@code{grep} Unix utility) to search +for. + +@item @code{--line} +Prefix the line number to each line where the +regexp matches. +@end table + +@node prune procedure, slay procedure, grep procedure, Utility Procedures +@subsubsection Prune Procedure + +Remove elements of the Tcl list @i{list}. +Elements are fields delimited by spaces. The result is a copy of +list, without any elements that match @i{pattern}. +You can use the common shell wildcard characters to specify the +pattern. + +@quotation + +@t{@b{prune}(@i{list} +@i{pattern});} +@end quotation + +@table @asis + +@item @code{list} +A Tcl list containing the original data. Commonly +this is the output of a batch executed command, like running a +compiler. + +@item @code{pattern} +The csh shell "glob" style pattern to search +for. +@end table + +@node slay procedure, absolute procedure, prune procedure, Utility Procedures +@subsubsection Slay Procedure + +This look in the process table for @i{name} +and send it a unix SIGINT, killing the process. This will only work +under Windows if you have Cygwin or another Unix subsystem for Windows +installed. + +@quotation + +@t{@b{slay}(@i{name});} +@end quotation + +@table @asis + +@item @code{name} +The name of the program to kill. +@end table + +@node absolute procedure, psource procedure, slay procedure, Utility Procedures +@subsubsection Absolute Procedure + +This procedure takes the relative @i{path}, +and converts it to an absolute path. + +@quotation + +@t{@b{absolute}(@i{path});} +@end quotation + +@table @asis + +@item @code{path} +The path to convert. +@end table + +@node psource procedure, runtest_file_p procedure, absolute procedure, Utility Procedures +@subsubsection Psource Procedure + +This sources the file @i{filename}, and traps +all errors. It also ignores all extraneous output. If there was an +error it returns a @i{1}, otherwise it returns a +@i{0}. + +@quotation + +@t{@b{psource}(@i{file});} +@end quotation + +@table @asis + +@item @code{filename} +The filename to Tcl script to +source. +@end table + +@node runtest_file_p procedure, diff procedure, psource procedure, Utility Procedures +@subsubsection Runtest_file_p Procedure + +Search @i{runtest}s for +@i{testcase} and return @i{1} if +found, @i{0} if not. @i{runtests} +is a list of two elements. The first is a copy of what was on +the right side of the @i{=} if + +@example +foo.exp="..." +@end example + +@noindent +" was specified, or +an empty string if no such argument is present. The second is the +pathname of the current testcase under consideration. This is used +by tools like compilers where each testcase is a file. + +@quotation + +@t{@b{runtest_file_p}(@i{runtests} +@i{testcase});} +@end quotation + +@table @asis + +@item @code{runtests} +The list of patterns to compare against. + +@item @code{testcase} +The test case filename. +@end table + +@node diff procedure, setenv procedure, runtest_file_p procedure, Utility Procedures +@subsubsection Diff Procedure + +Compares the two files and returns a @i{1} if +they match, or a @i{0} if they don't. If +@code{verbose} is set, then it'll print the differences to +the screen. + +@quotation + +@t{@b{diff}(@i{file_1} +@i{file_2});} +@end quotation + +@table @asis + +@item @code{file_1} +The first file to compare. + +@item @code{file_2} +The second file to compare. +@end table + +@node setenv procedure, unsetenv procedure, diff procedure, Utility Procedures +@subsubsection Setenv Procedure + +Sets the environment variable @i{var} to the +value @i{val}. + +@quotation + +@t{@b{setenv}(@i{var} +@i{val});} +@end quotation + +@table @asis + +@item @code{var} +The environment variable to set. + +@item @code{val} +The value to set the variable to. +@end table + +@node unsetenv procedure, getenv procedure, setenv procedure, Utility Procedures +@subsubsection unsetenv Procedure + +Unsets the environment variable +@i{var}. + +@quotation + +@t{@b{unsetenv}(@i{var});} +@end quotation + +@table @asis + +@item @code{var} +The environment variable to +unset. +@end table + +@node getenv procedure, prune_system_crud procedure, unsetenv procedure, Utility Procedures +@subsubsection Getenv Procedure + +Returns the value of @i{var} in the +environment if it exists, otherwise it returns NULL. + +@quotation + +@t{@b{getenv}(@i{var});} +@end quotation + +@table @asis + +@item @code{var} +The environment variable to get the value +of. +@end table + +@node prune_system_crud procedure, , getenv procedure, Utility Procedures +@subsubsection Prune_system_crud Procedure + +For system @i{system}, delete text the host or +target operating system might issue that will interfere with pattern +matching of program output in @i{text}. An example +is the message that is printed if a shared library is out of +date. + +@quotation + +@t{@b{prune_system_crud}(@i{system} +@i{test});} +@end quotation + +@table @asis + +@item @code{system} +The system error messages to look for to screen out +. + +@item @code{text} +The Tcl variable containing the +text. +@end table + +@node Libgloss, Debugging Procedures, Utility Procedures, Builtin Procedures +@subsection Libgloss, A Free BSP + +Libgloss is a free @i{BSP} (Board Support +Package) commonly used with GCC and G++ to produce a fully linked +executable image for an embedded systems. + +@menu +* Libgloss_link_flags Procedure: libgloss_link_flags procedure. +* Libgloss_include_flags Procedure: libgloss_include_flags procedure. +* Newlib_link_flags Procedure: newlib_link_flags procedure. +* Newlib_include_flags Procedure: newlib_include_flags procedure. +* Libio_include_flags Procedure: libio_include_flags procedure. +* Libio_link_flags Procedure: libio_link_flags procedure. +* G++_include_flags Procedure: g++_include_flags procedure. +* G++_link_flags Procedure: g++_link_flags procedure. +* Libstdc++_include_flags Procedure: libstdc++_include_flags procedure. +* Libstdc++_link_flags Procedure: libstdc++_link_flags procedure. +* Get_multilibs Procedure: get_multilibs procedure. +* Find_binutils_prog Procedure: find_binutils_prog procedure. +* Find_gcc Procedure: find_gcc procedure. +* Find_gcj Procedure: find_gcj procedure. +* Find_g++ Procedure: find_g++ procedure. +* Find_g77 Procedure: find_g77 procedure. +* Process_multilib_options Procedure: process_multilib_options procedure. +* Add_multilib_option Procedure: add_multilib_option procedure. +* Find_gas Procedure: find_gas procedure. +* Find_ld Procedure: find_ld procedure. +* Build_wrapper Procedure: build_wrapper procedure. +* Winsup_include_flags Procedure: winsup_include_flags procedure. +* Winsup_link_flags Procedure: winsup_link_flags procedure. +@end menu + +@node libgloss_link_flags procedure, libgloss_include_flags procedure, , Libgloss +@subsubsection Libgloss_link_flags Procedure + + +@quotation + +@t{@b{libgloss_link_flags}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node libgloss_include_flags procedure, newlib_link_flags procedure, libgloss_link_flags procedure, Libgloss +@subsubsection Libgloss_include_flags Procedure + + +@quotation + +@t{@b{libgloss_include_flags}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node newlib_link_flags procedure, newlib_include_flags procedure, libgloss_include_flags procedure, Libgloss +@subsubsection Newlib_link_flags Procedure + + +@quotation + +@t{@b{newlib_link_flags}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node newlib_include_flags procedure, libio_include_flags procedure, newlib_link_flags procedure, Libgloss +@subsubsection Newlib_include_flags Procedure + + +@quotation + +@t{@b{newlib_include_flags}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node libio_include_flags procedure, libio_link_flags procedure, newlib_include_flags procedure, Libgloss +@subsubsection Libio_include_flags Procedure + + +@quotation + +@t{@b{libio_include_flags}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node libio_link_flags procedure, g++_include_flags procedure, libio_include_flags procedure, Libgloss +@subsubsection Libio_link_flags Procedure + + +@quotation + +@t{@b{libio_link_flags}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node g++_include_flags procedure, g++_link_flags procedure, libio_link_flags procedure, Libgloss +@subsubsection G++_include_flags Procedure + + +@quotation + +@t{@b{g++_include_flags}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node g++_link_flags procedure, libstdc++_include_flags procedure, g++_include_flags procedure, Libgloss +@subsubsection G++_link_flags Procedure + + +@quotation + +@t{@b{g++_link_flags}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node libstdc++_include_flags procedure, libstdc++_link_flags procedure, g++_link_flags procedure, Libgloss +@subsubsection Libstdc++_include_flags Procedure + + +@quotation + +@t{@b{libstdc++_include_flags}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node libstdc++_link_flags procedure, get_multilibs procedure, libstdc++_include_flags procedure, Libgloss +@subsubsection Libstdc++_link_flags Procedure + + +@quotation + +@t{@b{libstdc++_link_flags}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node get_multilibs procedure, find_binutils_prog procedure, libstdc++_link_flags procedure, Libgloss +@subsubsection Get_multilibs Procedure + + +@quotation + +@t{@b{get_multilibs}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node find_binutils_prog procedure, find_gcc procedure, get_multilibs procedure, Libgloss +@subsubsection Find_binutils_prog Procedure + + +@quotation + +@t{@b{find_binutils_prog}(@i{name});} +@end quotation + +@table @asis + +@item @code{name} +@end table + +@node find_gcc procedure, find_gcj procedure, find_binutils_prog procedure, Libgloss +@subsubsection Find_gcc Procedure + + +@quotation + +@t{@b{find_gcc}(@i{});} +@end quotation + +@node find_gcj procedure, find_g++ procedure, find_gcc procedure, Libgloss +@subsubsection Find_gcj Procedure + + +@quotation + +@t{@b{find_gcj}(@i{});} +@end quotation + +@node find_g++ procedure, find_g77 procedure, find_gcj procedure, Libgloss +@subsubsection Find_g++ Procedure + + +@quotation + +@t{@b{find_g++}(@i{});} +@end quotation + +@node find_g77 procedure, process_multilib_options procedure, find_g++ procedure, Libgloss +@subsubsection Find_g77 Procedure + + +@quotation + +@t{@b{find_g77}(@i{});} +@end quotation + +@node process_multilib_options procedure, add_multilib_option procedure, find_g77 procedure, Libgloss +@subsubsection Process_multilib_options Procedure + + +@quotation + +@t{@b{process_multilib_options}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node add_multilib_option procedure, find_gas procedure, process_multilib_options procedure, Libgloss +@subsubsection Add_multilib_option Procedure + + +@quotation + +@t{@b{add_multilib_option}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node find_gas procedure, find_ld procedure, add_multilib_option procedure, Libgloss +@subsubsection Find_gas Procedure + + +@quotation + +@t{@b{find_gas}(@i{});} +@end quotation + +@node find_ld procedure, build_wrapper procedure, find_gas procedure, Libgloss +@subsubsection Find_ld Procedure + + +@quotation -@example -eg$ make install -@end example +@t{@b{find_ld}(@i{});} +@end quotation -@noindent -@samp{make install} does these things for DejaGnu: +@node build_wrapper procedure, winsup_include_flags procedure, find_ld procedure, Libgloss +@subsubsection Build_wrapper Procedure + + +@quotation + +@t{@b{build_wrapper}(@i{gluefile});} +@end quotation + +@table @asis + +@item @code{gluefile} +@end table + +@node winsup_include_flags procedure, winsup_link_flags procedure, build_wrapper procedure, Libgloss +@subsubsection Winsup_include_flags Procedure + + +@quotation + +@t{@b{winsup_include_flags}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node winsup_link_flags procedure, , winsup_include_flags procedure, Libgloss +@subsubsection Winsup_link_flags Procedure + + +@quotation + +@t{@b{winsup_link_flags}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node Debugging Procedures, , Libgloss, Builtin Procedures +@subsection Procedures for debugging your Tcl code. + +@file{lib/debugger.exp}defines these utility +procedures: + +@menu +* Dumpvars Procedure: dumpvars procedure. +* Dumplocals Procedure: dumplocals procedure. +* Dumprocs Procedure: dumprocs procedure. +* Dumpwatch Procedure: dumpwatch procedure. +* Watcharray Procedure: watcharray procedure. +* Watchvar Procedure: watchvar procedure. +* Watchunset Procedure: watchunset procedure. +* Watchwrite Procedure: watchwrite procedure. +* Watchread Procedure: watchread procedure. +* Watchdel Procedure: watchdel procedure. +* Print Procedure: print procedure. +* Quit Procedure: quit procedure. +@end menu + +@node dumpvars procedure, dumplocals procedure, , Debugging Procedures +@subsubsection Dumpvars Procedure + +This takes a csh style regular expression (glob rules) and prints +the values of the global variable names that match. It is abbreviated +as @i{dv}. + +@quotation + +@t{@b{dumpvars}(@i{vars});} +@end quotation + +@table @asis + +@item @code{vars} +The variables to dump. +@end table + +@node dumplocals procedure, dumprocs procedure, dumpvars procedure, Debugging Procedures +@subsubsection Dumplocals Procedure + +This takes a csh style regular expression (glob rules) and +prints the values of the local variable names that match. It is +abbreviated as @i{dl}. + +@quotation + +@t{@b{dumplocals}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node dumprocs procedure, dumpwatch procedure, dumplocals procedure, Debugging Procedures +@subsubsection Dumprocs Procedure + +This takes a csh style regular expression (glob rules) and +prints the body of all procs that match. It is abbreviated as +@i{dp}. + +@quotation + +@t{@b{dumprocs}(@i{pattern});} +@end quotation + +@table @asis + +@item @code{pattern} +The csh "glob" style pattern to look +for. +@end table + +@node dumpwatch procedure, watcharray procedure, dumprocs procedure, Debugging Procedures +@subsubsection Dumpwatch Procedure + +This takes a csh style regular expression (glob rules) and +prints all the watchpoints. It is abbreviated as +@i{dw}. + +@quotation + +@t{@b{dumpwatch}(@i{pattern});} +@end quotation + +@table @asis + +@item @code{pattern} +The csh "glob" style pattern to look +for. +@end table + +@node watcharray procedure, watchvar procedure, dumpwatch procedure, Debugging Procedures +@subsubsection Watcharray Procedure + + +@quotation + +@t{@b{watcharray}(@i{element} +@i{type});} +@end quotation + +@table @asis + +@item @code{type} +The csh "glob" style pattern to look +for. +@end table + +@node watchvar procedure, watchunset procedure, watcharray procedure, Debugging Procedures +@subsubsection Watchvar Procedure + + +@quotation + +@t{@b{watchvar}(@i{var} +@i{type});} +@end quotation + +@table @asis + +@item @code{} +@end table + +@node watchunset procedure, watchwrite procedure, watchvar procedure, Debugging Procedures +@subsubsection Watchunset Procedure + +This breaks program execution when the variable +@code{var} is unset. It is abbreviated as +@i{wu}. + +@quotation + +@t{@b{watchunset}(@i{arg});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node watchwrite procedure, watchread procedure, watchunset procedure, Debugging Procedures +@subsubsection Watchwrite Procedure + +This breaks program execution when the variable +@code{var} is written. It is abbreviated as +@i{ww}. + +@quotation + +@t{@b{watchwrite}(@i{var});} +@end quotation + +@table @asis + +@item @code{var} +The variable to watch. +@end table + +@node watchread procedure, watchdel procedure, watchwrite procedure, Debugging Procedures +@subsubsection Watchread Procedure + +This breaks program execution when the variable +@code{var} is read. It is abbreviated as +@i{wr}. + +@quotation + +@t{@b{watchread}(@i{var});} +@end quotation + +@table @asis + +@item @code{var} +The variable to watch. +@end table + +@node watchdel procedure, print procedure, watchread procedure, Debugging Procedures +@subsubsection Watchdel Procedure + +This deletes a the watchpoint from the watch list. It is +abbreviated as @i{wd}. + +@quotation + +@t{@b{watchdel}(@i{args});} +@end quotation + +@table @asis + +@item @code{args} +@end table + +@node print procedure, quit procedure, watchdel procedure, Debugging Procedures +@subsubsection Print Procedure + +This prints the value of the variable +@code{var}. It is abbreviated as +@i{p}. + +@quotation + +@t{@b{print}(@i{var});} +@end quotation + +@table @asis + +@item @code{var} +@end table + +@node quit procedure, , print procedure, Debugging Procedures +@subsubsection Quit Procedure + +This makes runtest exit. It is abbreviated as +@i{q}. + +@quotation + +@t{@b{quit}(@i{});} +@end quotation + +@table @asis + +@item @code{} +@end table + +@node File Map, , Builtin Procedures, Reference +@section File Map + +This is a map of the files in DejaGnu. + +@itemize @bullet{} + +@item +runtest + +@item +runtest.exp + +@item +stub-loader.c + +@item +testglue.c + +@item +config + +@item +baseboards + +@item +lib/debugger.exp -@enumerate @item -Look in the path specified for executables (@file{$exec_prefix}) for -directories called @file{lib} and @file{bin}. If these directories do -not exist, @samp{make install} creates them. +lib/dg.exp @item -Create another directory in the @file{lib} directory, called -@file{dejagnu}. +lib/framework.exp @item -Copy the @code{runtest} shell script into @file{$exec_prefix/bin}. +lib/ftp.exp @item -Copy all the library files (used to support the framework) into -@file{$exec_prefix/lib/dejagnu}. +lib/kermit.exp @item -Copy @file{runtest.exp} into @file{$exec_prefix/lib/dejagnu}. This is -the main Tcl code implementing DejaGnu. +lib/libgloss.exp + +@item +lib/mondfe.exp + +@item +lib/remote.exp + +@item +lib/rlogin.exp + +@item +lib/rsh.exp + +@item +lib/standard.exp + +@item +lib/target.exp + +@item +lib/targetdb.exp + +@item +lib/telnet.exp + +@item +lib/tip.exp + +@item +lib/util-defs.exp + +@item +lib/utils.exp + +@item +lib/xsh.exp + +@item +lib/dejagnu.exp +@end itemize + +@node Unit Testing API, , Reference, Top +@chapter Unit Testing API + +@menu +* C Unit Testing API:: +* C++ Unit Testing API:: +@end menu + +@node C Unit Testing API, C++ Unit Testing API, , Unit Testing API +@section C Unit Testing API -@end enumerate +All of the functions that take a +@code{msg} parameter use a C char * that is +the message to be dislayed. There currently is no support for +variable length arguments. -Each test suite collection comes with simple installation instructions -in a @file{README} file; in general, the test suites are designed to be -unpacked in the source directory for the corresponding tool, and extract -into a directory called @file{testsuite}. +@menu +* Pass Function: pass function. +* Fail Function: fail function. +* Untested Function: untested function. +* Unresolved Function: unresolved function. +* Totals Function: totals function. +@end menu + +@node pass function, fail function, , C Unit Testing API +@subsection Pass Function + +This prints a message for a successful test +completion. + +@quotation + +@t{@b{pass}(@i{msg});} +@end quotation + +@node fail function, untested function, pass function, C Unit Testing API +@subsection Fail Function + +This prints a message for an unsuccessful test +completion. + +@quotation + +@t{@b{fail}(@i{msg});} +@end quotation + +@node untested function, unresolved function, fail function, C Unit Testing API +@subsection Untested Function + +This prints a message for an test case that isn't run +for some technical reason. + +@quotation + +@t{@b{untested}(@i{msg});} +@end quotation + +@node unresolved function, totals function, untested function, C Unit Testing API +@subsection Unresolved Function + +This prints a message for an test case that is run, +but there is no clear result. These output states require a +human to look over the results to determine what happened. + +@quotation + +@t{@b{unresolved}(@i{msg});} +@end quotation + +@node totals function, , unresolved function, C Unit Testing API +@subsection Totals Function + +This prints out the total numbers of all the test +state outputs. + +@quotation + +@t{@b{totals}(@i{});} +@end quotation -@node Index -@unnumbered Index +@node C++ Unit Testing API, , C Unit Testing API, Unit Testing API +@section C++ Unit Testing API -@printindex cp +All of the methods that take a +@code{msg} parameter use a C char * +or STL string, that is the message to be +dislayed. There currently is no support for variable +length arguments. -@contents +@menu +* Pass Method: pass method. +* Fail Method: fail method. +* Untested Method: untested method. +* Unresolved Method: unresolved method. +* Totals Method: totals method. +@end menu + +@node pass method, fail method, , C++ Unit Testing API +@subsection Pass Method + +This prints a message for a successful test +completion. + +@quotation + +@t{@b{TestState::pass}(@i{msg});} +@end quotation + +@node fail method, untested method, pass method, C++ Unit Testing API +@subsection Fail Method + +This prints a message for an unsuccessful test +completion. + +@quotation + +@t{@b{TestState::fail}(@i{msg});} +@end quotation + +@node untested method, unresolved method, fail method, C++ Unit Testing API +@subsection Untested Method + +This prints a message for an test case that isn't run +for some technical reason. + +@quotation + +@t{@b{TestState::untested}(@i{msg});} +@end quotation + +@node unresolved method, totals method, untested method, C++ Unit Testing API +@subsection Unresolved Method + +This prints a message for an test case that is run, +but there is no clear result. These output states require a +human to look over the results to determine what happened. + +@quotation + +@t{@b{TestState::unresolved}(@i{msg});} +@end quotation + +@node totals method, , unresolved method, C++ Unit Testing API +@subsection Totals Method + +This prints out the total numbers of all the test +state outputs. + +@quotation + +@t{@b{TestState::totals}(@i{});} +@end quotation @bye diff --git a/doc/C/dejagnu.xml b/doc/dejagnu.xml similarity index 100% rename from doc/C/dejagnu.xml rename to doc/dejagnu.xml diff --git a/doc/C/legal.xml b/doc/legal.xml similarity index 100% rename from doc/C/legal.xml rename to doc/legal.xml diff --git a/doc/C/ref.xml b/doc/ref.xml similarity index 100% rename from doc/C/ref.xml rename to doc/ref.xml diff --git a/doc/C/user.xml b/doc/user.xml similarity index 100% rename from doc/C/user.xml rename to doc/user.xml diff --git a/doc/texinfo.tex b/texinfo.tex similarity index 100% rename from doc/texinfo.tex rename to texinfo.tex