Setting Up FrobTADS

Authoring TADS
1

In order to gather some info with which to perhaps tidy up the T3 documentation, I thought I’d try installing FrobTADS on my Mac and document the process. I’ve run into a couple of things that I don’t understand. Hopin’ someone can put me in the picture…

Rather than open a Terminal window and type “t3make -d -f TestGame” every time, I created a .command file, TestGame.command, which contains that text. When I do this with Inform 6, double-clicking the .command file opens a Terminal window and runs the compiler, easy as you please.

But when I do this with my new TestGame.command for TADS, Finder pops up an alert box that complains, “The file TestGame.command” could not be executed because you do not have the appropriate access privileges. To view or change access privileges, select the file in the finder and choose File > Get Info." Okay, I can fix that. Except … fixing it doesn’t work. I change the access privileges so that everyone is read/write, and I get the same error message as before.

Conversely, when I copy a TestGame.command file over from the Inform 6 Games directory and change its text to the t3make command, I don’t get the error message. This .command file runs. And its access privileges are actually more restrictive than those of the file that won’t run. I’d sure like to know what’s going on here, because I’d like to tell new users how to do it if they don’t have a properly set up .command file to start with, but are creating one from scratch.

But wait – there’s more.

Now that I have a .command file that (mysteriously) runs, I double-click it and the Terminal window says, "error: unable to read option file “TestGame.t3m”. I get this same message if I type the text in the .command file manually at the Terminal prompt. But that file is certainly present in the same directory with TestGame.command. There’s no typo in the filename. And it contains exactly the text given in the Getting Started Guide. Well, almost. There seems to be a typo in that text. It says -omygame.t3. It should probably have a space after the -o flag. But adding or removing that space makes no difference. I get the same error message. In any case, the error message isn’t about a problem within the file. The error message says it can’t read the file.

I’ve tried closing the .t3m file in my text editor, just on the off-chance the text editor was hanging onto it and refused to let anybody else touch it. That doesn’t help. I tried adding the #include for adv3.h, which is omitted from the GSG instructions, to TestGame.t. That doesn’t help either.

Setting up FrobTADS is easy, I’m sure – once you know what you’re doing. Can anyone help me troubleshoot this stuff so I can document the steps? Thanks hugely!

2

Sorry, I’m not a Mac user, but rather a Linux user. But since Mac is Unix-based, isn’t the problem you must give the file executable permission rather than read or write?

Desktop icon could run the command in a wrong directory. Try something like “cd /correct/directory && t3make -d -f TestGame.t3m”. Or try “pwd” command to show actual directory in terminal.

3

Files on Unix systems (and Mac OS X is a Unix system) don’t only have read and write permissions, but as tomasb mentioned, they also have execute permissions. It’s different from Windows where the file extension defines if a file is executable or not (for example a file extension of *.exe, *.cmd or *.bat tells the system that it can be executed). Unix doesn’t use file extensions for that. It uses a permission flag. So just like you can make a file “writable” or “readable”, you can also make it “executable.”

I don’t know why Apple does not provide a way to mark files as being “executable” in the Finder. I just tried it myself and I can’t find any way in the “Get Info” dialog to make a file executable. But as with Linux (or other Unix systems), you can mark a file as being “executable” with the following command:

chmod +x filename

So in your case:

chmod +x TestGame.command

(To remove the “executable” flag again, you would use “-x” instead of “+x”.)

The reason your other .command file is working when copying it, is because that file already has the “exec” flag set on it, and that is preserved when copying.

Edit:
Btw, the FrobTADS installer on tads.org is still version 1.0, which means it supports TADS 3.0.18.1. You can find a test version of FrobTADS 1.1 with 3.1.0 support here:

foss.aegean.gr/~realnc/FrobTADS-1.1.dmg

Note that it needs Mac OS X 10.6 and higher (due to the new network functionality in TADS 3.1.) It won’t work with OS X 10.5.

4

Thanks, Nikos! With your help, I was able to put together a fairly complete set of instructions for new users (see below). If anyone has suggestions on how this material could be further clarified, feel free to jump in. I’m hoping that perhaps this material can be included in a future version of the Getting Started Guide. I don’t know what differences Linux users may encounter, but if I were Eric, I’d separate that section of the GSG into three subsections by OS, so that people can jump to whatever section they need.

–JA

P.S.: I know the download I have is only for 3.0.18. That doesn’t concern me greatly at the moment. At some point in the future it will become relevant, I’m sure, but maybe by then the standard download will be 3.1.

Reasonably coherent instructions for setting up TADS 3 on your Macintosh:

  1. Download FrobTADS, double-click on the .dmg file, and run the installer.

  2. Create a directory to hold your projects, and a subdirectory within it to hold your first project. For example, in Documents, create TADS. In TADS, create a MyGame folder.

  3. In the folder for your first project, create a folder called obj. This will hold the object files created by the compiler while it’s running. You won’t need to be concerned about anything in this folder – it will take care of itself.

  4. Using a text editor, create a .t3m file. For convenience, give the .t3m file the same name as the project – perhaps MyGame.t3m. Copy the following text into your new .t3m file and save the file to the project folder:

-DLANGUAGE=en_us -DMESSAGESTYLE=neu -Fy obj -Fo obj -o MyGame.t3 -lib system -lib adv3/adv3 -source MyGame
Replace “MyGame” in the code above with the name of your actual game, if it’s different.

  1. Open a Terminal window. The Terminal program is located in Applications > Utilities. You may want to make an alias for it and drag it into your Dock.

  2. Create a starter game file, again as a text file, and save it to the MyGame directory. Your starter game should look more or less like this:

