From 37711e88fa6585b0ae44f8999d336fbe1a200af3 Mon Sep 17 00:00:00 2001
From: xgopilot <noreply@goplus.org>
Date: Mon, 13 Oct 2025 03:50:12 +0000
Subject: [PATCH 01/11] 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>
---
 CLAUDE.md | 375 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 375 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..40705e5d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,375 @@
+# 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
+- `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
+
+### Prerequisites
+
+llcppg has strict dependencies that MUST be installed in the correct order:
+
+1. **LLVM 19** - Exactly version 19 (not compatible with other versions)
+   ```bash
+   # Ubuntu/Linux
+   sudo apt-get install -y llvm-19-dev clang-19 libclang-19-dev lld-19 libunwind-19-dev libc++-19-dev
+   export PATH="/usr/lib/llvm-19/bin:$PATH"
+   
+   # macOS
+   brew install llvm@19 lld@19
+   echo "$(brew --prefix llvm@19)/bin" >> $GITHUB_PATH
+   ```
+
+2. **System Dependencies**
+   ```bash
+   # Ubuntu/Linux
+   sudo apt-get install -y pkg-config libgc-dev libssl-dev zlib1g-dev libffi-dev libuv1-dev libcjson-dev
+   
+   # macOS
+   brew install bdw-gc openssl libffi libuv zlib cjson
+   ```
+
+3. **LLGo** - CRITICAL dependency, specific commit required
+   ```bash
+   git clone https://github.com/goplus/llgo.git .llgo
+   cd .llgo
+   git checkout f0728c4fe028fbc72455c1242cef638ebdf60454
+   go install -v ./cmd/llgo/...
+   export LLGO_ROOT=$(pwd)
+   cd ..
+   ```
+
+### Installation
+
+**CRITICAL**: Always run the installation script to build all tools:
+
+```bash
+bash ./install.sh
+```
+
+**NEVER CANCEL**: This takes 2-3 minutes including LLGo compilation. Set timeouts to 10+ minutes.
+
+This script installs all five core tools. Without it, tests will fail.
+
+## Building and Testing
+
+### Build Commands
+
+```bash
+go build -v ./...
+```
+
+Timing: ~15 seconds. Build always succeeds without LLGo dependencies.
+
+### Testing Strategy
+
+#### Quick Tests (Standard Go)
+```bash
+go test -v ./config ./internal/name ./internal/arg ./internal/unmarshal
+```
+Timing: ~2 seconds. Always run these first for quick validation.
+
+#### Full Test Suite
+```bash
+go test -v ./...
+```
+Timing: 8-12 minutes. Some tests require LLGo tools installed via `install.sh`.
+
+#### LLGo-Dependent Tests
+```bash
+llgo test ./_xtool/internal/...
+llgo test ./_xtool/llcppsigfetch/internal/...
+llgo test ./_xtool/llcppsymg/internal/...
+```
+**NEVER CANCEL**: Takes 3-5 minutes. Set timeout to 10+ minutes.
+
+#### Demo Validation
+```bash
+bash .github/workflows/test_demo.sh
+```
+**NEVER CANCEL**: Takes 5-10 minutes. Set timeout to 15+ minutes.
+
+### Pre-Commit Validation
+
+**ALWAYS** run before committing:
+
+```bash
+go fmt ./...
+go vet ./...
+go test -timeout=10m ./...
+```
+
+Timing: 8-12 minutes total. **NEVER CANCEL** - set timeout to 20+ minutes.
+
+## Usage Workflow
+
+### 1. Generate Configuration
+
+```bash
+llcppcfg [options] libname
+```
+
+Examples:
+- `llcppcfg cjson` - Basic configuration
+- `llcppcfg -cpp libname` - For C++ libraries
+- `llcppcfg -deps "c/os,github.com/author/llpkg" libname` - With dependencies
+
+Timing: Instant (< 1 second).
+
+### 2. Edit Configuration
+
+Edit the generated `llcppg.cfg` to specify:
+- `include`: Header files to process
+- `cflags`: Compiler flags
+- `libs`: Library flags
+- `trimPrefixes`: Prefixes to remove from names
+- `deps`: Dependencies on other packages
+- `typeMap`: Custom type name mappings
+- `symMap`: Custom function name mappings
+
+### 3. Generate Bindings
+
+```bash
+llcppg [config-file]
+```
+
+**NEVER CANCEL**: Takes 30 seconds to 5 minutes. Set timeout to 10+ minutes.
+
+### 4. Validate Output
+
+Check the generated Go package:
+- Type definitions match C structures
+- Functions are correctly mapped
+- Dependencies are properly imported
+
+## Architecture and Design
+
+### Type Mapping System
+
+llcppg converts C/C++ types to Go types following strict rules:
+
+#### Basic Types
+- `int` → `c.Int`
+- `unsigned int` → `c.Uint`
+- `char` → `c.Char`
+- `void*` → `c.Pointer`
+- `float` → `c.Float`
+- `double` → `c.Double`
+
+All basic types are imported from `github.com/goplus/lib/c`.
+
+#### Function Pointers
+C function pointers become Go function types with `llgo:type C` tag:
+
+```c
+typedef int (*CallBack)(void *L);
+```
+
+Becomes:
+
+```go
+// llgo:type C
+type CallBack func(c.Pointer) c.Int
+```
+
+#### Method Generation
+
+When a C function's first parameter matches a converted type, it becomes a Go method:
+
+```c
+int sqlite3_close(sqlite3*);
+```
+
+Becomes:
+
+```go
+// llgo:link (*Sqlite3).Close C.sqlite3_close
+func (recv_ *Sqlite3) Close() c.Int {
+    return 0
+}
+```
+
+### Name Conversion Rules
+
+1. **Type Names**: Convert to PascalCase after removing configured prefixes
+   - `cJSON_Hooks` → `CJSONHooks` (or `Hooks` with `trimPrefixes: ["cJSON_"]`)
+   - `sqlite3_destructor_type` → `Sqlite3DestructorType`
+
+2. **Field Names**: Convert to PascalCase for export
+   - `value_string` → `Valuestring`
+
+3. **Parameters**: Preserve original case, add `_` suffix for Go keywords
+   - `func` → `func_`
+   - Variadic params always named `__llgo_va_list`
+
+### Dependency System
+
+llcppg handles cross-package dependencies through:
+
+1. **llcppg.pub** - Type mapping table (C type → Go type name)
+2. **deps field** - List of dependency packages in `llcppg.cfg`
+3. **Special aliases** - `c/` prefix maps to `github.com/goplus/lib/c/`
+
+Example: `c/os` → `github.com/goplus/lib/c/os`
+
+### File Generation Rules
+
+- **Interface headers** (in `include`): Each generates a `.go` file
+- **Implementation headers** (same directory): Content goes in `{name}_autogen.go`
+- **Link file**: `{name}_autogen_link.go` contains linking info
+- **Type mapping**: `llcppg.pub` for dependency resolution
+
+## 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
+
+**Parser tests failing**
+- Install llclang: `llgo install ./_xtool/llclang`
+
+**Demo tests failing**
+- Verify library dependencies (libcjson-dev, etc.) are installed
+
+### Performance Expectations
+
+- Build time: 15 seconds (Go only), 2-3 minutes (with install.sh)
+- Test time: 2 seconds (basic), 8-15 minutes (full suite)
+- Demo time: 5-10 minutes
+- Memory usage: 2-4GB during LLVM compilation
+
+## 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
+
+### Validation Workflow
+
+After making changes, ALWAYS:
+
+1. Build: `go build -v ./...`
+2. Install tools: `bash ./install.sh` (**ESSENTIAL**)
+3. Generate test config: `llcppcfg sqlite`
+4. Edit config to add proper headers
+5. Run binding generation: `llcppg llcppg.cfg`
+6. Verify Go files are generated
+7. Test with example from `_demo/` or `_llcppgtest/`
+
+## Important Constraints
+
+### Version Requirements
+- Go 1.23+
+- LLGo commit: `f0728c4fe028fbc72455c1242cef638ebdf60454`
+- LLVM 19 (exact version)
+
+**NEVER** use different versions without updating the entire toolchain.
+
+### Timeout Settings
+
+Many operations are CPU-intensive. Set appropriate timeouts:
+
+- `install.sh`: 10+ minutes
+- Full tests: 20+ minutes
+- Demo tests: 15+ minutes
+- Binding generation: 10+ minutes
+
+**NEVER CANCEL** long-running operations - they will complete successfully with proper timeout settings.
+
+### 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 (8-15 minutes)
+- `.github/workflows/end2end.yml` - End-to-end validation (15-30 minutes)
+- `.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/`
+- Reference `.github/copilot-instructions.md` for detailed build instructions
+
+## Key Principles
+
+1. **Always install tools first** - Run `bash ./install.sh` before testing
+2. **Set generous timeouts** - LLGo compilation takes time
+3. **Follow dependency order** - LLGo requires specific LLVM and commit versions
+4. **Validate thoroughly** - Run full test suite and demos
+5. **Study examples** - Real-world bindings in `_llcppgtest/` are the best reference
+6. **Never cancel long operations** - They complete successfully with proper timeouts
+
+This guide provides the foundation for working effectively with llcppg. For detailed technical specifications, always reference the design documentation in `doc/en/dev/`.

From 672187f588bd157e79d84da18dce0c94921f88cc Mon Sep 17 00:00:00 2001
From: xgopilot <noreply@goplus.org>
Date: Mon, 13 Oct 2025 04:10:01 +0000
Subject: [PATCH 02/11] 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>
---
 CLAUDE.md | 65 ++++++++++++-------------------------------------------
 1 file changed, 14 insertions(+), 51 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 40705e5d..6bde458a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -19,7 +19,7 @@ llcppg is a binding generator that bridges C/C++ libraries to LLGo (a Go-based c
 - `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
