From f65072d997e1dc73386711694b3865cc599c46cf Mon Sep 17 00:00:00 2001 From: xgopilot Date: Mon, 13 Oct 2025 06:16:41 +0000 Subject: [PATCH 1/9] docs: address review feedback on CLAUDE.md - Update _cmptest/ description to clarify its purpose - Remove scattered 'Verified output' sections - Consolidate all validation information into unified Validation section Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot --- CLAUDE.md | 46 +++++++++++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 19 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9d2db984..b88d0f80 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,7 +15,7 @@ LLGo is a Go compiler based on LLVM designed to better integrate Go with the C e - `runtime/` - LLGo runtime library - `chore/` - Development tools (llgen, llpyg, ssadump, etc.) - `_demo/` - Example programs (prefixed with `_` to prevent standard `go` command compilation) -- `_cmptest/` - Comparison tests +- `_cmptest/` - Comparison tests to verify the same program gets the same output with Go and LLGo ## Development Environment @@ -41,8 +41,6 @@ LLGo is a Go compiler based on LLVM designed to better integrate Go with the C e go build -v ./... ``` -**Verified output:** Successfully builds all packages without errors. - ### Build llgo command specifically ```bash go build -o llgo ./cmd/llgo @@ -53,11 +51,6 @@ go build -o llgo ./cmd/llgo llgo version ``` -**Verified output:** -``` -llgo v0.11.6-0.20251012014242-7e1abf1486b7 linux/amd64 -``` - ## Testing ### Run all tests @@ -77,13 +70,6 @@ cd _demo/c/hello LLGO_ROOT=/path/to/llgo llgo run . ``` -**Verified output:** -``` -hello world by println -hello world by fmt.Println -Hello world by c.Printf -``` - **Important:** The `LLGO_ROOT` environment variable must be set to the repository root when running llgo commands during development. ## Code Quality @@ -93,8 +79,6 @@ Hello world by c.Printf go fmt ./... ``` -**Verified:** Runs successfully with no output (indicating all files are properly formatted). - ### Run static analysis ```bash go vet ./... @@ -169,6 +153,30 @@ LLGO_ROOT=/path/to/llgo llgo run -tags nogc . 4. **C Ecosystem Integration:** LLGo uses `go:linkname` directive to link external symbols through ABI 5. **Python Integration:** Third-party Python libraries require separate installation of library files -## Verification Approach +## Validation -All commands and examples in this document have been executed and verified in the actual LLGo development environment. Any failures or limitations have been documented. +The following commands and workflows have been validated in the development environment: + +### Build Validation +- `go build -v ./...` - Successfully builds all packages without errors +- `go build -o llgo ./cmd/llgo` - Builds the llgo command +- `llgo version` - Output: `llgo v0.11.6-0.20251012014242-7e1abf1486b7 linux/amd64` + +### Code Quality Validation +- `go fmt ./...` - Runs successfully with no output (all files properly formatted) +- `go vet ./...` - Reports known issues in `ssa/type_cvt.go` and `cl/builtin_test.go` + +### Testing Validation +- `go test ./...` - Runs test suite (some tests require Python dependencies) +- `LLGO_ROOT=/workspace llgo run .` in `_demo/c/hello` - Output: + ``` + hello world by println + hello world by fmt.Println + Hello world by c.Printf + ``` + +### Environment +- Go: 1.24.5 linux/amd64 +- Operating System: Linux 5.4.0-164-generic + +All failures or limitations are documented in the relevant sections above. From c7e34087825293a736e14cb3f86fa298f7a5a74a Mon Sep 17 00:00:00 2001 From: xgopilot Date: Mon, 13 Oct 2025 06:39:52 +0000 Subject: [PATCH 2/9] docs: simplify CLAUDE.md per review feedback - Link Development Environment section to README to avoid redundancy - Remove 'Verified Environment' subsection - Remove 'Build pydump' section as not needed for current doc Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot --- CLAUDE.md | 22 +--------------------- 1 file changed, 1 insertion(+), 21 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b88d0f80..56619f57 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,20 +19,7 @@ LLGo is a Go compiler based on LLVM designed to better integrate Go with the C e ## Development Environment -**Verified Environment:** -- Go: 1.24.5 linux/amd64 -- Operating System: Linux 5.4.0-164-generic - -**Dependencies:** -- Go 1.21+ -- LLVM 18+ -- Clang 18+ -- LLD 18+ -- pkg-config 0.29+ -- bdwgc/libgc 8.0+ -- OpenSSL 3.0+ -- zlib 1.2+ -- Python 3.12+ (optional, for Python integration) +For detailed dependency requirements and installation instructions, see the [Dependencies](README.md#dependencies) and [How to install](README.md#how-to-install) sections in the README. ## Build Commands @@ -124,13 +111,6 @@ go install -v ./cmd/... go install -v ./chore/... ``` -### Build pydump (requires llgo) -```bash -export LLGO_ROOT=$PWD -cd _xtool -llgo install ./... -``` - ## Key Modules for Understanding - `ssa` - Generates LLVM IR using Go SSA semantics From 1edd4b863ea87632104b744f3156863c3016639d Mon Sep 17 00:00:00 2001 From: xgopilot Date: Mon, 13 Oct 2025 06:52:02 +0000 Subject: [PATCH 3/9] docs: merge Testing and Validation into single section - Combines Testing and Validation sections for better organization - Emphasizes these steps are essential when fixing bugs or implementing features - Maintains all validation information with clearer structure Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot --- CLAUDE.md | 57 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 56619f57..e7778850 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -38,7 +38,9 @@ go build -o llgo ./cmd/llgo llgo version ``` -## Testing +## Testing & Validation + +The following commands and workflows are essential when fixing bugs or implementing features in the LLGo project: ### Run all tests ```bash @@ -59,6 +61,32 @@ LLGO_ROOT=/path/to/llgo llgo run . **Important:** The `LLGO_ROOT` environment variable must be set to the repository root when running llgo commands during development. +### Validated Commands and Expected Outputs + +#### Build Validation +- `go build -v ./...` - Successfully builds all packages without errors +- `go build -o llgo ./cmd/llgo` - Builds the llgo command +- `llgo version` - Output: `llgo v0.11.6-0.20251012014242-7e1abf1486b7 linux/amd64` + +#### Code Quality Validation +- `go fmt ./...` - Runs successfully with no output (all files properly formatted) +- `go vet ./...` - Reports known issues in `ssa/type_cvt.go` and `cl/builtin_test.go` + +#### Testing Validation +- `go test ./...` - Runs test suite (some tests require Python dependencies) +- `LLGO_ROOT=/workspace llgo run .` in `_demo/c/hello` - Output: + ``` + hello world by println + hello world by fmt.Println + Hello world by c.Printf + ``` + +#### Environment +- Go: 1.24.5 linux/amd64 +- Operating System: Linux 5.4.0-164-generic + +All failures or limitations are documented in the relevant sections above. + ## Code Quality ### Format code @@ -133,30 +161,3 @@ LLGO_ROOT=/path/to/llgo llgo run -tags nogc . 4. **C Ecosystem Integration:** LLGo uses `go:linkname` directive to link external symbols through ABI 5. **Python Integration:** Third-party Python libraries require separate installation of library files -## Validation - -The following commands and workflows have been validated in the development environment: - -### Build Validation -- `go build -v ./...` - Successfully builds all packages without errors -- `go build -o llgo ./cmd/llgo` - Builds the llgo command -- `llgo version` - Output: `llgo v0.11.6-0.20251012014242-7e1abf1486b7 linux/amd64` - -### Code Quality Validation -- `go fmt ./...` - Runs successfully with no output (all files properly formatted) -- `go vet ./...` - Reports known issues in `ssa/type_cvt.go` and `cl/builtin_test.go` - -### Testing Validation -- `go test ./...` - Runs test suite (some tests require Python dependencies) -- `LLGO_ROOT=/workspace llgo run .` in `_demo/c/hello` - Output: - ``` - hello world by println - hello world by fmt.Println - Hello world by c.Printf - ``` - -### Environment -- Go: 1.24.5 linux/amd64 -- Operating System: Linux 5.4.0-164-generic - -All failures or limitations are documented in the relevant sections above. From a99f3d940900292bc3fe8eeaaefdc70ae0bb3e8d Mon Sep 17 00:00:00 2001 From: xgopilot Date: Mon, 13 Oct 2025 07:16:39 +0000 Subject: [PATCH 4/9] docs: refactor Important Notes with clear workflow and requirements - Add clear 'Validation Workflow' section with numbered steps - Create prominent 'LLGO_ROOT Environment Variable' section - Add requirement: All bug fixes/features MUST include tests - Reorganize Important Notes for better clarity Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot --- CLAUDE.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index e7778850..b69138be 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -153,9 +153,31 @@ For testing purposes, you can disable GC: LLGO_ROOT=/path/to/llgo llgo run -tags nogc . ``` +## Validation Workflow + +When fixing bugs or implementing features, follow this workflow: + +1. **Make your code changes** +2. **Write or update tests** - All bug fixes and features MUST include tests +3. **Run the test suite**: `go test ./...` +4. **Build the project**: `go build -v ./...` +5. **Test with examples**: Run relevant demos from `_demo/` directory +6. **Format code**: `go fmt ./...` +7. **Run static analysis**: `go vet ./...` + +## LLGO_ROOT Environment Variable + +**CRITICAL:** Always set `LLGO_ROOT` to the repository root when running llgo during development: + +```bash +export LLGO_ROOT=/path/to/llgo +# or +LLGO_ROOT=/path/to/llgo llgo run . +``` + ## Important Notes -1. **LLGO_ROOT:** Always set `LLGO_ROOT` to the repository root when running llgo during development +1. **Testing Requirement:** All bug fixes and features MUST include tests 2. **Demo Directory:** Examples in `_demo` are prefixed with `_` to prevent standard `go` command from trying to compile them 3. **Defer in Loops:** LLGo intentionally does not support `defer` in loops (considered bad practice) 4. **C Ecosystem Integration:** LLGo uses `go:linkname` directive to link external symbols through ABI From 72602d606d2a72ad28704981a74ce8a3f4898204 Mon Sep 17 00:00:00 2001 From: xgopilot Date: Mon, 13 Oct 2025 07:36:11 +0000 Subject: [PATCH 5/9] docs: address review feedback on CLAUDE.md - Move demo examples to Project Structure with simplified descriptions - Change 'Test a simple example' to focus on writing and running test cases - Remove standalone Running Examples section to reduce redundancy Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot --- CLAUDE.md | 39 +++++++++++---------------------------- 1 file changed, 11 insertions(+), 28 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b69138be..e650759d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,7 +14,7 @@ LLGo is a Go compiler based on LLVM designed to better integrate Go with the C e - `internal/build/` - Build process orchestration - `runtime/` - LLGo runtime library - `chore/` - Development tools (llgen, llpyg, ssadump, etc.) -- `_demo/` - Example programs (prefixed with `_` to prevent standard `go` command compilation) +- `_demo/` - Example programs demonstrating C/C++ interop (`c/hello`, `c/qsort`) and Python integration (`py/callpy`, `py/numpy`) - `_cmptest/` - Comparison tests to verify the same program gets the same output with Go and LLGo ## Development Environment @@ -53,10 +53,17 @@ go test ./... - C interop - Python integration (requires Python development headers) -### Test a simple example +### Write and run tests for your changes + +When adding new functionality or fixing bugs, create appropriate test cases: + ```bash -cd _demo/c/hello -LLGO_ROOT=/path/to/llgo llgo run . +# Add your test to the relevant package's *_test.go file +# Then run tests for that package +go test ./path/to/package + +# Or run all tests +go test ./... ``` **Important:** The `LLGO_ROOT` environment variable must be set to the repository root when running llgo commands during development. @@ -101,30 +108,6 @@ go vet ./... **Note:** Currently reports some issues related to lock passing by value in `ssa/type_cvt.go` and a possible unsafe.Pointer misuse in `cl/builtin_test.go`. These are known issues. -## Running Examples - -The `_demo` directory contains working examples: - -### C Standard Library Examples -```bash -cd _demo/c/hello -LLGO_ROOT=/path/to/llgo llgo run . -``` - -Other C examples: -- `_demo/c/concat` - Variadic function with fprintf -- `_demo/c/qsort` - C function callbacks - -### Python Integration Examples -```bash -cd _demo/py/callpy -LLGO_ROOT=/path/to/llgo llgo run . -``` - -Other Python examples: -- `_demo/py/pi` - Python constants -- `_demo/py/statistics` - Python list and statistics -- `_demo/py/matrix` - NumPy demo ## Common Development Tasks From 00d5aad528f735ac3d16ca7a79991c88e6427d86 Mon Sep 17 00:00:00 2001 From: xgopilot Date: Mon, 13 Oct 2025 07:45:24 +0000 Subject: [PATCH 6/9] docs: remove duplicate validation section from CLAUDE.md - Remove 'Validated Commands and Expected Outputs' section (lines 71-95) - This information is already covered in 'Validation Workflow' section - Reduces redundancy and improves document clarity Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot --- CLAUDE.md | 26 -------------------------- 1 file changed, 26 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e650759d..1e2b0d95 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -68,32 +68,6 @@ go test ./... **Important:** The `LLGO_ROOT` environment variable must be set to the repository root when running llgo commands during development. -### Validated Commands and Expected Outputs - -#### Build Validation -- `go build -v ./...` - Successfully builds all packages without errors -- `go build -o llgo ./cmd/llgo` - Builds the llgo command -- `llgo version` - Output: `llgo v0.11.6-0.20251012014242-7e1abf1486b7 linux/amd64` - -#### Code Quality Validation -- `go fmt ./...` - Runs successfully with no output (all files properly formatted) -- `go vet ./...` - Reports known issues in `ssa/type_cvt.go` and `cl/builtin_test.go` - -#### Testing Validation -- `go test ./...` - Runs test suite (some tests require Python dependencies) -- `LLGO_ROOT=/workspace llgo run .` in `_demo/c/hello` - Output: - ``` - hello world by println - hello world by fmt.Println - Hello world by c.Printf - ``` - -#### Environment -- Go: 1.24.5 linux/amd64 -- Operating System: Linux 5.4.0-164-generic - -All failures or limitations are documented in the relevant sections above. - ## Code Quality ### Format code From 62198a59ba40a15e1f4148c761518b21a1ea8f78 Mon Sep 17 00:00:00 2001 From: xgopilot Date: Mon, 13 Oct 2025 07:53:12 +0000 Subject: [PATCH 7/9] docs: add descriptive instructions to Code Quality section - Add requirement to run formatting before submitting code updates - Emphasize that go fmt must be run before committing changes - Clarify that formatting ensures consistent code formatting Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot --- CLAUDE.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 1e2b0d95..362478b6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -70,11 +70,15 @@ go test ./... ## Code Quality +Before submitting any code updates, you must run the following formatting and validation commands: + ### Format code ```bash go fmt ./... ``` +**Important:** Always run `go fmt ./...` before committing code changes. This ensures consistent code formatting across the project. + ### Run static analysis ```bash go vet ./... From d6f45c67fb1901a434d5bf4e21d5a3b66bda4038 Mon Sep 17 00:00:00 2001 From: xgopilot Date: Mon, 13 Oct 2025 08:05:56 +0000 Subject: [PATCH 8/9] docs: merge Testing and Validation into single section - Move Build Commands into Common Development Tasks section - Remove duplicate Validation Workflow section - Simplify document structure by consolidating build commands Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot --- CLAUDE.md | 34 +++++----------------------------- 1 file changed, 5 insertions(+), 29 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 362478b6..e8ded7c6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,23 +21,6 @@ LLGo is a Go compiler based on LLVM designed to better integrate Go with the C e For detailed dependency requirements and installation instructions, see the [Dependencies](README.md#dependencies) and [How to install](README.md#how-to-install) sections in the README. -## Build Commands - -### Build the entire project -```bash -go build -v ./... -``` - -### Build llgo command specifically -```bash -go build -o llgo ./cmd/llgo -``` - -### Check llgo version -```bash -llgo version -``` - ## Testing & Validation The following commands and workflows are essential when fixing bugs or implementing features in the LLGo project: @@ -89,6 +72,11 @@ go vet ./... ## Common Development Tasks +### Build the project +```bash +go build -v ./... +``` + ### Install llgo for system-wide use ```bash ./install.sh @@ -114,18 +102,6 @@ For testing purposes, you can disable GC: LLGO_ROOT=/path/to/llgo llgo run -tags nogc . ``` -## Validation Workflow - -When fixing bugs or implementing features, follow this workflow: - -1. **Make your code changes** -2. **Write or update tests** - All bug fixes and features MUST include tests -3. **Run the test suite**: `go test ./...` -4. **Build the project**: `go build -v ./...` -5. **Test with examples**: Run relevant demos from `_demo/` directory -6. **Format code**: `go fmt ./...` -7. **Run static analysis**: `go vet ./...` - ## LLGO_ROOT Environment Variable **CRITICAL:** Always set `LLGO_ROOT` to the repository root when running llgo during development: From 391e09a407ed6607e023f3a8b3ce86589566b119 Mon Sep 17 00:00:00 2001 From: xgopilot Date: Mon, 13 Oct 2025 08:07:23 +0000 Subject: [PATCH 9/9] docs: migrate all build commands to Common Development Tasks - Add 'Build llgo command specifically' and 'Check llgo version' commands - Consolidate all build-related commands in one section - Reduce redundancy by having single section for development tasks Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: xgopilot --- CLAUDE.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index e8ded7c6..8aba87af 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -72,11 +72,21 @@ go vet ./... ## Common Development Tasks -### Build the project +### Build the entire project ```bash go build -v ./... ``` +### Build llgo command specifically +```bash +go build -o llgo ./cmd/llgo +``` + +### Check llgo version +```bash +llgo version +``` + ### Install llgo for system-wide use ```bash ./install.sh