______ ___ ___
/\ _ \ /\_ \ /\_ \
\ \ \L\ \\//\ \ \//\ \ __ __ _ __ ___
\ \ __ \ \ \ \ \ \ \ /'__`\ /'_ `\/\`'__\/ __`\
\ \ \/\ \ \_\ \_ \_\ \_/\ __//\ \L\ \ \ \//\ \L\ \
\ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
\/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
/\____/
\_/__/
ABI compatibility information.
See readme.txt for a more general overview.
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:
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.
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.
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.2 => /usr/local/lib/liballeg.so.4.2 (0xdeadbeaf)
It should NOT say:
liballeg.so.4.2.0 => /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.
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).
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 <mybinary> 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.
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.