llgo/CLAUDE.md

LLGo Project AI Assistant Guide

This document provides essential information for AI assistants to help fix bugs and implement features in the LLGo project.

About LLGo

LLGo is a Go compiler based on LLVM designed to better integrate Go with the C ecosystem, including Python and JavaScript. It's a subproject of the XGo project that aims to expand the boundaries of Go/XGo for game development, AI and data science, WebAssembly, and embedded development.

Project Structure

• cmd/llgo - Main llgo compiler command (usage similar to go command)
• cl/ - Core compiler logic that converts Go packages to LLVM IR
• ssa/ - LLVM IR file generation using Go SSA semantics
• internal/build/ - Build process orchestration
• runtime/ - LLGo runtime library
• chore/ - Development tools (llgen, llpyg, ssadump, etc.)
• _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

For detailed dependency requirements and installation instructions, see the Dependencies and How to install sections in the README.

Testing & Validation

The following commands and workflows are essential when fixing bugs or implementing features in the LLGo project:

Run all tests

go test ./...

Note: Some tests may fail if optional dependencies (like Python) are not properly configured. The test suite includes comprehensive tests for:

• Compiler functionality
• SSA generation
• C interop
• Python integration (requires Python development headers)

Write and run tests for your changes

When adding new functionality or fixing bugs, create appropriate test cases:

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

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:

   go install -v ./chore/llgen
   

2. Regenerate all out.ll files under the cl/ directory:

   # llgen automatically finds and updates all test cases
   llgen
   

   Or you can regenerate specific test directories:

   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:

Format code

go fmt ./...

Important: Always run go fmt ./... before committing code changes. This ensures consistent code formatting across the project.

Run static analysis

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.

Common Development Tasks

Build the entire project

go build -v ./...

Build llgo command specifically

go build -o llgo ./cmd/llgo

Check llgo version

llgo version

Install llgo for system-wide use

./install.sh

Build development tools

go install -v ./cmd/...
go install -v ./chore/...

Key Modules for Understanding

• ssa - Generates LLVM IR using Go SSA semantics
• cl - Core compiler converting Go to LLVM IR
• internal/build - Orchestrates the compilation process

Debugging

Disable Garbage Collection

For testing purposes, you can disable GC:

LLGO_ROOT=/path/to/llgo llgo run -tags nogc .

LLGO_ROOT Environment Variable

CRITICAL: Always set LLGO_ROOT to the repository root when running llgo during development:

export LLGO_ROOT=/path/to/llgo
# or
LLGO_ROOT=/path/to/llgo llgo run .

Important Notes

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
5. Python Integration: Third-party Python libraries require separate installation of library files