README.md Raw History Folder

purego

A library for calling C functions from Go without Cgo.

Fork notice: this repository is a maintained fork of github.com/ebitengine/purego with additional ABI, callback, and generator-facing fixes needed by the PureGoTK stack.

This is beta software so expect bugs and potentially API breaking changes but each release will be tagged to avoid breaking people's code. Bug reports are encouraged.

Motivation

The Ebitengine game engine was ported to use only Go on Windows. This enabled cross-compiling to Windows from any other operating system simply by setting GOOS=windows. The purego project was born to bring that same vision to the other platforms supported by Ebitengine.

Benefits

Simple Cross-Compilation: No C means you can build for other platforms easily without a C compiler.
Faster Compilation: Efficiently cache your entirely Go builds.
Smaller Binaries: Using Cgo generates a C wrapper function for each C function called. Purego doesn't!
Dynamic Linking: Load symbols at runtime and use it as a plugin system.
Foreign Function Interface: Call into other languages that are compiled into shared objects.
Cgo Fallback: Works even with CGO_ENABLED=1 so incremental porting is possible. This also means unsupported GOARCHs (freebsd/riscv64, linux/mips, etc.) will still work except for float arguments and return values.

Supported Platforms

Tier 1

Tier 1 platforms are the primary targets officially supported by PureGo. When a new version of PureGo is released, any critical bugs found on Tier 1 platforms are treated as release blockers. The release will be postponed until such issues are resolved.

Android: amd641, arm641
iOS: amd641, arm641
Linux: amd64, arm64
macOS: amd64, arm64
Windows: amd64, arm64

Tier 2

Tier 2 platforms are supported by PureGo on a best-effort basis. Critical bugs on Tier 2 platforms do not block new PureGo releases. However, fixes contributed by external contributors are very welcome and encouraged.

Android: 3861, arm1
FreeBSD: amd642, arm642
Linux: 386, arm, loong64, ppc64le, riscv64, s390x1
NetBSD: amd642, arm642
Windows: 3863, arm3,4

Support Notes

These architectures require CGO_ENABLED=1 to compile
These architectures require the special flag -gcflags="github.com/bnema/purego/internal/fakecgo=-std" to compile with CGO_ENABLED=0
These architectures only support SyscallN and NewCallback
These architectures are no longer supported as of Go 1.26

Example

The example below only showcases purego use for macOS and Linux. The other platforms require special handling which can be seen in the complete example at examples/libc which supports FreeBSD and Windows.

package main

import (
	"fmt"
	"runtime"

	"github.com/bnema/purego"
)

func getSystemLibrary() string {
	switch runtime.GOOS {
	case "darwin":
		return "/usr/lib/libSystem.B.dylib"
	case "linux":
		return "libc.so.6"
	default:
		panic(fmt.Errorf("GOOS=%s is not supported", runtime.GOOS))
	}
}

func main() {
	libc, err := purego.Dlopen(getSystemLibrary(), purego.RTLD_NOW|purego.RTLD_GLOBAL)
	if err != nil {
		panic(err)
	}
	var puts func(string)
	purego.RegisterLibFunc(&puts, libc, "puts")
	puts("Calling C from Go without Cgo!")
}

Then to run: CGO_ENABLED=0 go run main.go

Callback diagnostics

Callback allocation diagnostics are disabled by default. When debugging callback slot exhaustion on Unix-like platforms, set PUREGO_CALLBACK_LEDGER=1 to append JSONL callback lifecycle events to /tmp/purego-callback-ledger-<pid>.jsonl, or set PUREGO_CALLBACK_LEDGER_FILE=/path/to/file.jsonl to choose the output file. Stack capture is also disabled by default; set PUREGO_CALLBACK_LEDGER_STACK=1 when call site attribution is needed. Stack capture adds per-callback overhead and should be reserved for active debugging sessions. For ad-hoc stderr/file traces near callback exhaustion, set PUREGO_CALLBACK_TRACE=1; PUREGO_CALLBACK_TRACE_FILE overrides the default /tmp/purego-callback-trace-<pid>.log path.

Diagnostic files are created with 0o600 permissions. They are append-only and unbounded, so long-running processes can exhaust disk space if diagnostics stay enabled. A ledger line is a JSON object such as:

{"time":"2026-06-09T14:03:00Z","pid":1234,"seq":42,"event":"alloc","index":7,"addr":"0x1234","stack":"..."}

