Introduction

What is Crossbow?

The crossbow project aims to provide a complete toolkit for cross-platform game development in Rust - from project creation to publishing. In addition, the project simplifies the creation, packaging, and signing of Android and iOS applications. We want to make most of our tools - engine agnostic to help rust game developers integrate them into their engines or games.

Why Crossbow?

There are already cargo-apk, cargo-mobile, cargo-xcode, etc. - why do I need another packaging tool?

Crossbow is more than an Android and iOS packager: it is a cross-platform Rust game-development toolkit. crossbundle turns standard Cargo projects into native .apk/.aab and .app/.ipa artifacts, with optional Gradle packaging for Android plugins. crossbundle-tools provides the same building blocks for custom workflows, while crossbow-android supports Android plugins written in Java/Kotlin.

A lot of functionality was inspired by Godot, Xamarin, and cargo-apk.

Design Goals

• Customizable: Create new commands with available tools.
• Simple: Easy to install and start hacking but also pretty flexible for strong devs.
• Cargo-first: Builds use Cargo's public CLI and consume the artifacts Cargo reports.
• Capable: Build native .apk/.aab and .app/.ipa artifacts, with optional Gradle packaging on Android.
• Rust: Don't leave your Rust code - everything can be configured from Cargo.toml.
• Plugins: Godot-like plugins for Android (and iOS in future) with Rust wrapper!

Next steps

As the next steps we recommend you to install and setup crossbundle to be able to build, test, and run your project!

See Getting Started for more information.

Installation

Rust Setup

All crossbow crates are written in Rust. This means that before we begin, we need to set up our Rust development environment.

Installing Rust

Install Rust by following the Rust Getting Started Guide.

Once this is done, you should have the rustc compiler and the cargo build system installed in your path.

Rust Learning Resources

The goal of this book is to learn crossbow, so it won't serve as a full Rust education. If you would like to learn more about the Rust language, check out the following resources:

• The Rust Book: the best place to learn Rust from scratch.
• Rust by Example: learn Rust by working through live coding examples.

Crossbundle Setup

To begin with crossbow - you will need to install crossbundle first. You can do it simply by running the following command:

cargo install --git=https://github.com/dodorare/crossbow crossbundle

Next steps

To complete the installation of all requirements, read the documentation corresponding to your platform:

• Android on Windows
• Android on Linux
• Android on macOS
• Android with Docker
• iOS on macOS

Android setup on Windows

Install necessary packages

1. Use crossbundle install command or download and install Android Studio.
2. Start Android Studio, and go through the Android Studio Setup Wizard with the Custom option and install the following (or install them in SDK Manager):
   • Android SDK
   • NDK (Side by side)
   • Android SDK Command-line Tools
   • Android SDK Build-Tools
   • Android SDK Platform-tools

Install necessary rustup targets

Run the following command:

rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android

Add environment variables

From the Start search bar, enter env and select Edit environment variables for your account.

Or you can install required env via command line accordingly table above. Arguments were provided for example

SETX ANDROID_SDK_ROOT "C:\Users\Username\AppData\Local\Android\Sdk" /M
SETX ANDROID_NDK_ROOT "C:\Users\Username\AppData\Local\Android\Sdk\ndk\28.2.13676358" /M
SETX JAVA_HOME "C:\Program Files\Java\jdk-17" /M
SETX GRADLE_HOME "C:\Gradle\gradle-9.5.0" /M
SETX BUNDLETOOL_PATH "C:\Users\Username\bundletool-all-1.18.3.jar" /M

You have to close and reopen any existing console windows for these changes to take effect.

Set up your Android device

Follow the link to find out how to set up your device or android emulator

Next step

See hello-world to configure your project

After previous steps you can use crossbundle to build gradle project or native APK/AAB. Go to the links:

• Crossbundle build command
• Crossbundle run command
• Crossbundle install command
• Crossbundle new command

Setup Android Environment on Linux

Install necessary packages

1. Use crossbundle install command or download and install Android Studio.
2. Start Android Studio, and go through the Android Studio Setup Wizard with the Custom option and install the following (or install them in SDK Manager):
   • Android SDK
   • NDK (Side by side)
   • Android SDK Command-line Tools
   • Android SDK Build-Tools
   • Android SDK Platform-tools

Install necessary rustup targets

Run the following command:

rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android

Add environment variables

From the Start search bar, enter env and select Edit environment variables for your account.

For that edit ~/.bash_profile or ~/.bashrc files so they contain those lines:

export ANDROID_SDK_ROOT=$HOME/Android/Sdk
export ANDROID_NDK_ROOT=$HOME/Android/Sdk/ndk/28.2.13676358
export GRADLE_HOME=<path_to_gradle>
export BUNDLETOOL_PATH=<path_to_bundletool>

Also, install JDK 17, which provides the Java runtime and the keytool utility.
To make sure it's present type this command: ls /usr/lib/jvm/default/bin/ | grep keytool

But please be aware that your path may vary. The above path is for arch-based Linux.

If not, install JDK 17 according to your operating system: Examples:

• Ubuntu: sudo apt install openjdk-17-jdk
• Manjaro (Arch): sudo pacman -S jre17-openjdk-headless jre17-openjdk jdk17-openjdk openjdk17-doc openjdk17-src

Set up your Android device

Follow the link to find out how to set up your device or android emulator

Next step

See hello-world to configure your project

After previous steps you can use crossbundle to build gradle project or native APK/AAB. Go to the links:

• Crossbundle build command
• Crossbundle run command
• Crossbundle install command
• Crossbundle new command

