Installation and usage instructions for QTads 1.7.

QTads does *not* use Automake/Autoconf.  It uses qmake instead, which
is better suited for Qt-specific software (I think).  If you don't know
what this is about, ignore me.


IMPORTANT!
==========

Recent versions of GCC are known to crash the T3 VM.  This only seems to
happen with 3.3 and 3.4 versions of GCC, and only on x86 (PC) hardware.
If QTads crashes with a segmentation fault (or similar) when loading a
Tads 3 game, re-build QTads and add the "-fno-strict-aliasing" switch to
the CXXFLAGS variable.  For example:

 qmake CXXFLAGS="[your own options] -fno-strict-aliasing"
 make clean
 make



The quickie
===========

Make sure you have an environment variable called QTDIR that points to
your Qt installation:

  echo $QTDIR

should print something like /usr/lib/qt3.  If not, set this variable
yourself with:

  export QTDIR=/usr/lib/qt3

(replacing "/usr/lib/qt3" with the actual Qt installation directory.)
To build the sources, do:

    $QTDIR/bin/qmake [option1=value option2=value ... optionN=value]
    make
    make install

Everything inside the [] block is optional.

Supported qmake options (cAsE sENsiTiVe):

    BIN_INSTALL  - Installation directory for the QTads executable.
                   Default is /usr/local/bin.

    DOC_INSTALL  - Installation directory for the documentation.
                   Default is /usr/local/share/doc.

    DATA_INSTALL - Installation directory for various data files.
                   Default is /usr/local/share.

    CFLAGS       - Optimization flags for the C compiler.
                   Default is whatever qmake thinks is best.

    CXXFLAGS     - Optimization flags for the C++ compiler.
                   Default is whatever qmake thinks is best.

    BUILD        - Which version of QTads to build (release or debug).
                   Default is release.

Note that the CFLAGS and CXXFLAGS options will override any existing
environment variables with the same name.  However, they will *not*
override nor modify any default compiler flags, so it's perfectly safe
(and recommended) to use them.

Play Tads games:

    qtads [sometadsgame]

The file extension (.gam or .t3) is optional.

If you don't give a filename, QTads will prompt you for one (unless the
prompting has been disabled in the configuration dialog.)



Requirements
============


Window Manager
..............

First of all, I wish to point out that QTads does *not* require
KDE.  It runs in every window manager.  Yes, the recommended
environment is KDE3, but QTads runs just fine without it.
Furthermore, you don't need the KDE libraries installed.  Qt (see
below) is enough.  I received a lot of email regarding this issue, in
the form: "Please make QTads run in Gnome".  QTads does and will
continue to run in Gnome, Enlightenment, IceWM, and any other X11
environment/window manager, or whatever the equivalent is in the case
of Mac OS X.  If QTads won't run on such an environment, you're
probably doing something wrong; feel free to email me for help.


Libraries
.........

QTads requires at least Qt version 3.1.  Development is done with Qt
3.3.1.  Version 2.x won't work (not because it's broken, but because it
lacks some very important features QTads depends upon).

The newest Qt release can be downloaded from Trolltech's site:

    http://www.trolltech.com

Qt binaries for various Linux distributions can be found at the KDE
homepage:

    http://www.kde.org

The Qt library comes in two flavors: a single-threaded version and a
multi-threaded one.  QTads will work fine with either version.

No third-party libraries other than Qt are needed to build and run the
interpreter.


Compiler
........

To compile QTads, you'll need a state-of-the-art compiler.  I recommend
GCC 3.2.1 or higher, but 2.95.x versions are known to work just as
well.  Older compilers may or may not work; most probably they won't.
If you compile QTads on a non-GCC compiler, I would like to know about
it, since no one tried it yet.  I would also like to see error messages
from non-GCC compilers, so I can add support for them (if possible).
Refer to the README file on how to get in contact with me.

You can find instructions on how to download and build GCC at:

    http://www.gnu.org/software/gcc