+- `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
@@ -69,8 +69,6 @@ llcppg has strict dependencies that MUST be installed in the correct order:
 bash ./install.sh
 ```
 
-**NEVER CANCEL**: This takes 2-3 minutes including LLGo compilation. Set timeouts to 10+ minutes.
-
 This script installs all five core tools. Without it, tests will fail.
 
 ## Building and Testing
@@ -81,21 +79,19 @@ This script installs all five core tools. Without it, tests will fail.
 go build -v ./...
 ```
 
-Timing: ~15 seconds. Build always succeeds without LLGo dependencies.
-
 ### Testing Strategy
 
 #### Quick Tests (Standard Go)
 ```bash
 go test -v ./config ./internal/name ./internal/arg ./internal/unmarshal
 ```
-Timing: ~2 seconds. Always run these first for quick validation.
+Always run these first for quick validation.
 
 #### Full Test Suite
 ```bash
 go test -v ./...
 ```
-Timing: 8-12 minutes. Some tests require LLGo tools installed via `install.sh`.
+Some tests require LLGo tools installed via `install.sh`.
 
 #### LLGo-Dependent Tests
 ```bash
@@ -103,13 +99,11 @@ llgo test ./_xtool/internal/...
 llgo test ./_xtool/llcppsigfetch/internal/...
 llgo test ./_xtool/llcppsymg/internal/...
 ```
-**NEVER CANCEL**: Takes 3-5 minutes. Set timeout to 10+ minutes.
 
 #### Demo Validation
 ```bash
 bash .github/workflows/test_demo.sh
 ```
-**NEVER CANCEL**: Takes 5-10 minutes. Set timeout to 15+ minutes.
 
 ### Pre-Commit Validation
 
@@ -121,8 +115,6 @@ go vet ./...
 go test -timeout=10m ./...
 ```
 