Android setup on MacOS

Install necessary packages

1. Use crossbundle install command or download and install Android Studio.
2. Start Android Studio, and go through the Android Studio Setup Wizard with the Custom option and install the following (or install them in SDK Manager):
   • Android SDK
   • NDK (Side by side)
   • Android SDK Command-line Tools
   • Android SDK Build-Tools
   • Android SDK Platform-tools
3. Download and install JDK 17. It can be installed with Homebrew:

brew install openjdk@17

Install necessary rustup targets

Run the following command:

rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android

Add environment variables

From the Start search bar, enter ‘env’ and select Edit environment variables for your account.

For that edit ~/.bash_profile/~/.bashrc or ~/.zshrc files so they contain those lines:

export ANDROID_SDK_ROOT=$HOME/android/sdk
export ANDROID_NDK_ROOT=$ANDROID_SDK_ROOT/ndk/28.2.13676358
export GRADLE_HOME=<path_to_gradle>
export BUNDLETOOL_PATH=<path_to_bundletool>

Also, we need to make sure we have a java runtime environment (JRE) installed. We will need a key tool utility from there.
To make sure it's present type this command: ls /usr/lib/jvm/default/bin/ | grep keytool or add to your PATH env var.

Set up your Android device

Follow the link to find out how to set up your device or android emulator

Next step

See hello-world to configure your project

After previous steps you can use crossbundle to build gradle project or native APK/AAB. Go to the links:

• Crossbundle build command
• Crossbundle run command
• Crossbundle install command
• Crossbundle new command

Android setup on Docker

Build Android with Docker

Pre-requirements:

• Installed Docker
• Installed adb (optional)

Clone this repository with this command:

git clone https://github.com/dodorare/crossbow
cd ./crossbow/

To run an example Android application with docker you will need to following steps:

Download the Docker image:

docker pull ghcr.io/dodorare/crossbundle:latest

Run the following command at the root of crossbow project:

For unix systems (Bash):

docker run --rm -it -v "$(pwd)/:/src" -w /src/examples/macroquad-permissions ghcr.io/dodorare/crossbundle build android --release

For Windows (PowerShell):

docker run --rm -it -v "${pwd}/:/src" -w /src/examples/macroquad-permissions ghcr.io/dodorare/crossbundle build android --release

Install APK on connected Android phone via USB:

Follow the link to find out how to set up your device or android emulator

adb install ./target/android/macroquad-permissions/gradle/build/outputs/apk/release/gradle-release-unsigned.apk

Or transfer APK file to your phone with any application.

iOS setup on macOS

Crossbundle requires the full Xcode installation; the standalone Command Line Tools are not enough. Install Xcode from the Mac App Store, launch it once to finish setup, and install an iOS Simulator runtime through Xcode.

If another developer directory is active, select Xcode explicitly:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

Install Rust, Crossbundle, and the supported iOS targets:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add aarch64-apple-ios aarch64-apple-ios-sim
cargo install --git https://github.com/dodorare/crossbow crossbundle

Intel Macs also need the x86_64 Simulator target:

rustup target add x86_64-apple-ios

Verify the toolchain before building:

crossbundle doctor --platform apple

Build and run in Simulator

From a Crossbundle project, build or run with:

crossbundle build ios
crossbundle run ios

Crossbundle builds for the host's Simulator architecture and selects an available iOS Simulator automatically. Pass --simulator <NAME_OR_UDID> to select one explicitly, or --no-open --detach for automation.

Run on a physical device

Physical-device deployment requires:

• an Apple signing certificate installed in the login keychain;
• a provisioning profile matching the application's bundle identifier;
• the Apple Developer Team ID associated with both;
• ios-deploy, installed with brew install ios-deploy.

List available signing identities with:

security find-identity -v -p codesigning

Then pass the profile by absolute path, the Team ID, and the certificate name or SHA-1 hash:

crossbundle run ios --release --device \
  --profile-path=/absolute/path/to/profile.mobileprovision \
  --team-id=AS9UV719T7 \
  --signing-identity=AF96DABFC5DEE81E339ED8755DA8D1E48A87CBFE

Set up your Android device

To prepare to run your Crossbow app on an Android device, you need an Android device running Android 6.0 (API level 23) or higher. This is a compatibility change from Crossbow's previous API 19 minimum.

1. Enable Developer options and USB debugging on your device. Detailed instructions are available in the Android documentation.
2. Using a USB cable, plug your phone into your computer. If prompted on your device, authorize your computer to access your device.

Set up the Android emulator

To prepare to run and test your Crossbow app on the Android emulator, follow these steps if you want to install it from the console:

# Run following command to install System Image for Android SDK 36
crossbundle install sdkmanager --install "system-images;android-36;google_apis;x86_64"
# Run this command to create a new Pnone emulator
avdmanager create avd -n Phone -k "system-images;android-36;google_apis;x86_64"
# And finally run this command to start the emulator
emulator -avd=Phone

If you want to install it from the GUI, follow these instructions:

1. Enable VM acceleration on your machine.
2. Launch Android Studio, click the AVD Manager icon, and select Create Virtual Device.
3. Choose a device definition and select Next.
4. Select one or more system images for the Android versions you want to emulate, and select Next. An x86 or x86_64 image is recommended.
5. Under Emulated Performance, select Hardware - GLES 2.0 to enable hardware acceleration.
6. Verify the AVD configuration is correct, and select Finish. (For details on the above steps, see Managing AVDs)
7. In Android Virtual Device Manager, click Run in the toolbar. The emulator starts up and displays the default canvas for your selected OS version and device.