Use time as the timestamp, index as the callback ID, and the pid, seq, event, addr, and optional stack fields when parsing the ledger output.

Questions

If you have questions about how to incorporate purego in your project or want to discuss how it works join the Discord!

External Code

Purego uses code that originates from the Go runtime. These files are under the BSD-3 License that can be found in the Go Source. This is a list of the copied files:

abi_*.h from package runtime/cgo
wincallback.go from package runtime
zcallback_darwin_*.s from package runtime
internal/fakecgo/abi_*.h from package runtime/cgo
internal/fakecgo/asm_GOARCH.s from package runtime/cgo
internal/fakecgo/callbacks.go from package runtime/cgo
internal/fakecgo/iscgo.go from package runtime/cgo
internal/fakecgo/setenv.go from package runtime/cgo
internal/fakecgo/freebsd.go from package runtime/cgo
internal/fakecgo/netbsd.go from package runtime/cgo
internal/fakecgo/linux.go from package runtime/cgo

The internal/fakecgo/go_GOOS.go files were modified from runtime/cgo/gcc_GOOS_GOARCH.go. The internal/fakecgo/linux.go file is a combination of runtime/cgo/linux.go and runtime/cgo/linux_syscall.c.

The files abi_*.h and internal/fakecgo/abi_*.h are the same because Bazel does not support cross-package use of #include so we need each one once per package. (cf. issue)

source

