From: michaelh <michaelh@4a8a32a2-be11-0410-ad9d-d568d2c75423>
Date: Sun, 6 May 2001 01:49:05 +0000 (+0000)
Subject: Commented everything; added 'volatile' to the mix; removed some unneeded itermediate... 
X-Git-Url: https://git.gag.com/?a=commitdiff_plain;h=2caab0a41a838d049b3991ec7d9d99a6c422074a;p=fw%2Fsdcc

Commented everything; added 'volatile' to the mix; removed some unneeded itermediate directories.


git-svn-id: https://sdcc.svn.sourceforge.net/svnroot/sdcc/trunk/sdcc@782 4a8a32a2-be11-0410-ad9d-d568d2c75423
---

diff --git a/support/regression/Makefile b/support/regression/Makefile
index 7d83bb99..6dc26b0b 100644
--- a/support/regression/Makefile
+++ b/support/regression/Makefile
@@ -1,3 +1,20 @@
+# Test suite Makefile
+# Part of SDCC - http://sdcc.sourceforge.net/
+# Michael Hope <michaelh@juju.net.nz> 2001
+#
+# This Makefile builds and runs the test suites under tests/ for each
+# one of the supported ports located under ports/.  The test suite
+# results are summarised and individual test failures are logged.  The
+# expected result is a single line per port summarising the number of
+# failures, test points, and test cases.  The philosophy is that
+# checked in code should always pass the suite with no failures, as
+# then if there are failures then it is in the current developers code.
+#
+# Only the required suites are run.  Changing sdcc causes all to be
+# re-run.  Changing one suite causes just that to be run.  Changing
+# one of the library files should cause all to re-run
+
+# Old nores:
 # Starting at the bottom
 # Set of source test suites
 # Each source suite is processesd producing multiple device specific test suites.
@@ -6,43 +23,70 @@
 # The output from each device specific test suite derrived from a source
 # test suite are collated.
 
+# Uncomment this to show only errors and the summary.
+# Comment this out for debugging.
 .SILENT:
 
-CASES_DIR = cases
-RESULTS_DIR = results
+# All original tests live in TESTS_DIR and below
 TESTS_DIR = tests
+# All suite results go in RESULTS_DIR
+RESULTS_DIR = results
+# All data relating to supported ports live in their own directory
+# under PORTS_DIR.
 PORTS_DIR = ports
-SUBRESULTS_DIR = subresults
 
+# Itermediate data directories
+# Directory that generated cases and the related object code go.
+CASES_DIR = gen
+
+# Script that takes a source test suite and generates the iterations
 GENERATE_CASES = generate-cases.py
 