-Timing: 8-12 minutes total. **NEVER CANCEL** - set timeout to 20+ minutes.
-
 ## Usage Workflow
 
 ### 1. Generate Configuration
@@ -136,8 +128,6 @@ Examples:
 - `llcppcfg -cpp libname` - For C++ libraries
 - `llcppcfg -deps "c/os,github.com/author/llpkg" libname` - With dependencies
 
-Timing: Instant (< 1 second).
-
 ### 2. Edit Configuration
 
 Edit the generated `llcppg.cfg` to specify:
@@ -155,8 +145,6 @@ Edit the generated `llcppg.cfg` to specify:
 llcppg [config-file]
 ```
 
-**NEVER CANCEL**: Takes 30 seconds to 5 minutes. Set timeout to 10+ minutes.
-
 ### 4. Validate Output
 
 Check the generated Go package:
@@ -263,19 +251,9 @@ Example: `c/os` → `github.com/goplus/lib/c/os`
 - MUST install via `bash ./install.sh`
 - Do not skip this step
 
-**Parser tests failing**
-- Install llclang: `llgo install ./_xtool/llclang`
-
 **Demo tests failing**
 - Verify library dependencies (libcjson-dev, etc.) are installed
 
-### Performance Expectations
-
-- Build time: 15 seconds (Go only), 2-3 minutes (with install.sh)
-- Test time: 2 seconds (basic), 8-15 minutes (full suite)
-- Demo time: 5-10 minutes
-- Memory usage: 2-4GB during LLVM compilation
-
 ## Working with Examples
 
 ### Study Real Examples
@@ -297,13 +275,12 @@ Each contains:
 
 After making changes, ALWAYS:
 
-1. Build: `go build -v ./...`
-2. Install tools: `bash ./install.sh` (**ESSENTIAL**)
-3. Generate test config: `llcppcfg sqlite`
-4. Edit config to add proper headers
-5. Run binding generation: `llcppg llcppg.cfg`
-6. Verify Go files are generated
-7. Test with example from `_demo/` or `_llcppgtest/`
+1. Install tools: `bash ./install.sh` (**ESSENTIAL**)
+2. Generate test config: `llcppcfg sqlite`
+3. Edit config to add proper headers
+4. Run binding generation: `llcppg llcppg.cfg`
+5. Verify Go files are generated
+6. Test with example from `_demo/` or `_llcppgtest/`
 
 ## Important Constraints
 
@@ -314,17 +291,6 @@ After making changes, ALWAYS:
 
 **NEVER** use different versions without updating the entire toolchain.
 
-### Timeout Settings
-
-Many operations are CPU-intensive. Set appropriate timeouts:
-
-- `install.sh`: 10+ minutes
-- Full tests: 20+ minutes
-- Demo tests: 15+ minutes
-- Binding generation: 10+ minutes
-
-**NEVER CANCEL** long-running operations - they will complete successfully with proper timeout settings.
-
 ### 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.
@@ -350,8 +316,8 @@ Header files in `include` must be in dependency order. If `filter.h` uses types
 
 The project uses GitHub Actions workflows:
 
-- `.github/workflows/go.yml` - Main test suite (8-15 minutes)
-- `.github/workflows/end2end.yml` - End-to-end validation (15-30 minutes)
+- `.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.
@@ -361,15 +327,12 @@ These run automatically on PR and provide validation feedback.
 - Check `README.md` for comprehensive usage documentation
 - Review design documentation in `doc/en/dev/`
 - Study working examples in `_llcppgtest/`