Add environment variables

If you will build application with emulator you should add this to environment variables:

Install via command line for for macos and linux:

export PATH=<path_to_sdk>\sdk\emulator:$PATH
export PATH=<path_to_sdk>\sdk\tools\bin:$PATH

Install via command line for windows:

• Add <path_to_sdk>\sdk\tools\bin to PATH variable.
• Add <path_to_sdk>\sdk\emulator to PATH variable.

SETX "<path_to_sdk>\sdk\tools\bin" ~PATH~
SETX "<path_to_sdk>\sdk\emulator" ~PATH~

Overview

In this category, you will learn how to use the crossbundle tool.

• Crossbundle build command
• Crossbundle run command
• Crossbundle install command
• Crossbundle doctor command
• Crossbundle new command
• Crossbundle update command

Crossbundle install command

Setup packages

Use crossbundle install command to install necessary packages. To find out available commands specify the -h flag. The -h flag can be used in all subcommands crossbundle install offers.

crossbundle install -h
crossbundle install command-line-tools -h

Install tools to APK building

We offer to use our command to fast installation all required packages.

crossbundle install --preferred

This command will setup command line tools, Android platforms, build-tools, Android NDK and bundletool for AAB correct working. To provide custom installation read the article below.

Install command-line tools

If you do not need Android Studio, you can download the basic Android command line tools below. You can use the included sdkmanager to download other SDK packages.

These tools are included in Android Studio.

To see all available options use the -h flag. To install command line tools use the command:

crossbundle install command-line-tools

The command will download a zip archive and unzip command line tools into $HOME\AppData\Local\Android\Sdk\cmdline-tools\bin for windows and $HOME/Local/Android/Sdk/cmdline-tools/bin for other operating systems. Note: Android studio install cmdline tools into $SDK_ROOT/cmdline-tools/<version>/bin.

Install packages

The sdkmanager is a command-line tool that allows you to view, install, update, and uninstall packages for the Android SDK.

Also you can install packages manually. To see all available tools use the -h flag. List installed and available packages:

crossbundle install sdkmanager --list

And then enter the command.

crossbundle install sdkmanager --install "build-tools;36.0.0" "ndk;28.2.13676358" "platforms;android-36"

The command will install packages into $HOME\AppData\Local\Android\Sdk\ for Windows, $HOME/Library/Android/sdk/ for macOS, and $HOME/Android/sdk/ for Linux.

Install bundletool to AAB building

To install bundletool use command below. To see all available options use the -h flag.

crossbundle install bundletool

The command will download bundletool from GitHub repository and save it into $HOME. Notice, that you should install Java JDK to open bundletool jar file.

Crossbundle doctor command

crossbundle doctor diagnoses every platform enabled when Crossbundle was compiled. It does not search for a project, download tools, install components, generate files, or compile code. Project checks run only when an explicit --project path is supplied.

crossbundle doctor
crossbundle doctor --platform android
crossbundle doctor --platform apple
crossbundle doctor --platform android,apple
crossbundle doctor --platform android --platform apple
crossbundle doctor --project ./Cargo.toml --platform apple

Platform names are typed and case-sensitive. Repeated or comma-delimited values are deduplicated and reported in canonical android, apple order. Requesting an unknown platform, or a known platform excluded from that Crossbundle build, is an invocation error.

Common host and project checks run once. Each selected platform then runs its own checks. On Linux and Windows, Apple-only tooling checks are skip with an explanation. These skips do not fail the report, including under --strict.

Compatibility and strict mode

Compatibility ranges live in crossbundle/tools/Cargo.toml under package.metadata.crossbundle.compatibility:

• A preferred version passes.
• Another supported version passes with a note.
• An unsupported or unrecognized version warns normally and fails with --strict.
• A check that is irrelevant to the host or operation is skipped. Strict mode never promotes skip to fail.

Crossbundle currently checks the discovered Xcode and Apple SDK versions but does not impose an artificial Xcode or SDK version range. Missing required Apple tools on macOS still fail.

Coverage

Common checks cover Cargo, rustc, the selected Cargo package, and typed Crossbow metadata. With --project, package selection reuses the build path's read-only cargo locate-project --message-format plain query; pass a package directory rather than a virtual-workspace root. Android checks cover Java, jarsigner, Gradle, Android SDK platforms and build tools, NDK, adb, bundletool, configured Android targets, assets, resources, manifests, and local Gradle plugins.

Apple checks cover the host OS, full Xcode installation, active developer directory, Xcode version, Command Line Tools, xcodebuild, xcrun, simctl, iPhoneOS and iPhoneSimulator SDK paths and versions, relevant installed Rust targets, and signing relevance. Without a project, doctor checks the simulator target matching the Mac's architecture (aarch64-apple-ios-sim on Apple Silicon or x86_64-apple-ios on Intel). Project checks use the same typed metadata and Info.plist model as Apple builds to validate bundle metadata, bundle identifiers, deployment targets, Rust targets, assets, resources, icons, platform-specific plugin compatibility, and signing configuration applicability. Signing values and command output that may identify credentials are never included in reports. Configured Android Gradle plugins are reported as inapplicable to Apple; ordinary Cargo dependencies are not guessed to be plugins. The typed Apple project model has no project-level signing fields: project.apple.signing warns when a device target requires build-time signing arguments and skips simulator-only projects where signing is irrelevant.

JSON contract

