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- **FreeBSD**: amd64, arm64
30- **Linux**: amd64, arm64
31- **macOS / iOS**: amd64, arm64
32- **Windows**: 386*, amd64, arm*, arm64
33
34`*` These architectures only support SyscallN and NewCallback
35
36## Example
37
38The example below only showcases purego use for macOS and Linux. The other platforms require special handling which can
39be seen in the complete example at [examples/libc](https://github.com/ebitengine/purego/tree/main/examples/libc) which supports Windows and FreeBSD.
40
41```go
42package main
43
44import (
45	"fmt"
46	"runtime"
47
48	"github.com/ebitengine/purego"
49)
50
51func getSystemLibrary() string {
52	switch runtime.GOOS {
53	case "darwin":
54		return "/usr/lib/libSystem.B.dylib"
55	case "linux":
56		return "libc.so.6"
57	default:
58		panic(fmt.Errorf("GOOS=%s is not supported", runtime.GOOS))
59	}
60}
61
62func main() {
63	libc, err := purego.Dlopen(getSystemLibrary(), purego.RTLD_NOW|purego.RTLD_GLOBAL)
64	if err != nil {
65		panic(err)
66	}
67	var puts func(string)
68	purego.RegisterLibFunc(&puts, libc, "puts")
69	puts("Calling C from Go without Cgo!")
70}
71```
72
73Then to run: `CGO_ENABLED=0 go run main.go`
74
75## Questions
76
77If you have questions about how to incorporate purego in your project or want to discuss
78how it works join the [Discord](https://discord.gg/HzGZVD6BkY)!
79
80### External Code
81
82Purego uses code that originates from the Go runtime. These files are under the BSD-3
83License that can be found [in the Go Source](https://github.com/golang/go/blob/master/LICENSE).
84This is a list of the copied files:
85
86* `abi_*.h` from package `runtime/cgo`
87* `zcallback_darwin_*.s` from package `runtime`
88* `internal/fakecgo/abi_*.h` from package `runtime/cgo`
89* `internal/fakecgo/asm_GOARCH.s` from package `runtime/cgo`
90* `internal/fakecgo/callbacks.go` from package `runtime/cgo`
91* `internal/fakecgo/go_GOOS_GOARCH.go` from package `runtime/cgo`
92* `internal/fakecgo/iscgo.go` from package `runtime/cgo`
93* `internal/fakecgo/setenv.go` from package `runtime/cgo`
94* `internal/fakecgo/freebsd.go` from package `runtime/cgo`
95
96The files `abi_*.h` and `internal/fakecgo/abi_*.h` are the same because Bazel does not support cross-package use of
97`#include` so we need each one once per package. (cf. [issue](https://github.com/bazelbuild/rules_go/issues/3636))