standardese/cppast for C++ AST tooling

Where cppast sits among Clang interfaces

cppast addresses a specific gap for standalone C++ tooling. A documentation generator, reflection-oriented tool, or AST-based code generator may need to inspect declarations, types, templates, macros, attributes, and documentation comments. The README says that Clang offers three interfaces for tools, but identifies libclang as the one that works for standalone applications. It also notes that libclang does not expose the entire AST.

cppast adds a native C++ library interface over that parsing capability. According to the repository description, it is intended to parse source files, synthesize entities, retrieve documentation comments, and generate code. The parser hierarchy is separate from the AST representation. That separation permits another parsing backend and also allows applications to construct AST entities instead of obtaining every node from source text.

This is useful when an application wants structured C++ objects rather than the C-facing API of libclang. It does not turn cppast into a compiler frontend. Its stated coverage is concentrated on declarations and types. Function bodies are not parsed, expression support currently exposes literal expressions, and parsed entities are immutable. Those boundaries matter more than the broad entity list when selecting a parser for refactoring or source-to-source transformation.

cppast's entity, type, and expression model

The API organizes the AST around three class hierarchies. `cpp_entity` represents C++ declarations and definitions, along with related entities such as function parameters and `static_assert()`. `cpp_type` represents types and can be reached from entities that contain a type. The documented type examples include `cpp_builtin_type` and `cpp_pointer_type`.

The third hierarchy is `cpp_expression`. An entity can contain an expression, with `cpp_function_parameter` and its `default_value()` serving as the documented relationship. The current expression hierarchy includes `cpp_literal_expression` and `cpp_unexposed_expression`. This naming is important because unexposed is a boundary: the interface can carry an expression node without exposing every operation represented by it.

The README says that the model covers almost all C++ entities, including functions, classes, templates, friend declarations, macros, and enums. It also documents support for C++11 attributes, including user-defined attributes, and documentation comments in several formats with matching against the corresponding AST entity. These claims describe a declaration-oriented model. They should not be read as full syntax coverage for C++ expressions or statements.

libclang parsing and cppast's workarounds

The included parsing backend is `libclang_parser`. It requires `libclang` and the `clang++` binary, with at least version 15 according to the README. `clang++` is located through `PATH` or in the same directory as the running program. CMake configuration also relies on `llvm-config` to locate LLVM components.

The project acknowledges that libclang has limitations and bugs. According to the README, cppast implements workarounds around those issues and directs readers to issues labelled `libclang-parser` for known parser cases. That is a meaningful distinction from a dependency-free parser, but it is not a guarantee of error-free C++ parsing. Parser fidelity still depends on the quality and compatibility of the underlying Clang installation.

The AST representation is decoupled from `parser`, so applications are not required to use this backend. A different implementation can feed the same entity and type model, and synthetic entities can be created directly. That architecture is appealing for generators and documentation systems, yet it also means backend behavior must be evaluated separately from the richness of the AST classes. A feature represented in `cpp_entity` is not necessarily reconstructed by every parser.

Building cppast with pixi and CMake

The README recommends pixi for development. These commands compile the package, invoke its test suite, and run the `cppast` tool. The tool directory contains an example application that prints an AST, which makes this the shortest documented path to a first real use.

pixi run build

This compiles the package using the repository's pixi environment.

pixi run test

This invokes the documented test suite.

pixi run cppast

This runs the project tool. The README identifies `tool/main.cpp` as a simple application that prints the AST, so the expected result is AST output rather than a GUI or standalone application window.

For use from another CMake project, the documented integration is to add cppast as a subdirectory and link the `cppast` target. The consumer must enable C++11 or later.

add_subdirectory(path/to/cppast)

This incorporates cppast's CMake project from the checked-out repository. The target name is `cppast`, and the README does not provide a complete consumer `CMakeLists.txt`, so no further link command can be reproduced safely from the available instructions.

