diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..79f1970f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,222 @@ +# 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](README.md). + +## Building and Testing + +### Build Commands + +```bash +go build -v ./... +``` + +### Testing Strategy + +#### Unit Tests (Priority) +```bash +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 +```bash +llgo test ./_xtool/internal/... +llgo test ./_xtool/llcppsigfetch/internal/... +llgo test ./_xtool/llcppsymg/internal/... +``` + +#### Full Test Suite +```bash +go test -v ./... +``` +Some tests require LLGo tools installed via `install.sh`. + +#### Demo Validation +```bash +bash .github/workflows/test_demo.sh +``` + +### Pre-Commit Validation + +**ALWAYS** run before committing: + +```bash +go fmt ./... +go vet ./... +go test -timeout=10m ./... +``` + +## Architecture and Design + +For detailed technical specifications, see [llcppg Design Documentation](doc/en/dev/llcppg.md). + +### Type Mapping System + +For complete details, see [Type Mapping](doc/en/dev/llcppg.md#type-mapping). + +### Name Conversion Rules + +For complete details, see [Name Mapping Rules](doc/en/dev/llcppg.md#name-mapping-rules). + +### Dependency System + +For complete details, see [Dependency](doc/en/dev/llcppg.md#dependency). + +### File Generation Rules + +For complete details, see [File Generation Rules](doc/en/dev/llcppg.md#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](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](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/`.