heil

The Zig package manager.
_{Hermetic Efficiency Interference Layer — Über alles.}

Unapologetic · Opinionated · Familiar · Efficient

Officially supports Zig 0.16+ and sig

---

Quick Start

# Install heil (or build from source — see Contributing)
heil --version

# Scaffold a new project
heil init --template cli-app --name my-app
cd my-app

# Install packages
heil i @heil/core @heil/json

# Build and run
heil run

---

Commands

Command	Alias	Description
heil init		Scaffold a new project from a template
heil install <pkg...>	i	Install packages and resolve dependencies
heil uninstall <pkg...>	rm	Remove packages and orphaned transitive deps
heil list	ls	List installed heil packages
heil search <query>		Search the registry for packages
heil publish	pub	Publish a package to the registry
heil validate	val	Validate heil.pkg.zon before publishing
heil update [pkg...]	up	Update packages to latest versions
heil doctor		Check environment health
heil run [args...]		Build and run via zig build run
heil build [args...]		Build via zig build

Global Flags

Flag	Short	Description
--verbose	-v	Detailed output
--quiet	-q	Suppress non-error output
--offline		No network requests
--registry <url>		Override registry URL
--transport quic		Use QUIC transport for registry ops
--help	-h	Show help
--version	-V	Show version

---

Templates

heil init --template <name> --name <project>

Template	Description
empty	Minimal Zig project (default)
cli-app	Cross-platform CLI with argument parsing
web-server	Zig HTTP server project
gui-app	Platform-abstracted window + GL rendering
library	Reusable Zig module with src/root.zig and tests
package	Library + heil.pkg.zon manifest for publishing
window	Native window creation with OpenGL context
gl-app	OpenGL application with render loop
trading	Trading application scaffold

---

Architecture

Four layers, strictly ordered — lower layers never import from higher layers.

Layer 2: Render      Drawing primitives, text, icons (color, primitives, text, icon)
Layer 1: Transport   QUIC stack — RFC 9000/9001/9002/9221 (conn, streams, packet, ...)
Layer 1: Platform    OS bindings, system services (win32, gl, window, http, crypto, ...)
Layer 0: Core        Pure data types, math, logic — no platform deps (core, math, json)

Principles

• No hidden allocations — all storage is stack or comptime-sized
• No implicit work — every cost is visible
• No standard library I/O at runtime — pure platform-native extern calls
• Explicit over convenient
• Zero-cost abstractions only

---

QUIC Transport

heil includes a full QUIC implementation (RFC 9000, 9001, 9002, 9221) for high-performance registry access. Enable with --transport quic.

Three application lanes map to QUIC primitives:

Lane	QUIC Primitive	Semantics	Use Cases
Control	Bidirectional stream 0	Reliable, ordered	Resolve, publish, search, auth
Bulk	Bidirectional streams 4+	Reliable, parallel	Tarball download
Hot	DATAGRAM frames	Unreliable, latest-wins	Invalidation, version announcements

const conn = @import("conn");
const appmap = @import("appmap");

var connection = conn.Connection.initClient(server_addr);
var app = appmap.AppMap.init(&connection.stream_mgr, &connection.dgram_handler);
app.sendResolveRequest(scope, name, version);

---

Official @heil/ Packages

34 packages derived from the existing heil module library.

Layer 0 — Core

Package	Description
@heil/core	Core data types, storage, and logic
@heil/math	Sin/cos approximations, lerp, interpolation, pure math
@heil/json	Minimal JSON parser

Layer 1 — Platform

Package	Description
@heil/win32	Hand-written Win32 type/constant/extern bindings
@heil/gl	OpenGL 1.x constants and function externs
@heil/window	Borderless window creation and management
@heil/timer	High-precision timer
@heil/seqlock	Sequence lock for lock-free concurrent reads
@heil/http	HTTP client
@heil/crypto	HMAC-SHA256 cryptographic operations
@heil/file-io	File I/O operations
@heil/threading	Thread pool and worker management
@heil/logging	Logging subsystem
@heil/input	Keyboard and mouse input handling
@heil/png	PNG encoder with deflate compression
@heil/screenshot	GL framebuffer capture
@heil/mcp	Embedded MCP server
@heil/platform	Coarse-grained re-export of all platform subsystems

Layer 1 — Transport

Package	Description
@heil/udp	UDP socket I/O (non-blocking send/receive)
@heil/packet	QUIC packet parsing and serialization (RFC 9000)
@heil/transport-crypto	TLS 1.3 integration and packet protection (RFC 9001)
@heil/recovery	Loss detection and congestion control (RFC 9002, NewReno)
@heil/streams	Stream management with flow control
@heil/datagram	DATAGRAM frame handling (RFC 9221)
@heil/telemetry	Per-connection counters and diagnostics
@heil/scheduler	Packet assembly and pacing
@heil/conn	QUIC connection state machine
@heil/appmap	Application protocol mapping (registry ops to QUIC lanes)
@heil/transport	Coarse-grained re-export of all transport sub-modules

Layer 2 — Render

Package	Description
@heil/color	Color types and constants
@heil/primitives	GL immediate-mode drawing: rect, line, candle, glow
@heil/text	Bitmap font rasterization
@heil/icon	ICO file loading to GL texture
@heil/render	Coarse-grained re-export of all render subsystems

---

Contributing

See CONTRIBUTING.md for build instructions, code style, and PR process.

# Build from source
cd heil/cli
zig build

# Run all tests
zig build test --summary all

# Run root-level tests (transport, core, platform)
cd heil
zig build test --summary all

---

Every byte accounted for. Every cycle earned.

Discord · Ko-fi · GitHub