[Docs] Explicitly document libclang ABI and API stability #141657
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Our current docs leave a lot of latitude ("relatively stable") without
explaining what the goals are for this stability. This patch adds some
basic documentation explaining that there are some changes which can
impact ABI and API stability that we reserve the right to make, lists
some scenarios we explicitly do not support, but otherwise tries to
assure the reader that the APIs and ABI are stable.
|
@llvm/pr-subscribers-clang Author: Aaron Ballman (AaronBallman) ChangesOur current docs leave a lot of latitude ("relatively stable") without explaining what the goals are for this stability. This patch adds some basic documentation explaining that there are some changes which can impact ABI and API stability that we reserve the right to make, lists some scenarios we explicitly do not support, but otherwise tries to assure the reader that the APIs and ABI are stable. Full diff: https://github.com/llvm/llvm-project/pull/141657.diff 1 Files Affected:
diff --git a/clang/docs/LibClang.rst b/clang/docs/LibClang.rst
index 08cf452a0df6c..bfcb95ee4a8ad 100644
--- a/clang/docs/LibClang.rst
+++ b/clang/docs/LibClang.rst
@@ -4,7 +4,7 @@
Libclang tutorial
=================
The C Interface to Clang provides a relatively small API that exposes facilities for parsing source code into an abstract syntax tree (AST), loading already-parsed ASTs, traversing the AST, associating physical source locations with elements within the AST, and other facilities that support Clang-based development tools.
-This C interface to Clang will never provide all of the information representation stored in Clang's C++ AST, nor should it: the intent is to maintain an API that is relatively stable from one release to the next, providing only the basic functionality needed to support development tools.
+This C interface to Clang will never provide all of the information representation stored in Clang's C++ AST, nor should it: the intent is to maintain an API that is :ref:`relatively stable <Stability>` from one release to the next, providing only the basic functionality needed to support development tools.
The entire C interface of libclang is available in the file `Index.h`_
Essential types overview
@@ -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
+considered major source- or ABI-breaking changes. Historically, the value this
+macro expands to has not changed, but may be incremented in the future should
+the need arise. The ``CINDEX_VERSION_MINOR`` macro is incremented as new APIs
+are added. The ``CINDEX_VERSION`` macro expands to a value based on the major
+and minor version macros.
+
+In an effort to allow the library to be modified as new needs arise, the
+following situations are explicitly unsupported:
+
+* Loading different library versions into the same executable and passing
+ objects between the libraries; despite general ABI stability, different
+ versions of the library may use different implementation details that are not
+ compatible across library versions.
+* For the same reason as above, serializing objects from one version of the
+ library and deserializing with a different version is also not supported.
|
|
I've added a handful of folks who might be reasonable reviewers for this, but if you know of anyone else who may have an opinion, feel free to rope them in. These changes came about because of #134551 where someone was trying to add a better string API that handles embedded nulls but we ran into "ABI stability" when working through the implementation. The intent here is not to shift away from ABI stability for the library but to remind folks that we still need enough wiggle room to maintain and evolve it, and that underlying details of Clang can sometimes still mean breaking changes between libclang versions. |
DeinAlptraum
approved these changes
May 27, 2025
Endilll
reviewed
May 28, 2025
Endilll
approved these changes
Jun 5, 2025
I had an offline discussion with Endilll and we came up with some small adjustments.
DeinAlptraum
approved these changes
Jun 5, 2025
|
LLVM Buildbot has detected a new failure on builder Full details are available at: https://lab.llvm.org/buildbot/#/builders/88/builds/12487 Here is the relevant piece of the build log for the reference |
rorth
pushed a commit
to rorth/llvm-project
that referenced
this pull request
Jun 11, 2025
Our current docs leave a lot of latitude ("relatively stable") without
explaining what the goals are for this stability. This patch adds some
basic documentation explaining that there are some changes which can
impact ABI and API stability that we reserve the right to make, lists
some scenarios we explicitly do not support, but otherwise tries to
assure the reader that the APIs and ABI are stable.
DhruvSrivastavaX
pushed a commit
to DhruvSrivastavaX/lldb-for-aix
that referenced
this pull request
Jun 12, 2025
Our current docs leave a lot of latitude ("relatively stable") without
explaining what the goals are for this stability. This patch adds some
basic documentation explaining that there are some changes which can
impact ABI and API stability that we reserve the right to make, lists
some scenarios we explicitly do not support, but otherwise tries to
assure the reader that the APIs and ABI are stable.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Our current docs leave a lot of latitude ("relatively stable") without explaining what the goals are for this stability. This patch adds some basic documentation explaining that there are some changes which can impact ABI and API stability that we reserve the right to make, lists some scenarios we explicitly do not support, but otherwise tries to assure the reader that the APIs and ABI are stable.