Source- and binary-packages of various GCC versions can be found at:

    ftp://gcc.gnu.org/pub/gcc/

If you're using Linux, you're lucky.  GCC (the GNU Compiler Collection)
and Qt are included in most (all?) Linux distributions.  If you're not
using Linux, pray that your vendor has included this stuff in the
distribution.  If he didn't, you'll have to download it from the places
mentioned above.  As a last resort, you might find a precompiled QTads
binary that is able to run on your system at the QTads home page:

    http://qtads.sourceforge.net


Disk Space
..........

You'll need about 40MB for building and installing; after the
installation, you can delete the build directory, which will free 38MB.

The executable is about 1MB big.



Detailed instructions
=====================

To install QTads, you'll have to compile it first, and to compile it
you'll have to configure it.  The procedure is very easy and is
described in detail below.


Configuration
.............

First, a "makefile" has to be created, since the "make" utility is used
for building QTads.  The makefile is created automatically with the
following command:

    $QTDIR/bin/qmake

This assumes that there is an environment variable called "QTDIR" that
points to the Qt installation directory.  If that's not the case, you
have to create that variable first.  If Qt is installed in /usr/lib/qt3
for example, do:

  export QTDIR=/usr/lib/qt3

The above command processes the file "qtads.pro".  You don't have to
specify the file in the command line; qmake finds it automaticly.  If
for some reason the automation fails (because you're using an older
version of qmake, for example), simply pass the filename as an
argument:

    $QTDIR/bin/qmake qtads.pro

"qtads.pro" is the project file for QTads.  The project file ensures
that the created makefile is compatible with the "make" version you are
using (which is "GNU Make" for most Linux-systems) and that it contains
build-instructions that your system's compiler can understand.

You can specify where QTads will be installed by passing arguments to
qmake.  For example, if you want the QTads executable to be installed
in /usr/bin, the documentation in /usr/share/doc and the data files to
/usr/share, you should call qmake like this:

    $QTDIR/bin/qmake BIN_INSTALL=/usr/bin DOC_INSTALL=/usr/share/doc \
    DATA_INSTALL=/usr/share

If you don't pass any arguments, the binary will go to /usr/local/bin,
the documentation to /usr/local/share/doc and the data files to
/usr/local/share.  Note that the arguments are case sensitive.

You can also pass optimization flags to qmake, and they will be passed
on to the compiler.  For example, to compile the C sources with "-O3
-march=athlon-xp" and the C++ sources with "-O2 -march=athlon-xp" (if
you happen to own an AMD Athlon XP and a newer version of GCC that
supports this CPU, that is), call qmake like this:

    $QTDIR/bin/qmake CFLAGS="-O3 -march=athlon-xp" CXXFLAGS="-O2 -march=athlon-xp"

(Don't forget to quote the options if they contain spaces, like in this
example.)  If you have environment variables called CFLAGS and
CXXFLAGS, you don't need to use the above options.  But if you do use
them, your environment variables will not be taken into account.

If you're using GCC 3.x, you should add -fno-exceptions to the C++
options, since QTads doesn't make use of C++ exceptions.  You'll save
some RAM and get a smaller executable, which is a Good Thing on low-end
systems.  You may want to check out the GCC docs to see what
optimization options are available; typing "info gcc" on the console
should get you started.

For GCC 3.3.x versions, add "-fno-strict-aliasing" to CXXFLAGS, or else
the interpreter will crash when loading Tads 3 games.  (Probably a bug
in GCC's optimizer, and not in T3's, which has no bugs no bugs no bugs.)

To find out the GCC version you have, type

  gcc --version

in a console or terminal.


Compilation
...........

Now that the makefile has been created, you can compile QTads with the
following command:

    make

