# zig

notes on [zig](https://ziglang.org/) patterns. organized by topic — version-specific
migration notes live in [versions/](./versions/), everything else is idiom notes
annotated with the release they were learned on.

## issue tracking

zig moved from github to codeberg. old issues (≤25xxx) are on github, new issues
(30xxx+) are on codeberg.org/ziglang/zig.

```bash
curl -s "https://codeberg.org/api/v1/repos/ziglang/zig/issues?state=all&q=flate"
```

## stdlib + language idioms

- [arraylist](./arraylist.md) - ownership patterns (toOwnedSlice vs deinit)
- [binary](./binary.md) - encoding/decoding wire formats (CBOR, CAR, varints, arenas)
- [comptime](./comptime.md) - type generation, tuple synthesis, string validation, anytype adapters, comptime-sql escape hatches
- [concurrency](./concurrency.md) - atomics vs mutex, callback pattern, ring buffers (threads; for std.Io-based concurrency see [io/](./io/))
- [crypto](./crypto.md) - ecdsa paths, signature verification
- [database](./database.md) - zqlite, connection patterns, transactions
- [hashmap](./hashmap.md) - StringHashMap, O(1) block index, managed vs unmanaged
- [interfaces](./interfaces.md) - comptime duck typing, type-returning functions, vtables
- [json](./json.md) - Stringify with writers, parse with arenas
- [modules](./modules.md) - file + directory pattern (foo.zig + foo/)
- [structs](./structs.md) - copy semantics, internal storage for strings
- [testing](./testing.md) - silent test discovery loss, multi-module test targets, comptime-folding, leaky apis
- [text](./text.md) - `[]const u8` is bytes: character vs byte vocabularies, std.unicode, where classification stops

## std.Io (0.16+)

- [io/](./io/) — the std.Io interface: everything that can block moves through it
  - [README](./io/README.md) — overview, backends, design philosophy
  - [concurrency](./io/concurrency.md) — async vs concurrent, Future, Group, Select, Queue
  - [synchronization](./io/synchronization.md) — Mutex, Condition, CancelProtection, cancellation model
  - [patterns](./io/patterns.md) — backend selection, InitOptions, debug_io, long-lived tasks, networking
- [fibers](./io/fibers.md) — building stackful fibers: the ReleaseSafe clobber bugs (LLVM drops `~{x30}`, x18 missing on linux) proven by IR-vs-disasm, mmap vs guard-page stacks, why blocking work must not go on fibers, testing on the arch you deploy to

## project lessons

- [cli](./cli.md) — building a terminal CLI: stdout/stderr split, broken-pipe handling, pager/browser via process.spawn
- [logging](./logging.md) — `std.log`, `std.options.logFn`, OTEL bridges, why direct-emit APIs are an anti-pattern
- [libuv-process-lifetimes](./libuv-process-lifetimes.md) — initialized-on-error handles and close callbacks at a Zig/C boundary
- [atomic-rate-meter](./atomic-rate-meter.md) — "current rate of X" with a lock-free hot path + shared sampler thread
- [per-command-arena](./per-command-arena.md) — protocol-client lifetime trick: arena reset per command
- [page-allocator-granularity](./page-allocator-granularity.md) — small-alloc leak amplification through page_allocator
- [ziglua-ffi](./ziglua-ffi.md) — embedding Lua 5.1 via ziglua, the `redis.call` upvalue pattern

## subsystems

- [build/](./build/) - build system patterns from large projects (basics, organization, dependencies, codegen, cross-compilation, distribution)
- [websocket/](./websocket/) - the first-party websocket.zig fork, its API divergence from upstream
- [versions/](./versions/) - release-keyed migration notes (0.15 fmt/io overhauls, 0.16 migration)

## sources

patterns derived from building and studying:

| project | what it is |
|---------|------------|
| [music-atmosphere-feed](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed) | bluesky feed generator |
| [find-bufo](https://tangled.sh/@zzstoatzz.io/find-bufo) | bluesky bot |
| [pub-search](https://tangled.sh/@zzstoatzz.io/pub-search) | fts search backend |
| [pollz](https://tangled.sh/@zzstoatzz.io/pollz) | bluesky polls (zqlite + transactions) |
| [zql](https://tangled.sh/@zzstoatzz.io/zql) | comptime sql parsing |
| [zat](https://tangled.sh/@zzstoatzz.io/zat) | atproto primitives (jwt, crypto, CBOR, firehose) |
| [k256](https://tangled.sh/@zzstoatzz.io/k256) | optimized secp256k1 ECDSA (5×52-bit field, GLV endomorphism) |
| [atproto-bench](https://tangled.sh/@zzstoatzz.io/atproto-bench) | three-way AT Protocol benchmarks (zig vs Go vs Rust) |
| [zuvloop](https://github.com/zzstoatzz/zuvloop) | asyncio event loop backed by Zig + libuv |
| [logfire-zig](https://tangled.sh/@zzstoatzz.io/logfire-zig) | OTLP observability client |
| [prefect-zig](https://tangled.sh/@zzstoatzz.io/prefect-zig) | prefect orchestration server |
| [zigman](https://tangled.org/zzstoatzz.io/zigman) | terminal reader for the zig langref |
| [ghostty](https://github.com/ghostty-org/ghostty) | terminal emulator (build system) |
| [bun](https://github.com/oven-sh/bun) | javascript runtime (build system) |

## libraries

- [websocket.zig](https://tangled.org/zzstoatzz.io/websocket.zig) - first-party fork of [karlseguin/websocket.zig](https://github.com/karlseguin/websocket.zig), tracked for 0.16 — see [websocket/](./websocket/)
- [zqlite.zig](https://github.com/karlseguin/zqlite.zig) - sqlite wrapper