Easy way to guarantee binary compatibility for C++

Question

I don't know exact way to guarantee binary compatibility for C++ library on both Windows and Linux. But I think if I make all exposed APIs with a C linkage I think I can easily guarantee this compatibility on both Windows and Linux.

It's like below :

extern "C" int SomeAPI();

Rest of the functions surely will be written in C++. Only the APIs exposed to outter world will have C linkage.

And the exposed API's must be pure C function - no exceptions, no C++ types are used.

Am I right or wrong? Do I have any misunderstandings?

I think I can use this library even with C program also.

The compatibility I'd like to achieve is compiler forward compatibility and standard library forward compatibility.

And I cannot make it opensource. I only have to close it. --> I will try making it open source.

I use boost and STL for making shared or static C++ library. Also I wonder the compatibility not only for compiling but also for launching and running in and OS.

Am I right?

Answer 1

For binary compatibility, what also matters is the application binary interface (ABI).

BTW, C++ functions can not only return some results, but also throw some exceptions. You need to document that (even if you decide that no exceptions are thrown, which is actually difficult to achieve, e.g. because new can throw std::bad_alloc and this can happen inside some internal layers of your software).

Notice that (notably on Linux) the ABI of the C++ standard library did change with various versions of the compiler. For examples, implementation of std::string-s or of standard C++ containers did vary (in a subtle incompatible way, at the binary level). You could statically link the C++ standard library (but this might not always be enough, or be brittle, e.g. if the user program also needs it because his code is in C++).

^{Since most C++ compilers and standard libraries are free software on Linux, you could dive into their source code to understand all the details. This should take you years of efforts and you need to budget that.}

So it is harder than what you believe. At the very least, document the version of the C++ compiler used to build your thing, and the version of the C++ standard library involved.

Another approach (which I recommend) could be to make your thing free software or open source and publish the source code on github or elsewhere, and let your user compile your source code (with his C++ compiler and C++ standard library).

Binary compatibility with various C++ compilers and standard C++ libraries is actually difficult to achieve, because the evil is in the details (if you release only some binary thing). You might publish several binaries compiled with various compiler versions (e.g. with g++-5, g++-6, clang++-4.0 etc...).

I don't know exact way to guarantee binary compatibility for C++ library

Such a general goal is unrealistic and over-ambitious. At most you might publish several binaries and document with what exact C++ compiler (and version, and compiler options) and C++ standard library each have been compiled.

The compatibility I'd like to achieve is compiler forward compatibility and standard library forward compatibility.

This is impossible in general. Various C++ compilers did break ABI compatibility in the past (and this has been documented). The evil is in the details (so even if it apparently seems to work most of the time, it could often be buggy).

Am I right?

No, you are wrong and over-ambitious. At most you could release a binary (probably you should release several ones) and tell exactly how it was built (what C++ compiler and version, what compilation flags, what C++ standard library and version and even what C standard library and version; if you use some external C++ or C library - like Qt, Boost, Sqlite, etc... - you also need to document their version). Binary compatibility for C++ is a fiction.

You could and probably should use (on Linux particularly) package management systems, e.g. publish some .deb package for some particular Linux distributions (e.g. a given version of Debian or Ubuntu). You'll list exact dependencies in your binary package.

Be aware that maintaining several binary versions (and binary packages) is a lot of boring work that you should budget. You might ask permission from your manager or client to open the source of your library (and quite often this takes less work). For instance, your library might be published under GPLv3 license: open source programs could freely use it, but proprietary applications would have to buy some other license from your company.