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.