Appendix C

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

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.

You can run the TADS Compiler simply by typing its name, tc, followed by the name of the file you want to compile. 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.)

The TADS Compiler accepts several options as part of its command to control its 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.

-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.
-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 wish to use the Debugger with your game. 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.
-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; if you do not have enough memory in your computer, you must lower one of these sizes. Alternatively, if your program exceeds one of the pre-defined sizes, you must increase the size. The item specifiers 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. With no second option letter, the -m option specifies the size of the virtual object cache; 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. 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.
-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 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.
-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 x 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.
-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.

On some 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 run-time, 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 run-time 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 run-time, 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 run-time is unable to detect the incompatibility. It is therefore not always safe to mix different versions of the compiler and run-time 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.

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.