Reference

JuliaImgBundle(project; kwargs...)

Build specification for staging a Julia application as a self-contained image.

The Julia version is read from Manifest.toml in project (falling back to the running Julia version). Incremental compilation defaults to true when no sysimage packages are requested; building a sysimage forces incremental = false because a new sysimage invalidates all existing pkgimage caches.

Arguments

• project::String: Path to the application directory containing Project.toml and Manifest.toml

Keyword Arguments

• precompile::Bool = true: Precompile packages during staging. When false, precompilation is deferred to the first launch on the target system
• incremental::Bool = isempty(sysimg_packages): Whether to reuse existing pkgimage caches. Automatically set to false when sysimg_packages is non-empty
• sysimg_packages::Vector{String} = []: Packages to bake into the system image. Triggers a full sysimage rebuild, which invalidates all pkgimage caches
• sysimg_args::Cmd =``: Extra command-line arguments forwarded to the sysimage compiler
• remove_sources::Bool = false: Strip .jl source files from the staged package tree (only meaningful when all relevant packages are baked into the sysimage)
• asset_spec::Dict{Symbol,Vector{String}} = Dict(): Selective asset inclusion rules. When empty, all artifacts are included and indexed via pkgorigin
• asset_rpath::String = "assets": Destination subdirectory for assets when asset_spec is set
• startup_file::String: Path to the startup.jl template. Resolved from meta/startup.jl inside project, falling back to $(pkgdir(AppBundler))/recipes/startup.jl

Examples

# Default: precompile everything, incremental caches
pkg = JuliaImgBundle("path/to/app")
 
# Skip precompilation — compile on first launch instead
pkg = JuliaImgBundle("path/to/app"; precompile = false)
 
# Bake heavy dependencies into a sysimage (forces non-incremental rebuild)
pkg = JuliaImgBundle("path/to/app"; sysimg_packages = ["Plots", "DifferentialEquations"])

JuliaCBundle(project; kwargs...)

Build specification for compiling a Julia application into a native executable via juliac.

Unlike JuliaImgBundle, which stages a full Julia runtime alongside precompiled package images, JuliaCBundle ahead-of-time compiles the application into a standalone native executable. The juliac tool must be installed and is looked up in bin/juliac under each entry of DEPOT_PATH, with ~/.julia/bin as a final fallback.

Arguments

• project::String: Path to the application directory containing Project.toml

Keyword Arguments

• juliac_cmd::Cmd = Cmd([juliac()]): Command used to invoke juliac. Defaults to the first juliac executable found on DEPOT_PATH
• trim::Bool = false: When true, passes --trim=safe to juliac, removing unreachable code from the output binary
• args::Cmd =`: Additional arguments forwarded verbatim tojuliac`
• asset_spec::Dict{Symbol,Vector{String}} = Dict(): Selective asset inclusion rules. When empty, no assets are copied into the bundle
• asset_rpath::String = "assets": Destination subdirectory for assets inside destination

Examples

# Minimal: compile with defaults
pkg = JuliaCBundle("path/to/app")
 
# Enable dead-code trimming and a custom executable name
pkg = JuliaCBundle("path/to/app"; executable_name = "myapp", trim = true)

stage(product::JuliaImgBundle, destination::String;
      platform::AbstractPlatform = HostPlatform(),
      cpu_target = get_cpu_target(platform),
      runtime_mode = "MIN",
      app_name = "",
      bundle_identifier = "")

Stage a Julia application into destination, ready for packaging and distribution.

The staging process:

1. Downloads and extracts the Julia runtime for platform (version from Manifest.toml)
2. Copies all non-stdlib packages and artifacts into the stdlib tree
3. Configures startup.jl, DEPOT_PATH, and LOAD_PATH via AppEnv
4. Optionally compiles a system image from product.sysimg_packages
5. Optionally precompiles pkgimages for all project dependencies

When product.precompile is true, platform must match the host OS and architecture (see cross-compilation constraints below).

Arguments

• product::JuliaImgBundle: Staging configuration
• destination::String: Directory in which the staged application is assembled

Keyword Arguments

• platform::AbstractPlatform: Target platform; defaults to the current host
• cpu_target: LLVM CPU target string; derived from platform by default
• runtime_mode: AppEnv runtime mode string passed to AppEnv.save_config
• app_name: Application name embedded in the AppEnv config
• bundle_identifier: Bundle identifier embedded in the AppEnv config (e.g. reverse-DNS on macOS)

Cross-Compilation Constraints

Precompilation runs native code, so cross-OS and cross-architecture compilation is not supported when product.precompile = true:

• Windows: host must be Windows
• macOS: host must be macOS; x86_64 → aarch64 is not supported
• Linux: host must be Linux with a matching architecture

Set precompile = false and sysimg_packages = [] in JuliaImgBundle to stage for a different platform without compilation.

Examples

pkg = JuliaImgBundle("src/MyApp")
 
# Stage for the current machine
stage(pkg, "build/staging")
 
# Stage for macOS arm64 (must run on Apple Silicon with precompile=false, or natively)
stage(pkg, "build/MyApp.app/Contents/Resources/julia";
      platform = Platform("aarch64", "macos"))
 
# Embed app identity in the AppEnv config
stage(pkg, "build/staging"; app_name = "MyApp", bundle_identifier = "com.example.myapp")

