Skip to content

AGENTS.md

Latest commit

 

History

History
73 lines (53 loc) · 2.9 KB

AGENTS.md

File metadata and controls

73 lines (53 loc) · 2.9 KB
Raw

AGENTS.md

Guidance for AI coding agents and new contributors working in the llcppg repository.

Project overview

llcppg (LLGo autogen tool) automatically generates LLGo bindings for C/C++ libraries, enhancing the experience of integrating LLGo with C/C++. It parses C/C++ headers via libclang and emits Go source that maps the library's public API onto LLGo.

  • Module: github.com/goplus/llcppg
  • Language: Go
  • Build/test toolchain: LLGo with LLVM/Clang (llcppg depends on libclang and is compiled/tested with llgo, not plain go).

Repository layout

Path Description
cl/ Core compiler: loads clang translation units and generates the Go package.
cl/_testc/, cl/_testcpp/, cl/_testpp/ Fixture inputs (C, C++, and package tests) consumed by cl tests. Directories are _-prefixed so the Go toolchain ignores them as packages.
clang/ Higher-level clang helpers.
lib/clang/ Low-level libclang bindings generated by llcppg.
cmd/llcppg/ Main llcppg command-line entry point.
.github/ CI workflow (workflows/llgo.yml) and the setup-llgo composite action.

Build and test

Reproduce the toolchain locally

Refer to the GitHub Action to download and build llgo (see .github/actions/setup-llgo).

Run the tests

Once llgo is installed and on PATH, run the same command as CI:

llgo test -v ./...

Only the cl package has tests; it drives every fixture under cl/_testc (C, via TestC), cl/_testcpp (C++, via TestCpp), and cl/_testpp (TestPreprocessor). To iterate on one fixture, filter by name:

llgo test -v -run 'TestC/union_struct' ./cl/

Fixtures and golden files

Each fixture directory has an input header (in.h) and a golden out.go. The cl test harness (cl/compile_test.go) parses in.h with libclang, generates Go, and diffs it against out.go. When adding or changing a fixture:

  1. Implement the generator change, then run the fixture test.
  2. When the generated Go differs from the golden (including a missing or stale out.go), the harness writes the actual output to out.go.txt (gitignored via the *.txt rule) and fails the test — it does not silently accept a mismatch. Do not hand-write or hand-edit out.go; always let the harness produce it so the golden matches the generator byte-for-byte.
  3. Inspect out.go.txt, and once correct promote it: mv out.go.txt out.go.
  4. Re-run until the fixture passes with no out.go.txt produced.

Make the tests pass before submitting a change.

Issue title convention

  • Format: feat(pkg): xxx, fix(pkg): xxx, or Proposal: xxx.
  • pkg is the package(s) affected by the issue. Multiple packages are separated by ,, e.g. fix(cl,parser): xxx.
  • Proposal: xxx issues usually affect the cl package, so they are equivalent to feat(cl): xxx.