Libclang tutorial — Clang 21.0.0git documentation (original) (raw)
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. The entire C interface of libclang is available in the file Index.h
Essential types overview¶
All types of libclang are prefixed with CX
CXIndex¶
An Index that consists of a set of translation units that would typically be linked together into an executable or library.
CXTranslationUnit¶
A single translation unit, which resides in an index.
CXCursor¶
A cursor representing a pointer to some element in the abstract syntax tree of a translation unit.
Code example¶
// file.cpp struct foo{ int bar; int* bar_pointer; };
#include <clang-c/Index.h> #include
int main(){ CXIndex index = clang_createIndex(0, 0); //Create index CXTranslationUnit unit = clang_parseTranslationUnit( index, "file.cpp", nullptr, 0, nullptr, 0, CXTranslationUnit_None); //Parse "file.cpp"
if (unit == nullptr){ std::cerr << "Unable to parse translation unit. Quitting.\n"; return 0; } CXCursor cursor = clang_getTranslationUnitCursor(unit); //Obtain a cursor at the root of the translation unit }
Visiting elements of an AST¶
The elements of an AST can be recursively visited with pre-order traversal with clang_visitChildren
.
clang_visitChildren( cursor, //Root cursor [](CXCursor current_cursor, CXCursor parent, CXClientData client_data){
CXString current_display_name = clang_getCursorDisplayName(current_cursor);
//Allocate a CXString representing the name of the current cursor
std::cout << "Visiting element " << clang_getCString(current_display_name) << "\n";
//Print the char* value of current_display_name
clang_disposeString(current_display_name);
//Since clang_getCursorDisplayName allocates a new CXString, it must be freed. This applies
//to all functions returning a CXString
return CXChildVisit_Recurse;
}, //CXCursorVisitor: a function pointer nullptr //client_data );
The return value of CXCursorVisitor
, the callable argument of clang_visitChildren
, can return one of the three:
CXChildVisit_Break
: Terminates the cursor traversalCXChildVisit_Continue
: Continues the cursor traversal with the next sibling of the cursor just visited, without visiting its children.CXChildVisit_Recurse
: Recursively traverse the children of this cursor, using the same visitor and client data
The expected output of that program is
Visiting element foo Visiting element bar Visiting element bar_pointer
Complete example code¶
#include <clang-c/Index.h> #include
int main(){ CXIndex index = clang_createIndex(0, 0); //Create index CXTranslationUnit unit = clang_parseTranslationUnit( index, "file.cpp", nullptr, 0, nullptr, 0, CXTranslationUnit_None); //Parse "file.cpp"
if (unit == nullptr){ std::cerr << "Unable to parse translation unit. Quitting.\n"; return 0; } CXCursor cursor = clang_getTranslationUnitCursor(unit); //Obtain a cursor at the root of the translation unit
clang_visitChildren( cursor, [](CXCursor current_cursor, CXCursor parent, CXClientData client_data){ CXType cursor_type = clang_getCursorType(current_cursor);
CXString type_kind_spelling = clang_getTypeKindSpelling(cursor_type.kind);
std::cout << "TypeKind: " << clang_getCString(type_kind_spelling);
clang_disposeString(type_kind_spelling);
if(cursor_type.kind == CXType_Pointer || // If cursor_type is a pointer
cursor_type.kind == CXType_LValueReference || // or an LValue Reference (&)
cursor_type.kind == CXType_RValueReference){ // or an RValue Reference (&&),
CXType pointed_to_type = clang_getPointeeType(cursor_type);// retrieve the pointed-to type
CXString pointed_to_type_spelling = clang_getTypeSpelling(pointed_to_type); // Spell out the entire
std::cout << "pointing to type: " << clang_getCString(pointed_to_type_spelling);// pointed-to type
clang_disposeString(pointed_to_type_spelling);
}
else if(cursor_type.kind == CXType_Record){
CXString type_spelling = clang_getTypeSpelling(cursor_type);
std::cout << ", namely " << clang_getCString(type_spelling);
clang_disposeString(type_spelling);
}
std::cout << "\n";
return CXChildVisit_Recurse;
}, nullptr );
clang_visitChildren( cursor, [](CXCursor current_cursor, CXCursor parent, CXClientData client_data){
CXType cursor_type = clang_getCursorType(current_cursor);
CXString cursor_spelling = clang_getCursorSpelling(current_cursor);
CXSourceRange cursor_range = clang_getCursorExtent(current_cursor);
std::cout << "Cursor " << clang_getCString(cursor_spelling);
CXFile file;
unsigned start_line, start_column, start_offset;
unsigned end_line, end_column, end_offset;
clang_getExpansionLocation(clang_getRangeStart(cursor_range), &file, &start_line, &start_column, &start_offset);
clang_getExpansionLocation(clang_getRangeEnd (cursor_range), &file, &end_line , &end_column , &end_offset);
std::cout << " spanning lines " << start_line << " to " << end_line;
clang_disposeString(cursor_spelling);
std::cout << "\n";
return CXChildVisit_Recurse;
}, nullptr ); }
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.