From 8f5f36e447f814db4cc86128160235898035d408 Mon Sep 17 00:00:00 2001 From: xgopilot Date: Fri, 31 Oct 2025 02:43:06 +0000 Subject: [PATCH 1/4] docs(CLAUDE.md): document out.ll update process after IR changes Add comprehensive documentation explaining: - What out.ll files are (IR comparison test files) - When to update them (after modifying IR generation logic) - How to update them (reinstall llgen, regenerate files) - Why this matters (test consistency and regression detection) This documentation will help avoid wasting time on repeatedly updating test files, as it clarifies the required workflow when making compiler changes that affect IR generation. Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: luoliwoshang <51194195+luoliwoshang@users.noreply.github.com> --- CLAUDE.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 8aba87af..d52e8b84 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -51,6 +51,48 @@ go test ./... **Important:** The `LLGO_ROOT` environment variable must be set to the repository root when running llgo commands during development. +### Update out.ll files after modifying compiler IR generation + +**CRITICAL:** When you modify the compiler's IR generation logic (especially in `ssa/` or `cl/` packages), you MUST update all out.ll test files under the `cl/` directory. + +#### Understanding out.ll files + +The `out.ll` files under the `cl/` directory are comparison IR files that serve as reference outputs for the test suite: +- They are generated by `llgen` from the corresponding `in.go` files in the same directory +- They reflect the current compiler's LLVM IR representation of the Go source code +- They are used by tests to verify that the compiler generates correct and consistent IR output + +#### Required steps after modifying IR generation logic + +1. **Reinstall llgen** to apply your compiler changes: + ```bash + go install -v ./chore/llgen + ``` + +2. **Regenerate all out.ll files** under the `cl/` directory: + ```bash + # llgen automatically finds and updates all test cases + llgen + ``` + Or you can regenerate specific test directories: + ```bash + llgen cl/_testgo/interface + llgen cl/_testrt/tpmethod + ``` + +3. **Verify the changes** make sense by reviewing the diff in the out.ll files + +4. **Commit the updated out.ll files** along with your compiler changes + +#### Why this matters + +Failing to update out.ll files after modifying IR generation will cause test failures in `TestFromTestgo` and `TestFromTestrt`. This process ensures that: +- The test suite reflects the current compiler behavior +- Changes to IR generation are properly documented and reviewed +- Future regressions can be detected by comparing against the reference output + +**Pro tip:** Always check if your changes affect IR generation. If you're unsure, run the tests first - they will fail if out.ll files need updating. + ## Code Quality Before submitting any code updates, you must run the following formatting and validation commands: From c15c7a05b710179582dfcc4bc86b9776075a9165 Mon Sep 17 00:00:00 2001 From: xgopilot Date: Fri, 31 Oct 2025 03:27:49 +0000 Subject: [PATCH 2/4] docs(CLAUDE.md): add gentests for batch out.ll updates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated the out.ll update workflow to document both tools: - gentests: batch regeneration of all test files (recommended) - llgen: individual test directory regeneration (for inspection) Verified gentests works correctly by testing the regeneration of all out.ll files. The tool successfully processes all non-Python test directories. 🤖 Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: luoliwoshang <51194195+luoliwoshang@users.noreply.github.com> --- CLAUDE.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d52e8b84..05316b54 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -64,17 +64,27 @@ The `out.ll` files under the `cl/` directory are comparison IR files that serve #### Required steps after modifying IR generation logic -1. **Reinstall llgen** to apply your compiler changes: +1. **Reinstall the tools** to apply your compiler changes: ```bash + go install -v ./chore/gentests go install -v ./chore/llgen ``` -2. **Regenerate all out.ll files** under the `cl/` directory: +2. **Regenerate out.ll files**: + + **For batch updates (recommended)** - Use `gentests` to regenerate all test files: ```bash - # llgen automatically finds and updates all test cases - llgen + gentests ``` - Or you can regenerate specific test directories: + This will automatically regenerate all out.ll files in these directories: + - `cl/_testlibc` + - `cl/_testlibgo` + - `cl/_testrt` + - `cl/_testgo` + - `cl/_testpy` + - `cl/_testdata` + + **For individual test inspection** - Use `llgen` to regenerate specific test directories: ```bash llgen cl/_testgo/interface llgen cl/_testrt/tpmethod From c557aa2af1a29e419dc0124c63dde4cc55789d6a Mon Sep 17 00:00:00 2001 From: xgopilot Date: Fri, 31 Oct 2025 03:34:08 +0000 Subject: [PATCH 3/4] docs(CLAUDE.md): remove pro tip line Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: luoliwoshang <51194195+luoliwoshang@users.noreply.github.com> --- CLAUDE.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 05316b54..8a1e2a71 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -101,8 +101,6 @@ Failing to update out.ll files after modifying IR generation will cause test fai - Changes to IR generation are properly documented and reviewed - Future regressions can be detected by comparing against the reference output -**Pro tip:** Always check if your changes affect IR generation. If you're unsure, run the tests first - they will fail if out.ll files need updating. - ## Code Quality Before submitting any code updates, you must run the following formatting and validation commands: From 01af858a2e7838b6aa85a07fdf2cfbef0a99274a Mon Sep 17 00:00:00 2001 From: xgopilot Date: Fri, 31 Oct 2025 03:42:54 +0000 Subject: [PATCH 4/4] docs(CLAUDE.md): remove redundant test failure mention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Removed the sentence about test failures as requested. The "Why this matters" section now focuses on the benefits of the process rather than the negative consequences. 🤖 Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: luoliwoshang <51194195+luoliwoshang@users.noreply.github.com> --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8a1e2a71..4fd9632c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -96,7 +96,7 @@ The `out.ll` files under the `cl/` directory are comparison IR files that serve #### Why this matters -Failing to update out.ll files after modifying IR generation will cause test failures in `TestFromTestgo` and `TestFromTestrt`. This process ensures that: +This process ensures that: - The test suite reflects the current compiler behavior - Changes to IR generation are properly documented and reviewed - Future regressions can be detected by comparing against the reference output