-- Reference `.github/copilot-instructions.md` for detailed build instructions
 
 ## Key Principles
 
 1. **Always install tools first** - Run `bash ./install.sh` before testing
-2. **Set generous timeouts** - LLGo compilation takes time
-3. **Follow dependency order** - LLGo requires specific LLVM and commit versions
-4. **Validate thoroughly** - Run full test suite and demos
-5. **Study examples** - Real-world bindings in `_llcppgtest/` are the best reference
-6. **Never cancel long operations** - They complete successfully with proper timeouts
+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/`.

From a8d0c0b935c9a367e8b27915709f275f1497a82f Mon Sep 17 00:00:00 2001
From: xgopilot <noreply@goplus.org>
Date: Mon, 13 Oct 2025 06:33:47 +0000
Subject: [PATCH 03/11] 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>
---
 CLAUDE.md | 52 ++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 44 insertions(+), 8 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 6bde458a..bdbd07ff 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -60,6 +60,8 @@ llcppg has strict dependencies that MUST be installed in the correct order:
    export LLGO_ROOT=$(pwd)
    cd ..
    ```
+   
+   **Note**: This LLGo version is a development version. The specific commit is required for compatibility.
 
 ### Installation
 
@@ -81,17 +83,11 @@ go build -v ./...
 
 ### Testing Strategy
 
-#### Quick Tests (Standard Go)
+#### Unit Tests (Priority)
 ```bash
 go test -v ./config ./internal/name ./internal/arg ./internal/unmarshal
 ```
