xonecas.io
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)