Repository files navigation

A library for calling C functions from Go without Cgo.

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

TheEbitengine game engine was ported to use only Go on Windows. This enabledcross-compiling to Windows from any other operating system simply by settingGOOS=windows. The purego project wasborn to bring that same vision to the other platforms supported by Ebitengine.

• 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 workexcept for float arguments and return values.

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: amd64¹, arm64¹
• iOS: amd64¹, arm64¹
• Linux: amd64, arm64
• macOS: amd64, arm64
• Windows: amd64, arm64

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: 386¹, arm¹
• FreeBSD: amd64², arm64²
• Linux: 386, arm, loong64, ppc64le, riscv64, s390x¹
• Windows: 386³, arm^3,4

1. These architectures require CGO_ENABLED=1 to compile
2. These architectures require the special flag-gcflags="github.com/ebitengine/purego/internal/fakecgo=-std" to compile with CGO_ENABLED=0
3. These architectures only supportSyscallN andNewCallback
4. These architectures are no longer supported as of Go 1.26

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

package mainimport ("fmt""runtime""github.com/ebitengine/purego")funcgetSystemLibrary()string {switchruntime.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))}}funcmain() {libc,err:=purego.Dlopen(getSystemLibrary(),purego.RTLD_NOW|purego.RTLD_GLOBAL)iferr!=nil {panic(err)}varputsfunc(string)purego.RegisterLibFunc(&puts,libc,"puts")puts("Calling C from Go without Cgo!")}

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

If you have questions about how to incorporate purego in your project or want to discusshow it works join theDiscord!

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

• abi_*.h from packageruntime/cgo
• wincallback.go from packageruntime
• zcallback_darwin_*.s from packageruntime
• internal/fakecgo/abi_*.h from packageruntime/cgo
• internal/fakecgo/asm_GOARCH.s from packageruntime/cgo
• internal/fakecgo/callbacks.go from packageruntime/cgo
• internal/fakecgo/iscgo.go from packageruntime/cgo
• internal/fakecgo/setenv.go from packageruntime/cgo
• internal/fakecgo/freebsd.go from packageruntime/cgo
• internal/fakecgo/netbsd.go from packageruntime/cgo

Theinternal/fakecgo/go_GOOS.go files were modified fromruntime/cgo/gcc_GOOS_GOARCH.go.

The filesabi_*.h andinternal/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)