# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1484085646 -3600
# Node ID bd484709f70de7ee887aee8148c1fe545e341319
# Parent  aebbc02d5dfe5cdc2d9699ddcefb659051288e3c
Added help text and reordered some statements.

diff -r aebbc02d5dfe -r bd484709f70d test_all.sh
--- a/test_all.sh	Tue Jan 10 21:41:46 2017 +0100
+++ b/test_all.sh	Tue Jan 10 23:00:46 2017 +0100
@@ -1,7 +1,29 @@
 #!/bin/sh
 
+# This tool runs the toolchain for each of the tests, optionally building and
+# running the test programs.
+#
+# Copyright (C) 2016 Paul Boddie <paul@boddie.org.uk>
+#
+# This program is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3 of the License, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+# details.
+#
+# You should have received a copy of the GNU General Public License along with
+# this program.  If not, see <http://www.gnu.org/licenses/>.
+
+PROGNAME=$0
+OPTION=$1
+
 LPLC="./lplc"
 DATADIR="_lplc"
+TESTINPUT="_results/testinput.txt"
 
 # Expect failure from the "bad" tests.
 
@@ -27,19 +49,46 @@
 
 # Main program.
 
-OPTION=$1
-TESTINPUT="_results/testinput.txt"
+# Show help if requested.
+
+if [ "$OPTION" = '--help' ] ; then
+    cat 1>&2 <<EOF
+Usage: $0 [ --build | --build-only | --run-built ]
+
+Run the toolchain over all tests in the tests directory.
 
-# Make any required results directory.
+If --build is specified, the generated program code will be compiled and run,
+with the results collected in the _results directory.
+
+If --build-only is specified, the generated programs themselves will be
+collected in the _results directory, each taking their name from that of the
+main program file used as input.
+
+If --run-built is specified, any generated programs in the _results directory
+will be run and their output collected in the _results directory.
 
-if [ "$OPTION" = '--build' ] || [ "$OPTION" = '--build-only' ] ; then
-    if [ ! -e "_results" ]; then
-        mkdir "_results"
-    else
-        rm "_results/"*
-    fi
+By using --build-only on one system, copying the _results directory to another
+system, and then running this script with the --run-built option on the other
+system, it becomes possible to test the toolchain output on the other system
+without needing to actually use the toolchain on that system. This permits the
+testing of cross-compiled programs.
+
+For example, to build on one system but not run the generated programs:
+
+ARCH=mipsel-linux-gnu $PROGNAME --build-only
 
-    cp "tests/testinput.txt" "$TESTINPUT"
+And to run the generated programs on another system:
+
+$PROGNAME --run-built
+
+Of course, this script will need to be copied to the target system if it is not
+already available there.
+
+Build and output logs are stored in the _results directory with the .build and
+.out suffixes employed respectively, one of each kind for each generated
+program.
+EOF
+    exit 1
 fi
 
 # If just running existing programs, do so now and exit.
@@ -66,6 +115,18 @@
     exit 0
 fi
 
+# Make any required results directory.
+
+if [ "$OPTION" = '--build' ] || [ "$OPTION" = '--build-only' ] ; then
+    if [ ! -e "_results" ]; then
+        mkdir "_results"
+    else
+        rm "_results/"*
+    fi
+
+    cp "tests/testinput.txt" "$TESTINPUT"
+fi
+
 # Perform each test.
 
 for FILENAME in tests/* ; do