Binary compatibility

Refer to the following types of object files as using libc++ ABI, which denotes the C++ standard library implementation on which the object files are based:

• C++ object files built with IBM Open XL C/C++ for AIX. These object files utilize interfaces provided by C++ runtime libraries libc++.a, libc++abi.a, and libunwind.a, which are from the libc++.rte, libc++abi.rte, and libunwind.rte fileset, respectively.
• C++ object files built with IBM XL C/C++ for AIX 16.1.0 that is invoked by xlclang++. These object files utilize interfaces provided by C++ runtime libc++.a, which is from the libc++.rte fileset.

Similarly, refer to the following type of object files as using libC ABI:

• C++ object files built with IBM XL C/C++ for AIX 16.1.0 that is invoked by xlC or earlier releases. The object files utilize interfaces provided by C++ runtime libC.a, which is from the xlC.rte fileset.

Although libc++ ABI and libC ABI are incompatible, you can package their shared objects into a single library so that the library can be used for an application built with either libc++ ABI or libC ABI if all of the following conditions are met:

• The libc++ ABI or libC ABI shared objects in the library are mutually exclusive.
• Each shared object in the library that presents a C++ API supports only one of libc++ ABI and libC ABI.
• Exported symbols from these ABIs are disjoint.
• There are no cross references between libc++ ABI and libC ABI.

Mangled C++ symbols in libc++ ABI and libC ABI are disjoint. To prevent symbol name overlapping across ABIs of C/C++ shared objects, it is recommended that symbols such as global variables and C functions be renamed to encode the ABI in the symbol names. For example, you can map a function name to different names either by changing the identifier or by using an asm label. In the following example, name externCFunctionV2 is used for the externCFunction function in libc++ ABI and its original name externCFunction is used in libC ABI.

#if defined(_AIX) && defined(__clang__)
  extern "C" void externCFunction(void) asm("externCFunctionV2");
#else
  extern "C" void externCFunction(void);
#endif

Example
The following example shows how to build a dual-ABI library from a single source to support both libc++ ABI and libC ABI:

$ cat build_example.sh
#!/usr/bin/ksh
rm -f xlc.shr.o ibmclang.shr.o libfunc.a xlc.a.out ibmclang.a.out
xlC -qmkshrobj func.cpp -o xlc.shr.o -bE:xlc.exp
ibm-clang++_r -shared func.cpp -o ibmclang.shr.o -bE:ibmclang.exp
ar -v -q libfunc.a xlc.shr.o ibmclang.shr.o
xlC main.cpp -o xlc.a.out libfunc.a -blibpath:.:/usr/lib
ibm-clang++_r main.cpp -o ibmclang.a.out libfunc.a -blibpath:.:/usr/lib

$ cat func.hpp
#include <iostream>

#if defined(_AIX) && defined(__clang__)
extern "C" void bar(void) asm("bar2");
#else
extern "C" void bar(void);
#endif

void func(void);

$ cat func.cpp
#include "func.hpp"

#if defined(_AIX) && defined(__clang__)
#define BUILD_COMPILER "build compiler is ibm-clang++_r"
#else
#define BUILD_COMPILER "build compiler is xlC"
#endif

void func(void)
{
  std::cout << "func(): " << BUILD_COMPILER << std::endl;
}

extern "C" void bar(void)
{
  std::cout << "bar(): " << BUILD_COMPILER << std::endl;
}
$ cat main.cpp
#include "func.hpp"

int main() {
  func();
  bar();
  return 0;
}
$ cat xlc.exp
#!
func__Fv
bar
$ cat ibmclang.exp
#!
_Z4funcv
bar2
$ build_example.sh
$ xlc.a.out
func(): build compiler is xlC
bar(): build compiler is xlC
$ ibmclang.a.out
func(): build compiler is ibm-clang++_r
bar(): build compiler is ibm-clang++_r
$

In this example, the main program built with either the xlC or ibm-clang++_r command can call both the func and bar functions from the dual-ABI library. Shared object ibmclang.shr.o in libfunc.a is built using the IBM Open XL C/C++ compiler. The shared object can be used by both IBM Open XL C/C++ for AIX and IBM XL C/C++ for AIX 16.1.0 invoked by xlclang++. Because ibmclang.shr.o has dependencies on the C++ runtime of the IBM Open XL C/C++ compiler, applications generated by IBM XL C/C++ for AIX 16.1.0 invoked by xlclang++ require the appropriate version of the IBM Open XL C/C++ for AIX runtime to be available on the system. Similarly, ibmclang.shr.o can also be built using IBM XL C/C++ for AIX 16.1.0 invoked by xlclang++ and used by both IBM Open XL C/C++ for AIX and IBM XL C/C++ for AIX 16.1.0 invoked by xlclang++.

You can confirm the load dependencies of your executable using the AIX command ldd. The following is the output from using ldd on xlc.a.out and ibmclang.a.out in the example above:

$ ldd xlc.a.out
xlc.a.out needs:
     ...
     /usr/lib/libC.a(shr.o)
     ...
     /usr/lib/libC.a(shrcore.o)
     /usr/lib/libC.a(ansi_32.o)
     /usr/lib/libC.a(ansicore_32.o)
$ ldd ibmclang.a.out
ibmclang.a.out needs:
     ...
     /usr/lib/libc++.a(shr2.o)
     /usr/lib/libc++abi.a(libc++abi.so.1)
     /usr/lib/libunwind.a(libunwind.so.1)
     /usr/lib/libc++.a(libc++.so.1)
     ...
$