diff options
| -rw-r--r-- | ChangeLog | 5 | ||||
| -rw-r--r-- | doc/dejagnu.texi | 10 | ||||
| -rw-r--r-- | doc/dejagnu.xml | 98 | ||||
| -rw-r--r-- | doc/ref.xml | 58 | ||||
| -rw-r--r-- | doc/user.xml | 167 |
5 files changed, 166 insertions, 172 deletions
@@ -1,5 +1,10 @@ 2006-06-06 Ben Elliston <bje@gnu.org> + * doc/dejagnu.xml, doc/ref.xml, doc/user.xml: Edits. + * doc/dejagnu.texi: Regenerate. + +2006-06-06 Ben Elliston <bje@gnu.org> + Import from GCC tree: 2006-06-02 Richard Earnshaw <rearnsha@arm.com> Mike Stump <mrs@apple.com> diff --git a/doc/dejagnu.texi b/doc/dejagnu.texi index f802f96..8ac307a 100644 --- a/doc/dejagnu.texi +++ b/doc/dejagnu.texi @@ -459,9 +459,9 @@ dejagnu with a AMD K6 and a Mac Powerbook G3 serving as a remote target. -The tests for Windows were run under Windows NT using the -actual Cygwin version (1.3.x as of October 2001). It's target system -was a PPC embedded system running vxWorks. +The tests for Windows were run under Windows using the actual +Cygwin version (1.3.x as of October 2001). Its target system was a PPC +embedded system running vxWorks. @menu * Test your installation:: @@ -524,7 +524,7 @@ them. On Windows systems DejaGnu is part of a port of a lot of Unix tools to the Windows OS, called Cygwin. Cygwin may be downloaded and installed from a mirror of http://www.cygwin.com/. All examples were -also run on Windows NT. If nothing is said, you can assume that you +also run on Windows. If nothing is said, you can assume that you should get the same output as on a Unix system. You will need a telnet daemon if you want to use a Windows box @@ -2453,7 +2453,7 @@ host. @subsection Personal Config File The personal config file is used to customize -@code{runtest's} behaviour for each person. It's +@code{runtest's} behaviour for each person. It is typically used to set the user prefered setting for verbosity, and any experimental Tcl procedures. My personal @file{~/.dejagnurc} file looks like: diff --git a/doc/dejagnu.xml b/doc/dejagnu.xml index 6a0653a..7dd5527 100644 --- a/doc/dejagnu.xml +++ b/doc/dejagnu.xml @@ -19,60 +19,50 @@ <articleinfo> <title>&dj;</title> <subtitle>The GNU Testing Framework</subtitle> - <date>2004 Feb 04</date> + <date>January 2006</date> <authorgroup> <author> - <firstname>Rob Savoye</firstname> - <affiliation> - <orgname>Free Software Foundation</orgname></affiliation> - <!-- <authorblurb> - <title>Rob Savoye</title> - <para> - His home page is at <ulink> - URL="http://www.welcomehome.org/rob.html">this - location</ulink> - </para> - </authorblurb> - --> + <firstname>Rob</firstname> + <surname>Savoye</surname> + </author> + <author> + <firstname>Ben</firstname> + <surname>Elliston</surname> </author> </authorgroup> - <address> - <email>rob@welcomehome.org</email> - </address> - <!-- &cygnus-street-address; --> + <copyright> - <year>2004</year> - <holder>Rob Savoye</holder> + <year>2006</year> + <holder>Free Software Foundation, Inc.</holder> </copyright> <!-- <legalnotice> <para> --> <!-- [FIXME: must put legal notice here] --> <!-- </para> --> - <!-- &cygnus-legal-notice; --> <!-- </legalnotice> --> <revhistory> <revision> <revnumber>0.6.2</revnumber> - <date>2002-7-16</date> - <authorinitials>rob@welcomehome.org</authorinitials> + <date>2002-07-16</date> + <authorinitials>rob</authorinitials> <revremark>Add new tutorial as a new sect1.</revremark> </revision> <revision> <revnumber>0.6.1</revnumber> - <date>2001-2-16</date> - <authorinitials>rob@welcomehome.org</authorinitials> + <date>2001-02-16</date> + <authorinitials>rob</authorinitials> <revremark>Add info on the new dejagnu.h file.</revremark> </revision> <revision> <revnumber>0.6</revnumber> - <date>2001-2-16</date> - <authorinitials>rob@welcomehome.org</authorinitials> + <date>2001-02-16</date> + <authorinitials>rob</authorinitials> <revremark>Updated for new release.</revremark> </revision> <revision> <revnumber>0.5</revnumber> - <date>2000-1-24</date> - <authorinitials>rob@welcomehome.org</authorinitials> + <date>2000-01-24</date> + <authorinitials>rob</authorinitials> <revremark>Initial version after conversion to DocBook.</revremark> </revision> </revhistory> @@ -82,8 +72,8 @@ <sect1 id="preface"> <title>Abstract</title> - <para>This document describes the functionality of DejaGnu, the - testing framework of the GNU project. DejaGnu is written in + <para>This document describes the functionality of &dj;, the + testing framework of the GNU project. &dj; is written in <productname>Expect</productname>, which uses <productname>Tcl</productname> as a command language. <productname>Expect</productname> acts as a very @@ -95,7 +85,7 @@ <command>diff</command> or <command>sh</command>, with full control over its input and output.</para> - <para>DejaGnu itself is merely a framework for the creation of + <para>&dj; itself is merely a framework for the creation of testsuites. Testsuites are distributed with each application.</para> @@ -106,14 +96,14 @@ <sect2 id="whatis" xreflabel="What is &dj; ?"> <title>What is &dj; ?</title> - <para><productname>DejaGnu</productname> is a framework for + <para><productname>&dj;</productname> is a framework for testing other programs. Its purpose is to provide a single front end for all tests. Think of it as a custom library of Tcl procedures crafted to support writing a test harness. A <emphasis>Test Harness</emphasis> is the testing infrastructure that is created to support a specific program or tool. Each program can have multiple testsuites, all - supported by a single test harness. DejaGnu is written in + supported by a single test harness. &dj; is written in <productname>Expect</productname>, which in turn uses <productname>Tcl</productname> -- Tool command language. There is more information on Tcl at the <ulink @@ -121,43 +111,43 @@ Expect web site is at <ulink url="http://expect.nist.gov">NIST</ulink>.</para> - <para>Julia Menapace first coined the term ``DejaGnu'' to describe + <para>Julia Menapace first coined the term ``&dj;'' to describe an earlier testing framework at Cygnus Support she had written for <command>GDB</command>. When we replaced it with the - Expect-based framework, it was like DejaGnu all over again. + Expect-based framework, it was like &dj; all over again. More importantly, it was also named after my daughter, <ulink url="http://www.welcomehome.org/deja/">Deja Snow Savoye</ulink> (now 14 years old as of Feb 2004), who was a toddler - during DejaGnu's beginnings.</para> + during &dj;'s beginnings.</para> - <para>DejaGnu offers several advantages for testing:</para> + <para>&dj; offers several advantages for testing:</para> <itemizedlist mark="bullet" spacing="compact"> - <listitem><para>The flexibility and consistency of the DejaGnu + <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>DejaGnu provides a layer of abstraction which + <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. DejaGnu runs tests on + 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. DejaGnu's output is designed to be + 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 - DejaGnu, it's easier to have a single set of report analyse + &dj;, it's easier to have a single set of report analyse programs..</para> </listitem> @@ -169,7 +159,7 @@ 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 DejaGnu test + suffix; for example, the main implementation of the &dj; test driver is in the file <productname>runtest.exp</productname>.)</para> @@ -201,7 +191,7 @@ <listitem><para>Lots of little bug fixes from years of heavy use at Cygnus Solutions.</para></listitem> - <listitem><para>DejaGnu now uses + <listitem><para>&dj; now uses <productname>Automake</productname> for Makefile configuration.</para></listitem> @@ -218,7 +208,7 @@ <sect3 id="cygwin" xreflabel="Windows Support"> <title>Windows Support</title> - <para>To use DejaGnu on Windows, you need to first install the + <para>To use &dj; on Windows, you need to first install the <ulink url="http://www.cygwin.com/">Cygwin</ulink> release. This works as of the B20.1 release. Cygwin is a POSIX system for Windows. This covers both utility programs and a library @@ -238,7 +228,7 @@ <sect2 id="designgoals" xreflabel="Design Goals"> <title>Design Goals</title> - <para>DejaGnu grew out of the internal needs of Cygnus Solutions, + <para>&dj; grew out of the internal needs of Cygnus Solutions, the company formerly known as Cygnus Support. Cygnus maintained and enhanced a variety of free programs in many different environments and we needed a testing tool that:</para> @@ -269,10 +259,10 @@ environments are customized by each developer. Even when buying packaged boards from vendors there are many differences. The communication interfaces vary from a serial line to Ethernet. - DejaGnu was designed with a modular communication setup, so that + &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 coded, any test can - use it. Currently DejaGnu can use <command>rsh</command>, + use it. Currently &dj; can use <command>rsh</command>, <command>rlogin</command>, <command>telnet</command>, <command>tip</command>, <command>kermit</command> and <command>mondfe</command> for remote communications.</para> @@ -282,7 +272,7 @@ <sect2 id="posix" xreflabel="A POSIX Conforming Test Framework"> <title>A POSIX conforming test framework</title> - <para>DejaGnu conforms to the POSIX 1003.3 standard for test + <para>&dj; conforms to the POSIX 1003.3 standard for test frameworks. Rob Savoye was a member of that committee.</para> <para>The POSIX standard 1003.3 defines what a testing framework needs to @@ -307,7 +297,7 @@ repeatedly reading the standard and experimenting. One of the main things 1003.3 does specify is the set of allowed output messages and their definitions. Four messages are supported for a required feature of - POSIX conforming systems and a fifth for a conditional feature. DejaGnu + POSIX conforming systems and a fifth for a conditional feature. &dj; supports the use of all five output messages. In this sense a testsuite that uses exactly these messages can be considered POSIX conforming. These definitions specify the output of a test @@ -373,7 +363,7 @@ <listitem><para>A test does not produce a clear result. This is usually because there was an - <emphasis>ERROR</emphasis> from DejaGnu while processing + <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> @@ -406,7 +396,7 @@ <term>UNSUPPORTED</term> <listitem><para>There is no support for the tested case. This may mean that a conditional feature of an operating system, or of a - compiler, is not implemented. DejaGnu also uses this message when + 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> @@ -415,9 +405,9 @@ </varlistentry> </variablelist> - <para>DejaGnu uses the same output procedures to produce these messages + <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 DejaGnu testsuite to conform to POSIX 1003.3, + to POSIX 1003.3. For a &dj; testsuite to conform to POSIX 1003.3, you must avoid the <emphasis>setup</emphasis>xfail} procedure as described in the <emphasis>PASS</emphasis> section above and you must be careful to return <emphasis>UNRESOLVED</emphasis> where appropriate, diff --git a/doc/ref.xml b/doc/ref.xml index fd8239e..988fe35 100644 --- a/doc/ref.xml +++ b/doc/ref.xml @@ -3,9 +3,9 @@ <title>Reference</title> <sect2 id="obtaining" xreflabel="Obtaining DejaGnu"> - <title>Obtaining DejaGnu</title> + <title>Obtaining &dj;</title> - <para>You can obtain DejaGnu from the DejaGnu web site at the + <para>You can obtain &dj; from the &dj; web site at the <ulink url="http://www.gnu.org">Free Software Foundation</ulink>, which is at <ulink url="http://www.gnu.org/software/dejagnu/">www.gnu.org/software/dejagnu/ @@ -16,17 +16,17 @@ <sect2 id="installation" xreflabel="Installation"> <title>Installation</title> - <para>Once you have the DejaGnu source unpacked and available, you must + <para>Once you have the &dj; source unpacked and available, you must first configure the software to specify where it is to run (and the associated defaults); then you can proceed to installing it.</para> <sect3 id="configuring" xreflabel="Configuring DejaGnu"> - <title>Configuring DejaGnu</title> + <title>Configuring &dj;</title> <para>It is usually best to configure in a directory separate from the source tree, specifying where to find the source with the optional <emphasis>--srcdir</emphasis> option to - <emphasis>configure</emphasis>. DejaGnu uses the GNU + <emphasis>configure</emphasis>. &dj; uses the GNU <emphasis>autoconf</emphasis> to configure itself. For more info on using autoconf, read the GNU autoconf manual. To configure, execute the <filename>configure</filename> program, no other options are @@ -37,12 +37,12 @@ ../dejagnu-&version;/configure </screen> - <para>DejaGnu doesn't care at config time if it's for testing a native + <para>&dj; doesn't care at config time if it's for testing a native system or a cross system. That is determined at runtime by using the config files.</para> <para>You may also want to use the <command>configure</command> option - <emphasis>--prefix</emphasis> to specify where you want DejaGnu and its + <emphasis>--prefix</emphasis> to specify where you want &dj; and its supporting code installed. By default, installation is in subdirectories of <filename>/usr/local</filename>, but you can select any alternate directory <symbol>altdir</symbol> by including @@ -51,10 +51,10 @@ the Makefile variables <emphasis>prefix</emphasis> and <emphasis>exec</emphasis>prefix}.)</para> - <para>Save for a small number of example tests, the DejaGnu distribution + <para>Save for a small number of example tests, the &dj; distribution itself does not include any testsuites; these are available separately. Testsuites for the GNU development tools are included in - those releases. After configuring the top-level DejaGnu directory, unpack + those releases. 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 @@ -63,9 +63,9 @@ </sect3> <sect3 id="installing" xreflabel="Installing DejaGnu"> - <title>Installing DejaGnu</title> + <title>Installing &dj;</title> - <para>To install DejaGnu in your filesystem (either in + <para>To install &dj; in your filesystem (either in <filename>/usr/local</filename>, or as specified by your <emphasis>--prefix</emphasis> option to <emphasis>configure</emphasis>), execute.</para> @@ -75,7 +75,7 @@ </screen> <para><emphasis>make install</emphasis>does thes things for - DejaGnu:</para> + &dj;:</para> <itemizedlist mark="bullet"> <listitem><para>Look in the path specified for executables @@ -99,7 +99,7 @@ <listitem><para>Copy <filename>runtest.exp</filename> into <filename>$exec_prefix/lib/dejagnu</filename>. This is the main Tcl - code implementing DejaGnu.</para></listitem> + code implementing &dj;.</para></listitem> </itemizedlist> </sect3> @@ -108,7 +108,7 @@ <sect2 id="builtins" xreflabel="Builtin Procedures"> <title>Builtin Procedures</title> - <para>DejaGnu provides these Tcl procedures.</para> + <para>&dj; provides these Tcl procedures.</para> <sect3 id="coreprocs" xreflabel="Core Internal Procedures"> <title>Core Internal Procedures</title> @@ -1012,10 +1012,10 @@ <sect4 id="loadlib" xreflabel="load_lib procedure"> <title>Load_lib Procedure</title> - <para>Loads a DejaGnu library file by searching a fixed path built - into DejaGnu. If DejaGnu has been installed, it looks in a path + <para>Loads a &dj; library file by searching a fixed path built + into &dj;. If &dj; has been installed, it looks in a path starting with the installed library directory. If you are running - DejaGnu directly from a source directory, without first running + &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 @@ -1031,7 +1031,7 @@ <variablelist> <varlistentry> <term><parameter>filespec</parameter></term> - <listitem><para>The name of the DejaGnu library file to + <listitem><para>The name of the &dj; library file to load.</para></listitem> </varlistentry> </variablelist> @@ -3306,7 +3306,7 @@ <para>This invokes the compiler as set by CC to compile the file <filename>file</filename>. The default options for many cross - compilation targets are <emphasis>guessed</emphasis> by DejaGnu, and + 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 @@ -3382,7 +3382,7 @@ info to execute this command on the build machine or a remote host. All config information for the remote host must be setup to have this command work. If this is a canadian cross, (where we test a - cross compiler that runs on a different host then where DejaGnu is + 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 @@ -3447,7 +3447,7 @@ An example of this second kind of start function is <function>gcc_start</function>, the start function for GCC.</para> - <para>DejaGnu itself does not call + <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; @@ -3478,7 +3478,7 @@ program it runs in a variable called <symbol>$exec_output</symbol>. Writing <function>${tool}_load</function> can be the most complex - part of extending DejaGnu to a new tool or a new target, if + 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> @@ -3494,7 +3494,7 @@ <sect4 id="toolexit" xreflabel="${tool}_exit procedure"> <title>${tool}_exit Procedure</title> - <para>Cleans up (if necessary) before DejaGnu exits. For + <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 @@ -3513,7 +3513,7 @@ <title>${tool}_version Procedure</title> <para>Prints the version label and number for - <symbol>${tool}</symbol>. This is called by the DejaGnu + <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> @@ -3666,7 +3666,7 @@ <sect4 id="prune" xreflabel="prune procedure"> <title>Prune Procedure</title> <para>This procedure is deprecated and will be removed in - the next release of DejaGnu. If a testsuite uses this + 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> @@ -3674,7 +3674,7 @@ <sect4 id="slay" xreflabel="slay procedure"> <title>Slay Procedure</title> <para>This procedure is deprecated and will be removed in - the next release of DejaGnu. If a testsuite uses this + 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> @@ -3682,7 +3682,7 @@ <sect4 id="absolute" xreflabel="absolute procedure"> <title>Absolute Procedure</title> <para>This procedure is deprecated and will be removed in - the next release of DejaGnu. If a testsuite uses this + 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> @@ -3690,7 +3690,7 @@ <sect4 id="psource" xreflabel="psource procedure"> <title>Psource Procedure</title> <para>This procedure is deprecated and will be removed in - the next release of DejaGnu. If a testsuite uses this + 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> @@ -4535,7 +4535,7 @@ <sect2 id="filemap"> <title>File Map</title> - <para>This is a map of the files in DejaGnu.</para> + <para>This is a map of the files in &dj;.</para> <itemizedlist> <listitem><para>runtest</para></listitem> diff --git a/doc/user.xml b/doc/user.xml index f4fa81d..d0f0838 100644 --- a/doc/user.xml +++ b/doc/user.xml @@ -1,32 +1,31 @@ <sect1 id="gettingup"> - <title>Getting DejaGnu up and running</title> + <title>Getting &dj; up and running</title> <para>This chapter was originally written by Niklaus Giger - (ngiger@mus.ch) because he lost a week to figure out how DejaGnu works + (ngiger@mus.ch) because he lost a week to figure out how &dj; works and how to write a first test. </para> <para>Follow these instructions as closely a possible in order get a -good insight into how DejaGnu works, else you might run into a lot of +good insight into how &dj; works, else you might run into a lot of subtle problems. You have been warned.</para> -<para>It should be no big problems installing DejaGnu using your +<para>It should be no big problems installing &dj; using your package manager or from the source code. Under a Debian/GNU/Linux systems just type (as root) <programlisting>apt-get dejagnu</programlisting>. These examples were run on a primary machine with a AMD K6 and a Mac Powerbook G3 serving as a remote target.</para> -<para> The tests for Windows were run under Windows NT using the -actual Cygwin version (1.3.x as of October 2001). It's target system -was a PPC embedded system running vxWorks. -</para> +<para> The tests for Windows were run under Windows using the actual +Cygwin version (1.3.x as of October 2001). Its target system was a PPC +embedded system running vxWorks. </para> <sect2> <title>Test your installation</title> -<para>Create a new user called "dgt" (DejaGnuTest), which uses bash as +<para>Create a new user called "dgt" (&dj;Test), which uses bash as it login shell. PS1 must be set to '\u:\w\$ ' in its ~/.bashrc. Login as this user, create an empty directory and change the working directory to it. e.g</para> @@ -36,7 +35,7 @@ dgt:~$ mkdir ~/dejagnu.test dgt:~$ cd ~/dejagnu.test </programlisting> -<para>Now you are ready to test DejaGnu's main program called +<para>Now you are ready to test &dj;'s main program called runtest. The expecteted output is shown</para> <example> @@ -67,10 +66,10 @@ them.</para> <sect3> <title>Windows</title> -<para>On Windows systems DejaGnu is part of a port of a lot of Unix +<para>On Windows systems &dj; is part of a port of a lot of Unix tools to the Windows OS, called Cygwin. Cygwin may be downloaded and installed from a mirror of http://www.cygwin.com/. All examples were -also run on Windows NT. If nothing is said, you can assume that you +also run on Windows. If nothing is said, you can assume that you should get the same output as on a Unix system.</para> <para>You will need a telnet daemon if you want to use a Windows box @@ -84,7 +83,7 @@ http://www.fictional.net/.</para> <para>If you are running a Debian distribution you can find the examples under /usr/share/doc/dejagnu/examples. These examples seem to be missing in Red Hat's RPM. In this case download the sources of -DejaGnu and adjust the pathes to the DejaGnu examples +&dj; and adjust the pathes to the &dj; examples accordingly.</para> </sect3> </sect2> @@ -93,7 +92,7 @@ accordingly.</para> <title>Create a minimal project, e.g. calc</title> <para>In this section you will to start a small project, -using the sample application calc, which is part of your DejaGnu +using the sample application calc, which is part of your &dj; distribution</para> <sect3><title>A simple project without the GNU autotools</title> @@ -119,7 +118,7 @@ automake. There is book "GNU autoconf, automake and libtool" by Garry V. Vaughan, et al. NewRider, ISBN 1-57870-190-2 which describes this process thoroughly.</para> -<para>From the calc example distributed with the DejaGnu documentation +<para>From the calc example distributed with the &dj; documentation you should copy the program file itself (calc.c) and some additional files, which you might examine a little bit close to derive their meanings.</para> @@ -152,7 +151,7 @@ Run it to generate calc.h.in. </para> dgt:~/dejagnu.test$ autoheader </programlisting> -<para>The Makefile.am of this example was developed as port of the DejaGnu +<para>The Makefile.am of this example was developed as port of the &dj; distribution. Adapt Makefile.am for this test. Replace the line "#noinst_PROGRAMS = calc" to @@ -271,7 +270,7 @@ calc: quit <para>Look at the intentional bug that 2 times 4 equals 12.</para> -<para>The tests run by DejaGnu need a file called site.exp, +<para>The tests run by &dj; need a file called site.exp, which is automatically generated if we call "make site.exp". This was the purpose of the "AUTOMAKE_OPTIONS = dejagnu" in Makefile.am.</para> @@ -350,7 +349,7 @@ long.</para> <sect3><title>The various config files or how to avoid warnings</title> -<para>DejaGnu may be customized by each user. It first searches for a +<para>&dj; may be customized by each user. It first searches for a file called ~/.dejagnurc. Create the file ~/.dejagnurc and insert the following line:</para> @@ -527,7 +526,7 @@ Connection closed by foreign host. <title>A test case for login via telnet</title> <para>In order to define a correct setup we have add a line containing "set target unix" either to ~/.dejagnurc or to ~/my_dejagnu.exp. -In ~/boards/standard.exp add the following four lines to define a few patterns for the DejaGnu telnet login procedure.</para> +In ~/boards/standard.exp add the following four lines to define a few patterns for the &dj; telnet login procedure.</para> <example> <title>Defining a remote target board</title> @@ -540,7 +539,7 @@ set_board_info hostname "localhost" </programlisting> </example> -<para>As DejaGnu will be parsing the telnet session output for some well +<para>As &dj; will be parsing the telnet session output for some well known pattern the output there are a lot of things that can go wrong. If you have any problems verify your setup:</para> <itemizedlist> @@ -563,7 +562,7 @@ Create the file ~/dejagnu.test/testsuite/calc.test/remote_echo.exp and add the following few lines:</para> <example> -<title>DejaGnu script for logging in into a remote target</title> +<title>&dj; script for logging in into a remote target</title> <programlisting> puts "this is remote_echo.exp target for $target " target_info $target @@ -589,7 +588,7 @@ this is remote_echo.exp target is unix Spawn id for remote shell is exp7 </programlisting> -<para>Have again a look at calc.log to get a feeling how DejaGnu and expect +<para>Have again a look at calc.log to get a feeling how &dj; and expect parse the input. </para></sect3> <sect3> @@ -755,7 +754,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <para>In order to test the vxWorks as a target I changed boards/standards.exp to reflect my settings (IP, username, password). Then I reconfigured vxWorks to include a FTP and telnet server (using the same username/password combination ad in boards/standard.exp).</para> -<para>With this setup and some minor modification (e.g. replacing echo by printf) in my test cases I could test my vxWorks system. It sure does not seem to be a correct setup by DejaGnu standard. For instance, it still loading /usr/share/dejagnu/baseboards/unix.exp instead of vxWorks. In any case I found that (at least under Windows) I did not find out how the command line would let me override settings in my personal config files.</para> +<para>With this setup and some minor modification (e.g. replacing echo by printf) in my test cases I could test my vxWorks system. It sure does not seem to be a correct setup by &dj; standard. For instance, it still loading /usr/share/dejagnu/baseboards/unix.exp instead of vxWorks. In any case I found that (at least under Windows) I did not find out how the command line would let me override settings in my personal config files.</para> </sect3> </sect2> @@ -788,12 +787,12 @@ powerpc-linux-gcc -g -O2 -o calc calc.o auxiliary programs or other files needed by the tests. The most common file the check builds is the <emphasis>site.exp</emphasis>. The site.exp file contains - various variables that DejaGnu used to dertermine the + various variables that &dj; used to dertermine the configuration of the program being tested. This is mostly for supporting remote testing.</para> <para>The <emphasis>check</emphasis> target is supported by GNU - <productname>Automake</productname>. To have DejaGnu support added to your + <productname>Automake</productname>. To have &dj; support added to your generated <filename>Makefile.in</filename>, just add the keyword dejagnu to the AUTOMAKE_OPTIONS variable in your <filename>Makefile.am</filename> file.</para> @@ -812,7 +811,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <title>Runtest</title> <para><command>runtest</command> is the executable test driver - for DejaGnu. You can specify two kinds of things on the + for &dj;. You can specify two kinds of things on the <command>runtest</command> command line: command line options, and Tcl variables for the test scripts. The options are listed alphabetically below.</para> @@ -945,7 +944,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <term><option>--build [string]</option></term> <listitem><para><emphasis>string</emphasis> is a full configuration ``triple'' name as used by <command>configure</command>. This - is the type of machine DejaGnu and the tools to be tested are built + 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 seperate.</para></listitem> </varlistentry> @@ -957,7 +956,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o option to override the default string recorded by your configuration's choice of host. This choice does not change how anything is actually configured unless --build is also specified; it - affects <emphasis>only</emphasis> DejaGnu procedures that compare the + 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</emphasis>xfail} @@ -966,7 +965,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o be run on, which may not be the same as the <emphasis>build</emphasis> machine. If <emphasis>--build</emphasis> is also specified, then <emphasis>--host</emphasis> refers to the - machine that the tests wil, be run on, not the machine DejaGnu is run + machine that the tests wil, be run on, not the machine &dj; is run on.</para></listitem> </varlistentry> @@ -1031,7 +1030,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <emphasis>runtest</emphasis>. This option affects only the summary and the detailed log files <filename>tool.sum</filename> and - <filename>tool.log</filename>. The DejaGnu debug + <filename>tool.log</filename>. The &dj; debug log <filename>dbg.log</filename> always appears (when requested) in the local directory.</para></listitem> </varlistentry> @@ -1078,7 +1077,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o running <emphasis>runtest</emphasis>. For example, use <emphasis>--connect</emphasis> to change the program used to connect to a ``bare board'' boot monitor. The choices for - <emphasis>type</emphasis> in the DejaGnu 1.4 distribution are + <emphasis>type</emphasis> in the &dj; 1.4 distribution are <emphasis>rlogin</emphasis>, <emphasis>telnet</emphasis>, <emphasis>rsh</emphasis>, <emphasis>tip</emphasis>, <emphasis>kermit</emphasis>, and <emphasis>mondfe</emphasis>.</para> @@ -1150,7 +1149,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <varlistentry> <term><option>--version</option> (-V)</term> - <listitem><para>Prints out the version numbers of DejaGnu, + <listitem><para>Prints out the version numbers of &dj;, <emphasis>expect</emphasis> and Tcl, and exits without running any tests.</para></listitem> </varlistentry> @@ -1164,8 +1163,8 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <emphasis>expect</emphasis> as the file <filename>expect/tcl-debug.ps.</filename>. If you specify <emphasis>-D1</emphasis>, the <emphasis>expect</emphasis> shell stops - at a breakpoint as soon as DejaGnu invokes it. If you specify - <emphasis>-D0</emphasis>, DejaGnu starts as usual, but you can enter + 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>C</keycap><keycap>c</keycap></keycombo>). </para></listitem> @@ -1204,7 +1203,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <emphasis>gdb.old</emphasis>.</para> <para>The default Tcl variables used for most tools are defined in - the main DejaGnu <emphasis>Makefile</emphasis>; their values are + the main &dj; <emphasis>Makefile</emphasis>; their values are captured in the <filename>site.exp</filename> file.</para></listitem> </varlistentry> </variablelist> @@ -1219,7 +1218,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o local site.exp file, created by "make site.exp".</para> <para>For example, if the directory <filename>gdb/testsuite</filename> - contains a collection of DejaGnu tests for GDB, you can run them like + contains a collection of &dj; tests for GDB, you can run them like this:</para> <screen> @@ -1267,9 +1266,9 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <sect2 id="outputfiles" xreflabel="Output Files"> - <title>The files DejaGnu produces.</title> + <title>The files &dj; produces.</title> - <para>DejaGnu always writes two kinds of output files: summary + <para>&dj; always writes two kinds of output files: summary logs and detailed logs. The contents of both of these are determined by your tests.</para> @@ -1281,7 +1280,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <sect3 id="sum" xreflabel="Summary File"> <title>Summary File</title> - <para>DejaGnu always produces a summary output file + <para>&dj; always produces a summary output file <filename>tool.sum</filename>. This summary shows the names of all test files run; for each test file, one line of output from each <command>pass</command> command (showing status @@ -1302,7 +1301,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <para>For example, after <command>runtest --tool binutils</command>, look for a summary log in - <filename>binutils.sum</filename>. Normally, DejaGnu writes this + <filename>binutils.sum</filename>. Normally, &dj; writes this file in your current working directory; use the <option>--outdir</option> option to select a different directory.</para> @@ -1336,11 +1335,11 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <sect3 id="log" xreflabel="Log File"> <title>Log File</title> - <para>DejaGnu also saves a detailed log file + <para>&dj; also saves a detailed log file <filename>tool.log</filename>, showing any output generated by tests as well as the summary output. For example, after <command>runtest --tool binutils</command>, look for a detailed - log in <filename>binutils.log</filename>. Normally, DejaGnu + log in <filename>binutils.log</filename>. Normally, &dj; writes this file in your current working directory; use the <option>--outdir</option> option to select a different directory.</para> @@ -1462,7 +1461,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <para>This example exhibits three properties of <productname>Expect</productname> and - <productname>DejaGnu</productname> that might be surprising at + <productname>&dj;</productname> that might be surprising at first glance:</para> <itemizedlist mark="bullet"> @@ -1510,19 +1509,19 @@ powerpc-linux-gcc -g -O2 -o calc calc.o </sect1> <sect1 id="Customizing" xreflabel="Customizing DejaGnu"> - <title>Customizing DejaGnu</title> + <title>Customizing &dj;</title> <para>The site configuration file, <filename>site.exp</filename>, captures configuration-dependent values and propagates them to the - DejaGnu test environment using Tcl variables. This ties the - DejaGnu test scripts into the <command>configure</command> and + &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>DejaGnu supports two <filename>site.exp</filename> + <para>&dj; supports two <filename>site.exp</filename> files. The multiple instances of <filename>site.exp</filename> are - loaded in a fixed order built into DejaGnu. The first file loaded + loaded in a fixed order built into &dj;. 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 @@ -1530,11 +1529,11 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <para>There is an optional <emphasis>master</emphasis> <filename>site.exp</filename>, capturing configuration values that - apply to DejaGnu across the board, in each configuration-specific - subdirectory of the DejaGnu library directory. + 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 DejaGnu. This master file is + 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 refered to as the ``global'' config file.</para> @@ -1569,7 +1568,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <para>It is usually more convenient to keep these <emphasis>manual overrides</emphasis> in the <filename>site.exp</filename> local to each test directory, rather than in the global - <filename>site.exp</filename> in the installed DejaGnu + <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> @@ -1598,7 +1597,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o </example> <para>In the second section, you can override any default values - (locally to DejaGnu) for all the variables. The second section + (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 @@ -1654,7 +1653,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o file, namely the three config triplets, and the srcdir. It also defines several other Tcl variables that are used exclusivly by the GCC testsuite. For most test cases, the CXXFLAGS and LDFLAGS - are supplied by DejaGnu itself for cross testing, but to test a + are supplied by &dj; itself for cross testing, but to test a compiler, GCC needs to manipulate these itself.</para> </sect2> @@ -1713,7 +1712,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <para>In this case, we have support for several cross compilers, that all run on this host. For testing on operating systems that - don't support Expect, DejaGnu can be run on the local build + 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 telnetd.</para> @@ -1816,7 +1815,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <note><para>Thanks to Dj Delorie for the original paper that this section is based on.</para></note> - <para>DejaGnu also supports running the tests on a remote + <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> @@ -1949,7 +1948,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <sect2 id="configfile" xreflabel="Config File Values"> <title>Config File Values</title> - <para>DejaGnu uses a named array in Tcl to hold all the info for + <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 @@ -2086,7 +2085,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <title>Personal Config File</title> <para>The personal config file is used to customize - <command>runtest's</command> behaviour for each person. It's + <command>runtest's</command> behaviour for each person. It is typically used to set the user prefered setting for verbosity, and any experimental Tcl procedures. My personal <filename>~/.dejagnurc</filename> file looks like:</para> @@ -2117,13 +2116,13 @@ powerpc-linux-gcc -g -O2 -o calc calc.o </sect1> <sect1 id="Extending" xreflabel="Extending DejaGnu"> - <title>Extending DejaGnu</title> + <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. DejaGnu require the directory be named + 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>flubber</emphasis>, each subdirectory containing @@ -2138,7 +2137,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o is to read something similar. This principle applies to test cases and to testsuites. Unfortunately, well-established testsuites have a way of developing their own conventions: as test writers become more - experienced with DejaGnu and with Tcl, they accumulate more utilities, + 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.</para> @@ -2149,8 +2148,8 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <para>There is one testsuite that is guaranteed not to grow more elaborate over time: both it and the tool it tests were created expressly - to illustrate what it takes to get started with DejaGnu. The - <filename>example/</filename> directory of the DejaGnu distribution + to illustrate what it takes to get started with &dj;. The + <filename>example/</filename> directory of the &dj; distribution contains both an interactive tool called <command>calc</command>, and a testsuite for it. Reading this testsuite, and experimenting with it, is a good way to supplement the information in this section. (Thanks to @@ -2168,7 +2167,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <para>Create a <filename>configure.in</filename> file in this directory, to control configuration-dependent choices for your tests. So far as - DejaGnu is concerned, the important thing is to set a value for the + &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 @@ -2186,10 +2185,10 @@ powerpc-linux-gcc -g -O2 -o calc calc.o keyword <emphasis>dejagnu</emphasis> to the <emphasis>AUTOMAKE_OPTIONS</emphasis> variable in your <filename>Makefile.am</filename> file. This will add all the Makefile - support needed to run DejaGnu, and support the <xref linkend="makecheck"/> + support needed to run &dj;, and support the <xref linkend="makecheck"/> target.</para> - <para>You also need to include two targets important to DejaGnu: + <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"/> @@ -2206,7 +2205,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <title>Sample Makefile.in Fragment</title> <programlisting> - # Look for a local version of DejaGnu, otherwise use one in the path + # 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 \ @@ -2374,13 +2373,13 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <sect2 id="addtarget" xreflabel="Adding A New Target"> <title>Adding A New Target</title> - <para>DejaGnu has some additional requirements for target support, beyond - the general-purpose provisions of configure. DejaGnu must actively + <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 DejaGnu to the target. This permits - DejaGnu itself to remain target independent.</para> + 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 @@ -2393,7 +2392,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <para>For cross targets, most of the work is in getting the communications right. Communications code (for several situations - involving IP networks or serial lines) is available in a DejaGnu library + involving IP networks or serial lines) is available in a &dj; library file.</para> <para>If you suspect a communication problem, try running the connection @@ -2428,7 +2427,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o changing the linker script. Once the new baseboard file is done, add it to the <symbol>boards_DATA</symbol> list in the <filename>dejagnu/baseboards/Makefile.am</filename>, and regenerate the - Makefile.in using automake. Then just rebuild and install DejaGnu. You + 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 @@ -2881,10 +2880,10 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <para>However, some interactive programs can be tested in a simple fashion reminiscent of batch tests. For example, prior - to the creation of DejaGnu, the GDB distribution already + 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 DejaGnu test cases. + 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 @@ -2896,14 +2895,14 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <title>Debugging A Test Case</title> <para>These are the kinds of debugging information available - from DejaGnu:</para> + 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 - DejaGnu log file. To do the same for new tests, use 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 @@ -2940,7 +2939,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o controls the depth of definitions expanded.</para></listitem> <listitem><para>Finally, if the value of - <emphasis>verbose</emphasis> is 3 or greater,DejaGnu turns on + <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 @@ -3059,7 +3058,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o take an extreme case, tests that pass even when the tool will not spawn are misleading. Ideally, a test in this sort of situation should not fail either. Instead, print an error - message by calling one of the DejaGnu procedures + message by calling one of the &dj; procedures <command>error</command> or <command>warning</command>.</para> </sect2> @@ -3068,7 +3067,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <title>Special variables used by test cases.</title> <para>There are special variables used by test cases. These contain - other information from DejaGnu. Your test cases can use these variables, + other information from &dj;. Your test cases can use these variables, with conventional meanings (as well as the variables saved in <filename>site.exp</filename>. You can use the value of these variables, but they should never be changed.</para> @@ -3129,7 +3128,7 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <sect2 id="unittest" xreflabel="What Is Unit Testing ?"> <title>What Is Unit Testing ?</title> - <para>Most regression testing as done by DejaGnu is system + <para>Most regression testing as done by &dj; is system testing. This is the complete application is tested all at once. Unit testing is for testing single files, or small libraries. In this case, each file is linked with a test case in @@ -3148,15 +3147,15 @@ powerpc-linux-gcc -g -O2 -o calc calc.o <sect2 id="djh" xreflabel="The dejagnu.h Header File"> <title>The dejagnu.h Header File</title> - <para>DejaGnu uses a single header file to assist in unit + <para>&dj; uses a single header file to assist in unit testing. As this file also produces it's one test state output, it can be run standalone, which is very useful for testing on embedded systems. This header file has a C and C++ API for the test states, with simple totals, and standardized - output. Because the output has been standardized, DejaGnu can be + 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 DejaGnu's.</para> + messages, and then merge them into &dj;'s.</para> </sect2> |