llgo

LLGo - A Go compiler based on LLVM

LLGo is a Go compiler based on LLVM in order to better integrate Go with the C ecosystem, including Python and JavaScript. It’s a subproject of the XGo project.

LLGo aims to expand the boundaries of Go/XGo, providing limitless possibilities such as:

• Game development
• AI and data science
• WebAssembly
• Embedded development
• …

How can these be achieved?

LLGo := Go * C ecosystem

LLGo is compatible with the C ecosystem through the C Application Binary Interface (ABI), while LLGo is compatible with Go at the source-code level. The C ecosystem includes languages that expose C-compatible interfaces (e.g. C/C++, Python, JavaScript, Objective-C, and Swift).

Go support

LLGo is compatible with Go 1.20+ source code and supports the complete Go 1.27 language syntax, as well as cgo.

Compiler compatibility is checked against applicable upstream GOROOT/test cases using the pinned Go 1.27 toolchain. User projects and packages under test/ are additionally tested with exact Go 1.20 through Go 1.27 toolchains. Remaining applicable differences are recorded in xfail.yaml; gc-specific mechanisms outside LLGo’s compatibility goals are documented in notapplicable.yaml.

Runtime

LLGo uses a different runtime from the standard Go toolchain. Native goroutines map 1:1 to OS threads with fixed native stacks, so direct C calls require no Go-to-C stack or scheduler transition, avoiding the cgo overhead that makes frequent C calls costly in standard Go.

The default garbage collector is conservative BDWGC (also known as libgc). Bare-metal embedded targets instead use a TinyGo-derived conservative mark-and-sweep collector.

Garbage collection can be disabled with the nogc build tag. For example:

llgo run -tags nogc .

Standard libraries

LLGo fully supports the Go standard library on supported native platforms. CI requires compatibility coverage for every public package and exported symbol in the primary Go toolchain, and runs focused test/std compatibility sets with each older supported toolchain.

Other targets may not provide every OS service or implementation-specific runtime behavior.

The supported WebAssembly profiles combine a memory ABI with a host ABI. -target emscripten emits a Memory32 ES module and its sibling wasm module, -target emscripten-memory64 emits the corresponding Memory64 pair, and -target wasi emits a Memory32 WASI Preview 1 module. Raw GOOS=js GOARCH=wasm and GOOS=wasip1 GOARCH=wasm select the Go-compatible JavaScript and WASI host contracts. See the WebAssembly proposal for the compatibility contract and acceptance plan.

WebAssembly goroutine stacks have fixed sizes. For deeply recursive workloads, set -goroutine-stack-size=2MB when building (the existing -pthread-stack-size flag remains an alias). This sets both the goroutine stack and its Asyncify buffer; it does not change the main goroutine’s stack. JavaScript-hosted builds check stack bounds and abort on overflow instead of corrupting linear memory. These checks remain enabled in optimized builds: checking each stack-pointer update adds code and execution overhead, but a return-time cookie check alone cannot prevent a goroutine from overwriting adjacent memory.

C/C++ support

LLGo lets you import and call C/C++ libraries directly, without wrappers or cgo overhead.

Interop mechanism

LLGo uses go:linkname to bind a Go declaration directly to a C ABI symbol:

import _ "unsafe" // for go:linkname

//go:linkname Sqrt C.sqrt
func Sqrt(x float64) float64

You can use this directly in your own code:

package main

import _ "unsafe" // for go:linkname

//go:linkname Sqrt C.sqrt
func Sqrt(x float64) float64

func main() {
	println("sqrt(2) =", Sqrt(2))
}

Or organize such bindings into a package, as c/math does:

package main

import "github.com/goplus/lib/c/math"

func main() {
	println("sqrt(2) =", math.Sqrt(2))
}

Because calls into C compile to native calls against the C ABI, there is no Go-to-C stack or scheduler transition, so frequent C calls stay cheap.

Promoted C variadic methods

