Appendix C

This chapter describes how to use the TADS Compiler, and explains the options and parameters that the compiler accepts.

The TADS Compiler

The TADS Compiler is the program that reads your adventure source file, checks it for correct syntax, and converts it to a binary representation that can be executed by the TADS run-time system. Generally, the binary version of your game is considerably smaller than the source. The symbolic TADS code is converted to a byte-code similar to machine language, the strings are compressed using a variable byte length encoding (which also makes it difficult for players to cheat by looking at your program’s strings), and the objects are converted to compact data structures.

This section describes the options and parameters that you use to control the TADS Compiler. Note that the format of the commands shown in this section is general, and some operating systems may have slightly different conventions; consult your system-specific release notes for information on using the Compiler on your computer. Note also that you may have to perform some minor configuration on your computer (for example, setting the command path so that your command interpreter can find the Compiler program file) before you can run the Compiler.

Note that on Macintosh systems, the compiler does not have a command line at all; instead, it uses a dialogue box and pull-down menus to specify compiler options. All of the options described in this appendix are accessible in the Macintosh version; it should be easy to identify the menu selections and dialog entries corresponding to the options described below.

The Macintosh compiler also does not add default suffix to input files. In past versions, the compiler added “.t” to the name of a source file if the source file didn’t have any periods in its name. While adding a default suffix is convenient on other platforms (since it saves the user the trouble of typing the suffix on the command line), it’s obviously not desirable on the Macintosh, since the user specifies the file by pointing at it - the full filename is always given, so a suffix shouldn’t be added.

Running the Compiler

You can run the TADS Compiler simply by typing its name, tc or tc32 or tadsc, followed by the name of the file you want to compile. (the exact name depends on the version you’re running and for what operating system) For example:

  tc sample 

This invokes the TADS Compiler, and tells it to compile the file sample.t (using the appropriate local conventions to add the extension .t to the given filename), and to write the binary version of the game to the file sample.gam.

If any errors occur during compilation, the Compiler provides an explanatory message and tells you the file and line number where the error occurred. If errors (other than warnings) occur, the binary file is not created, since the game would not be playable. (On Macintosh systems the compiler also displays the text of lines at which errors are detected.)

Compiler Options

Text-only versions of the TADS Compiler accept several options as part of the command to control operation. All of the options consist of a dash, followed by one or more option letters, possibly followed by a parameter. The options are specified before the name of the source file:

  tc options file 

For example, to compile sample.t and generate source-level debugging information, you would type this command:

  tc -ds sample 

Note that with options that take a parameter, you can either run the option and its parameter together without a space, or you can put a space between them; it makes no difference. For example, the following two commands are equivalent:

  tc -ic:\tads -od:sample sample
  tc -i c:\tads -o d:sample sample 

Note, however, that the memory options require the memory type letter immediately after the -m option; the size, however, can be separated by a space. Hence, the following two commands are valid:

  tc -mh5000 sample tc -mh 5000 sample 

Following is the complete list of Compiler options. For a brief list of the options, just type tc without any parameters; the Compiler will display a list of the options it accepts and what they do. Note that versions of the Compiler with a graphical interface (Macintosh and Windows) have menu items which allow you to set most or all of these options without any typing in of commands.