-Always run these first for quick validation.
-
-#### Full Test Suite
-```bash
-go test -v ./...
-```
-Some tests require LLGo tools installed via `install.sh`.
+Always run these unit tests first for quick validation before running the full test suite.
 
 #### LLGo-Dependent Tests
 ```bash
@@ -100,6 +96,12 @@ 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
@@ -282,6 +284,40 @@ After making changes, ALWAYS:
 5. Verify Go files are generated
 6. Test with example from `_demo/` or `_llcppgtest/`
 
+### 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

From 63081e98c64d1548f8983c57d8489a8143408342 Mon Sep 17 00:00:00 2001
From: xgopilot <noreply@goplus.org>
Date: Mon, 13 Oct 2025 06:48:36 +0000
Subject: [PATCH 04/11] 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>
---
 CLAUDE.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index bdbd07ff..ec7ea34f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -156,9 +156,11 @@ Check the generated Go package:
 
 ## Architecture and Design
 
+For detailed technical specifications, see [llcppg Design Documentation](doc/en/dev/llcppg.md).
+
 ### Type Mapping System
 
-llcppg converts C/C++ types to Go types following strict rules:
+llcppg converts C/C++ types to Go types following strict rules. For complete details, see [Type Mapping](doc/en/dev/llcppg.md#type-mapping).
 
 #### Basic Types
 - `int` → `c.Int`
@@ -203,6 +205,8 @@ func (recv_ *Sqlite3) Close() c.Int {
 
 ### Name Conversion Rules
 
+For complete details, see [Name Mapping Rules](doc/en/dev/llcppg.md#name-mapping-rules).
+
 1. **Type Names**: Convert to PascalCase after removing configured prefixes
    - `cJSON_Hooks` → `CJSONHooks` (or `Hooks` with `trimPrefixes: ["cJSON_"]`)
    - `sqlite3_destructor_type` → `Sqlite3DestructorType`
@@ -216,6 +220,8 @@ func (recv_ *Sqlite3) Close() c.Int {
 
 ### Dependency System
 
+For complete details, see [Dependency](doc/en/dev/llcppg.md#dependency).
+
 llcppg handles cross-package dependencies through:
 
 1. **llcppg.pub** - Type mapping table (C type → Go type name)
@@ -226,6 +232,8 @@ Example: `c/os` → `github.com/goplus/lib/c/os`
 
 ### File Generation Rules
 
+For complete details, see [File Generation Rules](doc/en/dev/llcppg.md#file-generation-rules).
+
 - **Interface headers** (in `include`): Each generates a `.go` file
 - **Implementation headers** (same directory): Content goes in `{name}_autogen.go`
 - **Link file**: `{name}_autogen_link.go` contains linking info

From 6bafb21cbc4e8bb1fc25ebc2e6e017795b269837 Mon Sep 17 00:00:00 2001
From: xgopilot <noreply@goplus.org>
Date: Mon, 13 Oct 2025 06:54:27 +0000
Subject: [PATCH 05/11] 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>
---
 CLAUDE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index ec7ea34f..3a1e9fe1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -368,7 +368,7 @@ These run automatically on PR and provide validation feedback.
 
 ## Getting Help
 
-- Check `README.md` for comprehensive usage documentation
+- Check [README.md](README.md) for comprehensive usage documentation
 - Review design documentation in `doc/en/dev/`
 - Study working examples in `_llcppgtest/`
 

From 8ac23e273c6604e7a702f60eb73a7a253b2323db Mon Sep 17 00:00:00 2001
From: xgopilot <noreply@goplus.org>
Date: Mon, 13 Oct 2025 07:20:30 +0000
Subject: [PATCH 06/11] 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>
---
 CLAUDE.md | 67 +------------------------------------------------------
 1 file changed, 1 insertion(+), 66 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 3a1e9fe1..fa1e7820 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -160,85 +160,20 @@ For detailed technical specifications, see [llcppg Design Documentation](doc/en/
 
 ### Type Mapping System
 
-llcppg converts C/C++ types to Go types following strict rules. For complete details, see [Type Mapping](doc/en/dev/llcppg.md#type-mapping).
-
-#### Basic Types
-- `int` → `c.Int`
-- `unsigned int` → `c.Uint`
-- `char` → `c.Char`
-- `void*` → `c.Pointer`
-- `float` → `c.Float`
-- `double` → `c.Double`
-
-All basic types are imported from `github.com/goplus/lib/c`.
-
-#### Function Pointers
-C function pointers become Go function types with `llgo:type C` tag:
-
-```c
-typedef int (*CallBack)(void *L);
-```
-
-Becomes:
-
-```go
-// llgo:type C
-type CallBack func(c.Pointer) c.Int
-```
-
-#### Method Generation
-
-When a C function's first parameter matches a converted type, it becomes a Go method:
-
-```c
-int sqlite3_close(sqlite3*);
-```
-
-Becomes:
-
-```go
-// llgo:link (*Sqlite3).Close C.sqlite3_close
-func (recv_ *Sqlite3) Close() c.Int {
-    return 0
-}
-```
+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).
 
-1. **Type Names**: Convert to PascalCase after removing configured prefixes
-   - `cJSON_Hooks` → `CJSONHooks` (or `Hooks` with `trimPrefixes: ["cJSON_"]`)
-   - `sqlite3_destructor_type` → `Sqlite3DestructorType`
-
-2. **Field Names**: Convert to PascalCase for export
-   - `value_string` → `Valuestring`
-
-3. **Parameters**: Preserve original case, add `_` suffix for Go keywords
-   - `func` → `func_`
-   - Variadic params always named `__llgo_va_list`
-
 ### Dependency System
 
 For complete details, see [Dependency](doc/en/dev/llcppg.md#dependency).
 
-llcppg handles cross-package dependencies through:
-
-1. **llcppg.pub** - Type mapping table (C type → Go type name)
-2. **deps field** - List of dependency packages in `llcppg.cfg`
-3. **Special aliases** - `c/` prefix maps to `github.com/goplus/lib/c/`
-
-Example: `c/os` → `github.com/goplus/lib/c/os`
-
 ### File Generation Rules
 
 For complete details, see [File Generation Rules](doc/en/dev/llcppg.md#file-generation-rules).
 
-- **Interface headers** (in `include`): Each generates a `.go` file
-- **Implementation headers** (same directory): Content goes in `{name}_autogen.go`
-- **Link file**: `{name}_autogen_link.go` contains linking info
-- **Type mapping**: `llcppg.pub` for dependency resolution
-
 ## Common Issues and Solutions
 
 ### Build Failures

From 0181c31f0a95f454a24ecbaab05101d8e7d15d06 Mon Sep 17 00:00:00 2001
From: xgopilot <noreply@goplus.org>
Date: Mon, 13 Oct 2025 07:55:40 +0000
Subject: [PATCH 07/11] 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>
---
 CLAUDE.md | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index fa1e7820..661ea586 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -216,17 +216,6 @@ Each contains:
 - Generated `.go` files
 - `demo/` - Usage examples
 
-### Validation Workflow
-
-After making changes, ALWAYS:
-
-1. Install tools: `bash ./install.sh` (**ESSENTIAL**)
-2. Generate test config: `llcppcfg sqlite`
-3. Edit config to add proper headers
-4. Run binding generation: `llcppg llcppg.cfg`
-5. Verify Go files are generated
-6. Test with example from `_demo/` or `_llcppgtest/`
-
 ### Unit Test Verification for New Features
 
 When adding a new feature to llcppg, follow this workflow to verify your changes:

From daf2f6eac19ed88c0e53df5d029fa3dd63ad4888 Mon Sep 17 00:00:00 2001
From: xgopilot <noreply@goplus.org>
Date: Mon, 13 Oct 2025 08:16:25 +0000
Subject: [PATCH 08/11] 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>
---
 CLAUDE.md | 37 -------------------------------------
 1 file changed, 37 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 661ea586..e581f73d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -117,43 +117,6 @@ go vet ./...
 go test -timeout=10m ./...
 ```
 
