The instrs and regression directories contain test suites for the HLA 
(High Level Assembler) compiler.  Instrs is OS-independent and will run on
Windows, Linux, and FreeBSD (no Mac version yet, it's coming). 
The Regression test suite (in the Regression directory) will run only 
under Windows.

These test suites are used to check HLA before any new release (as well as
compiling all the HLA example programs and the HLA v2.0 compiler). The
successful completion of all these tests won't guarantee that an HLA
build is correct, but these tests do tend to catch a lot of errors that
get injected into the system during bug fixes and enhancements.

Note that under Windows, the stdlib must be compiled with MASM and
Microsoft linker in order for the data file comparisons to be valid.
The regression test suite must also be compiled with MASM and linked
with the Microsoft linker, e.g.,

set hla=mhla
set hlalink=mslink
set hlaasmopt=-Zi -Zd -Zf
set hlalinkopt=-DEBUGTYPE:COFF


================= I N S T R S   T E S T    S U I T E   =======================

The Instrs test suite consists of a program that generates various assembly
language source files for HLA, MASM, FASM, and Gas. It compiles these source
files with the corresponding assemblers and then compares their output. Note
that MASM/FASM is Windows-only, Gas is Linux/FreeBSD-only. Also note that
the source code generation program generates .intel_syntax style Gas
assembly language, so some work will be needed to port this test program
to Mac OSX (whose version of Gas supports only AT&T syntax).

The Instrs test suite requires *considerable* free space (many gigabytes) to
run. This is because it generates hundreds of really large source files for
each of the different assemblers. Of course, after running the test suite,
you can easily reclaim all this storage by issuing a "make clean" command. Just
be aware that you will need considerable disk space to successfully run this
test suite.

Running the Instrs test suite is easy. Just CD into the "instrs" directory
and type "make" from your command line/shell interpreter. Linux and
FreeBSD users should use the "makefile.unix" make file (by using the command
"make -f makefile.unix").  This will run the program that generates the
source test files, compiles them, disassembles them, and then compares the
disassembled output. The system aborts operation if a pair of files do not
compare properly.

As noted above, once the test suite completes running, you should clean up
all the extraneous source files, executable files, and temporary files by
issuing a "make clean" (or "make -f makefile.unix clean") command.

The theory behind the Instrs test suite is that if HLA generates the same
binary code as several different assemblers (using HLA "-sourcemode"), then
chances are pretty good that HLA is generating proper code (i.e., it's
unlikely that *all* the assemblers generate the same bad code).

Note that the Instrs test suite tests *only* machine instructions and
tests only HLA in the "-sourcemode" mode of operation. Nevertheless, it
provides a very good test of the HLA parser processing all the machine
instructions and x86 addressing modes.  The Regression test suite checks
the machine instructions in hexadecimal output mode (not "-sourcemode").

	

========   R E G R E S S I O N   T E S T    S U I T E   =======================

The Regression test suite is a large set of functional test programs for
HLA. The basic principle of this test suite is that it compiles a large
number of source files in hexadecimal output mode and in source output mode
and compares the disassembled binaries against one another. This verifies that
HLA (in hexadecimal mode) emits the same object code as other assemblers
(processing the "-sourcemode" output).  Several of the regression tests'
outputs are also compared against some fixed (checked by hand) data to see
if there are any deviations from a known correct assembly.

Unlike the Instrs test suite, the Regression test suite checks more than 
just machine instructions. It checks compilation of HLL-like control
structures, declarations, procedure calls, and other HLA language features.

To run the Regression test suite, you must set the hlainc environment
variable to point at the ...../hlalibsrc/working/hlainc subdirectory
(because the test suite needs access to header files in the
...../hlalibsrc/working/include directory, which it references off
the ...../hlainc subdirectory).  Pointing hlainc at the typical 
"c:/hla/include" WILL NOT WORK.  Once you've set hlainc properly, just CD
into the Regression directory and type "make". The rest should be automatic.

