Compiling with TADS Workbench



Overview

TADS Workbench lets you run the compiler, resource bundler, and executable builder from within the graphical Workbench environment, without ever opening a DOS command shell. In addition, TADS Workbench lets you select the numerous options and parameters that the build commands use through dialogs, rather than through command lines.

Before you build your game, you must select your build settings: these settings specify your source files, output files, and build options. Once you specify your settings, TADS Workbench stores them in your game's configuration file (the .tdc file corresponding to your game's compiled .t3x file), then uses these stored settings whenever you build the game. You can of course edit the dialog settings at any time; but in most cases you need only set up the options once, when you first start working on your game, and then forget about them.

Because the build options are stored with your game's configuration, building your game after each change to your source files is extremely simple: just open the "Build" menu and select the appropriate "Compile" command. Unlike the command-line interface to the tools, the TADS Workbench interface does not make you enter all of the build options each time you build; you set your options once, and TADS Workbench remembers them whenever you compile.

Project Window

TADS Workbench uses a special window titled "Project" to let you control the source files, include files, and resource files that make up your game. If you have a game open in Workbench, and you don't see the Project window, open the "View" menu and click on the "Project" item to display the window.

The Project window organizes its information into a tree. At the root is your project's compiled image file, because that is the file that everything in the project goes into building. Within this root, you will see three main items: Source Files, Include Files, and Resource Files.

Source Files

The Source Files folder (which looks like a folder only because it's used to group files - it's not actually a directory on your hard disk) contains the source files that make up your project. TADS 3 allows you to divide your source code into any number of separate source files; the compiler processes each source file separately, creating an "object file" from each one, and then links together all of the object files to create your image file. Dividing your source into several different files is often a good way to keep your code organized. Using several separate source files also has the advantage that, when you make a change, the compiler only has to re-compile the file or files you actually changed.

You must add each individual source file in your game to the Source Files folder, and only source files can go here. When you use the Compile command, Workbench will compile each file that appears here, and link together the result to create your image file.

To add a file to the Source Files folder, you can simply drag the file from Windows Explorer, and drop it on the Source Files icon in the Project window. If you prefer, you can right-click on the Source Files icon to display the Project window menu, then select the "Add File" item from the menu. You can also click on the Source Files folder to select it, then open the "Project" menu and select "Add File to Project." All of these different approaches are equivalent; you can use whichever way you find most convenient.

Once you've added a source file, it will appear in the list under the Source Files folder in the Project window. (If you don't see a list, click the little "+" icon next to the Source Files folder to open the folder.) If you want to view one of your source files, simply double-click on the file in the list.

Include Files

The Include Files folder is similar to the Source Files folder, but this folder lists header files only. You don't actually have to add any files here, but Workbench lets you add files here as a convenience. The only reason to add files to this folder is that you can easily open a file from this list by double-clicking on it. You will probably want to add the header files you're using simply to make it easy to view them.

Resource Files

The Resource Files folder is similar to the others, but contains your resource files: JPEG and PNG images, and MIDI, WAV, and MP3 sound files.

The Resource Files folder can contain not only files, but also entire file system directories. To add a directory, you can drag it from Windows Explorer and drop it on the Resource Files folder, or you can use the right-click menu to select the "Add Directory to Resources" item. If you do add a directory, Workbench only displays the folder - it doesn't display the items in the folder. Only the folder is displayed, because Workbench doesn't actually process the folder until you compile your game for release; when you do, it bundles all of the files found in that folder. This allows you to manage your resources in the file system, without having to worry about keeping your project list synchronized as you add, rename, or delete files. Simply add your folder to the project, and Workbench will automatically build an up-to-date bundle each time you compile.

External Resources

In addition to the three folders that are part of every project, you can add one or more "external" resource files to your project. An external resource file is not a resource file in the sense of a JPEG or MP3 - it's a group file that contains an entire bundle of JPEG's, MP3's, and other resources. It's "external" in that it's not part of your image (.t3x) file - it's a separate file that you can distribute along with or separately from your image file.

The primary purpose is to allow you to distribute your game in several different configurations, with a different group of resources in each configuration. There are several instances where you might want to do this; some examples:

To add an external resource to your project, use the "Add External Resource" from the right-click menu in the Project window (or select the same item from the "Project" menu in the main menu bar). This will add a resource file to the list.

Once you've created an external resource file, you can treat it just like the Resource Files folder. Add individual resource files or directories to this folder to include them in this external resource file. Each time you compile for release, the compiler will build a file with the same name as your image file, but with the suffix replaced by ".3r0", ".3r1", and so on, as shown in the Project window.

