Adding tests to the testsuite
-----------------------------

The Guile test cases are divided up into several directories.  Some
directories are for testing optional features of Guile, such as
threads. Others are separated out for historical reasons, such as the
guile.scm directory that contains the SLIB tests.

Many directories are configured to run test cases in special ways,
meaning that tests must be carefully configured before adding them to
the testsuite. What follows is a discussion on how to add tests to the
various test directories.

guile.builtin

	This directory contains tests for various "builtin" Guile
	functions. Many of the tests were derived from stubs that were 
	generated automatically from the Guile source code. The
	builtin tests all use the dg.exp extension to DejaGnu. Please
	read the dg.exp documentation for details.

	Here is a sample test from guile.builtin:

	---- cut here ------------------------------------------------------
	; $Id: README,v 1.1.1.1 2003/02/18 20:59:35 green Exp $ 

	; { dg-output "3;7;7;0;done" }

	;; required: 3
	;; optional: 0
	;; rest    : 0

	(define (put n)
	  (display n)
	  (display ";"))

	(put (bit-extract 7 1 4))
	(put (bit-extract 7 0 3))
	(put (bit-extract 7 0 4))
	(put (bit-extract 7 4 32))

	(display 'done)
	---- cut here ------------------------------------------------------

	Before running the test, DejaGnu greps the file for the comment:
	
	; { dg-output STRING }
	
	The output from the test must match STRING in the above comment.
	
	If you expect the test to fail on all platforms, change
	the comment to:
	
	; { dg-output STRING { xfail *-*-* } }
	
	The dg.exp documentation has more details on these comment strings.
	
	Once Guile has been changed to make a test case expected to fail 
	pass, remove the "xfail" clause.

guile.gscm

	Each test case in this consists of a C source file and a
	corresponding output file. The output file must have the same
	name as the C file, but end in ".out" rather than ".c". The
	test framework compiles the C source code, links it with libguile,
	runs it, and compares the output with the output file. If it 
	is the same, the test passes. It fails otherwise. If the C source
	contains the text "PASSES", DejaGnu will expect the test case to
	pass, otherwise it will expect a failure. If the C source 
	doesn't build, then the test is considered to fail.

	Here is a sample gscm test, called init.c:

	---- cut here ------------------------------------------------------
	/* This test PASSES - Wed Aug 14 11:25:45 PDT 1996 - green */
	
	#include <stdio.h>
	#include "libguile.h"
	
	static GSCM_status guile_init()
	{
	  puts("Called guile_init()");
	}
	
	/* Force a "quiet" start */
	int argc = 2;
	char *argv[] = {"/tmp/a.out", "-q", NULL};
	
	int main()
	{
	  SCM status;
	
	  status = gscm_run_scm(argc, argv, 0, stdout, stderr, 
				guile_init, 0, "#t");
	
	  if (status != GSCM_OK) 
	    {
	      fputs(gscm_error_msg(status), stderr);
	      fputc('\n', stderr);
	      exit(1);
	    }
	  else
	    puts ("Success");
	
	  exit(0);
	}
	---- cut here ------------------------------------------------------

	And here is the corresponding output file, called init.out:

	---- cut here ------------------------------------------------------
	Called guile_init()
	Success
	---- cut here ------------------------------------------------------

guile.i18n

	This directory contains tests for the internationalization features
	of Guile. This directory contains tests run by various drivers.
	Each driver is an expect program that ends in ".exp".

	When dg-runtest (from dg.exp) executes a Guile test, it does 
	so by invoking a special script called run-test.scm. 
	This script handles special command line arguments for the
	main Guile program. The two main options are -f and -p. If -f is
	specified, it must be followed by the name of a feature in 
	Guile's *feature* list. For instance, in the i18n directory,
	run-test.scm is called with -fi18n. If the feature specified is
	not in *features* DejaGnu notes the test case as unsupported.
	The -p switch must specify the source directory for the tests
	being executed. All of the dg.exp style tests in guile.i18n
	are executed with "-fi18n -p $srcdir/$subdir" as the flags for
	dg-runtest.

	The test cases that use dg.exp follow the same scheme as is
	described above for guile.builtin.

	Some tests use the Tcl function guile_test. It is best not
	to write test cases that use the guile_test function. Use
	the dg.exp functions instead.

guile.scm

	This directory contains the SLIB test code. Several of the tests
	have been commented out, because they fail under Guile for
	good reason. Do not add tests to this directory.

guile.simple

	This directory contains simple test cases used to test the
	testing framework. Do not add tests to this directory.

guile.threads

	This directory contains tests for the multi-threading features
	of Guile. It is only executed when the Guile build being
	tested has been configured for threads, using the scheme described
	above for guile.i18n. This directory uses dg.exp as is described
	above for guile.builtin.


