Build and bundle your application

Build and bundle for macOS

Use cargo-bundle to package a Byte Engine application as a macOS .app. Bake resources first because cargo-bundle copies files but doesn't process assets.

1. Install cargo-bundle

cargo install cargo-bundle

2. Bake your application resources

Install BELD, then run it from the application directory:

beld --source "$PWD/assets" --destination "$PWD/resources" \
  bake

The zero-ID form includes every recognized application asset and the engine shaders exposed through assets/byte-engine. Verify the resulting inventory:

beld --destination "$PWD/resources" list

A release build doesn't compile a missing shader on demand.

Keep resources/ outside Cargo's target/ directory. It is an application input to packaging. Cargo owns target/ and might remove it when you run cargo clean.

3. Declare your bundle contents

Add bundle metadata to the application's Cargo.toml:

[package.metadata.bundle]
name = "My Application"
identifier = "com.example.my-application"
resources = ["resources"]

Use a reverse-DNS identifier that you own before distributing the application. The resources entry makes cargo-bundle copy the complete baked directory into the application bundle.

4. Select the bundled resource directory

Let GraphicsApplication select the default resource directory during normal development and release runs:

• In a debug build, it uses resources/ under CARGO_MANIFEST_DIR when Cargo provides that directory. Otherwise, it falls back to resources/ beside the executable.
• In a release build, it uses resources/ beside the executable.
• An explicit resources.path value replaces the default. A relative value is relative to the process's current working directory.

The assets-path default follows the same manifest-first policy in debug builds. Release builds don't install asset processors, so package the baked resources/ directory instead of the source assets/ directory.

A macOS application bundle is the exception. Its executable lives in Contents/MacOS, but cargo-bundle copies the resource directory to Contents/Resources/resources. Add the override only when the executable is inside a macOS application bundle:

use std::path::PathBuf;

use byte_engine::application::{Application, Parameter};

fn bundled_resources_path() -> Option<PathBuf> {
    let executable = std::env::current_exe().ok()?;
    let contents = executable.parent()?.parent()?;

    (contents.file_name()?.to_str()? == "Contents")
        .then(|| contents.join("Resources").join("resources"))
}

let parameters = bundled_resources_path()
    .map(|path| {
        Parameter::new_string(
            "resources.path".to_owned(),
            path.to_string_lossy().into_owned(),
        )
    })
    .into_iter()
    .collect::<Vec<_>>();

let app = GraphicsApplication::new("My Application", &parameters);

Outside an application bundle, parameters is empty and GraphicsApplication applies the current debug or release directory policy. You can still pass an absolute --resources.path value to select a fixed directory, or a relative --resources.path=custom/resources value to select one from the current working directory.

5. Build the application bundle

cargo bundle --release --format osx

The completed app is written to:

target/release/bundle/osx/My Application.app

Its relevant layout is:

My Application.app/
  Contents/
    MacOS/my-application
    Resources/resources/
      resources.db
      ... baked payload files ...

Copy the .app to /Applications or drag it there in Finder to install it locally. Code signing and notarization are required before distributing it to other Macs. A DMG is optional distribution packaging layered on top of the .app; it isn't required to run or install the application.

Build for Linux

Create an optimized application binary from your project directory:

cargo build --release

Cargo writes the binary to target/release/.

Build for Windows

Create an optimized application executable from your project directory:

cargo build --release

Cargo writes the executable to target\release\.