60255
Zn
Zoea-Nova / files
Zoea-Nova / documentation / guides / GO_COMPILATION.md
3.0 KB
1# Go Compilation Without CGO 2 3Zoea Nova is built as a pure Go application with `CGO_ENABLED=0`. This document explains the benefits and implications of this architectural decision. 4 5## Why Pure Go? 6 7### Compilation Speed 8 9CGO significantly slows down Go compilation: 10 11- **CGO enabled**: Sequential compilation, C compiler overhead, 2-10x slower builds 12- **Pure Go**: Parallel compilation, fast incremental builds, near-instant for small changes 13 14```bash 15# Benchmark the difference 16time CGO_ENABLED=1 go build ./cmd/zoea # Slower 17time CGO_ENABLED=0 go build ./cmd/zoea # Faster (default) 18time go build ./cmd/zoea # Same as CGO_ENABLED=0 19``` 20 21### Build Simplicity 22 23Pure Go eliminates external dependencies: 24 25- No C compiler toolchain required (gcc/clang) 26- Single static binary output 27- Reproducible builds across environments 28- Trivial cross-compilation: 29 30```bash 31# Cross-compile for Linux from any platform 32GOOS=linux GOARCH=amd64 go build ./cmd/zoea 33 34# Cross-compile for macOS ARM 35GOOS=darwin GOARCH=arm64 go build ./cmd/zoea 36 37# Cross-compile for Windows 38GOOS=windows GOARCH=amd64 go build ./cmd/zoea 39``` 40 41### Runtime Performance 42 43- No overhead crossing Go/C boundary 44- Better garbage collector coordination 45- Simpler memory management 46 47## Pure Go Dependencies 48 49Zoea Nova's stack is entirely CGO-free: 50 51| Component | Package | Notes | 52|-----------|---------|-------| 53| SQLite | `modernc.org/sqlite` | Pure Go SQLite implementation | 54| HTTP/JSON | Standard library | Native Go | 55| TUI | Bubble Tea ecosystem | Pure Go | 56| LLM clients | `go-openai` | Pure Go | 57| Logging | `zerolog` | Pure Go | 58| Configuration | `github.com/BurntSushi/toml` | Pure Go | 59 60## When CGO Is Required 61 62CGO is only necessary when: 63 641. **Linking against C libraries** - Proprietary SDKs with only C bindings 652. **Calling C functions directly** - Hardware drivers, legacy code 663. **Using CGO-dependent packages** - Some older database drivers (e.g., `mattn/go-sqlite3`) 67 68## Historical Context 69 70Previous versions of Zoea Nova may have used BAML (BoundaryML's AI function framework), which required CGO. Removing BAML eliminated this requirement and significantly improved build times. 71 72## Verification 73 74Check if a package requires CGO: 75 76```bash 77# List all dependencies 78go list -deps ./cmd/zoea 79 80# Check for CGO usage 81go list -f '{{if .CgoFiles}}{{.ImportPath}}: {{.CgoFiles}}{{end}}' ./... 82 83# Verify pure Go build 84CGO_ENABLED=0 go build ./cmd/zoea # Should succeed 85``` 86 87If the build fails with `CGO_ENABLED=0`, a dependency requires CGO. 88 89## Build Configuration 90 91The `Makefile` explicitly disables CGO: 92 93```makefile 94build: 95 CGO_ENABLED=0 go build -o bin/zoea ./cmd/zoea 96``` 97 98This ensures: 99- Consistent builds across environments 100- No accidental CGO dependencies 101- Fast compilation times 102- Easy cross-compilation 103 104## References 105 106- [Go CGO Documentation](https://pkg.go.dev/cmd/cgo) 107- [modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite) - Pure Go SQLite 108- [Cross-compilation Guide](https://go.dev/doc/install/source#environment)