Forwarding an incoming C ellipsis through a promoted-method wrapper, including an interface call, is currently supported only on hosted native targets without an explicit -target profile. The underlying C method must have a pointer receiver. The wrapper and callee must have matching fixed LLVM prototypes and calling conventions, with no result conversion. Fixed parameters must be scalars, with zero or one scalar result: booleans, integers, floating-point values, and pointers qualify.

Value receivers, aggregate fixed parameters or results, multiple results, Wasm, and explicit -target profiles (including custom native profiles) remain outside this support. Selecting an unsupported forwarding wrapper through an interface conversion, method expression, or bound method produces a compiler error naming the method, target, and reason forwarding is unsupported. Call the C-linked method or function directly with explicit C-compatible arguments when forwarding is unavailable. Unused synthetic wrappers do not prevent those direct calls.

Windows API

On Windows, bind APIs declared with WINAPI or __stdcall through the stdcall. namespace. The convention is distinct on 386; Windows amd64 and arm64 use their unified native C ABI. An explicitly decorated 386 name such as _MessageBoxW@16 is also accepted and is normalized to MessageBoxW on 64-bit targets.

//go:linkname MessageBoxW stdcall.MessageBoxW
func MessageBoxW(hwnd uintptr, text, caption *uint16, flags uint32) int32

//llgo:stdcall
type Callback func(context uintptr) uintptr

stdcall. declarations and //llgo:stdcall apply only to non-variadic function types. A native callback is one function pointer, so a Go callback must be a direct function reference; pass state through an explicit context pointer rather than a capturing closure.

Calling-convention directives

A function type that models a C or Windows callback carries a calling-convention directive so the generated function pointer matches the native ABI:

• //llgo:cdecl selects the C calling convention.
• //llgo:stdcall selects the Windows stdcall convention (distinct only on 386; Windows amd64 and arm64 use their unified native C ABI).

import (
	"unsafe"

	"github.com/goplus/lib/c"
)

//llgo:cdecl
type Handler func(data unsafe.Pointer) c.Int

//llgo:stdcall
type WinProc func(hwnd uintptr, msg uint32, wParam, lParam uintptr) uintptr

The older //llgo:type C and //llgo:type stdcall spellings remain supported for backward compatibility but are deprecated: the compiler accepts them and prints a warning naming the replacement (//llgo:type C → //llgo:cdecl, //llgo:type stdcall → //llgo:stdcall). Prefer the new directives in new code. A type may carry only one calling-convention directive; combining them (for example //llgo:cdecl together with //llgo:stdcall or //llgo:type stdcall) is reported as an error.

Host-layout structs

Use a leading blank structs.HostLayout field for a struct exchanged with native code. LLGo recognizes the marker from type information, including aliases, defined marker types, and generic instantiations.

import "structs"

//llgo:cdecl
type Callback func(int32) int32

type Record struct {
    _        structs.HostLayout
    Callback Callback
    Data     *byte
}

The marker selects native field layout, not a calling convention. A plain Go func field still carries its closure environment; use an explicitly annotated function type for a native callback. Nested struct fields keep their own layout, and containing structs do not inherit the marker. Ordinary Go fields retain their storage representation, including when their address is passed to another function. On profiled wasm32 targets, Go pointers and uintptr still occupy eight bytes; explicitly annotated callback fields also retain their existing Go storage width. HostLayout does not change callback reflection or conversion semantics. Host records requiring four-byte address slots must use explicit fixed-width storage and convert at the interface boundary. A nonempty marked struct ending in a zero-sized field retains Go’s protective trailing padding.

The older struct-level //llgo:cdecl and //llgo:type C declarations remain accepted for compatibility. A struct that still carries a legacy type directive keeps its legacy source-layout behavior, including when a HostLayout marker is added directly or through a field. Remove the struct directive when adopting HostLayout. When migrating, give any native callback fields explicit callback types rather than relying on the outer struct’s directive. If Go and native pointer widths differ, use target-specific address/size slots and boundary accessors, retaining Go references for any addresses the host saves. The marker is a real zero-sized field: reflection field indices and positional struct literals must be adjusted when adding it. The runtime uses an internal compatibility marker on Go 1.20–1.22 and an alias to the standard structs.HostLayout on Go 1.23 and later.

