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 dialog 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.

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, due to the inability of some text editors to go directly to a line by number, 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.

-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.

-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.

-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.

-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 new 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 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.