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:

  1. CXChildVisit_Break: Terminates the cursor traversal
  2. CXChildVisit_Continue: Continues the cursor traversal with the next sibling of the cursor just visited, without visiting its children.
  3. 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:

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: