Resolving ABI Compatibility Issues Between std::__cxx11::string and std::string in C++11

Problem Background and Error Analysis

In the era of widespread C++11 adoption, developers using GCC 5 or later compilers often encounter perplexing linker errors. Specifically, when attempting to link code with certain third-party libraries, errors similar to the following may appear:

undefined reference to `H5::CompType::insertMember(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, unsigned long, H5::DataType const&) const'

The root cause of this error lies in a significant change introduced in GCC 5—the dual ABI (Application Binary Interface) mechanism. Prior to C++11, the standard library string type was implemented as std::string. However, in GCC 5, to support new C++11 features such as move semantics and small string optimization, std::__cxx11::string was introduced as a new implementation.

Detailed Explanation of ABI Mechanism

ABI defines binary-level interface specifications, including function calling conventions, data structure layouts, and name mangling. When different compilation units use different ABIs, linking errors occur. GCC 5 controls which ABI to use through the _GLIBCXX_USE_CXX11_ABI macro:

• When _GLIBCXX_USE_CXX11_ABI=1, the new C++11 ABI is used, with string type as std::__cxx11::string
• When _GLIBCXX_USE_CXX11_ABI=0, the old ABI is used, with string type as traditional std::string

This design allows backward compatibility but also introduces compatibility issues when mixing code compiled with different ABIs.

Solutions

Solution 1: Code-Level Macro Definition

The most direct solution is to define the ABI macro before including any standard library headers. For example:

#define _GLIBCXX_USE_CXX11_ABI 0
#include <iostream>
#include <string>
// Additional code...

This approach ensures consistent ABI settings throughout the compilation unit. It is crucial to note that this definition must appear before the first standard library header inclusion; otherwise, it may not take effect.

Solution 2: Compiler Options

For larger projects, a better approach is to uniformly set the ABI through compiler options. Add the following to GCC compilation commands:

g++ -D_GLIBCXX_USE_CXX11_ABI=0 -o program source.cpp

Or in CMake projects:

add_compile_definitions(_GLIBCXX_USE_CXX11_ABI=0)

This method avoids repeating macro definitions in each source file and ensures consistent ABI settings across the entire project.

Practical Recommendations and Considerations

When addressing ABI compatibility issues in practical development, consider the following points:

1. Third-Party Library Inspection: First determine the compilation environment of third-party libraries. If a library was compiled with an older GCC version, it typically requires setting the project to use the old ABI (_GLIBCXX_USE_CXX11_ABI=0).
2. Consistency Principle: Ensure all components in the project use the same ABI settings, including the main program, static libraries, and dynamic libraries.
3. Build System Integration: Explicitly specify ABI settings in the build system to avoid reliance on default configurations.
4. Gradual Migration: If possible, gradually recompile third-party libraries to use the new ABI, ultimately unifying to _GLIBCXX_USE_CXX11_ABI=1.

In-Depth Understanding

From a technical perspective, std::__cxx11::string and std::string are compatible at the source code level—both are aliases of std::basic_string<char>. The issue arises at the binary level: the two implementations have different memory layouts and name mangling.

For example, consider the following function declaration:

void processString(const std::string& str);

When compiled with the old ABI, this function might be mangled as _Z13processStringRKSs; with the new ABI, it might be mangled as _Z13processStringRKNSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEE. This discrepancy directly causes the linker to fail in finding matching symbols.

Conclusion

The ABI changes in C++11 represent necessary adjustments in compiler evolution. While they present short-term compatibility challenges, they benefit language development in the long run. By properly understanding and utilizing the _GLIBCXX_USE_CXX11_ABI macro, developers can effectively manage ABI compatibility between different components. In environments mixing old and new codebases, selecting appropriate ABI setting strategies is crucial—not only for resolving current linking issues but also for laying a solid foundation for future code migration.