hsc source directory
====================

This directory contains the sources for hsc. They are distributed
under GNU General Public License (for details, see file "COPYING" in
the parent directory).

For some binary distributions (AmigaOS, RiscOS), you might only find
this README. Please refer to "hsc/README" (see parent directory) where
you can obtain the sources from.

---------------------------------------------------------------------

IMPORTANT: If you've compiled older versions of hsc before, remove 
all files of the old sources before you continue.

There are two makefiles, but only one is required to create the 
binaries:

=====================
USING "MAKEFILE.DODL"
=====================

"Makefile.dodl" is designed to compile with CC under an Unixoid
environment without any special options or debugging-features
enabled.

Use

    make -f Makefile.dodl

to start the compilation-sequence.

If you dare, you can try to coment out/in some lines to select a more
specific compiler setup.

================
USING "MAKEFILE"
================

"Makefile" uses conditionals for figuring out the compiler and
environment. You can change the environment commenting-out the
required symbol. GNUmake v3.74 is recommended.

At the moment, only AmigaOS and Unix are supported. For AmigaOS, you
require GCC or SAS/c, for Unix,  GCC and CC are supported.

This makefile supports three compilation modes: "debug" for a
debugging version that includes all debugging information, supports
a source-level memory-tracking and enables some additional output
and plausibility checks. "norm" links only some debugging
information, and "optim" strips all debugging information and
creates an optimized executable.

After having done this, use

    make

to start the compilation-sequence.

-----------------
COMPILER WARNINGS
-----------------
Normally, no warnings should show up, exept about ununsed functions
and parameters. This is because some parameters and functions are
only used by the debugging-version.

------------
OPTIMISATION
------------
If you set the compilation mode to "optim", the binary will be 
optimised for small code.

If the optimised version causes serious problems, try to compile
with compilation mode set to "norm". There are loads of buggy
optimisers out there..

--------
TEST RUN
--------
To test if hsc works as expected, some test data are included in
source/test/. Simple type

    make test

from the same directory you started the compilation before.

This will invoke hsc several times: some .hsc-files will be used
to create some .html files. These are compared with .expected-files,
which have been compiled before and contain the expected output.

For this comparison, `diff --brief' will used. Make sure that such
a command is available before starting the test process.

Additionally, hsc will redirect messages to .msg files. These will
be compared with .mex ("messages expected") files the same way as
described above.

If all works fine, `diff' should not produce any output.

-------
CLEANUP
-------
To remove the object files, use

    make clean

To also remove binaries and temporary files, use

    make sterile

========
PROBLEMS
========

If you modify the Makefile, make sure that your editor does not
convert TABs to blanks.

Make sure that you didn't extract the source-archive to a path where
an old source-archive has already been located; remove older 
versions before you extract the sources.

Problems might occure, if your compiler does not support ANSI-C (as
"cc" under SunOS on my university - Pfthuahuhahua!), but I won't
care about this.

============
THE BINARIES
============

If nothing went wrong, you now should have created three files:

    hsc/hsc
    hsctools/hscdepp
    hsctools/hscpitt

These are the executables. Now follow the installation-instructions 
of the documentation that came with the main-archive.

(In short: put the binaries somewhere in your search-path, and setup
hsc.prefs in the appropriate place.)

Thomas Aglassinger <agi@giga.or.at>