Each external resource file has an icon to the left of its primary icon. The icon looks like a CD, and either has a big red X through it or not. If you see just a CD icon, it means that the external resource will be included in the installer version of your build; if the red X is showing, the file will not be included in the installer version. If your goal is to build a smaller version for internet distribution, and a larger version for CD-based distribution, you can use this setting to build external resources for the installer. To change the setting, just click on the icon.

Compiling

To compile your game, you must first configure the build settings for your game. Once you configure the settings, TADS Workbench will remember them in your game's configuration (.tdc) file, so you won't need to enter any settings when you actually compile your game.

There are four ways to compile your game, all accessed using the "Build" menu:

The debug log window will display the build status, including the program command lines and any error messages from the compiler and other tools. The build proceeds in the background, so you can continue with other work while the build is running. If you're compiling the debugging version of your game, you cannot, of course, run the game until the build completes, and you cannot start a new build while another build is running.

Going to an Error Line

The debug log window shows any error messages that the compiler produces as it compiles your source code. If the compiler does find errors, you can jump directly to the line containing the error in your source file by double-clicking on the error message in the debug log window.

In order for this to work, your TADS Workbench editor configuration must include a %n option in the editor's command line setting, so that Workbench can communicate the desired line number to your text editor. Notepad, the default editor, doesn't have any way to jump to a specific line; most programmer's text editors, however, do provide such a feature. Refer here for information on configuring TADS Workbench to use your text editor.

Build Settings

Before you build for the first time, you must configure the build settings for your game. Open the "Build" menu, and select "Settings" to open the Build Settings dialog.

The Build Settings dialog is organized into several pages, arranged by function. In most cases, you can use the default settings, but you should scan each page to make sure the settings are suitable for your game.

Build Settings: Include

Directories to search for #include files: This is the list of directories that the compiler will search for files included with #include directives. You don't normally have to add anything here, because the compiler automatically searches both the directory containing your source files and the directory containing the TADS system headers when looking for included files. However, if you're using any additional third-party libraries, you should add to this list the directory or directories where you've installed the header files for those libraries.

Build Settings: Output

Debugging image file: This is the compiled (or "image") file for debugging. You can't change this setting, because it's always the same as the image file that you currently have loaded. This version of the compiled game contains extra information that the TADS Debugger uses to provide source-level debugging. This file is created whenever you use the "Compile for Debugging" command on the "Build" menu.