C/C++ standard libraries

LLGo provides Go bindings for the C/C++ standard library:

Here is a simple example calling the C printf function:

package main

import "github.com/goplus/lib/c"

func main() {
	c.Printf(c.Str("Hello world\n"))
}

c.Str is not a runtime conversion from a Go string to a C string — it is a built-in instruction that llgo recognizes and compiles directly into a C string constant.

Additional demos are available in the _demo directory (prefixed with _ so the go command skips them):

• hello: call C printf and fprintf with Go and C strings
• qsort: call a C function that takes a callback (e.g. qsort)

To run a demo (see How to install if llgo isn’t installed yet):

cd <demo-directory>  # e.g. cd _demo/c/hello
llgo run .

Other frequently used libraries

Beyond the standard library, LLGo can import libraries from across the C/C++ ecosystem. Bindings are currently maintained by hand; automating this process, as is already done for Python library imports, is planned for the future.

Available bindings include:

• c/bdwgc
• cjson
• c/clang
• c/ffi
• c/libuv
• c/llama2
• c/lua
• c/neco
• c/openssl
• c/raylib
• c/sqlite
• c/zlib
• cpp/inih
• cpp/llvm

Examples built on these bindings:

• llama2-c: inference Llama 2 (the first LLGo AI example)
• mkjson: create a JSON object and print it
• sqlitedemo: a basic SQLite demo
• tetris: a Tetris game based on raylib

Python support

You can import a Python library in LLGo!

You can import Python libraries into llgo through llpyg. Available bindings include:

• py (abi)
• py/std (builtins)
• py/sys
• py/os
• py/math
• py/json
• py/inspect
• py/statistics
• py/numpy
• py/pandas
• py/torch
• py/matplotlib

Third-party libraries such as pandas and PyTorch must be installed separately.

Here is an example:

package main

import (
	"github.com/goplus/lib/py"
	"github.com/goplus/lib/py/math"
	"github.com/goplus/lib/py/std"
)

func main() {
	x := math.Sqrt(py.Float(2))       // x = sqrt(2)
	std.Print(py.Str("sqrt(2) ="), x) // print("sqrt(2) =", x)
}

It is equivalent to the following Python code:

import math

x = math.sqrt(2)
print("sqrt =", x)

Here, We call py.Float(2) to create a Python number 2, and pass it to Python’s math.sqrt to get x. Then we call std.Print to print the result.

Let’s look at a slightly more complex example. For example, we use numpy to calculate:

package main

import (
	"github.com/goplus/lib/py"
	"github.com/goplus/lib/py/numpy"
	"github.com/goplus/lib/py/std"
)

func main() {
	a := py.List(
		py.List(1.0, 2.0, 3.0),
		py.List(4.0, 5.0, 6.0),
		py.List(7.0, 8.0, 9.0),
	)
	b := py.List(
		py.List(9.0, 8.0, 7.0),
		py.List(6.0, 5.0, 4.0),
		py.List(3.0, 2.0, 1.0),
	)
	x := numpy.Add(a, b)
	std.Print(py.Str("a+b ="), x)
}

Here we define two 3x3 matrices a and b, add them to get x, and then print the result.

The _demo/py/ directory contains some python related demos:

• basic: call Python math, statistics, variadic builtin, iterator, and print APIs
• scientific: convert nested lists through NumPy and PyTorch

To run these demos (If you haven’t installed llgo yet, please refer to How to install):

cd <demo-directory>  # eg. cd _demo/py/basic
llgo run .

Dependencies

• Go 1.27 for building LLGo; CI validates user packages separately with Go 1.20 through Go 1.27
• LLVM 22
• Clang 22
• LLD 22
• LLDB (LLVM 22 packages on Linux/Windows; Xcode’s Apple LLDB on macOS)
• pkg-config 0.29+
• bdwgc/libgc 8.0+
• libffi
• OpenSSL 3.0+
• zlib 1.2+
• Python 3.12+ (optional, for github.com/goplus/lib/py)

How to install

Use the platform package manager instructions below whenever possible.

with mise or Pixi (development)