Dependencies such as `type_safe` are acquired with `FetchContent` when they are not already installed. A machine without network access during configuration therefore needs dependencies already available or an explicitly prepared build environment. The README does not describe an offline FetchContent mode.

LLVM configuration and Windows dependency constraints

A normal CMake configuration looks for `llvm-config`. The README warns that installing `clang` may not be enough because `llvm-config` belongs to the LLVM tooling package. On systems such as ArchLinux, it says that installing `llvm` rather than only `clang` may be necessary. When discovery fails, `LLVM_CONFIG_BINARY` can point CMake to the correct executable.

When `llvm-config` is unavailable, the documented controls are `LLVM_VERSION_EXPLICIT`, `LIBCLANG_LIBRARY`, `LIBCLANG_INCLUDE_DIR`, and `CLANG_BINARY`. These settings require a matching LLVM version, the libclang library file, the directory containing headers such as `clang-c/Index.h`, and the full path to `clang++`. The README does not provide a complete configuration file with values for every system, so there is no portable snippet to reproduce here.

Windows adds a larger setup cost. The README says release binaries do not include `llvm-config.exe`, so users may need to compile it or obtain it from a third party. It suggests matching LLVM, libclang, and llvm-config versions, and lists Visual Studio 2017, LLVM, and Clang installation steps. These instructions reflect the repository's documentation and may not match the stated minimum Clang version without further checking.

The Windows guide also contains version-specific instructions involving an LLVM checkout and a Visual Studio generator. They should not be treated as a version-independent modern setup. The central operational requirement is still explicit LLVM configuration when automatic discovery does not work.

Code generation with explicit AST boundaries

cppast provides a code generation interface described as simple and customizable. Its entity model can also be synthesized independently of the parser, which supports applications that build output from discovered or constructed declarations. The README connects these capabilities to tools such as documentation generators, although it does not publish a short generator API example in the available text.

The repository contains examples named `documentation_generator.cpp`, `serialization.cpp`, `enum_category.cpp`, `enum_to_string.cpp`, `comparison.cpp`, and `ast_printer.cpp`. Based on the repository layout, these are distinct examples rather than one complete workflow. The README specifically points new readers to `tool/main.cpp` for a simple AST-printing application.

There are hard boundaries to consider before choosing cppast for transformation. Parsed entities cannot currently be modified. Expressions are limited to literal exposure. Statements are not parsed because function bodies are absent. Separate specialization of members within a template is also unsupported. These are not minor parser conveniences. Each changes the kind of tool cppast can support. It is better suited to inspection, documentation, classification, serialization, and synthesis around declarations than to editing an existing implementation.

Release history, maintenance, and licence review

The repository is not archived, and its last push was on 2026-05-20. The available release history lists `v0.1.0`, dated 2022-02-07. A recent repository change and an older tagged release are separate signals. The former does not establish that a new release has been published, and the latter does not show whether the current `main` branch has had compatibility work since then.

The repository labels its licence as a custom licence that GitHub cannot classify. The actual permissions, restrictions, attribution requirements, and redistribution conditions must be read in `LICENSE.md`. This article does not interpret those terms or provide legal advice. The licence is an explicit adoption check because cppast is intended to be embedded into other C++ tools through its CMake target.

Upgrade planning also depends on the LLVM side of the installation. The README requires Clang 15 or later and gives manual configuration controls when automatic discovery fails. The Windows guidance goes further by warning about version mismatches among LLVM, libclang, and `llvm-config.exe`. That dependency setup can dominate the initial integration cost, especially where consistent LLVM packages are not readily available.

Editorial conclusion

Adopt cppast when a documentation generator, source analyzer, or code generator needs declaration-level C++ AST access without depending directly on libclang's C interface. Do not adopt it as a full C++ parser for refactoring, statement analysis, or expression transformation. Verify the custom LICENSE.md terms, confirm that your LLVM installation provides compatible libclang, clang++, and llvm-config components, and inspect whether literal-only expression coverage meets the tool's first production workload.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. standardese/cppast on GitHub