湖南大学SCCI并行计算组-LLVM Clang AST 01-使用libclang(C Routine)操作AST

Clang官网
Clang AST官网简介

湖南大学 SCCI 并行计算组
LLVM Clang AST 01
使用 libclang (C Routine) 操作 AST

利用 libclang 操作 AST 的入口 TranslationUnit

总头文件
clang-c/Index.h

总依赖库
libclang.a
or
libclang.so

1. clang_createIndex() 例程

clang_createIndex 例程官网解释

该例程为创建 TranslationUnit（翻译单元）提供一个可共享的 Context（上下文）。

函数名

clang_createIndex

函数原型

CXIndex clang_createIndex
(
	int   excludeDeclarationsFromPCH,
	int   displayDiagnostics
)

参数解释

• int   excludeDeclarationsFromPCH
  该参数输入值为非0时，允许枚举“本地”声明（当加载任何新翻译单元时），“本地”声明属于翻译单元本身，而不属于翻译单元使用的预编译头。
  该参数输入值为0时，所有声明将被枚举。

• int   displayDiagnostics
  显示诊断。该参数输入值为0时，不显示诊断；输入值非0时，显示诊断。

返回值

• CXIndex
  返回一个 CXIndex 类型的对象，作为 TranslationUnit（翻译单元）可共享的 Context（上下文）。

2. clang_disposeIndex() 例程

clang_disposeIndex 例程官网解释

该例程用于销毁给定 CXIndex。

注意：在CXIndex中创建的所有TranslationUnit都已被销毁前，不得销毁该CXIndex。

函数名

clang_disposeIndex

函数原型

void clang_disposeIndex(CXIndex index)

3. clang_parseTranslationUnit() 例程

clang_parseTranslationUnit例程官网解释

该 Routine 用来解析给定的源文件和生成对应于该文件的 Translation Unit（翻译单元，即AST的根节点）。此例程是Clang C API 的主要入口，它提供了将源文件解析为 Translation Unit 的能力，然后我们可以利用 Clang C API 中的其他 Routine 来查询该翻译单元。此 Routine 会接受一组命令行参数，以便以与在命令行上配置编译器相同的方式配置编译。

函数名

clang_parseTranslationUnit

函数原型

CXTranslationUnit clang_parseTranslationUnit
(
	CXIndex                 CIdx,
	const char *            source_filename,
	const char * const *    command_line_args,
	int                     num_command_line_args,
	struct CXUnsavedFile *  unsaved_files,
	unsigned                num_unsaved_files,
	unsigned                options
)

参数解释

• CXIndex   CIdx
  CXIndex类型是一种“索引”，由一组 Translation Unit 组成，这些 Translation Unit 通常链接到一个可执行文件或库中。

• const char *   source_filename
  source_filename 为要加载的源文件的名称，或者置为 NULL（如果源文件被包含在了下一个参数：command_line_args 参数中）

• const char * const *   command_line_args
  command_line_args 为在正常情况下用 Clang 编译的编译参数。这些传入的编译参数将被解析，并将影响TranslationUnit的解析方式。注意，以下选项将被忽略：“-c”，“-emit ast”，“-fsyntax only”（这是默认值）和 “-o <output file>”。
  比如，如果正常的编译命令是：clang -O2 source.c -o a.out 的话，那么该 command_line_args 为 -O2 source.c -o a.out，但是实际起作用的只有 -O2。

• int   num_command_line_args

  上一个参数的 command_line_args 中参数的个数。
  比如，如果正常的编译命令是：clang -O2 source.c -o a.out 的话，那么 command_line_args 为 -O2 source.c -o a.out，num_command_line_args 的值为 2。

• struct CXUnsavedFile *   unsaved_files
  unsaved_files 是尚未保存到磁盘但可能需要用来解析该 source_filename 的一些文件。必要时会复制这些文件的内容和名称（由CXUnsavedFile指定），因此用户只需保证其有效性，直到调用此函数返回为止。

• unsigned   num_unsaved_files
  上一个参数 unsaved_files 中文件的数量。

• unsigned   options
  选项的位掩码，影响 TranslationUnit 的管理方式，但不影响其编译。 其值的格式为CXTranslationUnit_XXX，见官网解释的CXTranslationUnit_Flags部分。

返回值

• CXTranslationUnit
  一个 CXTranslationUnit 类型的对象，用于存储创建的“CXTranslationUnit”，描述已解析的代码，并包含编译器生成的任何诊断。

另一个相同功能的兄弟函数

clang_parseTranslationUnit2

该 Routine 与 clang_parseTranslationUnit 相同，但返回错误代码而不是CXTranslationUnit，其输出的CXTranslationUnit在参数中，用一个CXTranslationUnit类型指针返回，具体见官网函数解释。

4. clang_disposeTranslationUnit() 例程

该例程用于销毁指定的 CXTranslationUnit 对象。

函数名

clang_disposeTranslationUnit

函数原型

void clang_disposeTranslationUnit(CXTranslationUnit TU)

5. clang_getTranslationUnitSpelling()例程

clang_getTranslationUnitSpelling例程官网解释

该例程用于获取给定 TranslationUnit 的源文件名

函数名

clang_getTranslationUnitSpelling

函数原型

CXString clang_getTranslationUnitSpelling(CXTranslationUnit TU)

返回值

• CXString类型的对象
  CXString类型的对象用于从 Routine 返回 String（字符串）。
  使用 clang_getCString() 例程来获取字符串信息，可以调用clang_disposeString() 例程来释放CXString类型的对象。

CXString原型

CXString类型是一个结构体，存储指向 data 的指针与一个标识符。

typedef struct{
	const void * data;
	unsigned private_flags;
}CXString;

6. clang_getCString()例程

clang_getCString例程官网解释

该例程用于获取与给定CXString类型中的指向字符串数据的指针。

函数名

clang_getCString

函数原型

char * clang_getCString (CXString string)

---

用法举例

代码：

/***********************************
* 文件名: test_TU.c
************************************/
#include <stdio.h>
#include "clang-c/Index.h"

int main(int argc, char *argv[])
{  
    //创键TransactionUnit所需的上下文环境
    CXIndex Index = clang_createIndex(0,0);

    //解析代码，并获得对应的TransactionUnit
    CXTranslationUnit TU =clang_parseTranslationUnit(Index,NULL,argv,argc,0,0,CXTranslationUnit_None);

    //获取TransactionUnit对应的源文件的文件名
    CXString CXstr = clang_getTranslationUnitSpelling(TU);

    //打印文件名
    printf("The source file name is: %s\n",clang_getCString(CXstr));

    //销毁TransactionUnit
    clang_disposeTranslationUnit(TU);

    //销毁Index
    clang_disposeIndex(Index);

    return 0;

}

Makefile

CC := clang

#--------------------------------------------------
# clang-c/Index.h 文件所在的位置
#------------------------------------------------

ClangIncludeDir :=  /home/user/Software-Execution/LLVM/include/


I := -I$(ClangIncludeDir)


#------------------------------------------------------
# libclang.so文件所在的位置
#------------------------------------------------------

ClangLibsPath := /home/user/Software-Execution/LLVM/lib/
 
ClangLibs := -lclang

tst: ./test_TU.c
    $(CC) $(I)  -Wl,-rpath=$(ClangLibsPath) $< -o $@ $(ClangLibs)