#Packaging
krate native package - installers and archives for macOS, Windows and Linux, generated icons and Windows resources, and which formats need a platform tool.
Experimental. Part of Krate Native, which is under construction.
krate native package [dir] [--target <os/arch>] [--format <list>] [--out <dir>]
krate native build --package [--target <os/arch>]package turns a built app into files you can hand to users. Output goes to
dist-native/packages/. Most formats are written by the compiler itself, so
you can build a Linux .deb, a Windows .zip or an MSIX package on any
machine. A few formats need a platform tool; the table says which.
#What it packages
package looks in dist-native/ for one of two layouts:
- A release executable:
dist-native/<os>-<arch>/<productName>[.exe], one binary with the app embedded (krate native build --release). Anything else in that directory is shipped next to it. - The prebuilt shell:
dist-native/<os>-<arch>/<productName>[.exe], thekrate-shellbinary under the product name, withapp/next to it.krate native buildwrites this when it finds a shell (see Finding the shell), and so doeskrate native build --releasewhen it falls back to the prebuilt-shell layout. No Go toolchain is needed. The shell findsapp/next to itself, or inContents/Resources/appinside a macOS bundle. The older pairdist-native/krate-shell[.exe]next todist-native/app/is still packaged. Withapp/next to it the shell is that app: it refuses another app directory on its command line and refuses--devunless the app was built withnative.debug, so nobody can run their own code or drive the app's pages under the app's signature and permissions. Run other app directories, and--dev, with a barekrate-shell.
The executable's header is checked against --target, so a Linux binary is
never packaged as a Windows app. With neither layout present the command stops
with KR7220 and says which build command to run.
krate native build --package builds, then packages the same target.
#Formats
| OS | Format | Written by | Notes |
|---|---|---|---|
| macOS | app |
compiler | <Name>.app, kept under packages/darwin-<arch>/ |
| macOS | zip |
compiler | always; the update file. Keeps modes and symlinks |
| macOS | dmg |
hdiutil |
only on macOS; elsewhere you get the .zip and a note |
| macOS | mas |
compiler, codesign, productbuild |
the Mac App Store variant, a sandboxed .app and a .pkg; see Stores |
| Windows | zip |
compiler | always; the update file |
| Windows | nsis |
makensis |
install dir, shortcuts, uninstaller, URL protocols, WebView2 check |
| Windows | msix |
compiler | unsigned; sign it with krate native sign |
| Windows | msix-store |
compiler | the Microsoft Store package, .msixupload and (x64 + arm64) .msixbundle; see Stores |
| Linux | tar.gz |
compiler | always; the update file |
| Linux | deb |
compiler | default Linux installer |
| Linux | rpm |
compiler | via the rpmpack library |
| Linux | appimage |
appimagetool |
needs a squashfs writer, so the tool is required |
| Linux | flatpak |
compiler, flatpak-builder |
manifest, metainfo and Flathub manifest always; the .flatpak bundle needs the tool. Details |
| Linux | snap |
compiler, snapcraft |
snapcraft.yaml always; the .snap needs the tool. Details |
Without --format the formats come from the config:
native.bundle.windows.installer (msix or nsis) and
native.bundle.linux.formats (deb, rpm, appimage, flatpak, snap; default deb). A tool
that is missing for a format you asked for fails with KR7221 and an install
hint. --format takes a comma separated list and replaces the config.
export default defineConfig({
native: {
appId: "com.acme.notes",
productName: "Acme Notes",
version: "1.2.0",
icons: "assets/icon.png",
deepLinks: ["acme"],
bundle: {
macos: { category: "productivity" },
windows: { publisher: "CN=Acme Inc", installer: "msix" },
linux: { formats: ["deb", "rpm"] },
},
},
});#Icons
native.icons is one PNG, ideally 1024 x 1024. The packager makes everything
else in pure Go:
.icnswith PNG elementsic07toic10(128 to 1024 pixels) and the retina and small variants..icowith PNG entries from 16 to 256 pixels.- Linux hicolor PNGs from 16 to 512 pixels, and the MSIX logos.
Without native.icons a placeholder icon is generated. A source under 512
pixels works but gives soft large icons (KR7223 is an unreadable file).
#macOS
<Name>.app/Contents/ holds Info.plist, MacOS/<Name>,
Resources/icon.icns and Resources/app/ (the shell layout). Info.plist
carries the bundle id (native.appId), the version, LSApplicationCategoryType
from bundle.macos.category (productivity or a full
public.app-category.*), NSHighResolutionCapable, LSMinimumSystemVersion
and, for deepLinks, CFBundleURLTypes; for fileAssociations, CFBundleDocumentTypes and UTExportedTypeDeclarations
(Files).
Signatures. The Go linker signs darwin/arm64 executables ad hoc, which is
enough for Apple silicon to run them (checked: LC_CODE_SIGNATURE with the
ad hoc flag). The .app as a whole has no _CodeSignature; that needs
codesign, so run krate native sign on a Mac. A pure Go bundle signer is not
implemented. See Signing.
#Windows
The portable .zip holds <Name>/<Name>.exe and its files. The NSIS
script (kept at packages/windows-<arch>/installer.nsi) installs to
Program Files, adds Start menu and desktop shortcuts and an uninstaller,
registers each deepLinks scheme, each fileAssociations type (the
uninstaller removes them) and the scheme of
notification clicks under the registry,
and makes sure the WebView2 Runtime is installed (below). MSIX needs
bundle.windows.publisher, the subject of your signing certificate (CN=Acme Inc). The package is a zip with AppxManifest.xml (identity, logos, protocol
and file type extensions, runFullTrust), [Content_Types].xml and AppxBlockMap.xml
(SHA-256 per 64 KiB block). Files are stored uncompressed so the block map
needs no compressed sizes.
#The WebView2 Runtime
The app shows its pages with Microsoft's Evergreen WebView2 Runtime. Windows 11
and current Windows 10 machines with Edge have it; an older Windows 10 may not.
native.bundle.windows.webview2 says what the NSIS installer does about that:
| Value | The installer |
|---|---|
download (default) |
Downloads Microsoft's Evergreen bootstrapper (go.microsoft.com/fwlink/p/?LinkId=2124703, PowerShell as the second try) and runs it with /silent /install |
embed |
The same without the download: webview2Path is a MicrosoftEdgeWebview2Setup.exe that is stored inside the installer (about 1.7 MB) |
fixed |
Installs no runtime. webview2Path is an extracted Fixed Version runtime folder (from the .cab on the WebView2 download page, for the architecture you build); it is copied to WebView2Runtime next to the executable and the app uses it before any installed runtime. Adds 150 to 300 MB |
none |
Does nothing; the app handles a missing runtime itself |
bundle: { windows: { installer: "nsis", webview2: "embed", webview2Path: "vendor/MicrosoftEdgeWebview2Setup.exe" } }The files are Microsoft's: download them yourself, keep them out of version
control, and check Microsoft's redistribution terms. A missing or wrong file is
KR7220 with a hint that names the fix.
The check follows Microsoft's documentation: the pv value under
EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}, in
HKLM\SOFTWARE\WOW6432Node (64-bit Windows), HKLM\SOFTWARE (32-bit Windows)
and HKCU\Software (per-user installs); a missing value or 0.0.0.0 means not
installed. The bootstrapper runs only when none is found, so reinstalling an
app does not touch an existing runtime. If the bootstrapper cannot be fetched or
fails, the installer says so (a message box, or the log of a silent install)
and finishes anyway.
The app itself does not fail silently either. A program started from Explorer
has no console, so when no runtime can be started the app shows a message box
("Native Tasks needs the Microsoft Edge WebView2 Runtime...") with the download
page and offers to open it, then exits with the error. Set
KRATE_NATIVE_NO_DIALOG=1 to suppress the box for unattended runs.
MSIX cannot declare the Evergreen runtime as a dependency: it is not a framework package, so a manifest has nothing to name. An MSIX app relies on the runtime being present and on the message box above. The package targets Windows 10 1809 and later.
#Architectures
--target windows/arm64 (and linux/arm64, darwin/arm64) builds and packages
for ARM: the .deb/.rpm architecture, the MSIX ProcessorArchitecture, the
AppImage ARCH and the Windows resource object follow the target. CI runs the
packaging steps natively on ubuntu-24.04-arm and windows-11-arm as well as on
x64 and Apple silicon. Bun and Deno publish no Windows on ARM builds, so a
Windows on ARM machine can use Node (or QuickJS) host code only.
#Icon and version resources
An .exe shows its icon and version in Explorer only if they are linked in.
pkg.WindowsResources writes a .syso object that the Go linker picks up:
// in a build step
err := pkg.WindowsResources(root, cfg, "rsrc_windows_amd64.syso")Put rsrc_windows_amd64.syso (and rsrc_windows_arm64.syso) next to the
main.go of the executable; the file name suffix keeps other platforms from
linking it. It contains the icon (RT_GROUP_ICON and RT_ICON), the version
information (RT_VERSION) and a manifest that turns on per-monitor DPI
awareness, long paths and Common Controls v6. The release build calls it.
#Linux
The .deb installs a single executable to /usr/bin/<name>. With support
files (the shell layout) the executable and files go to /usr/lib/<name>/ and
/usr/bin/<name> is a symlink. It also installs
/usr/share/applications/<appId>.desktop (with
MimeType= entries for deepLinks and fileAssociations, plus
/usr/share/mime/packages/<appId>.xml for the file types), hicolor icons and an
md5sums file. Depends: lists libwebkit2gtk-4.1-0 and libgtk-3-0; the
.rpm requires webkit2gtk4.1 and gtk3. Check a .deb with
dpkg-deb --info and --contents.
#Universal apps and stores
One macOS app for Apple silicon and Intel (--arch universal), Flatpak, Snap,
the Mac App Store and the Microsoft Store are on their own page:
Stores and universal apps. The feed of a
universal app is latest-darwin-universal.json.
#Update files and --notes
The zip (macOS, Windows) or tar.gz (Linux) is also the file the
updater downloads. With KRATE_UPDATER_PRIVATE_KEY set
package signs it and writes latest-<os>-<arch>.json beside it.
#Flags
| Flag | Meaning |
|---|---|
--target <os/arch> |
linux, windows, darwin with amd64 or arm64; default this machine. darwin/universal merges arm64 and x86_64, windows/universal bundles x64 and arm64 for the Store, mas is the Mac App Store variant |
--arch universal |
the same as universal as the architecture of the target; also on native build --release |
--installer-identity <name> |
the installer identity that signs the Mac App Store .pkg |
--format <list> |
formats from the table |
--out <dir> |
native output directory (default dist-native) |
--sign, --notarize |
sign (and notarize) while packaging; see Signing |
--notes <text or @file> |
release notes for the update feed |
--update-base-url <url> |
where the update files will be hosted |
--delta-from <dir>[,<dir>], --delta-count <n> |
write signed delta updates from the newest n (default 3) earlier releases whose update files are in these directories; see Updates |
--channel <name> |
write the feed as latest-<name>-<os>-<arch>.json for that channel |
--rollout <percent>, --rollout-start <RFC 3339>, --rollout-ramp-hours <h> |
staged rollout |
--critical, --min-version <v> |
offer the update to every install, whatever the rollout says |
#Diagnostics
KR7220 nothing to package, KR7221 tool missing, KR7222 unknown format for
the OS, KR7223 icon, KR7228 write failure, KR7229 metadata (appId,
version, MSIX publisher). Universal, store and sandbox formats: KR7300 to
KR7302 (see Stores).
Last updated: 2026-11-17
Contributors: Noinkin