-case-	The compiler lets you turn off case sensitivity. If you don’t want to distinguish between upper- and lower-case letters in your symbols, you can use the -case- option to turn off the compiler’s case sensitivity. By default, the compiler is set to -case+, which makes the compiler treat an upper-case letter as distinct from the same letter in lower-case. For example, when the compiler is case-sensitive, deepverb and deepVerb are different symbols. If you would prefer not to keep track of the exact case of the letters in the symbols defined in your game (or in adv.t), you can make the compiler treat upper- and lower-case letters the same by using -case-. Note that adv.t will work either way. All of the references to a particular symbol in adv.t use the same case, so adv.t will work properly with case sensitivity turned on. However, adv.t will also work properly with case sensitivity turned off, because it doesn’t have any symbols that depend on being in a particular case (for example, it doesn’t define one symbol called "a" and a distinct symbol called "A" - if it did, these symbols would collide when compiling without case sensitivity).
-C	(Note that this is a capital letter “C.”) This is a toggle option that lets you turn C operator mode on and off (see the section on C operators). The default is -C-, which enables the standard TADS operators. If you specify -C+, TADS will change the assignment operator to “=” and the equality operator to "==" to match the C language.
-ctab file	Sets the character mapping file. For details, see Appendix K.
-D symbol=value	(Note that this is a capital letter “D.”) Defines the preprocessor macro symbol symbol, optionally assigning it the text value. This has the same effect as placing #define symbol value at the very start of the source file (see the Preprocessor Directives section for more about #define). Note that the "=" and value can be omitted, in which case the default value is "1". The reason that there's a -D option is that it lets you compile different versions of your program purely from the command line, without changing any source code. You can use #if and related directives to mark portions of the source code for inclusion or exclusion, depending on macro settings, and then use -D to select the particular combination of options (often called a "configuration") that you want to build.
-ds	Generate source-level debugging information. This option causes the compiler to include information in the binary game file that the TADS Debugger uses to trace execution of the program and correlate the generated code to the source files. You must use this option if you want to use the Debugger with your game. Note that using this option increases the size of the game file, so you will normally compile without the -ds option once you have finished debugging your game. Just as importantly, plain text information will be stored in the game file when you use the debugging format, which may give away game hints to inquisitive players who try opening up the game file in a text editor or word processor.
-ds2	Generate source-level debugging information in the new format. This new style of debugging information is designed to work with the Windows HTML TADS Debugger (part of TADS Workbench). If you’re running your game with the Windows debugger version 2.5.0 or later, you must compile with the -ds2 option. If you’re using an older version of the Windows debugger, or you’re using the debugger on another platform (DOS, Unix, Mac), you must continue to use the original -ds option as before.
-e file	This option tells the compiler to log all error messages to file. All error messages generated during compilation will be saved to the indicated file; the messages will also be displayed on your screen as usual. The file will be created if it doesn’t exist, or overwritten with the new error log if it already exists.
-fv type	Sets the .GAM file format. The type can be a for format “A” (used by TADS versions prior to 2.1), b for format “B” (used by version 2.1.0), c for format “C” (introduced in version 2.2) or * for the most recent version. The default is -fv*, which currently selects format “C.” Unless you have some specific reason for using an older file format, you should use the most recent format (-fv*). Version 2.1 of TADS uses file format “B,” which is slightly different from the original file format, and 2.2 uses format “C,” which differs slightly from “B.” File formats other than “A” will not be accepted by versions of the runtime earlier than 2.1. The version 2.2 runtime is able to read any previous file format.
-Fsmygame.lis mygame.t	This compiles mygame.t, producing mygame.gam as usual, and writes all of the strings in the source code to the file mygame.lis. In other words, the compiler can capture all of the strings used in a game to a text file. This can be useful for spell-checking your game, since it gives you a listing of all of the text in the game, separated from your source code.
-ipath	Adds path to the include path. When you use the #include directive to include a file, and enclose the file in angle brackets (< and >), the list of directories specified with -i options is searched, in the order given, for the file. Note that previous versions of TADS required you to end the path specification with your operating system’s path separator character; this is no longer required, but a trailing path separator character is harmless if present.
-lfile	Load a pre-compiled file prior to compiling the source program. The file must have been previously created with the -w option. This option allows you to speed up the compile process by compiling the include files that you commonly use separately from your program, then loading their binary forms when you compile your program. Loading a binary file is much faster than compiling the source file it came from. Note that only one file can be loaded with the -l option. However, you can easily pre-compile several include files simply by making a short file that contains only #include directives listing the files you want to gather together into a single pre-compiled binary. Note also that files can be included only once; if you attempt to include a file twice, the compiler will ignore the second directive. This makes it convenient to use pre-compiled files, because you do not need to change your source files - simply leave the normal #include directives in your program. If you use the -l option to load pre-compiled versions of these source files, the #include directives in your program will be ignored; if you do not use -l, the files will be included as normal. This way, you do not need to change your source file when you wish to use the -l option.
-mitem size	Set memory size for a given item to size. The compiler will attempt to pre-allocate a certain amount of space for several types of objects when it initializes itself. Naturally, if you do not have enough memory in your computer you must lower one of these sizes. Or, if your program exceeds one of the pre-defined sizes, you must increase the size. With no second option letter, the -m option specifies the size of the virtual object cache. The item specifiers, however, are: g - goto label table size h - heap size l - local symbol table size p - parse node pool size s - stack size To determine the default sizes on your computer, run the Compiler with the option “-m?”; this will display the memory options and their default values. The various memory options are explained below.
-ofile	Set output filename to file. If the filename does not have an extension, the default extension .gam will be appended to the name (following the conventions of your operating system).
-p	Pause before terminating the compiler. This option is useful for operating systems that operate from a “desktop”; on these systems, the information displayed by the compiler is usually cleared off the screen as soon as the program terminates, which doesn’t leave enough time to see the messages the compiler produces. When the Compiler pauses, it prompts you to strike a key; when you do so, it continues. Note that this option is not necessary on Macintosh or Windows systems, because the compiler does not exit after compilation until you explicitly select the “Quit” item from the “File” menu, or hit the “Quit” button.
-s	Enables statistics. After the game has been compiled, a set of statistics on memory usage will be displayed.
-tf file	Use file to hold swapping information. By default, the file TADSSWAP.DAT in the current directory is used. If you are using a RAM disk, you may wish to place the swap file on the RAM disk to improve performance.
-ts size	Limit the swap file to size bytes. You may wish to use this option if you have limited space on the disk containing the swap file.
-t-	Turn off swapping. This forces the compiler to keep the entire game in memory. Note that, even when swapping is enabled, the compiler won’t swap until necessary - that is, until the cache is full and no more space can be allocated for the cache.
-U symbol	(Note that this is a capital letter “U.”) Undefines (i.e., deletes) the preprocessor macro symbol symbol. assigning it the text value. This has the same effect as placing #undef symbol at the very start of the source file (see the Preprocessor Directives section for more about #undef). The reason there's a -U option is that it lets you remove macros that the compiler automatically pre-defines, and also lets you remove macros defined with -D options earlier on the same command line. This gives you more control over command-line builds, particularly if you use #if and related directives to create multiple configurations of your program.
-v level	Set warning verbosity level. The default level is 0 (minimum verbosity: suppress certain warnings which are either purely informational or generally do not indicate an actual problem). Other levels are 1 (suppress purely informational messages, but display warnings even when they generally do not indicate a problem), and 2 (maximum verbosity: display all warnings and informational messages).
-v-abin	Disables the warning message “operator & interpreted as unary in list.” (TADS-357). If you’re compiling a game written with a previous version of TADS, and you get this warning, you may want to use -v-abin to disable the warning. This warning is intended to notify you that the new meaning of the operator is not being used - in other words, TADS is warning you that it’s using an interpretation that’s compatible with past versions of the compiler. If your game was written for an older version of the system, this is exactly what you want, so you probably don’t need the warning.
-wfile	Writes the pre-compiled version of the source to file. No default extension is applied. When you use this option, any -o option that you have specified is ignored, since a game file is not produced. Files written with -w are intended to be loaded with the -l option; see the description of -l for more information on how to use pre-compiled files.
-Za	Suppress generation of argument-checking code. Whenever a function is called, TADS version 2 will check to make sure that the function received the same number of arguments that it was expecting. Since TADS version 1 did not do this, some games have a mismatch between actual and formal parameters for some functions and methods; with TADS 2, this will cause a run-time error. You can use the -Za option to suppress these run-time errors, which in many cases are harmless.
-1	Enable all version 1 compatibility options. These options allow you to compile ancient TADS version 1 games, if you happen to have the source to such games available.
-1a	Same as -Za: disable run-time argument checking.
-1e	Ignore semicolons between a closing brace and an else keyword. TADS version 1 allowed this construction, even though it is not actually allowed by the TADS language’s grammar. Version 2, by default, does not allow semicolons between a closing brace and an else keyword; using the -1e option will allow your old code to compile if it contains this construction.
-1k	Disable the TADS version 2 keywords: for, do, switch, case, default, and goto. When you specify -1k, all of these words can be used as identifiers. Some older TADS programs use one or more of these words as identifiers (in particular, do for a direct object argument), which will cause errors when compiled with TADS version 2. Specifying the -1k option will remove these words from the keyword table, making them available for use as identifiers. Of course, specifying -1k will make it impossible to use any of these new language constructs in your game, so it should only be specified with old code that you haven’t updated for version 2 yet.
-1dkeyword	Changes the do keyword (used in the do-while construct) to a new keyword of your choosing. If you have a really old game written for TADS version 1 that used “do” as an identifier (such as the name of a local variable or a parameter to a method or function), but you still want to use the new language features in TADS version 2 (such as switch and for), you can use the -1d option to change the do keyword, so that it doesn’t interfere with your game. For example, if you specify “-1d DO”, you will be able to use “do” as a variable name, and you can write do-while loops using the keyword DO instead of do. If you use this option instead of -1k, you can still use switch, for, and the other new version 2 language constructs.