--json writes one JSON document to stdout; human diagnostics and errors go to stderr. Schema version 1 contains:

{
  "schema_version": 1,
  "command": "doctor",
  "scope": "host",
  "strict": false,
  "platforms": ["android", "apple"],
  "status": "pass",
  "summary": { "pass": 0, "warn": 0, "fail": 0, "skip": 0 },
  "checks": []
}

Check states are pass, warn, fail, or skip. Checks and platforms have deterministic ordering, and summary is the exact aggregation of check states.

Stable check IDs

The schema-v1 registry is:

• Common host: host.rust.cargo, host.rust.rustc
• Android host: host.java.runtime, host.java.jarsigner, host.gradle, android.sdk.root, android.sdk.platform, android.sdk.build_tools, android.ndk, android.adb, android.bundletool
• Apple host: apple.host.os, apple.xcode.installation, apple.xcode.version, apple.xcode.developer_dir, apple.xcode.command_line_tools, apple.tool.xcodebuild, apple.tool.xcrun, apple.tool.simctl, apple.sdk.iphoneos, apple.sdk.iphonesimulator, apple.signing.identity, and apple.rust.target.<triple>
• Common project: project.cargo.manifest, project.cargo.package, project.crossbow.metadata
• Android project: project.android.assets, project.android.resources, project.android.icon, project.android.manifest, project.android.targets, project.android.rust_targets, project.android.plugins, project.android.target_sdk, project.android.min_sdk
• Apple project: project.apple.metadata, project.apple.bundle_identifier, project.apple.deployment_target, project.apple.target.<triple>, project.apple.assets, project.apple.icon, project.apple.signing, and project.apple.plugin.<normalized-name>

Dynamic target suffixes are canonical Rust triples. Plugin suffixes are normalized by lowercasing ASCII text, replacing each run of non-alphanumeric characters with one -, trimming leading and trailing separators, and using unnamed if nothing remains.

Exit codes

• 0: no failed checks; warnings and skips are allowed
• 1: one or more checks failed
• 2: invalid invocation, a requested platform is not compiled in, or report serialization failed

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.

Crossbundle run command

Crossbundle run gradle

Crossbow default run 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 run android

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

By default run directory is target/android/<project_name>/gradle. But you can specify your own build directory via --export-path=<OUT_PATH> flag.

Crossbundle run native AAB/APK

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

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

To find out available commands specify the -h flag.

crossbundle run android -h

Crossbundle run iOS

crossbundle run ios builds, installs, and launches the app on an iOS Simulator. Without --target, it builds for the host's Simulator architecture. It prefers an already booted Simulator and otherwise selects one from the newest available iOS runtime. Select a specific Simulator by name or UDID when needed:

crossbundle run ios --simulator "iPhone 17"

For automation, Crossbundle can launch without opening Simulator.app or attaching to the application console:

crossbundle run ios --no-open --detach

Crossbundle new command

crossbundle uses cargo-generate to generate a new project. This means that you need to install it before we proceed.

cargo install cargo-generate

Then you can create a new project:

crossbundle new project-name
# crossbundle new project-name --template bevy
# crossbundle new project-name --template quad

All supported templates you can watch here (each branch = template).

Troubleshooting

You can face the problem with Cargo.toml parsing for the generated project:

Crossbundle Tools error: FailedToFindCargoManifest("...")

To resolve this add your project name to members table of crossbow Cargo.toml:

[workspace]
members = [
    "...",
    "example/",
    "...",
]

Crossbundle update command

Crossbundle has an inner command that allows to check the version used by the user and compare it with the version in crates.io. To check the latest version of crossbundle project in crates.io use:

crossbundle update --check

If the version found in crates.io is newer than used now you can enter the command below:

crossbundle update --force

Overview

In this category, you will learn how to use the crossbow crate.

• Project configuration
• Android plugins
• Permissions

Project configuration

Crossbow's Android baseline is API 36 with a minimum SDK of 23, AGP 9.3.1, Gradle 9.5.0, Java 17, and NDK 28.2. New Google Play submissions must target API 36 from August 31, 2026; see the official target API requirements.

Configuration through metadata

The easiest way to configure a project is with metadata. Here's an example of Cargo.toml:

[package]
name = "game"
version = "0.1.0"
authors = ["Example <[email protected]>"]
edition = "2024"

[dependencies]
crossbow = "0.2.3"

[package.metadata]
# The user-friendly application name for your app. Displayed in the applications menu
app_name = "Game"
# Android assets directory path relative to the project path
assets = ["assets"]
# Path to icon with `.png` format that will be provided to generate mipmap resources
icon = "path/to/icon.png"

# Explicitly import build-time environment variables. Undeclared environment variables are never
# available to configuration templates.
[package.metadata.build_variables]
API_HOST = { env = "API_HOST" }
BUILD_NUMBER = { env = "CI_BUILD_NUMBER", type = "integer" }
APP_CHANNEL = { env = "APP_CHANNEL", default = "development" }
FEATURE_ENABLED = { env = "FEATURE_ENABLED", type = "boolean", default = false }

[package.metadata.android]
# Optional activity integration. The default is "native-activity"; use
# "miniquad" for Macroquad projects built with the Gradle strategy.
runtime = "native-activity"
# Android targets to build on debug or release.
debug_build_targets = ["aarch64-linux-android"]
release_build_targets = ["aarch64-linux-android"]
# Android resources directory path relatively to project path
resources = ["res/android"]

# Complete support of all AndroidManifest.xml attributes
[package.metadata.android.manifest]
package = "com.example.ExampleProject"

