From 2b5aa5e2525fef36335502eb37462c1ceb93e43d Mon Sep 17 00:00:00 2001
From: Damien Lespiau <damien.lespiau@gmail.com>
Date: Fri, 29 Jun 2007 01:18:12 +0200
Subject: [PATCH] test-suite documentation

A quick description of test-suite usage.

Signed-off-by: Damien Lespiau <damien.lespiau@gmail.com>
---
 Documentation/test-suite |  113 ++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 113 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/test-suite

diff --git a/Documentation/test-suite b/Documentation/test-suite
new file mode 100644
index 0000000..b6ef22c
--- /dev/null
+++ b/Documentation/test-suite
@@ -0,0 +1,113 @@
+
+
+	Sparse test suite
+	~~~~~~~~~~~~~~~~~
+
+Sparse has a number of test cases in its validation directory. The test-suite
+script aims at making automated checking of these tests possible. It works by
+embedding tags in C comments in the test cases.
+
+check-name: (mandatory)
+	Name of the test.
+
+check-description: (optional)
+	A description of what checks the test.
+
+check-command: (optional)
+	There are different kinds of tests. Some can validate sparse
+	preprocessor while others will use sparse, cgcc of even other backends
+	of the library. check-command allows you to give a custom command to
+	run the test-case.
+	The '$file' string is special. It will be expanded to the file name at
+	run time.
+	It defaults to "sparse $file".
+
+check-exit-value: (optional)
+	The expected exit value of check-command. It defaults to 0.
+
+check-output: (optional)
+	The expected output (stdout and stderr) of check-command. It defaults
+	to no output.
+
+check-known-to-fail (optional)
+	Mark the test as being known to fail.
+
+
+	Using test-suite
+	~~~~~~~~~~~~~~~~
+
+The test-suite script is called trough the check target of the Makefile. It
+will try to check every test case it finds (find validation -name '*.c').
+It can be called to check a single test with:
+
+$ cd validation
+$ ./test-suite single preprocessor1.c
+    TEST  Preprocessor 1 (preprocessor1.c)
+preprocessor1.c passed !
+
+
+	Writing a test
+	~~~~~~~~~~~~~~
+
+test-suite comes with the format command to make a test easier to write:
+
+	test-suite format file [name [cmd]]
+
+name:
+	check-name value. If no name is provided, it defaults to the file name.
+cmd:
+	check-command value. It no cmd if provided, it defaults to
+	"sparse $file".
+
+The output of the test-suite format command can be redirected into the
+test case to create a test-suite formated file.
+
+$ ./test-suite format bad-assignment.c Assignement >> bad-assignment.c
+$ cat !$
+cat bad-assignment.c
+static int foo(int a)
+{
+        a |=\1;
+
+        return a;
+}
+/*
+ * check-name: Assignement
+ *
+ * check-command: sparse $file
+ * check-exit-value: 0
+ *
+ * check-output:bad-assignment.c:3:6: error: Expected ; at end of statement
+ * check-output:bad-assignment.c:3:6: error: got \
+ */
+
+You can define the check-command you want to use for the test. $file will be
+extended to the file name at run time.
+
+$ ./test-suite format preprocessor2.c "Preprocessor 2" \
+		"sparse -E \$file" >> preprocessor2.c
+$ cat !$
+/*
+ * This one we happen to get right.
+ *
+ * It should result in a simple
+ *
+ *      a + b
+ *
+ * for a proper preprocessor.
+ */
+#define TWO a, b
+
+#define UNARY(x) BINARY(x)
+#define BINARY(x, y) x + y
+
+UNARY(TWO)
+/*
+ * check-name: Preprocessor 2
+ *
+ * check-command: sparse -E $file
+ * check-exit-value: 0
+ *
+ * check-output:
+ * check-output:a + b
+ */
-- 
1.5.2.1.280.g38570