| Evgeniy Stepanov | da2ff7e | 2015-10-13 23:48:28 +0000 | [diff] [blame] | 1 | |
| 2 | ==================== |
| 3 | Libc++ ABI stability |
| 4 | ==================== |
| 5 | |
| Arthur O'Dwyer | 3800a10 | 2021-05-26 08:59:16 -0400 | [diff] [blame^] | 6 | Libc++ aims to preserve a stable ABI to avoid subtle bugs when code built under the old ABI |
| 7 | is linked with code built under the new ABI. At the same time, libc++ wants to make |
| 8 | ABI-breaking improvements and bugfixes in scenarios where the user doesn't mind ABI breaks. |
| Evgeniy Stepanov | da2ff7e | 2015-10-13 23:48:28 +0000 | [diff] [blame] | 9 | |
| Arthur O'Dwyer | 3800a10 | 2021-05-26 08:59:16 -0400 | [diff] [blame^] | 10 | To support both cases, libc++ allows specifying an ABI version at |
| 11 | build time. The version is defined with CMake option ``LIBCXX_ABI_VERSION``. |
| 12 | Currently supported values are ``1`` (the stable default) |
| 13 | and ``2`` (the unstable "next" version). At some point "ABI version 2" will be |
| 14 | frozen and new ABI-breaking changes will start being applied to version ``3``; |
| 15 | but this has not happened yet. |
| Evgeniy Stepanov | da2ff7e | 2015-10-13 23:48:28 +0000 | [diff] [blame] | 16 | |
| Arthur O'Dwyer | 3800a10 | 2021-05-26 08:59:16 -0400 | [diff] [blame^] | 17 | To always use the most cutting-edge, most unstable ABI (which is currently ``2`` |
| 18 | but at some point will become ``3``), set the CMake option ``LIBCXX_ABI_UNSTABLE``. |
| 19 | |
| 20 | Internally, each ABI-changing feature is placed under its own C++ macro, |
| 21 | ``_LIBCPP_ABI_XXX``. These macros' definitions are controlled by the C++ macro |
| 22 | ``_LIBCPP_ABI_VERSION``, which is controlled by the ``LIBCXX_ABI_VERSION`` set |
| 23 | at build time. Libc++ does not intend users to interact with these C++ macros |
| 24 | directly. |