README: Add more comment.

2001-01-28  Gabriel Dos Reis  <gdr@codesourcery.com>

        * testsuite/README: Add more comment.
        * testsuite/lib/libstdc++.exp: Tweak comment.

From-SVN: r39321

libstdc++-v3/ChangeLog

+2001-01-28  Gabriel Dos Reis  <gdr@codesourcery.com>
+
+	* testsuite/README: Add more comment.
+	* testsuite/lib/libstdc++.exp: Tweak comment.
+
 2001-01-26  Benjamin Kosnik  <bkoz@kredhat.com>
 
 	* libsupc++/pure.cc (writestr): Just use cstdio and std::fputs.

libstdc++-v3/testsuite/README

@@ -3,8 +3,8 @@ use the new style DejaGnu framework.  Eventually, we'll abandon
 ../mkcheck.in in favor of this new testsuite framework.  
 
   Basically, a testcase contains dg-keywords (see dg.exp) indicating
-what to do and what kind of behaviour are to be expected.  New
-testsuite should be written with the new style DejaGnu framework in mind.
+what to do and what kinds of behaviour are to be expected.  New
+testcases should be written with the new style DejaGnu framework in mind.
 
   The V3 testing framework supports additional keywords for the purpose
 of easing the job of writing testcases.  All V3-keywords are of the
@@ -21,5 +21,9 @@ form @xxx@.  Currently supported keywords include:
 	   // @require@ %-*.tst %-*.txt
 
   @diff@ <first-list> <second-list>
+      After the testcase compiles and ran successfully, diff
+      <first-list> against <second-list>, these lists should have the
+      same length.  The test fails if diff returns non-zero a pair of
+      files.
 
 -- Gaby

libstdc++-v3/testsuite/lib/libstdc++.exp

@@ -19,22 +19,26 @@
 #
 # This file is contributed by Gabriel Dos Reis <gdr@codesourcery.com>
 
-## This file contains support routines for dg.exp-based testsuite
+## This file contains support routines for dg.exp based testsuite
 ## framework.
 
 ## The global associative array lib_env contains the totality
 ## of options necessary to run testcases; the meanings of which are
 ## as follows:
-##    lib_env(CXX):  The compiler used to run testcases
-##    lib_env(CXXFLAGS): Special flags passed to the compiler
-##    lib_env(INCLUDES):
-##    lib_env(LDFLAGS): Additional library flags 
-##    lib_env(LIBTOOL):
-##    lib_env(SRC_DIR):
-##    lib_env(BUILD_DIR):
-##    lib_env(static):
-##    lib_env(shared):
-##    lib_env(testcase_options):
+##    lib_env(CXX)       The compiler used to run testcases.
+##    lib_env(CXXFLAGS)  Special flags passed to the compiler.
+##    lib_env(INCLUDES)  Includes options to pass to the compiler.
+##    lib_env(LDFLAGS)   Additional library flags.
+##    lib_env(LIBTOOL)   Path to the `libtool' script.
+##    lib_env(SRC_DIR)   Where V3 master source lives.
+##    lib_env(BUILD_DIR) Where V3 is built.
+##    lib_env(static)    Flags to pass to the linker to build a 
+##                       statically linked executable.
+##    lib_env(shared)    Flags to pass to the linker to build a 
+##                       dynamically linked executable.
+##    lib_env(testcase_options) Options specified by current testcase.
+##                       These are specified through the @xxx@-keywords.
+
 
 load_lib dg.exp
 
