Installation and usage instructions for QTads 1.3a.

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



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


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

First of all, I wish to point out one thing: 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 even need the KDE libraries installed.  Qt (see
below) is enough.  Sorry for being somewhat pedantic about this, but I
recieved 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.


Libraries
.........

QTads requires at least Qt version 3.1.  Development is done with Qt
3.1.1.  Version 2.x won't work (not because it's broken, but because it
lacks some very important features QTads depends upon).  Work is
being done to make it compile with Qt 3.0 (in the past, I made the
wrong assuption that 3.1 is backwards compatible with 3.0, but as it
turned out, this is not the case).  The newest Qt release can be
downloaded from Trolltech's site:

    http://www.trolltech.com

Qt binaries for various Linux distributions (including some older ones,
like SuSE Linux 7.x) can be found at the KDE homepage:

    http://www.kde.org

Most of the Qt packages on this site have been created by the
distribution vendors themselves, so they should work "out of the box".
Note though, that in some cases the vendors have configured Qt very
poorly, so the recommended way is to build Qt by yourself (for example,
the version offered for SuSE Linux 7.2 lacks font anti-aliasing, which
results in very ugly rendering of text).

The Qt library comes in two flavors: a single-threaded version and a
multi-threaded one.  QTads will work fine with either version.  If
you're using KDE 3, the recommended version is the one for which KDE
has been linked against, or else QTads won't be able to communicate
with KDE 3 the way it should; it will use KDE's colors and fonts, but
not its styles ("Keramik", ".NET", etc).  Since KDE is linked against
the multi-threaded Qt library (I don't know if it's possible to use the
single-threaded version with KDE), QTads will use this one by default
(if it exists).  Otherwise, it will fall back to the single-threaded
version.  If you're not using KDE at all, then the above need not
concern you.

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.  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 of 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



MacOS X
=======

Since I don't own a Mac, I don't know if QTads compiles under MacOS X
(it should though; the code only uses Qt and is written in ANSI C++).
Please try it and let me know how it went.  The MacOS X port of Qt,
like the Unix port, is freely available under the GPL; only the Windows
port is proprietary.



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).
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).  Also note that it's
not important *when* QTads has been compiled.  If, for example, you
build and install KDE 3 after QTads has been compiled, and both QTads
and KDE use the same Qt library ("same" means a build using the same
configuration options and compiler), then there's no need to recompile
QTads for KDE 3.



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 will start up with a German interface.

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.



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

Compile and install:

    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.



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, you'll have to create a "makefile", since the "make" utility is
used for building QTads.  This is done with the following command:

    qmake

The above command processes the file "qtads.pro".  You don't have to
specify it 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:

    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:

    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:

    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, 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.


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

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

    make

(Note that on some systems you'll 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 a *lot* of warnings
when you are compiling the debug version of QTads (at least when you're
using a real compiler, like GCC <grin>).  Most 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
mostly harmless.  It's just the compiler trying to show you how smart
it is.


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.)

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 these 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.


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 prompt you for a game file.
