add new toplevel infrastructure

1 files changed, 71 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..fe152a3
--- /dev/null
+++ b/README
@@ -0,0 +1,71 @@
+-----------
+ For: User
+-----------
+Following make targets are available
+
+make compile
+
+This will compile and link the tests.
+
+make run
+
+This will execute all the tests.
+
+make check
+make all
+
+This will build and run tests.
+
+The following make variables may help you in testing:
+
+ - V / VERBOSE  - run tests with a lot of output
+ - TIMEOUTFACTOR=nn - increase test timeout nn times.
+
+You can pass the following 2 environment variables to "make run":
+ - make run SIMULATOR=qemu-sh4
+
+If you need to test just a subset of all test, delete subdirectories
+you do not need.
+
+----------------
+ For: Developer
+----------------
+
+The structure of this test system is:
+ test/                    toplevel dir containing common test code
+ test/Rules.mak           Common build code
+ test/Test.mak            Runtime test make code
+ test/subdir/             code specific to a subsystem is stored in a subdir
+ test/subdir/Makefile.in  describe the tests to run
+ test/subdir/Makefile     test entry point, includes needed upper-level
+                          makefiles plus Makefile.in
+ test/subdir/*.c          the tests
+
+Each subdir has a Makefile (same for any subdir) that must include in strict order:
+  - the upper-level Rules.mak file
+  - the Makefile.in
+  - the upper-level Test.mak file
+Makefile.in may be used to define the TESTS and TESTS_DISABLED variables.
+If you do not, TESTS is built automatically based upon all the .c files in the subdir.
+TESTS := foo
+TESTS_DISABLED := bar
+Each test must use a similar .c name; so the "foo" test needs a "foo.c".
+
+Additionally, the following options further control specific test behavior:
+CFLAGS_foo    := extra cflags to use to compile test
+LDFLAGS_foo   := extra ldflags to use to link test
+OPTS_foo      := extra options to pass to test
+RET_foo       := expected exit code of test; default is 0
+WRAPPER_foo   := execute stuff just before test
+
+Or to control all tests in a subdir:
+EXTRA_CLEAN   := extra files to remove in the clean target
+EXTRA_DIRS    := extra directories to remove in the clean target
+EXTRA_CFLAGS  := -DFOO
+EXTRA_LDFLAGS := -lpthread
+OPTS          :=
+WRAPPER       :=
+
+If you want to compare the output of a test with known good output, then just
+create a local file named "foo.out.good" and the output generated by the test
+"foo" will be automatically stored in "foo.out" and compared to "foo.out.good".