Memory allocation

The TADS Compiler has a number of memory options related to certain internal settings. Most versions of the compiler ship with these options preset to reasonable defaults, so it’s unlikely you’ll run into problems with the settings being too low. However, the default values do vary between certain versions of the compiler, so it may be necessary to experiment with some of these memory options, particularly if you’re compiling a really large (a megabyte or more of source code) game or if you’re using a very old computer with very limited memory. The parse node pool setting is the most likely option that will need adjusting in those cases.

The compiler checks carefully to ensure that the memory size settings specified with the various -m parameters (in particular, -mg, -mp, -ml, -ms, and -mh) are valid. These settings must fit within certain limits, which are enforced carefully. Previous versions of the compiler responded unpredictably to invalid settings.

goto label table size (-mg)

This setting controls the size of an internal table used to keep track of “goto” labels within a function. You probably will never need to adjust this setting - especially if you never use goto anywhere in your code.

The size affects each function individually, so you only need to set it as large as necessary to accommodate whichever of your functions has the most “goto” labels. The actual number of bytes needed is the sum of the number of characters in all of the label names in a function, plus some overhead per label.

The default for this setting is usually 1024 or 8192 bytes. The maximum value is 64K, but there should be never be any reason to set it this high unless you’re dangerously obsessed with goto statements.

