/\ \ /\ \ /\ \
______ ___ ___
/\ _ \ /\_ \ /\_ \
\ \ \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 GNU 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. On some
Unices (for example Linux), you can fix this by adding "/usr/local/lib" to
your /etc/ld.so.conf file and then running `ldconfig' as root. On others
(for example Solaris), you can hardcode the location of the library into
the executables by passing "-R/usr/local/lib" to the compiler or linker.
Alternatively, you can add the path to your LD_LIBRARY_PATH environment
variable.
If you are compiling a CVS version of Allegro, you need to generate the
configure header and script prior to doing anything else. Make sure that
GNU autoconf 2.53 or newer is installed on your system and type:
autoheader
autoconf
It is possible to add compilation and link flags to the make command line.
This is done by passing CFLAGS and/or LDFLAGS to make, with the flags
you want. This is meant as a generic customization ability and you should
really use configure to set the flags if possible. Note that any flags you
pass using the make command line are transient: they will only apply to
whatever compilation and link happen to be spawned by this particular
invokation of make.
When you pass CFLAGS and/or LDFLAGS to the make command line Allegro's
build system will use these as a starting point and will add its own
flags to those. This means that you should be aware that flags you pass
this way may be overridden. For this reason, it is best to only use this
to specify flags that do not interfere with the code generation. Useful
flags to pass are -save-temps, or -pipe.
======================================
============ Shared files ============
======================================
Installing Allegro will copy the library and header files plus other
support files. These are:
allegro-config: Script that outputs the correct compiler and linker flags
for your system in order to compile Allegro. This is copied into a
`.../bin' path.
allegro.m4: Autoconf support file to include in your `./configure'
scripts. Copied into a `.../share/aclocal' path.
On the other hand, there are files which you, as system administrator, are
required to installed manually. These are:
language.dat: Contains translations for text strings used by Allegro. If
this file is not available, Allegro runtime messages will only speak
English. Recommended location is `/usr[/local]/share/allegro'.
allegro.info: Allegro documentation in Info format, viewable with GNU's
info viewer. This is copied into the correct `.../info' path of your
system if you run `make install-info'.
allegro.cfg: Contains configuration settings for your system when the
hardware autodetection fails. You can either copy this file and edit
the contents manually or you can use Allegro's setup configuration
program (in the `setup' directory) to create this file. Recommended
location is `[/usr/local]/etc/allegro.cfg'.
You can find more information about some of these files and other
suggestions in the chapter "Unix specifics" of the main Allegro manual.
=======================================
============ 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!
=============================================
============ Setting an X11 icon ============
=============================================
You can set the X11 icon for your application to use. To do this, you need
to include the icon in .xpm format and then point the symbol allegro_icon
to the .xpm data before calling set_gfx_mode().
Alternatively, you can use the xfixicon.sh shellscript to produce a C file
that will do this for you automatically when you link it with your project.
No other steps are required. The xfixicon.sh utility will also accept
bitmaps that are not in .xpm format, interpreting magic pink as transparent.
You will need to have the ImageMagik tools installed for this to work.
======================================================
============ 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 (abi.txt).
==================================================
============ 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 two different X graphics drivers: GFX_XWINDOWS uses only
standard X calls, while GFX_XDGA2 uses the XFree86 DGA 2.0 extension
(shipped with XFree86 4.0.x) which allows it to write directly to the
screen surface, and use hardware acceleration if available. It is
normally much faster than the standard X mode, but requires root
permissions and will not work remotely.
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.
![[logo]](/logo.png){kind=logo}