docs: add CLAUDE.md AI assistant guide #577

xgopilot · 2025-10-13T03:50:57Z

Summary

This PR adds a comprehensive CLAUDE.md file to guide AI assistants working with the llcppg project.

Changes

Created CLAUDE.md with detailed project documentation including:
- Project overview and architecture
- Development setup and prerequisites
- Build and testing strategies
- Usage workflow and validation steps
- Type mapping and design principles
- Common issues and troubleshooting
- Working with examples

Context

Addresses #576 - Request to create an AI assistant guide based on:

Project code understanding
.github/copilot-instructions.md rules
Design documentation in doc/en/dev/

The guide provides AI assistants with comprehensive context to effectively work with llcppg's unique requirements (LLGo dependencies, LLVM 19, timeout settings, etc.).

Testing

File created successfully
Content covers all key aspects of the project
Follows conventions from copilot-instructions.md
Includes references to design documentation

Generated with codeagent

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 <[email protected]>

codecov · 2025-10-13T03:56:10Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.19%. Comparing base (ca87182) to head (582cad1).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #577   +/-   ##
=======================================
  Coverage   84.19%   84.19%           
=======================================
  Files          27       27           
  Lines        2746     2746           
=======================================
  Hits         2312     2312           
  Misses        391      391           
  Partials       43       43

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

luoliwoshang

@xgopilot resolve these comments

CLAUDE.md

luoliwoshang · 2025-10-13T03:59:08Z

CLAUDE.md

+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


luoliwoshang · 2025-10-13T04:00:20Z

CLAUDE.md

+**Parser tests failing**
+- Install llclang: `llgo install ./_xtool/llclang`


error info remove it !

CLAUDE.md

xgopilot · 2025-10-13T04:07:04Z

✅ All Review Comments Resolved

Successfully addressed all 8 review comments from @luoliwoshang:

Changes Made:

✅ Removed "Timeout Settings" section (lines 317-326)
✅ Removed go build -v ./... from validation workflow (line 300)
✅ Removed .github/copilot-instructions.md reference (line 364)
✅ Removed timeout reference from Key Principles (line 369)
✅ Removed timeout reference from Key Principles (line 373)
✅ Removed "Parser tests failing" error info section (lines 266-267)
✅ Removed all timing fields throughout the document
✅ Updated parser directory description (line 22) to clarify C AST to internal AST conversion logic in _xtool/internal/parser

Summary:

1 file changed, 14 insertions(+), 51 deletions(-)
Committed as: 672187f
Pushed to: codeagent/claude/issue-576-1760327220

All requested changes have been applied and pushed to the PR branch.

Job run: https://github.com/goplus/llcppg/actions/runs/

- 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 <[email protected]>

luoliwoshang

@xgopilot resolve comments

CLAUDE.md

xgopilot · 2025-10-13T06:29:54Z

✅ All New Review Comments Resolved

Successfully addressed all 3 review comments from @luoliwoshang:

Changes Made:

LLGo Development Version Note (lines 54-62)
- ✅ Added clarification that the LLGo commit is a development version
- Noted that the specific commit is required for compatibility
Testing Strategy Reordering (lines 82-101)
- ✅ Renamed "Quick Tests" to "Unit Tests (Priority)"
- ✅ Moved unit tests to the top of the testing strategy section
- ✅ Emphasized running unit tests before the full test suite
- Reordered sections: Unit Tests → LLGo-Dependent Tests → Full Test Suite
Unit Test Verification Workflow (after line 283)
- ✅ Added comprehensive "Unit Test Verification for New Features" section
- Documented the complete workflow for creating test cases in _testdata/
- Explained testFrom function usage with gen:true parameter
- Included step-by-step instructions for generating gogensig.expect
- Added example test case directory structure
- Noted that test cases should not be committed unless they're permanent regression tests

Summary:

1 file changed, 44 insertions(+), 8 deletions(-)
Committed as: a8d0c0b
Pushed to: codeagent/claude/issue-576-1760327220

All requested changes have been applied and pushed to the PR branch.

Job run: https://github.com/goplus/llcppg/actions/runs/

- 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 <[email protected]>

luoliwoshang · 2025-10-13T06:45:46Z

CLAUDE.md

+## 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


Make these link to the design doc! @xgopilot

✅ Done! Added links to design documentation in the Architecture and Design section.

Changes made:

Added main design doc link at the section header: llcppg Design Documentation

Added specific link for Type Mapping System → Type Mapping

Added specific link for Name Conversion Rules → Name Mapping Rules

Added specific link for Dependency System → Dependency

Added specific link for File Generation Rules → File Generation Rules

Summary:

1 file changed, 9 insertions(+), 1 deletion(-)

Committed as: 63081e9

Pushed to: codeagent/claude/issue-576-1760327220

- 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 <[email protected]>

luoliwoshang · 2025-10-13T06:52:01Z

CLAUDE.md

+### Version Requirements
+- Go 1.23+
+- LLGo commit: `f0728c4fe028fbc72455c1242cef638ebdf60454`
+- LLVM 19 (exact version)


@xgopilot link to README

✅ Done! Added link to README in the Getting Help section.

Changes made:

Converted README.md reference to clickable link: README.md

Summary:

1 file changed, 1 insertion(+), 1 deletion(-)

Committed as: 6bafb21

Pushed to: codeagent/claude/issue-576-1760327220

- Convert README.md reference to clickable link Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot <[email protected]>

