diff --git a/clang/docs/LibClang.rst b/clang/docs/LibClang.rst index 08cf452a0df6c..9e72400e3dde5 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 ` 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,48 @@ 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 or changes to Clang's internal implementation, or (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.