
  This document explains how to use Allegro.pas with the Free Pascal compiler.
  This works also for Lazarus IDE, but you should read "lazarus.txt" too for
  more information.  For Delphi read "delphi.txt".

  To compile the examples and the demonstration game, read "makefile.txt".

  Before to use Allegro.pas you must install Allegro itself.  If you didn't
  yet, please read the appropriate document for your operating system.



The Allegro.pas units
---------------------

  All units needed to use Allegro.pas are in the "~/lib" directory.  You'll
  need all "pas", "inc" and "cfg" files.

  You have different ways to "add" Allegro.pas to your projects:

  Adding to the project
  ---------------------

  Copy the "~/lib" directory to the same directory of the sources of your game.

  To keep things ordered I recommend you to keep the Allegro.pas in a
  subdirectory and name it "allegro" and use the FPC option -Fu when compiling.
  Don't forget to use -Fi too as Allegro.pas units need to include some files.

  Adding to the fpc.cfg file
  --------------------------

  If you're used to the fpc.cfg file may be it is more easy to add the "~/lib"
  directory to that file, both units and include.

  Adding to Free Pascal or Lazarus installation
  ---------------------------------------------

  My favorite is to copy the "~/lib" directory to the RTL units directory of
  your Free Pascal installation.  This directory varies depending on the
  operating system and Free Pascal version but it should be something like:

c:\fpc\<version_number>\units\<architecture>

  or

/usr/lib/fpc/<version_number>/units/<architecture>

  Where <version_number> is the version of FPC (for example 3.0.0) and
  <architecture> is the architecture of your operating system (for example
  x86_64-linux, i386-win32, ...).

  I recommend you to put the files inside a subdirectory named "allegro5".



Linking with Allegro debug version
----------------------------------

  If you are working in an add-on or modifying Allegro.pas, may be you want to
  use the "debug" version of Allegro.  If so, you must add "-dAL_DEBUGMODE" to
  the compilation command, this way your programs will link with the "debug"
  version of Allegro.  In most cases this isn't necessary.

  Note that may be you have to compile Allegro by yourself to obtain the "debug"
  library.



Differences between Delphi, Free Pascal and Lazarus
---------------------------------------------------

  Note that there are language differences between Delphi and Free Pascal (even
  using Free Pascal's Delphi mode) so don't expect that your code is portable
  through both compilers.  See the example sources to see how I've tried to
  write code that work in both compilers.

  Also note STRING management may be problematic.  Allegro expects ASCII-7 or
  UTF-8 stored in ANSISTRING, wich is compatible with Free Pascal defaults, but
  Delphi uses UTF-16 by default (WIDECHAR).  To help with this use the
  conversion functions of unit al5strings.



Windows manifest
----------------

  If you're using Windows, may be you found that your programs may not work, or
  they do but a warning window appears talking about "Windows execution
  privileges" or similar.  This is because the modern Windows weird permission
  system.

  To solve this you should add a "manifest" to your programs.  With help from
  the Lazarus community, I've created manifest template files you can find in
  the ~/resources directory.  Copy both "manifest.rc" and "manifest.xml" to your
  source directory and add the next compiler directive in your program source,
  between your "PROGRAM" and your "USES" directives as you can see in the
  examples:

  {$IFDEF WINDOWS}{$R 'manifest.rc'}{$ENDIF}

  You need to change some of the fields of the XML file, as the name and
  description.  Also administration programs (and not all them) may need some
  special stuff (which makes Windows permission system even more weirdest and
  uselessest, IMHO).

  This works also for Lazarus.