-## Usage Workflow
-
-### 1. Generate Configuration
-
-```bash
-llcppcfg [options] libname
-```
-
-Examples:
-- `llcppcfg cjson` - Basic configuration
-- `llcppcfg -cpp libname` - For C++ libraries
-- `llcppcfg -deps "c/os,github.com/author/llpkg" libname` - With dependencies
-
-### 2. Edit Configuration
-
-Edit the generated `llcppg.cfg` to specify:
-- `include`: Header files to process
-- `cflags`: Compiler flags
-- `libs`: Library flags
-- `trimPrefixes`: Prefixes to remove from names
-- `deps`: Dependencies on other packages
-- `typeMap`: Custom type name mappings
-- `symMap`: Custom function name mappings
-
-### 3. Generate Bindings
-
-```bash
-llcppg [config-file]
-```
-
-### 4. Validate Output
-
-Check the generated Go package:
-- Type definitions match C structures
-- Functions are correctly mapped
-- Dependencies are properly imported
-
 ## Architecture and Design
 
 For detailed technical specifications, see [llcppg Design Documentation](doc/en/dev/llcppg.md).

From 582cad10ddbaba5af32425841d60b250d637cd84 Mon Sep 17 00:00:00 2001
From: xgopilot <noreply@goplus.org>
Date: Wed, 15 Oct 2025 03:49:51 +0000
Subject: [PATCH 09/11] 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>
---
 CLAUDE.md | 46 +---------------------------------------------
 1 file changed, 1 insertion(+), 45 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index e581f73d..7989aab9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -27,51 +27,7 @@ llcppg is a binding generator that bridges C/C++ libraries to LLGo (a Go-based c
 
 ## Development Setup
 
-### Prerequisites
-
-llcppg has strict dependencies that MUST be installed in the correct order:
-
-1. **LLVM 19** - Exactly version 19 (not compatible with other versions)
-   ```bash
-   # Ubuntu/Linux
-   sudo apt-get install -y llvm-19-dev clang-19 libclang-19-dev lld-19 libunwind-19-dev libc++-19-dev
-   export PATH="/usr/lib/llvm-19/bin:$PATH"
-   
-   # macOS
-   brew install llvm@19 lld@19
-   echo "$(brew --prefix llvm@19)/bin" >> $GITHUB_PATH
-   ```
-
-2. **System Dependencies**
-   ```bash
-   # Ubuntu/Linux
-   sudo apt-get install -y pkg-config libgc-dev libssl-dev zlib1g-dev libffi-dev libuv1-dev libcjson-dev
-   
-   # macOS
-   brew install bdw-gc openssl libffi libuv zlib cjson
-   ```
-
-3. **LLGo** - CRITICAL dependency, specific commit required
-   ```bash
-   git clone https://github.com/goplus/llgo.git .llgo
-   cd .llgo
-   git checkout f0728c4fe028fbc72455c1242cef638ebdf60454
-   go install -v ./cmd/llgo/...
-   export LLGO_ROOT=$(pwd)
-   cd ..
-   ```
-   
-   **Note**: This LLGo version is a development version. The specific commit is required for compatibility.
-
-### Installation
-
-**CRITICAL**: Always run the installation script to build all tools:
-
-```bash
-bash ./install.sh
-```
-
-This script installs all five core tools. Without it, tests will fail.
+For detailed setup instructions including prerequisites, dependencies, and installation steps, see [README.md](README.md).
 
 ## Building and Testing
 

From b893bdc1eb36afc6d71d3f214746050d99aa44ff Mon Sep 17 00:00:00 2001
From: xgopilot <noreply@goplus.org>
Date: Fri, 17 Oct 2025 02:14:43 +0000
Subject: [PATCH 10/11] 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>
---
 CLAUDE.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 7989aab9..cdf6a7b3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -172,6 +172,9 @@ cl/internal/convert/_testdata/yourfeature/
 ## Important Constraints
 
 ### Version Requirements
+
+For detailed version requirements and installation instructions, see [README.md](README.md).
+
 - Go 1.23+
 - LLGo commit: `f0728c4fe028fbc72455c1242cef638ebdf60454`
 - LLVM 19 (exact version)

From 4a00bc4ba92836452c82c2021aafc3f7bec87016 Mon Sep 17 00:00:00 2001
From: xgopilot <noreply@goplus.org>
Date: Fri, 17 Oct 2025 02:30:11 +0000
Subject: [PATCH 11/11] 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>
---
 CLAUDE.md | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index cdf6a7b3..79f1970f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -175,12 +175,6 @@ cl/internal/convert/_testdata/yourfeature/
 
 For detailed version requirements and installation instructions, see [README.md](README.md).
 
-- Go 1.23+
-- LLGo commit: `f0728c4fe028fbc72455c1242cef638ebdf60454`
-- LLVM 19 (exact version)
-
-**NEVER** use different versions without updating the entire toolchain.
-
 ### 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.