diff options
| -rw-r--r-- | ChangeLog | 11 | ||||
| -rw-r--r-- | Makefile.am | 26 | ||||
| -rw-r--r-- | Makefile.in | 26 | ||||
| -rwxr-xr-x | configure | 211 | ||||
| -rw-r--r-- | configure.ac | 7 | ||||
| -rw-r--r-- | doc/dejagnu.xml | 370 | ||||
| -rw-r--r-- | doc/legal.xml | 76 | ||||
| -rw-r--r-- | doc/ref.xml | 4458 | ||||
| -rw-r--r-- | doc/user.xml | 2568 |
9 files changed, 13 insertions, 7740 deletions
@@ -1,5 +1,16 @@ 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. diff --git a/Makefile.am b/Makefile.am index 6172558..aaaca55 100644 --- a/Makefile.am +++ b/Makefile.am @@ -166,29 +166,3 @@ unit_SOURCES = testsuite/libdejagnu/unit.cc 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 diff --git a/Makefile.in b/Makefile.in index 842237b..323f8e8 100644 --- a/Makefile.in +++ b/Makefile.in @@ -288,11 +288,6 @@ CYGPATH_W = @CYGPATH_W@ 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@ @@ -502,7 +497,6 @@ unit_SOURCES = testsuite/libdejagnu/unit.cc # Documentation. dist_man_MANS = doc/runtest.1 info_TEXINFOS = doc/dejagnu.texi -XML = doc/dejagnu.xml doc/legal.xml doc/ref.xml doc/user.xml all: all-am .SUFFIXES: @@ -1245,7 +1239,7 @@ dvi-am: $(DVIS) html: html-am -html-am: $(HTMLS) html-local +html-am: $(HTMLS) info: info-am @@ -1410,7 +1404,7 @@ uninstall-man: uninstall-man1 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 \ @@ -1434,22 +1428,6 @@ export DEJAGNU 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: @@ -592,11 +592,6 @@ LIBOBJS subdirs DEJAGNU EXPECT -DOCBOOK2TEXI -DOCBOOK2PS -DOCBOOK2PDF -DOCBOOK2RTF -DOCBOOK2HTML am__fastdepCXX_FALSE am__fastdepCXX_TRUE CXXDEPMODE @@ -3939,212 +3934,6 @@ fi -# 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 diff --git a/configure.ac b/configure.ac index c1057c5..fcd8f72 100644 --- a/configure.ac +++ b/configure.ac @@ -30,13 +30,6 @@ AC_PROG_CXX 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 diff --git a/doc/dejagnu.xml b/doc/dejagnu.xml deleted file mode 100644 index 488ab3a..0000000 --- a/doc/dejagnu.xml +++ /dev/null @@ -1,370 +0,0 @@ -<?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: ---> diff --git a/doc/legal.xml b/doc/legal.xml deleted file mode 100644 index ac97e1d..0000000 --- a/doc/legal.xml +++ /dev/null @@ -1,76 +0,0 @@ - <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> - diff --git a/doc/ref.xml b/doc/ref.xml deleted file mode 100644 index 05013ae..0000000 --- a/doc/ref.xml +++ /dev/null @@ -1,4458 +0,0 @@ - -<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 - --> diff --git a/doc/user.xml b/doc/user.xml deleted file mode 100644 index b9c8d51..0000000 --- a/doc/user.xml +++ /dev/null @@ -1,2568 +0,0 @@ - - <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: ---> |