Initial revision

1 files changed, 283 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..0e22eab
--- /dev/null
+++ b/README
@@ -0,0 +1,283 @@
+  DejaGnu is a framework for testing other programs. Its purpose is to
+provide a single front end for all tests.  Beyond this, DejaGnu offers
+several advantages for testing:
+
+        - The flexibility and consistency of the DejaGnu framework
+          make it easy to write tests for any program.
+
+        - DejaGnu provides a layer of abstraction which makes all
+          tests (if correctly written) portable to any host or target
+          where a program must be tested.  For instance, a test for
+          GDB can run (from any Unix based host) on any target
+          architecture supported by DejaGnu. Currently DejaGnu runs
+          tests on several single board computers, whose operating
+          software ranges from just a boot monitor to a full-fledged,
+          Unix-like realtime OS.
+
+        - DejaGnu is written in expect, which in turn uses Tcl
+          (Tool command language).  The framework comprises two parts:
+          the testing framework and the testsuites themselves. Tests
+          are usually written in expect using Tcl.
+
+  Bugs can be reported to bug-dejagnu@prep.ai.mit.edu.
+
+ 		      How To Configure and Build
+
+ To build DejaGnu, run the ``configure'' script here, e.g.:
+
+        ./configure MYHOSTTYPE
+
+followed by running ``make''.  (MYHOSTTYPE is a name for your host computer,
+for instance "sun4".  You can use the script ``config.sub'' to test whether
+a name is recognized; if it is, config.sub translates it to a triplet 
+specifying CPU, vendor, and OS.) This is used when you plan to
+configure and build in the source tree.
+
+  If you use a separate tree for object files, (the recommended way),
+then the --srcdir option must also be specified. This would also
+require that the configure script be run from the top level directory.
+
+	PATH/configure MYHOSTYPE --srcdir PATH/dejagnu
+
+where PATH is is the directory that the contains the sources.
+
+  To configure it so it gets installed somewhere other than the
+default of /usr/local, use the --prefix option.
+	
+	configure MYHOSTYPE --prefix [PATH]
+
+where PATH is the prefix used to install the programs. 
+
+  The configure testing and building will use the native compiler "cc"
+on your host machine. To change which compiler gets used (like gcc)
+set a the variable "CC" in your environment to point to it. 
+	
+	For csh users:		"setenv CC gcc"
+	For bourne shell users:	"CC=gcc;export CC"
+
+  Then when you compile, use "make CC=$CC". 
+
+See etc/cfg-paper.texi, etc/configure.texi, and/or the README files in
+various subdirectories, for more details. 
+
+ As DejaGnu is a Tcl program, there is nothing to build. However, the
+documentation is not built by default. Use these targets:
+"make info"	- Convert the texinfo document to something that can
+		  be used the GNU info program or info mode in emacs.
+"make dvi"	- Convert the texinfo document to something that can
+		  be printed. This produces dvi output.
+"make doc"	- This builds both.
+"make ps"	- This converts the dvi file into postscript. This
+		  requires a copy of dvips.
+"make install"	- This installs DejaGnu based on the --prefix option
+		  when configuring. Otherwise it defaults to
+		  /usr/local. See the DejaGnu manual for more
+		  information on installation.
+
+			  Changes from 1.1.1
+	1. Works with (included in release) Tcl 7.3 and Expect 5.6.
+	2. Much better error trapping and handling, including the
+	   execution of sub scripts.
+	3. Re-worked configuration subsystem.
+	4. Default handling for testing unknown targets.
+	5. New testsuite for expect and runtest.
+	6. More debugging procedures.
+
+                          Changes from 1.0
+
+	1. DejaGnu now conforms to POSIX 1003.3, a standard for
+	   testing frameworks.
+	2. A Tcl debugger written by Don Libes has been added.
+	3. Lots of bug fixes.
+
+                          Changes from 0.9
+
+        1. DejaGnu now installs itself like other utilities.
+        2. 700 G++ tests are included.
+        3. The bugs in the GCC tests have been fixed.
+        4. Testsuites are released separately.
+        5. Testsuite sources now reside with the within each tool's
+           source tree. 
+
+-------------------------------------------------------------------
+Here's is a posting on the Free OS testing project. (FROST)
+-------------------------------------------------------------------
+If you have built up your own tests for system calls, library
+routines, networking protocols, or common utilities, this posting
+offers you an opportunity to put them to good use.  You can do a good
+deed for the Linux community, the Berkeley UNIX community, and the
+wider world of free software users.
+
+Also, if you would like to learn some good test tools and strategies,
+and devote some time on a volunteer basis to writing tests -- perhaps
+a couple of weeks full-time, or a couple hours per week over a period
+of several months -- then here is a project you should get involved
+in.
+
+I am helping to coordinate a test effort for Linux.  In the following
+four sections of this message I will describe the goals, the process,
+the people trying to do it, and what you can do to help.
+
+Goals
+
+  Linux and BSD share a number of libraries and utilities, both
+  because BSD software was ported to Linux, and because several free
+  software (GNU) utilities have been ported to both operating
+  systems.
+
+  Linux shows startling differences and failures as you move from one
+  set of hardware to another.  People who hope to base their own
+  commercial products on Linux would like to see proof that it is
+  robust, portable, and standard-conforming.  The problem is that
+  cross-platform testing is very hard to do, and few decent test
+  suites exist either for free software or for UNIX.  (Look at all the
+  differences you find among systems that are SVID-conforming,
+  particularly at higher levels such as the utilities.)
+
+  Therefore, a number of us who are interested n Linux have decided to
+  enter the modern age of formal, automated software testing -- but in
+  a manner that is proper for the free software community.
+
+  Using DejaGnu, a test platform developed by Cygnus Support and
+  placed under the GPL, we want to collect the best tests we can from
+  people everywhere, and integrate them into suites that any user can
+  download, run, and interpret with a few commands.  DejaGnu already
+  runs under BSD, and Cygnus is porting it to Linux.
+
+  Our goal is to test as many parts of the system as possible,
+  including system calls (particularly for POSIX 1003.1 compliance),
+  libraries in the official distribution, networking protocols,
+  and utilities.  We need help with
+
+    1) integrating good tests donated by the community (and probably
+       written in a variety of programming languages and command
+       shells) into the DejaGnu framework, and
+
+    2) writing new tests for major functional areas for which no
+       adequate tests exist.
+
+  The tests we use will be placed under the GPL and distributed by
+  Cygnus Support along with DejaGnu.  H. J. Lu, who maintains the C
+  library for Linux, has offered to run the POSIX 1003.1 tests and as
+  many others as he can.
+
+Process
+
+  First let me summarize the advantages of using DejaGnu, a free
+  software product that will be the umbrella for all the tests, and
+  then explain how we plan to conduct this project.
+
+  Cygnus Support released DejaGnu to the public on January 3, along
+  with several test suites for GNU language tools.  The product is
+  designed for portability and easy cross-platform development and
+  execution.  It works more uniformly than typical tests using the
+  UNIX shell, and also supports interactive testing better than most
+  test platforms -- for instance, Cygnus has written over 1300 unit
+  tests for the gdb debugger using it.
+
+  The implementation of DejaGnu is based on tcl and expect, two simple
+  existing languages for writing commands.  You can develop new tests
+  in two major ways: by placing keyword-based comments in C source
+  code, or by writing tests in tcl.
+
+  While Cygnus is still increasing their body of tests for language
+  tools, they are also turning their resources toward the libraries
+  and GNU utilities.  While most of the tests are written at Cygnus,
+  they have reached out to communities of testers and are now porting
+  substantial sets of donated tests.
+
+  We are hoping to broaden this successful use of collaboration across
+  user communities.  We hope that suites of useful tests are sitting
+  in desk drawers out there.  We also hope to gather and mobilize
+  people who appreciate the value of formal tests in legitimizing free
+  software, and would like to help write them.
+
+  I am not an employee of Cygnus, but have volunteered to talk to
+  interested people and do an initial classification of tests, just to
+  offload some of this routine work from them.  I will discuss all
+  offers with Cygnus staff to find out what is most needed and decide
+  which tests to incorporate into DejaGnu.  There are several criteria
+  for choosing tests, including the degree to which an area is
+  covered, and its importance in the overall stability of the
+  operating system.  Some tests may have to be rejected just because
+  they are hard to fit into the DejaGnu model.
+
+People
+
+  Now you can find out why each of us got involved with this project.
+
+  Cygnus writes and distributes free software, selling support as a
+  means to make money.  The company is not directly in the business of
+  supporting operating systems or common UNIX utilities, so this kind
+  of testing is tangential to their main goals.  But they may want to
+  support those things in the future.  In any case, they would like to
+  see Linux do well, and this big test project will be a good
+  promotion for DejaGnu.
+  H. K. Lu, as a volunteer for Linux, has been using his own system to
+  implement, port, maintain, and ensure ANSI and POSIX compliance for
+  the C library (mostly the GNU C library along with the iostream
+  class from the g++ library).  He is looking for ways to validate the
+  work that he and many other contributors have put in.
+
+  As an editor at a publisher of computer books, my relationship to
+  Linux and BSD is even more distant than that of Cygnus.  But we are
+  thinking about putting out books about Linux, from either the Linux
+  Documentation Project or independent authors, and would like to make
+  sure Linux is stable enough to be documented.  The testing of
+  utilities is particularly important to me, because it can provide
+  quality assurance for our books, including the BSD version of UNIX
+  in a Nutshell.
+
+What you can do
+
+  We ask people who have written tests in the areas I have described
+  to donate them to this project and see them benefit the public.
+  Don't just send me stuff -- write or call to discuss what you've got
+  in general.  You also have to assign the tests to the Free Software
+  Foundation (a simple matter, so long as you are the owner of the
+  tests) so that they can be distributed under the GPL.
+
+  Also, please don't starting flaming about the GPL.  Either join our
+  project and donate your tests, or don't.  Personally, I do not take
+  a side in this war.
+
+  People who are interested in testing as a discipline, and have some
+  time to donate, are invited to contact me to help write tests.  Tell
+  me:
+
+        Your knowledge of computer languages and tools
+
+        Previous software test efforts you have engaged in, if any
+
+        How much time you can devote
+
+        What functional areas you think are important and have a
+        particular interest in
+
+  Cygnus staff will tell volunteers which areas need testing, and
+  offer guidance while you learn and apply DejaGnu.  The most
+  important trait for the project is rigorous thinking along the lines
+  of software quality (so the best preparation is to have done some
+  formal testing before).  You do not need to know any particular
+  language or tool; you can learn tcl or other aspects of DejaGnu
+  fairly quickly.
+
+  Contact information for me is in my signature.  I am at the phone
+  number during traditional U.S. business hours.  So send mail any
+  time, or try calling from Monday through Friday, 9:00 AM to 5:00 PM,
+  Eastern Daylight Saving Time (four hours later than Greenwich Mean
+  Time).
+
+  Feel free to distribute and repost this message elsewhere, in its
+  entirety.
+
+----------------------------------------------------------------------
+Andy Oram    O'Reilly & Associates, Inc.                 andyo@ora.com
+             90 Sherman Street, Cambridge, MA 02140     (617) 354-5800
+                                                    fax (617) 661-1116
+----------------------------------------------------------------------
+
+There is a new listserv based mailing list for the FROST project. To
+subscribe, send email to "listserv@cygnus.com" and the body should
+contain "SUBSCRIBE FROST <your name>". Messages sent to
+frost@cygnus.com go to the mailing list.
\ No newline at end of file