From 29801e2a1c7a0c8a5c81e71a175a210b1f011aab Mon Sep 17 00:00:00 2001 From: Ben Elliston Date: Tue, 17 Feb 2004 02:40:55 +0000 Subject: 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. * doc/overview.sgml: More editorial changes. * doc/user.sgml: Likewise. --- ChangeLog | 11 +++++ doc/overview.sgml | 130 ++++++++++++++++++++---------------------------------- doc/user.sgml | 41 ++++++++--------- 3 files changed, 79 insertions(+), 103 deletions(-) diff --git a/ChangeLog b/ChangeLog index e350872..ee11265 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,14 @@ +2004-02-17 Ben Elliston + + 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 + + * doc/overview.sgml: More editorial changes. + * doc/user.sgml: Likewise. + 2004-02-04 Ben Elliston * 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. Ben Elliston Free Software Foundation + + + Lisa Elliston +
rob@welcomehome.org @@ -145,9 +149,9 @@ into another language, under the above conditions for modified versions. What is &dj;? - &dj; is a framework for - testing other programs. Its purpose is to provide a uniform - testing environment. Think of it as a library of + &dj; is a framework for testing + other programs. Its purpose is to provide a uniform testing + environment. Think of it as a library of Tcl procedures to support writing a test harness. A test harness is the testing infrastructure created to support a specific @@ -156,17 +160,15 @@ into another language, under the above conditions for modified versions. Expect, which in turn relies upon Tcl. More information on Tcl and - Expect can be found at the Tcl/Tk web site and the - Expect home page, - respectively. + Expect can be found in . Julia Menapace first coined the term ``&dj;'' to describe an earlier testing framework she had written at Cygnus Support for testing GDB. 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. There are several advantages to testing with &dj;: @@ -210,7 +212,8 @@ into another language, under the above conditions for modified versions. not based on Expect. Expect scripts use .exp as a filename extension as a - convention. + convention. Testsuites are typically kept in the source tree of + the programs that they test. @@ -269,10 +272,10 @@ into another language, under the above conditions for modified versions. Design Goals - &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: + &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: was useful to developers while fixing @@ -299,10 +302,10 @@ into another language, under the above conditions for modified versions. 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 rsh, rlogin, @@ -475,93 +478,54 @@ into another language, under the above conditions for modified versions. Installation - 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. + 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. Configuring DejaGnu - It is usually best to configure in a directory separate from the - source tree, specifying where to find the source with the optional - --srcdir option to - configure. DejaGnu uses the GNU - autoconf to configure itself. For more info on using - autoconf, read the GNU autoconf manual. To configure, execute the - configure 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: + It is usually best to configure &dj; in a different + directory than the source tree. To configure from a sibling + build directory, execute the configure + script from the source tree like this: ../dejagnu-&version/configure - 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. + 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. - You may also want to use the configure option - --prefix to specify where you want DejaGnu and its - supporting code installed. By default, installation is in subdirectories - of /usr/local, but you can select any alternate - directory altdir by including + You may wish to use the configure + option --prefix to specify where you want + DejaGnu installed. The default installation prefix is under + /usr/local, but you can select any + alternate directory altdir by including {altdir}} on the - configure command line. (This value is captured in - the Makefile variables prefix and - execprefix}.) - - 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 make check to build - auxiliary programs required by some of the tests, and run the test - suites. + configure command line. - + DejaGnu includes a small testsuite of own, but it does not + include other testsuites; these are typically available with the + packages that they test. Installing DejaGnu - To install DejaGnu in your filesystem (either in - /usr/local, or as specified by your - --prefix option to configure), - execute. + Once a build directory is configured, installing &dj; is a + simple matter of running: - eg$ make install + $ make install - make installdoes thes things for - DejaGnu: - - - Look in the path specified for executables - $exec_prefix) for directories called - lib and bin. If these - directories do not exist, make install creates - them. - - Create another directory in the - share directory, called - dejagnu, and copy all the library files into - it. - - Create a directory in the - dejagnu/share directory, called - config, and copy all the configuration files into - it. - - Copy the runtest shell script into - $exec_prefix/bin. - - Copy runtest.exp into - $exec_prefix/lib/dejagnu. This is the main Tcl - code implementing DejaGnu. - - - + The make install output will show what + was installed where, but the most important installation step to + note is that the runtest command is + installed into the $prefix/bin directory. + This program is the driver for &dj;. + 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 @@ Running Tests - There are two ways to execute a testsuite. The most common - way is to rely upon support in a Makefile for - a check target. The other way is to execute - the runtest program directly. To run - runtest directcly from the command line - requires either all the correct options, or the must be setup correctly. Automake can generate a - Makefile that does all of the right things - when the user invokes make check and is the - preferred approach. Both ways of executing a testsuite will be - covered in more detail below. + There are two ways to run a testsuite. The most common way + is to rely on Makefile support for a + check target. The other way is to invoke the + runtest program directly. To invoke + runtest from the command line requires either + much care to be taken to ensure that all of the correct options + are given or that the is set up correctly. + Automake can help to produce a Makefile that + does the right things when the user invokes make + check and this is the preferred approach. Both ways of + executing a testsuite will be covered in more detail below. make check @@ -746,15 +746,16 @@ Tutorial -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. - -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. + +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. + +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. Test your installation -- cgit v1.1