Notes on porting TADS
=====================

The TADS code is divided into portable and system-specific sections.
In porting TADS to a new platform, only the system-specific portions
should need to be changed.  If any changes are needed to the portable
code, we consider the portable code in error and will try to correct
it so that it is the same on all platforms.  We want the portable
portion to have a single set of sources, without port-dependent
ifdefs, across all platforms.

For the most part, the system-specific sections are isolated in
files with the prefix "os", and system-specific functions and macros
all begin with "os" or "OS".  In addition, we've recently started
to group some code that High Energy is internally sharing between
multiple products into a code library, all of whose files start
with "L".  The file los.h contains many of the system-specific macros
and definitions.


oem.h
-----

This file defines information about the person who built a particular
version ("OEM" for "Original Equipment Manufacturer").  Refer to oem.h
for details about how to set up the definitions there.


os.h
----

The first thing to do when starting a new port is to create a new
os.h (and los.h) for the new platform.  You can probably take one of
the existing os.h/los.h implementations with a few changes, depending
on your hardware and operating system.  For a 68000 or 68000-like
processor, start with the Macintosh header (osmac.h), since the alignment
and byte ordering macros will be appropriate.  For an 8086-like processor,
start with the DOS headers (os.h and los.h).  Other platforms may need
additional work.


Datatype configuration
----------------------

TADS makes relatively few assumptions about datatype sizes.  TADS
expects that shorts are at least 16 bits, ints are at least 16 bits,
and longs are at least 32 bits.


System-specific function implementation
---------------------------------------

The two files osdos.c and osgen.c provide an implementation of the
system routines for DOS.  osgen.c should be usable on any system with
DOS-like display characteristics.  Note osgen.c and osdos.c check
to see if several USE_xxx preprocessor symbols are defined; these
macros are NOT defined anywhere in the source, but are to be defined
by the makefile.  On DOS, these os files are compiled multiple times
with different combinations of the USE_xxx symbols to produce different
object files for linking the compiler and run-time.

A stdio implementation of many of the routines can also be selected
by defining the preprocessor symbol USE_STDIO.


Building the system
-------------------

TADS consists of three main pieces: the compiler, the run-time, and
the debugger.  Refer to the DOS makefile to see which object files
are included in each.  Note that it may not be possible to let a
librarian/archiver resolve the links for all symbols, because a few
of the object files provide overlapping sets of symbols -- it is
necessary to manually include such object files in the links.  (The
overlapping symbol sets are generally used to provide empty
definitions for certain functions that are referenced but not
actually used by one executable, but must be fully implemented in
another.)


Debugger
--------

The debugger diverges somewhat from the convention of keeping the
os-dependent functions in a file prefixed by "os" or "los".  The
debugger's user interface is implemented in the file dbgu.c on DOS,
and dbgumac.c on Macintosh.  The DOS version also has a file, osdbg.c,
which provides lower-level functions; it should be possible to port
the debugger to a new platform by using the DOS user interface and
replacing only osdbg.c with an appropriate set of functions for the
new system.  However, for any system without DOS-like display and
input device characteristics, the entire user interface will usually
need to be replaced; for example, on the Mac, dbgu.c is not used at all,
but is replaced by dbgumac.c.  This separation of the user interface
provides maximum flexibility for the debugger's user interface while
minimizing the amount of work to port it to a new platform.


Testing
-------

The first test is to build a run-time and see if it can run games
compiled on another system.  The second is to build the compiler, use
it to compile game on your system, and see if that runs.

You can further test using the regression tests.  Compile DEEP.T,
then run tr like this:

      tr -i dsdwalk.in -l dsdwalk.new deep

Then compare dsdwalk.new (the new log generated by your version of
DEEP) with dsdwalk.log (the reference version) -- if they're
identical, your system is probably in pretty good shape.  You can
test similary with DITCH.T and DDDWALK.IN, and BUGS.T and BUGS.IN.