Local symbol table size (-ml)

This is an internal table that the compiler uses to track local variable definitions. Like the ‘goto’ table, this is used for functions individually, so it scales according to your largest function (ie: the one with the most locals), not with the overall program size.

The default for this setting is usually 4096 or 16384 bytes. Note that the values for the local symbol table and parse node pool table are linked - the combined value of the two tables cannot exceed 64K.

Parse node pool size (-mp)

The parse node pool is another internal table, and probably the only memory setting you’re likely to need to change if you’re compiling a very large game.

This table is used by the compiler for temporary storage of internal data structures required to parse expressions. The memory required generally scales according to the complexity of expressions (such as variable assignments, ‘if’ conditions, ‘while’ control expressions, and the like). In addition, some types of statements have to keep track of several expressions at once, so the complexity compounds; ‘for’ statements and nested ‘switch’ statements, for example, tend to keep several expressions’ worth of data at once.

The default for this setting is usually 6144 bytes or 24576 bytes. The latter should be more than adequate to compile even really huge games. Note that the values for the local symbol table and parse node pool table are linked - you can’t have a combined value of greater than 64K for the two tables.

Heap size (-mh)

This setting has exactly the same function as the interpreter’s heap size - the compiler uses it for configuring the integrated interpreter it uses to run the preinit function. This is the area where the interpreter builds intermediate values for string and list operations, such as extracting a substring or appending data to a list.

The default for this setting is usually 1024 bytes or 65535 bytes; the latter being its maximum value.

Stack size (-ms)

This setting has exactly the same function as the interpreter’s interpreter stack, and like the heap is used for running preinit. The size needed here depends on how deeply nested your function calls are while running preinit.

The default for this setting is usually 50 or 512 elements, and the maximum varies from system to system but usually tops out at 8000 elements.

Virtual object cache (-m)

This is the memory area that the compiler uses to contain the compiled representation of game objects and functions. Since the compiler has a virtual memory system, the cache size can be smaller than the actual memory needs of your game. Normally, you will not need to set the cache size, since the compiler automatically allocates additional memory for the cache as needed.

However, since the compiler also allocates non-cache memory during compilation, the cache can grow so large that, in low-memory situations, your computer runs out of space for non-cache memory. If this happens, the compiler will exit and issue an error message telling you how big the cache was when the compiler ran out of non-cache memory; you should re-run the compiler specifying a smaller size with the -m parameter. For example, if the compiler runs out of memory and tells you that the cache is 256,000 bytes, you could try re-running with -m 200000 to specify that the cache should grow no larger than 200,000 bytes.

Some versions of the compiler (eg: Macintosh) do not let you adjust this setting - it’s permanently set to the highest value. In this case you may need to expand the amount of memory available to the compiler program if your computer’s operating system doesn’t do it for you automatically. For example, under versions of the MacOS through to OS 9.x you will need to increase the amount of memory allocated to the compiler program by going to the program’s Get Info box.

