The GGZ Gaming Zone - Client Setup
==================================

Installation Requirements for the release 0.0.14
------------------------------------------------

The GGZ Gaming Zone client is built from three separate packages
(these may be available as an integrated package in the future), upon
which any number of game clients may be installed.  It is important
that each package be built and installed in the proper sequence in
order that all library dependencies are properly resolved.  For
example, you must build and install the libggz package before building
ggz-client-libs.  The reason things are packaged this way is that our
libraries will change only rarely once they have stabilized, so we
will be able to release a new version of a client or game module
without requiring every subsystem to be replaced anew.

If you are missing a package, they are freely downloadable in source
format (as well as precompiled or preconfigured packages for a number
of GNU/Linux distributions and BSD systems) from:

http://ggzgamingzone.org/releases/latest/

The packages have been tested on a variety of systems, including
Linux, FreeBSD and Solaris.  It should work on pretty much any type of
UNIX system that supports X Windows and sockets, though it may require
some changes in order to work.  We will be glad to assist anyone who
wishes to port the software to other platforms.
Windows users can use either the native Windows client ports (might be
outdated) or the newer Cygwin packages.

For both Windows users and others, the GGZ Java efforts provide an applet
which can be used to play GGZ games in the browser, without any installation
at all! The Java package can still be installed locally however.

The remainder of this document assumes that you are installing from
source code.  If you are installing pre-compiled packages, please keep
in mind two things:

1) The order of installation should be the same as when installing from
   source.  Dependencies should enforce this automatically.

2) If you are performing an upgrade, make sure that you obtained the
   upgrade from the same location so that directory location
   requirements are not broken.  If you obtain your packages from the
   GGZ homepage (noted above) you will always be safe in that regard.


General Installation Guidelines
-------------------------------

Client packages should be installed in this order:
   libggz
   ggz-client-libs
   ggz-xxx-client (where xxx is the user interface the client supports)

You do not need to install all of the client frontends, only the one
for your preferred environment.  Following this, the game packages
(ggz-xxx-games) and/or individual games may be installed.

For most packages, the installation is as simple as:

./configure
make
make install (as root)

You may also need to update the shared library cache, eg:

ldconfig /usr/local/lib  (as root, and assuming --prefix was not specified)

Note that the installation defaults to the /usr/local hierarchy. If
you prefer to install it under /usr, add

--prefix=/usr --sysconfdir=/etc

to all of the configure scripts below.  The source packages are
relocatable, so you can also install them inside your home directory,
if you don't have system-wide permission.

Step by step instructions follow.  For more detailed installation
instructions, please read the INSTALL file that accompanies each of
the packages.


Installing libggz
-----------------

Unpack the libggz sources.  They should extract into a directory
named libggz-X.X.X.  Enter that directory and run the following
commands:

./configure
make
make install (as root)

This will install the libggz library under /usr/local.  You may also
need to run ldconfig (as root) on some systems.

The following important features exist:
--disable-debug: omit debug code
--with-gcrypt: enable hash functions
--with-tls: enable encryptions functions
--enable-anl: enable asynchronous resolver functions


Installing ggz-client-libs
--------------------------

Before installing ggz-client-libs, you must have the expat
library installed (the previous dependency popt is no longer
required).  You may obtain it from

http://prdownloads.sourceforge.net/expat/

Unpack the ggz-client-libs sources.  They should extract into a
directory named ggz-client-libs-X.X.X.  Enter that directory and run
the following commands:

./configure
make
make install (as root)

This will install the GGZ client libraries and the ggz-config tool under
/usr/local.  You may also need to run ldconfig as root on some systems.


Gtk Client Installation
-----------------------

The Gtk+ client requires that the Gtk+ libraries 2.X be
installed. These can be downloaded from http://www.gtk.org.
We recommend the latest stable version (2.6) to be able to use
the new stock icons.

Unpack the ggz-gtk-client sources.  They should extract into a
directory named ggz-gtk-client-X.X.X.  Enter that directory and run
the following commands:

