GoFre 🧇

A build system for creating Python packages with Go extensions, inspired by maturin for Rust/Python.

Features

• Pure Go: No CGo required, thanks to purego
• cffi Bindings: Fast, type-safe Python bindings
• Cross-Platform: Linux, macOS, Windows support
• PEP 517 Compliant: Standard Python packaging
• Binary Bundling: Include Go binaries in your Python packages

Installation

go install github.com/grackin/gofre@latest

Or build from source:

git clone https://github.com/grackin/gofre
cd gofre
go build -o gofre .

Quick Start

Create a new project

gofre new my-package
cd my-package

Write Go code

// pkg/core/core.go
package core

//export Add
func Add(a, b int64) int64 {
    return a + b
}

//export Multiply
func Multiply(a, b int64) int64 {
    return a * b
}

Build and install

gofre develop

Use in Python

import my_package

result = my_package.Add(2, 3)
print(result)  # 5

Commands

Benchmarks

GoFre provides significant performance improvements over pure Python by leveraging Go's performance.

Note: The overhead of FFI calls means that very simple operations (like sum()) may not benefit from Go extensions. GoFre shines for complex computational workloads.

fibonacci(30) - Recursive Implementation

count_primes(100,000)

matrix_multiply(50x50)

Real-World Benchmarks

Based on programming-language-benchmarks:

Webserver Benchmarks

GoFre also benchmarks HTTP server performance across six approaches — from pure Python to Go with embedded pocketpy. See the full results and methodology.

Quick Summary

Go + pocketpy delivers ~5-6x the throughput of FastAPI/Flask while keeping memory under 22 MB peak in a single 9.7 MB binary. See examples/webserver/README.md for full details.

Project Structure

gofre/
├── main.go
├── go.mod
├── cmd/                    # CLI commands
├── internal/               # Library code
│   ├── bindings/           # Go parser + Python code generator
│   ├── build/              # Build system (Go + wheel)
│   ├── config/             # Config loader (pyproject.toml)
│   ├── pocketpy/           # Embedded pocketpy interpreter (excluded with no_pocketpy tag)
│   └── gomod/              # Bridge modules (http, json)
└── tests/                  # Unit tests

User Project Structure

my-package/
├── pyproject.toml
├── go.mod
├── pkg/
│   └── core/
│       └── core.go         # Go code with //export functions
└── cmd/
    └── main.go             # CGo bridge

Build artifacts go to build/ and dist/ by default. Use --output-dir to put them elsewhere.

How It Works

1. Parse: GoFre parses your Go source files to find exported functions
2. Build: Compiles Go code to a shared library (.so, .dylib, .dll)
3. Generate: Creates cffi bindings for Python
4. Package: Builds a wheel with the shared library and Python wrappers

Cross-Compilation

# Build for Linux from macOS
GOOS=linux GOARCH=amd64 gofre build

# Build for Windows from macOS
GOOS=windows GOARCH=amd64 gofre build

# Build for macOS arm64 from Intel
GOOS=darwin GOARCH=arm64 gofre build

Platform Support

Configuration

pyproject.toml

[build-system]
requires = ["gofre>=0.1.0"]
build-backend = "gofre.build"

[project]
name = "my-package"
version = "0.1.0"
requires-python = ">=3.8"
dependencies = ["cffi>=1.0.0"]

[tool.gofre]
module = "github.com/user/my-package"
bindings = "cffi"
pkg-dir = "pkg"
build-tags = []

Build Tags

Use build-tags to pass custom Go build tags to go build. This is useful for excluding parts of the codebase from compilation.

[tool.gofre]
module = "github.com/user/my-package"
build-tags = ["no_pocketpy"]

This produces:

go build -buildmode=c-shared -tags no_pocketpy -o output ./cmd/

GoFre ships with the no_pocketpy build tag, which excludes the embedded pocketpy interpreter and related bridge code. Files excluded by build tags:

• internal/pocketpy/* — pocketpy Go wrapper and C source
• internal/gomod/http/register.go — pocketpy HTTP bridge
• internal/gomod/json/register.go — pocketpy JSON bridge
• examples/webserver_binary/ — pocketpy-based webserver example

When no_pocketpy is set, the cffi exports in http/cffi_exports.go and json/cffi_exports.go remain available. If your cmd/ imports pocketpy directly, the build will fail with a missing import error.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License

Acknowledgments

• maturin - Inspiration for the build system
• purego - CGo-free C function calls
• cffi - Python FFI
• programming-language-benchmarks - Benchmark data