caio/clang-p2996
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[Docs] Explicitly document libclang ABI and API stability (#141657)

Browse Source 
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.
This commit is contained in:
Aaron Ballman
2025-06-05 10:37:16 -04:00
committed by GitHub
parent 16c7b3c9f5
commit ab650c697d
1 changed files with 47 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
clang/docs/LibClang.rst
View File

@@ -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,49 @@ 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 (non-exhaustive) situations:
* Adding new enumerator to an enumeration (can be ABI-breaking in C++).
* Removing an explicitly deprecated API after a suitably long deprecation
period.
* Using implementation details, such as names or comments that say something
is "private", "reserved", "internal", etc.
* Bug fixes and changes to Clang's internal implementation happen routinely and
will change the behavior of callers.
* Rarely, bug fixes to libclang itself.
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 deprecated 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.