diff options
-rw-r--r-- | ChangeLog | 11 | ||||
-rw-r--r-- | doc/overview.sgml | 130 | ||||
-rw-r--r-- | doc/user.sgml | 41 |
3 files changed, 79 insertions, 103 deletions
@@ -1,3 +1,14 @@ +2004-02-17 Ben Elliston <bje@wasabisystems.com> + + This branch is now closed. The documentation has been moved to + XML format on the trunk, so the changes on this branch will be + merged forward and a new documentation branch will be created. + +2004-02-17 Ben Elliston <bje@wasabisystems.com> + + * doc/overview.sgml: More editorial changes. + * doc/user.sgml: Likewise. + 2004-02-04 Ben Elliston <bje@wasabisystems.com> * doc/overview.sgml (revhistory): Update. diff --git a/doc/overview.sgml b/doc/overview.sgml index 5ca5e2d..9808aa1 100644 --- a/doc/overview.sgml +++ b/doc/overview.sgml @@ -76,6 +76,10 @@ into another language, under the above conditions for modified versions. <firstname>Ben Elliston</firstname> <affiliation><orgname>Free Software Foundation</orgname></affiliation> </author> + + <author> + <firstname>Lisa Elliston</firstname> + </author> </authorgroup> <address> <email>rob@welcomehome.org</email> @@ -145,9 +149,9 @@ into another language, under the above conditions for modified versions. <sect1 id=whatis xreflabel="What is &dj;?"> <title>What is &dj;?</title> - <para><productname>&dj;</productname> is a framework for - testing other programs. Its purpose is to provide a uniform - testing environment. Think of it as a library of + <para><productname>&dj;</productname> is a framework for testing + other programs. Its purpose is to provide a uniform testing + environment. Think of it as a library of <productname>Tcl</productname> procedures to support writing a test harness. A <emphasis>test harness</emphasis> is the testing infrastructure created to support a specific @@ -156,17 +160,15 @@ into another language, under the above conditions for modified versions. <productname>Expect</productname>, which in turn relies upon <productname>Tcl</productname>. More information on <productname>Tcl</productname> and - <productname>Expect</productname> can be found at the <ulink - URL="http://www.tcltk.com">Tcl/Tk web site</ulink> and the - <ulink URL="http://expect.nist.gov">Expect home page</ulink>, - respectively.</para> + <productname>Expect</productname> can be found in <xref + linkend=appendix>.</para> <para>Julia Menapace first coined the term ``&dj;'' to describe an earlier testing framework she had written at Cygnus Support for testing <command>GDB</command>. When it was replaced it with the Expect-based framework, it was like &dj; all over again. More importantly, it was also named after Deja Snow - Savoye (13 years old as of September 2003), who was a toddler + Savoye (13 years old in September 2003), who was a toddler during &dj;'s beginnings.</para> <para>There are several advantages to testing with &dj;:</para> @@ -210,7 +212,8 @@ into another language, under the above conditions for modified versions. not based on <productname>Expect</productname>. <productname>Expect</productname> scripts use <emphasis>.exp</emphasis> as a filename extension as a - convention.</para> + convention. Testsuites are typically kept in the source tree of + the programs that they test.</para> </sect1> <sect1 id=new xreflabel="Release Notes"> @@ -269,10 +272,10 @@ into another language, under the above conditions for modified versions. <sect1 id=designgoals xreflabel="Design Goals"> <title>Design Goals</title> - <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. A testing tool was needed that:</para> + <para>&dj; grew out of the needs of Cygnus Solutions, the company + formerly known as Cygnus Support. Cygnus maintained and enhanced a + variety of free programs in many different environments. A + testing tool was needed that:</para> <itemizedlist mark="bullet"> <listitem><para>was useful to developers while fixing @@ -299,10 +302,10 @@ into another language, under the above conditions for modified versions. <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 + packaged evaluation boards 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 mode of communication can be added as required and supported + &dj; was designed with a modular communication setup, so that each + mode of communication can be added as required and supported thereafter. Once a communication procedure is implemented, any testsuite can use it. Currently &dj; can use <command>rsh</command>, <command>rlogin</command>, @@ -475,93 +478,54 @@ into another language, under the above conditions for modified versions. <sect1 id=installation xreflabel="Installation"> <title>Installation</title> - <para>Once you have the DejaGnu source unpacked and available, you must - first configure the software to specify where it is to run (and the - associated defaults); then you can proceed to installing it.</para> + <para>Once you have obtained the DejaGnu source archive and + unpacked it, you must configure the package to specify where it is + to be installed. You may then proceed with installing it.</para> <sect2 id=configuring xreflabel="Configuring DejaGnu"> <title>Configuring DejaGnu</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>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 - required. For an example, to configure in a seperate tree for objects, - execute the configure script from the source tree like this:</para> + <para>It is usually best to configure &dj; in a different + directory than the source tree. To configure from a sibling + build directory, execute the <filename>configure</filename> + script from the source tree like this:</para> <screen> ../dejagnu-&version/configure </screen> - <para>DejaGnu doesn't care at config time if it's for testing a native - system or a cross system. That is determined at runtime by using the - config files.</para> + <para>DejaGnu doesn't distinguish when installed whether it will + be testing programs on a native system or a remote system. That + is determined at runtime via its own configuration 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 - 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 + <para>You may wish to use the <command>configure</command> + option <emphasis>--prefix</emphasis> to specify where you want + DejaGnu installed. The default installation prefix is under + <filename>/usr/local</filename>, but you can select any + alternate directory <symbol>altdir</symbol> by including <option>--prefix</option>{altdir}} on the - <command>configure</command> command line. (This value is captured in - the Makefile variables <emphasis>prefix</emphasis> and - <emphasis>exec</emphasis>prefix}.)</para> - - <para>Save for a small number of example tests, the DejaGnu distribution - itself does not include any testsuites; these are available - separately. Testsuites for the GNU development tools are included in - those releases. After configuring the top-level DejaGnu directory, unpack - and configure the test directories for the tools you want to test; then, - in each test directory, run <emphasis>make check</emphasis> to build - auxiliary programs required by some of the tests, and run the test - suites.</para> + <command>configure</command> command line.</para> - </sect2> + <para>DejaGnu includes a small testsuite of own, but it does not + include other testsuites; these are typically available with the + packages that they test.</para> <sect2 id=installing xreflabel="Installing DejaGnu"> <title>Installing DejaGnu</title> - <para>To install DejaGnu in your filesystem (either in - <filename>/usr/local</filename>, or as specified by your - <emphasis>--prefix</emphasis> option to <emphasis>configure</emphasis>), - execute.</para> + <para>Once a build directory is configured, installing &dj; is a + simple matter of running:</para> <screen> - eg$ make install + $ make install </screen> - <para><emphasis>make install</emphasis>does thes things for - DejaGnu:</para> - - <itemizedlist mark=bullet> - <listitem><para>Look in the path specified for executables - <symbol>$exec_prefix</symbol>) for directories called - <filename>lib</filename> and <filename>bin</filename>. If these - directories do not exist, <emphasis>make install</emphasis> creates - them.</para></listitem> - - <listitem><para>Create another directory in the - <filename>share</filename> directory, called - <filename>dejagnu</filename>, and copy all the library files into - it.</para></listitem> - - <listitem><para>Create a directory in the - <filename>dejagnu/share</filename> directory, called - <filename>config</filename>, and copy all the configuration files into - it.</para></listitem> - - <listitem><para>Copy the <emphasis>runtest</emphasis> shell script into - <filename>$exec_prefix/bin</filename>.</para></listitem> - - <listitem><para>Copy <filename>runtest.exp</filename> into - <filename>$exec_prefix/lib/dejagnu</filename>. This is the main Tcl - code implementing DejaGnu.</para></listitem> - - </itemizedlist> - </sect2> + <para>The <command>make install</command> output will show what + was installed where, but the most important installation step to + note is that the <filename>runtest</filename> command is + installed into the <filename>$prefix/bin</filename> directory. + This program is the driver for &dj;.</para> + </sect2> </sect1> </chapter> diff --git a/doc/user.sgml b/doc/user.sgml index c711a10..1de4c89 100644 --- a/doc/user.sgml +++ b/doc/user.sgml @@ -1,17 +1,17 @@ <chapter id=runningtests> <title>Running Tests</title> - <para>There are two ways to execute a testsuite. The most common - way is to rely upon support in a <filename>Makefile</filename> for - a <emphasis>check</emphasis> target. The other way is to execute - the <command>runtest</command> program directly. To run - <command>runtest</command> directcly from the command line - requires either all the correct options, or the <xref - linkend=local> must be setup correctly. Automake can generate a - <filename>Makefile</filename> that does all of the right things - when the user invokes <command>make check</command> and is the - preferred approach. Both ways of executing a testsuite will be - covered in more detail below.</para> + <para>There are two ways to run a testsuite. The most common way + is to rely on <filename>Makefile</filename> support for a + <emphasis>check</emphasis> target. The other way is to invoke the + <command>runtest</command> program directly. To invoke + <command>runtest</command> from the command line requires either + much care to be taken to ensure that all of the correct options + are given or that the <xref linkend=local> is set up correctly. + Automake can help to produce a <filename>Makefile</filename> that + does the right things when the user invokes <command>make + check</command> and this is the preferred approach. Both ways of + executing a testsuite will be covered in more detail below.</para> <sect1 id=makecheck xreflabel="Make Check"> <title>make check</title> @@ -746,15 +746,16 @@ <chapter id=tutorial> <title>Tutorial</title> -<para>This chapter was originally written by Niklaus Giger (ngiger@mus.ch) because he lost a week to figure out how DejaGnu works and how to write a first test.</para> - -<para>Follow these instructions as closely a possible in order get a -good insight into how DejaGnu works, otherwise you might run into a -lot of subtle problems. The examples given in this chapter were run -on an AMD K6 machine with a AMD K6 and a Mac Powerbook G3 acting as a -remote target. The tests for Windows were run under Windows NT using -Cygwin. Its target system was a PowerPC embedded system running -vxWorks.</para> + +<para>This chapter was originally written by Niklaus Giger +(ngiger@mus.ch) because he lost a week to figure out how DejaGnu works +and how to write a first test.</para> + +<para>This tutorial will give a brief, but sound overview into how +DejaGnu works. The examples given in this chapter were run on an AMD +K6 machine with a Mac Powerbook G3 acting as a remote target. The +tests for Windows were run under Cygwin. Its target system was a +PowerPC embedded system running vxWorks.</para> <sect1> <title>Test your installation</title> |