Packaging

zero-native provides tooling to bundle your app into distributable packages for macOS, Linux, and Windows. Chromium packaging is currently supported for macOS and includes the CEF runtime when .web_engine = "chromium" and the matching CEF layout is installed.

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)

macOS app bundles declare LSMinimumSystemVersion as 11.0. File associations and URL schemes are emitted as CFBundleDocumentTypes and CFBundleURLTypes entries in Contents/Info.plist.

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
• share/mime/packages/<name>.xml -- shared MIME metadata when file associations are configured

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

Configured file associations and URL schemes are added to the desktop file MimeType list. Extension-only associations get generated application/x-... MIME types with glob patterns in the shared MIME package.

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. When file associations or URL schemes are configured, the artifact also includes install/register-file-types.ps1, which registers the package-local executable under the current user's HKCU\Software\Classes registry keys.

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 on macOS, 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 macOS target 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