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. 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
structfoo{
intbar;
int*bar_pointer;
};

// main.cpp
#include<clang-c/Index.h>
#include<iostream>
intmain(){
CXIndexindex=clang_createIndex(0,0);//Create index
CXTranslationUnitunit=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";
return0;
}
CXCursorcursor=clang_getTranslationUnitCursor(unit);//Obtain a cursor at the root of the translation unit
}

# CMakeLists.txt
cmake_minimum_required(VERSION3.20)
project(my_clang_toolVERSION0.1.0)
# This will find the default system installation of Clang; if you want to
# use a different build of clang, pass -DClang_DIR=/foobar/lib/cmake/clang
# to the CMake configure command, where /foobar is the build directory where
# you built Clang.
find_package(ClangCONFIGREQUIRED)
add_executable(my_clang_toolmain.cpp)
target_include_directories(my_clang_toolPRIVATE${CLANG_INCLUDE_DIRS})
target_link_libraries(my_clang_toolPRIVATElibclang)

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
[](CXCursorcurrent_cursor,CXCursorparent,CXClientDataclient_data){
CXStringcurrent_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
returnCXChildVisit_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

Extracting information from a Cursor

Extracting the Cursor kind

CXCursorKind clang_getCursorKind(CXCursor) Describes the kind of entity that a cursor refers to. Example values:

  • CXCursor_StructDecl: A C or C++ struct.

  • CXCursor_FieldDecl: A field in a struct, union, or C++ class.

  • CXCursor_CallExpr: An expression that calls a function.

Extracting the Cursor type

CXType clang_getCursorType(CXCursor): Retrieve the type of a CXCursor (if any).

A CXType represents a complete C++ type, including qualifiers and pointers. It has a member field CXTypeKind kind and additional opaque data.

Example values for CXTypeKind kind

  • CXType_Invalid: Represents an invalid type (e.g., where no type is available)

  • CXType_Pointer: A pointer to another type

  • CXType_Int: Regular int

  • CXType_Elaborated: Represents a type that was referred to using an elaborated type keyword e.g. struct S, or via a qualified name, e.g., N::M::type, or both.

Any CXTypeKind can be converted to a CXString using clang_getTypeKindSpelling(CXTypeKind).

A CXType holds additional necessary opaque type info, such as:

  • Which struct was referred to?

  • What type is the pointer pointing to?

  • Qualifiers (e.g. const, volatile)?

Qualifiers of a CXType can be queried with:

  • clang_isConstQualifiedType(CXType) to check for const

  • clang_isRestrictQualifiedType(CXType) to check for restrict

  • clang_isVolatileQualifiedType(CXType) to check for volatile

Code example 

//structs.cpp
structA{
intvalue;
};
structB{
intvalue;
Astruct_value;
};

#include<clang-c/Index.h>
#include<iostream>
intmain(){
CXIndexindex=clang_createIndex(0,0);//Create index
CXTranslationUnitunit=clang_parseTranslationUnit(
index,
"structs.cpp",nullptr,0,
nullptr,0,
CXTranslationUnit_None);//Parse "structs.cpp"
if(unit==nullptr){
std::cerr<<"Unable to parse translation unit. Quitting.\n";
return0;
}
CXCursorcursor=clang_getTranslationUnitCursor(unit);//Obtain a cursor at the root of the translation unit
clang_visitChildren(
cursor,
[](CXCursorcurrent_cursor,CXCursorparent,CXClientDataclient_data){
CXTypecursor_type=clang_getCursorType(current_cursor);
CXStringtype_kind_spelling=clang_getTypeKindSpelling(cursor_type.kind);
std::cout<<"Type Kind: "<<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 (&&),
CXTypepointed_to_type=clang_getPointeeType(cursor_type);// retrieve the pointed-to type
CXStringpointed_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);
}
elseif(cursor_type.kind==CXType_Record){
CXStringtype_spelling=clang_getTypeSpelling(cursor_type);
std::cout<<", namely "<<clang_getCString(type_spelling);
clang_disposeString(type_spelling);
}
std::cout<<"\n";
returnCXChildVisit_Recurse;
},
nullptr
);

