Add additional tests to provide more examples.

1 files changed, 71 insertions, 0 deletions

diff --git a/test/README b/test/README
new file mode 100644
index 00000000..4834f5bb
--- /dev/null
+++ b/test/README
@@ -0,0 +1,71 @@
+This directory contains our end-to-end SCons tests.
+
+They are all meant to be run essentially standalone, with the exception
+of the TestSCons.py module (and the TestCmd.py module it imports) that
+is imported by each test.  These modules are in the etc/ subdirectory,
+and PYTHONPATH needs to be set up correctly so that the test script can
+find them, and so that the SCons script itself can find the build engine
+modules.
+
+There is a wrapper script, runtest.py, that takes care of this for you,
+so the canonical invocation of a test is:
+
+	python runtest.py test/option-x.py
+
+There is also a "runtest.py -a" option that will search the tree for
+all tests, and execute them.
+
+Many of these tests have code for features that are not yet supported,
+but which will be part of SCons IN THE CURRENT PLANNED RELEASE.  These
+are either:
+
+	commented out with a "#XXX" at the beginning of the line;
+
+	short-circuited entirely by having the test pass via an
+	early call to test.pass_test(), which has a "#XXX" comment
+	at the end of the line
+
+The upshot is that you should be able to:
+
+	egrep -l '#XXX' test/*.c
+
+and see a list of the tests we still have to make work in order to get
+the next release out the door.
+
+If you're trying to implement one of these features, DO NOT BLINDLY
+ASSUME THAT THE NEW CODE IN THE TEST IS CORRECT.  It may have problems
+that have gone undiscovered due to the fact that the code testing the
+future feature couldn't be run yet!
+
+We're not going to be dogmatic about it, but so that there's some
+semblance of uniformity, here are the naming conventions for tests:
+
+    --	All tests end with a .py suffix.
+
+    --	General form:
+
+    		Feature.py	test of specified feature; try to
+				keep this description reasonably
+				short
+
+		Feature-01.py	additional tests of specified
+		Feature-02.py	feature
+		Feature-03.py
+
+    		Feature-x.py	test of specified feature using
+				option x
+
+		Feature-x-01.py	additional tests of specified
+		Feature-x-02.py	feature using option x
+		Feature-x-03.py
+
+    --	Command line option tests take the form:
+
+    		option-x.py	lower-case single-letter option
+
+		option--X.py	upper-case single-letter option
+				(extra hyphen so the file names will
+				be unique on case-insensitive systems)
+
+		option--lo.py	long option; abbreviate the long
+				option name to a few characters