Examples

If you want to see how the library is used before writing your own program, start with the offline examples. They use checked-in fixtures or injected exchanges, so they do not need a registry.

Quick start

Run the offline smoke pass from the repository root:

zig build examples-smoke

To build all five packaged examples without running them:

zig build examples

The individual example-* steps build and run one program. Arguments after -- are passed to that example.

Offline examples

Normalize a reference

normalize-reference.zig parses an image reference and prints its normalized registry, repository, tag or digest, and reference form:

zig build example-normalize-reference -- ubuntu:22.04

The example uses the process arena because the parsed reference is printed and then discarded when the process exits.

Inspect a manifest fixture

inspect-manifest.zig reads a bounded manifest fixture, prints its media types, digests, layer sizes, and annotations, then calls parsed.deinit():

zig build example-inspect-manifest
zig build example-inspect-manifest -- fixtures/manifests/busybox-amd64-live-oci-manifest.json

The first command uses the checked-in fixture default. The second accepts another manifest JSON path, subject to the example's 32 KiB input limit.

Select a platform

select-platform.zig parses an OCI image index or Docker manifest list and selects one descriptor:

zig build example-select-platform
zig build example-select-platform -- linux arm64
zig build example-select-platform -- fixtures/indexes/busybox-latest-live-oci-index.json linux arm64 v8

With no arguments it reads the checked-in index and selects linux/amd64. The two-argument form keeps the default index and changes the os and architecture. The path form accepts an optional variant. The parsed document owns the selected descriptor's borrowed strings until it is released.

Resolve a batch with injected exchanges

resolve-many.zig demonstrates sequential batch resolution with injected manifest and token exchanges. It reads one fixture, processes five references, and expects four pinned results plus one missing-reference failure:

zig build example-resolve-many

This is an offline demonstration of the z_oci.testing.resolveManyWithExchangers seam, not a live registry example. The result owns every batch item and is released with ResolveManyResult.deinit.

Live example

resolve-reference.zig calls the public resolve API against a registry:

zig build example-resolve-reference -- ubuntu:22.04
zig build example-resolve-reference -- ubuntu:22.04 linux/amd64

These commands may need network access and registry credentials. The example uses Config{}, so it starts with anonymous access. It creates a caller-owned HTTP client, releases the successful ResolveResult, and cleans up the parsed reference on failure.

The live example is excluded from examples-smoke. If you adapt it for a private registry, inject credentials through Config.credential_sources as described in Credentials. Do not put credentials in command arguments or source files.

Ownership and next steps

The examples use the process allocator for short-lived command input and caller-owned allocators for parsed documents, clients, references, and results where those values must outlive a step. Follow the cleanup in the source when adapting an example to a longer-lived program.

For a complete library quick start, see Library. For CLI usage, see CLI. For platform selection details, see Platform and limits.