stage(spec::JuliaCBundle, destination::String;
      runtime_mode = "MIN",
      app_name = get_module_name(spec.project),
      bundle_identifier = "")

Compile a Julia application into a native executable and assemble it in destination.

The staging process:

1. Saves an AppEnv config to destination/config with runtime identity and load-path settings
2. Installs assets from spec.asset_spec into destination/<asset_rpath>
3. Writes a pkgorigin index to destination/index for asset resolution at runtime
4. Invokes juliac to AOT-compile the application and bundle the result into destination

Unlike JuliaImgBundle, no Julia runtime tarball is downloaded — juliac produces a self-contained native binary. The host toolchain must be compatible with the target.

Arguments

• spec::JuliaCBundle: Compilation and asset configuration
• destination::String: Directory in which the compiled application is assembled

Keyword Arguments

• runtime_mode: AppEnv runtime mode string passed to AppEnv.save_config
• app_name: Application name embedded in the AppEnv config; defaults to the module name
• bundle_identifier: Bundle identifier embedded in the AppEnv config (e.g. reverse-DNS on macOS)

Examples

pkg = JuliaCBundle("src/MyApp")
 
# Stage into a directory
stage(pkg, "build/myapp";
      app_name = "MyApp", bundle_identifier = "com.example.myapp")
 
# Stage with a custom runtime mode
stage(pkg, "build/staging"; runtime_mode = "SANDBOX")

stage(config, destination::String; [dsstore=false])

Stage package metadata and directory structure into destination in preparation for bundling.

config is a format-specific configuration object — MSIX, DMG, or Snap — that carries the template files, parameters, and settings for the target platform. Mustache-rendered templates are written using the parameters stored in config.

stage is called automatically by bundle, but can be used directly when you need to inspect or modify the staging directory before compression and signing.

Staged layout by format

MSIX

• Assets/ — application icons (generated from source or copied verbatim if already a directory)
• AppxManifest.xml — rendered package manifest
• resources.pri — package resource index
• Msix.AppInstaller.Data/MSIXAppInstallerData.xml — rendered installer configuration

DMG

• Contents/Resources/icon.icns — application icon
• Contents/Info.plist — rendered application metadata
• Contents/MacOS/<app-name> (optional) — native launcher when main_launcher is set

When dsstore = true, also writes into the parent of destination:

• Applications — symlink to /Applications for drag-and-drop installation
• .DS_Store — custom Finder window appearance

Snap

• meta/icon.png — application icon
• meta/snap.yaml — rendered Snap package metadata
• meta/gui/<app-name>.desktop — rendered desktop launcher
• meta/hooks/configure (optional) — configuration hook when configure_hook is set
• bin/<app-name> (optional) — main launcher script when main_launcher is set

Examples

stage(MSIX(app_dir), "build/msix_staging")
stage(DMG(app_dir),  "build/MyApp.app"; dsstore = true)
stage(Snap(app_dir), "build/snap_staging")

bundle(setup::Function, config, destination::String; force=false, [password=""])

Stage, populate, and optionally compress an application bundle for distribution.

config is a format-specific configuration object — MSIX (Windows), DMG (macOS), or Snap (Linux) — and destination is the path of the final artifact (e.g. "MyApp.msix", "MyApp.dmg", "MyApp.snap") or an uncompressed staging directory.

The function follows three steps:

1. Stage — writes platform metadata and directory structure into a staging area via stage.
2. Setup — calls setup(staging_dir), where you copy or compile the application files that should be included in the bundle.
3. Pack — when config.compress is true (the default when destination carries the format extension), compresses the staging area into the final artifact and performs code signing.

Set force = true to overwrite an existing destination path.

Code signing

MSIX and DMG sign the bundle automatically during the pack step. Pass the certificate password via the password keyword argument (defaults to ""). When config.selfsign is true, a temporary self-signed certificate is generated instead of using the one in the configuration. DMG entitlements are rendered from the template stored in the configuration. Snap packages are not signed locally; they are verified by the Snap Store after upload.

Examples

bundle(MSIX(app_dir), "MyApp.msix") do staging_dir
    # copy or compile application files into staging_dir
end
 
bundle(DMG(app_dir), "MyApp.dmg") do staging_dir
    # copy or compile application files into staging_dir
end
 
bundle(Snap(app_dir), "MyApp.snap") do staging_dir
    # copy or compile application files into staging_dir
end

bundle(product::JuliaCBundle, appimage::AppImage, destination::String; force = false)

Package a juliac-compiled executable as a mountable AppImage.

bundle(product, packaging, destination; force=false, [password=""])

Bundle a Julia application product into a platform-specific package at destination by calling bundle(setup, config, destination) with product staged as the setup step.

Arguments

• product: The application artifact to bundle. Either a JuliaImgBundle or a JuliaCBundle
• packaging: The target package format. One of:
  • DMG — macOS disk image (.dmg). Must be built on macOS.
  • Snap — Linux Snap package. Must be built on Linux.
  • MSIX — Windows app package (.msix). Must be built on Windows.
• destination: Output path for the produced package file.

Keyword Arguments

• force=false: Overwrite an existing package at destination if true.
• password="": Code-signing certificate password. Applicable to DMG and MSIX targets only.

A warning is emitted when the host OS does not match the target platform, as cross-platform packaging is not supported.

See also stage, bundle(setup, config, destination).