1# purego
2[![Go Reference](https://pkg.go.dev/badge/github.com/ebitengine/purego?GOOS=darwin.svg)](https://pkg.go.dev/github.com/ebitengine/purego?GOOS=darwin)
3
4A library for calling C functions from Go without Cgo.
5
6> This is beta software so expect bugs and potentially API breaking changes
7> but each release will be tagged to avoid breaking people's code.
8> Bug reports are encouraged.
9
10## Motivation
11
12The [Ebitengine](https://github.com/hajimehoshi/ebiten) game engine was ported to use only Go on Windows. This enabled
13cross-compiling to Windows from any other operating system simply by setting `GOOS=windows`. The purego project was
14born to bring that same vision to the other platforms supported by Ebitengine.
15
16## Benefits
17
18- **Simple Cross-Compilation**: No C means you can build for other platforms easily without a C compiler.
19- **Faster Compilation**: Efficiently cache your entirely Go builds.
20- **Smaller Binaries**: Using Cgo generates a C wrapper function for each C function called. Purego doesn't!
21- **Dynamic Linking**: Load symbols at runtime and use it as a plugin system.
22- **Foreign Function Interface**: Call into other languages that are compiled into shared objects.
23- **Cgo Fallback**: Works even with CGO_ENABLED=1 so incremental porting is possible. 
24This also means unsupported GOARCHs (freebsd/riscv64, linux/mips, etc.) will still work
25except for float arguments and return values.
26
27## Supported Platforms
28
29### Tier 1
30
31Tier 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.
32
33- **Android**: amd64<sup>1</sup>, arm64<sup>1</sup>
34- **iOS**: amd64<sup>1</sup>, arm64<sup>1</sup>
35- **Linux**: amd64, arm64
36- **macOS**: amd64, arm64
37- **Windows**: amd64<sup>2</sup>, arm64<sup>2</sup>
38
39### Tier 2
40
41Tier 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.
42
43- **Android**: 386<sup>1,3</sup>, arm<sup>1,3</sup>
44- **FreeBSD**: amd64<sup>3,4</sup>, arm64<sup>3,4</sup>
45- **Linux**: 386<sup>3</sup>, arm<sup>3</sup>, loong64<sup>2</sup>, ppc64le<sup>2</sup>, riscv64<sup>3</sup>, s390x<sup>3, 5</sup>
46- **NetBSD**: amd64<sup>3,4</sup>, arm64<sup>3,4</sup>
47- **Windows**: 386<sup>3,6</sup>, arm<sup>3,6,7</sup>
48
49#### Support Notes
50
511. These architectures require CGO_ENABLED=1 to compile
522. These architectures support passing structs by value as arguments and return values when calling C functions, but not in callbacks created with `NewCallback`
533. These architectures do not support passing structs by value as arguments or return values
544. These architectures require the special flag `-gcflags="github.com/ebitengine/purego/internal/fakecgo=-std"` to compile with CGO_ENABLED=0
555. These architectures require CGO_ENABLED=1 to compile in versions before Go 1.27, but will be supported without Cgo in Go 1.27 and later
566. These architectures only support `SyscallN` and `NewCallback`
577. These architectures are no longer supported as of Go 1.26
58
59## Example
60
61The example below only showcases purego use for macOS and Linux. The other platforms require special handling which can
62be seen in the complete example at [examples/libc](https://github.com/ebitengine/purego/tree/main/examples/libc) which supports FreeBSD and Windows.
63
64```go
65package main
66
67import (
68	"fmt"
69	"runtime"
70
71	"github.com/ebitengine/purego"
72)
73
74func getSystemLibrary() string {
75	switch runtime.GOOS {
76	case "darwin":
77		return "/usr/lib/libSystem.B.dylib"
78	case "linux":
79		return "libc.so.6"
80	default:
81		panic(fmt.Errorf("GOOS=%s is not supported", runtime.GOOS))
82	}
83}
84
85func main() {
86	libc, err := purego.Dlopen(getSystemLibrary(), purego.RTLD_NOW|purego.RTLD_GLOBAL)
87	if err != nil {
88		panic(err)
89	}
90	var puts func(string)
91	purego.RegisterLibFunc(&puts, libc, "puts")
92	puts("Calling C from Go without Cgo!")
93}
94```
95
96Then to run: `CGO_ENABLED=0 go run main.go`
97
98## Questions
99
100If you have questions about how to incorporate purego in your project or want to discuss
101how it works join the [Discord](https://discord.gg/HzGZVD6BkY)!
102
103### External Code
104
105Purego uses code that originates from the Go runtime. These files are under the BSD-3
106License that can be found [in the Go Source](https://github.com/golang/go/blob/master/LICENSE).
107This is a list of the copied files:
108
109* `abi_*.h` from package `runtime/cgo`
110* `wincallback.go` from package `runtime`
111* `internal/fakecgo/abi_*.h` from package `runtime/cgo`
112* `internal/fakecgo/asm_GOARCH.s` from package `runtime/cgo`
113* `internal/fakecgo/callbacks.go` from package `runtime/cgo`
114* `internal/fakecgo/iscgo.go` from package `runtime/cgo`
115* `internal/fakecgo/setenv.go` from package `runtime/cgo`
116* `internal/fakecgo/freebsd.go` from package `runtime/cgo`
117* `internal/fakecgo/netbsd.go` from package `runtime/cgo`
118* `internal/fakecgo/linux.go` from package `runtime/cgo`
119
120The `internal/fakecgo/go_GOOS.go` files were modified from `runtime/cgo/gcc_GOOS_GOARCH.go`.
121The `internal/fakecgo/linux.go` file is a combination of `runtime/cgo/linux.go` and `runtime/cgo/linux_syscall.c`.
122
123The files `abi_*.h` and `internal/fakecgo/abi_*.h` are the same because Bazel does not support cross-package use of
124`#include` so we need each one once per package. (cf. [issue](https://github.com/bazelbuild/rules_go/issues/3636))