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


                ABI compatibility information.

         See readme.txt for a more general overview.



======================================
============ Introduction ============
======================================

   Once Allegro 4.2 is released, we plan to maintain backward compatibility
   at the Application Binary Interface level for the subsequent releases of
   the 4.2.x series. For example, that means you will be able to use an
   executable compiled using version 4.2.0 with version 4.2.5 or 4.2.41 of
   the dynamically linked library.

   "Whew," you sigh, "I don't have to put allxxxx.dll in my zips anymore."

   Ultimately, yes. However, there are some guidelines (rules) you should
   (must) follow, otherwise things will not work, and you will get angry
   emails from users and from us (the Allegro "Be Good" Mafia).

   Note: ABI compatibility will only be _actively_ maintained for
   Windows, Linux and BeOS on x86 architectures.



=======================================
============ Windows notes ============
=======================================

   If you don't need a modified version of Allegro then just link your
   program against an officially blessed non-WIP, non-CVS, non-dodgy
   version and chocolate chip cookies will fall from the sky. Don't
   disable any features (eg. colour depths, drivers) in the DLL.

   If you require a modified version of Allegro, then please either
   statically link, or pick a non-standard name for the Allegro DLL.
   For example, it would be bad mojo to distribute a modified version of
   Allegro under a name such as all40.dll or alleg40.dll. Instead, call
   it something like alcustom.dll. Even better, statically link.

   For the people who use vanilla Allegro, we will provide a set of
   "reference" DLLs. If your binary works with those then everything is
   fine. If you want to distribute Allegro DLLs with your program
   (usually a good idea), we recommend you distribute our DLLs instead
   of ones you compiled yourself. We trust you will bodge something up.



=====================================
============ Linux notes ============
=====================================

   To make sure an Allegro binary compiled on your machine will work on
   another machine, do not disable any "features" with `configure'. Your
   copy of Allegro must have assembly routines, threads, modules, all
   colour depths and X11 support enabled, amongst other things. If in
   doubt, leave it at the default setting.

   When you are ready to distribute your binary, run "ldd <mybinary>".
   It should say something like:

      liballeg.so.4.0 => /usr/local/lib/liballeg.so.4.0 (0xdeadbeaf)

   It should NOT say:

      liballeg.so.4.0.0 => /usr/local/lib/liballeg.so.4.0.0 (0xdeadbeaf)

   If you see the latter, that would mean users with later versions of
   Allegro would not be able to run your binary.

   See also the Windows section if you need to use a modified version of
   Allegro.

   For people packaging Allegro for redistribution: Drivers that are
   built as dynamically loaded modules may be disabled or left out, but
   all others should be left in. Examples of drivers that are _not_
   dynamically loaded include: VBE/AF, DGA1, OSS digital, OSS MIDI. In
   short, if a program built against a copy of default-options Allegro
   will work with your final library, all is goodly.



====================================
============ BeOS notes ============
====================================

   Most of the things discussed in the Windows notes apply here. In
   particular, you're encouraged to use a non-WIP, non-CVS unmodified
   official version of the library, in which case your program should
   run without problems on foreign machines.



=====================================
============ Final notes ============
=====================================

   Providing source is still better than not providing source. Binaries
   are good, however, if your code sucks and only you (with the help of
   witchcraft) can compile it.

   If you provided binaries in the past using WIP versions of Allegro,
   we politely request that you recompile your program using a stable
   version of Allegro. (Unless, of course, you'd prefer to sleep with
   the fishes.)

   And oh, don't make your compiler generate i686-only code or anything
   stupid like that.


