Skip to content

CLAUDE.md

Latest commit

 

History

History
240 lines (165 loc) · 7.97 KB

CLAUDE.md

File metadata and controls

240 lines (165 loc) · 7.97 KB

llcppg Project AI Assistant Guide

This guide helps AI assistants like Claude Code understand and work effectively with the llcppg project - a tool for automatically generating LLGo bindings for C/C++ libraries.

Project Overview

llcppg is a binding generator that bridges C/C++ libraries to LLGo (a Go-based compiler). It processes C/C++ header files and generates idiomatic Go bindings, enabling Go code to seamlessly interact with C/C++ libraries.

Core Components

  1. llcppcfg - Configuration file generator (Go)
  2. llcppg - Main binding generator (Go)
  3. gogensig - Go signature generator (Go)
  4. llcppsymg - Symbol generator (LLGo, requires LLGo compilation)
  5. llcppsigfetch - Signature fetcher (LLGo, requires LLGo compilation)

Key Directories

  • cmd/ - Main executables (llcppg, llcppcfg, gogensig)
  • _xtool/ - LLGo-compiled tools (llcppsymg, llcppsigfetch)
  • cl/ - Core conversion logic and AST processing
  • parser/ - C/C++ header file parsing interface. The core C AST to internal AST conversion logic is in _xtool/internal/parser, compiled with LLGo
  • config/ - Configuration file handling
  • _llcppgtest/ - Real-world binding examples (cjson, sqlite, lua, etc.)
  • _demo/ - Simple demonstration projects
  • _cmptest/ - Comparison and end-to-end tests

Development Setup

For detailed setup instructions including prerequisites, dependencies, and installation steps, see README.md.

Building and Testing

Build Commands

go build -v ./...

Testing Strategy

Unit Tests (Priority)

go test -v ./config ./internal/name ./internal/arg ./internal/unmarshal

Always run these unit tests first for quick validation before running the full test suite.

LLGo-Dependent Tests

llgo test ./_xtool/internal/...
llgo test ./_xtool/llcppsigfetch/internal/...
llgo test ./_xtool/llcppsymg/internal/...

Full Test Suite

go test -v ./...

Some tests require LLGo tools installed via install.sh.

Demo Validation

bash .github/workflows/test_demo.sh

Pre-Commit Validation

ALWAYS run before committing:

go fmt ./...
go vet ./...
go test -timeout=10m ./...

After Modifying LLGo-Compiled Components

The following components are built with LLGo and installed via bash ./install.sh:

  • llcppsigfetch (_xtool/llcppsigfetch/) — parses C/C++ headers into JSON AST
  • llcppsymg (_xtool/llcppsymg/) — extracts symbols from C/C++ libraries

These tools share internal packages under _xtool/internal/ (e.g., parser, libclang, clangtool).

Tests such as TestFromTestdata (cl/internal/convert) invoke llcppsigfetch as a subprocess, so they depend on the installed binary being up to date.

When you modify any code under _xtool/ (including its internal dependencies), you MUST:

  1. Run bash ./install.sh to rebuild and reinstall the LLGo-compiled tools
  2. Run the unit tests first to verify the modified packages work correctly, and check that any test output changes are expected (e.g., llgo test ./_xtool/internal/parser, llgo test ./_xtool/internal/header)
  3. Run go test -v ./cl/internal/convert -run TestFromTestdata to verify the dependent tests pass
  4. If test output changes are expected, temporarily set gen:true in the test to regenerate expected output (gogensig.expect), verify it is correct, then set back to gen:false

Architecture and Design

For detailed technical specifications, see llcppg Design Documentation.

Type Mapping System

For complete details, see Type Mapping.

Name Conversion Rules

For complete details, see Name Mapping Rules.

Dependency System

For complete details, see Dependency.

File Generation Rules

For complete details, see File Generation Rules.

Common Issues and Solutions

Build Failures

"llgo: command not found"

  • LLGo not installed or not in PATH
  • Solution: Install LLGo with correct commit hash

"llcppsymg: executable file not found"

  • CRITICAL: MUST run bash ./install.sh
  • This is absolutely essential for testing

"BitReader.h: No such file or directory"

  • Install LLVM 19 development packages
  • Ensure LLVM 19 is in PATH

Test Failures

Tests requiring llcppsigfetch or llcppsymg

  • MUST install via bash ./install.sh
  • Do not skip this step

Demo tests failing

  • Verify library dependencies (libcjson-dev, etc.) are installed

Working with Examples

Study Real Examples

Look at _llcppgtest/ subdirectories for working configurations:

  • cjson/ - JSON library binding
  • sqlite/ - Database binding
  • lua/ - Scripting language binding
  • zlib/ - Compression library binding
  • libxml2/ - XML parsing with dependencies

Each contains:

  • llcppg.cfg - Configuration
  • Generated .go files
  • demo/ - Usage examples

Unit Test Verification for New Features

When adding a new feature to llcppg, follow this workflow to verify your changes:

  1. Create a test case in cl/internal/convert/_testdata/ with:

    • A conf/ directory containing llcppg.cfg and llcppg.symb.json
    • An hfile/ directory with your test header files
    • Configuration that exercises your new feature

  2. Generate the expected output using the testFrom function:

    • Temporarily set gen:true in the test call to generate gogensig.expect
    • Run the test: go test -v ./cl/internal/convert -run TestFromTestdata
    • This creates the expected output file that future test runs will compare against

  3. Verify the test passes with gen:false:

    • Change back to gen:false (or remove the gen parameter)
    • Run the test again to ensure it passes
    • The test compares generated output against gogensig.expect

  4. Do NOT commit the test case to the repository unless it's a permanent regression test

    • Use test cases for verification during development
    • Only add to _testdata/ if it should be part of the test suite

Example test structure:

cl/internal/convert/_testdata/yourfeature/
├── conf/
│   ├── llcppg.cfg
│   └── llcppg.symb.json
├── hfile/
│   └── test.h
└── gogensig.expect  (generated with gen:true)

Important Constraints

Version Requirements

For detailed version requirements and installation instructions, see README.md.

Header File Order

Header files in include must be in dependency order. If filter.h uses types from vli.h, then vli.h must appear first in the include array.

Code Style and Conventions

Configuration Files

  • Use JSON format for llcppg.cfg
  • Follow examples in _llcppgtest/ for structure
  • Comment complex configurations

Generated Code

  • Do not manually edit generated .go files
  • Regenerate bindings after config changes
  • Use typeMap and symMap for customization

Testing

  • Add test cases for new features
  • Run full test suite before PR
  • Validate with real library examples

CI/CD

The project uses GitHub Actions workflows:

  • .github/workflows/go.yml - Main test suite
  • .github/workflows/end2end.yml - End-to-end validation
  • .github/workflows/test_demo.sh - Demo validation script

These run automatically on PR and provide validation feedback.

Getting Help

  • Check README.md for comprehensive usage documentation
  • Review design documentation in doc/en/dev/
  • Study working examples in _llcppgtest/

Key Principles

  1. Always install tools first - Run bash ./install.sh before testing
  2. Follow dependency order - LLGo requires specific LLVM and commit versions
  3. Validate thoroughly - Run full test suite and demos
  4. Study examples - Real-world bindings in _llcppgtest/ are the best reference

This guide provides the foundation for working effectively with llcppg. For detailed technical specifications, always reference the design documentation in doc/en/dev/.