Configuration Files

On non-graphical operating systems, the TADS compiler allows you to place a set of command line options into a “configuration file” that is read each time the compiler is run. This file is named CONFIG.TC. TADS looks for this file first in the current directory, and if it fails to find it, in the same directory as your TADS Compiler executable. This allows you to have multiple configurations: one default configuration, stored in the CONFIG.TC file in your TADS compiler directory; and then special per-game configurations, stored in the CONFIG.TC files in your game source directories. If the file does not exist in either the current directory or in the TADS compiler directory, no configuration file is used.

The configuration file simply contains compiler options. The file is a standard text file; each line within the file can have as many options as you want, and the file can have as many lines as you want. Any blank lines within the file are ignored.

If you want to create a configuration file that specifies that the virtual object cache is to be limited to 128,000 bytes, that the swap file is to be named SWAP.DAT on the D: disk, and that the directory c:\tads\include is to be searched for header files, you could make a configuration file like this:

  -m 128000 -tf d:\swap.dat
  -I c:\tads\include 

Note that options specified on the command line always override options in the configuration file. The configuration file is simply a convenient way to store default options that you often use. Suppose you are using the above configuration file, and you type this command:

  tc -m 256000 -I c:\myinc mygame.t 

The -m 256000 option overrides the configuration file’s -m 128000 option, so the configuration file’s version is ignored. Include directory options are a little different, in that they’re additive: the command line’s -I c:\myinc is added to the include path. However, since the command line takes precedence over the configuration file, the command line include path is added before the path in the configuration file.

You are not required to use a configuration file, and no error is generated if a configuration file is not found. The configuration file is simply a convenient way to store options that you frequently use, so you don’t have to type them every time you run the compiler.

File Formats

Version 2.2 of TADS introduced a slightly different game file format than that used by previous versions, and version 2.1 introduced another format. The newer formats will not be acceptable to older versions of the interpreter, although the new run-times are able to read .GAM files produced by older versions of the compiler.

The version 2.2 compiler generates .GAM files with format “C”; the version 2.1 compiler generated .GAM files with format “B” and prior versions generated format “A.” The version 2.2 interpreter is able to read files in all three formats. Previous versions cannot read all three formats.

If for some reason you wish to generate a .GAM file that can be read by an older version of the interpreter, the compiler has a new option, -fva (Format Version “A”) which generates .GAM files in the old format A. Similarly you can use -fvb (Format Version “B”) to generate format B games.

Unless you have a specific need to generate the older formats, we recommend using the newest format (which the compiler will use by default). Another switch, -fvc, is provided to tell the compiler explicitly to use format “C”; and -fv* tells the compiler to use the most recent format (currently “C”).

Note that some incompatible file format changes have been made in past versions in such a way that the interpreter is unable to detect the incompatibility. It is therefore not always safe to mix different versions of the compiler and interpreter with versions prior to 2.1.

One of the changes to the game file format “B” makes the files much more compressible with archiving and compression utilities. The .ZIP and .SIT files that you make from your .GAM files should now be much smaller.

The changes made in version “C” enable the disambigDobjFirst flag. If you compile with an earlier file format, you will not be allowed to use this flag.

Error recovery

When the compiler encounters a semicolon or a right brace (“}”) in the first column of a line while inside a string (either double-quoted or single-quoted), it will generate a warning message that you have a possible unterminated string. This is purely a guess by the compiler, but if you are careful to format your code using the same convention as adv.t, in which every function ends with a right brace on a line by itself, and every object ends with a semicolon on a line by itself (without any spaces preceding it), the compiler will be able to find your unterminated strings almost every time. Note that the unterminated string will often not be the last string, but this warning will at least isolate the object or function where the string is coded.

The compiler will generate an error message if you attempt to use self in a function. This has always been illegal, but versions of the compiler prior to 2.1 did not detect the error, so the problem was not detected until the code was actually executed.

The warning messages that the compiler generates for optional objects and functions (such as parseError and commandPrompt) are suppressed at warning verbosity levels less than 2. Many users find these warnings confusing or annoying, and they almost never actually indicate a problem in your game, so they are not generated unless you specifically ask for them.

The warning message for multiple inclusions of the same file is suppressed at verbosity levels less than 1. This message is almost always spurious if you use precompiled headers, because it is generated for every header that you precompiled. You will not see this warning unless you specifically ask for it by setting a higher warning verbosity level.