README
¶
cgo
Pure-Go FFI Library for Windows, Linux, and macOS - No CGO Required
Overview
cgo is a zero-c-dependency, pure-Go Foreign Function Interface (FFI) library that enables calling C shared libraries directly from Go code without requiring the CGO toolchain. Built on top of https://github.com/ebitengine/purego, it provides a unified API for Windows, Linux, and macOS with enhanced features for modern Go development.
And in addition, it adds support for struct parameters and return values on the Windows platform.
Features
- 🚫 No CGO - Eliminates cross-compilation complexities and C toolchain dependencies
- 🎯 Unified API - Consistent interface across all supported platforms
- 📦 Zero Dependencies - Pure Go implementation, only standard library + purego
- 🔍 Extern Variable Support - Read and write C
externglobal variables - 🚀 Fast Development - No recompilation needed when changing Go code
- 🏃 Cross-Platform Support: Windows (
dll), Linux (so), macOS (dylib)
Quick Start
Installation
go get github.com/goexlib/cgo
1. Basic Library Usage
package main
import (
"fmt"
"github.com/goexlib/cgo"
)
func main() {
// Load a shared library file
lib, err := cgo.LoadLibrary("path/to/library.file")
if err != nil {
panic(err)
}
defer lib.Close()
// Load a function symbol
sym, err := lib.GetSymbol("add")
if err != nil {
panic(err)
}
// Call the C function
result := cgo.CallRet[cgo.Int](sym.Addr(), cgo.Int(5), cgo.Int(3))
fmt.Printf("5 + 3 = %d\n", result)
}
2. Working with Extern Variables
package main
import (
"fmt"
"github.com/goexlib/cgo"
)
func main() {
lib, err := cgo.LoadLibrary("mylib")
if err != nil {
panic(err)
}
defer lib.Close()
// Access an extern integer variable
counter,err := cgo.GetExternVariant[cgo.Int](lib, "counter")
if err != nil {
panic(err)
}
fmt.Printf("Counter value: %d\n", *counter) // 0
fnIncrement, err := lib.GetSymbol("increment")
if err != nil {
panic(err)
}
cgo.Call(fnIncrement)
fmt.Printf("Counter value: %d\n", *counter) // 1
*counter = 999
cgo.Call(fnIncrement)
fmt.Printf("Counter value: %d\n", *counter) // 1000
}
3. Platform-Specific Code Paths
package main
import (
"runtime"
"github.com/goexlib/cgo"
)
func main() {
var libPath string
switch runtime.GOOS {
case "windows":
libPath = "C:\\libs\\mylib.dll"
case "darwin":
libPath = "/usr/local/lib/libmylib.dylib"
case "linux":
libPath = "/usr/lib/libmylib.so"
}
lib, err := cgo.LoadLibrary(libPath)
if err != nil {
panic(err)
}
defer lib.Close()
// Use library...
}
4. Callbacks with Float/Struct Return Values
cgo.NewCallback converts a Go function into a C function pointer. Unlike
purego.NewCallback (and syscall.NewCallback on Windows), it also supports
float32/float64 and struct return values, backed by this package's own
assembly thunks on linux/amd64, linux/arm64, darwin/amd64, darwin/arm64 and
windows/amd64. Signatures that the underlying backend already supports are
forwarded to it unchanged.
package main
import "github.com/goexlib/cgo"
type Point struct {
X, Y cgo.Float
}
func main() {
// A callback returning a struct (not possible with purego.NewCallback):
cb := cgo.NewCallback(func(x, y cgo.Float) Point {
return Point{X: x * 2, Y: y * 2}
})
// Pass cb to a C function expecting: Point (*)(float, float)
_ = cb
}
Supported callback signatures:
| integer/pointer/bool args | float args | float return | struct return | struct args | |
|---|---|---|---|---|---|
| linux/amd64, linux/arm64 | ✅ | ✅ | ✅ | ✅ | ❌ |
| darwin/amd64, darwin/arm64 | ✅ | ✅ | ✅ | ✅ | ❌ |
| windows/amd64 | ✅ | ✅ | ✅ | ✅ | ❌ |
| other purego platforms | ✅ | ✅ | ❌ | ❌ | ❌ |
Struct return types must have the same memory layout as the C struct (including padding). Homogeneous float aggregates, small structs in registers and large structs through the hidden result pointer all follow the platform C ABI (System V AMD64, AAPCS64 incl. Apple's stack packing, and the Microsoft x64 convention).
Platform-Specific Notes
Windows
- Searches in: application directory, system directories,
PATH - Supports both
stdcallandcdeclcalling conventions (X64 ABI)
Linux
- Respects
LD_LIBRARY_PATHenvironment variable
macOS
- Searges in:
@rpath,@executable_path, system directories - Supports framework bundles
License
This project is licensed under the MIT License
Documentation
¶
Index ¶
- Constants
- func CBool(b bool) int8
- func CSlice[S ~[]E, E any](s S) unsafe.Pointer
- func CString(s string) unsafe.Pointer
- func Call[F ~uintptr](fn F, args ...any)
- func CallRaw(fn uintptr, args ...uintptr) (r1, r2 uintptr, err syscall.Errno)
- func CallRet[T any, F ~uintptr](fn F, args ...any) (ret T)
- func Dlclose(handle uintptr) error
- func Dlopen(path string, mode int) (uintptr, error)
- func Dlsym(handle uintptr, name string) (uintptr, error)
- func Free(p Pointer)
- func GetExternVariant[T any, L ~uintptr](lib L, name string) (pv *T, err error)
- func GoBool[T comparable](v T) bool
- func GoPointer[T any](p uintptr) *T
- func GoSlice[T comparable](p unsafe.Pointer) []T
- func GoSliceN[T any](p unsafe.Pointer, n int) []T
- func GoSliceNTemp[T any](p unsafe.Pointer, n int) []T
- func GoSliceTemp[T comparable](p unsafe.Pointer) []T
- func GoString(s unsafe.Pointer) string
- func GoStringN(s unsafe.Pointer, n int) string
- func GoStringNTemp(s unsafe.Pointer, n int) string
- func GoStringTemp(s unsafe.Pointer) string
- func Length[T comparable](p unsafe.Pointer) (n int)
- func Memcpy(dst, src Pointer, size Sizet)
- func Memset(p Pointer, val int, size Sizet)
- func NewCallback(fn any) uintptr
- func RegisterFunc(pf any, cfn uintptr) (err error)
- func RegisterLibFunc(pf any, lib uintptr, symbol string) (err error)
- func Strlen(s unsafe.Pointer) (n int)
- type Char
- type Double
- type Float
- type Int
- type Intptr
- type LazyLibrary
- type LazySymbol
- type Library
- type Long
- type LongLong
- type Pointer
- type Short
- type Sizet
- type Ssize
- type Symbol
- type Uchar
- type Uint
- type Uintptr
- type Ulong
- type UlongLong
- type Ushort
Constants ¶
const ( RTLD_DEFAULT = purego.RTLD_DEFAULT RTLD_LAZY = purego.RTLD_LAZY RTLD_NOW = purego.RTLD_NOW RTLD_LOCAL = purego.RTLD_LOCAL RTLD_GLOBAL = purego.RTLD_GLOBAL )
Variables ¶
This section is empty.
Functions ¶
func Dlopen ¶
Dlopen examines the dynamic library or bundle file specified by path.
The mode was ignored on Windows.
func GetExternVariant ¶
func GoBool ¶
func GoBool[T comparable](v T) bool
func GoSlice ¶
func GoSlice[T comparable](p unsafe.Pointer) []T
func GoSliceTemp ¶
func GoSliceTemp[T comparable](p unsafe.Pointer) []T
func GoStringTemp ¶
func Length ¶
func Length[T comparable](p unsafe.Pointer) (n int)
Length Get the length of an array ending with zero
func NewCallback ¶
NewCallback converts a Go function to a C function pointer that can be passed to C code as a callback.
On linux/amd64, linux/arm64, darwin/amd64 and darwin/arm64 it additionally supports float32/float64 and struct return values (which purego.NewCallback does not): such callbacks are backed by this package's own assembly thunk, everything else is forwarded to purego.NewCallback. Struct arguments are not supported. Struct return types must have the same memory layout as their C counterpart (add explicit padding fields if needed).
Only a limited number of callbacks may be created in a single Go process, and any memory allocated for these callbacks is never released.
func RegisterFunc ¶
Types ¶
type LazyLibrary ¶
type LazyLibrary struct {
// contains filtered or unexported fields
}
func NewLazyLibrary ¶
func NewLazyLibrary(name string, fallbacks ...string) (l *LazyLibrary)
func (*LazyLibrary) Handle ¶ added in v0.0.3
func (l *LazyLibrary) Handle() uintptr
func (*LazyLibrary) Load ¶
func (l *LazyLibrary) Load() error
func (*LazyLibrary) NewSymbol ¶
func (l *LazyLibrary) NewSymbol(name string) *LazySymbol
type LazySymbol ¶
type LazySymbol struct {
// contains filtered or unexported fields
}
func (*LazySymbol) Addr ¶
func (s *LazySymbol) Addr() uintptr
func (*LazySymbol) CallRaw ¶
func (s *LazySymbol) CallRaw(args ...uintptr) (r1, r2 uintptr, err error)
func (*LazySymbol) Find ¶
func (s *LazySymbol) Find() error
Source Files
Directories