Install mise or Pixi, then enter the environment from the repository root:

mise -C dev trust
mise -C dev install --locked
mise -C dev en

Or, with Pixi:

cd dev
pixi shell --locked

In either shell, run cd .., then use go run ./cmd/llgo version or go build ./cmd/llgo. See development tooling for details.

on macOS

brew update
brew install llvm@22 lld@22 bdw-gc openssl cjson libffi libuv pkg-config
brew install [email protected] # optional
brew link --force --overwrite llvm@22 lld@22 libffi
./install.sh

Native macOS builds use LLVM/LLD 22 and require a macOS SDK older than 27. LLGo keeps the active SDK when it meets that requirement; otherwise it selects the newest installed older SDK from Xcode or Command Line Tools. SDK 27 and newer are excluded. Set SDKROOT to pin an installed older SDK; an unsupported or missing explicit SDK is an error. If no older SDK is installed, install one before building. The selected SDK is used for both compilation and linking.

Homebrew’s versioned LLVM 22 formula does not ship LLDB and there is no lldb@22 formula. LLGo checks common Homebrew and system locations, then lldb on PATH; use LLGO_LLDB or llgo lldb -lldb to select one explicitly.

on Linux

The APT/YUM configurations below accept packages without GPG signature verification (trusted=yes / gpgcheck=0); downloads use HTTPS.

Debian/Ubuntu

The DEB contains LLGo’s compiler, runtime, targets, licenses and a pinned ESP runtime archive, unpacked locally on the first embedded build. Native LLVM 22, Clang, LLD and native libraries are installed as system dependencies. Ubuntu 26.04 provides LLVM 22 in its standard repositories; on older Debian/Ubuntu releases, enable the matching apt.llvm.org LLVM 22 repository before installing LLGo.

Install the latest stable release for amd64 or arm64 from the APT repository:

echo 'deb [trusted=yes] https://pkgs.goplus.org/apt/ /' | sudo tee /etc/apt/sources.list.d/goplus.list
sudo apt-get update
sudo apt-get install -y llgo
llgo version

For source builds, install the build dependencies:

echo "deb http://apt.llvm.org/$(lsb_release -cs)/ llvm-toolchain-$(lsb_release -cs)-22 main" | sudo tee /etc/apt/sources.list.d/llvm.list
wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
sudo apt-get update
sudo apt-get install -y llvm-22-dev clang-22 libclang-22-dev lld-22 lldb-22 libunwind-22-dev libc++-22-dev pkg-config libgc-dev libssl-dev zlib1g-dev libffi-dev libcjson-dev libsqlite3-dev libuv1-dev
sudo apt-get install -y python3.12-dev # optional
./install.sh

Alpine Linux

apk add go llvm22-dev clang22-dev lld22 lldb pkgconf gc-dev libunwind-dev openssl-dev zlib-dev libffi-dev cjson-dev sqlite-dev libuv-dev
apk add python3-dev # optional
apk add g++ # build only
export LLVM_CONFIG=/usr/lib/llvm22/bin/llvm-config
export CGO_CPPFLAGS="$($LLVM_CONFIG --cppflags)"
export CGO_CXXFLAGS=-std=c++17
export CGO_LDFLAGS="$($LLVM_CONFIG --ldflags) $($LLVM_CONFIG --libs all)"
./install.sh

Fedora Linux 44 or newer

The RPM contains LLGo and a pinned ESP runtime archive, unpacked locally for embedded builds. Native compilation uses the system LLVM/Clang/LLD 22 packages and native libraries.

Install the latest stable release for amd64 or arm64 from the YUM/DNF repository:

sudo tee /etc/yum.repos.d/fury.repo > /dev/null <<'EOF'
[fury]
name=goplus (Gemfury)
baseurl=https://pkgs.goplus.org/yum/
enabled=1
gpgcheck=0
EOF
sudo dnf install -y llgo
llgo version

With YUM, use sudo yum install -y llgo for the installation command.

For source builds, Fedora 44 and 45 ship LLVM 22 as the default LLVM stack. Fedora 43 still ships LLVM 21 and is not a supported default-toolchain environment for this LLGo release.