# Adds a uses-permission element to the AndroidManifest.xml.
# Note that android_version 23 and higher, Android requires the application to request permissions at runtime
[[package.metadata.android.manifest.uses_permission]]
name = "android.permission.INTERNET"
# Specifies that an app wants a particular permission, but only if the app is installed on a device running
# Android 6.0 (API level 23) or higher. If the device is running API level 22 or lower, the app does not have the specified permission.

# See https://developer.android.com/guide/topics/manifest/uses-permission-sdk-23-element
[[package.metadata.android.manifest.uses_permission_sdk_23]]
name = "android.permission.WRITE_EXTERNAL_STORAGE"
max_sdk_version = 30

# See https://developer.android.com/guide/topics/manifest/service-element
[[package.metadata.android.manifest.service]]
name = "UpdateService"
intent_filter = []
meta_data = []

# See https://developer.android.com/guide/topics/manifest/queries-element#provider
[[package.metadata.android.manifest.queries.provider]]
authorities = "org.khronos.openxr.runtime_broker;org.khronos.openxr.system_runtime_broker"
# The `android-manifest` model currently requires `name` even though Android queries providers
# normally require only `authorities`.
name = "org.khronos.openxr"

# See https://developer.android.com/guide/topics/manifest/uses-feature-element
#
# Note: there can be multiple .uses_feature entries.
[[package.metadata.android.manifest.features]]
name = "android.hardware.vulkan.level"
required = true
version = 1

# See https://developer.android.com/guide/topics/manifest/meta-data-element
[[package.metadata.android.manifest.application.meta_data]]
name = "com.oculus.vr.focusaware"
value = "true"

[package.metadata.apple]
# iOS targets to build in debug or release mode.
debug_build_targets = ["aarch64-apple-ios-sim"]
release_build_targets = ["aarch64-apple-ios"]
# Apple resources directory path relatively to project path.
resources = ["res/apple"]

Build variables

Build variables let the same checked-in configuration produce environment-specific Android and Apple bundles. Declare every imported value under package.metadata.build_variables, then use it as {{crossbow.NAME}} in an inline platform document, an external AndroidManifest.xml, or an external Info.plist:

<!-- AndroidManifest.xml -->
<meta-data
    android:name="com.example.api_host"
    android:value="https://{{crossbow.API_HOST}}/v1" />

<!-- Info.plist -->
<key>APIHost</key>
<string>{{crossbow.API_HOST}}</string>

Crossbundle reads the named environment variable first and uses default only when it is absent; an empty environment value therefore overrides the default. A missing value without a default stops the build with the declaration name. The default type is string; type = "integer" and type = "boolean" validate environment input and preserve the native type when the placeholder is the complete metadata or plist value. A placeholder embedded inside a larger string is formatted as text. Variable values cannot contain other build-variable placeholders.

Only allow-listed variables are readable. The syntax intentionally does not conflict with Android ${applicationId} placeholders or Xcode $(PRODUCT_BUNDLE_IDENTIFIER) build settings. XML special characters and Unicode are escaped by the platform serializers, and both XML and binary plists are supported.

Build variables are public application configuration, not secrets. Values embedded in AndroidManifest.xml or Info.plist can be inspected by anyone with the built application. Do not use this feature for passwords, signing credentials, private keys, or API secrets.

Configuration through separate files

For more complex configuration, use separate AndroidManifest.xml and/or Info.plist files.

To enable this feature, you just need to add this to your Cargo.toml:

[package.metadata.android]
manifest_path = "/path/to/file"

[package.metadata.apple]
info_plist_path = "/path/to/file"

and then place AndroidManifest.xml and/or Info.plist near Cargo.toml.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.rust.game"
    android:versionCode="1"
    android:versionName="1.0">
    <uses-sdk android:minSdkVersion="23"
        android:targetSdkVersion="36" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <application android:allowBackup="true"
        android:hasCode="false"
        android:icon="@mipmap/ic_launcher"
        android:label="Game"
        android:theme="@android:style/Theme.DeviceDefault.NoActionBar.Fullscreen">
        <activity android:name="com.rust.game.MainActivity"
            android:label="Game"
            android:configChanges="orientation|keyboardHidden|screenSize">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

That's it, this config file will be used for your mobile application.

Crossbow permissions

To request permissions with Crossbow you will need to add crossbow dependency to your Cargo.toml file. And add permissions to AndroidManifest.xml or Info.plist:

# This one:
[package.metadata]
permissions = ["camera", "microphone", "photos", "storage-read"]

# Will make the same as this one:
[[package.metadata.android.manifest.uses_permission]]
name = "android.permission.READ_EXTERNAL_STORAGE"
[[package.metadata.android.manifest.uses_permission]]
name = "android.permission.CAMERA"
[[package.metadata.android.manifest.uses_permission]]
name = "android.permission.RECORD_AUDIO"

[package.metadata.apple.info_plist]
NSCameraUsageDescription = "This app needs access to your phone's camera."
NSMicrophoneUsageDescription = "This app needs access to your phone's microphone."
NSPhotoLibraryUsageDescription = "This app needs access to your phone's photo library."

Then invoke request_async function. This function checks the permission status in the application and will request permission if it's not granted yet:

#![allow(unused)]
fn main() {
use crossbow::Permission;
let res = Permission::Camera.request_async().await?;
match res {
    Permission::Unknown => println!("Permission is in an unknown state"),
    Permission::Denied => println!("Denied by user"),
    Permission::Disabled => println!("Feature is disabled on device."),
    Permission::Granted => println!("Granted by user."),
    Permission::Restricted => println!("Restricted (only iOS)."),
}
}