(Note that on some systems you might have to type "nmake" if "make"
doesn't work.)  If you have a slow computer, you can go make some
coffee now.  If you have a slow computer and are using GNU C++, you can
go to Colombia, plant the coffee, wait for it to grow and then visit
the FSF folks and hit them on the forehead with a precompiled header.
On the other hand, if you have a very fast computer, you can blink and
proceed with the installation.

Note that during the compilation process you'll see some warnings when
you are compiling the debug version of QTads (at least when you're
using a real compiler, like GCC <grin>).  All of them are generated
from the portable Tads sources which I'm not allowed to modify (or they
wouldn't stay portable, now would they :)  Just ignore them; they're
harmless.  It's just the compiler trying to show you how smart it is.
If you see a warning that is generated by QTads' own sources, please
report it.


Installation
............

To install QTads, type:

  make install

(You'll probably have to login as root first, if you're installing in
a directory where you don't have write-access.  If you're installing
everything in your own home-directory, you don't have to be root.)

This will install QTads on your system and you're ready to play all
those Tads games.  If the above procedure doesn't work for you, drop me
a mail; I'll be very happy to help.  See the README file for
instructions about how to contact me.

Although there is a "uninstall" target in the makefile, it doesn't
work because of a bug in the current version of qmake (as of Qt 3.1.1).
I hope Trolltech will fix it soon.  (Or *I* am doing something wrong
but don't know it.)


Usage
.....

To play a Tads game, just pass the game's filename as an argument to
QTads, like this:

    qtads /usr/local/games/tads/zebulon.gam

The extension "gam" (or "t3" for Tads 3 games) is optional; typing:

    qtads /usr/local/games/tads/zebulon

will also work.  Simply entering:

    qtads

will by default prompt you for a game file.

You might also want to put a link on some kind of "start menu" (or
whatever it's called on the system you're using).  If you're using the
Debian package, it should have been created automatically for you.



MacOS X
=======

OS X should work just like "regular" Unix (using the words "regular"
and "Unix" together sure is funny isn't it).  Nothing special is
required to build the interpreter on OS X.  But since OS X isn't messy
the way Linux is, it might be better to just download the ready-to-run
application bundle instead of building it manually, especially if you
don't have the Qt development tools installed on your system.

Let me say that again:  Without the *development* package of Qt, you
won't be able to compile QTads on your own.  The Qt runtime library is
not enough for this task.  Download the ready-to-run application in this
case.



QTads and KDE
=============

Although KDE is not required to run QTads, it is nonetheless supported
natively.  This is especially true for KDE 3, where QTads will behave
like a native KDE application and will use the current KDE theme
(colors, fonts, style, etc), and will change on the fly whenever you
modify these settings through the KDE Control Center.  For example, if
you're using the "Keramik" style of KDE 3, QTads will also have
"Keramik" buttons, menus, scrollbars, etc, and will use alpha-blending.
For this to work, QTads must be linked against the same Qt library as
KDE (which means that the KDE integration may not work with the
precompiled QTads binaries; sometimes it does though, so try it out if
you like).

In other environments, QTads will always look the same (Win9x like),
except for Mac OS X, where it will look like any other OS X
application ("Aqua").  Note that font anti-aliasing works everywhere
(because this feature is part of Qt, not KDE; if your Qt library has
been compiled with anti-aliasing, QTads will use it automatically).



Internationalization
====================

As of now, QTads supports English and German.  To activate the
German translations, your LANG env. variable must be set to "de_DE" (or
similar).  If you're a German user, then this is probably already the
case on your system; QTads should start up with a German interface.
Most distributions provide some sort of system-tool for setting the
desired language (on SuSE linux it's "yast", for example).

QTads also supports the translations of the Qt library.  For this to
work, the QTDIR environment variable must point to the directory where
Qt is installed (/usr/lib/qt/ for example) and the translation files
must reside in the translations/ subdirectory inside the Qt directory.
For example, the German translation of the Qt library could be
something like /usr/lib/qt/translations/qt_de.qm (the *.ts files are
not needed).  These files are not required to run QTads, but standard
dialogs (like "Open File" or "Font Select") will always be shown in
English if the translation files cannot be found.
