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...
}
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 GetExternVariant[T any, L ~uintptr](lib L, name string) (pv *T, err error)
- func GoBool[T comparable](v T) bool
- 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 unsafe.Pointer, size uintptr)
- func Memset(p unsafe.Pointer, val byte, size uintptr)
- 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 ¶
View Source
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 ¶
func RegisterFunc ¶
Types ¶
type LazyLibrary ¶
type LazyLibrary struct {
// contains filtered or unexported fields
}
func NewLazyLibrary ¶
func NewLazyLibrary(name string) *LazyLibrary
func (*LazyLibrary) Handle ¶ added in v0.0.3
func (l *LazyLibrary) Handle() (handle uintptr, err error)
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() (addr uintptr, err error)
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
Click to show internal directories.
Click to hide internal directories.