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 (prefixed with _ to prevent standard go command compilation)
• _cmptest/ - Comparison tests

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)

Build Commands

Build the entire project

go build -v ./...

Verified output: Successfully builds all packages without errors.

Build llgo command specifically

go build -o llgo ./cmd/llgo

Check llgo version

llgo version

Verified output:

llgo v0.11.6-0.20251012014242-7e1abf1486b7 linux/amd64

Testing

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)

Test a simple example

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

Format code

go fmt ./...

Verified: Runs successfully with no output (indicating all files are properly formatted).

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.

Running Examples

The _demo directory contains working examples:

C Standard Library Examples

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

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

Install llgo for system-wide use

./install.sh

Build development tools

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

Build pydump (requires llgo)

export LLGO_ROOT=$PWD
cd _xtool
llgo install ./...

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 .

Important Notes

1. LLGO_ROOT: Always set LLGO_ROOT to the repository root when running llgo during development
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

Verification Approach

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.