Packaging

zero-native provides tooling to bundle your app into distributable packages for macOS, Linux, and Windows. The beta distribution path is macOS-focused; Linux and Windows package support should be treated as roadmap or early support unless your app has validated those targets.

Quick start

Build and package in two steps:

zig build package

Or use the CLI directly with more control:

zero-native package --target macos --manifest app.zon --binary zig-out/bin/MyApp

Build options

The build system exposes options that control platform, web engine, and build features:

app.zon packaging fields

The manifest drives packaging metadata:

.{
    .id = "com.example.myapp",
    .name = "myapp",
    .display_name = "My App",
    .version = "1.0.0",
    .icons = .{ "assets/icon.icns", "assets/icon.ico" },
    .platforms = .{ "macos", "linux" },
    .web_engine = "system",
    .cef = .{ .dir = "third_party/cef/macos", .auto_install = false },
}

macOS

App bundle

zig build package creates a .app bundle with:

• Contents/MacOS/<binary> -- the compiled executable
• Contents/Resources/icon.icns -- the app icon
• Contents/Info.plist -- generated from app.zon
• Contents/Resources/dist/ -- frontend assets (if configured)

See Code Signing for signing, notarization, and DMG creation.

Linux

Package structure

Linux packaging creates an install tree:

• bin/<name> -- the executable
• share/applications/<name>.desktop -- desktop entry file
• share/icons/hicolor/.../<name>.png -- icons at standard sizes

zero-native package --target linux --manifest app.zon --binary zig-out/bin/MyApp

Windows

zero-native package --target windows --manifest app.zon --binary zig-out/bin/MyApp.exe

Windows packaging is in early development. The packager copies the binary and assets into a distributable directory structure.

Frontend assets

Bundle assets

If your app has a frontend build step, bundle the output:

zig build bundle-assets

This copies the configured dist directory into the build output. Production packages serve these through zero://app/, so paths like /assets/app.js work without file:// URLs.

Configure in app.zon

.frontend = .{
    .dist = "dist",
    .entry = "index.html",
    .spa_fallback = true,
}

CEF bundling

When using the Chromium engine, bundle CEF alongside the app:

zig build cef-bundle -Dcef-dir=/path/to/cef

This copies the required CEF framework, libraries, and resources into the app bundle. The CEF distribution must match the target platform and architecture.

Use the same CEF version for install, build, package, and CI verification. The usual app-developer flow is:

zero-native cef install --version <pinned-version>
zig build
zero-native package --target macos

Set .web_engine = "chromium" and .cef = .{ .dir = "third_party/cef/macos", .auto_install = false } in app.zon for the normal Chromium package path. Use -Dweb-engine, --web-engine, -Dcef-dir, or --cef-dir only when you need a one-off override.

Verify the Chromium macOS package layout locally with:

zig build test-package-cef-layout -Dplatform=macos

This gated check requires a local CEF layout or -Dcef-auto-install=true and verifies that the packaged app contains the CEF framework and resource files.

Icon generation

Generate platform-specific icon files from a source PNG:

zig build generate-icon

This produces icon.icns (macOS) and icon.ico (Windows) from assets/icon.png.

Validation

Check that your manifest and environment are ready for packaging:

zero-native doctor --manifest app.zon --strict
zero-native validate app.zon

doctor checks the host environment, WebView availability, manifest validity, log paths, and optional CEF paths. Add --strict to fail on any warning. See Debugging for details on what zero-native doctor checks.

Platform shortcut commands

In addition to zero-native package --target <platform>, the CLI provides shortcut commands:

zero-native package-windows [--output path] [--binary path]
zero-native package-linux [--output path] [--binary path]
zero-native package-ios [--output path] [--binary path]
zero-native package-android [--output path] [--binary path]

Platform targets