[clang] [Docs] Explicitly document libclang ABI and API stability (PR #141657)
Vlad Serebrennikov via cfe-commits
cfe-commits at lists.llvm.org
Tue May 27 23:06:34 PDT 2025
================
@@ -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.
----------------
Endilll wrote:
> Is this list meant to be exhaustive? If not, perhaps the wording should be changed.
I think "etc." at the end conveys that it's not exhaustive
> I'm coming only from the Python-bindings perspective, but we did have a number of "potentially breaking changes"
Yeah, bindings for specific languages need additional docs, because they are not as conservative as C API.
https://github.com/llvm/llvm-project/pull/141657
More information about the cfe-commits
mailing list