# Crossbundle CLI ![splash](https://github.com/dodorare/crossbow/blob/main/assets/crossbow/splash.png?raw=true) [![Crate Info](https://img.shields.io/crates/v/crossbundle.svg)](https://crates.io/crates/crossbundle) [![Documentation](https://img.shields.io/badge/docs.rs-crossbundle-green)](https://docs.rs/crossbundle/) [![MIT/Apache 2.0](https://img.shields.io/badge/license-MIT%2FApache-blue.svg)](https://github.com/dodorare/crossbow#license) [![GitHub Stars](https://img.shields.io/github/stars/dodorare/crossbow.svg?style=social)](https://github.com/dodorare/crossbow/stargazers) 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**): | Name | Status | | ---- | ------ | | Windows | ✅ | | Linux | ✅ | | macOS | ✅ | Packaging Strategy status: | Name | Description | Status | | ---- | ----------- | ------ | | Android APK | Supported via `-s=native-apk` flag. | ✅ | | Android AAB | Supported via `-s=native-aab` flag. | ✅ | | Android Gradle | Supported via `-s=gradle-apk` flag. | ✅ | | Apple Debug APP | Default build strategy. Works only on Simulator and could be run on iPhone with Dev Certificate. | ✅ | | Apple Debug IPA | Works only on Simulator and could be run on iPhone with Dev Certificate. | 🆗 | | Apple Release IPA | Not supported yet. Crossbundle should generate `xcodeproj`, but user should build and sign IPA manually. | 🛠 | Supported game engines: | Name | Description | Status | | ---- | ----------- | ------ | | [Bevy](https://github.com/bevyengine/bevy) | Default build method. Injects [ndk-glue](https://github.com/rust-windowing/android-ndk-rs/tree/master/ndk-glue) into generated tmp `lib.rs` file. | 🆗 | | [Macroquad](https://github.com/not-fl3/macroquad) | Supported via `app_wrapper = "quad"` inside `Cargo.toml` metadata. Also, can work as [cargo-quad-apk](https://github.com/not-fl3/cargo-quad-apk) but with all `crossbundle` features. | ✅ | | **placeholder** | Don't find your game engine here? Open an issue! We are happy to add support for new engines. | 🛠 | ✅ = Works and tested — 🆗 = Works but may contain bugs — 🛠 = Under development ## Installation ```sh cargo install --git=https://github.com/dodorare/crossbow crossbundle ``` See [installation documentation](https://crossbow.dodorare.com/install/index.html) for more details on how to setup environment on your platform. ## Cargo.toml Metadata syntax ```toml [[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`: ```sh crossbundle -h crossbundle build android -h crossbundle run ios -h crossbundle install -h # ... ``` Result of `crossbundle -h`: ```text USAGE: crossbundle [OPTIONS] OPTIONS: -c, --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`): ```text 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 Build the specified example --export-path Path to export Gradle project. By default exports to `target/android/` folder --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 `/` syntax. This flag may be specified multiple times, which enables all specified features -h, --help Print help information --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 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 Signing key alias --sign-key-pass Signing key password --sign-key-path Path to the signing key -t, --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 Directory for generated artifact and intermediate files ``` Result of `crossbundle build ios -h` (this command extends `crossbundle build ios`): ```text 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 Specify custom cargo binary -d, --debug Run in debug mode -d, --device Install and launch on the connected device -D, --device-id Connected device id --example Build the specified example --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 `/` syntax. This flag may be specified multiple times, which enables all specified features -h, --help Print help information --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 Provisioning profile name to find in this directory: `~/Library/MobileDevice/Provisioning\ Profiles/` --profile-path Absolute path to provisioning profile --release Build optimized artifact with the `release` profile -s, --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 device name [default: "iPhone 13"] -t, --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 Directory for generated artifact and intermediate files --team-identifier The team identifier of your signing identity ``` ## Troubleshooting ### Shared library "" 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///tools/libname.so`. The builder will pick the library up and put it in the final package. ## License Licensed under [MIT](../../LICENSE-MIT) or [Apache-2.0](../../LICENSE-APACHE).