@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

   We plan to maintain backward compatibility at the Application Binary
   Interface level for the subsequent releases of the 4.4.x series. For
   example, that means you will be able to use an executable compiled using
   version 4.4.0 with version 4.4.5 or 4.4.41 of the dynamically linked
   library.

   However, there are some guidelines you should follow.

   Note: ABI compatibility will only be _actively_ maintained for:
<ul>
<li>Windows on x86 / x86-64
<li>Linux on x86 / x86-64
<li>MacOS X on PowerPC / x86
</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 official stable version. Don't disable any features
   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 all44.dll or alleg44.dll.

   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 notes

   When you are ready to distribute your binary, run "ldd &ltmybinary&gt".
   It should say something like:

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

   It should NOT say:

      liballeg.so.4.4.0 =&gt /usr/local/lib/liballeg.so.4.4.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: you should try to ensure
   that a program built against a copy of Allegro with the default
   configuration will work with your version of the library.



@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 section above, using the command `otool -L' instead of `ldd'.

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

      liballeg.4.4.dylib (compatibility version 4.4.0, current version 4.4.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.