sudo dnf install -y llvm-devel clang-devel lld lldb libcxx-devel llvm-libunwind-devel \
  pkgconf-pkg-config gc-devel openssl-devel libffi-devel libuv-devel \
  cjson-devel sqlite-devel zlib-ng-compat-devel
llvm-config --version # must report 22.x
./install.sh

docker alpine 386 llgo environment

export GCC_ROOT_DIR=$(gcc -print-search-dirs | grep 'install:' | awk -F': ' '{print $2}')
export LDFLAGS="-L$GCC_ROOT_DIR -B$GCC_ROOT_DIR -Wl,-dynamic-linker,/lib/ld-musl-i386.so.1"
llgo run .

on Windows

The release workflow builds six compact Windows ZIPs: llgo<VERSION>.windows-{386,amd64,arm64}-{msvc,mingw}.zip. Each contains LLGo, its DLL dependencies, runtime, targets and licenses. Add the extracted bin directory to PATH. Each architecture’s MSVC and MinGW archives contain the same statically linked llgo.exe. The pinned ESP runtime archive is bundled and unpacked locally into the user cache on the first ESP build.

See Windows release dependencies and PowerShell setup for the external tools, ABI-specific libraries, and pkg-config configuration needed to compile native programs. The document is included in every Windows ZIP.

Use the archive matching your native architecture and toolchain profile. Native programs still need the corresponding SDK/CRT, Clang, and dependencies described below: Visual Studio’s C++ developer environment for MSVC, or MSYS2 CLANG64 (amd64) / CLANGARM64 (arm64) for MinGW. For 386, configure the native i686 MSVC or MinGW environment described in WINDOWS.md; automatic dependency installation is unavailable. Bundled ESP Clang matches the host architecture, including native i686 and ARM64 tools for those hosts.

The recommended GNU-hosted setup is an MSYS2 CLANG64 shell. Install the LLVM 22 stack and LLGo’s native dependencies, then provide the versioned pkg-config metadata used by the Go/C++ bindings:

pacman -S --needed \
  mingw-w64-clang-x86_64-{clang,llvm,llvm-tools,lld,lldb,compiler-rt,libc++,libunwind} \
  mingw-w64-clang-x86_64-{gc,libffi,libuv,openssl,cjson,sqlite3,zlib,pkgconf}
test "$(llvm-config --version | cut -d. -f1)" = 22
pc_dir="$MINGW_PREFIX/lib/pkgconfig"
mkdir -p "$pc_dir"
printf '%s\n' \
  'Name: LLVM 22' \
  'Description: LLVM 22 host compiler and linker flags' \
  "Version: $(llvm-config --version)" \
  "Cflags: $(llvm-config --cflags)" \
  "Libs: $(llvm-config --ldflags --libs all --system-libs)" \
  > "$pc_dir/llvm-22.pc"

The native MSVC CI profile uses LLVM’s official 22.1.8 development archive for headers, libraries, Clang, LLD, and all code-generation backends. That archive does not contain LLDB, so the profile also extracts LLDB from the matching official win64 or woa64 installer. LLVM 22 has no official Win32 installer; the Windows 386 lane uses the LLVM 22.1.8-based llvm-mingw 20260616 builtins and qualifies the official x64 LLDB under WoW64. The complete pinned setup, checksums, and generated llvm-22.pc are in .github/actions/setup-deps/action.yml.

Install from source

git clone https://github.com/xgo-dev/llgo.git
cd llgo
./install.sh

Fallback release installers

The Unix fallback installs LLGo and, by default, Go and native C libraries. It does not install LLVM/Clang/LLD 22; install those with the platform steps above before compiling programs with LLGo.

On macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/xgo-dev/llgo/main/install.sh | bash

On Windows with MSVC, run in PowerShell:

irm https://raw.githubusercontent.com/xgo-dev/llgo/main/install.ps1 | iex

On Windows with MinGW, run in an MSYS2 CLANG64 or CLANGARM64 shell:

curl -fsSL https://raw.githubusercontent.com/xgo-dev/llgo/main/install.sh | bash

Go environment

Use llgo env GOOS GOARCH to query Go environment values and llgo env LLGO_ROOT LLGO_RUNTIME_DIR LLGO_LLVM_VERSION to inspect the LLGo installation and selected LLVM toolchain. With no variable names it prints both sets. -json provides machine-readable output, and -target name adds the resolved LLGO_TARGET_* fields for an embedded target without downloading tools or building libraries. For LLGO_* fields, -changed includes only values explicitly set in the process environment and omits derived values; Go fields retain the underlying go env -changed behavior. Paths for optional packaged tools are empty when the payload is not installed.

Go-only queries are delegated to the underlying Go toolchain and respect its environment and configuration. The -w and -u flags update the same GOENV configuration as go env; LLGo fields are read-only.

A real Go executable must remain in an absolute PATH directory. If go is a symlink or hard link to llgo, the environment command skips that link and searches the remaining PATH entries instead of invoking itself recursively.

Module management

Use llgo mod init, llgo mod tidy, llgo mod vendor, and other go mod subcommands to manage modules with the underlying Go toolchain. Arguments, working directory, environment, standard streams, and exit status are preserved. As with llgo env, a real Go executable must remain in an absolute PATH directory; links from go back to LLGo are skipped to prevent recursion.

Module maintenance does not inject LLGo-specific build tags. Go’s tidy and vendor already consider all build tags except ignore, including dependencies imported only by files with //go:build llgo.

Development tools

llgo list provides a Go-compatible package query backed by the real Go toolchain while adding LLGo’s source-selection build tags to package queries. Module queries keep caller-supplied and explicit target tags but do not add LLGo’s defaults. It supports the list queries used by golang.org/x/tools/go/packages, including list -f '{{context.GOARCH}} {{context.Compiler}}' -- unsafe; the reported gc context identifies Go frontend and type-size compatibility, not LLGo’s LLVM backend. Use -target name to apply a resolved LLGo target’s GOOS, GOARCH, and build tags without installing its toolchain. When go/packages requests -export=true, paths in the Export field refer to Go frontend type data in Go’s build cache, not LLGo package archives.

llgo get, llgo fix, llgo generate, and llgo vet use the Go toolchain with LLGo’s build tags and accept -target to select the target GOOS, GOARCH, and tags. llgo fmt and llgo work forward arguments unchanged; go fmt already includes files excluded by build constraints.

build, clean, install, run, test, version, and tool compile remain LLGo-specific. The Go bug, doc, and telemetry commands are not exposed: the first and last operate Go services, while go doc cannot select LLGo-only sources because it has no build-tag option.

• gentests: It refreshes runtime-output and package-metadata golden data under cl/_test*. LLVM IR checks live in Go sources as // LITTEST FileCheck directives.
• litgen: It maintains explicitly opted-in, source-embedded FileCheck snapshots. It supports function/global selection, update-only operation, stale-check verification, and stable LLVM value abstractions. Small handwritten checks remain manual.

For local workflows and test-golden refresh commands, see dev/README.md.

How do I generate these tools?

git clone https://github.com/xgo-dev/llgo.git
cd llgo
go install -v ./cmd/...
go install -v ./chore/...  # compile all tools except pydump

Key modules

Below are the key modules for understanding the implementation principles of llgo:

• ssa: It generates LLVM IR files (LLVM SSA) using the semantics and interfaces of Go SSA. Although LLVM SSA and Go SSA are both IR languages, they work at completely different levels. LLVM SSA is closer to machine code and abstracts over different instruction sets, while Go SSA is closer to a high-level language. We can think of it as the instruction set of the Go computer. llgo/ssa is not limited to the llgo compiler. If we view it as providing the high-level expressive power of LLVM, it is very useful. Its advanced SSA form lets clients use LLVM without operating directly on machine-code semantics.
• cl: It is the core of the llgo compiler. It converts a Go package into LLVM IR files. It depends on llgo/ssa.
• internal/build: It strings together the entire compilation process of llgo. It depends on llgo/ssa and llgo/cl.