@html_text_substitution=readme.txt|<a href="../readme.html">readme.txt</a>
@html_text_substitution=docs/build/linux.txt|<a href="linux.html">docs/build/linux.txt</a>
@html_text_substitution=abi.txt|<a href="../abi.html">abi.txt</a>
@html_text_substitution=Allegro manual|<a href="../allegro.html">Allegro manual</a>
@external-css=../allegro.css
@document_title=Allegro Unix-specific information
@<pre>
     ______   ___    ___
    /\  _  \ /\_ \  /\_ \
    \ \ \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.
@</pre>



@heading
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 be portable to any Unix variant. For information about the
   Linux-specific console routines, see <tt>docs/build/linux.txt</tt>.

   Only the X version is installed by default.



@heading
Required software

   Chances are that you already have all the necessary development tools, at
   least for compiling and installing the library.  You will need CMake 2.6 or
   above.  Most distributions should include it now, otherwise you will need to
   install it yourself.



@heading
Installing Allegro

   Please follow the generic instructions in docs/build/cmake.txt.



@heading
Shared files

   Installing Allegro will copy the library and header files plus other
   support files. These are:
<ul><li>
   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.
<li>
   pkg-config files. These are alternatives to the allegro-config script.
</ul>
   On the other hand, there are files which you, as system administrator, are
   required to installed manually. These are:
<ul><li>
   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'.
<li>
   allegro.info: Allegro documentation in Info format, viewable with GNU's
   info viewer. This is copied into the `info' path of your system.
<li>
   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'.
</ul>
   You can find more information about some of these files and other
   suggestions in the chapter "Unix specifics" of the main Allegro manual.

   

@heading
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.

   To avoid you having to work out the right linker commands for 
   yourself, the installation creates a script, <tt>allegro-config</tt>, that will
   print out a suitable command line. You can use this inside a backtick 
   command substitution, for example:
<textblock>
      gcc myfile.c -o myprogram `allegro-config --libs`
<endblock>
   Or if you want to build a debug version of your program, assuming that 
   you have installed the debug version of Allegro:
<textblock>
      gcc myfile.c -o myprogram `allegro-config --libs debug`
<endblock>
   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.

   You can also use pkg-config instead, for example:
<textblock>
      gcc myfile.c -o myprogram `pkg-config --libs allegro loadpng`
<endblock>
   As shown, there are pkg-config files for the bundled addons as well.

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



@heading
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 ImageMagick tools installed for this to work.



@heading
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 `<tt>--prefix</tt>' you
   can change the target directories for installation -- for example,
   you can write:
<textblock>
      cmake -DCMAKE_INSTALL_PREFIX=$HOME ..
<endblock>
   Then binaries will be installed to the `<tt>bin</tt>' subdirectory of your home
   directory, libraries to `<tt>lib</tt>', 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 <tt>.bash_profile</tt>
   or similar startup script.  If you use a csh-style shell, you want to
   use `<tt>setenv</tt>', not `<tt>export</tt>'.

   Your PATH must include the `bin' directory:
<textblock>
      export PATH=$PATH:$HOME/bin
<endblock>
   If you are using Allegro as a shared library, you need to tell the dynamic
   loader where to find the Allegro libraries:
<textblock>
      export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/lib
<endblock>
   GCC needs to know where to find header and library files:
<textblock>
      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
<endblock>
   Note: in fact `<tt>allegro-config</tt>' can handle the last step for you, if
   you use it for compilation as well as linking:
<textblock>
      gcc -c mygame.c `allegro-config --cflags`
      gcc -o mygame mygame.o `allegro-config --libs`
<endblock>
   But, it's better to set the environment variables too.  Most people
   don't tend to bother with `<tt>allegro-config</tt>' when compiling.

   Alternatively, you can get the required environment changes from 
   <tt>allegro-config</tt>, by typing at a shell prompt:
<textblock>
      allegro-config --env
<endblock>
   You can catenate the output to your <tt>.bash_profile</tt>, which is pretty
   much like adding all of the above commands.  Note that `<tt>allegro-config</tt>'
   itself is in the `<tt>bin</tt>' directory of the installation, so either make
   sure that directory is in your path before running `<tt>allegro-config</tt>' or
   specify the path exactly, for example:
<textblock>
      ~/bin/allegro-config --env &gt&gt ~/.bash_profile
<endblock>


@heading
Notes on drivers

   <dl><dt><b>System:</b></dt><dd>
      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 driver, if it is enabled).
      This means that to run it in X mode, you must either launch your programs
      from inside an X session, or have set the <tt>DISPLAY</tt> environment
      variable to indicate what server you would like to use.</dd>

   <dt><b>Graphics:</b></dt><dd>
      There are two different X graphics drivers: <tt>GFX_XWINDOWS</tt> uses only
      standard X calls, while <tt>GFX_XDGA2</tt> 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. Note that DGA2 is deprecated now.
      
      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-&gtdesc 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.</dd>
   </dl>


@heading
Irix Notes

   If the Irix compiler spits strange lines such as the following when
   compiling your Allegro program:
<textblock>
      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'
<endblock>
   then you should <tt>#define ALLEGRO_NO_FIX_ALIASES</tt> prior to
   the <tt>#include &ltallegro.h&gt</tt> line.