+# Magically generate the list of configured ports to test.
+# Each directory under ports/ is used as a port name.  Each port is tested.
+# The port name must be the same as the one used in the SDCC '-mxxx' argument.
+# Each port must have a spec.mk which describes how to build the object
+# files and how to run the emulator.
 ALL_PORTS = $(filter-out CVS,$(notdir $(wildcard $(PORTS_DIR)/*)))
 
+# Test all of the ports
 test-ports:
 	for i in $(ALL_PORTS); do $(MAKE) inter-port-clean test-port PORT=$$i; done
 
+# Begin per-port rules
+# List of all of the known source test suites.
 ALL_TESTS = $(shell find $(TESTS_DIR) -name "*.c")
 
+# Intermediate directory
 PORT_CASES_DIR = $(CASES_DIR)/$(PORT)
 PORT_RESULTS_DIR = $(RESULTS_DIR)/$(PORT)
-PORT_SUBRESULTS_DIR = $(SUBRESULTS_DIR)/$(PORT)
+# Each test generates a result log file
 PORT_RESULTS = $(ALL_TESTS:$(TESTS_DIR)/%.c=$(PORT_RESULTS_DIR)/%.out)
 
-# Defaults
+# Defaults.  Override in spec.mk if required.
+# Path to SDCC
 SDCC = ../../bin/sdcc
+# Base flags.
 SDCCFLAGS = -m$(PORT)
+# Extension of object intermediate files
 OBJEXT = .o
+# Extension of files that can be run in the emulator
 EXEEXT = .bin
+# Currently unused.  Extension to append to intermediate directories.
 DIREXT = 
 
+# Only include if we're in a per-port call.
 ifdef PORT
 include $(PORTS_DIR)/$(PORT)/spec.mk
 endif
 
-.PRECIOUS: $(PORT_CASES_DIR)/% %$(OBJEXT) %$(EXEEXT) %.dir
-
 SDCCFLAGS += -Ifwk/include
 
+# List of intermediate files to keep.  Pretty much keep everything as
+# disk space is free.
+.PRECIOUS: $(PORT_CASES_DIR)/% %$(OBJEXT) %$(EXEEXT)
+
+# Rule to generate the iterations of a test suite off the soure suite.
 $(PORT_CASES_DIR)/%$(DIREXT): $(TESTS_DIR)/%.c $(GENERATE_CASES)
 	rm -rf $(CASES_DIR)/tests
 	mkdir -p $(CASES_DIR)/tests
@@ -51,34 +95,52 @@ $(PORT_CASES_DIR)/%$(DIREXT): $(TESTS_DIR)/%.c $(GENERATE_CASES)
 	cp $(CASES_DIR)/tests/*.c $@
 	touch $@
 
+# Rule linking the combined results log to all of the files in the
+# iteration directory.
 $(PORT_RESULTS_DIR)/%.out: $(PORT_CASES_DIR)/%$(DIREXT)
 	$(MAKE) iterations PORT=$(PORT) CASES=$<
 
+# Rule to summaries the results for one port after all of the tests
+# have been run.
 port-results: port-dirs $(PORT_RESULTS)
 	echo Summary for \'$(PORT)\': `cat $(PORT_RESULTS) | python collate-results.py`
 
 port-dirs:
-	mkdir -p $(PORT_CASES_DIR) $(PORT_RESULTS_DIR) $(PORT_SUBRESULTS_DIR)
+	mkdir -p $(PORT_CASES_DIR) $(PORT_RESULTS_DIR)
 
 test-port: port-results
 
+# Begin rules that process each iteration generated from the source
+# test
+
+# List of all of the generated iteration source files.
 SUB_CASES = $(wildcard $(CASES)/*.c)
-SUB_RESULTS = $(SUB_CASES:$(PORT_CASES_DIR)/%.c=$(PORT_SUBRESULTS_DIR)/%.out)
+# List of all the sub result logs generated from the iterations.
+SUB_RESULTS = $(SUB_CASES:%.c=%.out)
+# Overall target.  Concatenation of all of the sub results.
 RESULTS = $(CASES:$(CASES_DIR)/%$(DIREXT)=$(RESULTS_DIR)/%.out)
 
 iterations: $(RESULTS)
 
+# Rule to generate the overall target from the sub results.
 $(RESULTS): $(SUB_RESULTS)
 	cat $(SUB_RESULTS) > $@
 
-#$(PORT_CASES_DIR)/%.bin: $(PORT_CASES_DIR)/%.c
+# The remainder of the rules are in $PORT/spec.mak.  The port needs to
+# be able to turn an iterated test suite into a sub result, normally
+# by:
+#    1. Compile the required library files
+#    2. Compile this test suite.
+#    3. Link 1, 2, and any required stdlib into an executable.
+#    4. Run the executable inside an emulator, and capture the text
+#    output into %.out.
+#
+# The emulator must exit when main() returns.
 
-#$(PORT_CASES_DIR)/%.o: $(PORT_CASES_DIR)/%.c
+# BeginGeneric rules
 
 clean:
-	rm -rf $(CASES_DIR) $(RESULTS_DIR) $(SUBRESULTS_DIR)
+	rm -rf $(CASES_DIR) $(RESULTS_DIR)
 
 inter-port-clean:
 	rm -f  fwk/lib/*.o
-
-
diff --git a/support/regression/collate-results.py b/support/regression/collate-results.py
index ab5b03b3..4f0ce64c 100644
--- a/support/regression/collate-results.py
+++ b/support/regression/collate-results.py
@@ -1,13 +1,21 @@
 import sys, re
 import string
 
+"""Simple script that scans all of the test suite results text fed in
+through stdin and summarises the total number of failures, test
+points, and test cases."""
+
+# Read in everything
 lines = sys.stdin.readlines()
 
+# Init the running totals
 failures = 0
 cases = 0
 tests = 0
 
 for line in lines:
+    # '--- Summary: f/t/c ...', where f = # failures, t = # test points,
+    # c = # test cases.
     if (re.search(r'^--- Summary:', line)):
         (summary, data, rest) = re.split(r':', line)
         (nfailures, ntests, ncases) = re.split(r'/', data)
diff --git a/support/regression/generate-cases.py b/support/regression/generate-cases.py
index 350e8088..32f8190e 100644
--- a/support/regression/generate-cases.py
+++ b/support/regression/generate-cases.py
@@ -1,9 +1,11 @@
 from HTMLgen import TemplateDocument
 import sys, re, tempfile, os
 
+"""See InstanceGenerator for a description of this file"""
+
 # Globals
 # Directory that the generated files should be placed into
-outdir = 'cases'
+outdir = 'gen'
 
 # Start of the test function table definition
 testfuntableheader = """
diff --git a/support/regression/ports/host/spec.mk b/support/regression/ports/host/spec.mk
index dc2449c6..d9666ccc 100644
--- a/support/regression/ports/host/spec.mk
+++ b/support/regression/ports/host/spec.mk
@@ -1,11 +1,13 @@
+# Port specification for compiling on the host machines version of gcc
 SDCC = gcc
 SDCCFLAGS = -Wall
 
 EXEEXT = .bin
 
+# Required extras
 EXTRAS = fwk/lib/testfwk$(OBJEXT) ports/$(PORT)/support$(OBJEXT)
 
-$(PORT_SUBRESULTS_DIR)/%.out: $(PORT_CASES_DIR)/%$(EXEEXT)
+%.out: %$(EXEEXT)
 	mkdir -p `dirname $@`
 	-$< > $@
 	if grep -q FAIL $@; then echo FAILURES in $@; fi
diff --git a/support/regression/ports/z80/spec.mk b/support/regression/ports/z80/spec.mk
index 78e6f699..e30da7de 100644
--- a/support/regression/ports/z80/spec.mk
+++ b/support/regression/ports/z80/spec.mk
@@ -1,14 +1,21 @@
+# Port specification for the z80 port running ontop of the Java based
+# 'ConsoleZ80' emulator.
+
+# PENDING: Patch to gbdk-lib for stdarg
 SDCCFLAGS += -I/home/michaelh/projects/gbdk-lib/include
 
 EXEEXT = .bin
 
+# Needs parts of gbdk-lib, namely the internal mul/div/mod functions.
 EXTRAS = fwk/lib/testfwk$(OBJEXT) ports/$(PORT)/support$(OBJEXT) \
 	/home/michaelh/projects/gbdk-lib/libc/asm/z80/mul$(OBJEXT) \
 	/home/michaelh/projects/gbdk-lib/libc/asm/z80/div$(OBJEXT)
 
+# Rule to generate a Emulator .bin file from the .ihx linker output.
 %$(EXEEXT): %.ihx
-	../makebin/makebin -s 32768 < $< > $@
+	../makebin/makebin -s 32768 < $< > $@  # Must be 32768 due to a bug in ConsoleZ80
 
+# Rule to link into .ihx
 %.ihx: %$(OBJEXT) $(EXTRAS)
 	../../bin/link-z80 -n -- -b_CODE=0x200 -b_DATA=0x8000 -i $@ $< $(EXTRAS)
 
@@ -21,19 +28,7 @@ EXTRAS = fwk/lib/testfwk$(OBJEXT) ports/$(PORT)/support$(OBJEXT) \
 %$(OBJEXT): %.s
 	../../bin/as-z80 -plosgff $@ $<
 
-$(PORT_SUBRESULTS_DIR)/%.out: $(PORT_CASES_DIR)/%$(EXEEXT)
+%.out: %$(EXEEXT)
 	mkdir -p `dirname $@`
 	java -cp /home/michaelh/projects/rose ConsoleZ80 $< > $@
 	if grep -q FAIL $@; then echo FAILURES in $@; fi
-
-#$(PORT_SUBRESULTS_DIR)/%.out: $(PORT_CASES_DIR)/%$(EXEEXT)
-#	mkdir -p `dirname $@`
-#	-$< > $@
-#	if grep -q FAIL $@; then echo FAILURES in $@; fi
-
-
-#%$(EXEEXT): %$(OBJEXT) fwk/lib/testfwk$(OBJEXT)
-#	$(SDCC) $(SDCCFLAGS) -o $@ $< fwk/lib/testfwk$(OBJEXT)
-
-#%$(OBJEXT): %.c fwk/include/*.h
-#	$(SDCC) $(SDCCFLAGS) -c $< -o $@
diff --git a/support/regression/ports/z80/support.asm b/support/regression/ports/z80/support.asm
index 6ba7686a..3014728c 100644
--- a/support/regression/ports/z80/support.asm
+++ b/support/regression/ports/z80/support.asm
@@ -1,4 +1,5 @@
 	;; ****************************************
+        ;; Minimal crt0 and support functions for the sdcc test suite.
 	;; Beginning of module
 	.title	"Test runtime"
 	.module	Runtime
@@ -24,7 +25,8 @@ __putchar::
         ld      a,l
         out     (0xff),a
         ret
-        
+
+        ;; Segment order
         .org    0x200
 	.area _HOME
         .area _CODE
diff --git a/support/regression/tests/increment.c b/support/regression/tests/increment.c
index ff0f5ce3..8807a65c 100644
--- a/support/regression/tests/increment.c
+++ b/support/regression/tests/increment.c
@@ -2,13 +2,14 @@
 
     type: signed char, int, long
     storage: static, 
+    attr: volatile,
 */
 #include <testfwk.h>
 
 static void
 testIncrement(void)
 {
-    volatile {storage} {type} i;
+    {attr} {storage} {type} i;
     i = 0;
     i--;
     ASSERT(i == -1);