[code]#include <adv3.h>
#include <en_us.h>

gameMain: GameMainDef
initialPlayerChar = me
;

versionInfo: GameID
name = ‘My First Game’
byline = ‘by Bob Author’
authorEmail = ‘Bob Author bob@myisp.com’
desc = 'This is an example of how to start a new game project. ’
version = ‘1’
IFID = ‘b8563851-6257-77c3-04ee-278ceaeb48ac’
;

firstRoom: Room ‘Starting Room’
“This is the boring starting room.”
;

+me: Actor
;[/code]
7) In the Terminal, use the cd (change directory) command to navigate to the folder where your game files are stored. For instance, you might type ‘cd Documents/TADS/MyGame’ and then hit Return.

  1. While the Terminal is logged into this directory, you can compile your game using this command:
t3make -d -f MyGame

If all goes well, you should see a string of messages in the Terminal window, and a new file (MyGame.t3) will appear in the MyGame directory. This is your compiled game file. If you’ve installed an interpreter program that can run TADS games, you’ll be able to double-click the .t3 file and launch the game so as to test your work.

Alternatively, you can run the game directly in the Terminal by typing ‘frob MyGame.t3’ and hitting Return.

  1. Instead of typing the t3make command every time you want to compile your game, you can create a .command file in your project folder and then double-click this file. Double-clicking the .command file will launch Terminal and pass the text in the .command file to Terminal.

However, when you try this, the Macintosh is quite likely to object that you don’t have permission to execute the .command file. There seems to be no way to fix this using the Info box (which is opened using Cmd-I). You’ll have to do it from the Terminal. Navigate, as before, to the directory where your .command file is located, and type this into the Terminal:

chmod +x MyGame.command
Again, substitute the name of your actual .command file. The chmod instruction with a +x flag will make the .command file executable. Now you can double-click it to compile your game – but only if Terminal is already logged into the game’s directory. If no Terminal window is open, that won’t be the case. To remedy this problem, add the cd line to the beginning of the .command file, so that the .command file looks something like this (substituting the name of your directory and game file):

cd Documents/TADS/MyGame t3make -d -f MyGame

5

One thing you could improve is the naming of the t3m file. If you name it “Makefile.t3m”, then you can build your game with simply entering “t3make” (or “t3make -d” for a debug build) and there’s no need to use “-f MyGame.t3m” at all. If t3make can find a file named “Makefile.t3m” in the current directory, it will use it automatically.

Furthermore, the makefile itself can be simplified to this:

[code]-DLANGUAGE=en_us
-DMESSAGESTYLE=neu
-Fy obj -Fo obj
-o MyGame.t3
-lib system
-lib adv3/adv3

List your game’s source files here

MyGame[/code]

That is, you don’t need the “-source” option and it makes it clearer that your game doesn’t need to be put in a single *.t file. You could as well have something like:

[code]-DLANGUAGE=en_us
-DMESSAGESTYLE=neu
-Fy obj -Fo obj
-o MyGame.t3
-lib system
-lib adv3/adv3

List your game’s source files here

main
verbs
kitchen
livingroom
[/code]

Having separate source files is very helpful as your game grows bigger. Every time you create a new source file, you simply append it at the end of the makefile.

Also, it’s probably a bad idea to specify an IFID. Let the compiler generate its own. Otherwise people might keep the example IFID and as a result we might have games out there using the same one.

6

I’m running 10.6.8. The 3.1 compiler seems to work for me (I tested it with the new <> syntax), but neither Zoom 1.1.5 nor CocoaTads 0.2 can play the resulting game. It seems to be playable only from the Terminal. Zoom was able to run a game compiled under 3.0.18, so maybe there’s something going on with the new VM features … dunno.

Zoom’s error message is “VM Error: error reading file”. Ditto for CocoaTads.

I get the same error when attempting to load into Zoom a game compiled with 3.1 for Windows. (I’m running Workbench under Crossover on my Mac – haven’t tried it with a game actually compiled on my Windows machine, but the compiled game runs under the terp that’s bundled with Workbench.) So apparently this is not a problem with FrobTads, it’s a problem with Zoom. I’ll alert Andrew Hunter.

7

Every interpreter must be updated to the new version of TADS to be able to play games compiled for TADS 3.1. There were changes to VM.

8

tomasb is correct. To run games that were compiled with a v3.1 compiler, you need at least a v3.1 interpreter.

I will release a new QTads version soon, and my guess is that Charles shouldn’t take too long with CocoaTADS either.

9

You know, the FrobTADS page (tads.org/frobtads.htm) is a bit confusing for the newcomer, or at least for OS X users who don’t have an IDE option. It says not a word about the compilers being included in the install–it refers only to the interpreter. I remember having looked at this page before and concluding that there must not be any option for Mac users after all. The new widget that asks which OS you’re running and then tells you what software to use is helpful in this regard, largely because it prevents you from ever getting to the confusing FrobTADS product page.

Anyway: Jim, I took the opportunity of the new release to try out your instructions. They worked great, but I did get hung up by one little thing. Step 6

should probably mention that the starter game file must have a .t extension.

–Erik

10

Yes, it should be a bit clearer and mention that it’s a compiler suite rather than just an interpreter. I’ll send a new description to Mike.

11

Thanks–and for all your work on this and QTADS as well!

–Erik