# Turbo Build

> Build the TurboAPI Zig native backend. Use when the turbonet extension needs to be recompiled, after changing Zig source files, or when seeing "Native core not available".

- Skill: `justrach/turbo-build` (Agent Skill)
- Install (CLI): `npx skillmds@latest add justrach/turbo-build`
- Raw SKILL.md: https://api.skillmd.com/api/skills/justrach/turbo-build/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: justrach (https://skillmd.com/u/justrach)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/justrach/turbo-build

---


# Build TurboAPI Zig Backend

## Steps

1. **Build turbonet**:

```bash
uv run --python 3.14t python zig/build_turbonet.py --install $ARGUMENTS
```

2. **Verify the build**:

```bash
uv run --python 3.14t python -c "from turboapi import turbonet; print(turbonet.hello())"
```

## Dependencies (auto-fetched via build.zig.zon)

- **dhi** (justrach/dhi) — Zig-native JSON validation
- **pg.zig** (justrach/pg.zig) — Zig-native Postgres client with SIMD + pgvector

## Common issues

- **"Native core not available"**: Rebuild with the command above
- **dhi hash mismatch**: `cd zig && zig fetch --save "https://github.com/justrach/dhi/archive/refs/heads/main.tar.gz"`
- **pg.zig hash mismatch**: `cd zig && zig fetch --save "git+https://github.com/justrach/pg.zig#master"`
- **Missing Python 3.14t**: `uv python install 3.14t`
- **Missing Zig 0.15+**: `brew install zig` or download from ziglang.org

## Build modes

- `--install`: Copy .so into `python/turboapi/` (required for dev)
- `--release`: ReleaseFast optimizations (for benchmarks/production)
- No flags: Compile check only

## What gets built

Output: `python/turboapi/turbonet.{suffix}.so` containing:
- HTTP server (server.zig) — 24-thread pool, keep-alive, CORS
- Router (router.zig) — radix trie with path params + wildcards
- dhi validator (dhi_validator.zig) — pre-GIL JSON validation
- DB layer (db.zig) — pg.zig pool, cache, prepared statements
- pg.zig fork — SIMD JSON escaping, pgvector, writeJsonRow