Skip to content

docs: normalize optimization profile terminology #241

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
VelariumAI wants to merge 1 commit into
base: main
Choose a base branch
from
+28 −12
Open

docs: normalize optimization profile terminology #241

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
docs: normalize optimization profile terminology
  • Loading branch information
@VelariumAI
VelariumAI committed May 23, 2026
commit e503a0caecc9ef841244809dcee3b644954004e1
40 changes: 28 additions & 12 deletions docs/articles/optimization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,33 @@
## Optimization And Size Profiles
## Build profiles

Zero profiles are product contracts, not hidden compiler moods. Build and size
JSON expose the selected profile so CI and agents can explain why bytes were
retained.
Zero exposes six catalog profiles:

Common profile choices:

| Profile | Use when | Contract |
| Profile | Profile key | Purpose |
| --- | --- | --- |
| `debug` | You need diagnostics and local symbols. | Checked traps, diagnostic panic path, debug metadata retained. |
| `fast` | Throughput matters more than minimum size. | Direct codegen optimizes for speed while keeping checked safety boundaries. |
| `small` | This is the default release profile. | Pay-as-used helpers, stripped unrequested metadata, deterministic artifacts. |
| `tiny` | Artifact size is the main constraint. | Abort-on-trap, minimum runtime metadata, strict helper budget. |
| `debug` | `debug` | Development profile with diagnostics and local debugging support. |
| `dev` | `dev` | Development-oriented profile accepted by the CLI catalog. |
| `release-fast` | `fast` | Release profile biased toward throughput. |
| `release-small` | `small` | Release profile biased toward smaller output. |
| `tiny` | `tiny` | Minimal-output profile for strict size budgets. |
| `audit` | `audit` | Audit-oriented profile exposed by the CLI catalog. |

The CLI also accepts these source-backed aliases:

| Alias | Canonical profile |
| --- | --- |
| `fast` | `release-fast` |
| `small` | `release-small` |
| `release` | `release-small` |

Prefer `--profile <profile>` in documentation. `--release <profile>` is accepted for `build`, `run`, and `size` where command help documents it.

For shipping, use the documented `ship` profile form:

```sh
zero ship --profile release-small
zero ship --profile tiny
zero ship --profile audit
```

Copyable commands:

Expand Down Expand Up @@ -41,7 +57,7 @@ bin/zero mem --json examples/allocator-collections.0

## Size Breakdown

`sizeBreakdown` is shaped for optimization agents:
`sizeBreakdown` is shaped for optimization workflows:

- `functions`: retained functions, tests, exports, estimated bytes, and retention reasons.
- `sections`: code, readonly literals, stack, debug metadata, and optional output artifact sections.
Expand Down