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

                    ABI compatibility information.

             See readme.txt for a more general overview.

# 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:

- Windows on x86 / x86-64
- Linux on x86 / x86-64
- MacOS X on PowerPC / x86

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.

# 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.

# Linux notes

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

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

It should NOT say:

liballeg.so.4.4.0 => /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.

# 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 <mybinary> 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.