1# purego
2[![Go Reference](https://pkg.go.dev/badge/github.com/bnema/purego?GOOS=darwin.svg)](https://pkg.go.dev/github.com/bnema/purego?GOOS=darwin)
3
4A library for calling C functions from Go without Cgo.
5
6> Fork notice: this repository is a maintained fork of `github.com/ebitengine/purego` with additional ABI, callback, and generator-facing fixes needed by the PureGoTK stack.
7
8> This is beta software so expect bugs and potentially API breaking changes
9> but each release will be tagged to avoid breaking people's code.
10> Bug reports are encouraged.
11
12## Motivation
13
14The [Ebitengine](https://github.com/hajimehoshi/ebiten) game engine was ported to use only Go on Windows. This enabled
15cross-compiling to Windows from any other operating system simply by setting `GOOS=windows`. The purego project was
16born to bring that same vision to the other platforms supported by Ebitengine.
17
18## Benefits
19
20- **Simple Cross-Compilation**: No C means you can build for other platforms easily without a C compiler.
21- **Faster Compilation**: Efficiently cache your entirely Go builds.
22- **Smaller Binaries**: Using Cgo generates a C wrapper function for each C function called. Purego doesn't!
23- **Dynamic Linking**: Load symbols at runtime and use it as a plugin system.
24- **Foreign Function Interface**: Call into other languages that are compiled into shared objects.
25- **Cgo Fallback**: Works even with CGO_ENABLED=1 so incremental porting is possible. 
26This also means unsupported GOARCHs (freebsd/riscv64, linux/mips, etc.) will still work
27except for float arguments and return values.
28
29## Supported Platforms
30
31### Tier 1
32
33Tier 1 platforms are the primary targets officially supported by PureGo. When a new version of PureGo is released, any critical bugs found on Tier 1 platforms are treated as release blockers. The release will be postponed until such issues are resolved.
34
35- **Android**: amd64<sup>1</sup>, arm64<sup>1</sup>
36- **iOS**: amd64<sup>1</sup>, arm64<sup>1</sup>
37- **Linux**: amd64, arm64
38- **macOS**: amd64, arm64
39- **Windows**: amd64, arm64
40
41### Tier 2
42
43Tier 2 platforms are supported by PureGo on a best-effort basis. Critical bugs on Tier 2 platforms do not block new PureGo releases. However, fixes contributed by external contributors are very welcome and encouraged.
44
45- **Android**: 386<sup>1</sup>, arm<sup>1</sup>
46- **FreeBSD**: amd64<sup>2</sup>, arm64<sup>2</sup>
47- **Linux**: 386, arm, loong64, ppc64le, riscv64, s390x<sup>1</sup>
48- **NetBSD**: amd64<sup>2</sup>, arm64<sup>2</sup>
49- **Windows**: 386<sup>3</sup>, arm<sup>3,4</sup>
50
51#### Support Notes
52
531. These architectures require CGO_ENABLED=1 to compile
542. These architectures require the special flag `-gcflags="github.com/bnema/purego/internal/fakecgo=-std"` to compile with CGO_ENABLED=0
553. These architectures only support `SyscallN` and `NewCallback`
564. These architectures are no longer supported as of Go 1.26
57
58## Example
59
60The example below only showcases purego use for macOS and Linux. The other platforms require special handling which can
61be seen in the complete example at [examples/libc](https://github.com/bnema/purego/tree/main/examples/libc) which supports FreeBSD and Windows.
62
63```go
64package main
65
66import (
67	"fmt"
68	"runtime"
69
70	"github.com/bnema/purego"
71)
72
73func getSystemLibrary() string {
74	switch runtime.GOOS {
75	case "darwin":
76		return "/usr/lib/libSystem.B.dylib"
77	case "linux":
78		return "libc.so.6"
79	default:
80		panic(fmt.Errorf("GOOS=%s is not supported", runtime.GOOS))
81	}
82}
83
84func main() {
85	libc, err := purego.Dlopen(getSystemLibrary(), purego.RTLD_NOW|purego.RTLD_GLOBAL)
86	if err != nil {
87		panic(err)
88	}
89	var puts func(string)
90	purego.RegisterLibFunc(&puts, libc, "puts")
91	puts("Calling C from Go without Cgo!")
92}
93```
94
95Then to run: `CGO_ENABLED=0 go run main.go`
96
97## Callback diagnostics
98
99Callback allocation diagnostics are disabled by default. When debugging callback slot
100exhaustion on Unix-like platforms, set `PUREGO_CALLBACK_LEDGER=1` to append JSONL
101callback lifecycle events to `/tmp/purego-callback-ledger-<pid>.jsonl`, or set
102`PUREGO_CALLBACK_LEDGER_FILE=/path/to/file.jsonl` to choose the output file. Stack
103capture is also disabled by default; set `PUREGO_CALLBACK_LEDGER_STACK=1` when call
104site attribution is needed. Stack capture adds per-callback overhead and should be
105reserved for active debugging sessions. For ad-hoc stderr/file traces near callback
106exhaustion, set `PUREGO_CALLBACK_TRACE=1`; `PUREGO_CALLBACK_TRACE_FILE` overrides
107the default `/tmp/purego-callback-trace-<pid>.log` path.
108
109Diagnostic files are created with `0o600` permissions. They are append-only and
110unbounded, so long-running processes can exhaust disk space if diagnostics stay
111enabled. A ledger line is a JSON object such as:
112
113```json
114{"time":"2026-06-09T14:03:00Z","pid":1234,"seq":42,"event":"alloc","index":7,"addr":"0x1234","stack":"..."}
115```
116
117Use `time` as the timestamp, `index` as the callback ID, and the `pid`, `seq`,
118`event`, `addr`, and optional `stack` fields when parsing the ledger output.
119
120## Questions
121
122If you have questions about how to incorporate purego in your project or want to discuss
123how it works join the [Discord](https://discord.gg/HzGZVD6BkY)!
124
125### External Code
126
127Purego uses code that originates from the Go runtime. These files are under the BSD-3
128License that can be found [in the Go Source](https://github.com/golang/go/blob/master/LICENSE).
129This is a list of the copied files:
130
131* `abi_*.h` from package `runtime/cgo`
132* `wincallback.go` from package `runtime`
133* `zcallback_darwin_*.s` from package `runtime`
134* `internal/fakecgo/abi_*.h` from package `runtime/cgo`
135* `internal/fakecgo/asm_GOARCH.s` from package `runtime/cgo`
136* `internal/fakecgo/callbacks.go` from package `runtime/cgo`
137* `internal/fakecgo/iscgo.go` from package `runtime/cgo`
138* `internal/fakecgo/setenv.go` from package `runtime/cgo`
139* `internal/fakecgo/freebsd.go` from package `runtime/cgo`
140* `internal/fakecgo/netbsd.go` from package `runtime/cgo`
141* `internal/fakecgo/linux.go` from package `runtime/cgo`
142
143The `internal/fakecgo/go_GOOS.go` files were modified from `runtime/cgo/gcc_GOOS_GOARCH.go`.
144The `internal/fakecgo/linux.go` file is a combination of `runtime/cgo/linux.go` and `runtime/cgo/linux_syscall.c`.
145
146The files `abi_*.h` and `internal/fakecgo/abi_*.h` are the same because Bazel does not support cross-package use of
147`#include` so we need each one once per package. (cf. [issue](https://github.com/bazelbuild/rules_go/issues/3636))

README.md RawHistoryFolder