================ @@ -358,3 +358,46 @@ Complete example code .. _Index.h: https://github.com/llvm/llvm-project/blob/main/clang/include/clang-c/Index.h + +.. _Stability: + +ABI and API Stability +--------------------- + +The C interfaces in libclang are intended to be relatively stable. This allows +a programmer to use libclang without having to worry as much about Clang +upgrades breaking existing code. However, the library is not unchanging. For +example, the library will gain new interfaces over time as needs arise, +existing APIs may be deprecated for eventual removal, etc. Also, the underlying +implementation of the facilities by Clang may change behavior as bugs are +fixed, features get implemented, etc. + +The library should be ABI and API stable over time, but ABI- and API-breaking +changes can happen in the following situations: + +* Adding new enumerator to an enumeration (can be ABI-breaking in C++). +* Removing an explicitly deprecated API after a suitably long deprecation + period. +* Uses of implementation details, such names or comments that say something is + "private", "reserved", "internal", etc. + +The library has version macros (``CINDEX_VERSION_MAJOR``, +``CINDEX_VERSION_MINOR``, and ``CINDEX_VERSION``) which can be used to test for +specific library versions at compile time. The ``CINDEX_VERSION_MAJOR`` macro +is only incremented if there are major source- or ABI-breaking changes. Except +for removing an explicitly deprecate API, the changes listed above are not ---------------- DeinAlptraum wrote:
```suggestion for removing an explicitly deprecated API, the changes listed above are not ``` https://github.com/llvm/llvm-project/pull/141657 _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
