* configure.ac: Likewise.
* Makefile.in: Regenerate.
* configure: Regenerate.
* doc/dejagnu.xml: Remove.
* doc/legal.xml: Likewise.
* doc/ref.xml: Likewise.
* doc/user.xml: Likewise.
2016-03-28 Ben Elliston <bje@gnu.org>
+ * Makefile.am: Remove references to Docbook and friends.
+ * configure.ac: Likewise.
+ * Makefile.in: Regenerate.
+ * configure: Regenerate.
+ * doc/dejagnu.xml: Remove.
+ * doc/legal.xml: Likewise.
+ * doc/ref.xml: Likewise.
+ * doc/user.xml: Likewise.
+
+2016-03-28 Ben Elliston <bje@gnu.org>
+
* lib/framework.exp (exp_continue): Remove old compatibility
wrapper. Expect deprecated 'continue -expect' in August 1997.
dist_man_MANS = doc/runtest.1
info_TEXINFOS = doc/dejagnu.texi
-
-DOCBOOK2PDF = @DOCBOOK2PDF@
-DOCBOOK2RTF = @DOCBOOK2RTF@
-DOCBOOK2PS = @DOCBOOK2PS@
-DOCBOOK2HTML = @DOCBOOK2HTML@
-DOCBOOK2TEXI = @DOCBOOK2TEXI@
-
-XML = doc/dejagnu.xml doc/legal.xml doc/ref.xml doc/user.xml
-
-dejagnu.pdf: $(XML)
- $(DOCBOOK2PDF) $(srcdir)/doc/dejagnu.xml
-
-dejagnu.ps: $(XML)
- $(DOCBOOK2PS) $(srcdir)/doc/dejagnu.xml
-
-dejagnu.rtf: $(XML)
- $(DOCBOOK2RTF) $(srcdir)/doc/dejagnu.xml
-
-html-local:
- $(DOCBOOK2HTML) -o html $(srcdir)/doc/dejagnu.xml
-
-if MAINTAINER_MODE
-doc/dejagnu.texi: $(XML)
- $(DOCBOOK2TEXI) --string-param directory-description="The GNU testing framework." --string-param directory-category="Programming" $(srcdir)/doc/dejagnu.xml
- mv dejagnu.texi $(srcdir)/doc
-endif
DEFS = @DEFS@
DEJAGNU = @DEJAGNU@
DEPDIR = @DEPDIR@
-DOCBOOK2HTML = @DOCBOOK2HTML@
-DOCBOOK2PDF = @DOCBOOK2PDF@
-DOCBOOK2PS = @DOCBOOK2PS@
-DOCBOOK2RTF = @DOCBOOK2RTF@
-DOCBOOK2TEXI = @DOCBOOK2TEXI@
ECHO_C = @ECHO_C@
ECHO_N = @ECHO_N@
ECHO_T = @ECHO_T@
# Documentation.
dist_man_MANS = doc/runtest.1
info_TEXINFOS = doc/dejagnu.texi
-XML = doc/dejagnu.xml doc/legal.xml doc/ref.xml doc/user.xml
all: all-am
.SUFFIXES:
html: html-am
-html-am: $(HTMLS) html-local
+html-am: $(HTMLS)
info: info-am
dist-shar dist-tarZ dist-xz dist-zip distcheck distclean \
distclean-DEJAGNU distclean-compile distclean-generic \
distclean-tags distcleancheck distdir distuninstallcheck dvi \
- dvi-am html html-am html-local info info-am install install-am \
+ dvi-am html html-am info info-am install install-am \
install-baseboardDATA install-binSCRIPTS install-configDATA \
install-data install-data-am install-djlibexecSCRIPTS \
install-dvi install-dvi-am install-exec install-exec-am \
all-local:
@echo "Done. Now run 'make install'."
-dejagnu.pdf: $(XML)
- $(DOCBOOK2PDF) $(srcdir)/doc/dejagnu.xml
-
-dejagnu.ps: $(XML)
- $(DOCBOOK2PS) $(srcdir)/doc/dejagnu.xml
-
-dejagnu.rtf: $(XML)
- $(DOCBOOK2RTF) $(srcdir)/doc/dejagnu.xml
-
-html-local:
- $(DOCBOOK2HTML) -o html $(srcdir)/doc/dejagnu.xml
-
-@MAINTAINER_MODE_TRUE@doc/dejagnu.texi: $(XML)
-@MAINTAINER_MODE_TRUE@ $(DOCBOOK2TEXI) --string-param directory-description="The GNU testing framework." --string-param directory-category="Programming" $(srcdir)/doc/dejagnu.xml
-@MAINTAINER_MODE_TRUE@ mv dejagnu.texi $(srcdir)/doc
-
# Tell versions [3.59,3.63) of GNU make to not export all variables.
# Otherwise a system limit (for SysV at least) may be exceeded.
.NOEXPORT:
subdirs
DEJAGNU
EXPECT
-DOCBOOK2TEXI
-DOCBOOK2PS
-DOCBOOK2PDF
-DOCBOOK2RTF
-DOCBOOK2HTML
am__fastdepCXX_FALSE
am__fastdepCXX_TRUE
CXXDEPMODE
-# Extract the first word of "docbook2html", so it can be a program name with args.
-set dummy docbook2html; ac_word=$2
-{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
-$as_echo_n "checking for $ac_word... " >&6; }
-if ${ac_cv_path_DOCBOOK2HTML+:} false; then :
- $as_echo_n "(cached) " >&6
-else
- case $DOCBOOK2HTML in
- [\\/]* | ?:[\\/]*)
- ac_cv_path_DOCBOOK2HTML="$DOCBOOK2HTML" # Let the user override the test with a path.
- ;;
- *)
- as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
-for as_dir in $PATH
-do
- IFS=$as_save_IFS
- test -z "$as_dir" && as_dir=.
- for ac_exec_ext in '' $ac_executable_extensions; do
- if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
- ac_cv_path_DOCBOOK2HTML="$as_dir/$ac_word$ac_exec_ext"
- $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
- break 2
- fi
-done
- done
-IFS=$as_save_IFS
-
- test -z "$ac_cv_path_DOCBOOK2HTML" && ac_cv_path_DOCBOOK2HTML="false"
- ;;
-esac
-fi
-DOCBOOK2HTML=$ac_cv_path_DOCBOOK2HTML
-if test -n "$DOCBOOK2HTML"; then
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: $DOCBOOK2HTML" >&5
-$as_echo "$DOCBOOK2HTML" >&6; }
-else
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
-$as_echo "no" >&6; }
-fi
-
-
-# Extract the first word of "docbook2rtf", so it can be a program name with args.
-set dummy docbook2rtf; ac_word=$2
-{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
-$as_echo_n "checking for $ac_word... " >&6; }
-if ${ac_cv_path_DOCBOOK2RTF+:} false; then :
- $as_echo_n "(cached) " >&6
-else
- case $DOCBOOK2RTF in
- [\\/]* | ?:[\\/]*)
- ac_cv_path_DOCBOOK2RTF="$DOCBOOK2RTF" # Let the user override the test with a path.
- ;;
- *)
- as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
-for as_dir in $PATH
-do
- IFS=$as_save_IFS
- test -z "$as_dir" && as_dir=.
- for ac_exec_ext in '' $ac_executable_extensions; do
- if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
- ac_cv_path_DOCBOOK2RTF="$as_dir/$ac_word$ac_exec_ext"
- $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
- break 2
- fi
-done
- done
-IFS=$as_save_IFS
-
- test -z "$ac_cv_path_DOCBOOK2RTF" && ac_cv_path_DOCBOOK2RTF="false"
- ;;
-esac
-fi
-DOCBOOK2RTF=$ac_cv_path_DOCBOOK2RTF
-if test -n "$DOCBOOK2RTF"; then
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: $DOCBOOK2RTF" >&5
-$as_echo "$DOCBOOK2RTF" >&6; }
-else
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
-$as_echo "no" >&6; }
-fi
-
-
-# Extract the first word of "docbook2pdf", so it can be a program name with args.
-set dummy docbook2pdf; ac_word=$2
-{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
-$as_echo_n "checking for $ac_word... " >&6; }
-if ${ac_cv_path_DOCBOOK2PDF+:} false; then :
- $as_echo_n "(cached) " >&6
-else
- case $DOCBOOK2PDF in
- [\\/]* | ?:[\\/]*)
- ac_cv_path_DOCBOOK2PDF="$DOCBOOK2PDF" # Let the user override the test with a path.
- ;;
- *)
- as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
-for as_dir in $PATH
-do
- IFS=$as_save_IFS
- test -z "$as_dir" && as_dir=.
- for ac_exec_ext in '' $ac_executable_extensions; do
- if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
- ac_cv_path_DOCBOOK2PDF="$as_dir/$ac_word$ac_exec_ext"
- $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
- break 2
- fi
-done
- done
-IFS=$as_save_IFS
-
- test -z "$ac_cv_path_DOCBOOK2PDF" && ac_cv_path_DOCBOOK2PDF="false"
- ;;
-esac
-fi
-DOCBOOK2PDF=$ac_cv_path_DOCBOOK2PDF
-if test -n "$DOCBOOK2PDF"; then
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: $DOCBOOK2PDF" >&5
-$as_echo "$DOCBOOK2PDF" >&6; }
-else
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
-$as_echo "no" >&6; }
-fi
-
-
-# Extract the first word of "docbook2ps", so it can be a program name with args.
-set dummy docbook2ps; ac_word=$2
-{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
-$as_echo_n "checking for $ac_word... " >&6; }
-if ${ac_cv_path_DOCBOOK2PS+:} false; then :
- $as_echo_n "(cached) " >&6
-else
- case $DOCBOOK2PS in
- [\\/]* | ?:[\\/]*)
- ac_cv_path_DOCBOOK2PS="$DOCBOOK2PS" # Let the user override the test with a path.
- ;;
- *)
- as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
-for as_dir in $PATH
-do
- IFS=$as_save_IFS
- test -z "$as_dir" && as_dir=.
- for ac_exec_ext in '' $ac_executable_extensions; do
- if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
- ac_cv_path_DOCBOOK2PS="$as_dir/$ac_word$ac_exec_ext"
- $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
- break 2
- fi
-done
- done
-IFS=$as_save_IFS
-
- test -z "$ac_cv_path_DOCBOOK2PS" && ac_cv_path_DOCBOOK2PS="false"
- ;;
-esac
-fi
-DOCBOOK2PS=$ac_cv_path_DOCBOOK2PS
-if test -n "$DOCBOOK2PS"; then
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: $DOCBOOK2PS" >&5
-$as_echo "$DOCBOOK2PS" >&6; }
-else
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
-$as_echo "no" >&6; }
-fi
-
-
-# Extract the first word of "docbook2x-texi", so it can be a program name with args.
-set dummy docbook2x-texi; ac_word=$2
-{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
-$as_echo_n "checking for $ac_word... " >&6; }
-if ${ac_cv_path_DOCBOOK2TEXI+:} false; then :
- $as_echo_n "(cached) " >&6
-else
- case $DOCBOOK2TEXI in
- [\\/]* | ?:[\\/]*)
- ac_cv_path_DOCBOOK2TEXI="$DOCBOOK2TEXI" # Let the user override the test with a path.
- ;;
- *)
- as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
-for as_dir in $PATH
-do
- IFS=$as_save_IFS
- test -z "$as_dir" && as_dir=.
- for ac_exec_ext in '' $ac_executable_extensions; do
- if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
- ac_cv_path_DOCBOOK2TEXI="$as_dir/$ac_word$ac_exec_ext"
- $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
- break 2
- fi
-done
- done
-IFS=$as_save_IFS
-
- test -z "$ac_cv_path_DOCBOOK2TEXI" && ac_cv_path_DOCBOOK2TEXI="false"
- ;;
-esac
-fi
-DOCBOOK2TEXI=$ac_cv_path_DOCBOOK2TEXI
-if test -n "$DOCBOOK2TEXI"; then
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: $DOCBOOK2TEXI" >&5
-$as_echo "$DOCBOOK2TEXI" >&6; }
-else
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
-$as_echo "no" >&6; }
-fi
-
-
-
# Extract the first word of "expect", so it can be a program name with args.
set dummy expect; ac_word=$2
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
AC_PROG_INSTALL
AC_EXEEXT
-dnl Search for the Docbook utilities.
-AC_PATH_PROG([DOCBOOK2HTML], [docbook2html], [false])
-AC_PATH_PROG([DOCBOOK2RTF], [docbook2rtf], [false])
-AC_PATH_PROG([DOCBOOK2PDF], [docbook2pdf], [false])
-AC_PATH_PROG([DOCBOOK2PS], [docbook2ps], [false])
-AC_PATH_PROG([DOCBOOK2TEXI], [docbook2x-texi], [false])
-
dnl Search for expect.
AC_PATH_PROG([EXPECT], [expect])
if test -z $ac_cv_path_EXPECT ; then
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
- <!ENTITY legal SYSTEM "legal.xml">
- <!ENTITY appversion "1.5.4">
- <!ENTITY version "1.5.4">
- <!ENTITY manrevision "1.0">
- <!ENTITY date "November 2015">
- <!ENTITY app "<application>DejaGnu</application>">
- <!ENTITY appname "DejaGnu">
- <!ENTITY dj "DejaGnu">
- <!-- The reference material -->
- <!ENTITY ref SYSTEM "ref.xml">
- <!-- The user manual -->
- <!ENTITY user SYSTEM "user.xml">
-]>
-<!-- Begin Document Specific Declarations -->
-<article>
- <articleinfo>
- <title>&dj;</title>
- <subtitle>The GNU Testing Framework</subtitle>
- <date>November 2015</date>
- <authorgroup>
- <author>
- <firstname>Rob</firstname>
- <surname>Savoye</surname>
- </author>
- <author>
- <firstname>Ben</firstname>
- <surname>Elliston</surname>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2015</year>
- <holder>Free Software Foundation, Inc.</holder>
- </copyright>
- <!-- <legalnotice>
- <para> -->
- <!-- [FIXME: must put legal notice here] -->
- <!-- </para> -->
- <!-- </legalnotice> -->
- <revhistory>
- <revision>
- <revnumber>1.5.3</revnumber>
- <date>2015-11-12</date>
- <authorinitials>bje</authorinitials>
- <revremark>Overhaul the manual.</revremark>
- </revision>
- </revhistory>
-
- </articleinfo>
-
- <sect1 id="intro" xreflabel="Introduction">
- <title>Introduction</title>
- <sect2 id="whatis" xreflabel="What is &dj;?">
- <title>What is &dj;?</title>
-
- <para><productname>&dj;</productname> is a framework for testing
- other programs, providing a single front-end for all
- tests. You can think of it as a custom library of Tcl
- procedures crafted to help with writing a test harness. A
- <emphasis>test harness</emphasis> is the testing
- infrastructure that is created to support a specific program
- or tool. Each program can have multiple testsuites, all
- supported by a single test harness. &dj; is written in
- <productname>Expect</productname>, which in turn uses
- <productname>Tcl</productname>, the Tool command
- language. There is more information on Tcl at
- the <ulink url="http://www.tcl.tk">Tcl/Tk</ulink> web site and
- the Expect web site is
- at <ulink url="http://expect.nist.gov">NIST</ulink>.</para>
-
- <para>Julia Menapace first coined the term ``&dj;'' to describe an
- earlier testing framework she wrote at Cygnus Support for
- testing GDB. When we replaced it with the Expect-based
- framework, it was like &dj; all over again. More importantly,
- it was also named after my daughter, Deja Snow Savoye, who was
- a toddler during &dj;'s beginnings.</para>
-
- <para>&dj; offers several advantages for testing:</para>
-
- <itemizedlist mark="bullet" spacing="compact">
-
- <listitem><para>The flexibility and consistency of the &dj;
- framework make it easy to write tests for any program, with
- either batch oriented, or interactive programs.</para>
- </listitem>
-
- <listitem><para>&dj; provides a layer of abstraction which
- allows you to write tests that are portable to any host or
- target where a program must be tested. For instance, a test
- for <command>GDB</command> can run from any supported host
- system on any supported target system. &dj; runs tests on
- many single board computers, whose operating software ranges
- from a simple boot monitor to a real-time OS.</para>
- </listitem>
-
- <listitem><para>All tests have the same output format. This
- makes it easy to integrate testing into other software
- development processes. &dj;'s output is designed to be
- parsed by other filtering script and it is also human
- readable.</para>
- </listitem>
-
- <listitem><para>Using Tcl and Expect, it's easy to create wrappers
- for existing testsuites. By incorporating existing tests under
- &dj;, it's easier to have a single set of report analyse
- programs..</para>
-
- </listitem>
- </itemizedlist>
-
- <para>Running tests requires two things: the testing framework and
- the testsuites themselves. Tests are usually written in
- <productname>Expect</productname> using Tcl, but you can also use
- a Tcl script to run a testsuite that is not based on
- <productname>Expect</productname>. <productname>Expect</productname>
- script filenames conventionally use <emphasis>.exp</emphasis> as a
- suffix; for example, the main implementation of the &dj; test
- driver is in the file
- <productname>runtest.exp</productname>.)</para>
-
- </sect2>
-
- <sect2 id="new" xreflabel="Release Notes">
- <title>New In This Release</title>
-
- <itemizedlist>
- <listitem>
- <para>A completely new manual.</para>
- </listitem>
-
- </itemizedlist>
-
- </sect2>
-
- <sect2 id="designgoals" xreflabel="Design Goals">
- <title>Design Goals</title>
-
- <para>&dj; grew out of the internal needs of Cygnus Solutions
- (formerly Cygnus Support). Cygnus maintained and enhanced a
- variety of free programs in many different environments and needed
- a testing tool that:</para>
-
- <itemizedlist mark="bullet">
- <listitem><para>was useful to developers while fixing
- bugs;</para></listitem>
- <listitem><para>automated running many tests during a software
- release process;</para></listitem>
- <listitem><para>was portable among a variety of host
- computers;</para></listitem>
- <listitem><para>supported a cross-development environment;
- </para></listitem>
- <listitem><para>permitted testing of interactive programs
- like <command>GDB</command>; and </para></listitem>
- <listitem><para>permitted testing of batch-oriented programs
- like <command>GCC</command>.</para></listitem>
- </itemizedlist>
-
- <para>Some of the requirements proved challenging. For example,
- interactive programs do not lend themselves very well to automated testing.
- But all the requirements are important. For instance, it is imperative to
- make sure that <command>GDB</command> works as well when cross-debugging
- as it does in a native configuration. </para>
-
- <para>Probably the greatest challenge was testing in a
- cross-development environment. Most cross-development
- environments are customized by each developer. Even when buying
- packaged boards from vendors there are many differences. The
- communication interfaces vary from a serial line to Ethernet.
- &dj; 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 written, any test can
- use it. Currently &dj; can use <command>rsh</command>,
- <command>rlogin</command>, <command>telnet</command>,
- <command>tip</command>, and <command>kermit</command> for remote
- communications.</para>
-
- </sect2>
-
- <sect2 id="posix" xreflabel="A POSIX Conforming Test Framework">
- <title>A POSIX compliant test framework</title>
-
- <para>&dj; conforms to the POSIX 1003.3 standard for test
- frameworks. Rob Savoye was a member of that committee.</para>
-
- <para>POSIX standard 1003.3 defines what a testing framework
- needs to provide to create a POSIX compliant testsuite. This
- standard is primarily oriented to checking POSIX conformance,
- 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 was created by
- Unisoft for a consortium comprised of X/Open, Unix International
- and the Open Software Foundation.</para>
-
- <para>The POSIX documentation refers to <firstterm>assertions</firstterm>.
- An assertion is a description of behavior. For example, if a standard
- says ``The sun shall shine'', a corresponding assertion might be ``The
- sun is shining.'' A test based on this assertion would pass or fail
- depending on whether it is day or night. It is important to note
- that the standard being tested is never 1003.3; the standard being tested
- is some other standard, for which the assertions were written.</para>
-
- <para>As there is no testsuite to verify that testing frameworks
- are POSIX 1003.3 compliant, this is done by repeatedly reading
- the standard and experimenting. One of the main things POSIX
- 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. &dj; supports all five output messages. In
- this sense a testsuite that uses exactly these messages can be
- considered POSIX compliant. These definitions specify the
- output of a test case:</para>
-
- <variablelist>
- <varlistentry>
- <term>PASS</term>
- <listitem><para>A test has succeeded. That is, it demonstrated that
- the assertion is true.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>FAIL</term>
- <listitem><para>A test has not succeeded -- the assertion is
- false. The <emphasis>FAIL</emphasis> message is based on
- this test case only. Other messages are used to indicate a
- failure of the framework. As with <emphasis>PASS</emphasis>,
- POSIX tests must return
- <emphasis>FAIL</emphasis> rather than <emphasis>XFAIL</emphasis> even
- if a failure was expected.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>XFAIL</term>
- <listitem><para>POSIX 1003.3 does not incorporate the notion of
- expected failures, so <emphasis>PASS</emphasis>, instead of
- <emphasis>XPASS</emphasis>, must also be returned for test cases
- which were expected to fail and did not. This means that
- <emphasis>PASS</emphasis> is in some sense more ambiguous than if
- <emphasis>XPASS</emphasis> is also used.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>UNRESOLVED</term>
- <listitem><para>A test produced indeterminate results. Usually, this
- means the test executed in an unexpected fashion. This outcome
- requires a human to go over results to determine if the test
- should have passed or failed. This message is also used for any test
- that requires human intervention because it is beyond the abilities
- of the testing framework. Any unresolved test should resolved to
- <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> before a test
- run can be considered finished.</para>
-
- <para>Note that for POSIX, each assertion must produce a test result
- code. If the test isn't actually run, it must produce
- <emphasis>UNRESOLVED</emphasis> rather than just leaving that test
- out of the output. This means that you have to be careful when
- writing tests to not carelessly use Tcl commands like
- <emphasis>return</emphasis>---if you alter the flow of control of the
- Tcl code you must insure that every test still produces some result
- code.</para>
-
- <para>Here are some of the ways a test may wind up
- <emphasis>UNRESOLVED</emphasis>:</para></listitem>
-
- </varlistentry>
- </variablelist>
-
- <itemizedlist>
- <listitem><para>Execution of a test 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 &dj; 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 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
- has failed.</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></listitem>
- </varlistentry>
- </variablelist>
-
- <variablelist>
- <varlistentry>
- <term>UNSUPPORTED</term>
- <listitem><para>There is no support for the tested case. This may
- mean that a conditional feature of an operating system, or of a
- compiler, is not implemented. &dj; also uses this message when
- a testing environment (often a ``bare board'' target) lacks basic
- support for compiling or running the test case. For example, a
- test for the system subroutine <emphasis>gethostname</emphasis>
- would never work on a target board running only a boot
- monitor.</para></listitem>
- </varlistentry>
- </variablelist>
-
- <para>&dj; uses the same output procedures to produce these messages
- for all testsuites and these procedures are already known to conform
- to POSIX 1003.3. For a &dj; testsuite to conform to POSIX 1003.3,
- you must avoid the <emphasis>setup_xfail</emphasis> procedure as
- described in the <emphasis>PASS</emphasis> section above and you must
- be careful to return <emphasis>UNRESOLVED</emphasis> where appropriate,
- as described in the <emphasis>UNRESOLVED</emphasis> section
- above.</para>
- </sect2>
-
- <sect2 id="installation" xreflabel="Installation">
- <title>Installation</title>
-
- <para>Refer to the <filename>INSTALL</filename> in the source
- distribution for detailed installation instructions. Note that
- there is no compilation step as with many other GNU packages, as
- &dj; consists of interpreted code only.</para>
-
- <para>Save for its own small testsuite, the &dj; distribution does
- not include any testsuites. Testsuites for the various GNU
- development tools are included with those packages. After
- configuring the top-level &dj; directory, unpack and configure
- the test directories for the tools you want to test; then, in
- each test directory, run <emphasis>make check</emphasis> to
- build auxiliary programs required by some of the tests, and run
- the test suites.</para>
- </sect2>
-
- </sect1>
-
- <!-- include the user manual -->
- &user;
-
- <!-- include the reference manual -->
- &ref;
-
-</article>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-namecase-general:t
-sgml-general-insert-case:lower
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:nil
-sgml-parent-document:nil
-sgml-exposed-tags:nil
-sgml-local-catalogs:nil
-sgml-local-ecat-files:nil
-End:
--->
+++ /dev/null
- <legalnotice id="legalnotice">
- <para>
- Permission is granted to copy, distribute and/or modify this
- document under the terms of the GNU Free Documentation
- License (GFDL), Version 1.1 or any later version published
- by the Free Software Foundation with no Invariant Sections,
- no Front-Cover Texts, and no Back-Cover Texts. You can find
- a copy of the GFDL at this <ulink type="help"
- url="ghelp:fdl">link</ulink> or in the file COPYING-DOCS
- distributed with this manual.
- </para>
- <para> This manual is part of a collection of GNOME manuals
- distributed under the GFDL. If you want to distribute this
- manual separately from the collection, you can do so by
- adding a copy of the license to the manual, as described in
- section 6 of the license.
- </para>
-
- <para>
- Many of the names used by companies to distinguish their
- products and services are claimed as trademarks. Where those
- names appear in any GNOME documentation, and the members of
- the GNOME Documentation Project are made aware of those
- trademarks, then the names are in capital letters or initial
- capital letters.
- </para>
-
- <para>
- DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED
- UNDER THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE
- WITH THE FURTHER UNDERSTANDING THAT:
-
- <orderedlist>
- <listitem>
- <para>DOCUMENT IS PROVIDED ON AN "AS IS" BASIS,
- WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR
- IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES
- THAT THE DOCUMENT OR MODIFIED VERSION OF THE
- DOCUMENT IS FREE OF DEFECTS MERCHANTABLE, FIT FOR
- A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE
- RISK AS TO THE QUALITY, ACCURACY, AND PERFORMANCE
- OF THE DOCUMENT OR MODIFIED VERSION OF THE
- DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR
- MODIFIED VERSION PROVE DEFECTIVE IN ANY RESPECT,
- YOU (NOT THE INITIAL WRITER, AUTHOR OR ANY
- CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY
- SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER
- OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS
- LICENSE. NO USE OF ANY DOCUMENT OR MODIFIED
- VERSION OF THE DOCUMENT IS AUTHORIZED HEREUNDER
- EXCEPT UNDER THIS DISCLAIMER; AND
- </para>
- </listitem>
- <listitem>
- <para>UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL
- THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE),
- CONTRACT, OR OTHERWISE, SHALL THE AUTHOR,
- INITIAL WRITER, ANY CONTRIBUTOR, OR ANY
- DISTRIBUTOR OF THE DOCUMENT OR MODIFIED VERSION
- OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH
- PARTIES, BE LIABLE TO ANY PERSON FOR ANY
- DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR
- CONSEQUENTIAL DAMAGES OF ANY CHARACTER
- INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS
- OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR
- MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR
- LOSSES ARISING OUT OF OR RELATING TO USE OF THE
- DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT,
- EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF
- THE POSSIBILITY OF SUCH DAMAGES.
- </para>
- </listitem>
- </orderedlist>
- </para>
- </legalnotice>
-
+++ /dev/null
-
-<sect1 id="reference">
- <title>Reference</title>
-
- <sect2 id="builtins" xreflabel="Builtin Procedures">
- <title>Builtin Procedures</title>
-
- <para>&dj; provides these Tcl procedures.</para>
-
- <sect3 id="coreprocs" xreflabel="Core Internal Procedures">
- <title>Core Internal Procedures</title>
-
- <sect4 id="mailfile" xreflabel="mail_file procedure">
- <title>Mail_file Procedure</title>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>mail_file</function></funcdef>
- <paramdef><parameter>file to
- subject</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter></parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="openlogs" xreflabel="open_logs procedure">
- <title>Open_logs Procedure</title>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>open_logs</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="closelogs" xreflabel="close_logs procedure">
- <title>Close_logs Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>close_logs</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="isbuild" xreflabel="isbuild procedure">
- <title>Isbuild Procedure</title>
-
- <para>Tests for a particular build host environment. If the
- currently configured host matches the argument string, the result is
- <emphasis>1</emphasis>; otherwise the result is
- <emphasis>0</emphasis>. <emphasis>host</emphasis> must be a full
- three-part configure host name; in particular, you may not use the
- shorter nicknames supported by configure (but you can use wildcard
- characters, using shell syntax, to specify sets of names). If it is
- passed a NULL string, then it returns the name of the build canonical
- configuration.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>isbuild</function></funcdef>
- <paramdef><parameter>pattern</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>pattern</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="isremote" xreflabel="is_remote procedure">
- <title>Is_remote Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>is_remote</function></funcdef>
- <paramdef><parameter>board</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter></parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="is3way" xreflabel="is3way procedure">
- <title>is3way Procedure</title>
-
- <para>Tests for a Canadian cross. This is when the tests will be run
- on a remotely hosted cross compiler. If it is a Canadian cross, then
- the result is <emphasis>1</emphasis>; otherwise the result is
- <emphasis>0</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>is3way</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="ishost" xreflabel="ishost procedure">
- <title>Ishost Procedure</title>
-
- <para>Tests for a particular host environment. If the currently
- configured host matches the argument string, the result is
- <emphasis>1</emphasis>; otherwise the result is
- <emphasis>0</emphasis>. <emphasis>host</emphasis> must be a full
- three-part configure host name; in particular, you may not use the
- shorter nicknames supported by configure (but you can use wildcard
- characters, using shell syntax, to specify sets of names).</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>ishost</function></funcdef>
- <paramdef><parameter>pattern</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter></parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="istarget" xreflabel="istarget procedure">
- <title>Istarget Procedure</title>
-
- <para>Tests for a particular target environment. If the currently
- configured target matches the argument string, the result is
- <emphasis>1</emphasis> ; otherwise the result is
- <emphasis>0</emphasis>. target must be a full three-part configure
- target name; in particular, you may not use the shorter nicknames
- supported by configure (but you can use wildcard characters, using
- shell syntax, to specify sets of names). If it is passed a
- <emphasis>NULL</emphasis> string, then it returns the name of the
- build canonical configuration.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>istarget</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter></parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="isnative" xreflabel="isnative procedure">
- <title>Isnative Procedure</title>
-
- <para>Tests whether the current configuration has the same host and
- target. When it runs in a native configuration this procedure returns
- a <emphasis>1</emphasis>; otherwise it returns a
- <emphasis>0</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>isnative</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="unknown" xreflabel="unknown procedure">
- <title>Unknown Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>unknown</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="cloneoutput" xreflabel="clone_output procedure">
- <title>Clone_output Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>clone_output</function></funcdef>
- <paramdef><parameter>message</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>message</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="resetvars" xreflabel="reset_vars procedure">
- <title>Reset_vars Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>reset_vars</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="logandexit" xreflabel="log_and_exit procedure">
- <title>Log_and_exit Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>log_and_exit</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="logsummary" xreflabel="log_summary procedure">
- <title>Log_summary Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>log_summary</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="setupxfail" xreflabel="setup_xfail procedure">
- <title>Setup_xfail Procedure</title>
-
- <para>Declares that the test is expected to fail on a particular set
- of configurations. The config argument must be a list of full
- three-part configure target name; in particular, you may not use the
- shorter nicknames supported by configure (but you can use the common
- shell wildcard characters to specify sets of names). The
- <emphasis>bugid</emphasis> argument is optional, and used only in the
- logging file output; use it as a link to a bug-tracking system such
- as <productname>GNATS</productname>.</para>
-
- <para>Once you use <function>setup_xfail</function>, the
- <function>fail</function> and <function>pass</function> procedures
- produce the messages <emphasis>XFAIL</emphasis> and
- <emphasis>XPASS</emphasis> respectively, allowing you to distinguish
- expected failures (and unexpected success!) from other test
- outcomes.</para>
-
- <warning><para>Warning you must clear the expected failure after
- using setup_xfail in a test case. Any call to <function>pass
- </function>or <function>fail</function> clears the expected failure
- implicitly; if the test has some other outcome, e.g. an error, you
- can call <function>clear_xfail</function> to clear the expected
- failure explicitly. Otherwise, the expected-failure declaration
- applies to whatever test runs next, leading to surprising
- results.</para></warning>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>setup_xfail</function></funcdef>
- <paramdef><parameter>config</parameter>
- <parameter>bugid</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>config</parameter></term>
- <listitem><para>The config triplet to trigger whether this is an
- unexpected or expect failure.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>bugid</parameter></term>
- <listitem><para>The optional bugid, used to tie this test case
- to a bug tracking system.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="recordtest" xreflabel="record_test procedure">
- <title>Record_test Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>record_test</function></funcdef>
- <paramdef><parameter>type</parameter>
- <parameter>message</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>type</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>message</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="pass" xreflabel="pass procedure">
- <title>Pass Procedure</title>
-
- <para>Declares a test to have passed. <function>pass</function>
- writes in the log files a message beginning with
- <emphasis>PASS</emphasis> (or <emphasis>XPASS</emphasis>, if failure
- was expected), appending the argument
- <parameter>string</parameter>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>pass</function></funcdef>
- <paramdef><parameter>string</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>string</parameter></term>
- <listitem><para>The string to use for this PASS
- message.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="fail" xreflabel="fail procedure">
- <title>Fail Procedure</title>
-
- <para>Declares a test to have failed. <function>fail</function>
- writes in the log files a message beginning with
- <emphasis>FAIL</emphasis> (or <emphasis>XFAIL</emphasis>, if failure
- was expected), appending the argument
- <parameter>string</parameter>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>fail</function></funcdef>
- <paramdef><parameter>string</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>string</parameter></term>
- <listitem><para>The string to use for this FAIL
- message.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="xpass" xreflabel="xpass procedure">
- <title>Xpass Procedure</title>
-
- <para>Declares a test to have unexpectedly passed, when it was
- expected to be a failure. <function>xpass</function>
- writes in the log files a message beginning with
- <emphasis>XPASS</emphasis> (or <emphasis>XFAIL</emphasis>, if failure
- was expected), appending the argument
- <parameter>string</parameter>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>xpass</function></funcdef>
- <paramdef><parameter>string</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>string</parameter></term>
- <listitem><para>The string to use for this output
- state.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="xfail" xreflabel="xfail procedure">
- <title>Xfail Procedure</title>
-
- <para>Declares a test to have expectedly
- failed. <function>xfail</function>
- writes in the log files a message beginning with
- <emphasis>XFAIL</emphasis> (or <emphasis>PASS</emphasis>, if success
- was expected), appending the argument
- <parameter>string</parameter>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>xpass</function></funcdef>
- <paramdef><parameter>string</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>string</parameter></term>
- <listitem><para>The string to use for this output
- state.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="setwarningthreshold" xreflabel="set_warning_threshold procedure">
- <title>Set_warning_threshold Procedure</title>
-
- <para>Sets the value of <symbol>warning_threshold</symbol>. A value
- of <emphasis>0</emphasis> disables it: calls to
- <function>warning</function> will not turn a
- <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> into an
- <emphasis>UNRESOLVED</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>set_warning_threshold</function></funcdef>
- <paramdef><parameter>threshold</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>threshold</parameter></term>
- <listitem><para>This is the value of the new warning
- threshold.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="getwarningthreshold" xreflabel="get_warning_threshold procedure">
- <title>Get_warning_threshold Procedure</title>
-
- <para>Returns the current value of
- <symbol>{warning_threshold</symbol>. The default value is 3. This
- value controls how many <function>warning</function> procedures can
- be called before becoming <emphasis>UNRESOLVED</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>get_warning_threshold</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- </sect4>
- <sect4 id="warning" xreflabel="warning procedure">
- <title>Warning Procedure</title>
-
- <para>Declares detection of a minor error in the test case
- itself. <function>warning</function> writes in the log files a message
- beginning with <emphasis>WARNING</emphasis>, appending the argument
- <parameter>string</parameter>. Use <function>warning</function> rather
- than <function>perror</function> for cases (such as communication
- failure to be followed by a retry) where the test case can recover from
- the error. If the optional <parameter>number</parameter> is supplied,
- then this is used to set the internal count of warnings to that
- value.</para>
-
- <para>As a side effect, <symbol>warning_threshold</symbol> or more
- calls to warning in a single test case also changes the effect of the
- next <function>pass</function> or <function>fail</function> command:
- the test outcome becomes <emphasis>UNRESOLVED</emphasis> since an
- automatic <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> may
- not be trustworthy after many warnings. If the optional numeric value
- is <emphasis>0</emphasis>, then there are no further side effects to
- calling this function, and the following test outcome doesn't become
- <emphasis>UNRESOLVED</emphasis>. This can be used for errors with no
- known side effects.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>warning</function></funcdef>
- <paramdef><parameter>string</parameter>
- <parameter>number</parameter>
- </paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>string</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>number</parameter></term>
- <listitem><para>The optional number to set the error counter. This
- is only used to fake out the counter when using the
- <function>xfail</function> procedure to control when it flips the
- output over to <emphasis>UNRESOLVED</emphasis>
- state.</para></listitem>
- </varlistentry>
- </variablelist>
-
- </sect4>
- <sect4 id="perror" xreflabel="perror procedure">
- <title>Perror Procedure</title>
-
- <para>Declares a severe error in the testing framework
- itself. <function>perror</function> writes in the log files a message
- beginning with <emphasis>ERROR</emphasis>, appending the argument
- <parameter>string</parameter>.</para>
-
- <para>As a side effect, perror also changes the effect of the next
- <function>pass</function> or <function>fail</function> command: the
- test outcome becomes <emphasis>UNRESOLVED</emphasis>, since an
- automatic <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> cannot
- be trusted after a severe error in the test framework. If the optional
- numeric value is <emphasis>0</emphasis>, then there are no further side
- effects to calling this function, and the following test outcome
- doesn't become <emphasis>UNRESOLVED</emphasis>. This can be used for
- errors with no known side effects.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>perror</function></funcdef>
- <paramdef><parameter>string</parameter>
- <parameter>number</parameter>
- </paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>string</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>number</parameter></term>
- <listitem><para>The optional number to set the error counter. This
- is only used to fake out the counter when using the
- <function>xfail</function> procedure to control when it flips the
- output over to <emphasis>UNRESOLVED</emphasis>
- state.</para></listitem>
- </varlistentry>
- </variablelist>
-
- </sect4>
- <sect4 id="note" xreflabel="note procedure">
- <title>Note Procedure</title>
-
- <para>Appends an informational message to the log
- file. <function>note</function> writes in the log files a message
- beginning with <emphasis>NOTE</emphasis>, appending the argument
- <parameter>string</parameter>. Use <function>note</function>
- sparingly. The <function>verbose</function> should be used for most
- such messages, but in cases where a message is needed in the log file
- regardless of the verbosity level use <function>note</function>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>note</function></funcdef>
- <paramdef><parameter>string</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>string</parameter></term>
- <listitem><para>The string to use for this note.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="untested" xreflabel="untested procedure">
- <title>Untested Procedure</title>
-
- <para>Declares a test was not run. <function>untested</function> writes
- in the log file a message beginning with <emphasis>UNTESTED</emphasis>,
- appending the argument <emphasis>string</emphasis>. For example, you
- might use this in a dummy test whose only role is to record that a test
- does not yet exist for some feature.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>untested</function></funcdef>
- <paramdef><parameter>string</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>string</parameter></term>
- <listitem><para>The string to use for this output
- state.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="unresolved" xreflabel="unresolved procedure">
- <title>Unresolved Procedure</title>
-
- <para>Declares a test to have an unresolved
- outcome. <function>unresolved</function> writes in the log file a
- message beginning with <emphasis>UNRESOLVED</emphasis>, appending the
- argument <emphasis>string</emphasis>. This usually means the test did
- not execute as expected, and a human being must go over results to
- determine if it passed or failed (and to improve the test case).</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>unresolved</function></funcdef>
- <paramdef><parameter>string</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>string</parameter></term>
- <listitem><para>The string to use for this output
- state.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="unsupported" xreflabel="unsupported procedure">
- <title>Unsupported Procedure</title>
-
- <para>Declares that a test case depends on some facility that does not
- exist in the testing environment. <function>unsupported</function>
- writes in the log file a message beginning with
- <emphasis>UNSUPPORTED</emphasis>, appending the argument string.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>unsupported</function></funcdef>
- <paramdef><parameter>string</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>string</parameter></term>
- <listitem><para>The string to use for this output
- state.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="inittestcounts" xreflabel="init_testcounts procedure">
- <title>Init_testcounts Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>init_testcounts</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="incrcount" xreflabel="incr_count procedure">
- <title>Incr_count Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>incr_count</function></funcdef>
- <paramdef><parameter>name</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>name</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="transform" xreflabel="transform procedure">
- <title>transform Procedure</title>
-
- <para>Generates a string for the name of a tool as it was configured
- and installed, given its native name (as the argument
- <parameter>toolname</parameter>). This makes the assumption that all
- tools are installed using the same naming conventions: For example,
- for a cross compiler supporting the <emphasis>m68k-vxworks</emphasis>
- configuration, the result of transform <command>gcc</command> is
- <command>m68k-vxworks-gcc</command>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>transform</function></funcdef>
- <paramdef><parameter>toolname</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>toolname</parameter></term>
- <listitem><para>The name of the cross-development program to
- transform.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
-
- <sect4 id="checkconditionalxfail" xreflabel="check_conditional_xfail procedure">
- <title>Check_conditional_xfail Procedure</title>
-
- <para>This procedure adds a conditional xfail, based on compiler
- options used to create a test case executable. If an include options
- is found in the compiler flags, and it's the right architecture,
- it'll trigger an <emphasis>XFAIL</emphasis>. Otherwise it'll produce
- an ordinary <emphasis>FAIL</emphasis>. You can also specify flags to
- exclude. This makes a result be a <emphasis>FAIL</emphasis>, even if
- the included options are found. To set the conditional, set
- the variable <symbol>compiler_conditional_xfail_data</symbol> to the
- fields</para>
- <programlisting>
- "[message string] [targets list] [includes list] [excludes list]"
- </programlisting>
- <para> (descriptions below). This is
- the checked at pass/fail decision time, so there is no need to call
- the procedure yourself, unless you wish to know if it gets
- triggered. After a pass/fail, the variable is reset, so it doesn't
- effect other tests. It returns <emphasis>1</emphasis> if the
- conditional is true, or <emphasis>0</emphasis> if the conditional is
- false.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>check_conditional_xfail</function></funcdef>
- <paramdef><parameter>message</parameter>
- <parameter>targets</parameter>
- <parameter>includes</parameter>
- <parameter>excludes</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>message</parameter></term>
- <listitem><para>This is the message to print with the normal test
- result.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>targets</parameter></term>
- <listitem><para>This is a string with the list targets to activate
- this conditional on.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>includes</parameter></term>
- <listitem><para>This is a list of sets of options to search for in
- the compiler options to activate this conditional. If the list of
- sets of options is empty or if any set of the options matches,
- then this conditional is true. (It may be useful to specify an
- empty list of include sets if the conditional is always true
- unless one of the exclude sets matches.)</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>excludes</parameter></term>
- <listitem><para>This is a list of sets of options to search for in
- the compiler options to activate this conditional. If any set of
- the options matches, (regardless of whether any of the include sets
- match) then this conditional is de-activated.</para></listitem>
- </varlistentry>
- </variablelist>
-
- <example>
- <title>Specifying the conditional xfail data</title>
-
- <programlisting>
- set compiler_conditional_xfail_data { \
- "I sure wish I knew why this was hosed" \
- "sparc*-sun*-* *-pc-*-*" \
- {"-Wall -v" "-O3"} \
- {"-O1" "-Map"} \
- }
- </programlisting>
-
- </example>
-
- <para>What this does is it matches only for these two targets if
- "-Wall -v" or "-O3" is set, but neither "-O1" or "-Map" is set. For
- a set to match, the options specified are searched for independently
- of each other, so a "-Wall -v" matches either "-Wall -v" or "-v
- -Wall". A space separates the options in the string. Glob-style
- regular expressions are also permitted.</para>
-
- </sect4>
-
- <sect4 id="clearxfail" xreflabel="clear_xfail procedure">
- <title>Clear_xfail Procedure</title>
-
- <para>Cancel an expected failure (previously declared with
- <command>setup_xfail</command>) for a particular set of
- configurations. The <parameter>config</parameter> argument is a list
- of configuration target names. It is only necessary to call
- <command>clear_xfail</command> if a test case ends without calling
- either <command>pass</command> or <command>fail</command>, after
- calling <command>setup_xfail</command>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>clear_xfail</function></funcdef>
- <paramdef><parameter>config</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>config</parameter></term>
- <listitem><para>The configuration triplets to
- clear.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="verbose" xreflabel="verbose procedure">
- <title>Verbose Procedure</title>
-
- <para>Test cases can use this function to issue helpful messages
- depending on the number of <option>--verbose</option> options on the
- runtest command line. It prints string if the value of the variable
- <symbol>verbose</symbol> is higher than or equal to the optional
- number. The default value for number is <emphasis>1</emphasis>. Use
- the optional <option>-log</option> argument to cause string to always
- be added to the log file, even if it won't be printed. Use the
- optional <option>-x</option> argument to log the test results into
- a parsable XML file. Use the optional <option>-n</option> argument
- to print string without a trailing newline. Use the optional
- <option>--</option> argument if string begins with "-".</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>verbose</function></funcdef>
- <paramdef><parameter>-log</parameter>
- <parameter>-x</parameter>
- <parameter>-n</parameter>
- <parameter>-r</parameter>
- <parameter>string</parameter>
- <parameter>number</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>-x</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>-log</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>-n</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>--</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>string</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>number</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="loadlib" xreflabel="load_lib procedure">
- <title>Load_lib Procedure</title>
-
- <para>Loads a &dj; library file by searching the default fixed paths
- built
- into &dj;. If &dj; has been installed, it looks in a path
- starting with the installed library directory. If you are running
- &dj; directly from a source directory, without first running
- <command>make install</command>, this path defaults to the current
- directory. In either case, it then looks in the current directory
- for a directory called <filename>lib</filename>. If there are
- duplicate definitions, the last one loaded takes precedence over the
- earlier ones.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>load_lib</function></funcdef>
- <paramdef><parameter>filespec</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>filespec</parameter></term>
- <listitem><para>The name of the &dj; library file to
- load.</para></listitem>
- </varlistentry>
- </variablelist>
- <para>The global variable <parameter>libdirs</parameter>, handled
- as a list, is appended to the default fixed paths built
- into &dj;.</para>
- <example>
- <title>Additional search directories for <function>load_lib</function></title>
- <programlisting># append a non-standard search path
- global libdirs
- lappend libdirs $srcdir/../../gcc/testsuite/lib
- # now loading $srcdir/../../gcc/testsuite/lib/foo.exp works
- load_lib foo.exp</programlisting>
- </example>
-
- </sect4>
-
- </sect3>
-
- <sect3 id="remoteprocs">
- <title>Procedures For Remote Communication</title>
-
- <para><filename>lib/remote.exp</filename> defines procedures for
- establishing and managing communications. Each of these
- procedures tries to establish the connection up to three times
- before returning. Warnings (if retries will continue) or
- errors (if the attempt is abandoned) report on communication
- failures. The result for any of these procedures is
- either <emphasis>-1</emphasis>, when the connection cannot be
- established, or the spawn ID returned by
- the <productname>Expect</productname> command
- <command>spawn</command>.</para>
-
- <para>It use the value of the <symbol>connect</symbol> field
- in the <symbol>target_info</symbol> array (was
- <symbol>connectmode</symbol> as the type of connection to
- make. Current supported connection types are tip, kermit,
- telnet, rsh, rlogin, and netdata. If the <option>--reboot</option>
- option was used on the runtest command line, then the target
- is rebooted before the connection is made.</para>
-
- <sect4 id="callremote" xreflabel="call_remote procedure">
- <title>Call_remote Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>call_remote</function></funcdef>
- <paramdef><parameter>type</parameter>
- <parameter>proc</parameter>
- <parameter>dest</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>proc</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="checkforboardstatus" xreflabel="check_for_board_status
- procedure">
- <title>Check_for_board_status Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>check_for_board_status</function></funcdef>
- <paramdef><parameter>variable</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>variable</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="fileonbuild" xreflabel="file_on_build procedure">
- <title>File_on_build Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>file_on_build</function></funcdef>
- <paramdef><parameter>op</parameter>
- <parameter>file</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>op</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>file</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="fileonhost" xreflabel="file_on_host procedure">
- <title>File_on_host Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>file_on_host</function></funcdef>
- <paramdef><parameter>op</parameter>
- <parameter>file</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>op</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>file</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="localexec" xreflabel="local_exec procedure">
- <title>Local_exec Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>local_exec</function></funcdef>
- <paramdef><parameter>commandline</parameter>
- <parameter>inp</parameter>
- <parameter>outp</parameter>
- <parameter>timeout</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>inp</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>outp</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>timeout</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remotebinary" xreflabel="remote_binary procedure">
- <title>Remote_binary Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_binary</function></funcdef>
- <paramdef><parameter>host</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>host</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoteclose" xreflabel="remote_close procedure">
- <title>Remote_close Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_close</function></funcdef>
- <paramdef><parameter>shellid</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>shellid</parameter></term>
- <listitem><para>This is the value returned by a call
- to <function>remote_open</function>. This closes the
- connection to the target so resources can be used by
- others. This parameter can be left off if the
- <symbol>fileid</symbol> field in the
- <symbol>target_info</symbol> array is set.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remotedownload" xreflabel="remote_download procedure">
- <title>Remote_download Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_download</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>file</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>file</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoteexec" xreflabel="remote_exec procedure">
- <title>Remote_exec Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_exec</function></funcdef>
- <paramdef><parameter>hostname</parameter>
- <parameter>program</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>hostname</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>program</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoteexpect" xreflabel="remote_expect procedure">
- <title>Remote_expect Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_expect</function></funcdef>
- <paramdef><parameter>board</parameter>
- <parameter>timeout</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>board</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>timeout</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remotefile" xreflabel="remote_file procedure">
- <title>Remote_file Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_file</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoteld" xreflabel="remote_ld procedure">
- <title>Remote_ld Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_ld</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>prog</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>prog</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoteload" xreflabel="remote_load procedure">
- <title>Remote_load Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_load</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>prog</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>prog</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoteopen" xreflabel="remote_open procedure">
- <title>Remote_open Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_open</function></funcdef>
- <paramdef><parameter>type</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>type</parameter></term>
- <listitem><para>This is passed <option>host</option> or
- <option>target</option>. Host or target refers to
- whether it is a connection to a remote target, or a
- remote host. This opens the connection to the desired
- target or host using the default values in the
- configuration system. It returns that
- <symbol>spawn_id</symbol> of the process that manages
- the connection. This value can be used in
- <productname>Expect</productname> or
- <command>exp_send</command> statements, or passed to
- other procedures that need the connection process's
- id. This also sets the <symbol>fileid</symbol> field in
- the <symbol>target_info</symbol> array.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remotepopconn" xreflabel="remote_pop_conn procedure">
- <title>Remote_pop_conn Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_pop_conn</function></funcdef>
- <paramdef><parameter>host</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>host</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remotepushconn" xreflabel="remote_push_conn procedure">
- <title>Remote_push_conn Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_push_conn</function></funcdef>
- <paramdef><parameter>host</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>host</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoterawbinary" xreflabel="remote_raw_binary procedure">
- <title>Remote_raw_binary Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_raw_binary</function></funcdef>
- <paramdef><parameter>host</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>host</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoterawclose" xreflabel="remote_raw_close procedure">
- <title>Remote_raw_close Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_raw_close</function></funcdef>
- <paramdef><parameter>host</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>host</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoterawfile" xreflabel="remote_raw_file procedure">
- <title>Remote_raw_file Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_raw_file</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoterawld" xreflabel="remote_raw_ld procedure">
- <title>remote_raw_ld Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_raw_ld</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>prog</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>prog</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoterawload" xreflabel="remote_raw_load procedure">
- <title>Remote_raw_load Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_raw_load</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>prog</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>prog</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoterawopen" xreflabel="remote_raw_open procedure">
- <title>Remote_raw_open Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_raw_open</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoterawsend" xreflabel="remote_raw_send procedure">
- <title>Remote_raw_send Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_raw_send</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>string</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>string</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoterawspawn" xreflabel="remote_raw_spawn procedure">
- <title>Remote_raw_spawn Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_raw_spawn</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>commandline</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>commandline</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoterawtransmit" xreflabel="remote_raw_transmit
- procedure">
- <title>Remote_raw_transmit Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_raw_transmit</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>file</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>file</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoterawwait" xreflabel="remote_raw_wait procedure">
- <title>Remote_raw_wait Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_raw_wait</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>timeout</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>timeout</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remotereboot" xreflabel="remote_reboot procedure">
- <title>Remote_reboot Procedure</title>
-
- <para>Return value of this function depends on actual implementation
- of reboot that will be used, in practice it is expected that
- <function>remote_reboot</function> returns <emphasis>1</emphasis>
- on success and <emphasis>0</emphasis> on failure.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_reboot</function></funcdef>
- <paramdef><parameter>host</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>host</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remotesend" xreflabel="remote_send procedure">
- <title>Remote_send Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_send</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>string</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>string</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remotespawn" xreflabel="remote_spawn procedure">
- <title>Remote_spawn Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_spawn</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>commandline</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>commandline</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoteswapconn" xreflabel="remote_swap_conn procedure">
- <title>Remote_swap_conn Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_swap_conn</function></funcdef>
- <paramdef><parameter>host</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter></parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remotetransmit" xreflabel="remote_transmit procedure">
- <title>Remote_transmit Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_transmit</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>file</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>file</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remoteupload" xreflabel="remote_upload procedure">
- <title>Remote_upload Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_upload</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>srcfile</parameter>
- <parameter>arg</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>srcfile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>arg</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="remotewait" xreflabel="remote_wait procedure">
- <title>Remote_wait Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>remote_wait</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>timeout</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>timeout</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="standardclose" xreflabel="standard_close procedure">
- <title>Standard_close Procedure</title>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>standard_close</function></funcdef>
- <paramdef><parameter>host</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>host</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="standarddownload" xreflabel="standard_download procedure">
- <title>Standard_download Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>standard_download</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>file</parameter>
- <parameter>destfile</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>file</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>destfile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="standardexec" xreflabel="standard_exec procedure">
- <title>Standard_exec Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>standard_exec</function></funcdef>
- <paramdef><parameter>hostname</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>hostname</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="standardfile" xreflabel="standard_file procedure">
- <title>Standard_file Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>standard_file</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>op</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter></parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="standardload" xreflabel="standard_load procedure">
- <title>Standard_load Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>standard_load</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>prog</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>prog</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="standardreboot" xreflabel="standard_reboot procedure">
- <title>Standard_reboot Procedure</title>
-
- <para>It looks like that this procedure is never called, instead
- <function>${board}_reboot</function> defined in
- <filename>base-config.exp</filename> will be used because it has
- higher priority and <filename>base-config.exp</filename> is
- always imported by <command>runtest</command>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>standard_reboot</function></funcdef>
- <paramdef><parameter>host</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>host</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="standardsend" xreflabel="standard_send procedure">
- <title>Standard_send Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>standard_send</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>string</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>string</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="standardspawn" xreflabel="standard_spawn procedure">
- <title>Standard_spawn Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>standard_spawn</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>commandline</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>commandline</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="standardtransmit" xreflabel="standard_transmit procedure">
- <title>Standard_transmit Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>standard_transmit</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>file</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>file</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="standardupload" xreflabel="standard_upload procedure">
- <title>Standard_upload Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>standard_upload</function></funcdef>
- <paramdef><parameter>dest srcfile destfile</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>srcfile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>destfile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="standardwait" xreflabel="standard_wait procedure">
- <title>Standard_wait Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>standard_wait</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>timeout</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>timeout</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="unixcleanfilename" xreflabel="unix_clean_filename
- procedure">
- <title>Unix_clean_filename Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>unix_clean_filename</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>file</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>file</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
- </sect3>
-
- <sect3 id="connprocs" xreflabel="connprocs">
- <title>Procedures For Using Utilities to Connect</title>
-
- <para>telnet, rsh, tip, kermit</para>
-
- <sect4 id="telnet" xreflabel="telnet procedure">
- <title>telnet Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>telnet</function></funcdef>
- <paramdef><parameter>hostname</parameter>
- <parameter>port</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>rlogin</function></funcdef>
- <paramdef><parameter>hostname</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="rsh" xreflabel="rsh procedure">
- <title>rsh Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>rsh</function></funcdef>
- <paramdef><parameter>hostname</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>hostname</parameter></term>
- <listitem><para>This refers to the IP address or name
- (for example, an entry in
- <filename>/etc/hosts</filename>) for this target. The
- procedure names reflect the Unix utility used to
- establish a connection. The optional
- <parameter>port</parameter> is used to specify the IP
- port number. The value of the
- <parameter>netport</parameter> field in the
- <symbol>target_info</symbol> array is used. (was
- <symbol>$netport</symbol>) This value has two parts,
- the hostname and the port number, separated by a
- <emphasis>:</emphasis>. If host or target is used in
- the <symbol>hostname</symbol> field, than the
- config array is used for all information.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="tip" xreflabel="tip procedure">
- <title>Tip Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>tip</function></funcdef>
- <paramdef><parameter>port</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>port</parameter></term>
- <listitem><para>Connect using the Unix utility
- <command>tip</command>. <parameter>Port</parameter>must
- be a name from the <productname>tip</productname>
- configuration file
- <filename>/etc/remote</filename>. Often, this is called
- <symbol>hardwire</symbol>, or something like
- <symbol>ttya</symbol>. This file holds all the
- configuration data for the serial port. The value of
- the <symbol>serial</symbol> field in the
- <symbol>target_info</symbol> array is used. (was
- <symbol>$serialport</symbol>) If <option>host</option>
- or <option>target</option> is used in the
- <parameter>port</parameter> field, than the config
- array is used for all information. the
- config array is used for all information.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="kermit" xreflabel="kermit procedure">
- <title>Kermit Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>kermit</function></funcdef>
- <paramdef><parameter>port</parameter>
- <parameter>bps</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>port</parameter></term>
- <listitem><para>Connect using the program
- <command>kermit</command>. <parameter>Port</parameter>
- is the device name,
- e.g. <filename>/dev/ttyb</filename>.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>bps</parameter></term>
- <listitem><para><parameter>bps</parameter> is the line
- speed to use (in its per second) for the
- connection. The value of the <symbol>serial</symbol>
- field in the <symbol>target_info</symbol> array is
- used. (was <symbol>$serialport</symbol>) If
- <option>host</option> or <option>target</option> is
- used in the <parameter>port</parameter> field, than the
- config array is used for all information. the
- config array is used for all information.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="kermitopen" xreflabel="kermit_open procedure">
- <title>kermit_open Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>kermit_open</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="kermitcommand" xreflabel="kermit_command procedure">
- <title>Kermit_command Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>kermit_command</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="kermitsend" xreflabel="kermit_send procedure">
- <title>Kermit_send Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>kermit_send</function></funcdef>
- <paramdef><parameter>dest string args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>string</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="kermittransmit" xreflabel="kermit_transmit procedure">
- <title>Kermit_transmit Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>kermit_transmit</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>file</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>file</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="telnetopen" xreflabel="telnet_open procedure">
- <title>Telnet_open Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>telnet_open</function></funcdef>
- <paramdef><parameter>hostname</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>hostname</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="telnetbinary" xreflabel="telnet_binary procedure">
- <title>Telnet_binary Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>telnet_binary</function></funcdef>
- <paramdef><parameter>hostname</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>hostname</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="telnettransmit" xreflabel="telnet_transmit procedure">
- <title>Telnet_transmit Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>telnet_transmit</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>file</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>file</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="tipopen" xreflabel="tip_open procedure">
- <title>Tip_open Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>tip_open</function></funcdef>
- <paramdef><parameter>hostname</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>hostname</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="rloginopen" xreflabel="rlogin_open procedure">
- <title>Rlogin_open Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>rlogin_open</function></funcdef>
- <paramdef><parameter>arg</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>arg</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="rloginspawn" xreflabel="rlogin_spawn procedure">
- <title>Rlogin_spawn Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>rlogin_spawn</function></funcdef>
- <paramdef><parameter>dest</parameter>
- <parameter>cmdline</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>dest</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>cmdline</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="rshopen" xreflabel="rsh_open procedure">
- <title>Rsh_open Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>rsh_open</function></funcdef>
- <paramdef><parameter>hostname</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>hostname</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="rshdownload" xreflabel="rsh_download procedure">
- <title>Rsh_download Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>rsh_download</function></funcdef>
- <paramdef><parameter>desthost</parameter>
- <parameter>srcfile</parameter>
- <parameter>destfile</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>desthost</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>srcfile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>destfile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="rshupload" xreflabel="rsh_upload procedure">
- <title>Rsh_upload Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>rsh_upload</function></funcdef>
- <paramdef><parameter>desthost</parameter>
- <parameter>srcfile</parameter>
- <parameter>destfile</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>desthost</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>srcfile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>destfile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="rshexec" xreflabel="rsh_exec procedure">
- <title>Rsh_exec Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>rsh_exec</function></funcdef>
- <paramdef><parameter>boardname</parameter>
- <parameter>cmd</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>boardname</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>cmd</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="ftpopen" xreflabel="ftp_open procedure">
- <title>Ftp_open Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>ftp_open</function></funcdef>
- <paramdef><parameter>host</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>host</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="ftpupload" xreflabel="ftp_upload procedure">
- <title>Ftp_upload Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>ftp_upload</function></funcdef>
- <paramdef><parameter>host</parameter>
- <parameter>remotefile</parameter>
- <parameter>localfile</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>host</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>remotefile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>localfile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="ftpdownload" xreflabel="ftp_download procedure">
- <title>Ftp_download Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>ftp_download</function></funcdef>
- <paramdef><parameter>host</parameter>
- <parameter>localfile</parameter>
- <parameter>remotefile</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>host</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>localfile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>remotefile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="ftpclose" xreflabel="ftp_close procedure">
- <title>Ftp_close Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>ftp_close</function></funcdef>
- <paramdef><parameter>host</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>host</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="tipdownload" xreflabel="tip_download procedure">
- <title>Tip_download Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>tip_download</function></funcdef>
- <paramdef><parameter>spawnid</parameter>
- <parameter>file</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>spawnid</parameter></term>
- <listitem><para>Download <option>file</option> to the
- process <symbol>spawnid</symbol> (the value returned
- when the connection was established), using the
- <command>~put</command> command under
- <productname>tip</productname>. Most often used for
- single board computers that require downloading
- programs in ASCII S-records. Returns
- <emphasis>1</emphasis> if an error occurs,
- <emphasis>0</emphasis> otherwise.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>file</parameter></term>
- <listitem><para>This is the filename to
- download.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
- </sect3>
-
- <sect3 id="targetprocs">
- <title>Procedures For Target Boards</title>
-
- <para></para>
-
- <sect4 id="defaultlink" xreflabel="default_link procedure">
- <title>Default_link Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>default_link</function></funcdef>
- <paramdef><parameter>board</parameter>
- <parameter>objects</parameter>
- <parameter>destfile</parameter>
- <parameter>flags</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>board</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>objects</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>destfile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>flags</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="defaulttargetassemble" xreflabel="default_target_assemble
- procedure">
- <title>Default_target_assemble Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>default_target_assemble</function></funcdef>
- <paramdef><parameter>source</parameter>
- <parameter>destfile</parameter>
- <parameter>flags</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>source</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>destfile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>flags</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="defaulttargetcompile" xreflabel="default_target_compile
- procedure">
- <title>default_target_compile Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>default_target_compile</function></funcdef>
- <paramdef><parameter>source</parameter>
- <parameter>destfile</parameter>
- <parameter>type</parameter>
- <parameter>options</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>source</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>destfile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>type</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>options</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="popconfig" xreflabel="pop_config procedure">
- <title>Pop_config Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>pop_config</function></funcdef>
- <paramdef><parameter>type</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>type</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="prunewarnings" xreflabel="prune_warnings procedure">
- <title>Prune_warnings Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>prune_warnings</function></funcdef>
- <paramdef><parameter>text</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>text</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="pushbuild" xreflabel="push_build procedure">
- <title>Push_build Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>push_build</function></funcdef>
- <paramdef><parameter>name</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>name</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="pushconfig" xreflabel="push_config procedure">
- <title>push_config Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>push_config</function></funcdef>
- <paramdef><parameter>type</parameter>
- <parameter>name</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>type</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>name</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="reboottarget" xreflabel="reboot_target procedure">
- <title>Reboot_target Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>reboot_target</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="targetassemble" xreflabel="target_assemble procedure">
- <title>Target_assemble Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>target_assemble</function></funcdef>
- <paramdef><parameter>source destfile flags</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>source</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>destfile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>flags</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="targetcompile" xreflabel="target_compile procedure">
- <title>Target_compile Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>target_compile</function></funcdef>
- <paramdef><parameter>source</parameter>
- <parameter>destfile</parameter>
- <parameter>type</parameter>
- <parameter>options</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>source</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>destfile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>type</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>options</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
- </sect3>
-
- <sect3 id="targetdb" xreflabel="target database library file ">
- <title>Target Database Procedures</title>
-
- <sect4 id="boardinfo" xreflabel="board_info procedure">
- <title>Board_info Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>board_info</function></funcdef>
- <paramdef><parameter>machine</parameter>
- <parameter>op</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>machine</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>op</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="hostinfo" xreflabel="host_info procedure">
- <title>Host_info Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>host_info</function></funcdef>
- <paramdef><parameter>op</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>op</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="setboardinfo" xreflabel="set_board_info procedure">
- <title>Set_board_info Procedure</title>
-
- <para>This checks if <symbol>board_info</symbol> array's field
- <emphasis>entry</emphasis> has been set already and if not, then
- sets it to <emphasis>value</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>set_board_info</function></funcdef>
- <paramdef><parameter>entry</parameter>
- <parameter>value</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>entry</parameter></term>
- <listitem><para>The name of a <symbol>board_info</symbol> field
- to operate on.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>value</parameter></term>
- <listitem><para>The value to set the field to.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="addboardinfo" xreflabel="add_board_info procedure">
- <title>Add_board_info Procedure</title>
-
- <para>This treats <symbol>board_info</symbol> array's field
- <emphasis>entry</emphasis> as a TCL list and adds
- <emphasis>value</emphasis> at the end.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>add_board_info</function></funcdef>
- <paramdef><parameter>entry</parameter>
- <parameter>value</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>entry</parameter></term>
- <listitem><para>The name of a <symbol>board_info</symbol> field
- to operate on.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>value</parameter></term>
- <listitem><para>The value to add to the field.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="setcurrtargetinfo" xreflabel="set_currtarget_info
- procedure">
- <title>Set_currtarget_info Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>set_currtarget_info</function></funcdef>
- <paramdef><parameter>entry</parameter>
- <parameter>value</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>entry</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>value</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="targetinfo" xreflabel="target_info procedure">
- <title>Target_info Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>target_info</function></funcdef>
- <paramdef><parameter>op</parameter>
- <parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>op</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="unsetboardinfo" xreflabel="unset_board_info procedure">
- <title>Unset_board_info Procedure</title>
-
- <para>This checks if <symbol>board_info</symbol> array's field
- <emphasis>entry</emphasis> has been set and if so, then removes
- it.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>unset_board_info</function></funcdef>
- <paramdef><parameter>entry</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>entry</parameter></term>
- <listitem><para>The name of a <symbol>board_info</symbol> field
- to operate on.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="unsetcurrtargetinfo" xreflabel="unset_currtarget_info
- procedure">
- <title>Unset_currtarget_info Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>unset_currtarget_info</function></funcdef>
- <paramdef><parameter>entry</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>entry</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="pushtarget" xreflabel="push_target procedure">
- <title>Push_target Procedure</title>
-
- <para>This makes the target named <emphasis>name</emphasis> be the
- current target connection. The value of <emphasis>name</emphasis> is
- an index into the <symbol>target_info</symbol> array and is set in
- the global config file.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>push_target</function></funcdef>
- <paramdef><parameter>name</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>name</parameter></term>
- <listitem><para>The name of the target to make current
- connection.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="poptarget" xreflabel="poptarget procedure">
- <title>Pop_target Procedure</title>
-
- <para>This unsets the current target connection.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>pop_target</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="listtargets" xreflabel="list_targets procedure">
- <title>List_targets Procedure</title>
-
- <para>This lists all the supported targets for this
- architecture.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>list_targets</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="pushhost" xreflabel="push_host procedure">
- <title>Push_host Procedure</title>
-
- <para>This makes the host named <emphasis>name</emphasis> be the
- current remote host connection. The value of
- <emphasis>name</emphasis> is an index into the
- <symbol>target_info</symbol> array and is set in the global config
- file.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>push_host</function></funcdef>
- <paramdef><parameter>name</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>name</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="pophost" xreflabel="pop_host procedure">
- <title>Pop_host Procedure</title>
-
- <para>This unsets the current host connection.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>pop_host</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="compile" xreflabel="compile procedure">
- <title>Compile Procedure</title>
-
- <para>This invokes the compiler as set by CC to compile the
- file <filename>file</filename>. The default options for many cross
- compilation targets are <emphasis>guessed</emphasis> by &dj;, and
- these options can be added to by passing in more parameters as
- arguments to <command>compile</command>. Optionally, this will also
- use the value of the <emphasis>cflags</emphasis> field in the target
- config array. If the host is not the same as the build machines, then
- then compiler is run on the remote host using
- <command>execute_anywhere</command>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>compile</function></funcdef>
- <paramdef><parameter>file</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>file</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="archive" xreflabel="archive procedure">
- <title>Archive Procedure</title>
-
- <para>This produces an archive file. Any parameters passed to
- <command>archive</command> are used in addition to the default
- flags. Optionally, this will also use the value of the
- <emphasis>arflags</emphasis> field in the target config array. If the
- host is not the same as the build machines, then then archiver is run
- on the remote host using <command>execute_anywhere</command>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>archive</function></funcdef>
- <paramdef><parameter>file</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>file</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="ranlib" xreflabel="ranlib procedure">
- <title>Ranlib Procedure</title>
-
- <para>This generates an index for the archive file for systems that
- aren't POSIX yet. Any parameters passed to <command>ranlib</command>
- are used in for the flags.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>ranlib</function></funcdef>
- <paramdef><parameter>file</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>file</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="executeanywhere" xreflabel="execute_anywhere procedure">
- <title>Execute_anywhere Procedure</title>
-
- <para>This executes the <emphasis>cmdline</emphasis> on the proper
- host. This should be used as a replacement for the Tcl command
- <command>exec</command> as this version utilizes the target config
- info to execute this command on the build machine or a remote
- host. All config information for the remote host must be setup to
- have this command work. If this is a Canadian cross (where we test a
- cross compiler that runs on a different host then where &dj; is
- running) then a connection is made to the remote host and the command
- is executed there. It returns either REMOTERROR (for an error) or the
- output produced when the command was executed. This is used for
- running the tool to be tested, not a test case.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>execute_anywhere</function></funcdef>
- <paramdef><parameter>cmdline</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>cmdline</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- </sect3>
- <sect3 id="platformprocs" xreflabel="platform dependent procedures">
- <title>Platform Dependent Procedures</title>
-
- <para>Each combination of target and tool requires some
- target-dependent procedures. The names of these procedures have
- a common form: the tool name, followed by an underscore
- <emphasis>_</emphasis>, and finally a suffix describing the
- procedure's purpose. For example, a procedure to extract the
- version from <productname>GDB</productname> is called
- <symbol>gdb_version</symbol>.</para>
-
- <para><command>runtest</command> itself calls only two of these
- procedures, <symbol>${tool}_exit</symbol> and
- <symbol>${tool}_version</symbol>; these procedures use no
- arguments.</para>
-
- <para>The other two procedures, <symbol>${tool}_start</symbol>
- and <symbol>${tool}_load</symbol>, are only called by the test
- suites themselves (or by testsuite-specific initialization
- code); they may take arguments or not, depending on the
- conventions used within each testsuite.</para>
-
- <para>The usual convention for return codes from any of these
- procedures (although it is not required by
- <command>runtest</command>) is to return <emphasis>0</emphasis>
- if the procedure succeeded, <emphasis>1</emphasis> if it failed,
- and <emphasis>-1</emphasis> if there was a communication error.</para>
-
- <sect4 id="toolstart" xreflabel="${tool}_start procedure">
- <title>${tool}_start Procedure</title>
-
- <para>Starts a particular tool. For an interactive tool,
- <function>${tool}_start</function> starts and initializes the
- tool, leaving the tool up and running for the test cases; an
- example is <function>gdb_start</function>, the start function
- for GDB. For a batch oriented tool,
- <function>${tool}_start</function> is optional; the recommended
- convention is to let <function>${tool}_start</function> run the
- tool, leaving the output in a variable called
- <function>comp_output</function>. Test scripts can then analyze
- <function>$comp_output</function> to determine the test results.
- An example of this second kind of start function is
- <function>gcc_start</function>, the start function for GCC.</para>
-
- <para>&dj; itself does not call
- <function>${tool}_start</function>. The initialization
- module <function>${tool}_init.exp</function> must call
- <function>${tool}_start</function> for interactive tools;
- for batch-oriented tools, each individual test script calls
- <function>${tool}_start</function> (or makes other
- arrangements to run the tool).</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>${tool}_start</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="toolload" xreflabel="${tool}_load procedure">
- <title>${tool}_load Procedure</title>
-
- <para>Loads something into a tool. For an interactive tool,
- this conditions the tool for a particular test case; for
- example, <function>gdb_load</function> loads a new
- executable file into the debugger. For batch oriented tools,
- <function>${tool}_load</function> may do nothing---though,
- for example, the GCC support uses
- <function>gcc_load</function> to load and run a binary on
- the target environment. Conventionally,
- <function>${tool}_load</function> leaves the output of any
- program it runs in a variable called
- <symbol>$exec_output</symbol>. Writing
- <function>${tool}_load</function> can be the most complex
- part of extending &dj; to a new tool or a new target, if
- it requires much communication coding or file
- downloading. Test scripts call
- <function>${tool}_load</function>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>${tool}_load</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="toolexit" xreflabel="${tool}_exit procedure">
- <title>${tool}_exit Procedure</title>
-
- <para>Cleans up (if necessary) before &dj; exits. For
- interactive tools, this usually ends the interactive
- session. You can also use <function>${tool}_exit</function>
- to remove any temporary files left over from the
- tests. <command>runtest</command> calls
- <function>${tool}_exit</function>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>${tool}_exit</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="toolversion" xreflabel="${tool}_version procedure">
- <title>${tool}_version Procedure</title>
-
- <para>Prints the version label and number for
- <symbol>${tool}</symbol>. This is called by the &dj;
- procedure that prints the final summary report. The output
- should consist of the full path name used for the tested
- tool, and its version number.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>${tool}_version</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- </sect3>
-
- <sect3 id="utilprocs">
- <title>Utility Procedures</title>
-
- <sect4 id="getdirs" xreflabel="getdirs procedure">
- <title>Getdirs Procedure</title>
-
- <para>Returns a list of all the directories in the single
- directory a single directory that match an optional
- pattern. </para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>getdirs</function></funcdef>
- <paramdef><parameter>rootdir</parameter>
- <parameter>pattern</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>pattern</parameter></term>
- <listitem><para>If you do not specify
- <parameter>pattern</parameter>,
- <function>Getdirs</function> assumes a default pattern of
- <emphasis>*</emphasis>. You may use the common shell
- wildcard characters in the pattern. If no directories
- match the pattern, then a NULL string is
- returned.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="find" xreflabel="find procedure">
- <title>Find Procedure</title>
-
- <para>Search for files whose names match <emphasis>pattern</emphasis>
- (using shell wildcard characters for filename expansion). Search
- subdirectories recursively, starting at
- <emphasis>rootdir</emphasis>. The result is the list of files whose
- names match; if no files match, the result is empty. Filenames in the
- result include all intervening subdirectory names. If no files match
- the pattern, then a NULL string is returned.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>find</function></funcdef>
- <paramdef><parameter>rootdir</parameter>
- <parameter>pattern</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>rootdir</parameter></term>
- <listitem><para>The top level directory to search the search
- from.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>pattern</parameter></term>
- <listitem><para>A csh "glob" style regular expression representing
- the files to find.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="which" xreflabel="which procedure">
- <title>Which Procedure</title>
-
- <para>Searches the execution path for an executable file
- <emphasis>binary</emphasis>, like the BSD <command>which</command>
- utility. This procedure uses the shell environment variable
- <emphasis>PATH</emphasis>. It returns <emphasis>0</emphasis> if the
- binary is not in the path, or if there is no <emphasis>PATH</emphasis>
- environment variable. If <command>binary</command> is in the path, it
- returns the full path to <command>binary</command>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>which</function></funcdef>
- <paramdef><parameter>file</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>binary</parameter></term>
- <listitem><para>The executable program or shell script to look
- for.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="grep" xreflabel="grep procedure">
- <title>Grep Procedure</title>
-
- <para>Search the file called <filename>filename</filename> (a fully
- specified path) for lines that contain a match for regular expression
- <emphasis>regexp</emphasis>. The result is a list of all the lines that
- match. If no lines match, the result is an empty string. Specify
- <emphasis>regexp</emphasis> using the standard regular expression style
- used by the Unix utility program grep.</para>
-
- <para>Use the optional third argument <emphasis>line</emphasis> to
- start lines in the result with the line number in
- <filename>filename</filename>. (This argument is simply an option
- flag; type it just as shown <option>--line</option>.)</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>grep</function></funcdef>
- <paramdef><parameter>filename</parameter>
- <parameter>regexp</parameter>
- <parameter>--line</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>filename</parameter></term>
- <listitem><para>The file to search.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>regexp</parameter></term>
- <listitem><para>The Unix style regular expression (as used by the
- <command>grep</command> Unix utility) to search
- for.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>--line</parameter></term>
- <listitem><para>Prefix the line number to each line where the
- regexp matches.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="prune" xreflabel="prune procedure">
- <title>Prune Procedure</title>
- <para>This procedure is deprecated and will be removed in
- the next release of &dj;. If a testsuite uses this
- procedure, a copy of the procedure should be made and placed
- in the lib directory of the testsuite.</para>
- </sect4>
-
- <sect4 id="runtestfilep" xreflabel="runtest_file_p procedure">
- <title>Runtest_file_p Procedure</title>
-
- <para>Search <emphasis>runtest</emphasis>s for
- <emphasis>testcase</emphasis> and return <emphasis>1</emphasis> if
- found, <emphasis>0</emphasis> if not. <emphasis>runtests</emphasis>
- is a list of two elements. The first is a copy of what was on
- the right side of the <emphasis>=</emphasis> if</para>
- <programlisting>foo.exp="..."</programlisting>
- <para>was specified, or
- an empty string if no such argument is present. The second is the
- pathname of the current testcase under consideration. This is used
- by tools like compilers where each testcase is a file.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>runtest_file_p</function></funcdef>
- <paramdef><parameter>runtests</parameter>
- <parameter>testcase</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>runtests</parameter></term>
- <listitem><para>The list of patterns to compare against.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>testcase</parameter></term>
- <listitem><para>The test case filename.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="diff" xreflabel="diff procedure">
- <title>Diff Procedure</title>
-
- <para>Compares the two files and returns a <emphasis>1</emphasis> if
- they match, or a <emphasis>0</emphasis> if they don't. If
- <symbol>verbose</symbol> is set, then it'll print the differences to
- the screen.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>diff</function></funcdef>
- <paramdef><parameter>file_1</parameter>
- <parameter>file_2</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>file_1</parameter></term>
- <listitem><para>The first file to compare.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>file_2</parameter></term>
- <listitem><para>The second file to compare.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="setenv" xreflabel="setenv procedure">
- <title>Setenv Procedure</title>
-
- <para>Sets the environment variable <emphasis>var</emphasis> to the
- value <emphasis>val</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>setenv</function></funcdef>
- <paramdef><parameter>var</parameter>
- <parameter>val</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>var</parameter></term>
- <listitem><para>The environment variable to set.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>val</parameter></term>
- <listitem><para>The value to set the variable to.</para></listitem>
- </varlistentry>
- </variablelist>
-
- </sect4>
- <sect4 id="unsetenv" xreflabel="unsetenv procedure">
- <title>unsetenv Procedure</title>
-
- <para>Unsets the environment variable
- <emphasis>var</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>unsetenv</function></funcdef>
- <paramdef><parameter>var</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>var</parameter></term>
- <listitem><para>The environment variable to
- unset.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="getenv" xreflabel="getenv procedure">
- <title>Getenv Procedure</title>
-
- <para>Returns the value of <emphasis>var</emphasis> in the
- environment if it exists, otherwise it returns NULL.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>getenv</function></funcdef>
- <paramdef><parameter>var</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>var</parameter></term>
- <listitem><para>The environment variable to get the value
- of.</para></listitem>
- </varlistentry>
- </variablelist>
-
- </sect4>
- <sect4 id="prunesystemcrud" xreflabel="prune_system_crud procedure">
- <title>Prune_system_crud Procedure</title>
-
- <para>For system <emphasis>system</emphasis>, delete text the host or
- target operating system might issue that will interfere with pattern
- matching of program output in <emphasis>text</emphasis>. An example
- is the message that is printed if a shared library is out of
- date.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>prune_system_crud</function></funcdef>
- <paramdef><parameter>system</parameter>
- <parameter>test</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>system</parameter></term>
- <listitem><para>The system error messages to look for to screen out
- .</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>text</parameter></term>
- <listitem><para>The Tcl variable containing the
- text.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- </sect3>
-
- <sect3 id="libgloss" xreflabel="Libgloss">
- <title>Libgloss, A Free BSP</title>
-
- <para>Libgloss is a free <firstterm>BSP</firstterm> (Board Support
- Package) commonly used with GCC and G++ to produce a fully linked
- executable image for an embedded systems.</para>
-
- <sect4 id="libglosslinkflags" xreflabel="libgloss_link_flags procedure">
- <title>Libgloss_link_flags Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>libgloss_link_flags</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="libglossincludeflags" xreflabel="libgloss_include_flags
- procedure">
- <title>Libgloss_include_flags Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>libgloss_include_flags</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="newliblinkflags" xreflabel="newlib_link_flags procedure">
- <title>Newlib_link_flags Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>newlib_link_flags</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="newlibincludeflags" xreflabel="newlib_include_flags
- procedure">
- <title>Newlib_include_flags Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>newlib_include_flags</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="libioincludeflags" xreflabel="libio_include_flags
- procedure">
- <title>Libio_include_flags Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>libio_include_flags</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="libiolinkflags" xreflabel="libio_link_flags procedure">
- <title>Libio_link_flags Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>libio_link_flags</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="gxxincludeflags" xreflabel="g++_include_flags procedure">
- <title>G++_include_flags Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>g++_include_flags</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="gxxlinkflags" xreflabel="g++_link_flags procedure">
- <title>G++_link_flags Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>g++_link_flags</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="libstdcxxincludeflags" xreflabel="libstdc++_include_flags
- procedure">
- <title>Libstdc++_include_flags Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>libstdc++_include_flags</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="libstdcxxlinkflags" xreflabel="libstdc++_link_flags
- procedure">
- <title>Libstdc++_link_flags Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>libstdc++_link_flags</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="getmultilibs" xreflabel="get_multilibs procedure">
- <title>Get_multilibs Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>get_multilibs</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="findbinutilsprog" xreflabel="find_binutils_prog procedure">
- <title>Find_binutils_prog Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>find_binutils_prog</function></funcdef>
- <paramdef><parameter>name</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>name</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="findgcc" xreflabel="find_gcc procedure">
- <title>Find_gcc Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>find_gcc</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="findgcj" xreflabel="find_gcj procedure">
- <title>Find_gcj Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>find_gcj</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="findgxx" xreflabel="find_g++ procedure">
- <title>Find_g++ Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>find_g++</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="findg77" xreflabel="find_g77 procedure">
- <title>Find_g77 Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>find_g77</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="findgfortran" xreflabel="find_gfortran procedure">
- <title>Find_gfortran Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>find_gfortran</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="processmultiliboptions" xreflabel="process_multilib_options
- procedure">
- <title>Process_multilib_options Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>process_multilib_options</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="addmultiliboption" xreflabel="add_multilib_option
- procedure">
- <title>Add_multilib_option Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>add_multilib_option</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="findgas" xreflabel="find_gas procedure">
- <title>Find_gas Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>find_gas</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="findld" xreflabel="find_ld procedure">
- <title>Find_ld Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>find_ld</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect4>
-
- <sect4 id="buildwrapper" xreflabel="build_wrapper procedure">
- <title>Build_wrapper Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>build_wrapper</function></funcdef>
- <paramdef><parameter>gluefile</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>gluefile</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="winsupincludeflags" xreflabel="winsup_include_flags
- procedure">
- <title>Winsup_include_flags Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>winsup_include_flags</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="winsuplinkflags" xreflabel="winsup_link_flags procedure">
- <title>Winsup_link_flags Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>winsup_link_flags</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
- </sect3>
-
- <sect3 id="debugprocs" xreflabel="Debugging Procedures">
- <title>Procedures for debugging your Tcl code.</title>
-
- <para><filename>lib/debugger.exp</filename>defines these utility
- procedures:</para>
-
- <sect4 id="dumpvars" xreflabel="dumpvars procedure">
- <title>Dumpvars Procedure</title>
-
- <para>This takes a csh style regular expression (glob rules) and prints
- the values of the global variable names that match. It is abbreviated
- as <emphasis>dv</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>dumpvars</function></funcdef>
- <paramdef><parameter>vars</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>vars</parameter></term>
- <listitem><para>The variables to dump.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="dumplocals" xreflabel="dumplocals procedure">
- <title>Dumplocals Procedure</title>
-
- <para>This takes a csh style regular expression (glob rules) and
- prints the values of the local variable names that match. It is
- abbreviated as <emphasis>dl</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>dumplocals</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="dumprocs" xreflabel="dumprocs procedure">
- <title>Dumprocs Procedure</title>
-
- <para>This takes a csh style regular expression (glob rules) and
- prints the body of all procs that match. It is abbreviated as
- <emphasis>dp</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>dumprocs</function></funcdef>
- <paramdef><parameter>pattern</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>pattern</parameter></term>
- <listitem><para>The csh "glob" style pattern to look
- for.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="dumpwatch" xreflabel="dumpwatch procedure">
- <title>Dumpwatch Procedure</title>
-
- <para>This takes a csh style regular expression (glob rules) and
- prints all the watchpoints. It is abbreviated as
- <emphasis>dw</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>dumpwatch</function></funcdef>
- <paramdef><parameter>pattern</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>pattern</parameter></term>
- <listitem><para>The csh "glob" style pattern to look
- for.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="watcharray" xreflabel="watcharray procedure">
- <title>Watcharray Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>watcharray</function></funcdef>
- <paramdef><parameter>element</parameter>
- <parameter>type</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>type</parameter></term>
- <listitem><para>The csh "glob" style pattern to look
- for.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="watchvar" xreflabel="watchvar procedure">
- <title>Watchvar Procedure</title>
-
- <para></para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>watchvar</function></funcdef>
- <paramdef><parameter>var</parameter>
- <parameter>type</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter></parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="watchunset" xreflabel="watchunset procedure">
- <title>Watchunset Procedure</title>
-
- <para>This breaks program execution when the variable
- <symbol>var</symbol> is unset. It is abbreviated as
- <emphasis>wu</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>watchunset</function></funcdef>
- <paramdef><parameter>arg</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="watchwrite" xreflabel="watchwrite procedure">
- <title>Watchwrite Procedure</title>
-
- <para>This breaks program execution when the variable
- <symbol>var</symbol> is written. It is abbreviated as
- <emphasis>ww</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>watchwrite</function></funcdef>
- <paramdef><parameter>var</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>var</parameter></term>
- <listitem><para>The variable to watch.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="watchread" xreflabel="watchread procedure">
- <title>Watchread Procedure</title>
-
- <para>This breaks program execution when the variable
- <symbol>var</symbol> is read. It is abbreviated as
- <emphasis>wr</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>watchread</function></funcdef>
- <paramdef><parameter>var</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>var</parameter></term>
- <listitem><para>The variable to watch.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="watchdel" xreflabel="watchdel procedure">
- <title>Watchdel Procedure</title>
-
- <para>This deletes a watchpoint from the watch list. It is
- abbreviated as <emphasis>wd</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>watchdel</function></funcdef>
- <paramdef><parameter>args</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="print" xreflabel="print procedure">
- <title>Print Procedure</title>
-
- <para>This prints the value of the variable
- <parameter>var</parameter>. It is abbreviated as
- <emphasis>p</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>print</function></funcdef>
- <paramdef><parameter>var</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter>var</parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
-
- <sect4 id="quit" xreflabel="quit procedure">
- <title>Quit Procedure</title>
-
- <para>This makes runtest exit. It is abbreviated as
- <emphasis>q</emphasis>.</para>
-
- <funcsynopsis role="tcl">
- <funcprototype>
- <funcdef><function>quit</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <variablelist>
- <varlistentry>
- <term><parameter></parameter></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </sect4>
- </sect3>
- </sect2>
-</sect1>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-namecase-general:t
-sgml-general-insert-case:lower
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:nil
-sgml-parent-document:nil
-sgml-exposed-tags:nil
-sgml-local-catalogs:nil
-sgml-local-ecat-files:nil
-End:
--->
-
-<!-- LocalWords: spawnid
- -->
+++ /dev/null
-
- <sect1 id="runningtests">
- <title>Running Tests</title>
-
- <para>There are two ways to execute a testsuite. The most
- common way is when there is existing support in the
- <filename>Makefile</filename> of the tool being tested. This
- usually consists of a
- <emphasis>check</emphasis> target. The other way is to execute the
- <command>runtest</command> program directly. To run
- <command>runtest</command> directly from the command line requires
- either all of the correct command line options, or a
- <xref linkend="local"/> must be set up correctly.</para>
-
- <sect2 id="makecheck" xreflabel="Make Check">
- <title>Running 'make check'</title>
-
- <para>To run tests from an existing collection, first use
- <command>configure</command> as usual to set up the build
- directory. Then type:</para>
-
- <screen>
- make check
- </screen>
-
- <para>If the <emphasis>check</emphasis> target exists, it
- usually saves you some trouble. For instance, it can set up any
- auxiliary programs or other files needed by the tests. The most
- common file the <emphasis>check</emphasis> target depends on is
- the
- <filename>site.exp</filename> file. The site.exp file contains
- various variables that &dj; used to determine the configuration
- of the program being tested. This is mostly for supporting
- remote testing.</para>
-
- <para>The <emphasis>check</emphasis> target is supported by GNU
- <productname>Automake</productname>. To have &dj; support added to your
- generated <filename>Makefile.in</filename>, just add the keyword
- <command>dejagnu</command> to the AUTOMAKE_OPTIONS variable in
- your <filename>Makefile.am</filename> file.</para>
-
- <para>Once you have run <emphasis>make check</emphasis> to build
- any auxiliary files, you can invoke the test driver
- <command>runtest</command> directly to repeat the tests.
- You will also have to execute <command>runtest</command>
- directly for test collections with no
- <emphasis>check</emphasis> target in the
- <filename>Makefile</filename>.</para>
-
- </sect2>
-
- <sect2 id="runtest" xreflabel="Runtest">
- <title>Running runtest</title>
-
- <para><command>runtest</command> is the test driver for
- &dj;. You can specify two kinds of things on the
- <command>runtest</command> command line: command line options,
- and Tcl variables that are passed to the test scripts. The
- options are listed alphabetically below.</para>
-
- <para><command>runtest</command> returns an exit code of
- <emphasis>1</emphasis> if any test has an unexpected result. If
- all tests pass or fail as expected, <command>runtest</command>
- returns <emphasis>0</emphasis> as the exit code.</para>
-
- <sect3 id="outputs" xreflabel="Output States">
- <title>Output States</title>
-
- <para><filename>runtest</filename> flags the outcome of each
- test as one of these cases. See <xref linkend="posix"/> for a
- discussion of how POSIX specifies the meanings of these
- cases.</para>
-
- <variablelist>
- <varlistentry>
- <term>PASS</term>
- <listitem><para>The most desirable outcome: the test was
- expected to succeed and did succeed.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>XPASS</term>
- <listitem><para>A pleasant kind of failure: a test was expected to
- fail, but succeeded. This may indicate progress; inspect the test
- case to determine whether you should amend it to stop expecting
- failure.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>FAIL</term>
- <listitem><para>A test failed, although it was expected to succeed.
- This may indicate regress; inspect the test case and the failing
- software to locate the bug.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>XFAIL</term>
- <listitem><para>A test failed, but it was expected to fail. This
- result indicates no change in a known bug. If a test fails because
- the operating system where the test runs lacks some facility required
- by the test, the outcome is <emphasis>UNSUPPORTED</emphasis>
- instead.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>UNRESOLVED</term>
- <listitem><para>Output from a test requires manual inspection; the
- testsuite could not automatically determine the outcome. For
- example, your tests can report this outcome is when a test does not
- complete as expected.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>UNTESTED</term>
- <listitem><para>A test case is not yet complete, and in particular
- cannot yet produce a <emphasis>PASS</emphasis> or
- <emphasis>FAIL</emphasis>. You can also use this outcome in dummy
- ``tests'' that note explicitly the absence of a real test case for a
- particular property.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>UNSUPPORTED</term>
- <listitem><para>A test depends on a conditionally available feature
- that does not exist (in the configured testing environment). For
- example, you can use this outcome to report on a test case that does
- not work on a particular target because its operating system support
- does not include a required subroutine.</para></listitem>
- </varlistentry>
- </variablelist>
-
- <para><command>runtest</command> may also display the following
- messages:</para>
-
- <variablelist>
- <varlistentry>
- <term>ERROR</term>
- <listitem><para>Indicates a major problem (detected by the test case
- itself) in running the test. This is usually an unrecoverable error,
- such as a missing file or loss of communication to the target. (POSIX
- testsuites should not emit this message; use
- <emphasis>UNSUPPORTED</emphasis>, <emphasis>UNTESTED</emphasis>, or
- <emphasis>UNRESOLVED</emphasis> instead, as
- appropriate.)</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>WARNING</term>
- <listitem><para>Indicates a possible problem in running the
- test. Usually warnings correspond to recoverable errors, or display
- an important message about the following tests.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>NOTE</term>
- <listitem><para>An informational message about the test
- case.</para></listitem>
- </varlistentry>
- </variablelist>
-
- </sect3>
-
- <sect3 id="invoking" xreflabel="Invoking runtest">
- <title>Invoking runtest</title>
-
- <para>This is the full set of command line options that
- <command>runtest</command> recognizes. Option names may be
- abbreviated to the shortest unique string.</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-a</option>, <option>--all</option></term>
- <listitem><para>Display all test output. By default,
- <emphasis>runtest</emphasis> shows only the output of tests that
- produce unexpected results; that is, tests with status
- <emphasis>FAIL</emphasis> (unexpected failure),
- <emphasis>XPASS</emphasis> (unexpected success), or
- <emphasis>ERROR</emphasis> (a severe error in the test case
- itself). Specify <option>--all</option> to see output for tests
- with status <emphasis>PASS</emphasis> (success, as expected)
- <emphasis>XFAIL</emphasis> (failure, as expected), or
- <emphasis>WARNING</emphasis> (minor error in the test case
- itself).</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--build [triplet]</option></term>
- <listitem><para><emphasis>string</emphasis> is a
- configuration triplet as used
- by <command>configure</command>. This is the type of machine
- &dj; 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 separate.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--host [triplet]</option></term>
- <listitem><para><symbol>string</symbol> is a configuration
- triplet as used by <emphasis>configure</emphasis>. Use this
- option to override the default string recorded by your
- configuration's choice of host. This choice does not change
- how anything is actually configured unless --build is also
- specified; it affects <emphasis>only</emphasis> &dj;
- procedures that compare the host string with particular
- values. The procedures
- <emphasis>ishost</emphasis>, <emphasis>istarget</emphasis>,
- <emphasis>isnative</emphasis>, and <emphasis>setup_xfail</emphasis>
- are affected by <option>--host</option>. In this usage,
- <emphasis>host</emphasis> refers to the machine that the tests are to
- be run on, which may not be the same as the
- <emphasis>build</emphasis> machine. If <option>--build</option>
- is also specified, then <option>--host</option> refers to the
- machine that the tests will be run on, not the machine &dj; is run
- on.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--host_board [name]</option></term>
- <listitem><para>The host board to use.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--target [triplet]</option></term>
- <listitem><para>Use this option to override the default
- setting (running native tests). <emphasis>triplet</emphasis>
- is a configuration triplet of the form
- <emphasis>cpu-vendor-os</emphasis> as used by
- <command>configure</command>. This option changes the
- configuration <command>runtest</command> uses for the
- default tool names, and other setup
- information.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--debug</option></term>
- <listitem><para>Turns on
- the <productname>Expect</productname> internal debugging
- output. Debugging output is displayed as part of the
- <emphasis>runtest</emphasis> output, and logged to a file called
- <filename>dbg.log</filename>. The extra debugging output does
- <emphasis>not</emphasis> appear on standard output, unless the
- verbose level is greater than 2 (for instance, to see debug output
- immediately, specify <option>--debug -v -v</option>). 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 <option>--strace</option> also goes into
- <filename>dbg.log</filename>.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--help</option></term>
- <listitem><para>Prints out a short summary of the
- <emphasis>runtest</emphasis> options, then exits (even if you also
- specify other options).</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--ignore [name(s)] </option></term>
- <listitem><para>The name(s) of specific tests to
- ignore.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--objdir [path]</option></term>
- <listitem><para>Use <emphasis>path</emphasis> as the top
- directory containing any auxiliary compiled test code. The
- default is '.'. Use this option to locate pre-compiled
- test code. You can normally prepare any auxiliary files
- needed with
- <emphasis>make</emphasis>.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--outdir [path]</option></term>
- <listitem><para>Write log files in directory
- <filename>path</filename>. The default is '.', the
- directory where you start <emphasis>runtest</emphasis>. This
- option affects only the summary (<filename>.sum</filename>)
- and the detailed log files (<filename>.log</filename>). The
- &dj; debug log <filename>dbg.log</filename> always appears
- (when requested) in the local directory.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--log_dialog</option></term>
- <listitem><para>Emit Expect output to stdout.
- The <productname>expect</productname> output is usually only
- written to
- <filename>tool.log</filename>. By enabling this option, they are also
- be printed to the stdout of the <emphasis>runtest</emphasis>
- invocation.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--reboot [name]</option></term>
- <listitem><para>Reboot the target board when
- <command>runtest</command> starts. 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 can take a lot of time.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--srcdir [path]</option></term>
- <listitem><para>Use <filename>path</filename> as the top directory
- for test scripts to run. <emphasis>runtest</emphasis> looks in this
- directory for any subdirectory whose name begins with the toolname
- (specified with <option>--tool</option>). For instance, with
- <option>--tool gdb</option>, <emphasis>runtest</emphasis> uses
- tests in subdirectories <filename>gdb.*</filename> (with the usual
- shell-like filename expansion). If you do not use
- <option>--srcdir</option>, <emphasis>runtest</emphasis> looks for
- test directories under the current working
- directory.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--strace [number]</option></term>
- <listitem><para>Turn on internal tracing for
- <emphasis>expect</emphasis>, to n levels deep. By adjusting the
- level, you can control the extent to which your output expands
- multi-level Tcl statements. This allows you to ignore some levels of
- <emphasis>case</emphasis> or <emphasis>if</emphasis> statements.
- Each procedure call or control structure counts as one ``level''. The
- output is recorded in the same file, <filename>dbg.log</filename>,
- used for output from <option>--debug</option>.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--target_board [name(s)]</option></term>
- <listitem><para>The list of target boards to run tests
- on.</para></listitem>
- </varlistentry>
-
- <varlistentry id="tool-opt">
- <term><option>--tool [name(s)]</option></term>
- <listitem><para>Specifies which testsuite to run, and what
- initialization module to use. <option>--tool</option> is used
- <emphasis>only</emphasis> for these two purposes. It is
- <emphasis>not</emphasis> used to name the executable program to
- test. Executable tool names (and paths) are recorded in
- <filename>site.exp</filename> and you can override them by specifying
- Tcl variables on the command line.</para>
-
- <para>For example, including "<option>--tool</option> gcc" on the
- <emphasis>runtest</emphasis> command line runs tests from all test
- subdirectories whose names match <filename>gcc.*</filename>, and uses
- one of the initialization modules named
- <filename>config/*-gcc.exp</filename>. To specify the name of the
- compiler (perhaps as an alternative path to what
- <emphasis>runtest</emphasis> would use by default), use
- <emphasis>GCC=binname</emphasis> on the <emphasis>runtest</emphasis>
- command line.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--tool_exec [name]</option></term>
- <listitem><para>The path to the tool executable to
- test.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--tool_opts [options]</option></term>
- <listitem><para>A list of additional options to pass to the
- tool.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-v</option>, <option>--verbose</option></term>
- <listitem><para>Turns on more output. Repeating this option increases
- the amount of output displayed. Level one (<emphasis>-v</emphasis>)
- is simply test output. Level two (<emphasis>-v -v</emphasis>) shows
- messages on options, configuration, and process control. Verbose
- messages appear in the detailed (<filename>*.log</filename>) log
- file, but not in the summary (<filename>*.sum</filename>) log
- file.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-V</option>, <option>--version</option></term>
- <listitem><para>Prints out the version numbers of &dj;,
- Expect, and Tcl.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--D0</option>, <option>--D1</option></term>
- <listitem><para>Start the internal Tcl debugger. The Tcl debugger
- supports breakpoints, single stepping, and other common debugging
- activities. See the document "Debugger for Tcl Applications" by Don
- Libes. (Distributed in PostScript form with
- <emphasis>expect</emphasis> as the file
- <filename>expect/tcl-debug.ps.</filename>. If you specify
- <emphasis>-D1</emphasis>, the <emphasis>expect</emphasis> shell stops
- at a breakpoint as soon as &dj; invokes it. If you specify
- <emphasis>-D0</emphasis>, &dj; starts as usual, but you can enter
- the debugger by sending an interrupt (e.g. by typing
- <keycombo><keycap>Control</keycap><keycap>c</keycap></keycombo>).
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><filename>testfile</filename>.exp[=arg(s)]</term>
- <listitem><para>Specify the names of testsuites to run. By default,
- <emphasis>runtest</emphasis> runs all tests for the tool, but you can
- restrict it to particular testsuites by giving the names of the
- <emphasis>.exp expect</emphasis> scripts that control
- them. <emphasis>testsuite</emphasis>.exp may not include path
- information; use plain filenames.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><filename>testfile</filename>.exp="testfile1 ..."</term>
- <listitem><para>Specify a subset of tests in a suite to run. For
- compiler or assembler tests, which often use a single
- <emphasis>.exp</emphasis> script covering many different source
- files, this option allows you to further restrict the tests by
- listing particular source files to compile. Some tools even support
- wildcards here. The wildcards supported depend upon the tool, but
- typically they are <emphasis>?</emphasis>, <emphasis>*</emphasis>,
- and <emphasis>[chars]</emphasis>.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><symbol>tclvar</symbol>=value</term>
- <listitem><para>You can define Tcl variables for use by your test
- scripts in the same style used with <emphasis>make</emphasis> for
- environment variables. For example, <emphasis>runtest
- GDB=gdb.old</emphasis> defines a variable called
- <command>GDB</command>; when your scripts refer to
- <symbol>$GDB</symbol> in this run, they use the value
- <emphasis>gdb.old</emphasis>.</para>
-
- <para>The default Tcl variables used for most tools are defined in
- the main &dj; <emphasis>Makefile</emphasis>; their values are
- captured in the <filename>site.exp</filename> file.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect3>
-
- <sect3 id="common" xreflabel="Common Operations">
- <title>Common Options</title>
-
- <para>Typically, you don't need to use any command line
- options. The <option>--tool</option> option is only required
- when there is more than one testsuite in the same
- directory. The default options are in the
- local <filename>site.exp</filename> file, created
- by <command>make site.exp</command>.</para>
-
- <para>For example, if the directory <filename>gdb/testsuite</filename>
- contains a collection of &dj; tests for GDB, you can run them like
- this:</para>
-
- <screen>
- $ cd gdb/testsuite
- $ runtest --tool gdb
- </screen>
-
- <para>The test output follows, then ends with:</para>
-
- <screen>
- === gdb Summary ===
-
- # of expected passes 508
- # of expected failures 103
- /usr/latest/bin/gdb version 4.14.4 -nx
- </screen>
-
- <para>You can use the option <option>--srcdir</option> to point to
- some other directory containing a collection of tests:</para>
-
- <screen>
- $ runtest --srcdir /devo/gdb/testsuite
- </screen>
-
- <para>By default, <command>runtest</command> prints only the
- names of the tests it runs, output from any tests that have unexpected
- results, and a summary showing how many tests passed and how many
- failed. To display output from all tests (whether or not they behave
- as expected), use the <option>--all</option> option. For more
- verbose output about processes being run, communication, and so on, use
- <option>--verbose</option>. To see even more output, use multiple
- <option>--verbose</option> options.
- The <option>--help</option> for a more detailed explanation of
- each <command>runtest</command> option.</para>
-
- </sect3>
- </sect2>
-
- <sect2 id="outputfiles" xreflabel="Output Files">
- <title>Output files</title>
-
- <para>&dj; always writes two kinds of output files. Summary
- output is written to the <filename>.sum</filename> file, and
- detailed output is written to the <filename>.log</filename> file.
- The tool name determines the prefix for these files. For example,
- after running with
- <option>--tool gdb</option>, the output files will be called
- <filename>gdb.sum</filename> and
- <filename>gdb.log</filename>. For troubleshooting, a debug log
- file that logs the operation
- of <productname>Expect</productname> is available. Each of
- these will be described in turn.</para>
-
- <sect3 id="sum" xreflabel="Summary log file">
- <title>Summary log file</title>
-
- <para>&dj; always produces a summary (<filename>.sum</filename>)
- output file. This summary lists the names of all test files run.
- For each test file, one line of output from
- each <command>pass</command> command (showing status
- <emphasis>PASS</emphasis> or <emphasis>XPASS</emphasis>) or
- <command>fail</command> command (status
- <emphasis>FAIL</emphasis> or <emphasis>XFAIL</emphasis>),
- trailing summary statistics that count passing and failing tests
- (expected and unexpected), the full pathname of the tool tested,
- and the version number of the tool. All possible outcomes, and
- all errors, are always reflected in the summary output file,
- regardless of whether or not you specify
- <option>--all</option>.</para>
-
- <para>If any of your tests use the procedures
- <command>unresolved</command>, <command>unsupported</command>,
- or <command>untested</command>, the summary output also
- tabulates the corresponding outcomes.</para>
-
- <para>For example, after running <command>runtest --tool
- binutils</command> a summary log file will be written to
- <filename>binutils.sum</filename>. Normally, &dj; writes this
- file in your current working directory. Use the
- <option>--outdir</option> option to select a different output
- directory.</para>
-
- <example>
- <title>Sample summary log</title>
-
- <screen>
- Test Run By bje on Sat Nov 14 21:04:30 AEDT 2015
-
- === gdb tests ===
-
- Running ./gdb.t00/echo.exp ...
- PASS: Echo test
- Running ./gdb.all/help.exp ...
- PASS: help add-symbol-file
- PASS: help aliases
- PASS: help breakpoint "bre" abbreviation
- FAIL: help run "r" abbreviation
- Running ./gdb.t10/crossload.exp ...
- PASS: m68k-elf (elf-big) explicit format; loaded
- XFAIL: mips-ecoff (ecoff-bigmips) "ptype v_signed_char" signed C types
-
- === gdb Summary ===
-
- # of expected passes 5
- # of expected failures 1
- # of unexpected failures 1
- /usr/latest/bin/gdb version 4.6.5 -q
- </screen>
- </example>
-
- </sect3>
-
- <sect3 id="log" xreflabel="Detailed log file">
- <title>Detailed log file</title>
-
- <para>&dj; also saves a detailed log file
- (<filename>.log</filename>), showing any output generated by
- test cases as well as the summary output. For example, after
- running
- <command>runtest --tool binutils</command>, a detailed log file
- will be written to <filename>binutils.log</filename>. Normally,
- &dj; writes this file in your current working directory. Use the
- <option>--outdir</option> option to select a different output
- directory.</para>
-
- <example>
- <title>Sample detailed log for <productname>g++</productname> tests</title>
-
- <screen>
- Test Run By bje on Sat Nov 14 21:07:23 AEDT 2015
-
- === g++ tests ===
-
- Running ./g++.other/t01-1.exp ...
- PASS: operate delete
-
- Running ./g++.other/t01-2.exp ...
- FAIL: i960 bug EOF
- p0000646.C: In function `int warn_return_1 ()':
- p0000646.C:109: warning: control reaches end of non-void function
- p0000646.C: In function `int warn_return_arg (int)':
- p0000646.C:117: warning: control reaches end of non-void function
- p0000646.C: In function `int warn_return_sum (int, int)':
- p0000646.C:125: warning: control reaches end of non-void function
- p0000646.C: In function `struct foo warn_return_foo ()':
- p0000646.C:132: warning: control reaches end of non-void function
- Running ./g++.other/t01-4.exp ...
- FAIL: abort
- 900403_04.C:8: zero width for bit-field `foo'
- Running ./g++.other/t01-3.exp ...
- FAIL: segment violation
- 900519_12.C:9: parse error before `;'
- 900519_12.C:12: Segmentation violation
- /usr/latest/bin/gcc: Internal compiler error: program cc1plus got fatal signal
-
- === g++ Summary ===
-
- # of expected passes 1
- # of expected failures 3
- /usr/latest/bin/g++ version cygnus-2.0.1
- </screen>
- </example>
-
- </sect3>
-
- <sect3 id="debugfile" xreflabel="Debug log file">
- <title>Debug log file</title>
-
- <para>The <command>runtest</command>
- option <option>--debug</option> creates a file showing the
- output from
- <productname>Expect</productname> in debugging mode. The
- <filename>dbg.log</filename> file is created in the directory
- where you start <command>runtest</command>. The log file shows
- the string sent to the tool under test by
- each <command>send</command> command and the pattern it compares
- with the tool output by each <command>expect</command>
- command.</para>
-
- <para>The log messages begin with a message of the form:
-
- <screen>
- expect: does {<symbol>tool output</symbol>} (spawn_id <symbol>n</symbol>)
- match pattern {<emphasis>expected pattern</emphasis>}?
- </screen>
- </para>
-
- <para>For every unsuccessful match,
- <productname>Expect</productname> issues a
- <emphasis>no</emphasis> after this message. If other patterns
- are specified for the same <productname>Expect</productname>
- command, they are reflected also, but without the first part of
- the message (<emphasis>expect... match
- pattern</emphasis>).</para>
-
- <para>When <productname>Expect</productname> finds a match, the
- log for the successful match ends with <emphasis>yes</emphasis>,
- followed by a record of the <productname>Expect</productname>
- variables set to describe a successful match.</para>
-
- <example>
- <title>Debug log excerpt for a
- <productname>GDB</productname> test:</title>
-
- <screen>
- send: sent {break gdbme.c:34\n} to spawn id 6
- expect: does {} (spawn_id 6) match pattern {Breakpoint.*at.* file
- gdbme.c, line 34.*\(gdb\) $}? no
- {.*\(gdb\) $}? no
- expect: does {} (spawn_id 0) match pattern {return} ? no
- {\(y or n\) }? no
- {buffer_full}? no
- {virtual}? no
- {memory}? no
- {exhausted}? no
- {Undefined}? no
- {command}? no
- break gdbme.c:34
- Breakpoint 8 at 0x23d8: file gdbme.c, line 34.
- (gdb) expect: does {break gdbme.c:34\r\nBreakpoint 8 at 0x23d8:
- file gdbme.c, line 34.\r\n(gdb) } (spawn_id 6) match pattern
- {Breakpoint.*at.* file gdbme.c, line 34.*\(gdb\) $}? yes
- expect: set expect_out(0,start) {18}
- expect: set expect_out(0,end) {71}
- expect: set expect_out(0,string) {Breakpoint 8 at 0x23d8: file
- gdbme.c, line 34.\r\n(gdb) }
- epect: set expect_out(spawn_id) {6}
- expect: set expect_out(buffer) {break gdbme.c:34\r\nBreakpoint 8
- at 0x23d8: file gdbme.c, line 34.\r\n(gdb) }
- PASS: 70 0 breakpoint line number in file
- </screen>
- </example>
-
- <para>This example exhibits three properties of
- <productname>Expect</productname> and
- <productname>&dj;</productname> that might be surprising at
- first glance:</para>
-
- <itemizedlist mark="bullet">
- <listitem><para>Empty output for the first attempted match. The
- first set of attempted matches shown ran against the output
- <emphasis>{}</emphasis> --- that is, no
- output. <productname>Expect</productname> begins
- attempting to match the patterns supplied immediately; often,
- the first pass is against incomplete output (or completely
- before all output, as in this case).</para></listitem>
-
- <listitem><para>Interspersed tool output. The beginning of
- the log entry for the second attempted match may be hard to
- spot: this is because the prompt <emphasis>{(gdb) }</emphasis>
- appears on the same line, just before the
- <emphasis>expect:</emphasis> that marks the beginning of the
- log entry.</para></listitem>
-
- <listitem><para>Fail-safe patterns. Many of the patterns
- tested are fail-safe patterns provided by
- <productname>GDB</productname> testing utilities, to reduce
- possible indeterminacy. It is useful to anticipate potential
- variations caused by extreme system conditions
- (<productname>GDB</productname> might issue the message
- <emphasis>virtual memory exhausted</emphasis> in rare
- circumstances), or by changes in the tested program
- (<emphasis>Undefined command</emphasis> is the likeliest
- outcome if the name of a tested command changes).</para>
-
- <para>The pattern <emphasis>{return}</emphasis> is a
- particularly interesting fail-safe to notice; it checks for an
- unexpected <keycap>RET</keycap> prompt. This may happen,
- for example, if the tested tool can filter output through a
- pager.</para>
-
- <para>These fail-safe patterns (like the debugging log itself)
- are primarily useful while developing test scripts. Use the
- <command>error</command> procedure to make the actions for
- fail-safe patterns produce messages starting with
- <emphasis>ERROR</emphasis> on standard output, and in the
- detailed log file.</para></listitem>
- </itemizedlist>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="Customizing" xreflabel="Customizing DejaGnu">
- <title>Customizing &dj;</title>
-
- <para>The site configuration file, <filename>site.exp</filename>,
- captures configuration-dependent values and propagates them to the
- &dj; test environment using Tcl variables. This ties the
- &dj; test scripts into the <command>configure</command> and
- <command>make</command> programs. If this file is setup correctly,
- it is possible to execute a testsuite merely by typing
- <command>runtest</command>.</para>
-
- <para>&dj; supports two <filename>site.exp</filename>
- files. The multiple instances of <filename>site.exp</filename> are
- loaded in a fixed order. The first file loaded
- is the local file <filename>site.exp</filename>, and then the
- optional global <filename>site.exp</filename> file as
- pointed to by the <symbol>DEJAGNU</symbol> environment
- variable.</para>
-
- <para>There is an optional <emphasis>master</emphasis>
- <filename>site.exp</filename>, capturing configuration values that
- apply to &dj; across the board, in each configuration-specific
- subdirectory of the &dj; library directory.
- <command>runtest</command> loads these values first. The master
- <filename>site.exp</filename> contains the default values for all
- targets and hosts supported by &dj;. This master file is
- identified by setting the environment variable
- <symbol>DEJAGNU</symbol> to the name of the file. This is also
- referred to as the ``global'' config file.</para>
-
- <para>Any directory containing a configured testsuite also has a
- local <filename>site.exp</filename>, capturing configuration values
- specific to the tool under test. Since <command>runtest</command>
- loads these values last, the individual test configuration can
- either rely on and use, or override, any of the global values from
- the global <filename>site.exp</filename> file.</para>
-
- <para>You can usually generate or update the testsuite's local
- <filename>site.exp</filename> by typing <command>make
- site.exp</command> in the testsuite directory, after the test
- suite is configured.</para>
-
- <para>You can also have a file in your home directory called
- <filename>.dejagnurc</filename>. This gets loaded after the other
- config files. Usually this is used for personal stuff, like
- setting the <symbol>all_flag</symbol> so all the output gets
- printed, or your own verbosity levels. This file is usually
- restricted to setting command line options.</para>
-
- <para>You can further override the default values in a
- user-editable section of any <filename>site.exp</filename>, or by
- setting variables on the <command>runtest</command> command
- line.</para>
-
- <sect2 id="local" xreflabel="Local Config File">
- <title>Local Config File</title>
-
- <para>It is usually more convenient to keep these <emphasis>manual
- overrides</emphasis> in the <filename>site.exp</filename>
- local to each test directory, rather than in the global
- <filename>site.exp</filename> in the installed &dj;
- library. This file is mostly for supplying tool specific info
- that is required by the testsuite.</para>
-
- <para>All local <filename>site.exp</filename> files have
- two sections, separated by comment text. The first section is
- the part that is generated by <command>make</command>. It is
- essentially a collection of Tcl variable definitions based on
- <filename>Makefile</filename> environment variables. Since they
- are generated by <command>make</command>, they contain the
- values as specified by <command>configure</command>. (You can
- also customize these values by using the <option>--site</option>
- option to <command>configure</command>.) In particular, this
- section contains the <filename>Makefile</filename>
- variables for host and target configuration data. Do not edit
- this first section; if you do, your changes are replaced next
- time you run <command>make</command>.</para>
-
- <example>
- <title>The first section starts with</title>
-
- <programlisting>
- ## these variables are automatically generated by make ##
- # Do not edit here. If you wish to override these values
- # add them to the last section
- </programlisting>
- </example>
-
- <para>In the second section, you can override any default values
- (locally to &dj;) for all the variables. The second section
- can also contain your preferred defaults for all the command
- line options to <command>runtest</command>. This allows you to
- easily customize <command>runtest</command> for your preferences
- in each configured test-suite tree, so that you need not type
- options repeatedly on the command line. (The second section may
- also be empty, if you do not wish to override any defaults.)</para>
-
- <example>
- <title>The first section ends with this line</title>
-
- <programlisting>
- ## All variables above are generated by configure. Do Not Edit ##
- </programlisting>
- </example>
-
- <para>You can make any changes under this line. If you wish to
- redefine a variable in the top section, then just put a
- duplicate value in this second section. Usually the values
- defined in this config file are related to the configuration of
- the test run. This is the ideal place to set the variables
- <symbol>host_triplet</symbol>, <symbol>build_triplet</symbol>,
- <symbol>target_triplet</symbol>. All other variables are tool
- dependent, i.e., for testing a compiler, the value for
- <symbol>CC</symbol> might be set to a freshly built binary, as
- opposed to one in the user's path.</para>
-
- <para>Here's an example local site.exp file, as used for
- <productname>GCC/G++</productname> testing.</para>
-
- <example>
- <title>Local Config File</title>
-
- <programlisting>
- ## these variables are automatically generated by make ##
- # Do not edit here. If you wish to override these values
- # add them to the last section
- set rootme "/build/devo-builds/i586-pc-linux-gnulibc1/gcc"
- set host_triplet i586-pc-linux-gnulibc1
- set build_triplet i586-pc-linux-gnulibc1
- set target_triplet i586-pc-linux-gnulibc1
- set target_alias i586-pc-linux-gnulibc1
- set CFLAGS ""
- set CXXFLAGS "-isystem /build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libio -isystem $srcdir/../libg++/src -isystem $srcdir/../libio -isystem $srcdir/../libstdc++ -isystem $srcdir/../libstdc++/stl -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libg++ -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libstdc++"
- append LDFLAGS " -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../ld"
- set tmpdir /build/devo-builds/i586-pc-linux-gnulibc1/gcc/testsuite
- set srcdir "${srcdir}/testsuite"
- ## All variables above are generated by configure. Do Not Edit ##
-
- </programlisting>
- </example>
-
- <para>This file defines the required fields for a local config
- file, namely the three config triplets, and the srcdir. It also
- defines several other Tcl variables that are used exclusively by
- the GCC testsuite. For most test cases, the CXXFLAGS and LDFLAGS
- are supplied by &dj; itself for cross testing, but to test a
- compiler, GCC needs to manipulate these itself.</para>
-
- <para>The local <filename>site.exp</filename> may also set Tcl
- variables such as <symbol>test_timeout</symbol> which can control
- the amount of time (in seconds) to wait for a remote test to
- complete. If not specified, <symbol>test_timeout</symbol> defaults
- to 300 seconds.</para>
-
- </sect2>
- <sect2 id="global" xreflabel="Global Config File">
- <title>Global Config File</title>
-
- <para>The master config file is where all the target specific
- config variables for a whole site get set. The idea is
- that for a centralized testing lab where people have to share a
- target between multiple developers. There are settings for both
- remote targets and remote hosts. Here's an example of a Master
- Config File (also called the Global config file) for a
- <emphasis>Canadian cross</emphasis>. A Canadian cross is when
- you build and test a cross compiler on a machine other than the
- one it's to be hosted on.</para>
-
- <para>Here we have the config settings for our California
- office. Note that all config values are site dependent. Here we
- have two sets of values that we use for testing m68k-aout cross
- compilers. As both of these target boards has a different
- debugging protocol, we test on both of them in sequence.</para>
-
- <example>
- <title>Global Config file</title>
-
- <programlisting>
-
- # Make sure we look in the right place for the board description files.
- if ![info exists boards_dir] {
- set boards_dir {}
- }
- lappend boards_dir "/nfs/cygint/s1/cygnus/dejagnu/boards"
-
- verbose "Global Config File: target_triplet is $target_triplet" 2
- global target_list
-
- case "$target_triplet" in {
- { "native" } {
- set target_list "unix"
- }
- { "sparc64-*elf" } {
- set target_list "sparc64-sim"
- }
- { "mips-*elf" } {
- set target_list "mips-sim wilma barney"
- }
- { "mips-lsi-elf" } {
- set target_list "mips-lsi-sim{,soft-float,el}"
- }
- { "sh-*hms" } {
- set target_list { "sh-hms-sim" "bloozy" }
- }
- }
- </programlisting>
- </example>
-
- <para>In this case, we have support for several cross compilers,
- that all run on this host. For testing on operating systems that
- don't support Expect, &dj; 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 Telnet server.</para>
-
- <para>As you can see, all one does is set the variable
- <symbol>target_list</symbol> to the list of targets and options to
- test. The simple settings, like for
- <emphasis>sparc64-elf</emphasis> only require setting the name of
- the single board config file. The <emphasis>mips-elf</emphasis>
- target is more complicated. Here it sets the list to three target
- boards. One is the default mips target, and both
- <emphasis>wilma</emphasis> <emphasis>barney</emphasis> are
- symbolic names for other mips boards. Symbolic names are covered
- in the <xref linkend="addboard"/> chapter. The more complicated
- example is the one for <emphasis>mips-lsi-elf</emphasis>. This one
- runs the tests with multiple iterations using all possible
- combinations of the <option>--soft-float</option> and the
- <option>--el</option> (little endian) option. Needless to say,
- this last feature is mostly compiler specific.</para>
-
- </sect2>
-
- <sect2 id="boardconfig" xreflabel="Board Config File">
- <title>Board Configuration File</title>
-
- <para>The board config file is where board specific config data
- is stored. A board config file contains all the higher-level
- configuration settings. There is a rough inheritance scheme, where it is
- possible to base a new board description file on an existing one. There
- are also collections of custom procedures for common environments. For
- more information on adding a new board config file, go to the <xref
- linkend="addboard"/> chapter. </para>
-
- <para>An example board config file for a GNU simulator is as
- follows. <function>set_board_info</function> is a procedure that sets the
- field name to the specified value. The procedures in square brackets
- <emphasis>[]</emphasis> are <emphasis>helper procedures</emphasis>. These
- 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 libraries, or the tool chain itself
- is part of your build tree.</para>
-
- <example>
- <title>Board Configuration File</title>
-
- <programlisting>
- # This is a list of toolchains that are supported on this board.
- set_board_info target_install {sparc64-elf}
-
- # Load the generic configuration for this board. This will define any
- # routines needed by the tool to communicate with the board.
- load_generic_config "sim"
-
- # We need this for find_gcc and *_include_flags/*_link_flags.
- load_base_board_description "basic-sim"
-
- # Use long64 by default.
- process_multilib_options "long64"
-
- setup_sim sparc64
-
- # We only support newlib on this target. We assume that all multilib
- # options have been specified before we get here.
- set_board_info compiler "[find_gcc]"
- set_board_info cflags "[libgloss_include_flags] [newlib_include_flags]"
- set_board_info ldflags "[libgloss_link_flags] [newlib_link_flags]"
- # No linker script.
- set_board_info ldscript "";
-
- # Used by a few gcc.c-torture testcases to delimit how large the
- # stack can be.
- set_board_info gcc,stack_size 16384
- # The simulator doesn't return exit statuses and we need to indicate this
- # the standard GCC wrapper will work with this target.
- set_board_info needs_status_wrapper 1
- # We can't pass arguments to programs.
- set_board_info noargs 1
- </programlisting>
- </example>
-
- <para>There are five helper procedures used in this example. The first
- one, <function>find gcc</function> looks for a copy of the GNU compiler in
- your build tree, or it uses the one in your path. This will also return
- the proper transformed name for a cross compiler if you whole build tree
- is configured for one. The next helper procedures are
- <function>libgloss_include_flags</function> &
- <function>libgloss_link_flags</function>. These return the proper flags to
- compiler and link an executable image using <xref
- linkend="libgloss"/>, the GNU BSP (Board Support Package). The final
- procedures are <function>newlib_include_flag</function> &
- <function>newlib_include_flag</function>. These find the Newlib C
- library, which is a reentrant standard C library for embedded systems
- comprising of non GPL'd code.</para>
-
- </sect2>
-
- <sect2 id="releng" xreflabel="Remote Host Testing">
- <title>Remote Host Testing</title>
-
- <note><para>Thanks to DJ Delorie for the original paper that
- this section is based on.</para></note>
-
- <para>&dj; also supports running the tests on a remote
- host. To set this up, the remote host needs an FTP server, and a
- telnet server. Currently foreign operating systems used as
- remote hosts are VxWorks, VRTX, DOS/Windows 3.1, MacOS and Windows.</para>
-
- <para>The recommended source for a Windows-based FTP
- server is to get IIS (either IIS 1 or Personal Web Server) from
- <ulink
- url="http://www.microsoft.com">http://www.microsoft.com</ulink>.
- When you install it, make sure you install the FTP server - it's
- not selected by default. Go into the IIS manager and change the
- FTP server so that it does not allow anonymous FTP. Set the home
- directory to the root directory (i.e. c:\) of a suitable
- drive. Allow writing via FTP.</para>
-
- <para>It will create an account like IUSR_FOOBAR where foobar is
- the name of your machine. Go into the user editor and give that
- account a password that you don't mind hanging around in the
- clear (i.e. not the same as your admin or personal
- passwords). Also, add it to all the various permission groups.</para>
-
- <para>You'll also need a telnet server. For Windows, go
- to the <ulink url="http://ataman.com">Ataman</ulink> web site,
- pick up the Ataman Remote Logon Services for Windows, and
- install it. You can get started on the eval period anyway. Add
- IUSR_FOOBAR to the list of allowed users, set the HOME directory
- to be the same as the FTP default directory. Change the Mode
- prompt to simple.</para>
-
- <para>Ok, now you need to pick a directory name to do all the
- testing in. For the sake of this example, we'll call it piggy
- (i.e. c:\piggy). Create this directory.</para>
-
- <para>You'll need a unix machine. Create a directory for the
- scripts you'll need. For this example, we'll use
- /usr/local/swamp/testing. You'll need to have a source tree
- somewhere, say /usr/src/devo. Now, copy some files from
- releng's area in SV to your machine:</para>
-
- <example>
- <title>Remote host setup</title>
-
- <screen>
- cd /usr/local/swamp/testing
- mkdir boards
- scp darkstar.welcomehome.org:/dejagnu/cst/bin/MkTestDir .
- scp darkstar.welcomehome.org:/dejagnu/site.exp .
- scp darkstar.welcomehome.org:/dejagnu/boards/useless98r2.exp boards/foobar.exp
- export DEJAGNU=/usr/local/swamp/testing/site.exp
-
- </screen>
- </example>
-
- <para>You must edit the boards/foobar.exp file to reflect your
- machine; change the hostname (foobar.com), username
- (iusr_foobar), password, and ftp_directory (c:/piggy) to match
- what you selected.</para>
-
- <para>Edit the global <filename> site.exp</filename> to reflect your
- boards directory:</para>
-
- <example>
- <title>Add The Board Directory</title>
-
- <programlisting>
- lappend boards_dir "/usr/local/swamp/testing/boards"
- </programlisting>
- </example>
-
- <para>Now run MkTestDir, which is in the contrib
- directory. The first parameter is the toolchain prefix, the
- second is the location of your devo tree. If you are testing a
- cross compiler (ex: you have sh-hms-gcc.exe in your PATH on
- the PC), do something like this:</para>
-
- <example>
- <title>Setup Cross Remote Testing</title>
-
- <programlisting>
- ./MkTestDir sh-hms /usr/dejagnu/src/devo
- </programlisting>
- </example>
-
- <para>If you are testing a native PC compiler (ex: you have
- gcc.exe in your PATH on the PC), do this:</para>
-
- <example>
- <title>Setup Native Remote Testing</title>
-
- <programlisting>
- ./MkTestDir '' /usr/dejagnu/src/devo
- </programlisting>
- </example>
-
- <para>To test the setup, <command>ftp</command> to your PC
- using the username (iusr_foobar) and password you selected. CD
- to the test directory. Upload a file to the PC. Now telnet to
- your PC using the same username and password. CD to the test
- directory. Make sure the file is there. Type "set" and/or "gcc
- -v" (or sh-hms-gcc -v) and make sure the default PATH contains
- the installation you want to test.</para>
-
- <example>
- <title>Run Test Remotely</title>
-
- <programlisting>
- cd /usr/local/swamp/testing
- make -k -w check RUNTESTFLAGS="--host_board foobar --target_board foobar -v -v" > check.out 2>&1
- </programlisting>
- </example>
-
- <para>To run a specific test, use a command like this (for
- this example, you'd run this from the gcc directory that
- MkTestDir created):</para>
-
- <example>
- <title>Run a Test Remotely</title>
-
- <programlisting>
- make check RUNTESTFLAGS="--host_board sloth --target_board sloth -v compile.exp=921202-1.c"
- </programlisting>
- </example>
-
- <para>Note: if you are testing a cross-compiler, put in the
- correct target board. You'll also have to download more .exp
- files and modify them for your local configuration. The -v's
- are optional.</para>
-
- </sect2>
-
- <sect2 id="configfile" xreflabel="Config File Values">
- <title>Config File Values</title>
-
- <para>&dj; uses a named array in Tcl to hold all the info for
- each machine. In the case of a Canadian cross, this means host
- information as well as target information. The named array is
- called <symbol>target_info</symbol>, and it has two indices. The
- following fields are part of the array.</para>
-
- <sect3 id="optiondefs" xreflabel="Option Variables">
- <title>Command Line Option Variables</title>
-
- <para>In the user editable second section of the <xref
- linkend="personal"/> you can not only override the configuration
- variables captured in the first section, but also specify
- default values for all on the <command>runtest</command>
- command line options. Save for <option>--debug</option>,
- <option>--help</option>, and <option>--version</option>, each
- command line option has an associated Tcl variable. Use the
- Tcl <command>set</command> command to specify a new default
- value (as for the configuration variables). The following
- table describes the correspondence between command line
- options and variables you can set in
- <filename>site.exp</filename>. <xref linkend="invoking"/>, for
- explanations of the command-line options.</para>
-
- <table frame="all" rowsep="0" colsep="0">
- <title>Tcl Variables For Command Line Options</title>
-
- <tgroup cols="3" align="char" rowsep="1" colsep="0">
- <thead><row>
- <entry>runtest option</entry>
- <entry>Tcl variable</entry>
- <entry>description</entry>
- </row></thead>
- <tbody>
-
- <row>
- <entry>--all</entry>
- <entry>all_flag</entry>
- <entry>display all test results if set</entry>
- </row>
-
- <row>
- <entry>--baud</entry>
- <entry>baud</entry>
- <entry>set the default baud rate to something other than
- 9600.</entry>
- </row>
-
- <row>
- <entry>--connect</entry>
- <entry>connectmode</entry>
- <entry><command>rlogin</command>,
- <command>telnet</command>, <command>rsh</command>,
- <command>kermit</command>, <command>tip</command>, or
- <command>mondfe</command></entry>
- </row>
-
- <row>
- <entry>--outdir</entry>
- <entry>outdir</entry>
- <entry>directory for <filename>tool.sum</filename> and
- <filename>tool.log.</filename></entry>
- </row>
-
- <row>
- <entry>--objdir</entry>
- <entry>objdir</entry>
- <entry>directory for pre-compiled binaries</entry>
- </row>
-
- <row>
- <entry>--reboot</entry>
- <entry>reboot</entry>
- <entry>reboot the target if set to
- <emphasis>"1"</emphasis>; do not reboot if set to
- <emphasis>"0"</emphasis> (the default).</entry>
- </row>
-
- <row>
- <entry>--srcdir</entry>
- <entry>srcdir</entry>
- <entry>directory of test subdirectories</entry>
- </row>
-
- <row>
- <entry>--strace</entry>
- <entry>tracelevel</entry>
- <entry>a number: Tcl trace depth</entry>
- </row>
-
- <row>
- <entry>--tool</entry>
- <entry>tool</entry>
- <entry>name of tool to test; identifies init, test subdir</entry>
- </row>
-
- <row>
- <entry>--verbose</entry>
- <entry>verbose</entry>
- <entry>verbosity level. As option, use multiple times; as
- variable, set a number, 0 or greater.</entry>
- </row>
-
- <row>
- <entry>--target</entry>
- <entry>target_triplet</entry>
- <entry>The canonical configuration string for the target.</entry>
- </row>
-
- <row>
- <entry>--host</entry>
- <entry>host_triplet</entry>
- <entry>The canonical configuration string for the host.</entry>
- </row>
-
- <row>
- <entry>--build</entry>
- <entry>build_triplet</entry>
- <entry>The canonical configuration string for the build
- host.</entry>
- </row>
-
- <row>
- <entry>--mail</entry>
- <entry>address</entry>
- <entry>Email the output log to the specified address.</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- </sect3>
-
- <sect3 id="personal" xreflabel="Personal Config File">
- <title>Personal Config File</title>
-
- <para>The personal config file is used to customize
- <command>runtest's</command> behaviour for each person. It is
- typically used to set the user preferred setting for verbosity,
- and any experimental Tcl procedures. My personal
- <filename>~/.dejagnurc</filename> file looks like:</para>
-
- <example>
- <title>Personal Config File</title>
-
- <programlisting>
- set all_flag 1
- set RLOGIN /usr/ucb/rlogin
- set RSH /usr/local/sbin/ssh
- </programlisting>
- </example>
-
- <para>Here I set <symbol>all_flag</symbol> so I see all the test
- cases that PASS along with the ones that FAIL. I also set
- <symbol>RLOGIN</symbol> to the BSD version. I have
- <productname>Kerberos</productname> installed, and when I rlogin
- to a target board, it usually isn't supported. So I use the non
- secure version rather than the default that's in my path. I also
- set <symbol>RSH</symbol> to the <productname>SSH</productname>
- secure shell, as rsh is mostly used to test unix
- machines within a local network here.</para>
-
- </sect3>
- </sect2>
-
- </sect1>
-
- <sect1 id="Extending" xreflabel="Extending DejaGnu">
- <title>Extending &dj;</title>
-
- <sect2 id="addsuite" xreflabel="Adding a new testsuite">
- <title>Adding a new testsuite</title>
-
- <para>The testsuite for a new tool should always be located in that tools
- source directory. &dj; require the directory be named
- <filename>testsuite</filename>. Under this directory, the test
- cases go in a subdirectory whose name begins with the tool
- name. For example, for a tool named <emphasis>myprog</emphasis>,
- each subdirectory containing testsuites must start
- with <emphasis>"myprog."</emphasis>.</para>
-
- </sect2>
-
- <sect2 id="addtool" xreflabel="Adding A New Tool">
- <title>Adding a new tool</title>
-
- <para>In general, the best way to learn how to write code, or
- even prose, is to read something similar. This principle
- applies to test cases and to testsuites. Unfortunately,
- well-established testsuites have a way of developing their own
- conventions: as test writers become more experienced with &dj;
- and with Tcl, they accumulate more utilities, and take advantage
- of more and more features of
- <productname>Expect</productname>
- and <productname>Tcl</productname> in general. Inspecting such
- established testsuites may make the prospect of creating an
- entirely new testsuite appear overwhelming. Nevertheless, it is
- straightforward to start a new testsuite.</para>
-
- <para>To help orient you further in this task, here is an outline of the
- steps to begin building a testsuite for a program example.</para>
-
- <itemizedlist mark="bullet">
-
- <listitem><para>Create or select a directory to contain your new
- collection of tests. Change into that directory (shown here as
- <filename>testsuite</filename>):</para>
-
- <para>Create a <filename>configure.in</filename> file in this directory,
- to control configuration-dependent choices for your tests. So far as
- &dj; is concerned, the important thing is to set a value for the
- variable <symbol>target_abbrev</symbol>; this value is the link to the
- init file you will write soon. (For simplicity, we assume the
- environment is Unix, and use <emphasis>unix</emphasis> as the
- value.)</para>
-
- <para>What else is needed in <filename>configure.in</filename> depends on
- the requirements of your tool, your intended test environments, and which
- configure system you use. This example is a minimal configure.in for use
- with <productname>GNU Autoconf</productname>. </para></listitem>
-
- <listitem><para>Create <filename>Makefile.in</filename> (if using
- Autoconf), or <filename>Makefile.am</filename> (if using
- Automake), the source file used by configure to build your
- <filename>Makefile</filename>. If you are using GNU Automake.just add the
- keyword <emphasis>dejagnu</emphasis> to the
- <emphasis>AUTOMAKE_OPTIONS</emphasis> variable in your
- <filename>Makefile.am</filename> file. This will add all
- the <filename>Makefile</filename> support needed to run &dj;,
- and support the <xref linkend="makecheck"/> target.</para>
-
- <para>You also need to include two targets important to &dj;:
- <emphasis>check</emphasis>, to run the tests, and
- <emphasis>site.exp</emphasis>, to set up the Tcl copies of
- configuration-dependent values. This is called the
- <xref linkend="local"/> The <emphasis>check</emphasis> target
- must invoke the <command>runtest</command> program to run the
- tests.</para>
-
- <para>The <emphasis>site.exp</emphasis> target should usually
- set up (among other things) the <emphasis>$tool</emphasis>
- variable for the name of your program. If the
- local <filename>site.exp</filename> file is setup correctly, it
- is possible to execute the tests by merely
- typing <command>runtest</command> on the command line.</para>
-
- <example>
- <title>Sample Makefile.in Fragment</title>
-
- <programlisting>
- # Look for a local version of &dj;, otherwise use one in the path
- RUNTEST = `if test -f $(top_srcdir)/../dejagnu/runtest; then \
- echo $(top_srcdir) ../dejagnu/runtest; \
- else \
- echo runtest; \
- fi`
-
- # Flags to pass to runtest
- RUNTESTFLAGS =
-
- # Execute the tests
- check: site.exp all
- $(RUNTEST) $(RUNTESTFLAGS) \
- --tool <symbol>${example}</symbol> --srcdir $(srcdir)
-
- # Make the local config file
- site.exp: ./config.status Makefile
- @echo "Making a new config file..."
- -@rm -f ./tmp?
- @touch site.exp
-
- -@mv site.exp site.bak
- @echo "## these variables are automatically\
- generated by make ##" > ./tmp0
- @echo "# Do not edit here. If you wish to\
- override these values" >> ./tmp0
- @echo "# add them to the last section" >> ./tmp0
- @echo "set host_os ${host_os}" >> ./tmp0
- @echo "set host_alias ${host_alias}" >> ./tmp0
- @echo "set host_cpu ${host_cpu}" >> ./tmp0
- @echo "set host_vendor ${host_vendor}" >> ./tmp0
- @echo "set target_os ${target_os}" >> ./tmp0
- @echo "set target_alias ${target_alias}" >> ./tmp0
- @echo "set target_cpu ${target_cpu}" >> ./tmp0
- @echo "set target_vendor ${target_vendor}" >> ./tmp0
- @echo "set host_triplet ${host_canonical}" >> ./tmp0
- @echo "set target_triplet ${target_canonical}">>./tmp0
- @echo "set tool binutils" >> ./tmp0
- @echo "set srcdir ${srcdir}" >> ./tmp0
- @echo "set objdir `pwd`" >> ./tmp0
- @echo "set <symbol>${examplename}</symbol> <symbol>${example}</symbol>" >> ./tmp0
- @echo "## All variables above are generated by\
- configure. Do Not Edit ##" >> ./tmp0
- @cat ./tmp0 > site.exp
- @sed < site.bak \
- -e '1,/^## All variables above are.*##/ d' \
- >> site.exp
- -@rm -f ./tmp?
-
- </programlisting>
- </example>
- </listitem>
-
- <listitem><para>Create a directory (in <filename>testsuite</filename>)
- called <filename>config</filename>. Make a <emphasis>Tool Init
- File</emphasis> in this directory. Its name must start with the
- <symbol>target_abbrev</symbol> value, or be named
- <filename>default.exp</filename> so call it
- <filename>config/unix.exp</filename> for our Unix based
- example. This is the file that contains the target-dependent
- procedures. Fortunately, on a native Unix system, most of
- them do not have to do very much in order
- for <command>runtest</command> to run. If the program being
- tested is not interactive, you can get away with this
- minimal <filename>unix.exp</filename> to begin with:</para>
-
- <example>
- <title>Simple tool init file for batch programs</title>
-
- <programlisting>
- proc myprog_exit {} {}
- proc myprog_version {} {}
- </programlisting>
- </example>
-
- <para>If the program being tested is interactive, however, you might
- as well define a <emphasis>start</emphasis> routine and invoke it by
- using a tool init file like this:</para>
-
- <example>
- <title>Simple tool init file for interactive programs</title>
-
- <programlisting>
- proc myprog_exit {} {}
- proc myprog_version {} {}
-
- proc myprog_start {} {
- global ${examplename}
- spawn ${examplename}
- expect {
- -re "" {}
- }
- }
-
- # Start the program running we want to test
- myprog_start
- </programlisting>
- </example>
- </listitem>
-
- <listitem><para>Create a directory whose name begins with your tool's
- name, to contain tests. For example, if your tool's name is
- <emphasis>myprog</emphasis>, then the directories all need to start with
- <emphasis>"myprog."</emphasis>.</para></listitem>
-
- <listitem><para>Create a sample test file. Its name must end with
- <filename>.exp</filename>. You can use
- <filename>first-try.exp</filename>. To begin with, just write there a
- line of Tcl code to issue a message.</para>
-
- <example>
- <title>Testing A New Tool Config</title>
-
- <programlisting>
-
- send_user "Testing: one, two...\n"
-
- </programlisting>
- </example>
- </listitem>
-
- <listitem><para>Back in the <filename>testsuite</filename> (top
- level) directory, run <command>configure</command>. Typically you do
- this while in the build directory. You may have to specify more of a
- path, if a suitable configure is not available in your execution
- path.</para></listitem>
-
- <listitem><para>You are now ready to type <command>make
- check</command> or <command>runtest</command>. You should
- see something like this:</para>
-
- <example>
- <title>Example Test Case Run</title>
-
- <screen>
- Test Run By bje on Sat Nov 14 15:08:54 AEDT 2015
-
- === example tests ===
-
- Running ./example.0/first-try.exp ...
- Testing: one, two...
-
- === example Summary ===
-
- </screen>
- </example>
-
- <para>There is no output in the summary, because so far the
- example does not call any of the procedures that report a
- test outcome.</para></listitem>
-
- <listitem><para>Write some real tests. For an interactive tool, you
- should probably write a real exit routine in fairly short order. In
- any case, you should also write a real version routine
- soon. </para></listitem>
-
- </itemizedlist>
-
- </sect2>
-
- <sect2 id="addtarget" xreflabel="Adding A New Target">
- <title>Adding A New Target</title>
-
- <para>&dj; has some additional requirements for target support, beyond
- the general-purpose provisions of configure. &dj; 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 &dj; to the target. This permits
- &dj; itself to remain target independent.</para>
-
- <para>Usually the best way to write a new initialization module is to
- edit an existing initialization module; some trial and error will be
- required. If necessary, you can use the <option>--debug</option> option to see what
- is really going on.</para>
-
- <para>When you code an initialization module, be generous in
- printing information controlled by
- the <function>verbose</function> procedure. In
- cross-development environments, most of the work is in getting
- the communications right. Code for communicating via TCP/IP
- networks or serial lines is available in a &dj; library files
- such as <filename>lib/telnet.exp</filename>.</para>
-
- <para>If you suspect a communication problem, try running the connection
- interactively from <productname>Expect</productname>. (There are three
- ways of running <productname>Expect</productname> as an interactive
- interpreter. You can run <productname>Expect</productname> with no
- arguments, and control it completely interactively; or you can use
- <command>expect -i</command> together with other command-line options and
- arguments; or you can run the command <command>interpreter</command> from
- any <productname>Expect</productname> procedure. Use
- <command>return</command> to get back to the calling procedure (if any),
- or <command>return -tcl</command> to make the calling procedure itself
- return to its caller; use <command>exit</command> or end-of-file to leave
- Expect altogether.) Run the program whose name is recorded in
- <symbol>$connectmode</symbol>, with the arguments in
- <symbol>$targetname</symbol>, to establish a connection. You should at
- least be able to get a prompt from any target that is physically
- connected.</para>
-
- </sect2>
-
- <sect2 id="addboard" xreflabel="Adding a new board">
- <title>Adding a new board</title>
-
- <para>Adding a new board consists of creating a new board
- configuration file. Examples are in
- <filename>dejagnu/baseboards</filename>. Usually to make a new
- board file, it's easiest to copy an existing one. It is also
- possible to have your file be based on a
- <emphasis>baseboard</emphasis> file with only one or two
- changes needed. Typically, this can be as simple as just
- changing the linker script. Once the new baseboard file is done,
- add it to the <symbol>boards_DATA</symbol> list in the
- <filename>dejagnu/baseboards/Makefile.am</filename>, and regenerate the
- Makefile.in using automake. Then just rebuild and install &dj;. You
- can test it by:</para>
-
- <para>There is a crude inheritance scheme going on with board files, so
- you can include one board file into another, The two main procedures used
- to do this are <function>load_generic_config</function> and
- <function>load_base_board_description</function>. The generic config file
- contains other procedures used for a certain class of target. The
- board description file is where the board specific settings go. Commonly
- there are similar target environments with just different
- processors.</para>
-
- <example>
- <title>Testing a New Board Configuration File</title>
-
- <screen>
- make check RUNTESTFLAGS="--target_board=<emphasis>newboardfile</emphasis>".
- </screen>
- </example>
-
- <para>Here's an example of a board config file. There are
- several <emphasis>helper procedures</emphasis> used in this
- example. A helper procedure is one that look for a tool of files
- in commonly installed locations. These are mostly used when
- testing in the build tree, because the executables to be tested
- are in the same tree as the new dejagnu files. The helper
- procedures are the ones in square braces
- <emphasis>[]</emphasis>, which is the Tcl execution characters.</para>
-
- <example>
- <title>Example Board Configuration File</title>
-
- <programlisting>
-
- # Load the generic configuration for this board. This will define a basic
- # set of routines needed by the tool to communicate with the board.
- load_generic_config "sim"
-
- # basic-sim.exp is a basic description for the standard Cygnus simulator.
- load_base_board_description "basic-sim"
-
- # The compiler used to build for this board. This has *nothing* to do
- # with what compiler is tested if we're testing gcc.
- set_board_info compiler "[find_gcc]"
-
- # We only support newlib on this target.
- # However, we include libgloss so we can find the linker scripts.
- set_board_info cflags "[newlib_include_flags] [libgloss_include_flags]"
- set_board_info ldflags "[newlib_link_flags]"
-
- # No linker script for this board.
- set_board_info ldscript "-Tsim.ld"
-
- # The simulator doesn't return exit statuses and we need to indicate this.
- set_board_info needs_status_wrapper 1
-
- # Can't pass arguments to this target.
- set_board_info noargs 1
-
- # No signals.
- set_board_info gdb,nosignals 1
-
- # And it can't call functions.
- set_board_info gdb,cannot_call_functions 1
-
- </programlisting>
- </example>
-
- </sect2>
-
- <sect2 id="boarddefs" xreflabel="Board File Values">
- <title>Board Configuration File Values</title>
-
- <para>These fields are all in the <symbol>board_info</symbol> array.
- These are all set by using the <function>set_board_info</function>
- and <function>add_board_info</function> procedures as required. The
- parameters are the field name, followed by the value that the field
- is set to or is added to the field, respectively.</para>
-
- <table frame="all" rowsep="0" colsep="0">
- <title>Common Board Info Fields</title>
-
- <tgroup cols="3" align="char" rowsep="1" colsep="0">
- <thead><row>
- <entry>Field</entry>
- <entry>Sample Value</entry>
- <entry>Description</entry>
- </row></thead>
- <tbody>
-
- <row>
- <entry>compiler</entry>
- <entry>"[find_gcc]"</entry>
- <entry>The path to the compiler to use.</entry>
- </row>
-
- <row>
- <entry>cflags</entry>
- <entry>"-mca"</entry>
- <entry>Compilation flags for the compiler.</entry>
- </row>
-
- <row>
- <entry>ldflags</entry>
- <entry>"[libgloss_link_flags] [newlib_link_flags]"</entry>
- <entry>Linking flags for the compiler.</entry>
- </row>
-
- <row>
- <entry>ldscript</entry>
- <entry>"-Wl,-Tidt.ld"</entry>
- <entry>The linker script to use when cross compiling.</entry>
- </row>
-
- <row>
- <entry>libs</entry>
- <entry>"-lgcc"</entry>
- <entry>Any additional libraries to link in.</entry>
- </row>
-
- <row>
- <entry>shell_prompt</entry>
- <entry>"cygmon>"</entry>
- <entry>The command prompt of the remote shell.</entry>
- </row>
-
- <row>
- <entry>hex_startaddr</entry>
- <entry>"0xa0020000"</entry>
- <entry>The Starting address as a string.</entry>
- </row>
-
- <row>
- <entry>start_addr</entry>
- <entry>0xa0008000</entry>
- <entry>The starting address as a value.</entry>
- </row>
-
- <row>
- <entry>startaddr</entry>
- <entry>"a0020000"</entry>
- <entry></entry>
- </row>
-
- <row>
- <entry>exit_statuses_bad</entry>
- <entry>1</entry>
- <entry>Whether there is an accurate exit status.</entry>
- </row>
-
- <row>
- <entry>reboot_delay</entry>
- <entry>10</entry>
- <entry>The delay between power off and power on.</entry>
- </row>
-
- <row>
- <entry>unreliable</entry>
- <entry>1</entry>
- <entry>Whether communication with the board is unreliable.</entry>
- </row>
-
- <row>
- <entry>sim</entry>
- <entry>[find_sim]</entry>
- <entry>The path to the simulator to use.</entry>
- </row>
-
- <row>
- <entry>objcopy</entry>
- <entry>$tempfil</entry>
- <entry>The path to the <command>objcopy</command> program.</entry>
- </row>
-
- <row>
- <entry>support_libs</entry>
- <entry>"${prefix_dir}/i386-coff/"</entry>
- <entry>Support libraries needed for cross compiling.</entry>
- </row>
-
- <row>
- <entry>addl_link_flags</entry>
- <entry>"-N"</entry>
- <entry>Additional link flags, rarely used.</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- <para>These fields are used by the GCC and GDB tests, and are mostly
- only useful to somewhat trying to debug a new board file for one of
- these tools. Many of these are used only by a few testcases, and their
- purpose is esoteric. These are listed with sample values as a guide to
- better guessing if you need to change any of these.</para>
-
- <table frame="all" rowsep="0" colsep="0">
- <title>Board Info Fields For GCC & GDB</title>
-
- <tgroup cols="3" align="char" rowsep="1" colsep="0">
- <thead><row>
- <entry>Field</entry>
- <entry>Sample Value</entry>
- <entry>Description</entry>
- </row></thead>
- <tbody>
-
- <row>
- <entry>strip</entry>
- <entry>$tempfile</entry>
- <entry>Strip the executable of symbols.</entry>
- </row>
-
- <row>
- <entry>gdb_load_offset</entry>
- <entry>"0x40050000"</entry>
- </row>
-
- <row>
- <entry>gdb_protocol</entry>
- <entry>"remote"</entry>
- <entry>The GDB debugging protocol to use.</entry>
- </row>
-
- <row>
- <entry>gdb_sect_offset</entry>
- <entry>"0x41000000";</entry>
- </row>
-
- <row>
- <entry>gdb_stub_ldscript</entry>
- <entry>"-Wl,-Teva-stub.ld"</entry>
- <entry>The linker script to use with a GDB stub.</entry>
- </row>
-
- <row>
- <entry>gdb,cannot_call_functions</entry>
- <entry>1</entry>
- <entry>Whether GDB can call functions on the target,</entry>
- </row>
-
- <row>
- <entry>gdb,noargs</entry>
- <entry>1</entry>
- <entry>Whether the target can take command line arguments.</entry>
- </row>
-
- <row>
- <entry>gdb,nosignals</entry>
- <entry>1</entry>
- <entry>Whether there are signals on the target.</entry>
- </row>
-
- <row>
- <entry>gdb,short_int</entry>
- <entry>1</entry>
- </row>
-
- <row>
- <entry>gdb,start_symbol</entry>
- <entry>"_start";</entry>
- <entry>The starting symbol in the executable.</entry>
- </row>
-
- <row>
- <entry>gdb,target_sim_options</entry>
- <entry>"-sparclite"</entry>
- <entry>Special options to pass to the simulator.</entry>
- </row>
-
- <row>
- <entry>gdb,timeout</entry>
- <entry>540</entry>
- <entry>Timeout value to use for remote communication.</entry>
- </row>
-
- <row>
- <entry>gdb_init_command</entry>
- <entry>"set mipsfpu none"</entry>
- <entry>A single command to send to GDB before the program being
- debugged is started.</entry>
- </row>
-
- <row>
- <entry>gdb_init_commands</entry>
- <entry>"print/x \$fsr = 0x0"</entry>
- <entry>Same as <emphasis>gdb_init_command</emphasis>, except
- that this is a list, more commands can be added.</entry>
- </row>
-
- <row>
- <entry>gdb_load_offset</entry>
- <entry>"0x12020000"</entry>
- </row>
-
- <row>
- <entry>gdb_opts</entry>
- <entry>"--command gdbinit"</entry>
- </row>
-
- <row>
- <entry>gdb_prompt</entry>
- <entry>"\\(gdb960\\)"</entry>
- <entry>The prompt GDB is using.</entry>
- </row>
-
- <row>
- <entry>gdb_run_command</entry>
- <entry>"jump start"</entry>
- </row>
-
- <row>
- <entry>gdb_stub_offset</entry>
- <entry>"0x12010000"</entry>
- </row>
-
- <row>
- <entry>use_gdb_stub</entry>
- <entry>1</entry>
- <entry>Whether to use a GDB stub.</entry>
- </row>
-
- <row>
- <entry>use_vma_offset</entry>
- <entry>1</entry>
- </row>
-
- <row>
- <entry>wrap_m68k_aout</entry>
- <entry>1</entry>
- </row>
-
- <row>
- <entry>gcc,no_label_values</entry>
- <entry>1</entry>
- </row>
-
- <row>
- <entry>gcc,no_trampolines</entry>
- <entry>1</entry>
- </row>
-
- <row>
- <entry>gcc,no_varargs</entry>
- <entry>1</entry>
- </row>
-
- <row>
- <entry>gcc,stack_size</entry>
- <entry>16384</entry>
- <entry>Stack size to use with some GCC testcases.</entry>
- </row>
-
- <row>
- <entry>ieee_multilib_flags</entry>
- <entry>"-mieee";</entry>
- </row>
-
- <row>
- <entry>is_simulator</entry>
- <entry>1</entry>
- </row>
-
- <row>
- <entry>needs_status_wrapper</entry>
- <entry>1</entry>
- </row>
-
- <row>
- <entry>no_double</entry>
- <entry>1</entry>
- </row>
-
- <row>
- <entry>no_long_long</entry>
- <entry>1</entry>
- </row>
-
- <row>
- <entry>noargs</entry>
- <entry>1</entry>
- </row>
-
- <row>
- <entry>nullstone,lib</entry>
- <entry>"mips-clock.c"</entry>
- </row>
-
- <row>
- <entry>nullstone,ticks_per_sec</entry>
- <entry>3782018</entry>
- </row>
-
- <row>
- <entry>sys_speed_value</entry>
- <entry>200</entry>
- </row>
-
- <row>
- <entry>target_install</entry>
- <entry>{sh-hms}</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- </sect2>
-
- <sect2 id="writing" xreflabel="Writing A Test Case">
- <title>Writing A Test Case</title>
-
- <para>The easiest way to prepare a new test case is to base it
- on an existing one for a similar situation. There are two major
- categories of tests: batch or interactive. Batch oriented tests
- are usually easier to write.</para>
-
- <para>The GCC tests are a good example of batch oriented tests.
- All GCC tests consist primarily of a call to a single common
- procedure, since all the tests either have no output, or only
- have a few warning messages when successfully compiled. Any
- non-warning output is a test failure. All the C code needed is
- kept in the test directory. The test driver, written in Tcl,
- need only get a listing of all the C files in the directory, and
- compile them all using a generic procedure. This procedure and a
- few others supporting for these tests are kept in the library
- module <filename>lib/c-torture.exp</filename> in the GCC test
- suite. Most tests of this kind use very few
- <productname>Expect</productname> features, and are coded almost
- purely in Tcl.</para>
-
- <para>Writing the complete suite of C tests, then, consisted of
- these steps:</para>
-
- <itemizedlist mark="bullet">
- <listitem><para>Copying all the C code into the test directory.
- These tests were based on the C-torture test created by Torbjorn
- Granlund (on behalf of the Free Software Foundation) for GCC
- development.</para></listitem>
-
- <listitem><para>Writing (and debugging) the generic Tcl procedures for
- compilation.</para></listitem>
-
- <listitem><para>Writing the simple test driver: its main task is to
- search the directory (using the Tcl procedure
- <emphasis>glob</emphasis> for filename expansion with wildcards)
- and call a Tcl procedure with each filename. It also checks for
- a few errors from the testing procedure.</para></listitem>
- </itemizedlist>
-
- <para>Testing interactive programs is intrinsically more
- complex. Tests for most interactive programs require some trial
- and error before they are complete.</para>
-
- <para>However, some interactive programs can be tested in a
- simple fashion reminiscent of batch tests. For example, prior
- to the creation of &dj;, 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 &dj; test cases.
- Accordingly, the best approach was simply to encapsulate the
- existing GDB tests, for reporting purposes. Thereafter, new GDB
- tests built up a family of Tcl procedures specialized for GDB
- testing.</para>
-
- </sect2>
-
- <sect2 id="debugging" xreflabel="Debugging A Test Case">
- <title>Debugging A Test Case</title>
-
- <para>These are the kinds of debugging information available
- from &dj;:</para>
-
- <itemizedlist mark="bullet">
-
- <listitem><para>Output controlled by test scripts themselves,
- explicitly allowed for by the test author. This kind of
- debugging output appears in the detailed output recorded in the
- &dj; log file. To do the same for new tests, use the
- <command>verbose</command> procedure (which in turn uses the
- variable also called <emphasis>verbose</emphasis>) to control
- how much output to generate. This will make it easier for other
- people running the test to debug it if necessary. Whenever
- possible, if <emphasis>$verbose</emphasis> is
- <emphasis>0</emphasis>, there should be no output other than the
- output from <emphasis>pass</emphasis>,
- <emphasis>fail</emphasis>, <emphasis>error</emphasis>, and
- <emphasis>warning</emphasis>. Then, to whatever extent is
- appropriate for the particular test, allow successively higher
- values of <emphasis>$verbose</emphasis> to generate more
- information. Be kind to other programmers who use your tests:
- provide for a lot of debugging information.</para></listitem>
-
- <listitem><para>Output from the internal debugging functions of
- Tcl and <productname>Expect</productname>. There is a command
- line options for each; both forms of debugging output are
- recorded in the file <filename>dbg.log</filename> in the current
- directory.</para>
-
- <para>Use <option>--debug</option> for information from the
- expect level; it generates displays of the expect attempts to
- match the tool output with the patterns specified. This output
- can be very helpful while developing test scripts, since it
- shows precisely the characters received. Iterating between the
- latest attempt at a new test script and the corresponding
- <filename>dbg.log</filename> can allow you to create the final
- patterns by ``cut and paste''. This is sometimes the best way
- to write a test case.</para></listitem>
-
- <listitem><para>Use <option>--strace</option> to see more
- detail at the Tcl level; this shows how Tcl procedure
- definitions expand, as they execute. The associated number
- controls the depth of definitions expanded.</para></listitem>
-
- <listitem><para>Finally, if the value of
- <emphasis>verbose</emphasis> is 3 or greater, &dj; turns on
- the expect command <command>log_user</command>. This command
- prints all expect actions to the expect standard output, to the
- detailed log file, and (if <option>--debug</option> is on) to
- <filename>dbg.log</filename>.</para></listitem>
- </itemizedlist>
-
- </sect2>
-
- <sect2 id="adding" xreflabel="Adding a test case to a testsuite">
- <title>Adding a test case to a testsuite</title>
-
- <para>There are two slightly different ways to add a test
- case. One is to add the test case to an existing directory. The
- other is to create a new directory to hold your test. The
- existing test directories represent several styles of testing,
- all of which are slightly different; examine the directories for
- the tool of interest to see which (if any) is most suitable.</para>
-
- <para>Adding a GCC test can be very simple: just add the C code
- to any directory beginning with <filename>gcc</filename> and it
- runs on the next: </para>
- <programlisting>runtest --tool gcc</programlisting>
-
- <para>To add a test to GDB, first add any source code you will
- need to the test directory. Then you can either create a new
- expect file, or add your test to an existing one (any
- file with a <emphasis>.exp</emphasis> suffix). Creating a new
- .exp file is probably a better idea if the test is significantly
- different from existing tests. Adding it as a separate file also
- makes upgrading easier. If the C code has to be already compiled
- before the test will run, then you'll have to add it to the
- <filename>Makefile.in</filename> file for that test directory,
- then run <command>configure</command> and
- <command>make</command>.</para>
-
- <para>Adding a test by creating a new directory is very
- similar:</para>
-
- <itemizedlist mark="bullet">
-
- <listitem><para>Create the new directory. All subdirectory names
- begin with the name of the tool to test; e.g. G++ tests might be
- in a directory called <filename>g++.other</filename>. There can
- be multiple test directories that start with the same tool name
- (such as <emphasis>g++</emphasis>).</para></listitem>
-
- <listitem><para>Add the new directory name to the
- <symbol>configdirs</symbol> definition in the
- <filename>configure.in</filename> file for the testsuite
- directory. This way when <command>make</command> and
- <command>configure</command> next run, they include the new
- directory.</para></listitem>
-
- <listitem><para>Add the new test case to the directory, as
- above. </para></listitem>
-
- <listitem><para>To add support in the new directory for
- configure and make, you must also create a
- <filename>Makefile.in</filename> and a
- <filename>configure.in</filename>.</para></listitem>
- </itemizedlist>
-
- </sect2>
-
- <sect2 id="hints" xreflabel="Hints On Writing A Test Case">
- <title>Hints On Writing A Test Case</title>
-
- <para>It is safest to write patterns that match all the output
- generated by the tested program; this is called closure.
- If a pattern does not match the entire output, any output that
- remains will be examined by the next <command>expect</command>
- command. In this situation, the precise boundary that determines
- which <command>expect</command> command sees what is very
- sensitive to timing between the Expect task and the task running
- the tested tool. As a result, the test may sometimes appear to
- work, but is likely to have unpredictable results. (This problem
- is particularly likely for interactive tools, but can also
- affect batch tools---especially for tests that take a long time
- to finish.) The best way to ensure closure is to use the
- <option>-re</option> option for the <command>expect</command>
- command to write the pattern as a full regular expressions; then
- you can match the end of output using a <emphasis>$</emphasis>.
- It is also a good idea to write patterns that match all
- available output by using <emphasis>.*\</emphasis> after the
- text of interest; this will also match any intervening blank
- lines. Sometimes an alternative is to match end of line using
- <emphasis>\r</emphasis> or <emphasis>\n</emphasis>, but this is
- usually too dependent on terminal settings.</para>
-
- <para>Always escape punctuation, such as <emphasis>(</emphasis>
- or <emphasis>"</emphasis>, in your patterns; for example, write
- <emphasis>\(</emphasis>. If you forget to escape punctuation,
- you will usually see an error message like:</para>
- <programlisting>extra characters after close-quote</programlisting>
-
- <para>If you have trouble understanding why a pattern does not
- match the program output, try using the <option>--debug</option>
- option to <command>runtest</command>, and examine the debug log
- carefully.</para>
-
- <para>Be careful not to neglect output generated by setup rather
- than by the interesting parts of a test case. For example,
- while testing GDB, I issue a send <emphasis>set height
- 0\n</emphasis> command. The purpose is simply to make sure GDB
- never calls a paging program. The <emphasis>set
- height</emphasis> command in GDB does not generate any
- output; but running any command makes GDB issue a new
- <emphasis>(gdb) </emphasis> prompt. If there were no
- <command>expect</command> command to match this prompt, the
- output <emphasis>(gdb) </emphasis> begins the text seen by the
- next <command>expect</command> command---which might make that
- pattern fail to match.</para>
-
- <para>To preserve basic sanity, I also recommended that no test
- ever pass if there was any kind of problem in the test case. To
- take an extreme case, tests that pass even when the tool will
- not spawn are misleading. Ideally, a test in this sort of
- situation should not fail either. Instead, print an error
- message by calling one of the &dj; procedures
- <command>error</command> or <command>warning</command>.</para>
-
- </sect2>
-
- <sect2 id="tvariables" xreflabel="Test case variables">
- <title>Test case special variables</title>
-
- <para>There are special variables that contain other information
- from &dj;. Your test cases can inspect these variables, as well
- as the variables saved in
- <filename>site.exp</filename>. These variables should never be
- changed.</para>
-
- <variablelist>
- <varlistentry>
- <term>$prms_id</term>
- <listitem><para>The bug tracking system (eg. PRMS/GNATS)
- number identifying a corresponding bug report
- (<emphasis>0</emphasis> if you do not specify
- it).</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>$bug_id</term>
- <listitem><para>An optional bug ID, perhaps a bug
- identification number from another organization
- (<emphasis>0</emphasis> if you do not specify
- it).</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>$subdir</term>
- <listitem><para>The subdirectory for the current test
- case.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>$exec_output</term>
- <listitem><para>This is the output from a
- <function>${tool}_load</function> command. This only applies to
- tools like GCC and GAS which produce an object file that must in
- turn be executed to complete a test.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>$comp_output</term>
- <listitem><para>This is the output from a
- <function>${tool}_start</function> command. This is conventionally
- used for batch oriented programs, like GCC and GAS, that may
- produce interesting output (warnings, errors) without further
- interaction.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>$expect_out(buffer)</term>
- <listitem><para>The output from the last command. This is an
- internal variable set by Expect. More information can be found in
- the Expect manual.</para></listitem>
- </varlistentry>
-
- </variablelist>
-
- </sect2>
-
-</sect1>
-
- <sect1 id="unit" xreflabel="Unit Testing">
- <title>Unit Testing</title>
-
- <sect2 id="unittest" xreflabel="What Is Unit Testing?">
- <title>What Is Unit Testing?</title>
-
- <para>Most regression testing as done by &dj; is system testing:
- the complete application is tested all at once. Unit testing is
- for testing single files, or small libraries. In this case, each
- file is linked with a test case in C or C++, and each function
- or class and method is tested in series, with the test case
- having to check private data or global variables to see if the
- function or method worked.</para>
-
- <para>This works particularly well for testing APIs and at level
- where it is easier to debug them, than by needing to trace through
- the entire application. Also if there is a specification for the
- API to be tested, the testcase can also function as a compliance
- test.</para>
-
- </sect2>
-
- <sect2 id="djh" xreflabel="The dejagnu.h header file">
- <title>The dejagnu.h header file</title>
-
- <para>&dj; uses a single header
- file, <filename>dejagnu.h</filename> to assist in unit
- testing. As this file also produces its one test state output,
- it can be run stand-alone, which is very useful for testing on
- embedded systems. This header file has a C and C++ API for the
- test states, with simple totals, and standardized
- output. Because the output has been standardized, &dj; can be
- made to work with this test case, without writing almost any
- Tcl. The library module, dejagnu.exp, will look for the output
- messages, and then merge them into &dj;'s.</para>
-
- </sect2>
-
- <sect2 id="cunit" xreflabel="C Unit Testing API">
- <title>C Unit Testing API</title>
-
- <para>All of the functions that take a
- <parameter>msg</parameter> parameter use a C char * that is the
- message to be displayed. There currently is no support for
- variable length arguments.</para>
-
- <sect3 id="passfunc" xreflabel="pass function">
- <title>Pass Function</title>
-
- <para>This prints a message for a successful test
- completion.</para>
-
- <funcsynopsis role="C">
- <funcprototype>
- <funcdef><function>pass</function></funcdef>
- <paramdef><parameter>msg</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- </sect3>
-
- <sect3 id="failfunc" xreflabel="fail function">
- <title>Fail Function</title>
-
- <para>This prints a message for an unsuccessful test
- completion.</para>
-
- <funcsynopsis role="C">
- <funcprototype>
- <funcdef><function>fail</function></funcdef>
- <paramdef><parameter>msg</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-
- </sect3>
-
- <sect3 id="untestedfunc" xreflabel="untested function">
- <title>Untested Function</title>
-
- <para>This prints a message for an test case that isn't run
- for some technical reason.</para>
-
- <funcsynopsis role="C">
- <funcprototype>
- <funcdef><function>untested</function></funcdef>
- <paramdef><parameter>msg</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect3>
-
- <sect3 id="unresolvedfunc" xreflabel="unresolved function">
- <title>Unresolved Function</title>
-
- <para>This prints a message for an test case that is run,
- but there is no clear result. These output states require a
- human to look over the results to determine what happened.
- </para>
-
- <funcsynopsis role="C">
- <funcprototype>
- <funcdef><function>unresolved</function></funcdef>
- <paramdef><parameter>msg</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect3>
-
- <sect3 id="totalsfunc" xreflabel="totals function">
- <title>Totals Function</title>
-
- <para>This prints out the total numbers of all the test
- state outputs.</para>
-
- <funcsynopsis role="C">
- <funcprototype>
- <funcdef><function>totals</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect3>
-
- </sect2>
-
- <sect2 id="cppunit" xreflabel="C++ Unit Testing API">
- <title>C++ Unit Testing API</title>
-
- <para>All of the methods that take a
- <parameter>msg</parameter> parameter use a C char *
- or STL string, that is the message to be
- displayed. There currently is no support for variable
- length arguments.</para>
-
- <sect3 id="passmeth" xreflabel="pass method">
- <title>Pass Method</title>
-
- <para>This prints a message for a successful test
- completion.</para>
-
- <funcsynopsis role="C++">
- <funcprototype>
- <funcdef><function>TestState::pass</function></funcdef>
- <paramdef><parameter>msg</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect3>
-
- <sect3 id="failmeth" xreflabel="fail method">
- <title>Fail Method</title>
-
- <para>This prints a message for an unsuccessful test
- completion.</para>
-
- <funcsynopsis role="C++">
- <funcprototype>
- <funcdef><function>TestState::fail</function></funcdef>
- <paramdef><parameter>msg</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect3>
-
- <sect3 id="untestedmeth" xreflabel="untested method">
- <title>Untested Method</title>
-
- <para>This prints a message for an test case that isn't run
- for some technical reason.</para>
-
- <funcsynopsis role="C++">
- <funcprototype>
- <funcdef><function>TestState::untested</function></funcdef>
- <paramdef><parameter>msg</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect3>
-
- <sect3 id="unresolvedmeth" xreflabel="unresolved method">
- <title>Unresolved Method</title>
-
- <para>This prints a message for an test case that is run,
- but there is no clear result. These output states require a
- human to look over the results to determine what happened.
- </para>
-
- <funcsynopsis role="C++">
- <funcprototype>
- <funcdef><function>TestState::unresolved</function></funcdef>
- <paramdef><parameter>msg</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect3>
-
- <sect3 id="totalsmeth" xreflabel="totals method">
- <title>Totals Method</title>
-
- <para>This prints out the total numbers of all the test
- state outputs.</para>
-
- <funcsynopsis role="C++">
- <funcprototype>
- <funcdef><function>TestState::totals</function></funcdef>
- <paramdef><parameter></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </sect3>
- </sect2>
-</sect1>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-namecase-general:t
-sgml-general-insert-case:lower
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:nil
-sgml-parent-document:nil
-sgml-exposed-tags:nil
-sgml-local-catalogs:nil
-sgml-local-ecat-files:nil
-End:
--->
projects / platform / upstream / dejagnu.git / commitdiff