View source for How to build FrobTADS on Mac OS X

===Introduction===

This document describes how to build FrobTADS 0.12 on Mac OS X. Doing this will get you:

* a command line interpreter ("frob") for playing both TADS 2 and TADS 3 games on Mac OS X
* a command line tool ("tadsc") and the necessary support files for developing TADS 2 games on Mac OS X
* a command line tool ("t3make") and the necessary support files for developing TADS 3 games on Mac OS X

FrobTADS 0.12 covers TADS versions 2.5.11 and 3.0.16.

The home page for FrobTADS is http://www.tads.org/frobtads.htm, and a visit there is highly recommended.

Note that the resulting executables - frob, tadsc, t3make - will be platform-specific:
that is, for either Intel or PowerPC Macs, depending on the kind of system you build them on. 
In other words, said executables will not be Universal Binaries.

===Prerequisites===

This document assumes you are using Mac OS X version 10.5 and Apple's XCode development tools version 3.

If you don't already have them, you'll need to download and install the XCode development tools;
see http://developer.apple.com/technology/xcode.html
(Note: XCode is included on a DVD with new Macs, which may save you the download.)

Building FrobTADS requires the use of OS X's command line shell ("the Terminal") -
/Applications/Utilities/Terminal.app - so go and start that program up right away.

===Caveats / disclaimer===

This document is intended as a short-cut: an easy-to-follow, sunny-day recipe.
The official/authoritative documentation for FrobTADS, however, is contained in the doc/ folder 
in the frobtads-0.12.tar.gz file (see below), especially the INSTALL file,
and you should refer to that in case of trouble.

===Preparing the directory structure===

First, let's establish a suitable directory structure for building FrobTADS.
This structure will be rooted in the directory build-frobtads-012/ in your home directory (/Users/'''username'''/).
In subsequent commands, your home directory will refered to as ~ (a common UNIX shortcut for such, and
understood by the Terminal.)

Using the Terminal, issue the following commands:
	
   cd ~
   mkdir build-frobtads-012
   cd build-frobtads-012
   mkdir downloads
   mkdir build
   mkdir results

~/build-frobtads-012/ should now contain the following directories:

   downloads/
   build/
   results/

===Downloading the source packages===

FrobTADS comes as three separate source packages:

* http://www.tads.org/frobtads/frobtads-0.12.tar.gz
* http://www.tads.org/frobtads/frobtads-t2compiler-0.12.tar.gz
* http://www.tads.org/frobtads/frobtads-t3compiler-0.12.tar.gz
	
Download all these into the ~/build-frobtads-012/downloads/ directory.

===Expanding and merging the source packages===

Using the Terminal, issue the following commands to expand the FrobTADS source packages:

   cd ~/build-frobtads-012/build
   tar -zxvf ../downloads/frobtads-0.12.tar.gz
   cd ~/build-frobtads-012/build/frobtads-0.12
   tar -zxvf ../../downloads/frobtads-t2compiler-0.12.tar.gz
   tar -zxvf ../../downloads/frobtads-t3compiler-0.12.tar.gz

Check that ~/build-frobtads-012/build/frobtads-0.12/ now contains:
	
   Common.am
   Frob.am
   Makefile.am
   Makefile.in
   README
   acinclude.m4
   aclocal.m4
   bootstrap
   config/
      *
   config.h.in
   configure
   configure.ac
   doc/
      *
   src/
      *
   t2compiler/
      Makefile.am
      src/
         *
      tads2/
         *
   t3compiler/
      Makefile.am
      Testsuite.am
      src/
         *
      tads3/
         *
      testscripts/
         *
   tads2/
      *
   tads3/
      *

===Preparing to build===

Here we configure things for OS X, and specify that the resulting executables
and support files should end up in ~/build-frobtads-012/results/. 
('''Hint:''' you might want to read the "(Perhaps a simpler way: the default install)" section, 
near the end of the document, at this point.)

Using the Terminal, issue the following commands 
(note that you have to use the explicit path to your home directory in the second command):

   cd ~/build-frobtads-012/build/frobtads-0.12/
   aclocal
   ./configure --prefix=/Users/'''username'''/build-frobtads-012/results

