Crossbundle CLI

The crossbundle is a command-line tool that encapsulates boring stuff of Android and iOS build/packaging processes and helps mobile developers to create and maintain applications written in rust programming language.

Support status

Supported operating systems for build (iOS only on macOS):

Packaging Strategy status:

Supported game engines:

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

Installation

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

See installation documentation for more details on how to setup environment on your platform.

Cargo.toml Metadata syntax

[[package.metadata]]
# Cross-platform user-friendly application name for your app.
app_name = "Example"
# Cross-platform assets directory path relatively to project path.
assets = ["assets"]
# Cross-platform icon path to generate icons for Android and iOS.
icon = "../../assets/images/icon.png"

[[package.metadata.android]]
# Android application wrapper: supports ndk-glue and quad
app_wrapper = "quad"
# The user-friendly application name for your app. Displayed in the applications menu
app_name = "Example"
# Path to AndroidManifest.xml file
manifest_path = "path/to/AndroidManifest.xml"
# Android resources directory path relatively to project path.
resources = ["res/android"]
# Android assets directory path relatively to project path.
assets = ["assets"]
# Android targets to build on debug or release.
debug_build_targets = ["aarch64-linux-android"]
release_build_targets = ["aarch64-linux-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 = 31

# 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"
# Note: The `name` attribute is normally not required for a queries provider, but is non-optional
# as a workaround for aapt throwing errors about missing `android:name` attribute.
# This will be made optional if/when cargo-apk migrates to aapt2.
name = "org.khronos.openxr"

# 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]
# Apple targets to build on debug or release.
debug_build_targets = ["aarch64-apple-ios"]
release_build_targets = ["aarch64-apple-ios", "x86_64-apple-ios"]
# Apple resources directory path relatively to project path.
resources = ["res/apple"]

CLI options and flags

To see the complete documentation for each command/subcommand you can write -h or --help:

crossbundle -h
crossbundle build android -h
crossbundle run ios -h
crossbundle install -h
# ...

Result of crossbundle -h:

USAGE:
    crossbundle [OPTIONS] <SUBCOMMAND>

OPTIONS:
    -c, --current-dir <CURRENT_DIR>    The current directory where to run all commands
    -h, --help                         Print help information
    -q, --quiet                        No output printed to stdout
    -v, --verbose                      A level of verbosity, and can be used multiple times
    -V, --version                      Print version information

SUBCOMMANDS:
    build      Starts the process of building/packaging/signing of the rust crate
    help       Print this message or the help of the given subcommand(s)
    install    Installs bundletool and Android Studio's sdkmanager
    new        Creates a new Cargo package in the given directory. Project will be ready to
               build with `crossbundle`
    run        Executes `build` command and then deploy and launches the application on the
               device/emulator

Result of crossbundle run android -h (this command extends crossbundle build android):

Executes `build` command and then deploy and launches the application on the Android device/emulator

USAGE:
    crossbundle run android [OPTIONS]

OPTIONS:
    --all-features
        Activate all available features of selected package

    --example <EXAMPLE>
        Build the specified example

    --export-path <EXPORT_PATH>
        Path to export Gradle project. By default exports to `target/android/` folder

    --features <FEATURES>
        Space or comma separated list of features to activate. These features only apply to the
        current directory's package. Features of direct dependencies may be enabled with
        `<dep-name>/<feature-name>` syntax. This flag may be specified multiple times, which
        enables all specified features

    -h, --help
        Print help information

    --lib <LIB>
        Only compile rust code as a dynamic library. By default: "crossbow-android"

    --log
        Enable logging attach after run

    --no-default-features
        Do not activate the `default` feature of the current directory's package

    --release
        Build optimized artifact with the `release` profile

    -s, --strategy <STRATEGY>
        Build strategy specifies what and how to build Android application: with help of Gradle,
        or with our native approach [default: gradle-apk]

    --sign-key-alias <SIGN_KEY_ALIAS>
        Signing key alias

    --sign-key-pass <SIGN_KEY_PASS>
        Signing key password

    --sign-key-path <SIGN_KEY_PATH>
        Path to the signing key

    -t, --target <TARGET>...
        Build for the given android architecture. Supported targets are:
        `armv7-linux-androideabi`, `aarch64-linux-android`, `i686-linux-android`,
        `x86_64-linux-android`

    --target-dir <TARGET_DIR>
        Directory for generated artifact and intermediate files

Result of crossbundle build ios -h (this command extends crossbundle build ios):

Executes `build` command and then deploy and launches the application on the iOS device/emulator

USAGE:
    crossbundle run ios [OPTIONS]

OPTIONS:
    --all-features
        Activate all available features of selected package

    --bin <BIN>
        Specify custom cargo binary

    -d, --debug
        Run in debug mode

    -d, --device
        Install and launch on the connected device

    -D, --device-id <DEVICE_ID>
        Connected device id

    --example <EXAMPLE>
        Build the specified example

    --features <FEATURES>
        Space or comma separated list of features to activate. These features only apply to the
        current directory's package. Features of direct dependencies may be enabled with
        `<dep-name>/<feature-name>` syntax. This flag may be specified multiple times, which
        enables all specified features

    -h, --help
        Print help information

    --identity <IDENTITY>
        The id of the identity used for signing. It won't start the signing process until you
        provide this flag

    --no-default-features
        Do not activate the `default` feature of the current directory's package

    --profile-name <PROFILE_NAME>
        Provisioning profile name to find in this directory:
        `~/Library/MobileDevice/Provisioning\ Profiles/`

    --profile-path <PROFILE_PATH>
        Absolute path to provisioning profile

    --release
        Build optimized artifact with the `release` profile

    -s, --strategy <STRATEGY>
        Build strategy specifies what and how to build iOS application: with help of XCode, or
        with our native approach [default: native-ipa]

    -s, --simulator-name <SIMULATOR_NAME>
        Simulator device name [default: "iPhone 13"]

    -t, --target <TARGET>...
        Build for the given apple architecture. Supported targets are: `aarch64-apple-ios`,
        `aarch64-apple-ios-sim`, `armv7-apple-ios`, `armv7s-apple-ios`, `i386-apple-ios`,
        `x86_64-apple-ios`

    --target-dir <TARGET_DIR>
        Directory for generated artifact and intermediate files

    --team-identifier <TEAM_IDENTIFIER>
        The team identifier of your signing identity

Troubleshooting

Shared library "<lib_name>" not found

If you ran into problem of missing shared library in the apk/aab - you can fix this by placing your .so file into target/<rust-triple>/<profile>/tools/libname.so. The builder will pick the library up and put it in the final package.

License

Licensed under MIT or Apache-2.0.