______   ___    ___
    /\  _  \ /\_ \  /\_ \
    \ \ \L\ \\//\ \ \//\ \      __     __   _ __   ___ 
     \ \  __ \ \ \ \  \ \ \   /'__`\ /'_ `\/\`'__\/ __`\
      \ \ \/\ \ \_\ \_ \_\ \_/\  __//\ \L\ \ \ \//\ \L\ \
       \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
	\/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
				       /\____/
				       \_/__/


		 Unix-specific information.

	 See readme.txt for a more general overview.

   Also see docs/build/linux.txt for Linux-specific information.



====================================
============ Unix notes ============
====================================

   On Linux you have two different system drivers -- one for running using 
   X, and one for running without X. This file describes the X version, 
   which should in theory be totally portable to any Unix variant. For 
   information about the Linux-specific console routines, see
   docs/build/linux.txt.



===========================================
============ Required software ============
===========================================

   Since you are using a Real Operating System, the chances are that you 
   already have all the necessary development tools, at least for compiling 
   and installing the library. However, you may also need autoconf if you 
   make any changes that require you to regenerate the configure script.



============================================
============ Installing Allegro ============
============================================

   If you downloaded Allegro as a Unix format .tar archive, it will already 
   be set up ready to go. If you downloaded a DOS or Windows format .zip 
   version, though, you will need to convert it into Unix format before you 
   can begin, by running:

      chmod +x fix.sh
      ./fix.sh unix

   From here on everything is a pretty standard Unix-style install process. 
   First you configure it:

      ./configure

   It should automatically build dependencies.

   Then you build it:

      make

   And finally you install it (as root -- see below for information on what
   to do if you can't be root):

      su -c "make install"

   You may also wish to install the man pages:

      su -c "make install-man"

   And perhaps the info docs as well:

      su -c "make install-info"

   The configure script has many options for changing the install paths, 
   deciding which parts of the library to include or leave out, and 
   specifying whether to build release libs, debug libs, etc. Run 
   ./configure --help for a list of switches. Especially useful options are:

      --enable-static      - builds a statically linked library
      --disable-shared     - disables the default shared libraries
      --enable-dbglib      - builds a debug version of the library
      --enable-dbgprog     - links test programs with the debug library

   These switches work in combination, for example if you pass 
   --enable-static but not --disable-shared, you will get both shared and 
   statically linked versions of Allegro.

   By default, Allegro will probably install into the /usr/local 
   filesystem. If this hasn't already been set up on your machine, you may 
   have trouble with programs being unable to find the Allegro shared 
   library. You can fix this by adding "/usr/local/lib" to your 
   /etc/ld.so.conf file, and then running ldconfig.

   If you are compiling a CVS version of Allegro, you'll need to
   generate the configure script:
   
      autoconf
      
   You will also need:
   
      make depend
      
   To create the dependency files.


=======================================
============ Using Allegro ============
=======================================

   The options for linking with Allegro are quite complicated, since 
   for static versions of the library, depending on how it was configured, 
   it may need to pull in other libraries (X, SVGAlib), as well as just 
   Allegro itself, and for all versions the library is split into two chunks
   -- one of which is always static, and the other of which is sometimes
   shared. To avoid you having to work out the right linker commands for 
   yourself, the installation creates a script, allegro-config, that will 
   print out a suitable commandline. You can use this inside a backtick 
   command substitution, for example:

      gcc myfile.c -o myprogram `allegro-config --libs`

   Or if you want to build a debug version of your program, assuming that 
   you have installed the debug version of Allegro:

      gcc myfile.c -o myprogram `allegro-config --libs debug`

   Unix newbies, take note that these are ` backticks, not normal ' quotes!

   There are also switches for printing out the Allegro version number, 
   overriding the install paths, and selecting between shared and static 
   libraries, in case you installed both. Run allegro-config without any 
   arguments for a full list of options.

   Don't forget that you need to use the END_OF_MAIN() macro right after 
   your main() function!



======================================================
============ Shared library compatibility ============
======================================================

   Allegro can interface with a lot of other libraries -- in particular, 
   various X libraries and SVGAlib. If you link statically to Allegro,
   your program will depend upon all these other libraries so you may want
   to link statically to them too. If you link dynamically to Allegro, your
   binary will only depend upon the Allegro version (and things like libc);
   in this case your binary is more easily portable, but it does depend
   upon the way Allegro was configured.

   The easiest way to make your program portable is to distribute it in 
   source form. That way the users can configure Allegro for themselves, 
   and will always end up using exactly the right set of libraries for 
   their particular system.

   Having said that, if you enable dynamic module support (default), then
   you should have few (if any) problems.

   Security note: Make sure that untrusted users cannot write to either of
   the `/usr/local/lib/allegro/' or `/usr/lib/allegro/' directories.
   Allegro looks for dynamically loaded modules in those directories, and
   loads all of them listed in `modules.lst' at startup.

   See also the ABI compatibility document for more information.



==================================================
============ What if you're not root? ============
==================================================

   Allegro can be installed on a system where you don't have root 
   privileges. Using the standard configure script option `--prefix' you 
   can change the target directories for installation -- for example,
   you can write:

      ./configure --prefix=$HOME

   (Be a bit careful, --prefix=~ works in bash but not tcsh -- it's safer
   to use $HOME if you're not sure.)

   Then binaries will be installed to the `bin' subdirectory of your home
   directory, libraries to `lib', etc.  Now you need to set up your system
   so that it knows where to find a few things, if this has not been done
   already.  You might want to add these commands to your .bash_profile
   or similar startup script.  If you use a csh-style shell, you want to
   use `setenv', not `export'.


   * Your PATH must include the `bin' directory:

	export PATH=$PATH:$HOME/bin


   * If you are using Allegro as a shared library, you need to tell the 
     dynamic loader where to find the Allegro libraries:

	export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/lib


   * GCC needs to know where to find header and library files:

	export C_INCLUDE_PATH=$C_INCLUDE_PATH:$HOME/include
	export CPLUS_INCLUDE_PATH=$CPLUS_INCLUDE_PATH:$HOME/include
	export LIBRARY_PATH=$LIBRARY_PATH:$HOME/lib


   (Note: in fact `allegro-config' can handle the last step for you, if
   you use it for compilation as well as linking:

	gcc -c mygame.c `allegro-config --cflags`
	gcc -o mygame mygame.o `allegro-config --libs`

   But, it's better to set the environment variables too.  Most people
   don't tend to bother with `allegro-config' when compiling.)


   Alternatively, you can get the required environment changes from 
   allegro-config, by typing at a shell prompt:

	allegro-config --env

   You can catenate the output to your .bash_profile, which is pretty
   much like adding all of the above commands.  Note that `allegro-config'
   itself is in the `bin' directory of the installation, so either make 
   sure that directory is in your path before running `allegro-config' or 
   specify the path exactly, for example:

	~/bin/allegro-config --env >> ~/.bash_profile



==========================================
============ Notes on drivers ============
==========================================

   * System:
	On initialisation, Allegro will try to connect to an X server. If it 
	can't find one, it will give up and try to use some different system 
	driver instead (such as the Linux console). This means that to run 
	it in X mode, you must either launch your programs from inside an X 
	session, or have set the DISPLAY environment variable to indicate 
	what server you would like to use.

   * Graphics:
	There are three different X graphics drivers: GFX_XWINDOWS uses 
	only standard X calls, while GFX_XDGA and GFX_XDGA2 use the XFree86
	DGA extension, which allows them to write directly to the screen
	surface. DGA is normally much faster than the standard X mode, but
	it requires root permissions and it will not work remotely.
	GFX_XDGA uses DGA 1.0 extension provided with XFree86 3.3.x, and
	it will not produce such well behaved windowed programs as the
	GFX_XWINDOWS driver; both DGA 1.0 and X drivers can run windowed as
	well as in fullscreen mode.
	GFX_XDGA2 uses new DGA 2.0 shipped with XFree86 4.0.x, and directly
	runs in fullscreen mode (as long as X is configured to support
	the requested resolution), and it will also use hardware acceleration
	if available.

	If your program requests a different color depth to the current X 
	display, Allegro will emulate the depth you asked for, so that your 
	program will still work, albeit more slowly than if the color depths 
	were identical. To find out whether this emulation is taking place, 
	look at the gfx_driver->desc field (which is displayed in the middle 
	of the screen by the tests/test program). If this says "matching", 
	the color formats are identical, so no conversions are required. If 
	it says "fast", some simple conversions are taking place, but 
	nothing too painful. If it says "slow", you are in trouble :-)
	This is not valid for the DGA 2.0 driver, as it'll always change the
	video mode to the specified resolution and color depth.



====================================
============ Irix Notes ============
====================================

   If the Irix compiler spits strange lines such as the following when
   compiling your Allegro program:

	include/allegro/alcompat.h:59: conflicting types for `ceilf'
	/usr/include/math.h:311: previous declaration of `ceilf'
	include/allegro/alcompat.h:60: conflicting types for `floorf'
	/usr/include/math.h:333: previous declaration of `floorf'
	include/allegro/alcompat.h:63: conflicting types for `tanf'
	/usr/include/math.h:176: previous declaration of `tanf'
	include/allegro/alcompat.h:64: conflicting types for `acosf'
	/usr/include/math.h:106: previous declaration of `acosf'
	include/allegro/alcompat.h:65: conflicting types for `asinf'
	/usr/include/math.h:116: previous declaration of `asinf'

   then you should #define ALLEGRO_NO_FIX_ALIASES prior to 
   the #include <allegro.h> line.