./configure
make
make install (as root)

This will install the gtk client under /usr/local.


KDE Client Installation
-----------------------

The KDE client requires that the KDE libraries 3.X be installed.
These can be downloaded from http://www.kde.org.  We recommend the
latest stable version, 3.5.1.  As KDE depends on Qt, you will need Qt
version >= 3.0 (3.3.5 is recommended as it is the version which
KDE 3.5 development was based on).

Unpack the ggz-kde-client sources.  They should extract into a
directory named ggz-kde-client-X.X.X.  Enter that directory and run
the following commands:

Typical Installation:
./configure
make
make install (as root)

This will install the KDE client under your KDE installation.  You may
also need to run ldconfig as root on some systems.
Make sure to use the same configuration prefix as KDE does, otherwise
no menu entries will show up, and programs might not work as expected.
Advanced users can use the KDEDIRS environment variable.


GNOME Client Installation
-------------------------

The GNOME client requires that the GNOME libraries 2.X be installed.
You can get them from http://www.gnome.org. The recommended version
is GNOME 2.8.0.

Unpack the ggz-gnome-client sources.  They should extract into a
directory named ggz-gnome-client-X.X.X.  Enter tjat directory and run
the following commands:

./configure
make
make install (as root)

You will then find the GNOME client under /usr/local.


Gtk/KDE/SDL Games Installation
------------------------------

Remember that all game modules can be used with any client.  Just
because you're using one frontend for your client doesn't mean you
can't use the games for the other frontend.

Whether you are installing a single game, or the full gtk-games or
kde-games or sdl-games package, the instructions are the same.
The ggz-config program must be on the path, and it will automatically
set all the proper installation directory options for you.

Typical Installation:
./configure
make
make install (as root)


Troubleshooting/Tips
--------------------

1) Remember, if you are going to be altering the locations of files in
   ggz-client-libs, you should uninstall all client and game packages
   first.  If you are changing ONLY the GGZCONFDIR, then it is
   possible to simply move the ggz.modules file to the new location
   after reinstalling ggz-client-libs - this will save you from
   recompiling all of the clients and games.

2) Both libggz and ggz-client-libs require you to run ldconfig after
   installing!  The same applies to the kde-client package.

3) Always use the 'make (un)install' script to add or remove a game client.
   This insures that the ggz-config program will update ggz.modules to note
   the presence of the game module.

4) If you can't launch a game, execute this command to view the ggz.module
   file that is being used by the programs:
      less `ggz-config --configdir`/ggz.modules
   You can then see if the game you are attempting to run is even present
   in the *Engines* list in the [Games] section.

5) Do not manually edit the ggz.modules file unless you are quite certain
   that you know what you are doing.  This file is meant to be completely
   maintained by the ggz-config program which should automatically be launched
   by the (un)installation scripts.

6) Severe compilation or install issues should be brought up with the GGZ
   maintainers.  You can either contact us on the ggz-dev mailing list or
   via the bug tracker accessible from our developer page
   (http://dev.ggzgamingzone.org/) - A link to join the mailing
   list is also available here.

7) Once you have everything compiled you need a server to connect to!  There
   is a permanent server installed at ggz://live.ggzgamingzone.org (Germany)
   on port 5688.
   Check the FAQ on our webpage (http://ggzgamingzone.org/) for any other
   permanent servers that may get setup.

8) If you are compiling from CVS and are getting weird errors during
   the compilations, make sure you have the correct version of each
   build tool. The following are known to cause problems:
     libtool < 1.4
     automake 1.5d or 1.6 or 1.7
   The recommended compiler is gcc 4.x, although many other versions
   (including 2.95 or previous or later 3.x) should work as well
   (see point 9 below).
   On non-GNU systems, use gmake rather than make.

9) All C++ code must be compiled with the same compiler. This does currently
   affect the KDE packages of GGZ.  It means that if your KDE and Qt has been
   compiled with gcc 2.9x, you cannot compile ggz-kde-client or ggz-kde-games
   with gcc 3.  The reverse is also true.