luoliwoshang · 2025-10-13T07:17:39Z

CLAUDE.md

+
+For detailed technical specifications, see [llcppg Design Documentation](doc/en/dev/llcppg.md).
+
+### Type Mapping System


@xgopilot These Architecture and Design already have doc!remove follow mapping rule descript!

✅ Done! Removed detailed mapping rule descriptions from Architecture and Design section.

Changes made:

Removed all detailed examples and code snippets from Type Mapping System subsection

Removed detailed descriptions from Name Conversion Rules subsection

Removed detailed descriptions from Dependency System subsection

Removed detailed descriptions from File Generation Rules subsection

Kept section headers and links to design documentation for reference

The design documentation contains all the detailed information

Summary:

1 file changed, 1 insertion(+), 66 deletions(-)

Committed as: 8ac23e2

Pushed to: codeagent/claude/issue-576-1760327220

The Architecture and Design section is now concise and delegates to the design docs for details, avoiding duplication.

- 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 <[email protected]>

luoliwoshang · 2025-10-13T07:53:50Z

CLAUDE.md

+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/`


@xgopilot remove this step ,current only keep Unit Test step at doc

✅ Done! Removed the Validation Workflow section, keeping only Unit Test Verification.

Changes made:

Removed the entire "Validation Workflow" section (8 lines)

This section contained steps for install.sh, config generation, and testing

Kept only the "Unit Test Verification for New Features" section

Simplifies documentation to focus on unit testing workflow

Summary:

1 file changed, 11 deletions(-)

Committed as: 0181c31

Pushed to: codeagent/claude/issue-576-1760327220

The documentation now focuses exclusively on the unit test verification process for new features.

- 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 <[email protected]>

luoliwoshang · 2025-10-13T08:12:46Z

CLAUDE.md

+## 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]
+```


@xgopilot remove this section!

✅ Done! Removed the Usage Workflow section from CLAUDE.md.

Changes made:

Removed the entire "Usage Workflow" section (37 lines)

This section contained:

Generate Configuration (llcppcfg usage)

Edit Configuration (llcppg.cfg fields)

Generate Bindings (llcppg command)

Validate Output (verification steps)

Document now flows directly from Pre-Commit Validation to Architecture and Design

Summary:

1 file changed, 37 deletions(-)

Committed as: daf2f6e

Pushed to: codeagent/claude/issue-576-1760327220

The documentation is now more concise and focused on essential information.

- 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 <[email protected]>

luoliwoshang · 2025-10-15T03:48:30Z

CLAUDE.md

+### 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 ..
+   ```


@xgopilot make it link to README.md!

✅ Done! Replaced the Development Setup section with a link to README.md.

Changes made:

Removed detailed Prerequisites subsection (LLVM 19, System Dependencies, LLGo setup instructions spanning 33 lines)

Removed Installation subsection with install.sh instructions

Replaced with concise link: "For detailed setup instructions including prerequisites, dependencies, and installation steps, see README.md."

Summary:

1 file changed, 1 insertion(+), 45 deletions(-)

Committed as: 582cad1

Pushed to: codeagent/claude/issue-576-1760327220

Branch: https://github.com/goplus/llcppg/tree/codeagent/claude/issue-576-1760327220
Job run: https://github.com/goplus/llcppg/actions/runs/

Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: luoliwoshang <[email protected]>

xgopilot bot mentioned this pull request Oct 13, 2025

basic CLAUDE.md #576

Open

luoliwoshang reviewed Oct 13, 2025

View reviewed changes

CLAUDE.md Outdated Show resolved Hide resolved

CLAUDE.md Show resolved Hide resolved

CLAUDE.md Outdated Show resolved Hide resolved

luoliwoshang reviewed Oct 13, 2025

View reviewed changes

docs: add README link to Getting Help section

6bafb21

- Convert README.md reference to clickable link Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot <[email protected]>

luoliwoshang reviewed Oct 13, 2025

View reviewed changes

luoliwoshang reviewed Oct 15, 2025

View reviewed changes

docs: replace Development Setup details with README link

582cad1

Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: luoliwoshang <[email protected]>

		Parser tests failing
		- Install llclang: `llgo install ./_xtool/llclang`


		For detailed technical specifications, see [llcppg Design Documentation](doc/en/dev/llcppg.md).

		### Type Mapping System

docs: add CLAUDE.md AI assistant guide #577

Are you sure you want to change the base?

docs: add CLAUDE.md AI assistant guide #577

Conversation

xgopilot bot commented Oct 13, 2025

Summary

Changes

Context

Testing

Uh oh!

codecov bot commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

luoliwoshang left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

xgopilot bot commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ All Review Comments Resolved

Uh oh!

luoliwoshang left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

xgopilot bot commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ All New Review Comments Resolved

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xgopilot bot Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xgopilot bot Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xgopilot bot Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xgopilot bot Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xgopilot bot Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xgopilot bot Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

codecov bot commented Oct 13, 2025 •

edited

Loading

xgopilot bot commented Oct 13, 2025 •

edited

Loading

xgopilot bot commented Oct 13, 2025 •

edited

Loading

xgopilot bot Oct 13, 2025 •

edited

Loading

xgopilot bot Oct 13, 2025 •

edited

Loading

xgopilot bot Oct 13, 2025 •

edited

Loading

xgopilot bot Oct 13, 2025 •

edited

Loading

xgopilot bot Oct 13, 2025 •

edited

Loading

xgopilot bot Oct 15, 2025 •

edited

Loading