Also, remember to set permissions in through Cargo.toml or Info.plist/AndroidManifest.xml files. List of required permissions for Cross-Platform Permission you can find in Permission enum.

See usage example.

Also, it's possible to request more permissions with this API:

#[cfg(target_os = "android")]
crossbow::android::permission::*;
let res = request_permission(&AndroidPermission::ReadCalendar).await?;

// or this for iOS:

#[cfg(target_os = "ios")]
crossbow::ios::permission::*;
let res = request_permission(&IosPermission::CaptureDevice(MediaType::Audio)).await;

Maybe useful

Useful commands to debug permission status in Android application using adb:

adb shell pm reset-permissions
adb shell pm list permission-groups
adb shell pm list permissions

adb shell pm grant <app package> <permission name>
adb shell pm revoke <app package> <permission name>

Crossbow Android Plugins

To write new Crossbow Android plugin - we recommend to clone this repository and use crossbow-admob as template for your plugin.

To do so, run these commands:

git clone https://github.com/dodorare/crossbow
cp -r crossbow/plugins/admob-android ./my-awesome-plugin
cd ./my-awesome-plugin

In Rust project you will need to update Cargo.toml and code in src/ folder.

Now in Android gradle project you will able to write your own Android plugin in Java or Kotlin!

Building

To build Android Gradle plugin you need to run the following command:

gradle build

Testing locally

To import your plugin into your game with Crossbow you can add following in Cargo.toml:

[[package.metadata.android.plugins_local_projects]]
include = ":my-awesome-plugin"
project_dir = "../my-awesome-plugin/android"

It will try to find your plugin by the specified path relative to your Cargo.toml.

Publishing to Github Maven repository

To publish your plugin to Github Maven repository you need a Personal Access Token from your Github account. Pass credentials through environment variables; never commit a token to a Gradle file.

To read more about Github Maven repository visit Publishing Github Maven packages.

As you setup everything - you can run the following command to publish your plugin to Maven repository:

USERNAME=<NAME> TOKEN=<TOKEN> gradle publish

To publish your plugin to crates.io - you can see this official article.

Using Published plugin

After successfully publishing your plugin you can use it in your game. To do so you will want to import it in Cargo.toml:

[dependencies]
my_awesome_plugin = "0.1.0"

[[package.metadata.android]]
plugins_remote = ["com.crossbow.awesome:my_awesome_plugin:0.1.0"]

That's it, now you can use your plugin in your game!

GitHub Packages requires authentication when resolving remote plugins. Export GITHUB_ACTOR and a GITHUB_TOKEN with read:packages, or set the Gradle properties crossbow.github.username and crossbow.github.token, before running crossbundle.

Overview

In this category, you will learn how to use the crossbundle tool and crossbow crate by examples and tutorials.

To get started - open Hello World example to see minimal project setup.

Hello world example

Generate a project

Generate new project with crossbundle new command!

Project overview

The project has been created. Now let's see what the project consists of.

The code below is belong to the native crossbow project with pure rust without android plugins. To see all possibilities of cargo.toml see crossbow configutarion tutorial

# Cargo.toml

[package]
name = "project-name"
version = "0.1.0"
authors = ["Example <[email protected]>"]
edition = "2024"

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

[dependencies]
crossbow = "*"

[target.'cfg(target_os = "android")'.dependencies]
android-activity = { version = "0.6", features = ["native-activity"] }

[package.metadata]
app_name = "My Project"
icon = "path/to/icon.png"

Put the shared application code and Android entry point in lib.rs:

// lib.rs
pub fn main() {
    println!("Hello, project-name!");
}

#[cfg(target_os = "android")]
#[unsafe(no_mangle)]
pub fn android_main(_app: android_activity::AndroidApp) {
    main();
}

Keep the desktop binary as a one-line wrapper:

// main.rs
fn main() {
    project_name::main();
}

Build an application

Let's build and run our first crossbundle application. Android commands below will generate gradle project and install apk on your device. See crossbundle run command for additional information.

cd project-name. To attach a logger when application deploys on your device use --log flag.

crossbundle run android --log

or

crossbundle run ios --log

If you want to build the application for android as native AAB - add -s=native-aab flag or add -s=native-apk to build native APK.

You will see the message: "Hello, project-name!"

In-app updates tutorial

Important: First of all you need to install crossbundle if you haven't already. See documention to install it.

Generate a project

crossbundle uses cargo-generate to generate a new project. This means that you need to install it before we proceed.

cargo install cargo-generate

Then you can create a new project:

crossbundle new project-name --template quad

All supported templates you can watch here (each branch = template).

Installation

Important: Before starting please read more about Google Play Core libraries and In-app updates.

Add Rust dependencies like this:

[dependencies]
crossbow = "0.2.3"
[target.'cfg(target_os = "android")'.dependencies]
play-core = "0.2.3"

And finally, add this to your Crossbow Android configuration:

[package.metadata.android]
plugins_remote = ["com.crossbow.play_core:play_core:0.2.3"]

That's it, now you can start using Play Core!

Usage

First step is plugin initialization. In your rust project, you will need to initialize Crossbow instance and then get Android plugin:

#![allow(unused)]
#![cfg(target_os = "android")]

fn main() {
use crossbow::android::*;
let crossbow = CrossbowInstance::new();
let play_core: play_core::PlayCorePlugin = crossbow.get_plugin()?;
}

