#define ALLEGRO_UNSTABLE
#include <allegro5/allegro.h>

Hmm, I don't know if I agree. Wouldn't that mean that the allegro source would be littered with a bunch of #ifdefs around every single difference between the stable and 'unstable' branches? It sounds like it would lead to a maintenance and compilation nightmare to me.

How do you expect to handle ABI compatibility? Especially when "unstable" things are removed or renamed?

I thought it'd might be possible to somehow split the unstable features into a separate optional library... Not sure if that is possible if they share the same source file. Maybe some clever linker scripts?

I'm not a dev, so maybe you're talking about internally. But if you mean externally, I see no reason people should expect an "unstable" function never to change. The same way between the existing two branches.

[edit]

But it looks like you're talking about internals. What's the problem this introduces? If you've got, say, a DLL, and you add a new function, do all the other functions get moved around and broken? Surely dynamic libraries work on a function name level and not a byte offset?

I guess in the case of a compiled program, but the DLL ABI changes, "function name exists but was changed" or "you are calling a depreciated unstable function". But couldn't we introduce some boilerplate for those rare cases, where we have a list of functions that immediately flag a critical-level allegro error that says, "This program is calling a depreciated function. There has likely been a DLL version mismatch."

Additionally, since we'd be forcing people to use ALLEGRO_UNSTABLE, it's the developer's fault if they make the assumption that functions will never change and doesn't statically link, or provide updates.

[edit]

Doing some reading. This seems like a fairly good attempt at C++ ABI, if you're wanting something to read for fun.

Basically, they use extern "abi" {}, and the OS (not the compiler) defines how that section must be implemented. And to deal with std::library issues (std::vector is a huge issue that can't even be used in public library functions), they introduce std::abi::library functions which are binary stable.

@Chris Katco:

That's an unimplemented proposal for C++ which is a huge mess when it comes to a stable ABI due to naùe mangling. Name mangling of C++ is the reason why there is ,no stable ABI and slower dll loading with c++. Plain C doesn't have any of those problems to keep the ABI stable when you stick to a few basic rules. Another reason why plain C is better.

So I checked Linux GCC, Windows GCC (via MinGW) and MSVC, and they all support the general ABI idea I was going for. Basically, if your program doesn't use a function from a shared library, then the next version of the library can safely remove that function without breaking ABI compatibility. So if you compile your code without ALLEGRO_UNSTABLE in e.g. 5.2.0, then your code will continue to work with DLLs produced for any later 5.2.x version. If you do use ALLEGRO_UNSTABLE, then your program is only guaranteed to work with the very same version your compiled for (i.e. 5.2.0 in this example).

This is the same ABI guarantee we currently provide with the current dual branch arrangement. Code compiled with 5.0.x works with shared libraries with version 5.0.y where y >= x. Code compiled with 5.1.x works only with shared libraries with the same version.

It occurs to me that we could actually provide an option to build Allegro without any visible unstable entries, for things like Debian which might not like these unstable ABI breakages.

Hah, great. Although I still prefer my opt-in approach more than silencing a warning. I get the impression many people routinely turn a blind eye to warnings .