cgo-bindings
cgo conventions for linking Go to a C or Rust static library: import "C" directives, type/string conversion, CString memory management, thread safety, and Go pointer pinning. Load when generating or r
SKILL.mdinternal/builtins/bindings/cgo/skills/cgo-bindings/SKILL.md
GitHub- Use
import "C"with// #cgo LDFLAGS:and// #cgo CFLAGS:directives for linking. - Declare C header functions in comment block immediately above
import "C"— no blank line between. - Type mapping:
C.int,C.long,C.char. UseC.CString()andC.GoString()for string conversion. - Memory:
C.CString()allocates — alwaysdefer C.free(unsafe.Pointer(cStr))immediately after creation. - Error handling: return error codes from C functions, convert to Go
errorvalues. Check all return values. - Link Rust static libraries:
// #cgo LDFLAGS: -L./target/release -lmylib. Build Rust withcrate-type = ["staticlib"]. - Thread safety: C functions called from Go may run on any OS thread. Use
runtime.LockOSThread()when needed. - Go pointer passing: use
runtime.Pinner(Go 1.21+) to pin Go memory passed to C. Never pass Go pointers without pinning. - Test with
go test(requiresCGO_ENABLED=1). Mock C layer for unit tests, use integration tests for real FFI. - Build:
CGO_ENABLED=1 go build. Cross-compilation requires appropriate C toolchain. - Anti-patterns: leaking
C.CStringmemory, passing unpinned Go pointers to C, ignoring C return codes.