diff options
| author | Rob Savoye <rob@welcomehome.org> | 2001-02-18 05:12:06 +0000 |
|---|---|---|
| committer | Rob Savoye <rob@welcomehome.org> | 2001-02-18 05:12:06 +0000 |
| commit | d1796b46df0f70ddb14b62013d88d2292995c7f1 (patch) | |
| tree | 0db1f064cd71218d42418c64f411bab128ac0d06 /doc | |
| parent | 229fa96029bd352626b934a724c88eba6a1350f7 (diff) | |
| download | dejagnu-d1796b46df0f70ddb14b62013d88d2292995c7f1.zip dejagnu-d1796b46df0f70ddb14b62013d88d2292995c7f1.tar.gz dejagnu-d1796b46df0f70ddb14b62013d88d2292995c7f1.tar.bz2 | |
* Most all files: Update copyright notices.
* Makefile.am: Add support for making RPMs. Force different
values for RUNTEST and RUNTESTFLAGS, so we can test ourselves.
* testsuite/Makefile.am: Force a different value for
RUNTESTFLAGS.
* acinclude.m4, configure.in: Find Tclsh, and Docbook.
* configure: Regenerated.
* doc/Makefile.am: Use $DOCBOOK to find the filters.
* doc/overview: Add the html version of the doc so one doesn't
need docbook to read the manual.
* example/calc/Makefile.am: New automake support.
* example/calc/Makefile.in: Generated.
* example/Makefile.am: Recursion support for make.
* example/calc/Makefile.in: Generated by automake.
* example/calc/calc.h.in: Move constants to calc.c, so we can use
autoheader.
* example/calc/calc.c: Add constants from calc.h.in.
* redhat/dejagnu.spec: New RPM packaging file.
* debian/{changelog,conffiles,control,copyright,postinst,preinst,
rules,site.exp}: New Debian packaging support.
Diffstat (limited to 'doc')
35 files changed, 20241 insertions, 221 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 9521a40..6e367d5 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,10 +1,9 @@ ## Process this file with automake to generate Makefile.in -AUTOMAKE_OPTIONS = cygnus +# AUTOMAKE_OPTIONS = -info_TEXINFOS = dejagnu.texi - -TARGETS = overview.rtf overview.html overview.dvi overview.ps +DOCBOOK = @DOCBOOK@ +TARGETS = overview.html overview.rtf # overview.dvi overview.ps docs: $(TARGETS) @@ -12,13 +11,13 @@ docs: $(TARGETS) dvips -o $@ $< %.pdf: %.sgml - db2pdf $< + $(DOCBOOK)/db2pdf $< %.dvi: %.sgml - db2dvi $< + $(DOCBOOK)/db2dvi $< %.rtf: %.sgml - db2rtf -o $@ $< + $(DOCBOOK)/db2rtf -o $@ $< %.gif: %.fig convert -transparency white $< $@ # .fig -> .gif @@ -30,18 +29,18 @@ docs: $(TARGETS) fig2dev -L ps -m 0.7 -p dummy $< > $@ # .fig -> .eps/portrait %.html: %.sgml - db2html $< + $(DOCBOOK)/db2html $< # now for some extra dependencies that the automatic rules will not # catch: -overview.pdf overview.ps overview.dvi overview.rtf overview.html: overview.sgml ref.sgml user.sgml +html rtf overview.pdf overview.ps overview.dvi overview.rtf overview.html: overview.sgml ref.sgml user.sgml clean: rm -f $(TARGETS) -# install-data-local: overview.pdf overview.html -# $(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/html -# $(INSTALL_DATA) overview/*.html $(DESTDIR)$(pkgdatadir)/html +install-doc: $(TARGETS) + $(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/html + $(INSTALL_DATA) overview/*.html $(DESTDIR)$(pkgdatadir)/html # $(INSTALL_DATA) overview.ps $(DESTDIR)$(pkgdatadir)/dejagnu.ps # $(INSTALL_DATA) overview.pdf $(DESTDIR)$(pkgdatadir)/dejagnu.pdf diff --git a/doc/Makefile.in b/doc/Makefile.in index 31d809b..0666f86 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -10,6 +10,8 @@ # even the implied warranty of MERCHANTABILITY or FITNESS FOR A # PARTICULAR PURPOSE. +# AUTOMAKE_OPTIONS = + SHELL = @SHELL@ @@ -64,149 +66,30 @@ EXEEXT = @EXEEXT@ MAINT = @MAINT@ MAKEINFO = @MAKEINFO@ PACKAGE = @PACKAGE@ +TCLSH = @TCLSH@ VERSION = @VERSION@ +tclsh = @tclsh@ -AUTOMAKE_OPTIONS = cygnus - -info_TEXINFOS = dejagnu.texi - -TARGETS = overview.rtf overview.html overview.dvi overview.ps -mkinstalldirs = $(SHELL) $(top_srcdir)/../mkinstalldirs +DOCBOOK = @DOCBOOK@ +TARGETS = overview.html overview.rtf # overview.dvi overview.ps +mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs CONFIG_CLEAN_FILES = -TEXI2DVI = `if test -f $(top_srcdir)/../texinfo/util/texi2dvi; then echo $(top_srcdir)/../texinfo/util/texi2dvi; else echo texi2dvi; fi` -TEXINFO_TEX = $(top_srcdir)/../texinfo/texinfo.tex -INFO_DEPS = dejagnu.info -DVIS = dejagnu.dvi -TEXINFOS = dejagnu.texi DIST_COMMON = README Makefile.am Makefile.in configure configure.in DISTFILES = $(DIST_COMMON) $(SOURCES) $(HEADERS) $(TEXINFOS) $(EXTRA_DIST) -TAR = gtar +TAR = tar GZIP_ENV = --best all: all-redirect .SUFFIXES: -.SUFFIXES: .dvi .info .ps .texi .texinfo .txi $(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ Makefile.am $(top_srcdir)/configure.in $(ACLOCAL_M4) - cd $(top_srcdir) && $(AUTOMAKE) --cygnus doc/Makefile + cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile -Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status $(BUILT_SOURCES) cd $(top_builddir) \ && CONFIG_FILES=$(subdir)/$@ CONFIG_HEADERS= $(SHELL) ./config.status - -dejagnu.info: dejagnu.texi -dejagnu.dvi: dejagnu.texi - - -DVIPS = dvips - -.texi.info: - @rm -f $@ $@-[0-9] $@-[0-9][0-9] - $(MAKEINFO) -I $(srcdir) $< - -.texi.dvi: - TEXINPUTS=$(top_srcdir)/../texinfo/texinfo.tex:$$TEXINPUTS \ - MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $< - -.texi: - @rm -f $@ $@-[0-9] $@-[0-9][0-9] - $(MAKEINFO) -I $(srcdir) $< - -.texinfo.info: - @rm -f $@ $@-[0-9] $@-[0-9][0-9] - $(MAKEINFO) -I $(srcdir) $< - -.texinfo: - @rm -f $@ $@-[0-9] $@-[0-9][0-9] - $(MAKEINFO) -I $(srcdir) $< - -.texinfo.dvi: - TEXINPUTS=$(top_srcdir)/../texinfo/texinfo.tex:$$TEXINPUTS \ - MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $< - -.txi.info: - @rm -f $@ $@-[0-9] $@-[0-9][0-9] - $(MAKEINFO) -I $(srcdir) $< - -.txi.dvi: - TEXINPUTS=$(top_srcdir)/../texinfo/texinfo.tex:$$TEXINPUTS \ - MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $< - -.txi: - @rm -f $@ $@-[0-9] $@-[0-9][0-9] - $(MAKEINFO) -I $(srcdir) $< -.dvi.ps: - $(DVIPS) $< -o $@ - -install-info-am: $(INFO_DEPS) - @$(NORMAL_INSTALL) - $(mkinstalldirs) $(DESTDIR)$(infodir) - @list='$(INFO_DEPS)'; \ - for file in $$list; do \ - if test -f $$file; then d=.; else d=$(srcdir); fi; \ - for ifile in `cd $$d && echo $$file $$file-[0-9] $$file-[0-9][0-9]`; do \ - if test -f $$d/$$ifile; then \ - echo " $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile"; \ - $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile; \ - else : ; fi; \ - done; \ - done - @$(POST_INSTALL) - @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \ - list='$(INFO_DEPS)'; \ - for file in $$list; do \ - echo " install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file";\ - install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file || :;\ - done; \ - else : ; fi - -uninstall-info: - $(PRE_UNINSTALL) - @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \ - ii=yes; \ - else ii=; fi; \ - list='$(INFO_DEPS)'; \ - for file in $$list; do \ - test -z "$ii" \ - || install-info --info-dir=$(DESTDIR)$(infodir) --remove $$file; \ - done - @$(NORMAL_UNINSTALL) - list='$(INFO_DEPS)'; \ - for file in $$list; do \ - (cd $(DESTDIR)$(infodir) && rm -f $$file $$file-[0-9] $$file-[0-9][0-9]); \ - done - -dist-info: $(INFO_DEPS) - list='$(INFO_DEPS)'; \ - for base in $$list; do \ - if test -f $$base; then d=.; else d=$(srcdir); fi; \ - for file in `cd $$d && eval echo $$base*`; do \ - test -f $(distdir)/$$file \ - || ln $$d/$$file $(distdir)/$$file 2> /dev/null \ - || cp -p $$d/$$file $(distdir)/$$file; \ - done; \ - done - -mostlyclean-aminfo: - -rm -f dejagnu.aux dejagnu.cp dejagnu.cps dejagnu.dvi dejagnu.fn \ - dejagnu.fns dejagnu.ky dejagnu.kys dejagnu.ps dejagnu.log \ - dejagnu.pg dejagnu.toc dejagnu.tp dejagnu.tps dejagnu.vr \ - dejagnu.vrs dejagnu.op dejagnu.tr dejagnu.cv dejagnu.cn - -clean-aminfo: - -distclean-aminfo: - -maintainer-clean-aminfo: - for i in $(INFO_DEPS); do \ - rm -f $$i; \ - if test "`echo $$i-[0-9]*`" != "$$i-[0-9]*"; then \ - rm -f $$i-[0-9]*; \ - fi; \ - done -clean-info: mostlyclean-aminfo tags: TAGS TAGS: @@ -216,27 +99,29 @@ distdir = $(top_builddir)/$(PACKAGE)-$(VERSION)/$(subdir) subdir = doc distdir: $(DISTFILES) + here=`cd $(top_builddir) && pwd`; \ + top_distdir=`cd $(top_distdir) && pwd`; \ + distdir=`cd $(distdir) && pwd`; \ + cd $(top_srcdir) \ + && $(AUTOMAKE) --include-deps --build-dir=$$here --srcdir-name=$(top_srcdir) --output-dir=$$top_distdir --gnu doc/Makefile @for file in $(DISTFILES); do \ - if test -f $$file; then d=.; else d=$(srcdir); fi; \ + d=$(srcdir); \ if test -d $$d/$$file; then \ - cp -pr $$d/$$file $(distdir)/$$file; \ + cp -pr $$/$$file $(distdir)/$$file; \ else \ test -f $(distdir)/$$file \ || ln $$d/$$file $(distdir)/$$file 2> /dev/null \ || cp -p $$d/$$file $(distdir)/$$file || :; \ fi; \ done - $(MAKE) $(AM_MAKEFLAGS) top_distdir="$(top_distdir)" distdir="$(distdir)" dist-info -info-am: $(INFO_DEPS) +info-am: info: info-am -dvi-am: $(DVIS) +dvi-am: dvi: dvi-am -check-am: +check-am: all-am check: check-am installcheck-am: installcheck: installcheck-am -install-info-am: -install-info: install-info-am install-exec-am: install-exec: install-exec-am @@ -264,29 +149,26 @@ distclean-generic: -rm -f config.cache config.log stamp-h stamp-h[0-9]* maintainer-clean-generic: -mostlyclean-am: mostlyclean-aminfo mostlyclean-generic +mostlyclean-am: mostlyclean-generic mostlyclean: mostlyclean-am -clean-am: clean-aminfo clean-generic mostlyclean-am +clean-am: clean-generic mostlyclean-am clean: clean-am -distclean-am: distclean-aminfo distclean-generic clean-am +distclean-am: distclean-generic clean-am distclean: distclean-am -maintainer-clean-am: maintainer-clean-aminfo maintainer-clean-generic \ - distclean-am +maintainer-clean-am: maintainer-clean-generic distclean-am @echo "This command is intended for maintainers to use;" @echo "it deletes files that may require special tools to rebuild." maintainer-clean: maintainer-clean-am -.PHONY: install-info-am uninstall-info mostlyclean-aminfo \ -distclean-aminfo clean-aminfo maintainer-clean-aminfo tags distdir \ -info-am info dvi-am dvi check check-am installcheck-am installcheck \ -install-info-am install-info install-exec-am install-exec \ +.PHONY: tags distdir info-am info dvi-am dvi check check-am \ +installcheck-am installcheck install-exec-am install-exec \ install-data-am install-data install-am install uninstall-am uninstall \ all-redirect all-am all installdirs mostlyclean-generic \ distclean-generic clean-generic maintainer-clean-generic clean \ @@ -299,13 +181,13 @@ docs: $(TARGETS) dvips -o $@ $< %.pdf: %.sgml - db2pdf $< + $(DOCBOOK)/db2pdf $< %.dvi: %.sgml - db2dvi $< + $(DOCBOOK)/db2dvi $< %.rtf: %.sgml - db2rtf -o $@ $< + $(DOCBOOK)/db2rtf -o $@ $< %.gif: %.fig convert -transparency white $< $@ # .fig -> .gif @@ -317,19 +199,19 @@ docs: $(TARGETS) fig2dev -L ps -m 0.7 -p dummy $< > $@ # .fig -> .eps/portrait %.html: %.sgml - db2html $< + $(DOCBOOK)/db2html $< # now for some extra dependencies that the automatic rules will not # catch: -overview.pdf overview.ps overview.dvi overview.rtf overview.html: overview.sgml ref.sgml user.sgml +html rtf overview.pdf overview.ps overview.dvi overview.rtf overview.html: overview.sgml ref.sgml user.sgml clean: rm -f $(TARGETS) -# install-data-local: overview.pdf overview.html -# $(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/html -# $(INSTALL_DATA) overview/*.html $(DESTDIR)$(pkgdatadir)/html +install-doc: $(TARGETS) + $(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/html + $(INSTALL_DATA) overview/*.html $(DESTDIR)$(pkgdatadir)/html # $(INSTALL_DATA) overview.ps $(DESTDIR)$(pkgdatadir)/dejagnu.ps # $(INSTALL_DATA) overview.pdf $(DESTDIR)$(pkgdatadir)/dejagnu.pdf diff --git a/doc/dejagnu.texi b/doc/dejagnu.texi index 68c4008..0d06cea 100644 --- a/doc/dejagnu.texi +++ b/doc/dejagnu.texi @@ -4,7 +4,7 @@ o\input texinfo @c -*- Texinfo -*- @c @c This file documents the GNU Testing Framework ``DejaGnu'' @c -@c Copyright (C) 92, 93, 94, 95, 1996 Free Software Foundation, Inc. +@c Copyright (C) 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software Foundation, Inc. @c @c This text may be freely distributed under the terms of the GNU @c General Public License. @@ -43,7 +43,7 @@ END-INFO-DIR-ENTRY @end tex @vskip 0pt plus 1filll -Copyright @copyright{} 92, 93, 94, 95, 1996 Free Software Foundation, Inc. +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 @@ -60,7 +60,7 @@ into another language, under the above conditions for modified versions. @end titlepage @ifinfo -Copyright @copyright{} 92, 93, 94, 95, 1996 Free Software Foundation, Inc. +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 diff --git a/doc/overview.sgml b/doc/overview.sgml index 58bce0c..4d86d25 100644 --- a/doc/overview.sgml +++ b/doc/overview.sgml @@ -4,18 +4,19 @@ <?Fm: Validation Off> -<!ENTITY version "0.5"> +<!ENTITY version "1.4"> <!ENTITY dj "DejaGnu"> <!ENTITY dejagnu-copyright " - <YEAR>1998</YEAR> + <YEAR>2000</YEAR> <HOLDER>Free Software Foundation, Inc.</HOLDER>"> <!ENTITY dejagnu-code-copyright " %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% This file documents the GNU Testing Framework ``DejaGnu'' -Copyright (C) 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc. +Copyright (C) 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software +Foundation, Inc. This text may be freely distributed under the terms of the GNU General Public License. @@ -23,7 +24,8 @@ General Public License. "> <!ENTITY dejagnu-copyright " -Copyright 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc. +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 @@ -51,7 +53,7 @@ into another language, under the above conditions for modified versions. <bookinfo> <title>&dj;</title> <subtitle>The GNU Testing Framework</subtitle> - <date>1998 Nov 24</date> + <date>2000 Jan 24</date> <edition> &version</edition> <releaseinfo> for circulation within Cygnus</releaseinfo> <authorgroup> @@ -83,8 +85,8 @@ into another language, under the above conditions for modified versions. <!-- </legalnotice> --> <revhistory> <revision> - <revnumber> 0.1</revnumber> - <date>1998-11</date> + <revnumber>0.5</revnumber> + <date>2000-1-24</date> <authorinitials>rob@welcomehome.org</authorinitials> <revremark>Initial version after conversion to DocBook.</revremark> </revision> @@ -226,7 +228,7 @@ into another language, under the above conditions for modified versions. <listitem><para>NT support. There is beta level support for NT that is still a work in progress. This requires the <ulink - URL=httpd://sourceware.cygnus.com>Cygwin</ulink> POSIX system + URL="http://sources.redhat.com">Cygwin</ulink> POSIX system for NT.</para></listitem> </itemizedlist> @@ -235,13 +237,13 @@ into another language, under the above conditions for modified versions. <title>NT Support</title> <para>To use DejaGnu on NT, you need to first install the - <ulink URL="http://sourceware.cygnus.com">Cygwin</ulink> + <ulink URL="http://sources.redhat.com">Cygwin</ulink> release. This works as of the B20.1 release. Cygwin is a POSIX system for NT. This covers both utility programs, and a libray that adds POSIX system calls to NT. Among them is pseudo tty support for NT that emulates the POSIX pty standard. The latest Cygwin is always available from <ulink - URL="http://sourceware.cygnus.com">this location</ulink>. This + URL="http://sources.redhat.com">this location</ulink>. This works well enough to run <emphasis>"make check"</emphasis> of the GNU development tree on NT after a native build. But the nature of pty's on NT is still evolving. Your mileage may @@ -259,16 +261,18 @@ into another language, under the above conditions for modified versions. in many different environments, and we needed a testing tool that:</para> <itemizedlist mark="bullet"> - <listitem><para>is useful to developers while fixing bugs.</para> + <listitem><para>is useful to developers while fixing + bugs.</para></listitem> <listitem><para>automates running many tests during a software - release process.</para> + release process.</para></listitem> <listitem><para>is portable among a variety of host - computers.</para> - <listitem><para>supports cross-development testing.</para> + computers.</para></listitem> + <listitem><para>supports cross-development + testing.</para></listitem> <listitem><para>permits testing interactive programs, like - <command>GDB</command>; and </para> + <command>GDB</command>; and </para></listitem> <listitem><para>permits testing batch oriented programs, like - <command>GCC</command>.</para> + <command>GCC</command>.</para></listitem> </itemizedlist> <para>Some of the requirements proved challenging. For example, @@ -323,7 +327,8 @@ into another language, under the above conditions for modified versions. POSIX conforming systems, and a fifth for a conditional feature. DejaGnu supports the use of all five output messages; in this sense a test suite that uses exactly these messages can be considered POSIX conforming. - These definitions specify the output of a test case:</para> + These definitions specify the output of a test + case:</para> <variablelist> <varlistentry> @@ -374,30 +379,38 @@ into another language, under the above conditions for modified versions. code.</para> <para>Here are some of the ways a test may wind up - <emphasis>UNRESOLVED</emphasis>:</para> + <emphasis>UNRESOLVED</emphasis>:</para></listitem> - <itemizedlist mark=bullet> - <listitem><para>A test's execution is interrupted.</listitem> + </varlistentry> + </variablelist> - <listitem><para>A test does not produce a clear result. This is - usually because there was an <emphasis>ERROR</emphasis> from - DejaGnu while processing the test, or because there were three or - more <emphasis>WARNING</emphasis> messages. Any - <emphasis>WARNING</emphasis> or <emphasis>ERROR</emphasis> messages - can invalidate the output of the test. This usually requires a - human being to examine the output to determine what really - happened---and to improve the test case.</para></listitem> + <itemizedlist mark=bullet> + <listitem><para>A test's execution is + interrupted.</para></listitem> + + <listitem><para>A test does not produce a clear + result. This is usually because there was an + <emphasis>ERROR</emphasis> from DejaGnu while processing + the test, or because there were three or more + <emphasis>WARNING</emphasis> messages. Any + <emphasis>WARNING</emphasis> or <emphasis>ERROR</emphasis> + messages can invalidate the output of the test. This + usually requires a human being to examine the output to + determine what really happened---and to improve the test + case.</para></listitem> <listitem><para>A test depends on a previous test, which fails.</para></listitem> - <listitem><para>The test was set up incorrectly.</para></listitem> + <listitem><para>The test was set up + incorrectly.</para></listitem> </itemizedlist> + <variablelist> <varlistentry> <term>UNTESTED</term> <listitem><para>A test was not run. This is a placeholder, used - when there is no real test case yet.</para> + when there is no real test case yet.</para></listitem> </varlistentry> </variablelist> @@ -414,7 +427,8 @@ into another language, under the above conditions for modified versions. a testing environment (often a ``bare board'' target) lacks basic support for compiling or running the test case. For example, a test for the system subroutine <emphasis>gethostname</emphasis> - would never work on a target board running only a boot monitor. + would never work on a target board running only a boot + monitor.</para></listitem> </varlistentry> </variablelist> @@ -425,7 +439,7 @@ into another language, under the above conditions for modified versions. described in the <emphasis>PASS</emphasis> section above, and you must be careful to return <emphasis>UNRESOLVED</emphasis> where appropriate, as described in the <emphasis>UNRESOLVED</emphasis> section - above.</para> + above.</para> </sect1> </chapter> diff --git a/doc/overview/addboard.html b/doc/overview/addboard.html new file mode 100644 index 0000000..37463c7 --- /dev/null +++ b/doc/overview/addboard.html @@ -0,0 +1,261 @@ +<HTML +><HEAD +><TITLE +>Adding A New Board</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Extending DejaGnu" +HREF="extending.html"><LINK +REL="PREVIOUS" +TITLE="Adding A New Target" +HREF="addtarget.html"><LINK +REL="NEXT" +TITLE="Board Config File Values" +HREF="boarddefs.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="addtarget.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 4. Extending DejaGnu</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="boarddefs.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="ADDBOARD" +>Adding A New Board</A +></H1 +><P +>Adding a new board consists of creating a new board config + file. Examples are in + <TT +CLASS="FILENAME" +>dejagnu/baseboards</TT +>. 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 +CLASS="EMPHASIS" +>baseboard</I +> 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 <SPAN +CLASS="SYMBOL" +>boards_DATA</SPAN +> list in the + <TT +CLASS="FILENAME" +>dejagnu/baseboards/Makefile.am</TT +>, and regenerate the + Makefile.in using automake. Then just rebuild and install DejaGnu. You + can test it by:</P +><P +>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 <TT +CLASS="FUNCTION" +><B +>load_generic_config</B +></TT +> and + <TT +CLASS="FUNCTION" +><B +>load_base_board_description</B +></TT +>. 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.</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 4-6. Testing a New Board Config File</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="SCREEN" +> make check RUNTESTFLAGS="--target_board=<I +CLASS="EMPHASIS" +>newboardfile</I +>". + </PRE +></TD +></TR +></TABLE +></DIV +><P +>Here's an example of a board config file. There are + several <I +CLASS="EMPHASIS" +>helper procedures</I +> 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 +CLASS="EMPHASIS" +>[]</I +>, which is the Tcl execution characters.</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 4-7. Example Board Config File</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> # Load the generic configuration for this board. This will define a basic + # set of routines needed by the tool to communicate with the board. + load_generic_config "sim" + + # basic-sim.exp is a basic description for the standard Cygnus simulator. + load_base_board_description "basic-sim" + + # The compiler used to build for this board. This has *nothing* to do + # with what compiler is tested if we're testing gcc. + set_board_info compiler "[find_gcc]" + + # We only support newlib on this target. + # However, we include libgloss so we can find the linker scripts. + set_board_info cflags "[newlib_include_flags] [libgloss_include_flags]" + set_board_info ldflags "[newlib_link_flags]" + + # No linker script for this board. + set_board_info ldscript "-Tsim.ld"; + + # The simulator doesn't return exit statuses and we need to indicate this. + set_board_info needs_status_wrapper 1 + + # Can't pass arguments to this target. + set_board_info noargs 1 + + # No signals. + set_board_info gdb,nosignals 1 + + # And it can't call functions. + set_board_info gdb,cannot_call_functions 1 + + </PRE +></TD +></TR +></TABLE +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="addtarget.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="boarddefs.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Adding A New Target</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="extending.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Board Config File Values</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/adding.html b/doc/overview/adding.html new file mode 100644 index 0000000..cac339d --- /dev/null +++ b/doc/overview/adding.html @@ -0,0 +1,244 @@ +<HTML +><HEAD +><TITLE +>Adding A Test Case To A Test Suite.</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Extending DejaGnu" +HREF="extending.html"><LINK +REL="PREVIOUS" +TITLE="Debugging A Test Case" +HREF="debugging.html"><LINK +REL="NEXT" +TITLE="Hints On Writing A Test Case" +HREF="hints.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="debugging.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 4. Extending DejaGnu</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="hints.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="ADDING" +>Adding A Test Case To A Test Suite.</A +></H1 +><P +>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.</P +><P +>Adding a GCC test can be very simple: just add the C code + to any directory beginning with <TT +CLASS="FILENAME" +>gcc</TT +>. and it + runs on the next <TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +>runtest --tool + gcc</PRE +></TD +></TR +></TABLE +>.</P +><P +>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 +CLASS="EMPHASIS" +>.exp</I +> 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 + <TT +CLASS="FILENAME" +>Makefile.in</TT +> file for that test directory, + then run <B +CLASS="COMMAND" +>configure</B +> and + <B +CLASS="COMMAND" +>make</B +>.</P +><P +>Adding a test by creating a new directory is very + similar:</P +><P +></P +><UL +><LI +STYLE="list-style-type: disc" +><P +>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 <TT +CLASS="FILENAME" +>g++.other</TT +>. There can + be multiple test directories that start with the same tool name + (such as <I +CLASS="EMPHASIS" +>g++</I +>).</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>Add the new directory name to the + <SPAN +CLASS="SYMBOL" +>configdirs</SPAN +> definition in the + <TT +CLASS="FILENAME" +>configure.in</TT +> file for the test suite + directory. This way when <B +CLASS="COMMAND" +>make</B +> and + <B +CLASS="COMMAND" +>configure</B +> next run, they include the new + directory.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>Add the new test case to the directory, as + above. </P +></LI +><LI +STYLE="list-style-type: disc" +><P +>To add support in the new directory for + configure and make, you must also create a + <TT +CLASS="FILENAME" +>Makefile.in</TT +> and a + <TT +CLASS="FILENAME" +>configure.in</TT +>.</P +></LI +></UL +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="debugging.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="hints.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Debugging A Test Case</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="extending.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Hints On Writing A Test Case</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/addtarget.html b/doc/overview/addtarget.html new file mode 100644 index 0000000..609a6ac --- /dev/null +++ b/doc/overview/addtarget.html @@ -0,0 +1,206 @@ +<HTML +><HEAD +><TITLE +>Adding A New Target</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Extending DejaGnu" +HREF="extending.html"><LINK +REL="PREVIOUS" +TITLE="Adding A New Tool" +HREF="addtool.html"><LINK +REL="NEXT" +TITLE="Adding A New Board" +HREF="addboard.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="addtool.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 4. Extending DejaGnu</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="addboard.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="ADDTARGET" +>Adding A New Target</A +></H1 +><P +>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.</P +><P +>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.</P +><P +>When you code an initialization module, be generous in printing + information controlled by the <TT +CLASS="FUNCTION" +><B +>verbose</B +></TT +> + procedure.</P +><P +>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.</P +><P +>If you suspect a communication problem, try running the connection + interactively from <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +>. (There are three + ways of running <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> as an interactive + interpreter. You can run <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> with no + arguments, and control it completely interactively; or you can use + <B +CLASS="COMMAND" +>expect -i</B +> together with other command-line options and + arguments; or you can run the command <B +CLASS="COMMAND" +>interpreter</B +> from + any <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> procedure. Use + <B +CLASS="COMMAND" +>return</B +> to get back to the calling procedure (if any), + or <B +CLASS="COMMAND" +>return -tcl</B +> to make the calling procedure itself + return to its caller; use <B +CLASS="COMMAND" +>exi</B +>t or end-of-file to leave + Expect altogether.) Run the program whose name is recorded in + <SPAN +CLASS="SYMBOL" +>$connectmode</SPAN +>, with the arguments in + <SPAN +CLASS="SYMBOL" +>$targetname</SPAN +>, to establish a connection. You should at + least be able to get a prompt from any target that is physically + connected.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="addtool.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="addboard.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Adding A New Tool</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="extending.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Adding A New Board</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/addtool.html b/doc/overview/addtool.html new file mode 100644 index 0000000..a5f7330 --- /dev/null +++ b/doc/overview/addtool.html @@ -0,0 +1,577 @@ +<HTML +><HEAD +><TITLE +>Adding A New Tool</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Extending DejaGnu" +HREF="extending.html"><LINK +REL="PREVIOUS" +TITLE="Extending DejaGnu" +HREF="extending.html"><LINK +REL="NEXT" +TITLE="Adding A New Target" +HREF="addtarget.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="extending.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 4. Extending DejaGnu</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="addtarget.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="ADDTOOL" +>Adding A New Tool</A +></H1 +><P +>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 + <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> and <SPAN +CLASS="PRODUCTNAME" +>Tcl</SPAN +> in + general.</P +><P +>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.</P +><P +>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 + <TT +CLASS="FILENAME" +>example/</TT +> directory of the DejaGnu distribution + contains both an interactive tool called <B +CLASS="COMMAND" +>calc</B +>, and a + test suite for it. Reading this test suite, and experimenting with it, + is a good way to supplement the information in this section. (Thanks to + Robert Lupton for creating calc and its test suite---and also the first + version of this section of the manual!)</P +><P +>To help orient you further in this task, here is an outline of the + steps to begin building a test suite for a program example.</P +><P +></P +><UL +><LI +STYLE="list-style-type: disc" +><P +>Create or select a directory to contain your new + collection of tests. Change into that directory (shown here as + <TT +CLASS="FILENAME" +>testsuite</TT +>):</P +><P +>Create a <TT +CLASS="FILENAME" +>configure.in</TT +> 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 <SPAN +CLASS="SYMBOL" +>target_abbrev</SPAN +>; this value is the link to the + init file you will write soon. (For simplicity, we assume the + environment is Unix, and use <I +CLASS="EMPHASIS" +>unix</I +> as the + value.)</P +><P +>What else is needed in <TT +CLASS="FILENAME" +>configure.in</TT +> 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 <SPAN +CLASS="PRODUCTNAME" +>GNU Autoconf</SPAN +>. </P +></LI +><LI +STYLE="list-style-type: disc" +><P +>Create <TT +CLASS="FILENAME" +>Makefile.in</TT +> (if you are using + Autoconf), or <TT +CLASS="FILENAME" +>Makefile.am</TT +>(if you are using + Automake), the source file used by configure to build your + <TT +CLASS="FILENAME" +>Makefile</TT +>. If you are using GNU Automake.just add the + keyword <I +CLASS="EMPHASIS" +>dejagnu</I +> to the + <I +CLASS="EMPHASIS" +>AUTOMAKE_OPTIONS</I +> variable in your + <TT +CLASS="FILENAME" +>Makefile.am</TT +> file. This will add all the Makefile + support needed to run DejaGnu, and support the <A +HREF="runningtests.html#MAKECHECK" +><I +>Make Check</I +></A +> + target.</P +><P +>You also need to include two targets important to DejaGnu: + <I +CLASS="EMPHASIS" +>check</I +>, to run the tests, and + <I +CLASS="EMPHASIS" +>site.exp</I +>, to set up the Tcl copies of + configuration-dependent values. This is called the <A +HREF="customizing.html#LOCAL" +><I +>Local Config File</I +></A +> + The check target must run the <B +CLASS="COMMAND" +>runtest</B +> program to + execute the tests.</P +><P +>The <TT +CLASS="FILENAME" +>site.exp</TT +> 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 <B +CLASS="COMMAND" +>runtest</B +> on the command + line.</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 4-1. Sample Makefile.in Fragment</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="90%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> # Look for a local version of DejaGnu, otherwise use one in the path + RUNTEST = `if test -f $(top_srcdir)/../dejagnu/runtest; then \ + echo $(top_srcdir) ../dejagnu/runtest; \ + else \ + echo runtest; \ + fi` + + # The flags to pass to runtest + RUNTESTFLAGS = + + # Execute the tests + check: site.exp all + $(RUNTEST) $(RUNTESTFLAGS) \ + --tool <SPAN +CLASS="SYMBOL" +>${example}</SPAN +> --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 <SPAN +CLASS="SYMBOL" +>${examplename}</SPAN +> <SPAN +CLASS="SYMBOL" +>${example}</SPAN +>" >> ./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? + + </PRE +></TD +></TR +></TABLE +></DIV +></LI +><LI +STYLE="list-style-type: disc" +><P +>Create a directory (in <TT +CLASS="FILENAME" +>testsuite</TT +>) + called <TT +CLASS="FILENAME" +>config</TT +>. Make a <I +CLASS="EMPHASIS" +>Tool Init + File</I +> in this directory. Its name must start with the + <SPAN +CLASS="SYMBOL" +>target_abbrev</SPAN +> value, or be named + <TT +CLASS="FILENAME" +>default.exp</TT +> so call it + <TT +CLASS="FILENAME" +>config/unix.exp</TT +> 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 <B +CLASS="COMMAND" +>runtest</B +> to run.</P +><P +>If the program being tested is not interactive, you can get + away with this minimal <TT +CLASS="FILENAME" +>unix.exp</TT +> to begin + with:</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 4-2. Simple Batch Program Tool Init File</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="90%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> + proc foo_exit {} {} + proc foo_version {} {} + + </PRE +></TD +></TR +></TABLE +></DIV +><P +>If the program being tested is interactive, however, you might + as well define a <I +CLASS="EMPHASIS" +>start</I +> routine and invoke it by + using an init file like this:</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 4-3. Simple Interactive Program Tool Init File</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="90%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> + proc foo_exit {} {} + proc foo_version {} {} + + proc foo_start {} { + global ${examplename} + spawn ${examplename} + expect { + -re "" {} + } + } + + # Start the program running we want to test + foo_start + + </PRE +></TD +></TR +></TABLE +></DIV +></LI +><LI +STYLE="list-style-type: disc" +><P +>Create a directory whose name begins with your tool's + name, to contain tests. For example, if your tool's name is + <I +CLASS="EMPHASIS" +>gcc</I +>, then the directories all need to start with + <I +CLASS="EMPHASIS" +>"gcc."</I +>.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>Create a sample test file. Its name must end with + <TT +CLASS="FILENAME" +>.exp</TT +>. You can use + <TT +CLASS="FILENAME" +>first-try.exp</TT +>. To begin with, just write there a + line of Tcl code to issue a message.</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 4-4. Testing A New Tool Config</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="90%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> send_user "Testing: one, two...\n" + + </PRE +></TD +></TR +></TABLE +></DIV +></LI +><LI +STYLE="list-style-type: disc" +><P +>Back in the <TT +CLASS="FILENAME" +>testsuite</TT +> (top + level) directory, run <B +CLASS="COMMAND" +>configure</B +>. 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.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>e now ready to triumphantly type <B +CLASS="COMMAND" +>make + check</B +> or <B +CLASS="COMMAND" +>runtest</B +>. You should see + something like this:</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 4-5. Example Test Case Run</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="90%" +><TR +><TD +><PRE +CLASS="SCREEN" +> Test Run By rhl on Fri Jan 29 16:25:44 EST 1993 + + === example tests === + + Running ./example.0/first-try.exp ... + Testing: one, two... + + === example Summary === + + </PRE +></TD +></TR +></TABLE +></DIV +><P +>There is no output in the summary, because so far the example + does not call any of the procedures that establish a test + outcome.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>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. </P +></LI +></UL +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="extending.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="addtarget.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Extending DejaGnu</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="extending.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Adding A New Target</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/boardconfig.html b/doc/overview/boardconfig.html new file mode 100644 index 0000000..95d6643 --- /dev/null +++ b/doc/overview/boardconfig.html @@ -0,0 +1,254 @@ +<HTML +><HEAD +><TITLE +>Board Config File</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Customizing DejaGnu" +HREF="customizing.html"><LINK +REL="PREVIOUS" +TITLE="Global Config File" +HREF="global.html"><LINK +REL="NEXT" +TITLE="Remote Host Testing" +HREF="releng.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="global.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 3. Customizing DejaGnu</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="releng.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="BOARDCONFIG" +>Board Config File</A +></H1 +><P +>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 <A +HREF="addboard.html" +><I +>Adding A New Board</I +></A +> chapter. </P +><P +>An example board config file for a GNU simulator is as + follows. <TT +CLASS="FUNCTION" +><B +>set_board_info</B +></TT +> is a procedure that sets the + field name to the specified value. The procedures in square brackets + <I +CLASS="EMPHASIS" +>[]</I +> are <I +CLASS="EMPHASIS" +>helper procedures</I +>. 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.</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 3-5. Board Config File</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> # This is a list of toolchains that are supported on this board. + set_board_info target_install {sparc64-elf} + + # Load the generic configuration for this board. This will define any + # routines needed by the tool to communicate with the board. + load_generic_config "sim" + + # We need this for find_gcc and *_include_flags/*_link_flags. + load_base_board_description "basic-sim" + + # Use long64 by default. + process_multilib_options "long64" + + setup_sim sparc64 + + # We only support newlib on this target. We assume that all multilib + # options have been specified before we get here. + set_board_info compiler "[find_gcc]" + set_board_info cflags "[libgloss_include_flags] [newlib_include_flags]" + set_board_info ldflags "[libgloss_link_flags] [newlib_link_flags]" + # No linker script. + set_board_info ldscript ""; + + # Used by a few gcc.c-torture testcases to delimit how large the + # stack can be. + set_board_info gcc,stack_size 16384 + # The simulator doesn't return exit statuses and we need to indicate this + # the standard GCC wrapper will work with this target. + set_board_info needs_status_wrapper 1 + # We can't pass arguments to programs. + set_board_info noargs 1 + </PRE +></TD +></TR +></TABLE +></DIV +><P +>There are five helper procedures used in this example. The first + one, <TT +CLASS="FUNCTION" +><B +>find gcc</B +></TT +> 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 + <TT +CLASS="FUNCTION" +><B +>libgloss_include_flags</B +></TT +> & + <TT +CLASS="FUNCTION" +><B +>libgloss_link_flags</B +></TT +>. These return the proper flags to + compiler and link an executable image using <A +HREF="builtins.html#LIBGLOSS" +><I +>Libgloss</I +></A +>, the GNU BSP (Board Support Package). The final + procedures are <TT +CLASS="FUNCTION" +><B +>newlib_include_flag</B +></TT +> & + <TT +CLASS="FUNCTION" +><B +>newlib_include_flag</B +></TT +>. These find the Newlib C + library, which is a reentrant standard C library for embedded systems + comprising of non GPL'd code.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="global.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="releng.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Global Config File</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="customizing.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Remote Host Testing</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/boarddefs.html b/doc/overview/boarddefs.html new file mode 100644 index 0000000..d89694c --- /dev/null +++ b/doc/overview/boarddefs.html @@ -0,0 +1,887 @@ +<HTML +><HEAD +><TITLE +>Board Config File Values</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Extending DejaGnu" +HREF="extending.html"><LINK +REL="PREVIOUS" +TITLE="Adding A New Board" +HREF="addboard.html"><LINK +REL="NEXT" +TITLE="Writing A Test Case" +HREF="writing.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="addboard.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 4. Extending DejaGnu</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="writing.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="BOARDDEFS" +>Board Config File Values</A +></H1 +><P +>These fields are all in the <SPAN +CLASS="SYMBOL" +>board_info</SPAN +> These are + all set by using the <TT +CLASS="FUNCTION" +><B +>set_board_info</B +></TT +> procedure. The + parameters are the field name, followed by the value to set the field + to.</P +><P +><DIV +CLASS="TABLE" +><P +><B +>Table 4-1. Common Board Info Fields</B +></P +><TABLE +BORDER="1" +CLASS="CALSTABLE" +><TR +><TH +ALIGN="LEFT" +VALIGN="TOP" +>Field</TH +><TH +ALIGN="LEFT" +VALIGN="TOP" +>Sample Value</TH +><TH +ALIGN="LEFT" +VALIGN="TOP" +>Description</TH +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>compiler</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"[find_gcc]"</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>The path to the compiler to use.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>cflags</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"-mca"</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>Compilation flags for the compiler.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>ldflags</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"[libgloss_link_flags] [newlib_link_flags]"</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>Linking flags for the compiler.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>ldscript</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"-Wl,-Tidt.ld"</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>The linker script to use when cross compiling.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>libs</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"-lgcc"</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>Any additional libraries to link in.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>shell_prompt</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"cygmon>"</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>The command prompt of the remote shell.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>hex_startaddr</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"0xa0020000"</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>The Starting address as a string.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>start_addr</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>0xa0008000</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>The starting address as a value.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>startaddr</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"a0020000"</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>exit_statuses_bad</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>Whether there is an accurate exit status.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>reboot_delay</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>10</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>The delay between power off and power on.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>unreliable</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>Whether communication with the board is unreliable.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>sim</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>[find_sim]</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>The path to the simulator to use.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>objcopy</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>$tempfil</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>The path to the <B +CLASS="COMMAND" +>objcopy</B +> program.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>support_libs</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"${prefix_dir}/i386-coff/"</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>Support libraries needed for cross compiling.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>addl_link_flags</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"-N"</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>Additional link flags, rarely used.</TD +></TR +></TABLE +></DIV +> + </P +><P +>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.</P +><P +><DIV +CLASS="TABLE" +><P +><B +>Table 4-2. Board Info Fields For GCC & GDB</B +></P +><TABLE +BORDER="1" +CLASS="CALSTABLE" +><TR +><TH +ALIGN="LEFT" +VALIGN="TOP" +>Field</TH +><TH +ALIGN="LEFT" +VALIGN="TOP" +>Sample Value</TH +><TH +ALIGN="LEFT" +VALIGN="TOP" +>Description</TH +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>strip</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>$tempfile</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>Strip the executable of symbols.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb_load_offset</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"0x40050000"</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb_protocol</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"remote"</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>The GDB debugging protocol to use.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb_sect_offset</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"0x41000000";</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb_stub_ldscript</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"-Wl,-Teva-stub.ld"</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>The linker script to use with a GDB stub.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb_init_command</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"set mipsfpu none"</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb,cannot_call_functions</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>Whether GDB can call functions on the target,</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb,noargs</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>Whether the target can take command line arguments.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb,nosignals</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>Whether there are signals on the target.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb,short_int</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb,start_symbol</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"_start";</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>The starting symbol in the executable.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb,target_sim_options</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"-sparclite"</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>Special options to pass to the simulator.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb,timeout</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>540</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>Timeout value to use for remote communication.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb_init_command</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"print/x \$fsr = 0x0"</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb_load_offset</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"0x12020000"</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb_opts</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"--command gdbinit"</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb_prompt</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"\\(gdb960\\)"</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>The prompt GDB is using.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb_run_command</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"jump start"</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gdb_stub_offset</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"0x12010000"</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>use_gdb_stub</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>Whether to use a GDB stub.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>use_vma_offset</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>wrap_m68k_aout</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gcc,no_label_values</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gcc,no_trampolines</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gcc,no_varargs</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>gcc,stack_size</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>16384</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>Stack size to use with some GCC testcases.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>ieee_multilib_flags</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"-mieee";</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>is_simulator</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>needs_status_wrapper</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>no_double</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>no_long_long</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>noargs</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>1</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>nullstone,lib</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>"mips-clock.c"</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>nullstone,ticks_per_sec</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>3782018</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>sys_speed_value</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>200</TD +><TD +> </TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>target_install</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>{sh-hms}</TD +><TD +> </TD +></TR +></TABLE +></DIV +> + </P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="addboard.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="writing.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Adding A New Board</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="extending.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Writing A Test Case</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/book1.html b/doc/overview/book1.html new file mode 100644 index 0000000..68347e0 --- /dev/null +++ b/doc/overview/book1.html @@ -0,0 +1,403 @@ +<HTML +><HEAD +><TITLE +>DejaGnu</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="NEXT" +TITLE="Abstract" +HREF="preface.html"></HEAD +><BODY +><DIV +CLASS="BOOK" +><A +NAME="AEN1" +></A +><DIV +CLASS="TITLEPAGE" +><H1 +CLASS="TITLE" +><A +NAME="AEN2" +>DejaGnu</A +></H1 +><H2 +CLASS="SUBTITLE" +>The GNU Testing Framework</H2 +><H3 +CLASS="AUTHOR" +>Rob Savoye</H3 +><DIV +CLASS="AFFILIATION" +><SPAN +CLASS="ORGNAME" +>Free Software Foundation<BR></SPAN +></DIV +><P +CLASS="COPYRIGHT" +>Copyright © 2000 by <SPAN +CLASS="HOLDER" +>Free Software Foundation, Inc.</SPAN +></P +><HR></DIV +><DIV +CLASS="TOC" +><DL +><DT +><B +>Table of Contents</B +></DT +><DT +><A +HREF="preface.html" +>Abstract</A +></DT +><DT +>1. <A +HREF="overview.html" +>Overview</A +></DT +><DD +><DL +><DT +><A +HREF="overview.html#WHATIS" +>What is DejaGnu ?</A +></DT +><DT +><A +HREF="new.html" +>What's New In This Release</A +></DT +><DD +><DL +><DT +><A +HREF="new.html#CYGWIN" +>NT Support</A +></DT +></DL +></DD +><DT +><A +HREF="designgoals.html" +>Design Goals</A +></DT +><DT +><A +HREF="posix.html" +>A POSIX conforming test framework</A +></DT +></DL +></DD +><DT +>2. <A +HREF="runningtests.html" +>Running Tests</A +></DT +><DD +><DL +><DT +><A +HREF="runningtests.html#MAKECHECK" +>Make check</A +></DT +><DT +><A +HREF="runtest.html" +>Runtest</A +></DT +><DD +><DL +><DT +><A +HREF="runtest.html#OUTPUTS" +>Output States</A +></DT +><DT +><A +HREF="runtest.html#INVOKING" +>Invoking Runtest</A +></DT +><DT +><A +HREF="runtest.html#COMMON" +>Common Options</A +></DT +></DL +></DD +><DT +><A +HREF="outputfiles.html" +>The files DejaGnu produces.</A +></DT +><DD +><DL +><DT +><A +HREF="outputfiles.html#SUM" +>Summary File</A +></DT +><DT +><A +HREF="outputfiles.html#LOG" +>Log File</A +></DT +><DT +><A +HREF="outputfiles.html#DEBUGFILE" +>Debug Log File</A +></DT +></DL +></DD +></DL +></DD +><DT +>3. <A +HREF="customizing.html" +>Customizing DejaGnu</A +></DT +><DD +><DL +><DT +><A +HREF="customizing.html#LOCAL" +>Local Config File</A +></DT +><DT +><A +HREF="global.html" +>Global Config File</A +></DT +><DT +><A +HREF="boardconfig.html" +>Board Config File</A +></DT +><DT +><A +HREF="releng.html" +>Remote Host Testing</A +></DT +><DT +><A +HREF="configfile.html" +>Config File Values</A +></DT +><DD +><DL +><DT +><A +HREF="configfile.html#OPTIONDEFS" +>Command Line Option Variables</A +></DT +><DT +><A +HREF="configfile.html#PERSONAL" +>Personal Config File</A +></DT +></DL +></DD +></DL +></DD +><DT +>4. <A +HREF="extending.html" +>Extending DejaGnu</A +></DT +><DD +><DL +><DT +><A +HREF="extending.html#ADDSUITE" +>Adding A New Test Suite</A +></DT +><DT +><A +HREF="addtool.html" +>Adding A New Tool</A +></DT +><DT +><A +HREF="addtarget.html" +>Adding A New Target</A +></DT +><DT +><A +HREF="addboard.html" +>Adding A New Board</A +></DT +><DT +><A +HREF="boarddefs.html" +>Board Config File Values</A +></DT +><DT +><A +HREF="writing.html" +>Writing A Test Case</A +></DT +><DT +><A +HREF="debugging.html" +>Debugging A Test Case</A +></DT +><DT +><A +HREF="adding.html" +>Adding A Test Case To A Test Suite.</A +></DT +><DT +><A +HREF="hints.html" +>Hints On Writing A Test Case</A +></DT +><DT +><A +HREF="tvariables.html" +>Special variables used by test cases.</A +></DT +></DL +></DD +><DT +>5. <A +HREF="reference.html" +>Reference</A +></DT +><DD +><DL +><DT +><A +HREF="reference.html#INSTALLATION" +>Installation</A +></DT +><DD +><DL +><DT +><A +HREF="reference.html#CONFIGURING" +>Configuring DejaGnu</A +></DT +><DT +><A +HREF="reference.html#INSTALLING" +>Installing DejaGnu</A +></DT +></DL +></DD +><DT +><A +HREF="builtins.html" +>Builtin Procedures</A +></DT +><DD +><DL +><DT +><A +HREF="builtins.html#COREPROCS" +>Core Internal Procedures</A +></DT +><DT +><A +HREF="builtins.html#REMOTEPROCS" +>Procedures For Remote Communication</A +></DT +><DT +><A +HREF="builtins.html#CONNPROCS" +>Procedures For Using Utilities to Connect</A +></DT +><DT +><A +HREF="builtins.html#TARGETPROCS" +>Procedures For Target Boards</A +></DT +><DT +><A +HREF="builtins.html#TARGETDB" +>Target Database Procedures</A +></DT +><DT +><A +HREF="builtins.html#PLATFORMPROCS" +>Platform Dependant Procedures</A +></DT +><DT +><A +HREF="builtins.html#UTILPROCS" +>Utility Procedures</A +></DT +><DT +><A +HREF="builtins.html#LIBGLOSS" +>Libgloss, A Free BSP</A +></DT +><DT +><A +HREF="builtins.html#DEBUGPROCS" +>Procedures for debugging your Tcl code.</A +></DT +></DL +></DD +><DT +><A +HREF="filemap.html" +>File Map</A +></DT +></DL +></DD +></DL +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +> </TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="preface.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +> </TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Abstract</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/builtins.html b/doc/overview/builtins.html new file mode 100644 index 0000000..8a01039 --- /dev/null +++ b/doc/overview/builtins.html @@ -0,0 +1,10723 @@ +<HTML +><HEAD +><TITLE +>Builtin Procedures</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Reference" +HREF="reference.html"><LINK +REL="PREVIOUS" +TITLE="Reference" +HREF="reference.html"><LINK +REL="NEXT" +TITLE="File Map" +HREF="filemap.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="reference.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 5. Reference</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="filemap.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="BUILTINS" +>Builtin Procedures</A +></H1 +><P +>DejaGnu provides these Tcl procedures.</P +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="COREPROCS" +>Core Internal Procedures</A +></H2 +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="MAILFILE" +>Mail_file Procedure</A +></H3 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>mail_file</B +></CODE +>(<VAR +CLASS="PDPARAM" +>file to subject</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +></I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="OPENLOGS" +>Open_logs Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>open_logs</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="CLOSELOGS" +>Close_logs Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>close_logs</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="ISBUILD" +>Isbuild Procedure</A +></H3 +><P +>Tests for a particular build host environment. If the + currently configured host matches the argument string, the result is + <I +CLASS="EMPHASIS" +>1</I +>; otherwise the result is + <I +CLASS="EMPHASIS" +>0</I +>. <I +CLASS="EMPHASIS" +>host</I +> 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.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>isbuild</B +></CODE +>(<VAR +CLASS="PDPARAM" +>pattern</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>pattern</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="ISREMOTE" +>Is_remote Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>is_remote</B +></CODE +>(<VAR +CLASS="PDPARAM" +>board</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +></I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="IS3WAY" +>is3way Procedure</A +></H3 +><P +>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 +CLASS="EMPHASIS" +>1</I +>; otherwise the result is + <I +CLASS="EMPHASIS" +>0</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>is3way</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="ISHOST" +>Ishost Procedure</A +></H3 +><P +>Tests for a particular host environment. If the currently + configured host matches the argument string, the result is + <I +CLASS="EMPHASIS" +>1</I +>; otherwise the result is + <I +CLASS="EMPHASIS" +>0</I +>. <I +CLASS="EMPHASIS" +>host</I +> 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).</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>ishost</B +></CODE +>(<VAR +CLASS="PDPARAM" +>pattern</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +></I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="ISTARGET" +>Istarget Procedure</A +></H3 +><P +>Tests for a particular target environment. If the currently + configured target matches the argument string, the result is + <I +CLASS="EMPHASIS" +>1</I +> ; otherwise the result is + <I +CLASS="EMPHASIS" +>0</I +>. 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 +CLASS="EMPHASIS" +>NULL</I +> string, then it returns the name of the + build canonical configuration.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>istarget</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +></I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="ISNATIVE" +>Isnative Procedure</A +></H3 +><P +>Tests whether the current configuration has the same host and + target. When it runs in a native configuration this procedure returns + a <I +CLASS="EMPHASIS" +>1</I +>; otherwise it returns a + <I +CLASS="EMPHASIS" +>0</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>isnative</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="UNKNOWN" +>Unknown Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>unknown</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="CLONEOUTPUT" +>Clone_output Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>clone_output</B +></CODE +>(<VAR +CLASS="PDPARAM" +>message</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>message</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="RESETVARS" +>Reset_vars Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>reset_vars</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="LOGANDEXIT" +>Log_and_exit Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>log_and_exit</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="LOGSUMMARY" +>Log_summary Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>log_summary</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="CLEANUP" +>Cleanup Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>cleanup</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="SETUPXFAIL" +>Setup_xfail Procedure</A +></H3 +><P +>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 +CLASS="EMPHASIS" +>bugid</I +> argument is optional, and used only in the + logging file output; use it as a link to a bug-tracking system such + as <SPAN +CLASS="PRODUCTNAME" +>GNATS</SPAN +>.</P +><P +>Once you use <TT +CLASS="FUNCTION" +><B +>setup_xfail</B +></TT +>, the + <TT +CLASS="FUNCTION" +><B +>fail</B +></TT +> and <TT +CLASS="FUNCTION" +><B +>pass</B +></TT +> procedures + produce the messages <I +CLASS="EMPHASIS" +>XFAIL</I +> and + <I +CLASS="EMPHASIS" +>XPASS</I +> respectively, allowing you to distinguish + expected failures (and unexpected success!) from other test + outcomes.</P +><DIV +CLASS="WARNING" +><P +></P +><TABLE +CLASS="WARNING" +BORDER="1" +WIDTH="100%" +><TR +><TD +ALIGN="CENTER" +><B +>Warning</B +></TD +></TR +><TR +><TD +ALIGN="LEFT" +><P +>Warning you must clear the expected failure after + using setup_xfail in a test case. Any call to <TT +CLASS="FUNCTION" +><B +>pass + </B +></TT +>or <TT +CLASS="FUNCTION" +><B +>fail</B +></TT +>l clears the expected failure + implicitly; if the test has some other outcome, e.g. an error, you + can call <TT +CLASS="FUNCTION" +><B +>clear_xfail</B +></TT +> to clear the expected + failure explicitly. Otherwise, the expected-failure declaration + applies to whatever test runs next, leading to surprising + results.</P +></TD +></TR +></TABLE +></DIV +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>setup_xfail</B +></CODE +>(<VAR +CLASS="PDPARAM" +>config</VAR +> + <VAR +CLASS="PDPARAM" +>bugid</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>config</I +></TT +></DT +><DD +><P +>The config triplet to trigger whether this is an + unexpected or expect failure.</P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>bugid</I +></TT +></DT +><DD +><P +>The optional bugid, used to tie it this test case + to a bug tracking system.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="RECORDTEST" +>Record_test Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>record_test</B +></CODE +>(<VAR +CLASS="PDPARAM" +>type</VAR +> + <VAR +CLASS="PDPARAM" +>message</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>type</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>message</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="PASS" +>Pass Procedure</A +></H3 +><P +>Declares a test to have passed. <TT +CLASS="FUNCTION" +><B +>pass</B +></TT +> + writes in the log files a message beginning with + <I +CLASS="EMPHASIS" +>PASS</I +> (or <I +CLASS="EMPHASIS" +>XPASS</I +>, if failure + was expected), appending the argument + <TT +CLASS="PARAMETER" +><I +>string</I +></TT +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>pass</B +></CODE +>(<VAR +CLASS="PDPARAM" +>string</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>string</I +></TT +></DT +><DD +><P +>The string to use for this PASS + message.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="FAIL" +>Fail Procedure</A +></H3 +><P +>Declares a test to have failed. <TT +CLASS="FUNCTION" +><B +>fail</B +></TT +> + writes in the log files a message beginning with + <I +CLASS="EMPHASIS" +>FAIL</I +> (or <I +CLASS="EMPHASIS" +>XFAIL</I +>, if failure + was expected), appending the argument + <TT +CLASS="PARAMETER" +><I +>string</I +></TT +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>fail</B +></CODE +>(<VAR +CLASS="PDPARAM" +>string</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>string</I +></TT +></DT +><DD +><P +>The string to use for this FAIL + message.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="XPASS" +>Xpass Procedure</A +></H3 +><P +>Declares a test to have unexpectably passed, when it was + expected to be a failure. <TT +CLASS="FUNCTION" +><B +>xpass</B +></TT +> + writes in the log files a message beginning with + <I +CLASS="EMPHASIS" +>XPASS</I +> (or <I +CLASS="EMPHASIS" +>XFAIL</I +>, if failure + was expected), appending the argument + <TT +CLASS="PARAMETER" +><I +>string</I +></TT +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>xpass</B +></CODE +>(<VAR +CLASS="PDPARAM" +>string</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>string</I +></TT +></DT +><DD +><P +>The string to use for this output + state.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="XFAIL" +>Xfail Procedure</A +></H3 +><P +>Declares a test to have expectably + failed. <TT +CLASS="FUNCTION" +><B +>xfail</B +></TT +> + writes in the log files a message beginning with + <I +CLASS="EMPHASIS" +>XFAIL</I +> (or <I +CLASS="EMPHASIS" +>PASS</I +>, if success + was expected), appending the argument + <TT +CLASS="PARAMETER" +><I +>string</I +></TT +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>xpass</B +></CODE +>(<VAR +CLASS="PDPARAM" +>string</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>string</I +></TT +></DT +><DD +><P +>The string to use for this output + state.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="SETWARNINGTHRESHOLD" +>Set_warning_threshold Procedure</A +></H3 +><P +>Sets the value of <SPAN +CLASS="SYMBOL" +>warning_threshold</SPAN +>. A value + of <I +CLASS="EMPHASIS" +>0</I +> disables it: calls to + <TT +CLASS="FUNCTION" +><B +>warning</B +></TT +> will not turn a + <I +CLASS="EMPHASIS" +>PASS</I +> or <I +CLASS="EMPHASIS" +>FAIL</I +> into an + <I +CLASS="EMPHASIS" +>UNRESOLVED</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>set_warning_threshold</B +></CODE +>(<VAR +CLASS="PDPARAM" +>threshold</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>threshold</I +></TT +></DT +><DD +><P +>This is the value of the new warning + threshold.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="GETWARNINGTHRESHOLD" +>Get_warning_threshold Procedure</A +></H3 +><P +>Returns the current value of + <SPAN +CLASS="SYMBOL" +>{warning_threshold</SPAN +>. The default value is 3. This + value controls how many <TT +CLASS="FUNCTION" +><B +>warning</B +></TT +> procedures can + be called before becoming <I +CLASS="EMPHASIS" +>UNRESOLVED</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>get_warning_threshold</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="WARNING" +>Warning Procedure</A +></H3 +><P +>Declares detection of a minor error in the test case + itself. <TT +CLASS="FUNCTION" +><B +>warning</B +></TT +> writes in the log files a message + beginning with <I +CLASS="EMPHASIS" +>WARNING</I +>, appending the argument + <TT +CLASS="PARAMETER" +><I +>string</I +></TT +>. Use <TT +CLASS="FUNCTION" +><B +>warning</B +></TT +> rather + than <TT +CLASS="FUNCTION" +><B +>perror</B +></TT +> for cases (such as communication + failure to be followed by a retry) where the test case can recover from + the error. If the optional <TT +CLASS="PARAMETER" +><I +>number</I +></TT +> is supplied, + then this is used to set the internal count of warnings to that + value.</P +><P +>As a side effect, <SPAN +CLASS="SYMBOL" +>warning_threshold</SPAN +> or more + calls to warning in a single test case also changes the effect of the + next <TT +CLASS="FUNCTION" +><B +>pass</B +></TT +> or <TT +CLASS="FUNCTION" +><B +>fail</B +></TT +> command: + the test outcome becomes <I +CLASS="EMPHASIS" +>UNRESOLVED</I +> since an + automatic <I +CLASS="EMPHASIS" +>PASS</I +> or <I +CLASS="EMPHASIS" +>FAIL</I +> may + not be trustworthy after many warnings. If the optional numeric value + is <I +CLASS="EMPHASIS" +>0</I +>, then there are no further side effects to + calling this function, and the following test outcome doesn't become + <I +CLASS="EMPHASIS" +>UNRESOLVED</I +>. This can be used for errors with no + known side effects.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>warning</B +></CODE +>(<VAR +CLASS="PDPARAM" +>string</VAR +> + <VAR +CLASS="PDPARAM" +>number</VAR +> + );<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>string</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>number</I +></TT +></DT +><DD +><P +>The optional number to set the error counter. Thius + is only used to fake out the counter when using the + <TT +CLASS="FUNCTION" +><B +>xfail</B +></TT +> procedure to control when it flips the + output over to <I +CLASS="EMPHASIS" +>UNRESOLVED</I +> + state.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="PERROR" +>Perror Procedure</A +></H3 +><P +>Declares a severe error in the testing framework + itself. <TT +CLASS="FUNCTION" +><B +>perror</B +></TT +> writes in the log files a message + beginning with <I +CLASS="EMPHASIS" +>ERROR</I +>, appending the argument + <TT +CLASS="PARAMETER" +><I +>string</I +></TT +>.</P +><P +>As a side effect, perror also changes the effect of the next + <TT +CLASS="FUNCTION" +><B +>pass</B +></TT +> or <TT +CLASS="FUNCTION" +><B +>fail</B +></TT +> command: the + test outcome becomes <I +CLASS="EMPHASIS" +>UNRESOLVED</I +>, since an + automatic <I +CLASS="EMPHASIS" +>PASS</I +> or <I +CLASS="EMPHASIS" +>FAIL</I +> cannot + be trusted after a severe error in the test framework. If the optional + numeric value is <I +CLASS="EMPHASIS" +>0</I +>, then there are no further side + effects to calling this function, and the following test outcome + doesn't become <I +CLASS="EMPHASIS" +>UNRESOLVED</I +>. This can be used for + errors with no known side effects.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>perror</B +></CODE +>(<VAR +CLASS="PDPARAM" +>string</VAR +> + <VAR +CLASS="PDPARAM" +>number</VAR +> + );<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>string</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>number</I +></TT +></DT +><DD +><P +>The optional number to set the error counter. Thius + is only used to fake out the counter when using the + <TT +CLASS="FUNCTION" +><B +>xfail</B +></TT +> procedure to control when it flips the + output over to <I +CLASS="EMPHASIS" +>UNRESOLVED</I +> + state.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="NOTE" +>Note Procedure</A +></H3 +><P +>Appends an informational message to the log + file. <TT +CLASS="FUNCTION" +><B +>note</B +></TT +> writes in the log files a message + beginning with <I +CLASS="EMPHASIS" +>NOTE</I +>, appending the argument + <TT +CLASS="PARAMETER" +><I +>string</I +></TT +>. Use <TT +CLASS="FUNCTION" +><B +>note</B +></TT +> + sparingly. The <TT +CLASS="FUNCTION" +><B +>verbose</B +></TT +> 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 <TT +CLASS="FUNCTION" +><B +>note</B +></TT +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>note</B +></CODE +>(<VAR +CLASS="PDPARAM" +>string</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>string</I +></TT +></DT +><DD +><P +>The string to use for this note.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="UNTESTED" +>Untested Procedure</A +></H3 +><P +>Declares a test was not run. <TT +CLASS="FUNCTION" +><B +>untested</B +></TT +> writes + in the log file a message beginning with <I +CLASS="EMPHASIS" +>UNTESTED</I +>, + appending the argument <I +CLASS="EMPHASIS" +>string</I +>. 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.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>untested</B +></CODE +>(<VAR +CLASS="PDPARAM" +>string</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>string</I +></TT +></DT +><DD +><P +>The string to use for this output + state.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="UNRESOLVED" +>Unresolved Procedure</A +></H3 +><P +>Declares a test to have an unresolved + outcome. <TT +CLASS="FUNCTION" +><B +>unresolved</B +></TT +> writes in the log file a + message beginning with <I +CLASS="EMPHASIS" +>UNRESOLVED</I +>, appending the + argument <I +CLASS="EMPHASIS" +>string</I +>. 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).</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>unresolved</B +></CODE +>(<VAR +CLASS="PDPARAM" +>string</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>string</I +></TT +></DT +><DD +><P +>The string to use for this output + state.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="UNSUPPORTED" +>Unsupported Procedure</A +></H3 +><P +>Declares that a test case depends on some facility that does not + exist in the testing environment. <TT +CLASS="FUNCTION" +><B +>unsupported</B +></TT +> + writes in the log file a message beginning with + <I +CLASS="EMPHASIS" +>UNSUPPORTED</I +>, appending the argument string.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>unsupported</B +></CODE +>(<VAR +CLASS="PDPARAM" +>string</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>string</I +></TT +></DT +><DD +><P +>The string to use for this output + state.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="INITTESTCOUNTS" +>Init_testcounts Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>init_testcounts</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="INCRCOUNT" +>Incr_count Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>incr_count</B +></CODE +>(<VAR +CLASS="PDPARAM" +>name</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>name</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="TRANSFORM" +>transform Procedure</A +></H3 +><P +>Generates a string for the name of a tool as it was configured + and installed, given its native name (as the argument + <TT +CLASS="PARAMETER" +><I +>toolname</I +></TT +>). This makes the assumption that all + tools are installed using the same naming conventions: For example, + for a cross compiler supporting the <I +CLASS="EMPHASIS" +>m68k-vxworks</I +> + configuration, the result of transform <B +CLASS="COMMAND" +>gcc</B +> is + <B +CLASS="COMMAND" +>m68k-vxworks-gcc</B +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>transform</B +></CODE +>(<VAR +CLASS="PDPARAM" +>toolname</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>toolname</I +></TT +></DT +><DD +><P +>The name of the cross-development program to + transform.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="CHECKCONDITIONALXFAIL" +>Check_conditional_xfail Procedure</A +></H3 +><P +>This procedure adds a condition xfail, based on compiler + options used to create a test case executable. If an include options + is found in the compiler flags, and it's the right architecture, + it'll trigger an <I +CLASS="EMPHASIS" +>XFAIL</I +>. Otherwise it'll produce + an ordinary <I +CLASS="EMPHASIS" +>FAIL</I +>. You can also specify flags to + exclude. This makes a result be a <I +CLASS="EMPHASIS" +>FAIL</I +>, even if + the included options are found. To set the conditional, set + the variable <SPAN +CLASS="SYMBOL" +>compiler_conditional_xfail_data</SPAN +> to the + fields <TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +>"[message string] [targets list] [includes + list] [excludes list]"</PRE +></TD +></TR +></TABLE +> (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 +CLASS="EMPHASIS" +>1</I +> if the + conditional is true, or <I +CLASS="EMPHASIS" +>0</I +> if the conditional is + false.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>check_conditional_xfail</B +></CODE +>(<VAR +CLASS="PDPARAM" +>message</VAR +> + <VAR +CLASS="PDPARAM" +>targets</VAR +> + <VAR +CLASS="PDPARAM" +>includes</VAR +> + <VAR +CLASS="PDPARAM" +>excludes</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>message</I +></TT +></DT +><DD +><P +>This is the message to print with the normal test + result.</P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>targets</I +></TT +></DT +><DD +><P +>This is a string with the list targets to activate + this conditional on.</P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>includes</I +></TT +></DT +><DD +><P +>This is a list of sets of options to search for in + the compiler options to activate this conditional. If any set of + the options matches, then this conditional is + true.</P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>excludes</I +></TT +></DT +><DD +><P +>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.</P +></DD +></DL +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 5-1. Specifying the conditional xfail data</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> set compiler_conditional_xfail_data { \ + "I sure wish I knew why this was hosed" \ + "sparc*-sun*-* *-pc-*-*" \ + {"-Wall -v" "-O3"} \ + {"-O1" "-Map"} \ + } + </PRE +></TD +></TR +></TABLE +></DIV +><P +>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.</P +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="CLEARXFAIL" +>Clear_xfail Procedure</A +></H3 +><P +>Cancel an expected failure (previously declared with + <B +CLASS="COMMAND" +>setup_xfail</B +>) for a particular set of + configurations. The <TT +CLASS="PARAMETER" +><I +>config</I +></TT +> argument is a list + of configuration target names. It is only necessary to call + <B +CLASS="COMMAND" +>clear_xfail</B +> if a test case ends without calling + either <B +CLASS="COMMAND" +>pass</B +> or <B +CLASS="COMMAND" +>fail</B +>, after + calling <B +CLASS="COMMAND" +>setup_xfail</B +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>clear_xfail</B +></CODE +>(<VAR +CLASS="PDPARAM" +>config</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>config</I +></TT +></DT +><DD +><P +>The configuration triplets to + clear.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="VERBOSE" +>Verbose Procedure</A +></H3 +><P +>Test cases can use this function to issue helpful messages + depending on the number of <TT +CLASS="OPTION" +>--verbose</TT +> options on the + runtest command line. It prints string if the value of the variable + <SPAN +CLASS="SYMBOL" +>verbose</SPAN +> is higher than or equal to the optional + number. The default value for number is <I +CLASS="EMPHASIS" +>1</I +>. Use + the optional <TT +CLASS="OPTION" +>-log</TT +> argument to cause string to always + be added to the log file, even if it won't be printed. Use the + optional <TT +CLASS="OPTION" +>-n</TT +> argument to print string without a + trailing newline. Use the optional <TT +CLASS="OPTION" +>--</TT +> argument if + string begins with "-".</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>verbose</B +></CODE +>(<VAR +CLASS="PDPARAM" +>-log</VAR +> + <VAR +CLASS="PDPARAM" +>-n</VAR +> + <VAR +CLASS="PDPARAM" +>-r</VAR +> + <VAR +CLASS="PDPARAM" +>string</VAR +> + <VAR +CLASS="PDPARAM" +>number</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>-log</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>-n</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>--</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>string</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>number</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="LOADLIB" +>Load_lib Procedure</A +></H3 +><P +>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 + <B +CLASS="COMMAND" +>make install</B +>, this path defaults to the current + directory. In either case, it then looks in the current directory + for a directory called <TT +CLASS="FILENAME" +>lib</TT +>. If there are + duplicate definitions, the last one loaded takes precedence over the + earlier ones.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>load_lib</B +></CODE +>(<VAR +CLASS="PDPARAM" +>filespec</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>filespec</I +></TT +></DT +><DD +><P +>The name of the DejaGnu library file to + load.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="REMOTEPROCS" +>Procedures For Remote Communication</A +></H2 +><P +><TT +CLASS="FILENAME" +>lib/remote.exp</TT +> 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 +CLASS="EMPHASIS" +>-1</I +>, when the + connection cannot be established, or the spawn ID returned by + the <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> command + <B +CLASS="COMMAND" +>spawn</B +>.</P +><P +>It use the value of the <SPAN +CLASS="SYMBOL" +>connect</SPAN +> field + in the <SPAN +CLASS="SYMBOL" +>target_info</SPAN +> array (was + <SPAN +CLASS="SYMBOL" +>connectmode</SPAN +> as the type of connection to + make. Current supported connection types are tip, kermit, + telnet, rsh, rlogin, and netdata. If the <TT +CLASS="OPTION" +>--reboot</TT +> + option was used on the runtest command line, then the target + is rebooted before the connection is made.</P +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="CALLREMOTE" +>Call_remote Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>call_remote</B +></CODE +>(<VAR +CLASS="PDPARAM" +>type</VAR +> + <VAR +CLASS="PDPARAM" +>proc</VAR +> + <VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>proc</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="CHECKFORBOARDSTATUS" +>Check_for_board_status Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>check_for_board_status</B +></CODE +>(<VAR +CLASS="PDPARAM" +>variable</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>variable</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="FILEONBUILD" +>File_on_build Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>file_on_build</B +></CODE +>(<VAR +CLASS="PDPARAM" +>op</VAR +> + <VAR +CLASS="PDPARAM" +>file</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>op</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>file</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="FILEONHOST" +>File_on_host Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>file_on_host</B +></CODE +>(<VAR +CLASS="PDPARAM" +>op</VAR +> + <VAR +CLASS="PDPARAM" +>file</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>op</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>file</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="LOCALEXEC" +>Local_exec Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>local_exec</B +></CODE +>(<VAR +CLASS="PDPARAM" +>commandline</VAR +> + <VAR +CLASS="PDPARAM" +>inp</VAR +> + <VAR +CLASS="PDPARAM" +>outp</VAR +> + <VAR +CLASS="PDPARAM" +>timeout</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>inp</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>outp</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>timeout</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTEBINARY" +>Remote_binary Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_binary</B +></CODE +>(<VAR +CLASS="PDPARAM" +>host</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>host</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTECLOSE" +>Remote_close Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_close</B +></CODE +>(<VAR +CLASS="PDPARAM" +>shellid</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>shellid</I +></TT +></DT +><DD +><P +>This is the value returned by a call + to <TT +CLASS="FUNCTION" +><B +>remote_open</B +></TT +>. This closes the + connection to the target so resources can be used by + others. This parameter can be left off if the + <SPAN +CLASS="SYMBOL" +>fileid</SPAN +> field in the + <SPAN +CLASS="SYMBOL" +>target_info</SPAN +> array is set.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTEDOWNLOAD" +>Remote_download Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_download</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>file</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>file</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTEEXEC" +>Remote_exec Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_exec</B +></CODE +>(<VAR +CLASS="PDPARAM" +>hostname</VAR +> + <VAR +CLASS="PDPARAM" +>program</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>hostname</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>program</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTEEXPECT" +>Remote_expect Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_expect</B +></CODE +>(<VAR +CLASS="PDPARAM" +>board</VAR +> + <VAR +CLASS="PDPARAM" +>timeout</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>board</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>timeout</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTEFILE" +>Remote_file Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_file</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTELD" +>Remote_ld Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_ld</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>prog</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>prog</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTELOAD" +>Remote_load Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_load</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>prog</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>prog</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTEOPEN" +>Remote_open Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_open</B +></CODE +>(<VAR +CLASS="PDPARAM" +>type</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>type</I +></TT +></DT +><DD +><P +>This is passed <TT +CLASS="OPTION" +>host</TT +> or + <TT +CLASS="OPTION" +>target</TT +>. 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 + <SPAN +CLASS="SYMBOL" +>spawn_id</SPAN +> of the process that manages + the connection. This value can be used in + <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> or + <B +CLASS="COMMAND" +>exp_send</B +> statements, or passed to + other procedures that need the connection process's + id. This also sets the <SPAN +CLASS="SYMBOL" +>fileid</SPAN +> field in + the <SPAN +CLASS="SYMBOL" +>target_info</SPAN +> array.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTEPOPCONN" +>Remote_pop_conn Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_pop_conn</B +></CODE +>(<VAR +CLASS="PDPARAM" +>host</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>host</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTEPUSHCONN" +>Remote_push_conn Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_push_conn</B +></CODE +>(<VAR +CLASS="PDPARAM" +>host</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>host</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTERAWBINARY" +>Remote_raw_binary Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_raw_binary</B +></CODE +>(<VAR +CLASS="PDPARAM" +>host</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>host</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTERAWCLOSE" +>Remote_raw_close Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_raw_close</B +></CODE +>(<VAR +CLASS="PDPARAM" +>host</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>host</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTERAWFILE" +>Remote_raw_file Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_raw_file</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTERAWLD" +>remote_raw_ld Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_raw_ld</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>prog</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>prog</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTERAWLOAD" +>Remote_raw_load Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_raw_load</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>prog</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>prog</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTERAWOPEN" +>Remote_raw_open Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_raw_open</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTERAWSEND" +>Remote_raw_send Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_raw_send</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>string</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>string</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTERAWSPAWN" +>Remote_raw_spawn Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_raw_spawn</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>commandline</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>commandline</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTERAWTRANSMIT" +>Remote_raw_transmit Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_raw_transmit</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>file</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>file</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTERAWWAIT" +>Remote_raw_wait Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_raw_wait</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>timeout</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>timeout</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTEREBOOT" +>Remote_reboot Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_reboot</B +></CODE +>(<VAR +CLASS="PDPARAM" +>host</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>host</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTESEND" +>Remote_send Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_send</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>string</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>string</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTESPAWN" +>Remote_spawn Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_spawn</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>commandline</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>commandline</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTESWAPCONN" +>Remote_swap_conn Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_swap_conn</B +></CODE +>(<VAR +CLASS="PDPARAM" +>host</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +></I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTETRANSMIT" +>Remote_transmit Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_transmit</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>file</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>file</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTEUPLOAD" +>Remote_upload Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_upload</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>srcfile</VAR +> + <VAR +CLASS="PDPARAM" +>arg</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>srcfile</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>arg</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REMOTEWAIT" +>Remote_wait Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>remote_wait</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>timeout</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>timeout</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="STANDARDCLOSE" +>Standard_close Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>standard_close</B +></CODE +>(<VAR +CLASS="PDPARAM" +>host</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>host</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="STANDARDDOWNLOAD" +>Standard_download Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>standard_download</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>file</VAR +> + <VAR +CLASS="PDPARAM" +>destfile</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>file</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>destfile</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="STANDARDEXEC" +>Standard_exec Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>standard_exec</B +></CODE +>(<VAR +CLASS="PDPARAM" +>hostname</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>hostname</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="STANDARDFILE" +>Standard_file Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>standard_file</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +>, <VAR +CLASS="PDPARAM" +>op</VAR +>, <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +></I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="STANDARDLOAD" +>Standard_load Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>standard_load</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>prog</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>prog</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="STANDARDREBOOT" +>Standard_reboot Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>standard_reboot</B +></CODE +>(<VAR +CLASS="PDPARAM" +>host</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>host</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="STANDARDSEND" +>Standard_send Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>standard_send</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>string</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>string</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="STANDARDSPAWN" +>Standard_spawn Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>standard_spawn</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>commandline</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>commndline</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="STANDARDTRANSMIT" +>Standard_transmit Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>standard_transmit</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>file</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>file</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="STANDARDUPLOAD" +>Standard_upload Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>standard_upload</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest srcfile destfile</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>srcfile</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>destfile</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="STANDARDWAIT" +>Standard_wait Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>standard_wait</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>timeout</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>timeout</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="UNIXCLEANFILENAME" +>Unix_clean_filename Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>unix_clean_filename</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>file</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>file</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="CONNPROCS" +>Procedures For Using Utilities to Connect</A +></H2 +><P +>telnet, rsh, tip, kermit</P +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="TELNET" +>telnet Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>telnet</B +></CODE +>(<VAR +CLASS="PDPARAM" +>hostname</VAR +> + <VAR +CLASS="PDPARAM" +>port</VAR +>);<P +></P +></DIV +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>rlogin</B +></CODE +>(<VAR +CLASS="PDPARAM" +>hostname</VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="RSH" +>rsh Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>rsh</B +></CODE +>(<VAR +CLASS="PDPARAM" +>hostname</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>hostname</I +></TT +></DT +><DD +><P +>This refers to the IP address or name + (for example, an entry in + <TT +CLASS="FILENAME" +>/etc/hosts</TT +>) for this target. The + procedure names reflect the Unix utility used to + establish a connection. The optional + <TT +CLASS="PARAMETER" +><I +>port</I +></TT +> is used to specify the IP + port number. The value of the + <TT +CLASS="PARAMETER" +><I +>netport</I +></TT +> field in the + <SPAN +CLASS="SYMBOL" +>target_info</SPAN +> array is used. (was + <SPAN +CLASS="SYMBOL" +>$netport</SPAN +>) This value has two parts, + the hostname and the port number, seperated by a + <I +CLASS="EMPHASIS" +>:</I +>. If host or target is used in + the <SPAN +CLASS="SYMBOL" +>hostname</SPAN +> field, than the + config array is used for all information.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="TIP" +>Tip Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>tip</B +></CODE +>(<VAR +CLASS="PDPARAM" +>port</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>port</I +></TT +></DT +><DD +><P +>Connect using the Unix utility + <B +CLASS="COMMAND" +>tip</B +>. <TT +CLASS="PARAMETER" +><I +>Port</I +></TT +>must + be a name from the <SPAN +CLASS="PRODUCTNAME" +>tip</SPAN +> + configuration file + <TT +CLASS="FILENAME" +>/etc/remote</TT +>. Often, this is called + <SPAN +CLASS="SYMBOL" +>hardwire</SPAN +>, or something like + <SPAN +CLASS="SYMBOL" +>ttya</SPAN +>. This file holds all the + configuration data for the serial port. The value of + the <SPAN +CLASS="SYMBOL" +>serial</SPAN +> field in the + <SPAN +CLASS="SYMBOL" +>target_info</SPAN +> array is used. (was + <SPAN +CLASS="SYMBOL" +>$serialport</SPAN +>) If <TT +CLASS="OPTION" +>host</TT +> + or <TT +CLASS="OPTION" +>target</TT +> is used in the + <TT +CLASS="PARAMETER" +><I +>port</I +></TT +> field, than the config + array is used for all information. the + config array is used for all information.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="KERMIT" +>Kermit Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>kermit</B +></CODE +>(<VAR +CLASS="PDPARAM" +>port</VAR +> + <VAR +CLASS="PDPARAM" +>bps</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>port</I +></TT +></DT +><DD +><P +>Connect using the program + <B +CLASS="COMMAND" +>kermit</B +>. <TT +CLASS="PARAMETER" +><I +>Port</I +></TT +> + is the device name, + e.g. <TT +CLASS="FILENAME" +>/dev/ttyb</TT +>. + </P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>bps</I +></TT +></DT +><DD +><P +><TT +CLASS="PARAMETER" +><I +>bps</I +></TT +> is the line + speed to use (in its per second) for the + connection. The value of the <SPAN +CLASS="SYMBOL" +>serial</SPAN +> + field in the <SPAN +CLASS="SYMBOL" +>target_info</SPAN +> array is + used. (was <SPAN +CLASS="SYMBOL" +>$serialport</SPAN +>) If + <TT +CLASS="OPTION" +>host</TT +> or <TT +CLASS="OPTION" +>target</TT +> is + used in the <TT +CLASS="PARAMETER" +><I +>port</I +></TT +> field, than the + config array is used for all information. the + config array is used for all information.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="KERMITOPEN" +>kermit_open Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>kermit_open</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="KERMITCOMMAND" +>Kermit_command Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>kermit_command</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="KERMITSEND" +>Kermit_send Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>kermit_send</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest string args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>string</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="KERMITTRANSMIT" +>Kermit_transmit Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>kermit_transmit</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>file</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>file</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="TELNETOPEN" +>Telnet_open Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>telnet_open</B +></CODE +>(<VAR +CLASS="PDPARAM" +>hostname</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>hostname</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="TELNETBINARY" +>Telnet_binary Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>telnet_binary</B +></CODE +>(<VAR +CLASS="PDPARAM" +>hostname</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>hostname</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="TELNETTRANSMIT" +>Telnet_transmit Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>telnet_transmit</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>file</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>file</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="TIPOPEN" +>Tip_open Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>tip_open</B +></CODE +>(<VAR +CLASS="PDPARAM" +>hostname</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>hostname</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="RLOGINOPEN" +>Rlogin_open Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>rlogin_open</B +></CODE +>(<VAR +CLASS="PDPARAM" +>arg</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>arg</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="RLOGINSPAWN" +>Rlogin_spawn Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>rlogin_spawn</B +></CODE +>(<VAR +CLASS="PDPARAM" +>dest</VAR +> + <VAR +CLASS="PDPARAM" +>cmdline</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>dest</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>cmdline</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="RSHOPEN" +>Rsh_open Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>rsh_open</B +></CODE +>(<VAR +CLASS="PDPARAM" +>hostname</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>hostname</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="RSHDOWNLOAD" +>Rsh_download Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>rsh_download</B +></CODE +>(<VAR +CLASS="PDPARAM" +>desthost</VAR +> + <VAR +CLASS="PDPARAM" +>srcfile</VAR +> + <VAR +CLASS="PDPARAM" +>destfile</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>desthost</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>srcfile</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>destfile</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="RSHUPLOAD" +>Rsh_upload Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>rsh_upload</B +></CODE +>(<VAR +CLASS="PDPARAM" +>desthost</VAR +> + <VAR +CLASS="PDPARAM" +>srcfile</VAR +> + <VAR +CLASS="PDPARAM" +>destfile</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>desthost</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>srcfile</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>destfile</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="RSHEXEC" +>Rsh_exec Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>rsh_exec</B +></CODE +>(<VAR +CLASS="PDPARAM" +>boardname</VAR +> + <VAR +CLASS="PDPARAM" +>cmd</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>boardname</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>cmd</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="FTPOPEN" +>Ftp_open Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>ftp_open</B +></CODE +>(<VAR +CLASS="PDPARAM" +>host</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>host</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="FTPUPLOAD" +>Ftp_upload Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>ftp_upload</B +></CODE +>(<VAR +CLASS="PDPARAM" +>host</VAR +> + <VAR +CLASS="PDPARAM" +>remotefile</VAR +> + <VAR +CLASS="PDPARAM" +>localfile</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>host</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>remotefile</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>localfile</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="FTPDOWNLOAD" +>Ftp_download Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>ftp_download</B +></CODE +>(<VAR +CLASS="PDPARAM" +>host</VAR +> + <VAR +CLASS="PDPARAM" +>localfile</VAR +> + <VAR +CLASS="PDPARAM" +>remotefile</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>host</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>localfile</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>remotefile</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="FTPCLOSE" +>Ftp_close Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>ftp_close</B +></CODE +>(<VAR +CLASS="PDPARAM" +>host</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>host</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="TIPDOWNLOAD" +>Tip_download Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>tip_download</B +></CODE +>(<VAR +CLASS="PDPARAM" +>spawnid</VAR +> + <VAR +CLASS="PDPARAM" +>file</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>spawnid</I +></TT +></DT +><DD +><P +>Download <TT +CLASS="OPTION" +>file</TT +> to the + process <SPAN +CLASS="SYMBOL" +>spawnid</SPAN +> (the value returned + when the connection was established), using the + <B +CLASS="COMMAND" +>~put</B +> command under + <SPAN +CLASS="PRODUCTNAME" +>tip</SPAN +>. Most often used for + single board computers that require downloading + programs in ASCII S-records. Returns + <I +CLASS="EMPHASIS" +>1</I +> if an error occurs, + <I +CLASS="EMPHASIS" +>0</I +> otherwise.</P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>file</I +></TT +></DT +><DD +><P +>This is the filename to + downlaod.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="TARGETPROCS" +>Procedures For Target Boards</A +></H2 +><P +></P +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="DEFAULTLINK" +>Default_link Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>default_link</B +></CODE +>(<VAR +CLASS="PDPARAM" +>board</VAR +> + <VAR +CLASS="PDPARAM" +>objects</VAR +> + <VAR +CLASS="PDPARAM" +>destfile</VAR +> + <VAR +CLASS="PDPARAM" +>flags</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>board</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>objects</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>destfile</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>flags</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="DEFAULTTARGETASSEMBLE" +>Default_target_assemble Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>default_target_assemble</B +></CODE +>(<VAR +CLASS="PDPARAM" +>source</VAR +> + <VAR +CLASS="PDPARAM" +>destfile</VAR +> + <VAR +CLASS="PDPARAM" +>flags</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>source</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>destfile</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>flags</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="DEFAULTTARGETCOMPILE" +>default_target_compile Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>default_target_compile</B +></CODE +>(<VAR +CLASS="PDPARAM" +>source</VAR +> + <VAR +CLASS="PDPARAM" +>destfile</VAR +> + <VAR +CLASS="PDPARAM" +>type</VAR +> + <VAR +CLASS="PDPARAM" +>options</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>source</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>destfile</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>type</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>options</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="POPCONFIG" +>Pop_config Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>pop_config</B +></CODE +>(<VAR +CLASS="PDPARAM" +>type</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>type</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="PRUNEWARNINGS" +>Prune_warnings Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>prune_warnings</B +></CODE +>(<VAR +CLASS="PDPARAM" +>text</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>text</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="PUSHBUILD" +>Push_build Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>push_build</B +></CODE +>(<VAR +CLASS="PDPARAM" +>name</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>name</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="PUSHCONFIG" +>push_config Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>push_config</B +></CODE +>(<VAR +CLASS="PDPARAM" +>type</VAR +> + <VAR +CLASS="PDPARAM" +>name</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>type</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>name</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="REBOOTTARGET" +>Reboot_target Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>reboot_target</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="TARGETASSEMBLE" +>Target_assemble Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>target_assemble</B +></CODE +>(<VAR +CLASS="PDPARAM" +>source destfile flags</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>source</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>destfile</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>flags</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="TARGETCOMPILE" +>Target_compile Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>target_compile</B +></CODE +>(<VAR +CLASS="PDPARAM" +>source</VAR +> + <VAR +CLASS="PDPARAM" +>destfile</VAR +> + <VAR +CLASS="PDPARAM" +>type</VAR +> + <VAR +CLASS="PDPARAM" +>options</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>source</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>destfile</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>type</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>options</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="TARGETDB" +>Target Database Procedures</A +></H2 +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="BOARDINFO" +>Board_info Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>board_info</B +></CODE +>(<VAR +CLASS="PDPARAM" +>machine</VAR +> + <VAR +CLASS="PDPARAM" +>op</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>machine</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>op</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="HOSTINFO" +>Host_info Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>host_info</B +></CODE +>(<VAR +CLASS="PDPARAM" +>op</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>op</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="SETBOARDINFO" +>Set_board_info Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>set_board_info</B +></CODE +>(<VAR +CLASS="PDPARAM" +>entry</VAR +> + <VAR +CLASS="PDPARAM" +>value</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>entry</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>value</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="SETCURRTARGETINFO" +>Set_currtarget_info Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>set_currtarget_info</B +></CODE +>(<VAR +CLASS="PDPARAM" +>entry</VAR +> + <VAR +CLASS="PDPARAM" +>value</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>entry</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>value</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="TARGETINFO" +>Target_info Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>target_info</B +></CODE +>(<VAR +CLASS="PDPARAM" +>op</VAR +> + <VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>op</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="UNSETBOARDINFO" +>Unset_board_info Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>unset_board_info</B +></CODE +>(<VAR +CLASS="PDPARAM" +>entry</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>entry</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="UNSETCURRTARGETINFO" +>Unset_currtarget_info Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>unset_currtarget_info</B +></CODE +>(<VAR +CLASS="PDPARAM" +>entry</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>entry</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="PUSHTARGET" +>Push_target Procedure</A +></H3 +><P +>This makes the target named <I +CLASS="EMPHASIS" +>name</I +> be the + current target connection. The value of <I +CLASS="EMPHASIS" +>name</I +> is + an index into the <SPAN +CLASS="SYMBOL" +>target_info</SPAN +> array and is set in + the global config file.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>push_target</B +></CODE +>(<VAR +CLASS="PDPARAM" +>name</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>name</I +></TT +></DT +><DD +><P +>The name of the target to make current + connection.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="POPTARGET" +>Pop_target Procedure</A +></H3 +><P +>This unsets the current target connection.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>pop_target</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="LISTTARGETS" +>List_targets Procedure</A +></H3 +><P +>This lists all the supported targets for this + architecture.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>list_targets</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="PUSHHOST" +>Push_host Procedure</A +></H3 +><P +>This makes the host named <I +CLASS="EMPHASIS" +>name</I +> be the + current remote host connection. The value of + <I +CLASS="EMPHASIS" +>name</I +> is an index into the + <SPAN +CLASS="SYMBOL" +>target_info</SPAN +> array and is set in the global config + file.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>push_host</B +></CODE +>(<VAR +CLASS="PDPARAM" +>name</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>name</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="POPHOST" +>Pop_host Procedure</A +></H3 +><P +>This unsets the current host connection.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>pop_host</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="COMPILE" +>Compile Procedure</A +></H3 +><P +>This invokes the compiler as set by CC to compile the + file <TT +CLASS="FILENAME" +>file</TT +>. The default options for many cross + compilation targets are <I +CLASS="EMPHASIS" +>guessed</I +> by DejaGnu, and + these options can be added to by passing in more parameters as + arguments to <B +CLASS="COMMAND" +>compile</B +>. Optionally, this will also + use the value of the <I +CLASS="EMPHASIS" +>cflags</I +> 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 + <B +CLASS="COMMAND" +>execute_anywhere</B +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>compile</B +></CODE +>(<VAR +CLASS="PDPARAM" +>file</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>file</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="ARCHIVE" +>Archive Procedure</A +></H3 +><P +>This produces an archive file. Any parameters passed to + <B +CLASS="COMMAND" +>archive</B +> are used in addition to the default + flags. Optionally, this will also use the value of the + <I +CLASS="EMPHASIS" +>arflags</I +> 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 <B +CLASS="COMMAND" +>execute_anywhere</B +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>archive</B +></CODE +>(<VAR +CLASS="PDPARAM" +>file</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>file</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="RANLIB" +>Ranlib Procedure</A +></H3 +><P +>This generates an index for the archive file for systems that + aren't POSIX yet. Any parameters passed to <B +CLASS="COMMAND" +>ranlib</B +> + are used in for the flags.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>ranlib</B +></CODE +>(<VAR +CLASS="PDPARAM" +>file</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>file</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="EXECUTEANYWHERE" +>Execute_anywhere Procedure</A +></H3 +><P +>This executes the <I +CLASS="EMPHASIS" +>cmdline</I +> on the proper + host. This should be used as a replacement for the Tcl command + <B +CLASS="COMMAND" +>exec</B +> 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.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>execute_anywhere</B +></CODE +>(<VAR +CLASS="PDPARAM" +>cmdline</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>cmdline</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="PLATFORMPROCS" +>Platform Dependant Procedures</A +></H2 +><P +>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 +CLASS="EMPHASIS" +>_</I +>, and finally a suffix describing the + procedure's purpose. For example, a procedure to extract the + version from <SPAN +CLASS="PRODUCTNAME" +>GDB</SPAN +> is called + <SPAN +CLASS="SYMBOL" +>gdb_version</SPAN +>.</P +><P +><B +CLASS="COMMAND" +>runtest</B +> itself calls only two of these + procedures, <SPAN +CLASS="SYMBOL" +>${tool}_exit</SPAN +> and + <SPAN +CLASS="SYMBOL" +>${tool}_version</SPAN +>; these procedures use no + arguments.</P +><P +>The other two procedures, <SPAN +CLASS="SYMBOL" +>${tool}_start</SPAN +> + and <SPAN +CLASS="SYMBOL" +>${tool}_load</SPAN +>}, 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.</P +><P +>The usual convention for return codes from any of these + procedures (although it is not required by + <B +CLASS="COMMAND" +>runtest</B +>) is to return <I +CLASS="EMPHASIS" +>0</I +> + if the procedure succeeded, <I +CLASS="EMPHASIS" +>1</I +> if it failed, + and <I +CLASS="EMPHASIS" +>-1</I +> if there was a communication error.</P +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="TOOLSTART" +>${tool}_start Procedure</A +></H3 +><P +>Starts a particular tool. For an interactive tool, + <TT +CLASS="FUNCTION" +><B +>${tool}_start</B +></TT +> starts and initializes the + tool, leaving the tool up and running for the test cases; an + example is <TT +CLASS="FUNCTION" +><B +>gdb_start</B +></TT +>, the start function + for GDB. For a batch oriented tool, + <TT +CLASS="FUNCTION" +><B +>${tool}_start</B +></TT +> is optional; the recommended + convention is to let <TT +CLASS="FUNCTION" +><B +>${tool}_start</B +></TT +> run the + tool, leaving the output in a variable called + <TT +CLASS="FUNCTION" +><B +>comp_output</B +></TT +>. Test scripts can then analyze + <TT +CLASS="FUNCTION" +><B +>$comp_output</B +></TT +> to determine the test results. + An example of this second kind of start function is + <TT +CLASS="FUNCTION" +><B +>gcc_start</B +></TT +>, the start function for GCC.</P +><P +>DejaGnu itself does not call + <TT +CLASS="FUNCTION" +><B +>${tool}_start</B +></TT +>. The initialization + module <TT +CLASS="FUNCTION" +><B +>${tool}_init.exp</B +></TT +> must call + <TT +CLASS="FUNCTION" +><B +>${tool}_start</B +></TT +> for interactive tools; + for batch-oriented tools, each individual test script calls + <TT +CLASS="FUNCTION" +><B +>${tool}_start</B +></TT +> (or makes other + arrangements to run the tool).</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>${tool}_start</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="TOOLLOAD" +>${tool}_load Procedure</A +></H3 +><P +>Loads something into a tool. For an interactive tool, + this conditions the tool for a particular test case; for + example, <TT +CLASS="FUNCTION" +><B +>gdb_load</B +></TT +> loads a new + executable file into the debugger. For batch oriented tools, + <TT +CLASS="FUNCTION" +><B +>${tool}_load</B +></TT +> may do nothing---though, + for example, the GCC support uses + <TT +CLASS="FUNCTION" +><B +>gcc_load</B +></TT +> to load and run a binary on + the target environment. Conventionally, + <TT +CLASS="FUNCTION" +><B +>${tool}_load</B +></TT +> leaves the output of any + program it runs in a variable called + <SPAN +CLASS="SYMBOL" +>$exec_output</SPAN +>. Writing + <TT +CLASS="FUNCTION" +><B +>${tool}_load</B +></TT +> 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 + <TT +CLASS="FUNCTION" +><B +>${tool}_load</B +></TT +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>${tool}_load</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="TOOLEXIT" +>${tool}_exit Procedure</A +></H3 +><P +>Cleans up (if necessary) before DejaGnu exits. For + interactive tools, this usually ends the interactive + session. You can also use <TT +CLASS="FUNCTION" +><B +>${tool}_exit</B +></TT +> + to remove any temporary files left over from the + tests. <B +CLASS="COMMAND" +>runtest</B +> calls + <TT +CLASS="FUNCTION" +><B +>${tool}_exit</B +></TT +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>${tool}_exit</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="TOOLVERSION" +>${tool}_version Procedure</A +></H3 +><P +>Prints the version label and number for + <SPAN +CLASS="SYMBOL" +>${tool}</SPAN +>. 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.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>${tool}_version</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +></DIV +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="UTILPROCS" +>Utility Procedures</A +></H2 +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="GETDIRS" +>Getdirs Procedure</A +></H3 +><P +>Returns a list of all the directories in the single + directory a single directory that match an optional + pattern. </P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>getdirs</B +></CODE +>(<VAR +CLASS="PDPARAM" +>rootdir</VAR +> + <VAR +CLASS="PDPARAM" +>pattern</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>pattern</I +></TT +></DT +><DD +><P +>If you do not specify + <TT +CLASS="PARAMETER" +><I +>pattern</I +></TT +>, + <TT +CLASS="FUNCTION" +><B +>Getdirs</B +></TT +> assumes a default pattern of + <I +CLASS="EMPHASIS" +>*</I +>. You may use the common shell + wildcard characters in the pattern. If no directories + match the pattern, then a NULL string is + returned</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="FIND" +>Find Procedure</A +></H3 +><P +>Search for files whose names match <I +CLASS="EMPHASIS" +>pattern</I +> + (using shell wildcard characters for filename expansion). Search + subdirectories recursively, starting at + <I +CLASS="EMPHASIS" +>rootdir</I +>. 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.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>find</B +></CODE +>(<VAR +CLASS="PDPARAM" +>rootdir</VAR +> + <VAR +CLASS="PDPARAM" +>pattern</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>rootdir</I +></TT +></DT +><DD +><P +>The top level directory to search the search + from.</P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>pattern</I +></TT +></DT +><DD +><P +>A csh "glob" style regular expression reprsenting + the files to find.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="WHICH" +>Which Procedure</A +></H3 +><P +>Searches the execution path for an executable file + <I +CLASS="EMPHASIS" +>binary</I +>, like the the BSD <B +CLASS="COMMAND" +>which</B +> + utility. This procedure uses the shell environment variable + <I +CLASS="EMPHASIS" +>PATH</I +>. It returns <I +CLASS="EMPHASIS" +>0</I +> if the + binary is not in the path, or if there is no <I +CLASS="EMPHASIS" +>PATH</I +> + environment variable. If <B +CLASS="COMMAND" +>binary</B +> is in the path, it + returns the full path to <B +CLASS="COMMAND" +>binary</B +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>which</B +></CODE +>(<VAR +CLASS="PDPARAM" +>file</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>binary</I +></TT +></DT +><DD +><P +>The executable program or shell script to look + for.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="GREP" +>Grep Procedure</A +></H3 +><P +>Search the file called <TT +CLASS="FILENAME" +>filename</TT +> (a fully + specified path) for lines that contain a match for regular expression + <I +CLASS="EMPHASIS" +>regexp</I +>. The result is a list of all the lines that + match. If no lines match, the result is an empty string. Specify + <I +CLASS="EMPHASIS" +>regexp</I +> using the standard regular expression style + used by the Unix utility program grep.</P +><P +>Use the optional third argument <I +CLASS="EMPHASIS" +>line</I +> to + start lines in the result with the line number in + <TT +CLASS="FILENAME" +>filename</TT +>. (This argument is simply an option + flag; type it just as shown <TT +CLASS="OPTION" +>--line</TT +>.)</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>grep</B +></CODE +>(<VAR +CLASS="PDPARAM" +>filename</VAR +> + <VAR +CLASS="PDPARAM" +>regexp</VAR +> + <VAR +CLASS="PDPARAM" +>--line</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>filename</I +></TT +></DT +><DD +><P +>The file to search.</P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>regexp</I +></TT +></DT +><DD +><P +>The Unix style regular expression (as used by the + <B +CLASS="COMMAND" +>grep</B +> Unix utility) to search + for.</P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>--line</I +></TT +></DT +><DD +><P +>Prefix the line number to each line where the + regexp matches.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="PRUNE" +>Prune Procedure</A +></H3 +><P +>Remove elements of the Tcl list <I +CLASS="EMPHASIS" +>list</I +>. + Elements are fields delimited by spaces. The result is a copy of + list, without any elements that match <I +CLASS="EMPHASIS" +>pattern</I +>. + You can use the common shell wildcard characters to specify the + pattern.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>prune</B +></CODE +>(<VAR +CLASS="PDPARAM" +>list</VAR +> + <VAR +CLASS="PDPARAM" +>pattern</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>list</I +></TT +></DT +><DD +><P +>A Tcl list containing the original data. Commonly + this is the output of a batch executed command, like running a + compiler.</P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>pattern</I +></TT +></DT +><DD +><P +>The csh shell "glob" style pattern to search + for.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="SLAY" +>Slay Procedure</A +></H3 +><P +>This look in the process table for <I +CLASS="EMPHASIS" +>name</I +> + and send it a unix SIGINT, killing the process. This will only work + under NT if you have Cygwin or another Unix system for NT + installed.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>slay</B +></CODE +>(<VAR +CLASS="PDPARAM" +>name</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>name</I +></TT +></DT +><DD +><P +>The name of the program to kill.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="ABSOLUTE" +>Absolute Procedure</A +></H3 +><P +>This procedure takes the relative <I +CLASS="EMPHASIS" +>path</I +>, + and converts it to an absolute path.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>absolute</B +></CODE +>(<VAR +CLASS="PDPARAM" +>path</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>path</I +></TT +></DT +><DD +><P +>The path to convert.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="PSOURCE" +>Psource Procedure</A +></H3 +><P +>This sources the file <I +CLASS="EMPHASIS" +>filename</I +>, and traps + all errors. It also ignores all extraneous output. If there was an + error it returns a <I +CLASS="EMPHASIS" +>1</I +>, otherwise it returns a + <I +CLASS="EMPHASIS" +>0</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>psource</B +></CODE +>(<VAR +CLASS="PDPARAM" +>file</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>filename</I +></TT +></DT +><DD +><P +>The filename to Tcl script to + source.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="RUNTESTFILEP" +>Runtest_file_p Procedure</A +></H3 +><P +>Search <I +CLASS="EMPHASIS" +>runtest</I +>s for + <I +CLASS="EMPHASIS" +>testcase</I +> and return <I +CLASS="EMPHASIS" +>1</I +> if + found, <I +CLASS="EMPHASIS" +>0</I +> if not. <I +CLASS="EMPHASIS" +>runtests</I +> + is a list of two elements. The first is the pathname of the + testsuite expect script running. The second is a copy of what was on + the right side of the <I +CLASS="EMPHASIS" +>=</I +> if + <TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +>foo.exp="..."</PRE +></TD +></TR +></TABLE +>" was specified, or + an empty string if no such argument is present. This is used by tools + like compilers where each testcase is a file.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>runtest_file_p</B +></CODE +>(<VAR +CLASS="PDPARAM" +>runtests</VAR +> + <VAR +CLASS="PDPARAM" +>testcase</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>runtests</I +></TT +></DT +><DD +><P +>The pathname of the testsuite expect script + running</P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>testcase</I +></TT +></DT +><DD +><P +>The test case filename.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="DIFF" +>Diff Procedure</A +></H3 +><P +>Compares the two files and returns a <I +CLASS="EMPHASIS" +>1</I +> if + they match, or a <I +CLASS="EMPHASIS" +>0</I +> if they don't. If + <SPAN +CLASS="SYMBOL" +>verbose</SPAN +> is set, then it'll print the differences to + the screen.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>diff</B +></CODE +>(<VAR +CLASS="PDPARAM" +>file_1</VAR +> + <VAR +CLASS="PDPARAM" +>file_2</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>file_1</I +></TT +></DT +><DD +><P +>The first file to compare.</P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>file_2</I +></TT +></DT +><DD +><P +>The second file to compare.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="SETENV" +>Setenv Procedure</A +></H3 +><P +>Sets the environment variable <I +CLASS="EMPHASIS" +>var</I +> to the + value <I +CLASS="EMPHASIS" +>val</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>setenv</B +></CODE +>(<VAR +CLASS="PDPARAM" +>var</VAR +> + <VAR +CLASS="PDPARAM" +>val</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>var</I +></TT +></DT +><DD +><P +>The environment variable to set.</P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>val</I +></TT +></DT +><DD +><P +>The value to set the variable to.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="UNSETENV" +>unsetenv Procedure</A +></H3 +><P +>Unsets the environment variable + <I +CLASS="EMPHASIS" +>var</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>unsetenv</B +></CODE +>(<VAR +CLASS="PDPARAM" +>var</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>var</I +></TT +></DT +><DD +><P +>The environment variable to + unset.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="GETENV" +>Getenv Procedure</A +></H3 +><P +>Returns the value of <I +CLASS="EMPHASIS" +>var</I +> in the + environment if it exists, otherwise it returns NULL.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>getenv</B +></CODE +>(<VAR +CLASS="PDPARAM" +>var</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>var</I +></TT +></DT +><DD +><P +>The environment variable to get the value + of.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="PRUNESYSTEMCRUD" +>Prune_system_crud Procedure</A +></H3 +><P +>For system <I +CLASS="EMPHASIS" +>system</I +>, delete text the host or + target operating system might issue that will interfere with pattern + matching of program output in <I +CLASS="EMPHASIS" +>text</I +>. An example + is the message that is printed if a shared library is out of + date.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>prune_system_crud</B +></CODE +>(<VAR +CLASS="PDPARAM" +>system</VAR +> + <VAR +CLASS="PDPARAM" +>test</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>system</I +></TT +></DT +><DD +><P +>The system error messages to look for to screen out + .</P +></DD +><DT +><TT +CLASS="PARAMETER" +><I +>text</I +></TT +></DT +><DD +><P +>The Tcl variable containing the + text.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="LIBGLOSS" +>Libgloss, A Free BSP</A +></H2 +><P +>Libgloss is a free <I +CLASS="FIRSTTERM" +>BSP</I +> (Board Support + Package) commonly used with GCC and G++ to produce a fully linked + executable image for an embedded systems.</P +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="LIBGLOSSLINKFLAGS" +>Libgloss_link_flags Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>libgloss_link_flags</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="LIBGLOSSINCLUDEFLAGS" +>Libgloss_include_flags Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>libgloss_include_flags</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="NEWLIBLINKFLAGS" +>Newlib_link_flags Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>newlib_link_flags</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="NEWLIBINCLUDEFLAGS" +>Newlib_include_flags Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>newlib_include_flags</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="LIBIOINCLUDEFLAGS" +>Libio_include_flags Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>libio_include_flags</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="LIBIOLINKFLAGS" +>Libio_link_flags Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>libio_link_flags</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="GXXINCLUDEFLAGS" +>G++_include_flags Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>g++_include_flags</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="GXXLINKFLAGS" +>G++_link_flags Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>g++_link_flags</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="LIBSTDCXXINCLUDEFLAGS" +>Libstdc++_include_flags Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>libstdc++_include_flags</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="LIBSTDCXXLINKFLAGS" +>Libstdc++_link_flags Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>libstdc++_link_flags</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="GETMULTILIBS" +>Get_multilibs Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>get_multilibs</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="FINDBINUTILSPROG" +>Find_binutils_prog Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>find_binutils_prog</B +></CODE +>(<VAR +CLASS="PDPARAM" +>name</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>name</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="FINDGCC" +>Find_gcc Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>find_gcc</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="FINDGCJ" +>Find_gcj Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>find_gcj</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="FINDGXX" +>Find_g++ Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>find_g++</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="FINDG77" +>Find_g77 Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>find_g77</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="PROCESSMULTILIBOPTIONS" +>Process_multilib_options Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>process_multilib_options</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="ADDMULTILIBOPTION" +>Add_multilib_option Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>add_multilib_option</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="FINDGAS" +>Find_gas Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>find_gas</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="FINDLD" +>Find_ld Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>find_ld</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="BUILDWRAPPER" +>Build_wrapper Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>build_wrapper</B +></CODE +>(<VAR +CLASS="PDPARAM" +>gluefile</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>gluefile</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="WINSUPINCLUDEFLAGS" +>Winsup_include_flags Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>winsup_include_flags</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="WINSUPLINKFLAGS" +>Winsup_link_flags Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>winsup_link_flags</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="DEBUGPROCS" +>Procedures for debugging your Tcl code.</A +></H2 +><P +><TT +CLASS="FILENAME" +>lib/debugger.exp</TT +>defines these utility + procedures:</P +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="DUMPVARS" +>Dumpvars Procedure</A +></H3 +><P +>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 +CLASS="EMPHASIS" +>dv</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>dumpvars</B +></CODE +>(<VAR +CLASS="PDPARAM" +>vars</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>vars</I +></TT +></DT +><DD +><P +>The variables to dump.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="DUMPLOCALS" +>Dumplocals Procedure</A +></H3 +><P +>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 +CLASS="EMPHASIS" +>dl</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>dumplocals</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="DUMPROCS" +>Dumprocs Procedure</A +></H3 +><P +>This takes a csh style regular expression (glob rules) and + prints the body of all procs that match. It is abbreviated as + <I +CLASS="EMPHASIS" +>dp</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>dumprocs</B +></CODE +>(<VAR +CLASS="PDPARAM" +>pattern</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>pattern</I +></TT +></DT +><DD +><P +>The csh "glob" style pattern to look + for.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="DUMPWATCH" +>Dumpwatch Procedure</A +></H3 +><P +>This takes a csh style regular expression (glob rules) and + prints all the watchpoints. It is abbreviated as + <I +CLASS="EMPHASIS" +>dw</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>dumpwatch</B +></CODE +>(<VAR +CLASS="PDPARAM" +>pattern</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>pattern</I +></TT +></DT +><DD +><P +>The csh "glob" style pattern to look + for.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="WATCHARRAY" +>Watcharray Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>watcharray</B +></CODE +>(<VAR +CLASS="PDPARAM" +>element</VAR +> + <VAR +CLASS="PDPARAM" +>type</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>type</I +></TT +></DT +><DD +><P +>The csh "glob" style pattern to look + for.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="WATCHVAR" +>Watchvar Procedure</A +></H3 +><P +></P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>watchvar</B +></CODE +>(<VAR +CLASS="PDPARAM" +>var</VAR +> + <VAR +CLASS="PDPARAM" +>type</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +></I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="WATCHUNSET" +>Watchunset Procedure</A +></H3 +><P +>This breaks program execution when the variable + <SPAN +CLASS="SYMBOL" +>var</SPAN +> is unset. It is abbreviated as + <I +CLASS="EMPHASIS" +>wu</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>watchunset</B +></CODE +>(<VAR +CLASS="PDPARAM" +>arg</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="WATCHWRITE" +>Watchwrite Procedure</A +></H3 +><P +>This breaks program execution when the variable + <SPAN +CLASS="SYMBOL" +>var</SPAN +> is written. It is abbreviated as + <I +CLASS="EMPHASIS" +>ww</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>watchwrite</B +></CODE +>(<VAR +CLASS="PDPARAM" +>var</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>var</I +></TT +></DT +><DD +><P +>The variable to watch.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="WATCHREAD" +>Watchread Procedure</A +></H3 +><P +>This breaks program execution when the variable + <SPAN +CLASS="SYMBOL" +>var</SPAN +> is read. It is abbreviated as + <I +CLASS="EMPHASIS" +>wr</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>watchread</B +></CODE +>(<VAR +CLASS="PDPARAM" +>var</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>var</I +></TT +></DT +><DD +><P +>The variable to watch.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="WATCHDEL" +>Watchdel Procedure</A +></H3 +><P +>This deletes a the watchpoint from the watch list. It is + abbreviated as <I +CLASS="EMPHASIS" +>wd</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>watchdel</B +></CODE +>(<VAR +CLASS="PDPARAM" +>args</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>args</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="PRINT" +>Print Procedure</A +></H3 +><P +>This prints the value of the variable + <TT +CLASS="PARAMETER" +><I +>var</I +></TT +>. It is abbreviated as + <I +CLASS="EMPHASIS" +>p</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>print</B +></CODE +>(<VAR +CLASS="PDPARAM" +>var</VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +>var</I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +><DIV +CLASS="SECT3" +><H3 +CLASS="SECT3" +><A +NAME="QUIT" +>Quit Procedure</A +></H3 +><P +>This makes runtest exit. It is abbreviated as + <I +CLASS="EMPHASIS" +>q</I +>.</P +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><CODE +CLASS="FUNCDEF" +><B +CLASS="FSFUNC" +>quit</B +></CODE +>(<VAR +CLASS="PDPARAM" +></VAR +>);<P +></P +></DIV +><P +></P +><DL +><DT +><TT +CLASS="PARAMETER" +><I +></I +></TT +></DT +><DD +><P +></P +></DD +></DL +></DIV +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="reference.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="filemap.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Reference</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="reference.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>File Map</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/configfile.html b/doc/overview/configfile.html new file mode 100644 index 0000000..da718e5 --- /dev/null +++ b/doc/overview/configfile.html @@ -0,0 +1,513 @@ +<HTML +><HEAD +><TITLE +>Config File Values</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Customizing DejaGnu" +HREF="customizing.html"><LINK +REL="PREVIOUS" +TITLE="Remote Host Testing" +HREF="releng.html"><LINK +REL="NEXT" +TITLE="Extending DejaGnu" +HREF="extending.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="releng.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 3. Customizing DejaGnu</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="extending.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="CONFIGFILE" +>Config File Values</A +></H1 +><P +>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 <SPAN +CLASS="SYMBOL" +>target_info</SPAN +>, and it has two indices. The + following fields are part of the array.</P +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="OPTIONDEFS" +>Command Line Option Variables</A +></H2 +><P +>In the user editable second section of the <A +HREF="configfile.html#PERSONAL" +><I +>Personal Config File</I +></A +> you can not only override the configuration + variables captured in the first section, but also specify + default values for all on the <B +CLASS="COMMAND" +>runtest</B +> + command line options. Save for <TT +CLASS="OPTION" +>--debug</TT +>, + <TT +CLASS="OPTION" +>--help</TT +>, and <TT +CLASS="OPTION" +>--version</TT +>, each + command line option has an associated Tcl variable. Use the + Tcl <B +CLASS="COMMAND" +>set</B +> 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 + <TT +CLASS="FILENAME" +>site.exp</TT +>. <A +HREF="runtest.html#INVOKING" +><I +>Invoking Runtest</I +></A +>, for + explanations of the command-line options.</P +><P +><DIV +CLASS="TABLE" +><P +><B +>Table 3-1. Tcl Variables For Command Line Options</B +></P +><TABLE +BORDER="1" +CLASS="CALSTABLE" +><TR +><TH +ALIGN="LEFT" +VALIGN="TOP" +>runtest</TH +><TH +ALIGN="LEFT" +VALIGN="TOP" +>Tcl</TH +><TH +ALIGN="LEFT" +VALIGN="TOP" +>option</TH +><TH +ALIGN="LEFT" +VALIGN="TOP" +>variable</TH +><TH +ALIGN="LEFT" +VALIGN="TOP" +>description</TH +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>--all</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>all_flag</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>display all test results if set</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>--baud</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>baud</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>set the default baud rate to something other than + 9600.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>--connect</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>connectmode</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +><B +CLASS="COMMAND" +>rlogin</B +>, + <B +CLASS="COMMAND" +>telnet</B +>, <B +CLASS="COMMAND" +>rsh</B +>, + <B +CLASS="COMMAND" +>kermit</B +>, <B +CLASS="COMMAND" +>tip</B +>, or + <B +CLASS="COMMAND" +>mondfe</B +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>--outdir</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>outdir</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>directory for <TT +CLASS="FILENAME" +>tool.sum</TT +> and + <TT +CLASS="FILENAME" +>tool.log.</TT +></TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>--objdir</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>objdir</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>directory for pre-compiled binaries</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>--reboot</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>reboot</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>reboot the target if set to + <I +CLASS="EMPHASIS" +>"1"</I +>; do not reboot if set to + <I +CLASS="EMPHASIS" +>"0"</I +> (the default).</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>--srcdir</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>srcdir</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>directory of test subdirectories</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>--strace</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>tracelevel</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>a number: Tcl trace depth</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>--tool</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>tool</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>name of tool to test; identifies init, test subdir</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>--verbose</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>verbose</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>verbosity level. As option, use multiple times; as + variable, set a number, 0 or greater.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>--target</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>target_triplet</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>The canonical configuration string for the target.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>--host</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>host_triplet</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>The canonical configuration string for the host.</TD +></TR +><TR +><TD +ALIGN="LEFT" +VALIGN="TOP" +>--build</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>build_triplet</TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +>The canonical configuration string for the build + host.</TD +></TR +></TABLE +></DIV +> + </P +></DIV +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="PERSONAL" +>Personal Config File</A +></H2 +><P +>The personal config file is used to customize + <B +CLASS="COMMAND" +>runtest's</B +> behaviour for each person. It's + typically used to set the user prefered setting for verbosity, + and any experimental Tcl procedures. My personal + <TT +CLASS="FILENAME" +>~/.dejagnurc</TT +> file looks like:</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 3-12. Personal Config File</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> set all_flag 1 + set RLOGIN /usr/ucb/rlogin + set RSH /usr/local/sbin/ssh + </PRE +></TD +></TR +></TABLE +></DIV +><P +>Here I set <SPAN +CLASS="SYMBOL" +>all_flag</SPAN +> so I see all the test + cases that PASS along with the ones that FAIL. I also set + <SPAN +CLASS="SYMBOL" +>RLOGIN</SPAN +> to the BSD version. I have + <SPAN +CLASS="PRODUCTNAME" +>Kerberos</SPAN +> 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 <SPAN +CLASS="SYMBOL" +>RSH</SPAN +> to the <SPAN +CLASS="PRODUCTNAME" +>SSH</SPAN +> + secure shell, as rsh is mostly used to test unix + machines within a local network here.</P +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="releng.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="extending.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Remote Host Testing</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="customizing.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Extending DejaGnu</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/customizing.html b/doc/overview/customizing.html new file mode 100644 index 0000000..e42ce19 --- /dev/null +++ b/doc/overview/customizing.html @@ -0,0 +1,470 @@ +<HTML +><HEAD +><TITLE +>Customizing DejaGnu</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="PREVIOUS" +TITLE="The files DejaGnu produces." +HREF="outputfiles.html"><LINK +REL="NEXT" +TITLE="Global Config File" +HREF="global.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="outputfiles.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="global.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="CHAPTER" +><H1 +><A +NAME="CUSTOMIZING" +>Chapter 3. Customizing DejaGnu</A +></H1 +><DIV +CLASS="TOC" +><DL +><DT +><B +>Table of Contents</B +></DT +><DT +><A +HREF="customizing.html#LOCAL" +>Local Config File</A +></DT +><DT +><A +HREF="global.html" +>Global Config File</A +></DT +><DT +><A +HREF="boardconfig.html" +>Board Config File</A +></DT +><DT +><A +HREF="releng.html" +>Remote Host Testing</A +></DT +><DT +><A +HREF="configfile.html" +>Config File Values</A +></DT +></DL +></DIV +><P +>The site configuration file, <TT +CLASS="FILENAME" +>site.exp</TT +>, + captures configuration-dependent values and propagates them to the + DejaGnu test environment using Tcl variables. This ties the + DejaGnu test scripts into the <B +CLASS="COMMAND" +>configure</B +> and + <B +CLASS="COMMAND" +>make</B +> programs. If this file is setup correctly, + it is possible to execute a test suite merely by typing + <B +CLASS="COMMAND" +>runtest</B +>.</P +><P +>DejaGnu supports two <TT +CLASS="FILENAME" +>site.exp</TT +> + files. The multiple instances of <TT +CLASS="FILENAME" +>site.exp</TT +> are + loaded in a fixed order built into DejaGnu. The first file loaded + is the local file <TT +CLASS="FILENAME" +>site.exp</TT +>, and then the + optional global <TT +CLASS="FILENAME" +>site.exp</TT +> file as + pointed to by the <SPAN +CLASS="SYMBOL" +>DEJAGNU</SPAN +> environment + variable.</P +><P +>There is an optional <I +CLASS="EMPHASIS" +>master</I +> + <TT +CLASS="FILENAME" +>site.exp</TT +>, capturing configuration values that + apply to DejaGnu across the board, in each configuration-specific + subdirectory of the DejaGnu library directory. + <B +CLASS="COMMAND" +>runtest</B +> loads these values first. The master + <TT +CLASS="FILENAME" +>site.exp</TT +> contains the default values for all + targets and hosts supported by DejaGnu. This master file is + identified by setting the environment variable + <SPAN +CLASS="SYMBOL" +>DEJAGNU</SPAN +> to the name of the file. This is also + refered to as the ``global'' config file.</P +><P +>Any directory containing a configured test suite also has a + local <TT +CLASS="FILENAME" +>site.exp</TT +>, capturing configuration values + specific to the tool under test. Since <B +CLASS="COMMAND" +>runtest</B +> + loads these values last, the individual test configuration can + either rely on and use, or override, any of the global values from + the global <TT +CLASS="FILENAME" +>site.exp</TT +> file.</P +><P +>You can usually generate or update the testsuite's local + <TT +CLASS="FILENAME" +>site.exp</TT +> by typing <B +CLASS="COMMAND" +>make + site.exp</B +> in the test suite directory, after the test + suite is configured.</P +><P +>You can also have a file in your home directory called + <TT +CLASS="FILENAME" +>.dejagnurc</TT +>. This gets loaded first before the + other config files. Usually this is used for personal stuff, like + setting the <SPAN +CLASS="SYMBOL" +>all_flag</SPAN +> so all the output gets + printed, or your own verbosity levels. This file is usually + restricted to setting command line options.</P +><P +>You can further override the default values in a + user-editable section of any <TT +CLASS="FILENAME" +>site.exp</TT +>, or by + setting variables on the <B +CLASS="COMMAND" +>runtest</B +> command + line.</P +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="LOCAL" +>Local Config File</A +></H1 +><P +>It is usually more convenient to keep these <I +CLASS="EMPHASIS" +>manual + overrides</I +> in the <TT +CLASS="FILENAME" +>site.exp</TT +> + local to each test directory, rather than in the global + <TT +CLASS="FILENAME" +>site.exp</TT +> in the installed DejaGnu + library. This file is mostly for supplying tool specific info + that is required by the test suite.</P +><P +>All local <TT +CLASS="FILENAME" +>site.exp</TT +> files have + two sections, separated by comment text. The first section is + the part that is generated by <B +CLASS="COMMAND" +>make</B +>. It is + essentially a collection of Tcl variable definitions based on + <TT +CLASS="FILENAME" +>Makefile</TT +> environment variables. Since they + are generated by <B +CLASS="COMMAND" +>make</B +>, they contain the + values as specified by <B +CLASS="COMMAND" +>configure</B +>. (You can + also customize these values by using the <TT +CLASS="OPTION" +>--site</TT +> + option to <B +CLASS="COMMAND" +>configure</B +>.) In particular, this + section contains the <TT +CLASS="FILENAME" +>Makefile</TT +> + variables for host and target configuration data. Do not edit + this first section; if you do, your changes are replaced next + time you run <B +CLASS="COMMAND" +>make</B +>.</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 3-1. The first section starts with</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> ## these variables are automatically generated by make ## + # Do not edit here. If you wish to override these values + # add them to the last section + </PRE +></TD +></TR +></TABLE +></DIV +><P +>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 <B +CLASS="COMMAND" +>runtest</B +>. This allows you to + easily customize <B +CLASS="COMMAND" +>runtest</B +> 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.)</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 3-2. The first section ends with this line</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> ## All variables above are generated by configure. Do Not Edit ## + </PRE +></TD +></TR +></TABLE +></DIV +><P +>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 + <SPAN +CLASS="SYMBOL" +>host_triplet</SPAN +>, <SPAN +CLASS="SYMBOL" +>build_triplet</SPAN +>, + <SPAN +CLASS="SYMBOL" +>target_triplet</SPAN +>. All other variables are tool + dependant. ie for testing a compiler, the value for + <SPAN +CLASS="SYMBOL" +>CC</SPAN +> might be set to a freshly built binary, as + opposed to one in the user's path.</P +><P +>Here's an example local site.exp file, as used for + <SPAN +CLASS="PRODUCTNAME" +>GCC/G++</SPAN +> testing.</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 3-3. Local Config File</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> + ## these variables are automatically generated by make ## + # Do not edit here. If you wish to override these values + # add them to the last section + set rootme "/build/devo-builds/i586-pc-linux-gnulibc1/gcc" + set host_triplet i586-pc-linux-gnulibc1 + set build_triplet i586-pc-linux-gnulibc1 + set target_triplet i586-pc-linux-gnulibc1 + set target_alias i586-pc-linux-gnulibc1 + set CFLAGS "" + set CXXFLAGS "-I/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libio -I$srcdir/../libg++/src -I$srcdir/../libio -I$srcdir/../libstdc++ -I$srcdir/../libstdc++/stl -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libg++ -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libstdc++" + append LDFLAGS " -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../ld" + set tmpdir /build/devo-builds/i586-pc-linux-gnulibc1/gcc/testsuite + set srcdir "${srcdir}/testsuite" + ## All variables above are generated by configure. Do Not Edit ## + + </PRE +></TD +></TR +></TABLE +></DIV +><P +>This file defines the required fields for a local config + file, namely the three config triplets, and the srcdir. It also + defines several other Tcl variables that are used exclusivly by + the GCC test suite. For most test cases, the CXXFLAGS and LDFLAGS + are supplied by DejaGnu itself for cross testing, but to test a + compiler, GCC needs to manipulate these itself.</P +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="outputfiles.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="global.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>The files DejaGnu produces.</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Global Config File</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/debugging.html b/doc/overview/debugging.html new file mode 100644 index 0000000..9dc71f0 --- /dev/null +++ b/doc/overview/debugging.html @@ -0,0 +1,248 @@ +<HTML +><HEAD +><TITLE +>Debugging A Test Case</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Extending DejaGnu" +HREF="extending.html"><LINK +REL="PREVIOUS" +TITLE="Writing A Test Case" +HREF="writing.html"><LINK +REL="NEXT" +TITLE="Adding A Test Case To A Test Suite." +HREF="adding.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="writing.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 4. Extending DejaGnu</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="adding.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="DEBUGGING" +>Debugging A Test Case</A +></H1 +><P +>These are the kinds of debugging information available + from DejaGnu:</P +><P +></P +><UL +><LI +STYLE="list-style-type: disc" +><P +>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 + <B +CLASS="COMMAND" +>verbose</B +> procedure (which in turn uses the + variable also called <I +CLASS="EMPHASIS" +>verbose</I +>) 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 +CLASS="EMPHASIS" +>$verbose</I +> is + <I +CLASS="EMPHASIS" +>0</I +>, there should be no output other than the + output from <I +CLASS="EMPHASIS" +>pass</I +>, + <I +CLASS="EMPHASIS" +>fail</I +>, <I +CLASS="EMPHASIS" +>error</I +>, and + <I +CLASS="EMPHASIS" +>warning</I +>. Then, to whatever extent is + appropriate for the particular test, allow successively higher + values of <I +CLASS="EMPHASIS" +>$verbose</I +> to generate more + information. Be kind to other programmers who use your tests: + provide for a lot of debugging information.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>Output from the internal debugging functions of + Tcl and <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +>. There is a command + line options for each; both forms of debugging output are + recorded in the file <TT +CLASS="FILENAME" +>dbg.log</TT +> in the current + directory.</P +><P +>Use <TT +CLASS="OPTION" +>--debug</TT +> 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 + <TT +CLASS="FILENAME" +>dbg.log</TT +> can allow you to create the final + patterns by ``cut and paste''. This is sometimes the best way + to write a test case.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>Use <TT +CLASS="OPTION" +>--strace</TT +> 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.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>Finally, if the value of + <I +CLASS="EMPHASIS" +>verbose</I +> is 3 or greater,DejaGnu turns on + the expect command <B +CLASS="COMMAND" +>log_user</B +>. This command + prints all expect actions to the expect standard output, to the + detailed log file, and (if <TT +CLASS="OPTION" +>--debug</TT +> is on) to + <TT +CLASS="FILENAME" +>dbg.log</TT +>.</P +></LI +></UL +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="writing.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="adding.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Writing A Test Case</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="extending.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Adding A Test Case To A Test Suite.</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/designgoals.html b/doc/overview/designgoals.html new file mode 100644 index 0000000..d2d88a4 --- /dev/null +++ b/doc/overview/designgoals.html @@ -0,0 +1,219 @@ +<HTML +><HEAD +><TITLE +>Design Goals</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Overview" +HREF="overview.html"><LINK +REL="PREVIOUS" +TITLE="What's New In This Release" +HREF="new.html"><LINK +REL="NEXT" +TITLE="A POSIX conforming test framework" +HREF="posix.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="new.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 1. Overview</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="posix.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="DESIGNGOALS" +>Design Goals</A +></H1 +><P +>DejaGnu grew out of the internal needs of Cygnus Solutions. (then + Cygnus Support). Cygnus maintains and enhances a variety of free programs + in many different environments, and we needed a testing tool that:</P +><P +></P +><UL +><LI +STYLE="list-style-type: disc" +><P +>is useful to developers while fixing + bugs.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>automates running many tests during a software + release process.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>is portable among a variety of host + computers.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>supports cross-development + testing.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>permits testing interactive programs, like + <B +CLASS="COMMAND" +>GDB</B +>; and </P +></LI +><LI +STYLE="list-style-type: disc" +><P +>permits testing batch oriented programs, like + <B +CLASS="COMMAND" +>GCC</B +>.</P +></LI +></UL +><P +>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 <B +CLASS="COMMAND" +>GDB</B +> works as well when cross-debugging + as it does in a native configuration. </P +><P +>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 + <B +CLASS="COMMAND" +>rsh</B +>, <B +CLASS="COMMAND" +>rlogin</B +>, + <B +CLASS="COMMAND" +>telnet</B +>, <B +CLASS="COMMAND" +>tip</B +>, + <B +CLASS="COMMAND" +>kermit</B +>, and <B +CLASS="COMMAND" +>mondfe</B +> for remote + communications.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="new.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="posix.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>What's New In This Release</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="overview.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>A POSIX conforming test framework</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/docbook.css b/doc/overview/docbook.css new file mode 100755 index 0000000..b42fb27 --- /dev/null +++ b/doc/overview/docbook.css @@ -0,0 +1,20 @@ +.BOOK .TITLE { text-align: center } +.BOOK .SUBTITLE { text-align: center } +.BOOK .CORPAUTHOR { text-align: center } +.BOOK .AUTHOR { text-align: center } +.BOOK .AFFILIATION { text-align: center } +.BOOK .EDITEDBY { text-align: center } +.BOOK .EDITOR { text-align: center } +.BOOK .GRAPHIC { text-align: center } + +.ARTICLE .TITLE { text-align: center } +.ARTICLE .SUBTITLE { text-align: center } +.ARTICLE .CORPAUTHOR { text-align: center } +.ARTICLE .AUTHOR { text-align: center } +.ARTICLE .AFFILIATION { text-align: center } +.ARTICLE .EDITEDBY { text-align: center } +.ARTICLE .EDITOR { text-align: center } +.ARTICLE .GRAPHIC { text-align: center } +.ARTICLE .ABSTRACT { margin-left: 0.5in; + margin-right: 0.5in; + font-style: italic } diff --git a/doc/overview/extending.html b/doc/overview/extending.html new file mode 100644 index 0000000..4cce3b7 --- /dev/null +++ b/doc/overview/extending.html @@ -0,0 +1,206 @@ +<HTML +><HEAD +><TITLE +>Extending DejaGnu</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="PREVIOUS" +TITLE="Config File Values" +HREF="configfile.html"><LINK +REL="NEXT" +TITLE="Adding A New Tool" +HREF="addtool.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="configfile.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="addtool.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="CHAPTER" +><H1 +><A +NAME="EXTENDING" +>Chapter 4. Extending DejaGnu</A +></H1 +><DIV +CLASS="TOC" +><DL +><DT +><B +>Table of Contents</B +></DT +><DT +><A +HREF="extending.html#ADDSUITE" +>Adding A New Test Suite</A +></DT +><DT +><A +HREF="addtool.html" +>Adding A New Tool</A +></DT +><DT +><A +HREF="addtarget.html" +>Adding A New Target</A +></DT +><DT +><A +HREF="addboard.html" +>Adding A New Board</A +></DT +><DT +><A +HREF="boarddefs.html" +>Board Config File Values</A +></DT +><DT +><A +HREF="writing.html" +>Writing A Test Case</A +></DT +><DT +><A +HREF="debugging.html" +>Debugging A Test Case</A +></DT +><DT +><A +HREF="adding.html" +>Adding A Test Case To A Test Suite.</A +></DT +><DT +><A +HREF="hints.html" +>Hints On Writing A Test Case</A +></DT +><DT +><A +HREF="tvariables.html" +>Special variables used by test cases.</A +></DT +></DL +></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="ADDSUITE" +>Adding A New Test Suite</A +></H1 +><P +>The testsuite for a new tool should always be located in that tools + source directory. DejaGnu require the directory be named + <TT +CLASS="FILENAME" +>testsuite</TT +>. Under this directory, the test cases go + in a subdirectory whose name begins with the tool name. For example, for + a tool named <I +CLASS="EMPHASIS" +>flubber</I +>, each subdirectory containing + testsuites must start with <I +CLASS="EMPHASIS" +>"flubber."</I +>.</P +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="configfile.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="addtool.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Config File Values</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Adding A New Tool</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/filemap.html b/doc/overview/filemap.html new file mode 100644 index 0000000..bb894c9 --- /dev/null +++ b/doc/overview/filemap.html @@ -0,0 +1,222 @@ +<HTML +><HEAD +><TITLE +>File Map</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Reference" +HREF="reference.html"><LINK +REL="PREVIOUS" +TITLE="Builtin Procedures" +HREF="builtins.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="builtins.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 5. Reference</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +> </TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="FILEMAP" +>File Map</A +></H1 +><P +>This is a map of the files in DejaGnu.</P +><P +></P +><UL +><LI +><P +>runtest</P +></LI +><LI +><P +>runtest.exp</P +></LI +><LI +><P +>stub-loader.c</P +></LI +><LI +><P +>testglue.c</P +></LI +><LI +><P +>config</P +></LI +><LI +><P +>baseboards</P +></LI +><LI +><P +>lib/debugger.exp</P +></LI +><LI +><P +>lib/dg.exp</P +></LI +><LI +><P +>lib/framework.exp</P +></LI +><LI +><P +>lib/ftp.exp</P +></LI +><LI +><P +>lib/kermit.exp</P +></LI +><LI +><P +>lib/libgloss.exp</P +></LI +><LI +><P +>lib/mondfe.exp</P +></LI +><LI +><P +>lib/remote.exp</P +></LI +><LI +><P +>lib/rlogin.exp</P +></LI +><LI +><P +>lib/rsh.exp</P +></LI +><LI +><P +>lib/standard.exp</P +></LI +><LI +><P +>lib/target.exp</P +></LI +><LI +><P +>lib/targetdb.exp</P +></LI +><LI +><P +>lib/telnet.exp</P +></LI +><LI +><P +>lib/tip.exp</P +></LI +><LI +><P +>lib/util-defs.exp</P +></LI +><LI +><P +>lib/utils.exp</P +></LI +><LI +><P +>lib/xsh.exp</P +></LI +></UL +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="builtins.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +> </TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Builtin Procedures</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="reference.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +> </TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/global.html b/doc/overview/global.html new file mode 100644 index 0000000..cc102f3 --- /dev/null +++ b/doc/overview/global.html @@ -0,0 +1,245 @@ +<HTML +><HEAD +><TITLE +>Global Config File</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Customizing DejaGnu" +HREF="customizing.html"><LINK +REL="PREVIOUS" +TITLE="Customizing DejaGnu" +HREF="customizing.html"><LINK +REL="NEXT" +TITLE="Board Config File" +HREF="boardconfig.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="customizing.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 3. Customizing DejaGnu</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="boardconfig.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="GLOBAL" +>Global Config File</A +></H1 +><P +>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 + <I +CLASS="EMPHASIS" +>canadian cross</I +>. 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.</P +><P +>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.</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 3-4. Global Config file</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> # Make sure we look in the right place for the board description files. + if ![info exists boards_dir] { + set boards_dir {} + } + lappend boards_dir "/nfs/cygint/s1/cygnus/dejagnu/boards" + + verbose "Global Config File: target_triplet is $target_triplet" 2 + global target_list + + case "$target_triplet" in { + { "native" } { + set target_list "unix" + } + { "sparc64-*elf" } { + set target_list "sparc64-sim" + } + { "mips-*elf" } { + set target_list "mips-sim wilma barney" + } + { "mips-lsi-elf" } { + set target_list "mips-lsi-sim{,soft-float,el}" + } + { "sh-*hms" } { + set target_list { "sh-hms-sim" "bloozy" } + } + } + </PRE +></TD +></TR +></TABLE +></DIV +><P +>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.</P +><P +>As you can see, all one does is set the variable + <SPAN +CLASS="SYMBOL" +>target_list</SPAN +> to the list of targets and options to + test. The simple settings, like for + <I +CLASS="EMPHASIS" +>sparc64-elf</I +> only require setting the name of + the single board config file. The <I +CLASS="EMPHASIS" +>mips-elf</I +> + target is more complicated. Here it sets the list to three target + boards. One is the default mips target, and both + <I +CLASS="EMPHASIS" +>wilma</I +> <I +CLASS="EMPHASIS" +>barney</I +> are + symbolic names for other mips boards. Symbolic names are covered + in the <A +HREF="addboard.html" +><I +>Adding A New Board</I +></A +> chapter. The more complicated + example is the one for <I +CLASS="EMPHASIS" +>mips-lsi-elf</I +>. This one + runs the tests with multiple iterations using all possible + combinations of the <TT +CLASS="OPTION" +>--soft-float</TT +> and the + <TT +CLASS="OPTION" +>--el</TT +> (little endian) option. Needless to say, + this last feature is mostly compiler specific.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="customizing.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="boardconfig.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Customizing DejaGnu</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="customizing.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Board Config File</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/hints.html b/doc/overview/hints.html new file mode 100644 index 0000000..aaf59ee --- /dev/null +++ b/doc/overview/hints.html @@ -0,0 +1,258 @@ +<HTML +><HEAD +><TITLE +>Hints On Writing A Test Case</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Extending DejaGnu" +HREF="extending.html"><LINK +REL="PREVIOUS" +TITLE="Adding A Test Case To A Test Suite." +HREF="adding.html"><LINK +REL="NEXT" +TITLE="Special variables used by test cases." +HREF="tvariables.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="adding.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 4. Extending DejaGnu</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="tvariables.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="HINTS" +>Hints On Writing A Test Case</A +></H1 +><P +>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 <B +CLASS="COMMAND" +>expect</B +> + command. In this situation, the precise boundary that determines + which <B +CLASS="COMMAND" +>expect</B +> 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 + <TT +CLASS="OPTION" +>-re</TT +> option for the <B +CLASS="COMMAND" +>expect</B +> + command to write the pattern as a full regular expressions; then + you can match the end of output using a <I +CLASS="EMPHASIS" +>$</I +>. + It is also a good idea to write patterns that match all + available output by using <I +CLASS="EMPHASIS" +>.*\</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 +CLASS="EMPHASIS" +>\r</I +> or <I +CLASS="EMPHASIS" +>\n</I +>, but this is + usually too dependent on terminal settings.</P +><P +>Always escape punctuation, such as <I +CLASS="EMPHASIS" +>(</I +> + or <I +CLASS="EMPHASIS" +>"</I +>, in your patterns; for example, write + <I +CLASS="EMPHASIS" +>\(</I +>. If you forget to escape punctuation, + you will usually see an error message like <TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +>extra + characters after close-quote.</PRE +></TD +></TR +></TABLE +></P +><P +>If you have trouble understanding why a pattern does not + match the program output, try using the <TT +CLASS="OPTION" +>--debug</TT +> + option to <B +CLASS="COMMAND" +>runtest</B +>, and examine the debug log + carefully.</P +><P +>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 +CLASS="EMPHASIS" +>set height + 0\n</I +> command. The purpose is simply to make sure GDB + never calls a paging program. The <I +CLASS="EMPHASIS" +>set + height</I +> command in GDB does not generate any + output; but running any command makes GDB issue a new + <I +CLASS="EMPHASIS" +>(gdb) </I +> prompt. If there were no + <B +CLASS="COMMAND" +>expect</B +> command to match this prompt, the + output <I +CLASS="EMPHASIS" +>(gdb) </I +> begins the text seen by the + next <B +CLASS="COMMAND" +>expect</B +> command---which might make that + pattern fail to match.</P +><P +>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 + <B +CLASS="COMMAND" +>error</B +> or <B +CLASS="COMMAND" +>warning</B +>.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="adding.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="tvariables.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Adding A Test Case To A Test Suite.</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="extending.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Special variables used by test cases.</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/new.html b/doc/overview/new.html new file mode 100644 index 0000000..edf4c6d --- /dev/null +++ b/doc/overview/new.html @@ -0,0 +1,228 @@ +<HTML +><HEAD +><TITLE +>What's New In This Release</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Overview" +HREF="overview.html"><LINK +REL="PREVIOUS" +TITLE="Overview" +HREF="overview.html"><LINK +REL="NEXT" +TITLE="Design Goals" +HREF="designgoals.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="overview.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 1. Overview</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="designgoals.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="NEW" +>What's New In This Release</A +></H1 +><P +>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 + <SPAN +CLASS="PRODUCTNAME" +>iTcl</SPAN +> by the next release. Other changes + are:</P +><P +></P +><UL +><LI +><P +>More builtin support for building target binaries + with the correct linker flags. Currently this only works with + <SPAN +CLASS="PRODUCTNAME" +>GCC</SPAN +> as the cross compiler, + preferably with a target supported by + <A +HREF="builtins.html#LIBGLOSS" +><I +>Libgloss</I +></A +>.</P +></LI +><LI +><P +>Lots of little bug fixes from years of heavy + use at Cygnus Solutions.</P +></LI +><LI +><P +>DejaGnu now uses + <SPAN +CLASS="PRODUCTNAME" +>Automake</SPAN +> for Makefile + configuration.</P +></LI +><LI +><P +>Updated documentation, now in SGML + (using the <A +HREF="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html" +TARGET="_top" +>free + GNU DocBook tools</A +>) format.</P +></LI +><LI +><P +>NT support. There is beta level support for NT + that is still a work in progress. This requires the <A +HREF="http://sources.redhat.com" +TARGET="_top" +>Cygwin</A +> POSIX system + for NT.</P +></LI +></UL +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="CYGWIN" +>NT Support</A +></H2 +><P +>To use DejaGnu on NT, you need to first install the + <A +HREF="http://sources.redhat.com" +TARGET="_top" +>Cygwin</A +> + release. This works as of the B20.1 release. Cygwin is a POSIX + system for NT. This covers both utility programs, and a libray + that adds POSIX system calls to NT. Among them is pseudo tty + support for NT that emulates the POSIX pty standard. The + latest Cygwin is always available from <A +HREF="http://sources.redhat.com" +TARGET="_top" +>this location</A +>. This + works well enough to run <I +CLASS="EMPHASIS" +>"make check"</I +> of + the GNU development tree on NT after a native build. But the + nature of pty's on NT is still evolving. Your mileage may + vary...</P +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="overview.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="designgoals.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Overview</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="overview.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Design Goals</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> diff --git a/doc/overview/outputfiles.html b/doc/overview/outputfiles.html new file mode 100644 index 0000000..97931b3 --- /dev/null +++ b/doc/overview/outputfiles.html @@ -0,0 +1,596 @@ +<HTML +><HEAD +><TITLE +>The files DejaGnu produces.</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Running Tests" +HREF="runningtests.html"><LINK +REL="PREVIOUS" +TITLE="Runtest" +HREF="runtest.html"><LINK +REL="NEXT" +TITLE="Customizing DejaGnu" +HREF="customizing.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="runtest.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 2. Running Tests</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="customizing.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="OUTPUTFILES" +>The files DejaGnu produces.</A +></H1 +><P +>DejaGnu always writes two kinds of output files: summary + logs and detailed logs. The contents of both of these are + determined by your tests.</P +><P +>For troubleshooting, a third kind of output file is useful: + use <TT +CLASS="OPTION" +>--debug</TT +> to request an output file showing + details of what <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> is doing + internally.</P +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="SUM" +>Summary File</A +></H2 +><P +>DejaGnu always produces a summary output file + <TT +CLASS="FILENAME" +>tool.sum</TT +>. This summary shows the names of + all test files run; for each test file, one line of output from + each <B +CLASS="COMMAND" +>pass</B +> command (showing status + <I +CLASS="EMPHASIS" +>PASS</I +> or <I +CLASS="EMPHASIS" +>XPASS</I +>) or + <B +CLASS="COMMAND" +>fail</B +> command (status + <I +CLASS="EMPHASIS" +>FAIL</I +> or <I +CLASS="EMPHASIS" +>XFAIL</I +>); + 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 + <TT +CLASS="OPTION" +>--all</TT +>.)</P +><P +>If any of your tests use the procedures + <B +CLASS="COMMAND" +>unresolved</B +>, <B +CLASS="COMMAND" +>unsupported</B +>, + or <B +CLASS="COMMAND" +>runtested</B +>, the summary output also + tabulates the corresponding outcomes.</P +><P +>For example, after <B +CLASS="COMMAND" +>runtest --tool + binutils</B +>, look for a summary log in + <TT +CLASS="FILENAME" +>binutils.sum</TT +>. Normally, DejaGnu writes this + file in your current working directory; use the + <TT +CLASS="OPTION" +>--outdir</TT +> option to select a different + directory.</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 2-1. Here is a short sample summary log</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="SCREEN" +> Test Run By rob on Mon May 25 21:40:57 PDT 1992 + === gdb tests === + Running ./gdb.t00/echo.exp ... + PASS: Echo test + Running ./gdb.all/help.exp ... + PASS: help add-symbol-file + PASS: help aliases + PASS: help breakpoint "bre" abbreviation + FAIL: help run "r" abbreviation + Running ./gdb.t10/crossload.exp ... + PASS: m68k-elf (elf-big) explicit format; loaded + XFAIL: mips-ecoff (ecoff-bigmips) "ptype v_signed_char" signed C types + === gdb Summary === + # of expected passes 5 + # of expected failures 1 + # of unexpected failures 1 + /usr/latest/bin/gdb version 4.6.5 -q + </PRE +></TD +></TR +></TABLE +></DIV +></DIV +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="LOG" +>Log File</A +></H2 +><P +>DejaGnu also saves a detailed log file + <TT +CLASS="FILENAME" +>tool.log</TT +>, showing any output generated by + tests as well as the summary output. For example, after + <B +CLASS="COMMAND" +>runtest --tool binutils</B +>, look for a detailed + log in <TT +CLASS="FILENAME" +>binutils.log</TT +>. Normally, DejaGnu + writes this file in your current working directory; use the + <TT +CLASS="OPTION" +>--outdir</TT +> option to select a different + directory.</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 2-2. Here is a brief example showing a detailed log for + <SPAN +CLASS="PRODUCTNAME" +>G++</SPAN +> tests</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="SCREEN" +> Test Run By rob on Mon May 25 21:40:43 PDT 1992 + + === g++ tests === + + --- Running ./g++.other/t01-1.exp --- + PASS: operate delete + + --- Running ./g++.other/t01-2.exp --- + FAIL: i960 bug EOF + p0000646.C: In function `int warn_return_1 ()': + p0000646.C:109: warning: control reaches end of non-void function + p0000646.C: In function `int warn_return_arg (int)': + p0000646.C:117: warning: control reaches end of non-void function + p0000646.C: In function `int warn_return_sum (int, int)': + p0000646.C:125: warning: control reaches end of non-void function + p0000646.C: In function `struct foo warn_return_foo ()': + p0000646.C:132: warning: control reaches end of non-void function + + --- Running ./g++.other/t01-4.exp --- + FAIL: abort + 900403_04.C:8: zero width for bit-field `foo' + --- Running ./g++.other/t01-3.exp --- + FAIL: segment violation + 900519_12.C:9: parse error before `;' + 900519_12.C:12: Segmentation violation + /usr/latest/bin/gcc: Internal compiler error: program cc1plus got fatal signal + + === g++ Summary === + + # of expected passes 1 + # of expected failures 3 + /usr/latest/bin/g++ version cygnus-2.0.1 + </PRE +></TD +></TR +></TABLE +></DIV +></DIV +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="DEBUGFILE" +>Debug Log File</A +></H2 +><P +>With the <TT +CLASS="OPTION" +>--debug</TT +> option, you can request + a log file showing the output from + <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> itself, running in debugging + mode. This file (<TT +CLASS="FILENAME" +>dbg.log</TT +>, in the directory + where you start <B +CLASS="COMMAND" +>runtest</B +>) shows each pattern + <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> considers in analyzing test + output.</P +><P +>This file reflects each <B +CLASS="COMMAND" +>send</B +> command, + showing the string sent as input to the tool under test; and + each <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> command, showing each + pattern it compares with the tool output.</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 2-3. The log messages begin with a message of the form</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="SCREEN" +> expect: does {<SPAN +CLASS="SYMBOL" +>tool output</SPAN +>} (spawn_id <SPAN +CLASS="SYMBOL" +>n</SPAN +>) + match pattern {<I +CLASS="EMPHASIS" +>expected pattern</I +>}? + + </PRE +></TD +></TR +></TABLE +></DIV +><P +>For every unsuccessful match, + <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> issues a + <I +CLASS="EMPHASIS" +>no</I +> after this message; if other patterns + are specified for the same <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> + command, they are reflected also, but without the first part of + the message (<I +CLASS="EMPHASIS" +>expect... match pattern</I +>).</P +><P +>When <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> finds a match, the + log for the successful match ends with <I +CLASS="EMPHASIS" +>yes</I +>, + followed by a record of the <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> + variables set to describe a successful match.</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 2-4. Here is an excerpt from the debugging log for a + <SPAN +CLASS="PRODUCTNAME" +>GDB</SPAN +> test:</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="SCREEN" +> send: sent {break gdbme.c:34\n} to spawn id 6 + expect: does {} (spawn_id 6) match pattern {Breakpoint.*at.* file + gdbme.c, line 34.*\(gdb\) $}? no + {.*\(gdb\) $}? no + expect: does {} (spawn_id 0) match pattern {return} ? no + {\(y or n\) }? no + {buffer_full}? no + {virtual}? no + {memory}? no + {exhausted}? no + {Undefined}? no + {command}? no + break gdbme.c:34 + Breakpoint 8 at 0x23d8: file gdbme.c, line 34. + (gdb) expect: does {break gdbme.c:34\r\nBreakpoint 8 at 0x23d8: + file gdbme.c, line 34.\r\n(gdb) } (spawn_id 6) match pattern + {Breakpoint.*at.* file gdbme.c, line 34.*\(gdb\) $}? yes + expect: set expect_out(0,start) {18} + expect: set expect_out(0,end) {71} + expect: set expect_out(0,string) {Breakpoint 8 at 0x23d8: file + gdbme.c, line 34.\r\n(gdb) } + epect: set expect_out(spawn_id) {6} + expect: set expect_out(buffer) {break gdbme.c:34\r\nBreakpoint 8 + at 0x23d8: file gdbme.c, line 34.\r\n(gdb) } + PASS: 70 0 breakpoint line number in file + </PRE +></TD +></TR +></TABLE +></DIV +><P +>This example exhibits three properties of + <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> and + <SPAN +CLASS="PRODUCTNAME" +>DejaGnu</SPAN +> that might be surprising at + first glance:</P +><P +></P +><UL +><LI +STYLE="list-style-type: disc" +><P +>Empty output for the first attempted match. The + first set of attempted matches shown ran against the output + <I +CLASS="EMPHASIS" +>{}</I +> --- that is, no + output. <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> 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).</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>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 +CLASS="EMPHASIS" +>{(gdb) }</I +> + appears on the same line, just before the + <I +CLASS="EMPHASIS" +>expect:</I +> that marks the beginning of the + log entry.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>Fail-safe patterns. Many of the patterns + tested are fail-safe patterns provided by + <SPAN +CLASS="PRODUCTNAME" +>GDB</SPAN +> testing utilities, to reduce + possible indeterminacy. It is useful to anticipate potential + variations caused by extreme system conditions + (<SPAN +CLASS="PRODUCTNAME" +>GDB</SPAN +> might issue the message + <I +CLASS="EMPHASIS" +>virtual memory exhausted</I +> in rare + circumstances), or by changes in the tested program + (<I +CLASS="EMPHASIS" +>Undefined command</I +> is the likeliest + outcome if the name of a tested command changes).</P +><P +>The pattern <I +CLASS="EMPHASIS" +>{return}</I +> is a + particularly interesting fail-safe to notice; it checks for an + unexpected <B +CLASS="KEYCAP" +>RET</B +> prompt. This may happen, + for example, if the tested tool can filter output through a + pager.</P +><P +>These fail-safe patterns (like the debugging log itself) + are primarily useful while developing test scripts. Use the + <B +CLASS="COMMAND" +>error</B +> procedure to make the actions for + fail-safe patterns produce messages starting with + <I +CLASS="EMPHASIS" +>ERROR</I +> on standard output, and in the + detailed log file.</P +></LI +></UL +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="runtest.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="customizing.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Runtest</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="runningtests.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Customizing DejaGnu</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/overview.html b/doc/overview/overview.html new file mode 100644 index 0000000..6be010f --- /dev/null +++ b/doc/overview/overview.html @@ -0,0 +1,279 @@ +<HTML +><HEAD +><TITLE +>Overview</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="PREVIOUS" +TITLE="Abstract" +HREF="preface.html"><LINK +REL="NEXT" +TITLE="What's New In This Release" +HREF="new.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="preface.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="new.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="CHAPTER" +><H1 +><A +NAME="OVERVIEW" +>Chapter 1. Overview</A +></H1 +><DIV +CLASS="TOC" +><DL +><DT +><B +>Table of Contents</B +></DT +><DT +><A +HREF="overview.html#WHATIS" +>What is DejaGnu ?</A +></DT +><DT +><A +HREF="new.html" +>What's New In This Release</A +></DT +><DT +><A +HREF="designgoals.html" +>Design Goals</A +></DT +><DT +><A +HREF="posix.html" +>A POSIX conforming test framework</A +></DT +></DL +></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="WHATIS" +>What is DejaGnu ?</A +></H1 +><P +><SPAN +CLASS="PRODUCTNAME" +>DejaGnu</SPAN +> 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 +CLASS="EMPHASIS" +>Test Harness</I +> is the testing + infrastructure that is created to support a specific program + or tool. Each program can have multiple test suites, all + supported by a single test harness. DejaGnu is written in + <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +>, which in turn uses + <SPAN +CLASS="PRODUCTNAME" +>Tcl</SPAN +> -- Tool command + language. There is more information on Tcl at the <A +HREF="http://www.scriptics.com" +TARGET="_top" +>Scriptics</A +> web site, and the + Expect web site is at <A +HREF="http://expect.nist.gov" +TARGET="_top" +>NIST</A +>.</P +><P +>DejaGnu offers several advantages for testing:</P +><P +></P +><UL +COMPACT="COMPACT" +><LI +STYLE="list-style-type: disc" +><P +>The flexibility and consistency of the DejaGnu + framework make it easy to write tests for any program, with + either batch oriented, or interactive programs.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>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 <B +CLASS="COMMAND" +>GDB</B +> can run (from any Unix + based host) on any target architecture that DejaGnu + supports. Currently DejaGnu runs tests on many single board + computers, whose operating software ranges from just a boot + monitor to a full-fledged, Unix-like realtime OS.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>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.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>Using Tcl and expect, it's easy to create wrappers + for existing test suites. By incorporating existing tests under + DejaGnu, it's easier to have a single set of report analyse + programs..</P +></LI +></UL +><P +>Running tests requires two things: the testing framework, and + the test suites themselves. Tests are usually written in + <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> using Tcl, but you can also use a + Tcl script to run a test suite that is not based on + <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +>. + (<SPAN +CLASS="PRODUCTNAME" +>expect</SPAN +> script filenames conventionally + use <I +CLASS="EMPHASIS" +>.exp</I +> as a suffix; for example, the main + implementation of the DejaGnu test driver is in the file + <SPAN +CLASS="PRODUCTNAME" +>runtest.exp</SPAN +>.)</P +><P +>Julia Menapace first coined the term ``Deja Gnu'' to describe an + earlier testing framework at Cygnus Support she had written for + <B +CLASS="COMMAND" +>GDB</B +>. When we replaced it with the Expect-based + framework, it was like DejaGnu all over again... But more importantly, it + was also named after my daughter,<A +HREF="mailto:deja@welcomehome.org" +TARGET="_top" +>Deja Snow Savoye</A +> (now 9 + years old in Dec of 1998), who was a toddler during DejaGnu's + creation.</P +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="preface.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="new.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Abstract</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>What's New In This Release</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/posix.html b/doc/overview/posix.html new file mode 100644 index 0000000..4a35a55 --- /dev/null +++ b/doc/overview/posix.html @@ -0,0 +1,365 @@ +<HTML +><HEAD +><TITLE +>A POSIX conforming test framework</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Overview" +HREF="overview.html"><LINK +REL="PREVIOUS" +TITLE="Design Goals" +HREF="designgoals.html"><LINK +REL="NEXT" +TITLE="Running Tests" +HREF="runningtests.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="designgoals.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 1. Overview</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="runningtests.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="POSIX" +>A POSIX conforming test framework</A +></H1 +><P +>DejaGnu conforms to the POSIX 1003.3 standard for test + frameworks. I was also a member of that committe.</P +><P +>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.</P +><P +>The POSIX documentation refers to <I +CLASS="FIRSTTERM" +>assertions</I +>. + 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.</P +><P +>As there is no test suite to test testing frameworks for POSIX + 1003.3 conformance, verifying conformance to this standard is done by + repeatedly reading the standard and experimenting. One of the main + things 1003.3 does specify is the set of allowed output messages, and + their definitions. Four messages are supported for a required feature of + POSIX conforming systems, and a fifth for a conditional feature. DejaGnu + supports the use of all five output messages; in this sense a test suite + that uses exactly these messages can be considered POSIX conforming. + These definitions specify the output of a test + case:</P +><P +></P +><DL +><DT +>PASS</DT +><DD +><P +>A test has succeeded. That is, it demonstrated that + the assertion is true.</P +></DD +><DT +>XFAIL</DT +><DD +><P +>POSIX 1003.3 does not incorporate the notion of + expected failures, so <I +CLASS="EMPHASIS" +>PASS</I +>, instead of + <I +CLASS="EMPHASIS" +>XPASS</I +>, must also be returned for test cases + which were expected to fail and did not. This means that + <I +CLASS="EMPHASIS" +>PASS</I +> is in some sense more ambiguous than if + <I +CLASS="EMPHASIS" +>XPASS</I +> is also used.</P +></DD +><DT +>FAIL</DT +><DD +><P +>A test has produced the bug it was intended to + capture. That is, it has demonstrated that the assertion is false. + The <I +CLASS="EMPHASIS" +>FAIL</I +> message is based on the test case only. + Other messages are used to indicate a failure of the framework. As + with <I +CLASS="EMPHASIS" +>PASS</I +>, POSIX tests must return + <I +CLASS="EMPHASIS" +>FAIL</I +> rather than <I +CLASS="EMPHASIS" +>XFAIL</I +> even + if a failure was expected.</P +></DD +><DT +>UNRESOLVED</DT +><DD +><P +>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 +CLASS="EMPHASIS" +>PASS</I +> or <I +CLASS="EMPHASIS" +>FAIL</I +> before a test + run can be considered finished.</P +><P +>Note that for POSIX, each assertion must produce a test result + code. If the test isn't actually run, it must produce + <I +CLASS="EMPHASIS" +>UNRESOLVED</I +> 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 + <I +CLASS="EMPHASIS" +>return</I +>---if you alter the flow of control of the + tcl code you must insure that every test still produces some result + code.</P +><P +>Here are some of the ways a test may wind up + <I +CLASS="EMPHASIS" +>UNRESOLVED</I +>:</P +></DD +></DL +><P +></P +><UL +><LI +STYLE="list-style-type: disc" +><P +>A test's execution is + interrupted.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>A test does not produce a clear + result. This is usually because there was an + <I +CLASS="EMPHASIS" +>ERROR</I +> from DejaGnu while processing + the test, or because there were three or more + <I +CLASS="EMPHASIS" +>WARNING</I +> messages. Any + <I +CLASS="EMPHASIS" +>WARNING</I +> or <I +CLASS="EMPHASIS" +>ERROR</I +> + 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.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>A test depends on a previous test, which + fails.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>The test was set up + incorrectly.</P +></LI +></UL +><P +></P +><DL +><DT +>UNTESTED</DT +><DD +><P +>A test was not run. This is a placeholder, used + when there is no real test case yet.</P +></DD +></DL +><P +>The only remaining output message left is intended to test + features that are specified by the applicable POSIX standard as + conditional:</P +><P +></P +><DL +><DT +>UNSUPPORTED</DT +><DD +><P +>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 +CLASS="EMPHASIS" +>gethostname</I +> + would never work on a target board running only a boot + monitor.</P +></DD +></DL +><P +>DejaGnu uses the same output procedures to produce these messages + for all test suites, and these procedures are already known to conform + to POSIX 1003.3. For a DejaGnu test suite to conform to POSIX 1003.3, + you must avoid the <I +CLASS="EMPHASIS" +>setup</I +>xfail} procedure as + described in the <I +CLASS="EMPHASIS" +>PASS</I +> section above, and you must + be careful to return <I +CLASS="EMPHASIS" +>UNRESOLVED</I +> where appropriate, + as described in the <I +CLASS="EMPHASIS" +>UNRESOLVED</I +> section + above.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="designgoals.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="runningtests.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Design Goals</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="overview.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Running Tests</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/preface.html b/doc/overview/preface.html new file mode 100644 index 0000000..acceb36 --- /dev/null +++ b/doc/overview/preface.html @@ -0,0 +1,157 @@ +<HTML +><HEAD +><TITLE +>Abstract</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="PREVIOUS" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="NEXT" +TITLE="Overview" +HREF="overview.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="book1.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="overview.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="PREFACE" +><H1 +><A +NAME="PREFACE" +>Abstract</A +></H1 +><P +>This document attempts to describe the functionality of + DejaGnu, the GNU Testing Framework. DejaGnu is entirely written in + <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +>, which uses + <SPAN +CLASS="PRODUCTNAME" +>Tcl</SPAN +> as a command + language. <SPAN +CLASS="PRODUCTNAME" +>Expect</SPAN +> serves as a very + programmable shell; you can run any program, as with the usual + Unix command shells---but once the program is started, your + test script has fully programmable control of + its input and output. This does not just apply to the programs + under test; <B +CLASS="COMMAND" +>expect</B +> can also run any auxiliary + program, such as <B +CLASS="COMMAND" +>diff</B +> or <B +CLASS="COMMAND" +>sh</B +>, + with full control over its input and output.</P +><P +>DejaGnu itself is merely a framework for creation of a test + suites. Test suites are distributed separately for each GNU + tool.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="book1.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="overview.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>DejaGnu</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Overview</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/reference.html b/doc/overview/reference.html new file mode 100644 index 0000000..9c2f57b --- /dev/null +++ b/doc/overview/reference.html @@ -0,0 +1,373 @@ +<HTML +><HEAD +><TITLE +>Reference</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="PREVIOUS" +TITLE="Special variables used by test cases." +HREF="tvariables.html"><LINK +REL="NEXT" +TITLE="Builtin Procedures" +HREF="builtins.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="tvariables.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="builtins.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="CHAPTER" +><H1 +><A +NAME="REFERENCE" +>Chapter 5. Reference</A +></H1 +><DIV +CLASS="TOC" +><DL +><DT +><B +>Table of Contents</B +></DT +><DT +><A +HREF="reference.html#INSTALLATION" +>Installation</A +></DT +><DT +><A +HREF="builtins.html" +>Builtin Procedures</A +></DT +><DT +><A +HREF="filemap.html" +>File Map</A +></DT +></DL +></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="INSTALLATION" +>Installation</A +></H1 +><P +>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.</P +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="CONFIGURING" +>Configuring DejaGnu</A +></H2 +><P +>It is usually best to configure in a directory separate from the + source tree, specifying where to find the source with the optional + <I +CLASS="EMPHASIS" +>--srcdir</I +> option to + <I +CLASS="EMPHASIS" +>configure</I +>. DejaGnu uses the GNU + <I +CLASS="EMPHASIS" +>autoconf</I +> to configure itself. For more info on using + autoconf, read the GNU autoconf manual. To configure, execute the + <TT +CLASS="FILENAME" +>configure</TT +> 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:</P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="SCREEN" +> ../dejagnu-1.4/configure + </PRE +></TD +></TR +></TABLE +><P +>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.</P +><P +>You may also want to use the <B +CLASS="COMMAND" +>configure</B +> option + <I +CLASS="EMPHASIS" +>--prefix</I +> to specify where you want DejaGnu and its + supporting code installed. By default, installation is in subdirectories + of <TT +CLASS="FILENAME" +>/usr/local</TT +>, but you can select any alternate + directory <SPAN +CLASS="SYMBOL" +>altdir</SPAN +> by including + <TT +CLASS="OPTION" +>--prefix</TT +>{altdir}} on the + <B +CLASS="COMMAND" +>configure</B +> command line. (This value is captured in + the Makefile variables <I +CLASS="EMPHASIS" +>prefix</I +> and + <I +CLASS="EMPHASIS" +>exec</I +>prefix}.)</P +><P +>Save for a small number of example tests, the DejaGnu distribution + itself does not include any test suites; these are available + separately. Test suites for the GNU development tools are included in + those releases. After configuring the top-level DejaGnu directory, unpack + and configure the test directories for the tools you want to test; then, + in each test directory, run <I +CLASS="EMPHASIS" +>make check</I +> to build + auxiliary programs required by some of the tests, and run the test + suites.</P +></DIV +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="INSTALLING" +>Installing DejaGnu</A +></H2 +><P +>To install DejaGnu in your filesystem (either in + <TT +CLASS="FILENAME" +>/usr/local</TT +>, or as specified by your + <I +CLASS="EMPHASIS" +>--prefix</I +> option to <I +CLASS="EMPHASIS" +>configure</I +>), + execute.</P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="SCREEN" +> eg$ make install + </PRE +></TD +></TR +></TABLE +><P +><I +CLASS="EMPHASIS" +>make install</I +>does thes things for + DejaGnu:</P +><P +></P +><UL +><LI +STYLE="list-style-type: disc" +><P +>Look in the path specified for executables + <SPAN +CLASS="SYMBOL" +>$exec_prefix</SPAN +>) for directories called + <TT +CLASS="FILENAME" +>lib</TT +> and <TT +CLASS="FILENAME" +>bin</TT +>. If these + directories do not exist, <I +CLASS="EMPHASIS" +>make install</I +> creates + them.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>Create another directory in the + <TT +CLASS="FILENAME" +>share</TT +> directory, called + <TT +CLASS="FILENAME" +>dejagnu</TT +>, and copy all the library files into + it.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>Create a directory in the + <TT +CLASS="FILENAME" +>dejagnu/share</TT +> directory, called + <TT +CLASS="FILENAME" +>config</TT +>, and copy all the configuration files into + it.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>Copy the <I +CLASS="EMPHASIS" +>runtest</I +> shell script into + <TT +CLASS="FILENAME" +>$exec_prefix/bin</TT +>.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>Copy <TT +CLASS="FILENAME" +>runtest.exp</TT +> into + <TT +CLASS="FILENAME" +>$exec_prefix/lib/dejagnu</TT +>. This is the main Tcl + code implementing DejaGnu.</P +></LI +></UL +></DIV +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="tvariables.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="builtins.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Special variables used by test cases.</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Builtin Procedures</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/releng.html b/doc/overview/releng.html new file mode 100644 index 0000000..58f9cd4 --- /dev/null +++ b/doc/overview/releng.html @@ -0,0 +1,354 @@ +<HTML +><HEAD +><TITLE +>Remote Host Testing</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Customizing DejaGnu" +HREF="customizing.html"><LINK +REL="PREVIOUS" +TITLE="Board Config File" +HREF="boardconfig.html"><LINK +REL="NEXT" +TITLE="Config File Values" +HREF="configfile.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="boardconfig.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 3. Customizing DejaGnu</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="configfile.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="RELENG" +>Remote Host Testing</A +></H1 +><DIV +CLASS="NOTE" +><BLOCKQUOTE +CLASS="NOTE" +><P +><B +>Note: </B +>Thanks to Dj Delorie for the original paper that + this section is based on.</P +></BLOCKQUOTE +></DIV +><P +>DejaGnu also supports running the tests on a remote + host. To set this up, the remote host needs an ftp server, and a + telnet server. Currently foreign operating systems used as + remote hosts are VxWorks, VRTX, Dos/Win3.1, MacOS, and + win95/win98/NT.</P +><P +>The recommended source for a win95/win98/NT based ftp + server is to get IIS (either IIS 1 or Personal Web Server) from + <A +HREF="http://www.microsoft.com" +TARGET="_top" +>http://www.microsoft.com</A +>. + 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.</P +><P +>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.</P +><P +>You'll also need a telnet server. For win95/win98/NT, go + to the <A +HREF="http://ataman.com" +TARGET="_top" +>Ataman</A +> 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.</P +><P +>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.</P +><P +>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:</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 3-6. Remote host setup</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="SCREEN" +> cd /usr/local/swamp/testing + mkdir boards + scp darkstar.welcomehome.org:/dejagnu/cst/bin/MkTestDir . + scp darkstar.welcomehome.org:/dejagnu/site.exp . + scp darkstar.welcomehome.org:/dejagnu/boards/useless98r2.exp boards/foobar.exp + export DEJAGNU=/usr/local/swamp/testing/site.exp + + </PRE +></TD +></TR +></TABLE +></DIV +><P +>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.</P +><P +>Edit the global <TT +CLASS="FILENAME" +> site.exp</TT +> to reflect your + boards directory:</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 3-7. Add The Board Directory</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> lappend boards_dir "/usr/local/swamp/testing/boards" + </PRE +></TD +></TR +></TABLE +></DIV +><P +>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:</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 3-8. Setup Cross Remote Testing</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> ./MkTestDir sh-hms /usr/dejagnu/src/devo + </PRE +></TD +></TR +></TABLE +></DIV +><P +>If you are testing a native PC compiler (ex: you have + gcc.exe in your PATH on the PC), do this:</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 3-9. Setup Native Remote Testing</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> ./MkTestDir '' /usr/dejagnu/src/devo + </PRE +></TD +></TR +></TABLE +></DIV +><P +>To test the setup, <B +CLASS="COMMAND" +>ftp</B +> 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.</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 3-10. Run Test Remotely</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> cd /usr/local/swamp/testing + make -k -w check RUNTESTFLAGS="--host_board foobar --target_board foobar -v -v" > check.out 2>&1 + </PRE +></TD +></TR +></TABLE +></DIV +><P +>To run a specific test, use a command like this (for + this example, you'd run this from the gcc directory that + MkTestDir created):</P +><DIV +CLASS="EXAMPLE" +><P +><B +>Example 3-11. Run a Test Remotely</B +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> make check RUNTESTFLAGS="--host_board sloth --target_board sloth -v compile.exp=921202-1.c" + </PRE +></TD +></TR +></TABLE +></DIV +><P +>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.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="boardconfig.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="configfile.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Board Config File</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="customizing.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Config File Values</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/runningtests.html b/doc/overview/runningtests.html new file mode 100644 index 0000000..54e3291 --- /dev/null +++ b/doc/overview/runningtests.html @@ -0,0 +1,257 @@ +<HTML +><HEAD +><TITLE +>Running Tests</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="PREVIOUS" +TITLE="A POSIX conforming test framework" +HREF="posix.html"><LINK +REL="NEXT" +TITLE="Runtest" +HREF="runtest.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="posix.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="runtest.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="CHAPTER" +><H1 +><A +NAME="RUNNINGTESTS" +>Chapter 2. Running Tests</A +></H1 +><DIV +CLASS="TOC" +><DL +><DT +><B +>Table of Contents</B +></DT +><DT +><A +HREF="runningtests.html#MAKECHECK" +>Make check</A +></DT +><DT +><A +HREF="runtest.html" +>Runtest</A +></DT +><DT +><A +HREF="outputfiles.html" +>The files DejaGnu produces.</A +></DT +></DL +></DIV +><P +>There are two ways to execute a test suite. The most + common way is when there is existing support in the + <TT +CLASS="FILENAME" +>Makefile</TT +>. This support consists of a + <I +CLASS="EMPHASIS" +>check</I +> target. The other way is to execute the + <B +CLASS="COMMAND" +>runtest</B +> program directly. To run + <B +CLASS="COMMAND" +>runtest</B +> directcly from the command line requires + either all the correct options, or the <A +HREF="customizing.html#LOCAL" +><I +>Local Config File</I +></A +> must be setup + correctly.</P +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="MAKECHECK" +>Make check</A +></H1 +><P +>To run tests from an existing collection, first use + <B +CLASS="COMMAND" +>configure</B +> as usual to set up the + build directory. Then try typing:</P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="SCREEN" +> make check + </PRE +></TD +></TR +></TABLE +><P +>If the <I +CLASS="EMPHASIS" +>check</I +> 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 +CLASS="EMPHASIS" +>site.exp</I +>. 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.</P +><P +>The <I +CLASS="EMPHASIS" +>check</I +> target is supported by GNU + <SPAN +CLASS="PRODUCTNAME" +>Automake</SPAN +>. To have DejaGnu support added to your + generated <TT +CLASS="FILENAME" +>Makefile.in</TT +>, just add the keyword + dejagnu to the AUTOMAKE_OPTIONS variable in your + <TT +CLASS="FILENAME" +>Makefile.am</TT +> file.</P +><P +>Once you have run <I +CLASS="EMPHASIS" +>make check</I +> to build + any auxiliary files, you can invoke the test driver + <B +CLASS="COMMAND" +>runtest</B +> directly to repeat the tests. + You will also have to execute <B +CLASS="COMMAND" +>runtest</B +> + directly for test collections with no + <I +CLASS="EMPHASIS" +>check</I +> target in the + <TT +CLASS="FILENAME" +>Makefile</TT +>.</P +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="posix.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="runtest.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>A POSIX conforming test framework</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Runtest</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/runtest.html b/doc/overview/runtest.html new file mode 100644 index 0000000..8188e4b --- /dev/null +++ b/doc/overview/runtest.html @@ -0,0 +1,1142 @@ +<HTML +><HEAD +><TITLE +>Runtest</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Running Tests" +HREF="runningtests.html"><LINK +REL="PREVIOUS" +TITLE="Running Tests" +HREF="runningtests.html"><LINK +REL="NEXT" +TITLE="The files DejaGnu produces." +HREF="outputfiles.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="runningtests.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 2. Running Tests</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="outputfiles.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="RUNTEST" +>Runtest</A +></H1 +><P +><B +CLASS="COMMAND" +>runtest</B +> is the executable test driver + for DejaGnu. You can specify two kinds of things on the + <B +CLASS="COMMAND" +>runtest</B +> command line: command line options, + and Tcl variables for the test scripts. The options are listed + alphabetically below.</P +><P +><B +CLASS="COMMAND" +>runtest</B +> returns an exit code of + <I +CLASS="EMPHASIS" +>1</I +> if any test has an unexpected result; otherwise + (if all tests pass or fail as expected) it returns <I +CLASS="EMPHASIS" +>0</I +> + as the exit code.</P +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="OUTPUTS" +>Output States</A +></H2 +><P +><TT +CLASS="FILENAME" +>runtest</TT +> flags the outcome of each + test as one of these cases. <A +HREF="posix.html" +><I +>A POSIX Conforming Test Framework</I +></A +> for a + discussion of how POSIX specifies the meanings of these + cases.</P +><P +></P +><DL +><DT +>PASS</DT +><DD +><P +>The most desirable outcome: the test succeeded, and + was expected to succeed.</P +></DD +><DT +>XPASS</DT +><DD +><P +>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.</P +></DD +><DT +>FAIL</DT +><DD +><P +>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.</P +></DD +><DT +>XFAIL</DT +><DD +><P +>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 +CLASS="EMPHASIS" +>UNSUPPORTED</I +> + instead.</P +></DD +><DT +>UNRESOLVED</DT +><DD +><P +>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.</P +></DD +><DT +>UNTESTED</DT +><DD +><P +>A test case is not yet complete, and in particular + cannot yet produce a <I +CLASS="EMPHASIS" +>PASS</I +> or + <I +CLASS="EMPHASIS" +>FAIL</I +>. You can also use this outcome in dummy + ``tests'' that note explicitly the absence of a real test case for a + particular property.</P +></DD +><DT +>UNSUPPORTED</DT +><DD +><P +>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.</P +></DD +></DL +><P +>runtest may also display the following messages:</P +><P +></P +><DL +><DT +>ERROR</DT +><DD +><P +>Indicates a major problem (detected by the test case + itself) in running the test. This is usually an unrecoverable error, + such as a missing file or loss of communication to the target. (POSIX + test suites should not emit this message; use + <I +CLASS="EMPHASIS" +>UNSUPPORTED</I +>, <I +CLASS="EMPHASIS" +>UNTESTED</I +>, or + <I +CLASS="EMPHASIS" +>UNRESOLVED</I +> instead, as + appropriate.)</P +></DD +><DT +>WARNING</DT +><DD +><P +>Indicates a possible problem in running the + test. Usually warnings correspond to recoverable errors, or display + an important message about the following tests.</P +></DD +><DT +>NOTE</DT +><DD +><P +>An informational message about the test + case.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="INVOKING" +>Invoking Runtest</A +></H2 +><P +>This is the full set of command line options that + <TT +CLASS="FILENAME" +>runtest</TT +> recognizes. Arguments may be + abbreviated to the shortest unique string.</P +><P +></P +><DL +><DT +><TT +CLASS="OPTION" +>--all</TT +> (-a)</DT +><DD +><P +>Display all test output. By default, + <I +CLASS="EMPHASIS" +>runtest</I +> shows only the output of tests that + produce unexpected results; that is, tests with status + <I +CLASS="EMPHASIS" +>FAIL</I +> (unexpected failure), + <I +CLASS="EMPHASIS" +>XPASS</I +> (unexpected success), or + <I +CLASS="EMPHASIS" +>ERROR</I +> (a severe error in the test case + itself). Specify <I +CLASS="EMPHASIS" +>--all</I +> to see output for tests + with status <I +CLASS="EMPHASIS" +>PASS</I +> (success, as expected) + <I +CLASS="EMPHASIS" +>XFAIL</I +> (failure, as expected), or + <I +CLASS="EMPHASIS" +>WARNING</I +> (minor error in the test case + itself).</P +></DD +><DT +><TT +CLASS="OPTION" +>--build [string]</TT +></DT +><DD +><P +><I +CLASS="EMPHASIS" +>string</I +> is a full configuration + ``triple'' name as used by <B +CLASS="COMMAND" +>configure</B +>. 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.</P +></DD +><DT +><TT +CLASS="OPTION" +>--host [string]</TT +></DT +><DD +><P +><SPAN +CLASS="SYMBOL" +>string</SPAN +> is a full configuration + ``triple'' name as used by <I +CLASS="EMPHASIS" +>configure</I +>. 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 +CLASS="EMPHASIS" +>only</I +> DejaGnu procedures that compare the + host string with particular values. The procedures + <I +CLASS="EMPHASIS" +>ishost</I +>, <I +CLASS="EMPHASIS" +>istarget</I +>, + <I +CLASS="EMPHASIS" +>isnative</I +>, and <I +CLASS="EMPHASIS" +>setup</I +>xfail} + are affected by <I +CLASS="EMPHASIS" +>--host</I +>. In this usage, + <I +CLASS="EMPHASIS" +>host</I +> refers to the machine that the tests are to + be run on, which may not be the same as the + <I +CLASS="EMPHASIS" +>build</I +> machine. If <I +CLASS="EMPHASIS" +>--build</I +> + is also specified, then <I +CLASS="EMPHASIS" +>--host</I +> refers to the + machine that the tests wil, be run on, not the machine DejaGnu is run + on.</P +></DD +><DT +><TT +CLASS="OPTION" +>--host_board [name]</TT +></DT +><DD +><P +>The host board to use.</P +></DD +><DT +><TT +CLASS="OPTION" +>--target [string]</TT +></DT +><DD +><P +>Use this option to override the default setting + (running native tests). <I +CLASS="EMPHASIS" +>string</I +> is a full + configuration ``triple'' name of the form + <I +CLASS="EMPHASIS" +>cpu-vendor-os</I +> as used by + <B +CLASS="COMMAND" +>configure</B +>. This option changes the + configuration <I +CLASS="EMPHASIS" +>runtest</I +> uses for the default tool + names, and other setup information.</P +></DD +><DT +><TT +CLASS="OPTION" +>--debug</TT +> (-de)</DT +><DD +><P +>Turns on the <I +CLASS="EMPHASIS" +>expect</I +> internal + debugging output. Debugging output is displayed as part of the + <I +CLASS="EMPHASIS" +>runtest</I +> output, and logged to a file called + <TT +CLASS="FILENAME" +>dbg.log</TT +>. The extra debugging output does + <I +CLASS="EMPHASIS" +>not</I +> appear on standard output, unless the + verbose level is greater than 2 (for instance, to see debug output + immediately, specify <I +CLASS="EMPHASIS" +>--debug</I +>-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 +CLASS="EMPHASIS" +>--strace</I +> also goes into + <TT +CLASS="FILENAME" +>dbg.log</TT +>.</P +></DD +><DT +><TT +CLASS="OPTION" +>--help</TT +> (-he)</DT +><DD +><P +>Prints out a short summary of the + <I +CLASS="EMPHASIS" +>runtest</I +> options, then exits (even if you also + specify other options).</P +></DD +><DT +><TT +CLASS="OPTION" +>--ignore [name(s)] </TT +></DT +><DD +><P +>The names of specific tests to + ignore.</P +></DD +><DT +><TT +CLASS="OPTION" +>--objdir [path]</TT +></DT +><DD +><P +>Use <I +CLASS="EMPHASIS" +>path</I +> as the top directory + containing any auxiliary compiled test code. This defaults to + <TT +CLASS="FILENAME" +>.</TT +>. Use this option to locate pre-compiled test + code. You can normally prepare any auxiliary files needed with + <I +CLASS="EMPHASIS" +>make</I +>.</P +></DD +><DT +><TT +CLASS="OPTION" +>--outdir [path]</TT +></DT +><DD +><P +>Write output logs in directory + <TT +CLASS="FILENAME" +>path</TT +>. The default is <I +CLASS="EMPHASIS" +>.}, + the</I +> directory where you start + <I +CLASS="EMPHASIS" +>runtest</I +>. This option affects only the summary + and the detailed log files + <TT +CLASS="FILENAME" +>tool.sum</TT +> and + <TT +CLASS="FILENAME" +>tool.log</TT +>. The DejaGnu debug + log <TT +CLASS="FILENAME" +>dbg.log</TT +> always appears (when requested) in + the local directory.</P +></DD +><DT +><TT +CLASS="OPTION" +>--reboot [name]</TT +></DT +><DD +><P +>Reboot the target board when + <I +CLASS="EMPHASIS" +>runtest</I +> 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.</P +></DD +><DT +><TT +CLASS="OPTION" +>--srcdir [path]</TT +></DT +><DD +><P +>Use <TT +CLASS="FILENAME" +>path</TT +> as the top directory + for test scripts to run. <I +CLASS="EMPHASIS" +>runtest</I +> looks in this + directory for any subdirectory whose name begins with the toolname + (specified with <I +CLASS="EMPHASIS" +>--tool</I +>). For instance, with + <I +CLASS="EMPHASIS" +>--tool</I +>gdb}, <I +CLASS="EMPHASIS" +>runtest</I +> uses + tests in subdirectories <TT +CLASS="FILENAME" +>gdb.*</TT +> (with the usual + shell-like filename expansion). If you do not use + <I +CLASS="EMPHASIS" +>--srcdir</I +>, <I +CLASS="EMPHASIS" +>runtest</I +> looks for + test directories under the current working + directory.</P +></DD +><DT +><TT +CLASS="OPTION" +>--strace [number]</TT +></DT +><DD +><P +>Turn on internal tracing for + <I +CLASS="EMPHASIS" +>expect</I +>, 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 +CLASS="EMPHASIS" +>case</I +> or <I +CLASS="EMPHASIS" +>if</I +> statements. + Each procedure call or control structure counts as one ``level''. The + output is recorded in the same file, <TT +CLASS="FILENAME" +>dbg.log</TT +>, + used for output from <I +CLASS="EMPHASIS" +>--debug</I +>.</P +></DD +><DT +><TT +CLASS="OPTION" +>--connect [program]</TT +></DT +><DD +><P +>Connect to a target testing environment as specified + by <I +CLASS="EMPHASIS" +>type</I +>, if the target is not the computer + running <I +CLASS="EMPHASIS" +>runtest</I +>. For example, use + <I +CLASS="EMPHASIS" +>--connect</I +> to change the program used to connect + to a ``bare board'' boot monitor. The choices for + <I +CLASS="EMPHASIS" +>type</I +> in the DejaGnu 1.4 distribution are + <I +CLASS="EMPHASIS" +>rlogin</I +>, <I +CLASS="EMPHASIS" +>telnet</I +>, + <I +CLASS="EMPHASIS" +>rsh</I +>, <I +CLASS="EMPHASIS" +>tip</I +>, + <I +CLASS="EMPHASIS" +>kermit</I +>, and <I +CLASS="EMPHASIS" +>mondfe</I +>.</P +><P +>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.</P +></DD +><DT +><TT +CLASS="OPTION" +>--baud [number]</TT +></DT +><DD +><P +>Set the default baud rate to something other than + 9600. (Some serial interface programs, like <I +CLASS="EMPHASIS" +>tip</I +>, + use a separate initialization file instead of this + value.)</P +></DD +><DT +><TT +CLASS="OPTION" +>--target_board [name(s)]</TT +></DT +><DD +><P +>The list of target boards to run tests + on.</P +></DD +><DT +><A +NAME="TOOL-OPT" +><TT +CLASS="OPTION" +>--tool[name(s)]</TT +></A +></DT +><DD +><P +>Specifies which test suite to run, and what + initialization module to use. <TT +CLASS="OPTION" +>--tool</TT +> is used + <I +CLASS="EMPHASIS" +>only</I +> for these two purposes. It is + <I +CLASS="EMPHASIS" +>not</I +> used to name the executable program to + test. Executable tool names (and paths) are recorded in + <TT +CLASS="FILENAME" +>site.exp</TT +> and you can override them by specifying + Tcl variables on the command line.</P +><P +>For example, including "<TT +CLASS="OPTION" +>--tool</TT +> gcc" on the + <I +CLASS="EMPHASIS" +>runtest</I +> command line runs tests from all test + subdirectories whose names match <TT +CLASS="FILENAME" +>gcc.*</TT +>, and uses + one of the initialization modules named + <TT +CLASS="FILENAME" +>config/*-gcc.exp</TT +>. To specify the name of the + compiler (perhaps as an alternative path to what + <I +CLASS="EMPHASIS" +>runtest</I +> would use by default), use + <I +CLASS="EMPHASIS" +>GCC=binname</I +> on the <I +CLASS="EMPHASIS" +>runtest</I +> + command line.</P +></DD +><DT +><TT +CLASS="OPTION" +>--tool_exec [name]</TT +></DT +><DD +><P +>The path to the tool executable to + test.</P +></DD +><DT +><TT +CLASS="OPTION" +>--tool_opts [options]</TT +></DT +><DD +><P +>A list of additional options to pass to the + tool.</P +></DD +><DT +><TT +CLASS="OPTION" +>--verbose</TT +> (-v)</DT +><DD +><P +>Turns on more output. Repeating this option increases + the amount of output displayed. Level one (<I +CLASS="EMPHASIS" +>-v</I +>) + is simply test output. Level two (<I +CLASS="EMPHASIS" +>-v</I +>-v}) shows + messages on options, configuration, and process control. Verbose + messages appear in the detailed (<TT +CLASS="FILENAME" +>*.log</TT +>) log + file, but not in the summary (<TT +CLASS="FILENAME" +>*.sum</TT +>) log + file.</P +></DD +><DT +><TT +CLASS="OPTION" +>--version</TT +> (-V)</DT +><DD +><P +>Prints out the version numbers of DejaGnu, + <I +CLASS="EMPHASIS" +>expect</I +> and Tcl, and exits without running any + tests.</P +></DD +><DT +><TT +CLASS="OPTION" +>--D[0-1]</TT +></DT +><DD +><P +>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 +CLASS="EMPHASIS" +>expect</I +> as the file + <TT +CLASS="FILENAME" +>expect/tcl-debug.ps.</TT +>. If you specify + <I +CLASS="EMPHASIS" +>-D1</I +>, the <I +CLASS="EMPHASIS" +>expect</I +> shell stops + at a breakpoint as soon as DejaGnu invokes it. If you specify + <I +CLASS="EMPHASIS" +>-D0</I +>, DejaGnu starts as usual, but you can enter + the debugger by sending an interrupt (e.g. by typing + <B +CLASS="KEYCAP" +>C</B +>-<B +CLASS="KEYCAP" +>c</B +>). + </P +></DD +><DT +><TT +CLASS="FILENAME" +>testfile</TT +>.exp[=arg(s)]</DT +><DD +><P +>Specify the names of testsuites to run. By default, + <I +CLASS="EMPHASIS" +>runtest</I +> runs all tests for the tool, but you can + restrict it to particular testsuites by giving the names of the + <I +CLASS="EMPHASIS" +>.exp expect</I +> scripts that control + them. <I +CLASS="EMPHASIS" +>testsuite</I +>.exp may not include path + information; use plain filenames.</P +></DD +><DT +><TT +CLASS="FILENAME" +>testfile</TT +>.exp="testfile1 ..."</DT +><DD +><P +>Specify a subset of tests in a suite to run. For + compiler or assembler tests, which often use a single + <I +CLASS="EMPHASIS" +>.exp</I +> 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 +CLASS="EMPHASIS" +>?</I +>, <I +CLASS="EMPHASIS" +>*</I +>, + and <I +CLASS="EMPHASIS" +>[chars]</I +>.</P +></DD +><DT +><SPAN +CLASS="SYMBOL" +>tclvar</SPAN +>=value</DT +><DD +><P +>You can define Tcl variables for use by your test + scripts in the same style used with <I +CLASS="EMPHASIS" +>make</I +> for + environment variables. For example, <I +CLASS="EMPHASIS" +>runtest + GDB=gdb.old</I +> defines a variable called + <B +CLASS="COMMAND" +>GDB</B +>; when your scripts refer to + <SPAN +CLASS="SYMBOL" +>$GDB</SPAN +> in this run, they use the value + <I +CLASS="EMPHASIS" +>gdb.old</I +>.</P +><P +>The default Tcl variables used for most tools are defined in + the main DejaGnu <I +CLASS="EMPHASIS" +>Makefile</I +>; their values are + captured in the <TT +CLASS="FILENAME" +>site.exp</TT +> file.</P +></DD +></DL +></DIV +><DIV +CLASS="SECT2" +><H2 +CLASS="SECT2" +><A +NAME="COMMON" +>Common Options</A +></H2 +><P +>Typically, you don't need must to use any command-line options. + <TT +CLASS="OPTION" +>--tool</TT +> used is only required when there are more than + one test suite in the same directory. The default options are in the + local site.exp file, created by "make site.exp".</P +><P +>For example, if the directory <TT +CLASS="FILENAME" +>gdb/testsuite</TT +> + contains a collection of DejaGnu tests for GDB, you can run them like + this:</P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="SCREEN" +> eg$ cd gdb/testsuite + eg$ runtest --tool gdb + </PRE +></TD +></TR +></TABLE +><P +>Test output follows, ending with:</P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="SCREEN" +> === gdb Summary === + + # of expected passes 508 + # of expected failures 103 + /usr/latest/bin/gdb version 4.14.4 -nx + </PRE +></TD +></TR +></TABLE +><P +>You can use the option <I +CLASS="EMPHASIS" +>--srcdir</I +> to point to + some other directory containing a collection of tests:</P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="SCREEN" +> eg$ runtest--srcdir /devo/gdb/testsuite + </PRE +></TD +></TR +></TABLE +><P +>By default, <B +CLASS="COMMAND" +>runtest</B +> 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 +CLASS="EMPHASIS" +>--all</I +> option. For more + verbose output about processes being run, communication, and so on, use + <I +CLASS="EMPHASIS" +>--verbose</I +>. To see even more output, use multiple + <I +CLASS="EMPHASIS" +>--verbose</I +> options. for a more detailed explanation + of each <B +CLASS="COMMAND" +>runtest</B +> option.</P +><P +>Test output goes into two files in your current directory: + summary output in <TT +CLASS="FILENAME" +>tool.sum</TT +>, + and detailed output in <TT +CLASS="FILENAME" +> tool.log</TT +>. (<I +CLASS="EMPHASIS" +>tool</I +> + refers to the collection of tests; for example, after a run with + <I +CLASS="EMPHASIS" +>--tool</I +> gdb, look for output files + <TT +CLASS="FILENAME" +>gdb.sum</TT +> and + <TT +CLASS="FILENAME" +>gdb.log</TT +>.)</P +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="runningtests.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="outputfiles.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Running Tests</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="runningtests.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>The files DejaGnu produces.</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/tvariables.html b/doc/overview/tvariables.html new file mode 100644 index 0000000..0bcb733 --- /dev/null +++ b/doc/overview/tvariables.html @@ -0,0 +1,208 @@ +<HTML +><HEAD +><TITLE +>Special variables used by test cases.</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Extending DejaGnu" +HREF="extending.html"><LINK +REL="PREVIOUS" +TITLE="Hints On Writing A Test Case" +HREF="hints.html"><LINK +REL="NEXT" +TITLE="Reference" +HREF="reference.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="hints.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 4. Extending DejaGnu</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="reference.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="TVARIABLES" +>Special variables used by test cases.</A +></H1 +><P +>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 + <TT +CLASS="FILENAME" +>site.exp</TT +>. You can use the value of these variables, + but they should never be changed.</P +><P +></P +><DL +><DT +>$prms_id</DT +><DD +><P +>The tracking system (e.g. GNATS) number identifying + a corresponding bugreport. (<I +CLASS="EMPHASIS" +>0</I +>} if you do not + specify it in the test script.)</P +></DD +><DT +>$item bug_id</DT +><DD +><P +>An optional bug id; may reflect a bug + identification from another organization. (<I +CLASS="EMPHASIS" +>0</I +> + if you do not specify it.)</P +></DD +><DT +>$subdir</DT +><DD +><P +>The subdirectory for the current test + case.</P +></DD +><DT +>$expect_out(buffer)</DT +><DD +><P +>The output from the last command. This is an + internal variable set by Expect. More information can be found in + the Expect manual.</P +></DD +><DT +>$exec_output</DT +><DD +><P +>This is the output from a + <TT +CLASS="FUNCTION" +><B +>${tool}_load</B +></TT +> 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.</P +></DD +><DT +>$comp_output</DT +><DD +><P +>This is the output from a + <TT +CLASS="FUNCTION" +><B +>${tool}_start</B +></TT +> command. This is conventionally + used for batch oriented programs, like GCC and GAS, that may + produce interesting output (warnings, errors) without further + interaction.</P +></DD +></DL +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="hints.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="reference.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Hints On Writing A Test Case</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="extending.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Reference</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/overview/writing.html b/doc/overview/writing.html new file mode 100644 index 0000000..b8b8e0f --- /dev/null +++ b/doc/overview/writing.html @@ -0,0 +1,202 @@ +<HTML +><HEAD +><TITLE +>Writing A Test Case</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.33"><LINK +REL="HOME" +TITLE="DejaGnu" +HREF="book1.html"><LINK +REL="UP" +TITLE="Extending DejaGnu" +HREF="extending.html"><LINK +REL="PREVIOUS" +TITLE="Board Config File Values" +HREF="boarddefs.html"><LINK +REL="NEXT" +TITLE="Debugging A Test Case" +HREF="debugging.html"></HEAD +><BODY +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>DejaGnu</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="boarddefs.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 4. Extending DejaGnu</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="debugging.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="WRITING" +>Writing A Test Case</A +></H1 +><P +>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.</P +><P +>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 <TT +CLASS="FILENAME" +>lib/c-torture.exp</TT +> in the GCC test + suite. Most tests of this kind use very few + <SPAN +CLASS="PRODUCTNAME" +>expect</SPAN +> features, and are coded almost + purely in Tcl.</P +><P +>Writing the complete suite of C tests, then, consisted of + these steps:</P +><P +></P +><UL +><LI +STYLE="list-style-type: disc" +><P +>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.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>Writing (and debugging) the generic Tcl procedures for + compilation.</P +></LI +><LI +STYLE="list-style-type: disc" +><P +>Writing the simple test driver: its main task is to + search the directory (using the Tcl procedure + <I +CLASS="EMPHASIS" +>glob</I +> for filename expansion with wildcards) + and call a Tcl procedure with each filename. It also checks for + a few errors from the testing procedure.</P +></LI +></UL +><P +>Testing interactive programs is intrinsically more + complex. Tests for most interactive programs require some trial + and error before they are complete.</P +><P +>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.</P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="boarddefs.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="book1.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="debugging.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Board Config File Values</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="extending.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Debugging A Test Case</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/ref.sgml b/doc/ref.sgml index 6a1a7d6..1256e00 100644 --- a/doc/ref.sgml +++ b/doc/ref.sgml @@ -75,15 +75,15 @@ <listitem><para>Create another directory in the <filename>share</filename> directory, called <filename>dejagnu</filename>, and copy all the library files into - it.</listitem> + it.</para></listitem> <listitem><para>Create a directory in the <filename>dejagnu/share</filename> directory, called <filename>config</filename>, and copy all the configuration files into - it.</listitem> + it.</para></listitem> <listitem><para>Copy the <emphasis>runtest</emphasis> shell script into - <filename>$exec_prefix/bin</filename>. + <filename>$exec_prefix/bin</filename>.</para></listitem> <listitem><para>Copy <filename>runtest.exp</filename> into <filename>$exec_prefix/lib/dejagnu</filename>. This is the main Tcl @@ -539,6 +539,7 @@ <paramdef><parameter></parameter></paramdef> </funcsynopsis> + </sect3> <sect3 id=warning xreflabel="warning procedure"> <title>Warning Procedure</title> @@ -584,6 +585,7 @@ </varlistentry> </variablelist> + </sect3> <sect3 id=perror xreflabel="perror procedure"> <title>Perror Procedure</title> @@ -623,6 +625,7 @@ </varlistentry> </variablelist> + </sect3> <sect3 id=note xreflabel="note procedure"> <title>Note Procedure</title> @@ -3118,6 +3121,7 @@ </variablelist> </sect3> + </sect2> <sect2 id=platformprocs xreflabel="platform dependant procedures"> <title>Platform Dependant Procedures</title> @@ -3210,7 +3214,7 @@ session. You can also use <function>${tool}_exit</function> to remove any temporary files left over from the tests. <command>runtest</command> calls - <function>${tool}_exit</function>.<para> + <function>${tool}_exit</function>.</para> <funcsynopsis role="tcl"> <funcdef><function>${tool}_exit</function></funcdef> @@ -3335,7 +3339,7 @@ <para>Use the optional third argument <emphasis>line</emphasis> to start lines in the result with the line number in <filename>filename</filename>. (This argument is simply an option - flag; type it just as shown <option>--line</option>.) + flag; type it just as shown <option>--line</option>.)</para> <funcsynopsis role="tcl"> <funcdef><function>grep</function></funcdef> @@ -3360,8 +3364,8 @@ regexp matches.</para></listitem> </varlistentry> </variablelist> - </sect3> + <sect3 id=prune xreflabel="prune procedure"> <title>Prune Procedure</title> @@ -3437,7 +3441,7 @@ <para>This sources the file <emphasis>filename</emphasis>, and traps all errors. It also ignores all extraneous output. If there was an error it returns a <emphasis>1</emphasis>, otherwise it returns a - <emphasis>0</emphasis>. + <emphasis>0</emphasis>.</para> <funcsynopsis role="tcl"> <funcdef><function>psource</function></funcdef> @@ -3530,6 +3534,7 @@ </varlistentry> </variablelist> + </sect3> <sect3 id=unsetenv xreflabel="unsetenv procedure"> <title>unsetenv Procedure</title> @@ -3553,7 +3558,7 @@ <title>Getenv Procedure</title> <para>Returns the value of <emphasis>var</emphasis> in the - environment if it exists, otherwise it returns NULL. + environment if it exists, otherwise it returns NULL.</para> <funcsynopsis role="tcl"> <funcdef><function>getenv</function></funcdef> @@ -3567,6 +3572,7 @@ </varlistentry> </variablelist> + </sect3> <sect3 id=prunesystemcrud xreflabel="prune_system_crud procedure"> <title>Prune_system_crud Procedure</title> diff --git a/doc/runtest.1 b/doc/runtest.1 index 2c3a357..861ec66 100644 --- a/doc/runtest.1 +++ b/doc/runtest.1 @@ -53,9 +53,8 @@ The configuration string for the host. .TP .BI --ignore \ test1.exp\ test2.exp\ ... Do not run the specified tests. -.BI --mail \ \'name1\ name2\ ...\' Electronic mail addresses to receive test results. -.TP +.TP .BI --name \ hostname The network hostname of the target board. .TP diff --git a/doc/user.sgml b/doc/user.sgml index 2154d74..143e1ac 100644 --- a/doc/user.sgml +++ b/doc/user.sgml @@ -490,7 +490,7 @@ verbose output about processes being run, communication, and so on, use <emphasis>--verbose</emphasis>. To see even more output, use multiple <emphasis>--verbose</emphasis> options. for a more detailed explanation - of each <command>runtest</command> option. + of each <command>runtest</command> option.</para> <para>Test output goes into two files in your current directory: summary output in <filename>tool.sum</filename>, @@ -498,7 +498,8 @@ tool.log</filename>. (<emphasis>tool</emphasis> refers to the collection of tests; for example, after a run with <emphasis>--tool</emphasis> gdb, look for output files - <filename>gdb.sum</filename> and <filename>gdb.log</filename>.) + <filename>gdb.sum</filename> and + <filename>gdb.log</filename>.)</para> </sect2> </sect1> @@ -529,7 +530,8 @@ (expected and unexpected); and the full pathname and version number of the tool tested. (All possible outcomes, and all errors, are always reflected in the summary output file, - regardless of whether or not you specify <option>--all</option>.) + regardless of whether or not you specify + <option>--all</option>.)</para> <para>If any of your tests use the procedures <command>unresolved</command>, <command>unsupported</command>, @@ -1137,7 +1139,7 @@ </example> <para>If you are testing a native PC compiler (ex: you have - gcc.exe in your PATH on the PC), do this: + gcc.exe in your PATH on the PC), do this:</para> <example> <title>Setup Native Remote Testing</title> @@ -1192,7 +1194,7 @@ called <symbol>target_info</symbol>, and it has two indices. The following fields are part of the array.</para> - <sect1 id=optiondefs xreflabel="Option Variables"> + <sect2 id=optiondefs xreflabel="Option Variables"> <title>Command Line Option Variables</title> <para>In the user editable second section of the <xref @@ -1311,9 +1313,9 @@ </table> </para> - </sect1> + </sect2> - <sect1 id=personal xreflabel="Personal Config File"> + <sect2 id=personal xreflabel="Personal Config File"> <title>Personal Config File</title> <para>The personal config file is used to customize @@ -1342,6 +1344,7 @@ secure shell, as rsh is mostly used to test unix machines within a local network here.</para> + </sect2> </sect1> </chapter> @@ -2146,13 +2149,13 @@ appropriate for the particular test, allow successively higher values of <emphasis>$verbose</emphasis> to generate more information. Be kind to other programmers who use your tests: - provide for a lot of debugging information.</para> + provide for a lot of debugging information.</para></listitem> <listitem><para>Output from the internal debugging functions of Tcl and <productname>Expect</productname>. There is a command line options for each; both forms of debugging output are recorded in the file <filename>dbg.log</filename> in the current - directory.</para> + directory.</para> <para>Use <option>--debug</option> for information from the expect level; it generates displays of the expect attempts to @@ -2162,7 +2165,7 @@ latest attempt at a new test script and the corresponding <filename>dbg.log</filename> can allow you to create the final patterns by ``cut and paste''. This is sometimes the best way - to write a test case.</para> + to write a test case.</para></listitem> <listitem><para>Use <option>--strace</option> to see more detail at the Tcl level; this shows how Tcl procedure @@ -2174,7 +2177,7 @@ the expect command <command>log_user</command>. This command prints all expect actions to the expect standard output, to the detailed log file, and (if <option>--debug</option> is on) to - <filename>dbg.log</filename>.</para> + <filename>dbg.log</filename>.</para></listitem> </itemizedlist> </sect1> @@ -2225,7 +2228,7 @@ directory.</para></listitem> <listitem><para>Add the new test case to the directory, as - above. </para> + above. </para></listitem> <listitem><para>To add support in the new directory for configure and make, you must also create a |