Check that the last command produced a response like this:
		
   checking for a BSD-compatible install... /usr/bin/install -c
   checking whether build environment is sane... yes
   [... SNIPPED...]
   config.status: executing depfiles commands

===Building===

At last, the big moment. This step typically takes several minutes...

Using the Terminal, issue the following commands:
	
   cd ~/build-frobtads-012/build/frobtads-0.12/
   make

Check that the last command produced a response like this:

   make  all-am
   [...SNIPPED...]
   g++  -g -O2   -o frob src/frob-frobappctx.o  [...SNIPPED...] tads3/frob-vmvec.o  -lncurses 

Check that ~/build-frobtads-012/build/frobtads-0.12/ now contains (among many other things) these files:

   frob	
   t3make	
   tadsc

===Installing the executables and support files===

Here we gather up the "net results" of all we've done - the executables and support files - 
into the ~/build-frobtads-012/results/ directory.

Using the Terminal, issue the following commands:

   cd ~/build-frobtads-012/build/frobtads-0.12/
   make install

Check that ~/build-frobtads-012/results/ now contains:
		
   bin/
      frob	
      t3make	
      tadsc
   share/
      frobtads/
         tads2/
            *.t
         tads3/
            doc/
               *
            include/
               *.h
            lib/
               *.t
               extensions/
                  *.t
                  TCommand/
                     *
               adv3/
                  *
               system.tl
            res/
               charmap/
                  cmaplib.t3r
						
And that's it for building FrobTADS. The files in ~/build-frobtads-012/results/ are, essentially, what you need for 
TADS game development on Mac OS X.

Still, there are a couple of more things you'll probably want to do...

===Getting the executables into your PATH===

It would be nice to invoke the executables without having to specify their full path.
E.g., typing <tt>~/build-frobtads-012/results/bin/t3make</tt> every time you want to invoke t3make is hardly practical.

The key here is the PATH environment variable, which defines the list of directories where the Terminal
looks for executables. (You can check the value of PATH by typing <tt>echo $PATH</tt> in the Terminal.)

To get the TADS executables into your PATH, you can either:
* Copy the executables into a directory already included in PATH, or:
* Modify PATH to include the directory where the executables are. This is done by editing the file ~/.bash_profile, adding a line:<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;export PATH='''my/tads/executables/directory''':$PATH</tt><br> and then restarting the Terminal.

===Pointing to the support files in TADS game projects===

The game development executables (tadsc and t3make) need various support files when invoked. The default locations of these support files are determined by the <tt>--prefix=...</tt> option used in the "Preparing to build" section above. So, if built according to this document:

* tadsc will look for its support files in the ~/build-frobtads-012/results/share/frobtads/tads2/ directory.
* t3make will look for its support files in the ~/build-frobtads-012/results/share/frobtads/tads3/ directory.

However, should you decide to move the support files elsewhere, you will have to instruct tadsc/t3make on where to find them:
* For tadsc, this is done via the -i option. See http://www.tads.org/t2doc/doc/tads-c.html for further details.
* For t3make, this is done via the -I and -lib directives in the game project (.t3m) file. See http://www.tads.org/howto/t3start.htm for further details.

===(Perhaps a simpler way: the default install)===

There is a way to avoid messing with PATH and having to explicitly point to the support files.  

If you omit the <tt>--prefix=...</tt> option used in the "Preparing to build" section:
* the executables will end up in the /usr/local/bin/ directory (which should already be in your PATH)
* the support files will end up in the /usr/local/share/frobtads/tads2/ and /usr/local/share/frobtads/tads3/ directories
* the executables will, by default, look for the support files in those directories

Be warned, however, that you'll '''overwrite any existing FrobTADS files in those locations.'''

Also, you'll have to do the install step by: <tt>'''sudo''' make install</tt> (and stating your password.)

===Now what? How to use this stuff?===

For information on writing games with TADS 2, see http://www.tads.org/tads2.htm#docs

For information on writing games with TADS 3, see http://www.tads.org/tads3.htm#docs

[[Category:TADS|FrobTADS on Mac OS X]] [[Category:Interpreter|FrobTADS on Mac OS X]]