如何修复Clang及libclang解析Python boolobject.h的错误？

我尝试用以下命令解析Python的boolobject.h头文件以提取所有函数声明：

clang -Xclang -ast-dump -fsyntax-only /usr/local/Cellar/python@3.11/3.11.2/Frameworks/Python.framework/Versions/3.11/include/python3.11/boolobject.h

对应的boolobject.h内容：

/* Boolean object interface */

#ifndef Py_BOOLOBJECT_H
#define Py_BOOLOBJECT_H
#ifdef __cplusplus
extern "C" {
#endif


PyAPI_DATA(PyTypeObject) PyBool_Type;

#define PyBool_Check(x) Py_IS_TYPE(x, &PyBool_Type)

/* Py_False and Py_True are the only two bools in existence.
Don't forget to apply Py_INCREF() when returning either!!! */

/* Don't use these directly */
PyAPI_DATA(PyLongObject) _Py_FalseStruct;
PyAPI_DATA(PyLongObject) _Py_TrueStruct;

/* Use these macros */
#define Py_False ((PyObject *) &_Py_FalseStruct)
#define Py_True ((PyObject *) &_Py_TrueStruct)

// Test if an object is the True singleton, the same as "x is True" in Python.
PyAPI_FUNC(int) Py_IsTrue(PyObject *x);
#define Py_IsTrue(x) Py_Is((x), Py_True)

// Test if an object is the False singleton, the same as "x is False" in Python.
PyAPI_FUNC(int) Py_IsFalse(PyObject *x);
#define Py_IsFalse(x) Py_Is((x), Py_False)

/* Macros for returning Py_True or Py_False, respectively */
#define Py_RETURN_TRUE return Py_NewRef(Py_True)
#define Py_RETURN_FALSE return Py_NewRef(Py_False)

/* Function to return a bool from a C long */
PyAPI_FUNC(PyObject *) PyBool_FromLong(long);

#ifdef __cplusplus
}
#endif
#endif /* !Py_BOOLOBJECT_H */

命令行解析报错 #

执行命令后出现一系列错误：

boolobject.h:10:26: error: expected function body after function declarator
PyAPI_DATA(PyTypeObject) PyBool_Type;
                         ^
boolobject.h:18:26: error: expected function body after function declarator
PyAPI_DATA(PyLongObject) _Py_FalseStruct;
                         ^
boolobject.h:19:26: error: expected function body after function declarator
PyAPI_DATA(PyLongObject) _Py_TrueStruct;
                         ^
boolobject.h:26:17: error: expected function body after function declarator
PyAPI_FUNC(int) Py_IsTrue(PyObject *x);
                ^
boolobject.h:30:17: error: expected function body after function declarator
PyAPI_FUNC(int) Py_IsFalse(PyObject *x);
                ^
boolobject.h:38:12: error: unknown type name 'PyObject'
PyAPI_FUNC(PyObject *) PyBool_FromLong(long);
           ^
boolobject.h:38:24: error: expected function body after function declarator
PyAPI_FUNC(PyObject *) PyBool_FromLong(long);
                       ^

libclang解析不完整 #

我用Python的libclang尝试解析，代码如下：

import sys
from typing import List

import clang
import clang.cindex
from clang.cindex import *

def traverse(node):
    for child in node.get_children():
        traverse(child)
    print('Found %s [line=%s, col=%s] -- %s' % (node.displayname, node.location.line, node.location.column, node.kind))


if __name__ == "__main__":
    clang.cindex.Config.set_library_path('/Library/Developer/CommandLineTools/usr/lib')

    index = Index.create()
    args = ['-xc++', '--std=c++17']
    translation_unit = index.parse(
        "/usr/local/Cellar/python@3.11/3.11.2/Frameworks/Python.framework/Versions/3.11/include/python3.11/boolobject.h",
        args=args,
        options=TranslationUnit.PARSE_INCOMPLETE)
    print('Translation unit:', translation_unit.spelling)
    traverse(translation_unit.cursor)

但解析结果不完整，仅输出VAR_DECL节点：

Found PyTypeObject [line=10, col=12] -- CursorKind.VAR_DECL
Found PyLongObject [line=18, col=12] -- CursorKind.VAR_DECL
Found PyLongObject [line=19, col=12] -- CursorKind.VAR_DECL
Found  [line=6, col=8] -- CursorKind.UNEXPOSED_DECL

请问如何修复这些问题以实现完整解析？是否遗漏了相关参数？

1. 修复命令行解析问题 #

报错核心原因是：

• PyAPI_DATA、PyAPI_FUNC、PyObject等宏/类型未定义，clang无法识别其真实含义
• 单独解析boolobject.h时，缺少Python头文件的依赖（如Python.h）

修复后的完整命令：

clang -Xclang -ast-dump -fsyntax-only \
-I/usr/local/Cellar/python@3.11/3.11.2/Frameworks/Python.framework/Versions/3.11/include/python3.11 \
-xc \
/usr/local/Cellar/python@3.11/3.11.2/Frameworks/Python.framework/Versions/3.11/include/python3.11/boolobject.h

参数说明：

• -I：添加Python的include目录，解决头文件依赖问题
• -xc：强制以C语言模式解析（Python的C API基于C标准，显式指定更可靠）

执行后即可正确解析所有函数声明和变量定义，不会再报语法错误。

2. 修复libclang解析问题 #

同样需要解决依赖头文件和解析模式的问题，修改后的代码如下：

import sys
import clang.cindex
from clang.cindex import *

def traverse(node):
    for child in node.get_children():
        traverse(child)
    # 过滤无关节点，只输出有用的声明内容
    if node.kind in [CursorKind.FUNCTION_DECL, CursorKind.VAR_DECL, CursorKind.MACRO_DEFINITION]:
        print('Found %s [line=%s, col=%s] -- %s' % (node.displayname, node.location.line, node.location.column, node.kind))


if __name__ == "__main__":
    clang.cindex.Config.set_library_path('/Library/Developer/CommandLineTools/usr/lib')

    index = Index.create()
    python_include_dir = '/usr/local/Cellar/python@3.11/3.11.2/Frameworks/Python.framework/Versions/3.11/include/python3.11'
    args = [
        '-xc',
        f'-I{python_include_dir}'
    ]
    translation_unit = index.parse(
        f"{python_include_dir}/boolobject.h",
        args=args,
        # 启用完整解析模式，保证获取所有节点
        options=TranslationUnit.PARSE_DETAILED_PROCESSING_RECORD)
    print('Translation unit:', translation_unit.spelling)
    traverse(translation_unit.cursor)

关键修改点：

• 添加-I参数指定Python include目录，解决依赖问题
• 替换为-xc强制C语言模式解析（原代码用C++模式会导致宏解析差异）
• 移除PARSE_INCOMPLETE选项，改用PARSE_DETAILED_PROCESSING_RECORD保证完整解析
• 增加节点过滤逻辑，只保留函数声明、变量声明、宏定义等有用内容

运行修改后的代码，就能看到完整的解析结果，包括Py_IsTrue、Py_IsFalse、PyBool_FromLong等函数声明。

内容的提问来源于stack exchange，提问作者Brandon