Note: the compiler does not bundle graphics and sound resources into the debugging version of the game. This makes it faster to compile the debugging version, since the build process skips the resource bundling step. As a result, all of your resource files must be in the same directory as the debugging game file (or subdirectories of the game file directory, if you're using relative paths in the resource names), so that the interpreter can find the resources as external files at run-time. Refer to resource naming conventions for information on how multimedia versions of TADS find resource files.

Release .t3x file: This is the compiled image file that you can release to players. This version of the image file does not contain any symbolic debugging information, so it cannot be used with the debugger; as a result, it's smaller and runs more quickly than the debugging version. This version includes the resources that you included in the "resource files" section of your project window, all bundled into the file, so that you need only distribute this single file to players; the only other thing needed to play your game is the TADS Interpreter. This file is portable to all platforms that have a TADS Interpreter; you don't need to recompile your game to run it on other types of computers. This version of the file is created whenever you use the "Compile for Release" command on the "Build" menu.

Note: This file must use a different name than the debugging game file, so that you don't overwrite the debugging version with the release version when you build the latter.

Executable file: This is an executable application (.EXE) file that contains your release .t3x file, including the bundled resources, bound together with the HTML TADS 3 Interpreter for Windows. You can distribute this single file to players; nothing else is needed to play your game. You might prefer to distribute this form of your game to players who are using Windows, rather than the release .t3x file, because players won't need to install a TADS Interpreter separately. For players who aren't using Windows, however, you'll want to distribute the release .t3x file, because that file is portable to all platforms with a TADS 3 Interpreter; the executable version only works on Windows machines. To build the executable file, open the "Build" menu and select "Compile Application (.EXE)."

Build Settings: Defines

Symbols to #define: This is a list of preprocessor symbols to define when compiling your game. Use the "Add" button to add a new symbol to the list. Each symbol listed here is defined as though you had used a #define preprocessor directive just before the first line of your primary source file.

Symbols to #undef: This is a list of pre-defined preprocessor symbols that you want to undefine. This lets you remove symbols that the compiler normally defines for you. The effect is the same as though you had used an #undef directive just before the first line of your primary source file.

Build Settings: Options

Character Mapping File: Check this box and fill in the field if you want to use a character-map file (a .TCM file). The TADS compiler lets you specify a character mapping file to determine how characters in the file are interpreted. The compiler converts everything to Unicode internally for complete portability; because your source file is not in Unicode, the compiler relies on the character mapping file to figure out how to convert the source code's character set to Unicode.

Additional command-line options: If you need to specify any command-line options that cannot be specified elsewhere in the dialog box, you can enter the text of the options here. Look here for the full set of compiler options. (In most cases, you won't need to put anything here, since all of the common compiler options are all accessible through the dialog without resorting to typing them in here directly.)

Build Settings: Installer

Setup Program: This is the name of the executable application file that will contain the installer for your game. TADS Workbench can create an automatic installation program for your game; this installer will be bundled into the single file named here. You can distribute this file to players, who can install your game on their Windows computers simply by running this installer program. The installer is entirely self-contained, so this is the only file you will need to distribute to players.

Building an installer for your game has several advantages over simply distributing the game executable file or the release .t3x file. Like a game executable, you can distribute the installer as a single, self-contained, stand-alone file, so players won't need to download or install any additional software. Unlike the game executable, you can include additional files, such as a license text file, or a hint file, with the installer; these additional files are bundled into the installer executable, then extracted and installed on the player's computer when the player runs the installer. With the installer version, you can specify a special desktop icon for your game, and the game will be set up in the player's Windows "Start" menu for easy access and better integration into the Windows desktop. Finally, the installer automatically sets up an "uninstall" utility that lets the player easily remove the game when they're finished with it.

To build the installer, after configuring the installer options, open the "Build" menu and select "Compiler Installer."

To enter installer options, you can type the options directly into the text box, or you can use the "Edit" button to use a dialog to enter the settings. The settings in the "Edit" dialog are:

Display Name: This is the name of your game that is displayed to the player during the installation process.

Saved Game Extension: This is the file suffix that your game's saved position files will use. With the standard TADS Interpreter, the suffix is always "SAV". By using a unique suffix for your game, you'll make it possible for the player to restore a saved position and start the game all at once simply by double-clicking on a saved position file on the Windows desktop. To make this possible, the installer will create a file type association for the suffix you specify, so that the Windows desktop will launch your game's executable when the player double-clicks on one of your game's saved position files.

Program Icon: You can specify a Windows Icon (.ICO) file here to use as the desktop icon for your game's executable.

License File: You can specify a text file here. The installer will include this file in your installation package, and display the file to the player during the installation process.

Read-Me file: You can specify a text or HTML file here. The installer will include this file in your installation package, and will automatically open this file for the user to view immediately after the user completes the installation process. You can use this file for any notes or information that you want the user to see right after installing your game. In addition to opening this file after the installation is completed, the installer places an icon for this file in the "Start" menu program group that it creates for your game.

Read-Me Title: If you specify a read-me file, you can use this field to enter the title that you want the installer to display in the "Start" menu for the read-me file. If you don't enter this field, but you do specify a read-me file, the installer will use the name of the read-me file (minus its ".txt" or ".htm" suffix) as the menu name.

Default Program Directory: This specifies the default directory in which your game will be installed on the player's computer. Most people use a subdirectory of "C:\Program Files" for the default value here. The player will be able to override this during installation, but you can make installation much easier and faster for most people by suggesting a suitable default here.

Default Start Menu Folder: This specifies the default name of the Windows "Start" menu folder that the installer will create for your game. As with the default program directory, the player can override this during installation, but a good default will make things easier for most people.

Adding extra files: The "Edit" dialog doesn't provide a means to add extra files to the installer. If you want to include any extra files (for example, you might want to include a text file with hints, or a PDF file showing a map), edit the text box directly. For each extra file, add an extra line to the text box, using this format:

    FILE=file_to_add

Include the full path to each file.

Suggested Directory Layout

You can arrange your source files and compiled game files into any set of directories that suit your working style. We have some guidelines, however, that you might wish to consider:

The easiest way to conform to these guidelines is simply to put all of your files (sources, resources, and compiled games) into a single directory, separate from the TADS program directory. However, some people prefer to organize their files into subdirectories to make them easier to manage; so, we offer this suggested directory layout:

TADS program directory:
    C:\Program Files\TADS 3 Toolkit

Main game directory:
    C:\Games\MyGame

Source file directory:
    C:\Games\MyGame\source

Compiled game directory:
    C:\Games\MyGame\GAM

Image resources (JPEG and PNG files):
    C:\Games\MyGame\GAM\images

Sound resources (MIDI, WAV, and MP3 files):
    C:\Games\MyGame\GAM\sounds









Copyright ©2000 by Michael J. Roberts.