@html_text_substitution=readme.txt|<a href="readme.html">readme.txt</a>
@external-css=allegro.css
@document_title=ABI compatibility information
@<pre>
@!indent
     ______   ___    ___
    /\  _  \ /\_ \  /\_ \
    \ \ \L\ \\//\ \ \//\ \      __     __   _ __   ___ 
     \ \  __ \ \ \ \  \ \ \   /'__`\ /'_ `\/\`'__\/ __`\
      \ \ \/\ \ \_\ \_ \_\ \_/\  __//\ \L\ \ \ \//\ \L\ \
       \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
        \/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
                                       /\____/
                                       \_/__/


                ABI compatibility information.

         See readme.txt for a more general overview.
@indent
@</pre>



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

   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.

   Note: ABI compatibility will only be _actively_ maintained for:
<ul>
<li>Windows on x86
<li>Linux on x86
<li>Linux on x86-64
<li>MacOS X on PowerPC
</ul>

   We will not be maintaining "forwards compatibility", meaning that
   programs compiled with a newer release of Allegro may not necessarily
   run on a target system which has an older release of Allegro installed.
   You would have to upgrade the Allegro DLL on the target system.  While
   we will try to minimise these kinds of forced upgrades, it should give
   us more flexibility within the stable series.



@heading
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. 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, don't distribute a modified version of Allegro under a
   name such as all42.dll or alleg42.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.



@heading
Linux on x86 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 &ltmybinary&gt".
   It should say something like:

      liballeg.so.4.2 =&gt /usr/local/lib/liballeg.so.4.2 (0xdeadbeaf)

   It should NOT say:

      liballeg.so.4.2.0 =&gt /usr/local/lib/liballeg.so.4.2.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: OSS digital sound and OSS MIDI. In
   short, if a program built against a copy of default-options Allegro
   will work with your final library it should be fine.



@heading
Linux on x86-64 notes

   The situation is basically the same as for Linux on x86, however
   your copy of Allegro must NOT have assembly routines enabled (it
   wouldn't work anyhow).



@heading
MacOS X notes

   On OSX there are two 'styles' of linking - Unix style and Mac style.
   For the Unix style linking, you would use `allegro-config --libs`
   on the link line. For versioning, follow the advice given in the
   'Linux on x86' section above, using the command otool -L instead
   of ldd.

   For example, otool -L &ltmybinary&gt should give

      liballeg-4.2.dylib (compatibility version 4.2.0, current version 4.2.0)

   For the Mac style, use `allegro-config --frameworks` on the link
   line, or add Allegro.framework to your project if you are using 
   XCode. In this case, the versioning is done inside the framework
   itself.

   Apple recommends that an application should be entirely self-
   contained. To achieve this in Allegro, static-link the executable
   and use fixbundle to bind all its resources together. In this
   way, you will not need to worry about incompatible versions of
   the library. This is useful if you are distributing an application.

   There is a known compatibility problem when using gcc 4 on MacOS X 10.4
   that prevents binaries from working on older versions of MacOS X. While it
   is anticipated that a future update from Apple will fix this problem, you
   can use gcc 3 to work around it.



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