Binary compatibility

Refer to the following types of object files as 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 the Clang-based front end of IBM XL C/C++ for AIX 16.1.0. 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 libC ABI:

• C++ object files built with the XL-based front end of IBM XL C/C++ for AIX 16.1.0 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 surface 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 a GNU 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 the Clang-based front end of IBM XL C/C++ for AIX 16.1.0. Because ibmclang.shr.o has dependencies on the C++ runtime of the IBM Open XL C/C++ compiler, applications generated by the Clang-based front end of IBM XL C/C++ for AIX 16.1.0 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 the Clang-based front end of IBM XL C/C++ for AIX 16.1.0 and used by both IBM Open XL C/C++ for AIX and the Clang-based front end of IBM XL C/C++ for AIX 16.1.0.

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)
     ...
$