The Beginner's Guide to Adonthell
                    
                    
Written by Andrew Henderson <hendersa@db.erau.edu>
19 February 2000


*******************
* 0.0 - CHANGELOG *
*******************

* 30 May 2008 - Kai Sterker <kaisterker@linuxgames.com>
  Updated for v0.3.5

* 24 October 2004 - Kai Sterker <kaisterker@linuxgames.com>
  Updated for v0.3.4

* 17 September 2002 - Kai Sterker <kaisterker@linuxgames.com>
  Updated for v0.3.3

* 08 February 2002 - Kai Sterker <kaisterker@linuxgames.com>
  Added Building RPM's Howto

* 12 January 2002 - Kai Sterker <kaisterker@linuxgames.com>
  Added Fullscreen Howto


****************************
* 1.0 - GUIDE INTRODUCTION *
****************************

Welcome to the world of Adonthell! Most software packages for Linux
tend to throw a lot at an unexperienced user when it comes to
installation. We know that not everyone is a Linux or Unix guru, not
everyone knows how to use gzip and tar, and that asking for step-by-
step installation instructions is not too much to ask for. So, we've
created this guide to get you rolling with as little hassle as
possible.

We've made this software distribution as easy to install as we could,
but we can't automate everything for you. You'll have to build and
install a few libraries that Adonthell relies on, then build the
Adonthell game itself.

If you feel that you don't need to have anyone hold your hand during
the installation process, just read the INSTALL file in this
directory for the standard install information. If you think you
need a little help or are having problems, then read on.

We're making a few assumptions. Take a quick look at them and see if
you match:

- You have a 2.x Linux kernel installed. If you aren't, ask the Linux
guru who installed the 1.x kernel to upgrade, since you probably won't
be able to build the Adonthell software on it.

- You have access to a superuser account (such as root). You'll need
the superuser permissions in order to install the libraries needed by
Adonthell. If you don't have these permissions, bribe your system
administrator to install them for you. Twinkies work well as bribes.
So do Doritos.

- You are running X-windows with a 16-bit color depth. If you aren't,
Adonthell is going to run slow as it compensates for the difference in
color depth. We can compensate for 8, 24, or 32 bit color depths only.
If you can only run in 16 color (4-bit) mode, you're out of luck. Sorry
again.

- You have C/C++ development tools (gcc, ld, etc.) installed on your
system, as well as the basic utility programs 'tar' and 'gzip'.
Practically every Linux installation will install these programs by
default. If you don't have these tools, you've got bigger problems
than just trying to get Adonthell to run.

- You have a sound card configured and running under Linux. If you
aren't, you'll miss out on the music and sound effects, but will still
be able to play the game. As a bonus, though, there is one less library
you'll have to download and install.

******************************************
* 2.0 - OVERVIEW OF THE BEGINNER'S GUIDE *
******************************************

Here is a quick outline of the steps we are going to follow to install
Adonthell:

* Installing the required libraries
  - Downloading the libraries
  - Installing the libraries
  - Configuring your system to use the libraries

* Building the Adonthell source code
  - Downloading the Adonthell source and data package
  - Building the source package
  - Installing Adonthell

* Running Adonthell

* Questions/Help

* Fullscreen Howto

* Building RPM's Howto

*******************************************
* 3.0 - INSTALLING THE REQUIRED LIBRARIES *
*******************************************

There are four libraries that Adonthell depends on. Two of these
libraries are required, one is optional. The three REQUIRED libraries 
(and where they can be downloaded from) are:

1. The Simple Directmedia Layer (SDL) library, version 1.2 or later.

    http://www.libsdl.org/

2. Python, version 2.0 or later.

    http://www.python.org/

3. Freetype, version 2.0 or later.

    http://www.freetype.org/

4. SDL_ttf, version 2.0 or later.

    http://www.libsdl.org/projects/SDL_ttf

Sound support under Adonthell is optional (but highly recommended!!).
We suggest building Adonthell with sound support if you have a sound
card configured to run under Linux. To do that, you'll need to build
and install another library:

5. Ogg Vorbis, version 1.0rc3 or later

    http://www.xiph.org/ogg/vorbis/download/

6. SDL Mixer, version 1.2 or later

    http://www.libsdl.org/projects/SDL_mixer

*****************************
* 3.1 - INSTALLING BINARIES *
*****************************

All of these libraries might already be part of your distribution,
or at least available as binary package on the respective website.

The package names might differ slightly on your distribution, but
the following list should help you to find all required packages:

For SDL you will need
    SDL-1.2
    SDL-devel-1.2
    libSDL_mixer-1.2
    libSDL_mixer-devel-1.2
    libSDL_ttf-2.0
    libSDL_ttf-devel-2.0

for python
    python2-2.2
    python2-devel-2.2

for freetype
    freetype2
    freetype2-devel

and for Ogg Vorbis
    libogg-1.0
    libogg-devel-1.0
    libvorbis-1.0
    libvorbis-devel-1.0
    
    
********************************
* 3.2 - INSTALLING FROM SOURCE *
********************************

The following steps show how to install the Python, SDL, Freetype and 
Ogg Vorbis libraries from source code. You may install Python, the SDL 
library, Freetype and Ogg Vorbis in any order.

Ogg Vorbis itself consists of two libraries: libogg and libvorbis
that have to be installed in this order.


Step #1: Download the source code of each library to a convient
directory. We suggest downloading to /usr/local/src (if you want to
keep the library source around after you've built it) or /tmp (if
you don't).

Step #2: Decompress the tar.gz file. Do this by typing:

	tar -xzf SDL-x.x.x.tar.gz           (for SDL)
		    or
	tar -xzf Python-x.x.tar.gz          (for Python)
		    or
	tar -xzf libogg-x.x.x.tar.gz        (for libogg)
                    
        etc. 

... where the x's are the version numbers of the file you
downloaded. A new directory will be created in the current directory
with the same name as the tar.gz file (minus the .tar.gz extension).

Step #3: Build and install the library. Do this by changing into the
newly created directory and typing:

	./configure
	make
	make install

For 'make install' you have to be logged in as superuser (i.e. root).

Step #4: While logged in to a superuser account (i.e. root),
configure the system linker configuration files to find the newly
installed library. Do this by typing:

	ldconfig

Repeat these 4 steps for each library you want to install. If all
went well, you now at least have Python, SDL, and Ogg Vorbis 
installed and configured in your system.


******************************************
* 4.0 BUILDING THE ADONTHELL SOURCE CODE *
******************************************

Now that the required libraries are built and installed on your
system, you need to build the Adonthell program itself. The
latest version of Adonthell is 0.3.5. You can download it from the
Adonthell website: http://adonthell.linuxgames.com/download/.


The steps for installing Adonthell are similar to the steps for
installing the libraries above:

Step #1: Download the Adonthell source and data tar.gz files to 
a convenient directory.

Step #2: Decompress the tar.gz files. Do this by typing:

	tar -xzf adonthell-0.3.x.tar.gz
	tar -xzf wastesedge-0.3.x.tar.gz	

Two new directories will be created in the current directory, named
"adonthell-0.3.x" and "wastesedge-0.3.x". Complete step #3 and #4 for 
both directories.

Step #3: Build Adonthell. Do this by changing into the newly created 
directory and typing:

	./configure
	make

A successful configure will produce an output like this:

	Adonthell v0.3.5

    SDL ....................... : 1.2.7
    Python .................... : 2.3
    Python debugging .......... : no
    Ogg music ................. : enabled
    Building editors .......... : no
    Building API doc .......... : no
    Data directory ............ : /usr/local/share/adonthell

If everything configured and built with no errors (which it should,
if the SDL libraries were correctly installed), Adonthell will now
be compiled and ready for use. If you installed Ogg Vorbis, the 
configure script will detect it and configure the program to play 
music automatically.

Step #4: Install Adonthell. Finally, you can log in as root and type

	make install

to copy the Adonthell binary to /usr/local/bin and the game data 
to /usr/local/share/adonthell.


*************************
* 5.0 RUNNING ADONTHELL *
*************************

After building the Adonthell source, an executable named "adonthell"
will be created and installed in /usr/local/bin. After installing the
data package, a script called 'adonthell-wastesedge' will be placed
there as well. You can launch Adonthell either by typing

	adonthell-0.3 wastesedge

or by running the script:

	adonthell-wastesedge

If the game engine and data have been correctly installed, you'll
find yourself in the main menu. Here you can begin a new or continue
an older game. The arrow keys let you move the cursor, and space 
selects an option.


**********************
* 6.0 Questions/Help *
**********************

Q: Why do I get background music, but never any sound effects?

A: Full sound effect support is in the code, and some sound effects
are even loaded into memory when the game is executed. Currently, no
events trigger sound effects, so you won't hear any (excepted those
related to GUI events).


