ABI compatibility information
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:
- Windows on x86
- Linux on x86
- Linux on x86-64
- MacOS X on PowerPC
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 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.
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 <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.
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).
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 <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.
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.