@@ -55,8 +59,7 @@ proc libstdc++-dg-init { args } {
     # Set proper environment variables for the framework.
     libstdc++-setup-flags ${src-dir} ${build-dir}
     
-    # mkcheck.in used to output these information.  Maybe we should
-    # abandon that practice.
+    # mkcheck.in used to output these information.
     set output [remote_exec host $lib_env(CXX) -v]
     if { [lindex $output 0] == 0 } {
 	set output [lindex $output 1]
@@ -69,14 +72,17 @@ proc libstdc++-dg-init { args } {
     }
 }
 
-## dg.exp callback.  Called from dg-test to run PROGRAM images.
+## dg.exp callback.  Called from dg-test to run PROGRAM.
+##
+## This is the heart of the framework.  For the time being, it is
+## pretty much baroque, but it will improve as time goes.
 proc libstdc++_load { prog } {
     global lib_env
     set opts $lib_env(testcase_options)
     set results [remote_load target $lib_env(LIBTOOL) "--mode=execute $prog"]
 
     if { [lindex $results 0] == "pass" && [info exists opts(diff)] } {
-	# FIXME: We should first test for any mentioned output file here
+	# FIXME: We should first test for any mentioned @output@ file here
 	#        before taking any other action.
 
 	set firsts [glob -nocomplain [lindex $opts(diff) 0]]
@@ -84,7 +90,7 @@ proc libstdc++_load { prog } {
 	foreach f $firsts s $seconds {
 	    if { [diff $f $s] == 0 } {
 		# FIXME: Well we should report a message.  But for the time
-		#        being, just pretend, there is nothing much to say.
+		#        being, just pretend there is nothing much to say.
 		#        Yes, that is silly, I know.  But we need, first, to
 		#        to have a working framework.
 		break
@@ -129,20 +135,20 @@ proc libstdc++_runtest { testdirs } {
 	    continue
 	}
 	
-	# Make the appropriate test-dirs with accompaning .libs/
+	# Make the appropriate test-dirs with related .libs/ subdir
 	# to keep libtool happy.
 	set td "$outdir/[dg-trim-dirname $srcdir $d]"
 	maybe-make-directory $td
 	maybe-make-directory $td/.libs
-	cd $td;
 
+	cd $td;
 	foreach testfile $testfiles {
-	    # We're not supposed to test this file, just skip it.
+	    # If we're not supposed to test this file, just skip it.
 	    if ![runtest_file_p $runtests $testfile] {
 		continue
 	    }
 	    
-	    verbose "Testing [dg-trim-dirname $srcdir $testfile]"
+#	    verbose "Testing [dg-trim-dirname $srcdir $testfile]"
 	    libstdc++_do_test $testfile static
 	    libstdc++_do_test $testfile shared
 	}
@@ -155,10 +161,8 @@ proc libstdc++_runtest { testdirs } {
 ##
 ## TESTCASE is the file-name of the program to test;
 ## COMPILE_TYPE is the kind of compilation to apply to TESTCASE; 
-##              current compilation kinds are: preprocessing(preprocess),
-##              compiling-only-no-assembling-nor-linking(compile),
-##              compiling-and-assmbling-no-linking(assemble),
-##              linking-no-running(link), running(run).
+##              current compilation kinds are: preprocess, compile,
+##              assemble, link, run.
 proc libstdc++-dg-test { testfile compile_type additional-options } {
     global srcdir; global outdir
     global lib_env
@@ -167,7 +171,7 @@ proc libstdc++-dg-test { testfile compile_type additional-options } {
     # Prepare for compilation output
     set comp_output ""
 
-    # By default, we want to use libtool to run tests.
+    # By default, we want to use libtool to compile and run tests.
     set lt $lib_env(LIBTOOL)
     set lt_args "--tag=CXX"
     
@@ -188,7 +192,7 @@ proc libstdc++-dg-test { testfile compile_type additional-options } {
 	"run" -
 	"link" {
 	    # If we're asked to run a testcase, then just do a `link'.
-	    # The framework will load the program image latter through
+	    # Later, the framework will load the program image through
 	    # libstdc++_load callback.
 	    if { $which_library == "static" } {
 		append output_file ".st-exe"
@@ -240,8 +244,7 @@ proc libstdc++-setup-flags {src-dir build-dir} {
 	set lib_env(FLAGS) "$lib_env(CXX) -B$lib_env(BUILD_DIR)/ \
 		$lib_env(INCLUDES) $lib_env(CXXFLAGS)"
     } else {
-	warning "$output"
-	exit $status
+	perror "$output"
     }
 }
 
@@ -253,6 +256,7 @@ proc maybe-make-directory {dir} {
 
 proc libstdc++_do_test { testfile lib } {
     global which_library; set which_library $lib
+    ## Is it planed to handle -keep-output throught @xxx@-option
     dg-test -keep-output $testfile "" ""
 }