Q: The configure script claims it cannot find SDL (or Ogg Vorbis or
GTK+) on my system, although I know it is there.

A: If you have installed precompiled packages (e.g. RPM'S) of those
liraries, you most likely have to install the corresponding -devel
packages (e.g. SDL-devel.rpm). They should be available where you
obtained the non-devel/runtime packages.

On some systems, it might be necessary to recreate the configure
script to work correctly. Do this by typing './autogen.sh' inside
the adonthell-0.3.x directory.


Q: While compiling the Adonthell source code I get an error similar
to the following:

adonthell: error in loading shared libraries: libSDL-1.2.so.0:
cannot open shared object file: No such file or directory

A: You either didn't install the library that the error message is
complaining about or you forgot to type the command 'ldconfig'
as a superuser account (i.e. root) after you installed the library.


Q: When I run Adonthell in fullscreen mode I get a tiny window with
a large black border around.

A: See the FULLSCREEN.howto file for help.


Q: I have a problem that isn't listed above. Where can I go for
help? How do I contact you?

A: Adonthell has three public mailing lists to provide support, take
suggestions, and interact with the users of the Adonthell software.
Any requests for help can be directed to the tech support manager.
To report bugs, please write to the Adonthell developer mailing list. 
There is usually a fairly short response time for any request of help.

Tech support manager:	

    http://savannah.gnu.org/support/?group_id=702

The mailing list addresses are:

General topic list:	adonthell-general@nongnu.org
Developer list:		adonthell-devel@nongnu.org
Artwork list:		adonthell-artwork@nongnu.org

You can subscribe to these mailing lists by going to the URL:
    
    http://adonthell.linuxgames.com/contact/mailinglist.shtml

If you'd rather e-mail an Adonthell team member directly, you can get
a list of contacts for the team from the Adonthell web page at:
    
    http://adonthell.linuxgames.com/development/team.shtml


************************
* 7.0 Fullscreen Howto *
************************

This section has been moved to a file called FULLSCREEN.howto.


****************************
* 8.0 Building RPM's Howto *
****************************

Normally, you don't have to do this (as you can download premade
binaries from our website), but if you want to make your own
package for some reason or another, here is the procedure.

Adonthell is already prepared for building RPM packages. The only
requirements you have to meet is the ability to compile Adonthell
from the sources; the larger part of this Guide deals with that. 

Once you are able to compile Adonthell, there are three more steps
to complete.

Step #1: Copy adonthell-0.3.x.tar.gz to /usr/src/packages/SOURCES/
If you do not have the source archive, because you obtained the 
sources through CVS, you can build it by typing

    make dist
    
in the adonthell-0.3.x/ directory.

Step #2: In the adonthell-0.3.x/ directory, run

    configure 

to create the adonthell.spec file.

Step #3: Still in the adonthell-0.3.x/ directory, run

    rpm -bb adonthell.spec
    
This command will compile Adonthell from the sources you placed in
/usr/src/packages/SOURCES/ and then build a RPM package from the
executables resulting from that compilation. They will end up in
/usr/src/packages/RPMS/i386/.

Voila, if all went well you'll now have a RPM package you can install
on your box in the usual way, or distribute among your friends.


*********************************************************************
* That's it! Enjoy the game engine and let us know what you think!! *
*********************************************************************
					- The Adonthell Team