After plugin initialization you can use supported features. For example to start connection and query purchases you can use:

#![allow(unused)]
fn main() {
play_core.check_update()?;
play_core.in_progress_update()?;
}

To read signals that plugin returns:

#![allow(unused)]
fn main() {
if let Ok(signal) = play_core.get_receiver().recv().await {
    println!("Signal: {:?}", signal);
}
}

Complete documentation of plugin you can find here.

Build an application

Let's build and run this application. Android command below will generate gradle project and install apk on your device. See crossbundle run command for additional information.

crossbundle run android

But to be able to test In-app updates - you will need to publish your application to Play Store as Internal testing or any other (Closed testing or Production, etc.).

To publish your app to Play Store - you will want to export gradle project with this command:

crossbundle build android --export-path=./path/

Then in generated project add signing to build.gradle like this:

signingConfigs {
    release {
        if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
            storeFile file(MYAPP_UPLOAD_STORE_FILE)
            storePassword MYAPP_UPLOAD_STORE_PASSWORD
            keyAlias MYAPP_UPLOAD_KEY_ALIAS
            keyPassword MYAPP_UPLOAD_KEY_PASSWORD
        }
    }
}
buildTypes {
    release {
        signingConfig signingConfigs.release
    }
}

and in gradle.properties actual values:

MYAPP_UPLOAD_STORE_FILE=my-project.keystore
MYAPP_UPLOAD_KEY_ALIAS=my-project
MYAPP_UPLOAD_STORE_PASSWORD=123456
MYAPP_UPLOAD_KEY_PASSWORD=123456

You can read more here, and here.

Google Play Billing tutorial

Important: First of all you need to install crossbundle if you haven't already. See documention to install it.

Generate a project

crossbundle uses cargo-generate to generate a new project. This means that you need to install it before we proceed.

cargo install cargo-generate

Then you can create a new project:

crossbundle new project-name --template quad

All supported templates you can watch here (each branch = template).

Installation

Important: Before using this plugin please follow instructions on Getting ready Google Play Billing official guide.

Just add Rust dependencies like this:

[dependencies]
crossbow = "0.2.3"
[target.'cfg(target_os = "android")'.dependencies]
play-billing = "0.2.3"

And finally, add this to your Crossbow Android configuration:

[package.metadata.android]
plugins_remote = ["com.crossbow.play_billing:play_billing:0.2.3"]

That's it, now you can start using Play Billing!

Usage

First step is plugin initialization. In your rust project, you will need to initialize Crossbow instance and then get Android plugin:

#![allow(unused)]
#![cfg(target_os = "android")]

fn main() {
use crossbow::android::*;
let crossbow = CrossbowInstance::new();
let play_billing: play_billing::PlayBillingPlugin = crossbow.get_plugin()?;
}

After plugin initialization you can use supported features. For example to start connection and query purchases you can use:

#![allow(unused)]
fn main() {
play_billing.start_connection()?;
play_billing.query_product_details(&["YOUR_PRODUCT_ID"], "inapp")?;
play_billing.query_purchases("inapp")?;
}

Crossbow uses Play Billing Library 9. Subscription products expose base plans, pricing phases, and offer tokens through product_details_query_completed; pass the selected token to purchase_with_offer. For subscription changes, call replace_subscription with the existing purchase token, old and new product IDs, selected offer token, and replacement mode. Billing 9 requires the existing purchase token even when product-level replacement parameters identify the old product.

To read signals:

#![allow(unused)]
fn main() {
if let Ok(signal) = play_billing.get_receiver().recv().await {
    println!("Signal: {:?}", signal);
}
}

Complete documentation you can find here.

Build an application

Important: Read officialtutorial on how to test Google Play Billing for more information here.

Let's build and run this application. Android command below will generate gradle project and install apk on your device. See crossbundle run command for additional information.

crossbundle run android

But to be able to test In-app purchases - you will need to add Products in Google Play Console. And then build and sign your app with your generated keystore.

To publish your app to Play Store Internal Testing - you will want to export gradle project with this command:

crossbundle build android --export-path=./path/

Then in generated project add signing to build.gradle like this:

signingConfigs {
    release {
        if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
            storeFile file(MYAPP_UPLOAD_STORE_FILE)
            storePassword MYAPP_UPLOAD_STORE_PASSWORD
            keyAlias MYAPP_UPLOAD_KEY_ALIAS
            keyPassword MYAPP_UPLOAD_KEY_PASSWORD
        }
    }
}
buildTypes {
    release {
        signingConfig signingConfigs.release
    }
}

and in gradle.properties actual values:

MYAPP_UPLOAD_STORE_FILE=my-project.keystore
MYAPP_UPLOAD_KEY_ALIAS=my-project
MYAPP_UPLOAD_STORE_PASSWORD=123456
MYAPP_UPLOAD_KEY_PASSWORD=123456

You can read more here, and here.

Fastlane automation for Android

We want to make you work less on the hard stuff behind the automation of publishing Rust mobile apps so we prepared some best practices on how you can automate the boring stuff with our creator Fastlane plugin. You can read more about Fastlane here.

Setup

First of all, we would suggest you pass through our crossbow basic tutorials for Android or/and iOS.

After you got familiar with crossbow you can get to the following steps to run Fastlane locally:

1. Make sure you have crossbundle installed.
2. Install Fastlane.
3. Setup XCode or Android Studio depending on which platform you want to run your workflow.
4. Create a test project (you can use our template) or add Fastlane to your project.
5. Install our fastlane plugin with the next command fastlane add_plugin crossbow.

