Skip to content

Commit 7955d98

Browse files
xgopilot[bot]xgopilotluoliwoshang
authored
docs: add CLAUDE.md AI assistant guide (#577)
* docs: add CLAUDE.md AI assistant guide Create comprehensive AI assistant guide for the llcppg project covering: - Project overview and core components - Development setup with prerequisites - Build and testing strategies - Usage workflow and validation - Architecture and design principles - Common issues and solutions - Working with examples Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot <noreply@goplus.org> * docs: address review comments on CLAUDE.md - Remove Timeout Settings section - Remove go build step from validation workflow - Remove copilot-instructions.md reference - Remove all timing information throughout document - Remove Parser tests failing section - Update parser directory description to clarify C AST parsing logic Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot <noreply@goplus.org> * docs: enhance CLAUDE.md with testing priorities and unit test workflow - Add note that LLGo version is a development version - Reorder testing strategy to prioritize unit tests before full test suite - Add comprehensive unit test verification workflow for new features - Document testFrom function usage with gen:true for generating expected output - Include example test case structure for _testdata directory Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot <noreply@goplus.org> * docs: add design documentation links to Architecture section - Add link to main llcppg design doc at section header - Add specific links to Type Mapping subsection - Add specific links to Name Conversion Rules subsection - Add specific links to Dependency System subsection - Add specific links to File Generation Rules subsection Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot <noreply@goplus.org> * docs: add README link to Getting Help section - Convert README.md reference to clickable link Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot <noreply@goplus.org> * docs: remove detailed mapping descriptions from Architecture section - Remove redundant detailed examples and code snippets - Keep section headers and links to design documentation - Design doc already contains all the detailed information - Makes CLAUDE.md more concise and reduces duplication Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot <noreply@goplus.org> * docs: remove Validation Workflow section from CLAUDE.md - Remove the Validation Workflow section - Keep only Unit Test Verification for New Features section - Simplifies documentation by focusing on unit testing workflow Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot <noreply@goplus.org> * docs: remove Usage Workflow section from CLAUDE.md - Remove entire Usage Workflow section - This section contained configuration and binding generation steps - Simplifies documentation to focus on essential information Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot <noreply@goplus.org> * docs: replace Development Setup details with README link Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: luoliwoshang <luoliwoshang@users.noreply.github.com> * docs: add README link to Version Requirements section Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: luoliwoshang <luoliwoshang@users.noreply.github.com> * docs: remove redundant version details from CLAUDE.md Removed duplicate version information (Go 1.23+, LLGo commit, LLVM 19) since it's already referenced via README.md link. Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: luoliwoshang <luoliwoshang@users.noreply.github.com> --------- Co-authored-by: xgopilot <noreply@goplus.org> Co-authored-by: luoliwoshang <luoliwoshang@users.noreply.github.com>
1 parent 1842693 commit 7955d98

File tree

1 file changed

+222
-0
lines changed

1 file changed

+222
-0
lines changed

‎CLAUDE.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
# llcppg Project AI Assistant Guide
2+
3+
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.
4+
5+
## Project Overview
6+
7+
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.
8+
9+
### Core Components
10+
11+
1. **llcppcfg** - Configuration file generator (Go)
12+
2. **llcppg** - Main binding generator (Go)
13+
3. **gogensig** - Go signature generator (Go)
14+
4. **llcppsymg** - Symbol generator (LLGo, requires LLGo compilation)
15+
5. **llcppsigfetch** - Signature fetcher (LLGo, requires LLGo compilation)
16+
17+
### Key Directories
18+
19+
- `cmd/` - Main executables (llcppg, llcppcfg, gogensig)
20+
- `_xtool/` - LLGo-compiled tools (llcppsymg, llcppsigfetch)
21+
- `cl/` - Core conversion logic and AST processing
22+
- `parser/` - C/C++ header file parsing interface. The core C AST to internal AST conversion logic is in `_xtool/internal/parser`, compiled with LLGo
23+
- `config/` - Configuration file handling
24+
- `_llcppgtest/` - Real-world binding examples (cjson, sqlite, lua, etc.)
25+
- `_demo/` - Simple demonstration projects
26+
- `_cmptest/` - Comparison and end-to-end tests
27+
28+
## Development Setup
29+
30+
For detailed setup instructions including prerequisites, dependencies, and installation steps, see [README.md](README.md).
31+
32+
## Building and Testing
33+
34+
### Build Commands
35+
36+
```bash
37+
go build -v ./...
38+
```
39+
40+
### Testing Strategy
41+
42+
#### Unit Tests (Priority)
43+
```bash
44+
go test -v ./config ./internal/name ./internal/arg ./internal/unmarshal
45+
```
46+
Always run these unit tests first for quick validation before running the full test suite.
47+
48+
#### LLGo-Dependent Tests
49+
```bash
50+
llgo test ./_xtool/internal/...
51+
llgo test ./_xtool/llcppsigfetch/internal/...
52+
llgo test ./_xtool/llcppsymg/internal/...
53+
```
54+
55+
#### Full Test Suite
56+
```bash
57+
go test -v ./...
58+
```
59+
Some tests require LLGo tools installed via `install.sh`.
60+
61+
#### Demo Validation
62+
```bash
63+
bash .github/workflows/test_demo.sh
64+
```
65+
66+
### Pre-Commit Validation
67+
68+
**ALWAYS** run before committing:
69+
70+
```bash
71+
go fmt ./...
72+
go vet ./...
73+
go test -timeout=10m ./...
74+
```
75+
76+
## Architecture and Design
77+
78+
For detailed technical specifications, see [llcppg Design Documentation](doc/en/dev/llcppg.md).
79+
80+
### Type Mapping System
81+
82+
For complete details, see [Type Mapping](doc/en/dev/llcppg.md#type-mapping).
83+
84+
### Name Conversion Rules
85+
86+
For complete details, see [Name Mapping Rules](doc/en/dev/llcppg.md#name-mapping-rules).
87+
88+
### Dependency System
89+
90+
For complete details, see [Dependency](doc/en/dev/llcppg.md#dependency).
91+
92+
### File Generation Rules
93+
94+
For complete details, see [File Generation Rules](doc/en/dev/llcppg.md#file-generation-rules).
95+
96+
## Common Issues and Solutions
97+
98+
### Build Failures
99+
100+
**"llgo: command not found"**
101+
- LLGo not installed or not in PATH
102+
- Solution: Install LLGo with correct commit hash
103+
104+
**"llcppsymg: executable file not found"**
105+
- **CRITICAL**: MUST run `bash ./install.sh`
106+
- This is absolutely essential for testing
107+
108+
**"BitReader.h: No such file or directory"**
109+
- Install LLVM 19 development packages
110+
- Ensure LLVM 19 is in PATH
111+
112+
### Test Failures
113+
114+
**Tests requiring llcppsigfetch or llcppsymg**
115+
- MUST install via `bash ./install.sh`
116+
- Do not skip this step
117+
118+
**Demo tests failing**
119+
- Verify library dependencies (libcjson-dev, etc.) are installed
120+
121+
## Working with Examples
122+
123+
### Study Real Examples
124+
125+
Look at `_llcppgtest/` subdirectories for working configurations:
126+
127+
- `cjson/` - JSON library binding
128+
- `sqlite/` - Database binding
129+
- `lua/` - Scripting language binding
130+
- `zlib/` - Compression library binding
131+
- `libxml2/` - XML parsing with dependencies
132+
133+
Each contains:
134+
- `llcppg.cfg` - Configuration
135+
- Generated `.go` files
136+
- `demo/` - Usage examples
137+
138+
### Unit Test Verification for New Features
139+
140+
When adding a new feature to llcppg, follow this workflow to verify your changes:
141+
142+
1. **Create a test case** in `cl/internal/convert/_testdata/` with:
143+
- A `conf/` directory containing `llcppg.cfg` and `llcppg.symb.json`
144+
- An `hfile/` directory with your test header files
145+
- Configuration that exercises your new feature
146+
147+
2. **Generate the expected output** using the `testFrom` function:
148+
- Temporarily set `gen:true` in the test call to generate `gogensig.expect`
149+
- Run the test: `go test -v ./cl/internal/convert -run TestFromTestdata`
150+
- This creates the expected output file that future test runs will compare against
151+
152+
3. **Verify the test passes** with `gen:false`:
153+
- Change back to `gen:false` (or remove the gen parameter)
154+
- Run the test again to ensure it passes
155+
- The test compares generated output against `gogensig.expect`
156+
157+
4. **Do NOT commit the test case** to the repository unless it's a permanent regression test
158+
- Use test cases for verification during development
159+
- Only add to `_testdata/` if it should be part of the test suite
160+
161+
**Example test structure:**
162+
```
163+
cl/internal/convert/_testdata/yourfeature/
164+
├── conf/
165+
│ ├── llcppg.cfg
166+
│ └── llcppg.symb.json
167+
├── hfile/
168+
│ └── test.h
169+
└── gogensig.expect (generated with gen:true)
170+
```
171+
172+
## Important Constraints
173+
174+
### Version Requirements
175+
176+
For detailed version requirements and installation instructions, see [README.md](README.md).
177+
178+
### Header File Order
179+
180+
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.
181+
182+
## Code Style and Conventions
183+
184+
### Configuration Files
185+
- Use JSON format for `llcppg.cfg`
186+
- Follow examples in `_llcppgtest/` for structure
187+
- Comment complex configurations
188+
189+
### Generated Code
190+
- Do not manually edit generated `.go` files
191+
- Regenerate bindings after config changes
192+
- Use `typeMap` and `symMap` for customization
193+
194+
### Testing
195+
- Add test cases for new features
196+
- Run full test suite before PR
197+
- Validate with real library examples
198+
199+
## CI/CD
200+
201+
The project uses GitHub Actions workflows:
202+
203+
- `.github/workflows/go.yml` - Main test suite
204+
- `.github/workflows/end2end.yml` - End-to-end validation
205+
- `.github/workflows/test_demo.sh` - Demo validation script
206+
207+
These run automatically on PR and provide validation feedback.
208+
209+
## Getting Help
210+
211+
- Check [README.md](README.md) for comprehensive usage documentation
212+
- Review design documentation in `doc/en/dev/`
213+
- Study working examples in `_llcppgtest/`
214+
215+
## Key Principles
216+
217+
1. **Always install tools first** - Run `bash ./install.sh` before testing
218+
2. **Follow dependency order** - LLGo requires specific LLVM and commit versions
219+
3. **Validate thoroughly** - Run full test suite and demos
220+
4. **Study examples** - Real-world bindings in `_llcppgtest/` are the best reference
221+
222+
This guide provides the foundation for working effectively with llcppg. For detailed technical specifications, always reference the design documentation in `doc/en/dev/`.

0 commit comments

Comments
 (0)