The expected output of program is:

Type Kind: Record, namely A
Type Kind: Int
Type Kind: Record, namely B
Type Kind: Int
Type Kind: Record, namely A
Type Kind: Record, namely A

Reiterating the difference between CXType and CXTypeKind: For an example

constchar*__restrict__variable;

  • Type Kind will be: CXType_Pointer spelled "Pointer"

  • Type will be a complex CXType structure, spelled "const char* __restrict__

Retrieving source locations

CXSourceRange clang_getCursorExtent(CXCursor) returns a CXSourceRange, representing a half-open range in the source code.

Use clang_getRangeStart(CXSourceRange) and clang_getRangeEnd(CXSourceRange) to retrieve the starting and end CXSourceLocation from a source range, respectively.

Given a CXSourceLocation, use clang_getExpansionLocation to retrieve file, line and column of a source location.

Code example 

// Again, file.cpp
structfoo{
intbar;
int*bar_pointer;
};

clang_visitChildren(
cursor,
[](CXCursorcurrent_cursor,CXCursorparent,CXClientDataclient_data){
CXTypecursor_type=clang_getCursorType(current_cursor);
CXStringcursor_spelling=clang_getCursorSpelling(current_cursor);
CXSourceRangecursor_range=clang_getCursorExtent(current_cursor);
std::cout<<"Cursor "<<clang_getCString(cursor_spelling);
CXFilefile;
unsignedstart_line,start_column,start_offset;
unsignedend_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";
returnCXChildVisit_Recurse;
},
nullptr
);

The expected output of this program is:

Cursor foo spanning lines 2 to 5
Cursor bar spanning lines 3 to 3
Cursor bar_pointer spanning lines 4 to 4

Complete example code 

// main.cpp
#include<clang-c/Index.h>
#include<iostream>
intmain(){
CXIndexindex=clang_createIndex(0,0);//Create index
CXTranslationUnitunit=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";
return0;
}
CXCursorcursor=clang_getTranslationUnitCursor(unit);//Obtain a cursor at the root of the translation unit
clang_visitChildren(
cursor,
[](CXCursorcurrent_cursor,CXCursorparent,CXClientDataclient_data){
CXTypecursor_type=clang_getCursorType(current_cursor);
CXStringtype_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 (&&),
CXTypepointed_to_type=clang_getPointeeType(cursor_type);// retrieve the pointed-to type
CXStringpointed_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);
}
elseif(cursor_type.kind==CXType_Record){
CXStringtype_spelling=clang_getTypeSpelling(cursor_type);
std::cout<<", namely "<<clang_getCString(type_spelling);
clang_disposeString(type_spelling);
}
std::cout<<"\n";
returnCXChildVisit_Recurse;
},
nullptr
);
clang_visitChildren(
cursor,
[](CXCursorcurrent_cursor,CXCursorparent,CXClientDataclient_data){
CXTypecursor_type=clang_getCursorType(current_cursor);
CXStringcursor_spelling=clang_getCursorSpelling(current_cursor);
CXSourceRangecursor_range=clang_getCursorExtent(current_cursor);
std::cout<<"Cursor "<<clang_getCString(cursor_spelling);
CXFilefile;
unsignedstart_line,start_column,start_offset;
unsignedend_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";
returnCXChildVisit_Recurse;
},
nullptr
);
}

# CMakeLists.txt
cmake_minimum_required(VERSION3.20)
project(my_clang_toolVERSION0.1.0)
# This will find the default system installation of Clang; if you want to
# use a different build of clang, pass -DClang_DIR=/foobar/lib/cmake/clang
# to the CMake configure command, where /foobar is the build directory where
# you built Clang.
find_package(ClangCONFIGREQUIRED)
add_executable(my_clang_toolmain.cpp)
target_include_directories(my_clang_toolPRIVATE${CLANG_INCLUDE_DIRS})
target_link_libraries(my_clang_toolPRIVATElibclang)

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.

Note: because libclang is a wrapper around the compiler frontend, it is not a security-sensitive component of the LLVM Project. Consider using a sandbox or some other mitigation approach if processing untrusted input.