
  This document explains how to use Allegro.pas with Delphi. For Lazarus read
  "lazarus.txt".  For Free Pascal read "fpc.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.

  Also note that Allegro.pas was tested ONLY with Delphi 11.3 Community Edition.
  We tried to make it compatible with most Delphi versions available but if
  you're using another version it may not work as expected.  You can help us to
  fix any problem by sharing your experience.  See README.md file to know how to
  contact with developers.



Compiling examples and demonstration games
------------------------------------------

  There are "delphi" subdirectories in both examples and demonstration
  directories.  Inside there are Delphi projects and groups.  Load with your
  IDE and just compile.  Executables are dropped at the "~/bin" subdirectories.

  If your Delphi version isn't able to load the project file correclty, you can
  create it by yourself:

  * Change the extension of the PROGRAM file to "dpr".
    i.e. "ex_menu.pas" became "ex_menu.dpr".
  * Open the "dpr" file  with Delphi (answering you want to open it as a project
    if you're asked for) and save the new project.
  * Add "~/src/lib" to the units path so Delphi can find Allegro.pas.  You may
    need to add the same directory for included files too.
  * Set binary output path to "~/bin/examples" or "~/bin/demos/...".
    (You may set "~/obj" for temporary files too).
  * Take a look to other options as debugging and optimization.
  * Save the project again.
  * Compile.
  * Profit.

  Note that a few of the examples doesn't work as expected.  I'm trying to find
  the reason and fix it



Creating a new game project
---------------------------

  To create a new project using Allegro.pas create a "console" project.  I
  haven't use Allegro.pas along with VCL or Firemonkey so I have no idea if it
  works or bad things may happen.  Experience with Lazarus (FCL and LCL) says
  that it would not work due to incompatible thread management.

  All units needed to use Allegro.pas are in the "~/lib" directory.  You'll
  need all "pas", "inc" and "cfg" files.  You can copy such directory to your
  project's one and then add the units to your project.

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



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.  To do so, you must define "AL_DEBUGMODE"
  symbol, this way your programs will link with the "debug" version of Allegro.
  In most cases this isn't necessary.

  Note that you may have to compile Allegro by yourself to obtain the "debug"
  version of the 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 if you want your code to be portable
  through both compilers you'll need to be careful.  See the example sources to
  see how I've tried to write code that work in both compilers.



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

  May be you found that your programs don't 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.  I have few
  experience with Delphi and I'm pretty new with latest Delphi versions (I used
  Delphi 6!) so I'm not sure how to do that.  If you are more experienced,
  please let me know (see the README file for contact info).  Since the manifest
  is a XML file, may be you can use the same one I've created for Free Pascal
  (read "fpc.txt").
