Crossbundle build command

Crossbundle build gradle

Crossbow default build process requires installed Gradle on your PC.

To create a project go to the example you want to build and use the command below. The command belongs to macroquad engine examples building:

crossbundle build android

# To specify custom export gradle directory
crossbundle build android --export-path=./gen/

By default build directory is target/android/<project_name>/gradle. But you can specify your own build directory via --export-path=<OUT_PATH> flag. Go to the directory where Gradle project was built and use command below to manually install APK on the device.

gradle installDebug

Also you can replace build with run subcommand to build and run APK on your device (it uses installDebug command under the hood). To see how to set android emulator check install recommendations for linux-android, macos-android, windows-android.

Crossbundle build native AAB/APK

If you don't want to use gradle you can specify it in strategy native-apk:

crossbundle build android -s=native-apk
# or do you need AAB:
crossbundle build android -s=native-aab

To find out available commands specify the -h flag.

crossbundle build android -h

Preview a build without side effects

--dry-run resolves and prints the same immutable Android build plan used by a real build, but never generates files, creates a signing key, compiles, downloads, installs, or launches anything:

crossbundle build android --dry-run
crossbundle build android --dry-run --json
crossbundle run android --dry-run --json

The JSON plan has a versioned envelope and ordered, stable step IDs. Paths and signing inputs may be reported, but signing passwords and other secret values are never stored in a plan.

Standard Cargo projects

Crossbundle uses Cargo's public command-line interface by default and reads Cargo's JSON messages to locate the resulting Android library. This path is engine-neutral: any application that exposes a cdylib with the appropriate Android entry point can use it.

Bevy

Expose the application as a library and let Bevy provide the native mobile entry point:

[lib]
crate-type = ["cdylib", "rlib"]

[dependencies]
bevy = { version = "0.19", default-features = false, features = ["2d"] }

[target.'cfg(target_os = "android")'.dependencies]
# NativeActivity keeps this path independent of Gradle and Maven.
bevy = { version = "0.19", default-features = false, features = ["android-native-activity"] }

use bevy::prelude::*;

#[bevy_main]
pub fn main() {
    App::new().add_plugins(DefaultPlugins).run();
}

The rlib entry keeps the library usable by a small desktop binary when desired:

fn main() {
    my_game::main();
}

Then use the same commands as any other Crossbow project:

crossbundle run android
crossbundle build android --release -s=native-aab

Crossbundle forwards the selected profile and Cargo feature flags, and streams Cargo's progress and compiler diagnostics while building. If the package does not expose a library cdylib, validation fails before compilation with the manifest change required to fix it.

android-native-activity is the recommended default because it keeps the toolchain Rust-native. Projects that need AndroidX or other JVM integrations can instead choose Bevy's android-game-activity feature and provide the corresponding Java/Gradle integration.

Macroquad

Macroquad uses Miniquad's Java activity, so select that runtime and use the Gradle strategy:

[lib]
crate-type = ["cdylib", "rlib"]

[package.metadata.android]
runtime = "miniquad"

#[macroquad::main("Game")]
pub async fn main() {
    // ...
}

#[cfg(target_os = "android")]
#[unsafe(no_mangle)]
pub extern "C" fn quad_main() {
    main();
}

Crossbundle takes the Java/JNI sources from the exact resolved Miniquad version. miniquad is not supported by native-apk or native-aab, because those strategies do not compile Java code. The Crossbow Java bridge and AndroidX are added only when permissions or plugins require them.

Migrating to Crossbow 0.3

Remove rust_compiler = "cargo"; Cargo is always used.
Replace rust_compiler = "quad" with runtime = "miniquad", then expose the library and quad_main shown above.
Remove rust_compiler = "ndk-glue" or app_wrapper; export the runtime's Android entry point from a cdylib instead.

Obsolete keys fail with migration guidance rather than being ignored.

Cargo-first iOS builds

Crossbundle builds iOS applications with Cargo's public CLI and packages the exact executable reported by Cargo. Workspace packages, renamed binaries, examples, feature flags, and custom target directories therefore follow normal Cargo behavior.

An iOS application must select an executable target. Use --bin <name> or --example <name> when the package has more than one; otherwise Crossbundle follows package.default-run or selects the package's only binary.

Bevy projects can share one application function across every platform. Keep Bevy's Android entry point in the library used for the Android cdylib, and call it from a small binary for iOS and desktop:

// src/lib.rs
use bevy::prelude::*;

#[bevy_main]
pub fn main() {
    App::new().add_plugins(DefaultPlugins).run();
}

// src/main.rs
fn main() {
    my_game::main();
}

Build for an Apple Silicon simulator or a device with:

crossbundle build ios --target aarch64-apple-ios-sim
crossbundle build ios --release --target aarch64-apple-ios

The supported Rust targets are aarch64-apple-ios, aarch64-apple-ios-sim, and x86_64-apple-ios.

Pass --profile-path, --team-id, and --signing-identity to sign a device bundle. crossbundle run ios --device requires all three.

Keyboard shortcuts

crossbow