Difference between revisions of "How to build FrobTADS on Mac OS X"

From IFWiki

m
(→‎Introduction: Mention installer package.)
 
(4 intermediate revisions by one other user not shown)
Line 1: Line 1:
This is a draft version, and very much a work in progress... feedback is welcome indeed...
+
===Introduction===
  
===Introduction===
+
(Note that FrobTADS now provides an installer for Mac OS X 10.3.9 and newer. You should be able to find a DMG download on the [http://tads.org/frobtads.htm FrobTADS homepage] and on the [http://www.ifarchive.org/indexes/if-archiveXprogrammingXtads3Xexecutables.html IF Archive].)
  
 
This document describes how to build FrobTADS 0.12 on Mac OS X. Doing this will get you:
 
This document describes how to build FrobTADS 0.12 on Mac OS X. Doing this will get you:
Line 38: Line 38:
  
 
First, let's establish a suitable directory structure for building FrobTADS.
 
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>).
+
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
 
In subsequent commands, your home directory will refered to as ~ (a common UNIX shortcut for such, and
 
understood by the Terminal.)
 
understood by the Terminal.)
Line 65: Line 65:
 
* http://www.tads.org/frobtads/frobtads-t3compiler-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.
+
Download all these into the ~/build-frobtads-012/downloads/ directory.
  
 
===Expanding and merging the source packages===
 
===Expanding and merging the source packages===
Line 77: Line 77:
 
   tar -zxvf ../../downloads/frobtads-t3compiler-0.12.tar.gz
 
   tar -zxvf ../../downloads/frobtads-t3compiler-0.12.tar.gz
  
Check that ~/build-frobtads-012/build/frobtads-0.12 now contains:
+
Check that ~/build-frobtads-012/build/frobtads-0.12/ now contains:
 
 
 
   Common.am
 
   Common.am
Line 119: Line 119:
  
 
Here we configure things for OS X, and specify that the resulting executables
 
Here we configure things for OS X, and specify that the resulting executables
and support files should end up in ~/build-frobtads-012/results.
+
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  
 
Using the Terminal, issue the following commands  
Line 126: Line 128:
 
   cd ~/build-frobtads-012/build/frobtads-0.12/
 
   cd ~/build-frobtads-012/build/frobtads-0.12/
 
   aclocal
 
   aclocal
   ./configure --prefix=/Users/<MYUSERNAME>/build-frobtads-012/results
+
   ./configure --prefix=/Users/'''username'''/build-frobtads-012/results
  
Check that the last command produced an response like this:
+
Check that the last command produced a response like this:
 
 
 
   checking for a BSD-compatible install... /usr/bin/install -c
 
   checking for a BSD-compatible install... /usr/bin/install -c
Line 149: Line 151:
 
   [...SNIPPED...]
 
   [...SNIPPED...]
 
   g++  -g -O2  -o frob src/frob-frobappctx.o  [...SNIPPED...] tads3/frob-vmvec.o  -lncurses  
 
   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:
 
Check that ~/build-frobtads-012/build/frobtads-0.12/ now contains (among many other things) these files:
Line 175: Line 176:
 
   share/
 
   share/
 
       frobtads/
 
       frobtads/
      tads2/
+
        tads2/
        *.t
+
            *.t
      tads3/
+
        tads3/
        doc/
+
            doc/
            *
+
              *
        include/
+
            include/
            *.h
+
              *.h
        lib/
+
            lib/
          *.t
 
            extensions/
 
 
               *.t
 
               *.t
               TCommand/
+
               extensions/
 +
                  *.t
 +
                  TCommand/
 +
                    *
 +
              adv3/
 
                   *
 
                   *
            adv3/
+
               system.tl
               *
+
            res/
            system.tl
+
              charmap/
        res/
+
                  cmaplib.t3r
            charmap/
 
              cmaplib.t3r
 
 
 
And that's it for building FrobTADS. The files in ~/build-frobtads-012/results/ are what you need for  
+
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, though you'll probably want to copy them to somewhere more permanent and suitable.
+
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 do I use this stuff?===
+
===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 2, see http://www.tads.org/tads2.htm#docs

Latest revision as of 05:39, 29 July 2011

Introduction

(Note that FrobTADS now provides an installer for Mac OS X 10.3.9 and newer. You should be able to find a DMG download on the FrobTADS homepage and on the IF Archive.)

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:

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 ~/build-frobtads-012/results/bin/t3make 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 echo $PATH 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:
        export PATH=my/tads/executables/directory:$PATH
    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 --prefix=... 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:

(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 --prefix=... 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: sudo make install (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