1<html> 2 3<title>Porting TADS 3</title> 4 5<h3>Porting TADS 3</h3> 6 7<p> 8TADS 3 is designed for easy portability to a wide 9variety of platforms. The source code is written in ANSI C++, and is 10very conservative in its use of C++ languages features; the code does 11not use templates, exceptions, or run-time type information, and limits 12itself to the standard C run-time library. 13 14<h4>A Note on Newlines</h4> 15 16<p>Different operating systems have a tendency to disagree on the 17most trivial details. One of these pointless variations that causes 18a lot of trouble is "newline" conventions: each OS has its own way of 19signaling the end of a line of text in files such as C source and 20header files. In almost every case, the end of a line of text is 21indicated by some combination of the special characters with ASCII 22values 10 and 13, known respectively as "line feed" or "LF", and 23"carriage return" or "CR". MS-DOS uses the sequence CR-LF; Unix uses 24just LF; Macintosh uses just CR; and some system somewhere probably 25uses LF-CR. 26 27<p>In many cases, systems are tolerant of "foreign" conventions, but 28sometimes the wrong conventions will confuse compilers and other 29tools. If you run into any mysterious compiler errors, or your text 30editor or other tools have problems reading or displaying the TADS 31source files, you might want to try converting the files to your 32system's newline conventions. One of the easiest ways to do this is 33usually to use your UNZIP tool's "auto-convert text files" option 34when you unpack the TADS source archive - on command-line systems, 35this is usually the "unzip -a" option. 36 37 38<h4>Portable and OS Layer Code</h4> 39 40<p> The TADS 3 source code uses the same technique to separate code 41into portable and OS layers that TADS 2 used. All of the code in the 42TADS 3 source distribution is portable, except for the files in 43system-specific subdirectories (such as "win32"). You should be able 44to use all of the portable code without making any changes to it. 45Any required changes in the portable code are porting exceptions; you 46should report them back to me so that I can find a way to merge the 47changes to correct the problem. There should be no platform-specific 48#if's or #ifdef's in the portable code - the source in the portable 49files should be 100% common to all platforms. 50 51<h4>OS Layer Implementation</h4> 52 53<p> TADS 3 uses the identical OS interface layer that TADS 2 used. 54So, the first thing you need to do to port TADS 3 to a new platform 55is to obtain the TADS 2 OS interface implementation for that 56platform. TADS 2 has been widely ported, so there is a good chance 57that you can use an existing OS layer implementation for your 58platform. If you're porting to a platform that doesn't have a TADS 2 59port, you must create your own TADS 2 OS interface implementation for 60the platform. Please obtain a copy of the TADS 2 source distribution 61for full details on how to go about this. 62 63<p> TADS 3 is designed to share the same object files from the TADS 2 64OS layer, so you will not need to create a new copy of the OS files. 65You should instead simply set up your new TADS 3 makefile so that it 66includes headers from your TADS 2 OS include directory, and links in 67the "osxxx" object files from your TADS 2 object file directory. 68 69<h4>Creating a Makefile</h4> 70 71<p> 72Refer to win32/makefile.vc5 in the source distribution for an example 73makefile. This makefile is set up for Microsoft Visual C++ on Windows 74(it'll work on VC++ versions 5 and 6, at least). This is <i>not</i> 75any kind of scary project file or other machine-generated monstronsity; 76it's simply a makefile, similar to Unix-style makefiles. The "vc5" 77extension, by the way, is just my own naming convention to indicate 78that it's the Visual C++ version of the makefile. 79 80<p> The Windows makefile defines the groups of object files that make 81up the various executables. In most cases, you will want to 82configure your own executables in roughly the same way; the only 83differences should be that you must substitute your OS layer 84implementation files for the Windows versions - these are the files 85whose names start with "os". 86 87<p> Makefiles are pretty nasty to read, so I'll provide some pointers on 88what to look for. The first piece of information you want from the makefile 89is simply the group of object files that make up each executable. This 90much is pretty easy to read - look for names of executables followed 91immediately by a colon - search for "t3make.exe:", for example, to find 92the compiler executable's build rule. Following this is a long list of 93object files. These are the object files that make up the executable. 94All of the object files prefixed with "$(OBJDIR)" are portable 95executables. The ones prefixed by "$(TADS2OBJDIR)" are the TADS 2 OS 96layer object files - these are not part of the TADS 3 source distribution 97because you can get them from the TADS 2 distribution. The object file 98list ends at the line that starts with "$(LD) $(LDFLAGS)" - this line 99starts the command specification for the "link" command that builds the 100executable. 101 102<p>Many of the executables listed in the makefile are for testing 103purposes only. You don't need to build these (but you certainly can 104if you want to run some more in-depth testing on your port). 105 106<p>The source file dependencies are mostly straightforward - these 107follow the executable rules. However, a few source files have special 108compilation rules - look at the end of the source-to-object dependency 109rules for the rules that have explicit "$(CC)" command lines listed 110under the dependencies. For example, the object module "vmrun_d.obj" 111is compiled from "vmrun.cpp" with a special compile command (the command 112sets the #define symbol VM_DEBUGGER). 113 114 115</html> 116