Setup for Play Market

1. Open Google Play Console (you will need a developer account for this).
2. Click on the button "Create app" and specify your application data in the form.
3. Generate signing key through Android Studio as shown in this official tutorial.
4. Generate a "Play Store Json Key" for Fastlane as shown here.
5. Configure corresponding variables in fastlane/Fastfile file.

Run lane

To run our Fastlane pipeline just call fastlane android or fastlane ios at the root of the project.

Please note, Fastlane will ask you to log in on the first run to configure the setup.

See results

After the successful finish of publishing as an internal testing draft, you should see your release on the Google Play Console. Find section "Testing" and click on the "Internal testing". You will see something like this:

Feel free to add some other lanes to fill your needs, here's the full list of them.

If you found a bug or issue - you can find or create an issue in this repository.

Contributing

If you want to help us build an awesome Cross-Platform future for Rust Games, please reach out! We need all the help we can get:

• If you are a software developer and you want to help out, check out the Contributing Code section.
• If you are good at writing or teaching, consider Contributing to our Docs.

Also, read testing guide to run tests in crossbow.

How to Contribute Code

Would you like to contribute code to Crossbow? Here's how!

1. Fork the dodorare/crossbow repository on GitHub, you'll need to create a GitHub account if you don't have one already.*
2. Make your changes in a local clone of your fork.
3. For a higher chance of CI passing the first time, consider run these commands from the root of your local clone:
   1. cargo fmt --all -- --check (remove --check to let the command fix found problems)
   2. cargo clippy --all-targets --all-features --locked -- -D warnings -A clippy::unnecessary-unwrap -A clippy::too-many-arguments -A clippy::result_large_err
   3. cargo test --all-targets --workspace --locked on macOS, or add --exclude crossbow-ios on non-Apple hosts. The crossbow-ios package links Apple frameworks and is tested separately by macOS CI.
4. Push your changes to your fork and open a Pull Request.
5. Respond to any CI failures or review feedback.

The same steps apply for any other repository in the organization that you would like to contribute to.

How to Contribute Docs

Crossbow Documentation

If you want to contribute to this documentation, please see the Contributing section.

1. Fork the dodorare/crossbow repository on GitHub, you'll need to create a GitHub account if you don't have one already.*
2. Install mdBook.
3. In the "docs/" directory, run mdbook serve --open and make your changes in a local clone of your fork.
4. Push your changes to your fork and open a Pull Request.
5. Respond to any CI failures or review feedback.

That's all, big thanks for contributing!

The same steps apply for any other repository in the organization that you would like to contribute to.

Testing guide

How to run tests in crossbow

In crossbow, we have unit tests, integration tests, and examples. To run tests, you will need to set up an Android and Apple environment (you can find more information in installation category).

If you want to run tests for our crossbundle crate, you can make it by the following steps: download this repository, proceed to the crossbundle/tools directory, and run cargo test. It will run all tests for the crossbundle-tools crate that is primarily used by crossbundle.

Dependency updates

Crossbow commits the workspace Cargo.lock because the workspace ships the crossbundle executable. Required CI, release, publishing, and installation checks use --locked so that a commit is always tested with its reviewed dependency graph.

Dependabot checks for Cargo updates every week and opens pull requests that update the manifests and lockfile. Minor and patch updates are grouped; major updates remain separate so their compatibility can be reviewed independently.

The Latest compatible dependencies workflow provides an additional early-warning check every week and on demand. It generates a new lockfile from the manifests and runs the complete non-iOS workspace test suite against that fresh resolution. Pull-request CI tests the iOS-only package and Apple feature set on macOS. The scheduled workflow does not replace or gate the reproducible checks run on pull requests.

Android stack versions are canonical in [package.metadata.crossbundle.compatibility] in crossbundle/tools/Cargo.toml. After changing them, run cargo run -p xtask --locked -- android-stack sync to update the standalone Gradle projects. Replace sync with check to verify every operative declaration.

In case of issues

Feel free to open Github Issues - we will be happy to fix or review them.

Contributors

Here is a list of the contributors who have helped improving Crossbow. Big shout-out to them!

• David (enfipy) - Project Lead
• Daniil (Heezay)
• Oleksii (olvyko)
• Adil (Adoka3710)
• Rodrigo (rodrigocam)

Development Roadmap

✅ = Works and tested — 🆗 = Works but may contain bugs — 🛠 = Under development — 📝 = Planned

Useful links

• https://developers.google.com/games/services/common/concepts/sign-in
• https://developers.google.com/games/services/downloads/sdks
• https://developers.google.com/games/services/cpp/GettingStartedNativeClient
• https://developers.google.com/identity/sign-in/web/build-button
• https://github.com/cgisca/PGSGP
• https://docs.godotengine.org/en/stable/tutorials/platform/ios/ios_plugin.html
• https://github.com/polyhorn/simctl
• https://docs.godotengine.org/en/stable/tutorials/plugins/android/android_plugin.html
• https://github.com/godotengine/godot-google-play-billing
• https://github.com/google/play-unity-plugins
• https://android.googlesource.com/platform/frameworks/opt/gamesdk
• https://developer.android.com/games/develop/permissions
• https://docs.microsoft.com/en-gb/xamarin/essentials
• https://docs.microsoft.com/en-us/xamarin/essentials/permissions

Special Thanks

This project initially funded by Web3 Foundation Grants Program. Big shout-out to them!

If you want to support this project - contact us on our corporate email: [email protected].