ACAV: Overview

ACAV f0ba4b7c9529

Abstract Syntax Tree (AST) visualization tool for C, C++, and Objective-C

Loading...
Searching...
No Matches

Overview

ACAV (Aurora Clang AST Viewer) is an interactive Abstract Syntax Tree (AST) visualization tool for C, C++, and Objective-C, built with Clang and Qt. Given a JSON compilation database such as compile_commands.json, ACAV lets you open a real project, inspect the AST for a translation unit, and move directly between source code and AST nodes.

Screenshot: ACAV displaying the file explorer, source-code panel, AST tree view, declaration-context panels, and log panel.

Project Links

Project codebase
Project introduction page
Online manual

At a Glance
With a valid compilation database, ACAV lets you:

inspect the AST for a translation unit in a navigable tree,
move in both directions between source locations and AST nodes,
view declaration context while exploring program structure,
search both source text and AST nodes, and
reuse dependency and AST-cache artifacts across sessions.

ACAV follows a three-program architecture:

acav is the interactive GUI application.
query-dependencies extracts dependency information from a compilation database.
make-ast builds and caches serialized AST files for individual source files.

Purpose and Scope
ACAV addresses the gap between Clang's powerful front-end infrastructure and the practical difficulty of exploring Clang ASTs interactively. It is designed for real codebases rather than toy examples: it reads a JSON compilation database, applies the recorded build settings for each source file, and keeps the interface responsive through background processing and AST caching.
ACAV is useful for students learning compiler internals, researchers studying program structure, and developers building or debugging Clang-based tools. Its current scope is intentionally limited to read-only AST exploration. ACAV does not modify source code, perform refactoring, or act as a general-purpose editor, and it displays the AST of one translation unit at a time.

Quick Start
The typical workflow is:

Generate or locate a compilation database for the target project.
Build or install ACAV by following Installation.
Launch ACAV:
acav -c /path/to/compile_commands.json

Browse files in the file explorer, then double-click a file or press F5 to generate or load its AST.
Use the source view, AST view, and declaration context view to navigate the program structure.

Documentation Organization

License points to the authoritative license file.
Installation covers prerequisites, native builds, and the containerized workflow.
Docker/Podman Demo Image provides detailed OCI demo image instructions.
User Manual describes the GUI, common workflows, the command-line programs, keyboard shortcuts, and configuration.
References lists related technologies and resources.
Classes provides the generated class reference.
Files provides the generated file reference.
Changelog provides public release notes for ACAV.
Notice provides project attribution, authorship, and licensing context.

How to Use This Manual
If you are new to ACAV, start with this overview, then Installation, and then User Manual. If you want to inspect the API surface, use Classes and Files. If you want to review public release notes, see the Changelog.

Generated by 1.16.1

ACAV, or Aurora Clang AST Viewer, is an interactive tool designed for visualizing the Abstract Syntax Tree (AST) of C, C++, and Objective-C code, leveraging Clang and Qt for its implementation. The core functionality of ACAV centers on allowing users to inspect the AST for a specific translation unit within a navigable structure, linking source code locations directly to corresponding AST nodes. This functionality is enabled by reading a compilation database, such as compile_commands.json, which provides the necessary context to analyze real projects.

The utility of ACAV is defined by several key capabilities: enabling navigation between the source code and the AST, viewing declaration context while exploring the program structure, facilitating searching across both the source text and the AST nodes, and allowing the reuse of dependency and AST-cache artifacts across different sessions. To achieve this interactive exploration in large codebases, ACAV employs a three-program architectural design. This architecture consists of acav, which serves as the interactive graphical user interface; query-dependencies, which is responsible for extracting dependency information from the compilation database; and make-ast, which handles the process of building and caching serialized AST files for individual source files.

ACAV is positioned to address a critical gap in the field by facilitating the practical exploration of Clang's powerful front-end infrastructure. It is intended for use on actual codebases rather than simple examples, processing build settings recorded in a compilation database to accurately analyze the structure. The scope of ACAV is intentionally limited to read-only AST exploration; it does not possess capabilities for modifying source code, performing refactoring operations, or functioning as a general-purpose editor, focusing instead on displaying the AST of a single translation unit at any given time.

The typical workflow for using ACAV begins with generating or locating a suitable compilation database for the target project. Following setup, the user launches the application, typically by specifying the path to the compilation database, which initiates the interaction. The workflow involves browsing files in the file explorer, loading or generating the AST for selected files, and utilizing the source view, AST view, and declaration context view to survey the program structure. Comprehensive documentation is provided to support this usage, covering installation procedures, user manuals detailing common workflows and keyboard shortcuts, instructions for setting up containerized environments, and references to related technologies and project artifacts.