How to Use Cargo Piston

Once you have cargo-piston installed (either locally within a repo or globally) and your .env and Cargo.toml are properly configured, you can use cargo-piston to build and run for various targets. Your desired targets should be installed via rustup and should match your host system's architecture.

Example

rustup target add aarch64-apple-darwin

Example command for building with piston

cargo piston build --target aarch64-apple-darwin

This command will build a Macos binary within a dynamically created app bundle derived from the information contained within your cargo.toml and .env. This includes ordinarily tedious minutia such as an Info.plist and app icon configuration.

Tested & Supported Build Targets

In theory this tool should support build targets for all of the supported Operting Systems, but they will only be added explicitly after being tested. If you test any of the unsupported targets in main.rs please let me know by opening an issue on the github repo.

Windows

x86_64-pc-windows-gnu

Android

aarch64-linux-android

x86_64-linux-android

IOS

aarch64-apple-ios

x86_64-apple-ios

MacOS

aarch64-apple-darwin

x86_64-apple-darwin

Linux

aarch64-unknown-linux-gnu

x86_64-unknown-linux-gnu

Configuration

.ENV configuration

Path to cargo binary (if not in your local PATH) example

cargo_path=/Users/<username>/.cargo/bin/cargo

If Building for Linux on MacOS

zigbuild_path=/Users/<username>/.cargo/bin/cargo-zigbuild homebrew_path=/opt/homebrew/bin

General Cargo.toml configuration

App Icon example

[package.metadata]
icon_path = "absolute/path/to/icon.png

Installing locally from source

Run the following command within your rust project repo to install the package locally cargo install --path ../path/to/cargo-piston

Windows Output Configuration

Install mingw-w64 via homebrew (required on MACOS only)

brew install mingw-w64

After installing mingw-w64, add the path to the linker to your global ~/.cargo.config.toml

[target.x86_64-pc-windows-gnu]
linker = path/to/homebrew/bin/x86_64-w64-mingw32-gcc

App Icon

You must have embed-resource in your Cargo.toml as a [build dependency]

[build dependency]
embed-resource = "3.0.2"

Linux Output Configuration

Install zigbuild via (required on MACOS ONLY)

cargo install cargo-zigbuild Provide a path to your cargo dependency binaries (somewhere like ~/.cargo/bin) zigbuild_path=/Users/<username>/.cargo/bin/cargo-zigbuild

Install Zig via homebrew (required on MACOS ONLY)

provide a path to your homebrew binaries (somewhere like /opt/homebrew/bin) in your .env homebrew_path=/opt/homebrew/bin

MacOS Output Configuration

IOS Output Configuration

Android Output Configuration

Install Java

Install Java and provide the path to the installation in your .env file

One option is to download the Java installer

https://www.oracle.com/in/java/technologies/downloads/#jdk25-mac

Example terminal install command (Macos)

brew install openjdk@17

set the path to the binary in your .env

Example .env entries (Macos)

macos arm64 installer /usr/bin/java

aarch64 (homebrew) java_path=/opt/homebrew/openjdk@17

silicone chipset (homebrew) java_path=/usr/local/opt/openjdk@17

Example install command (Linux)

sudo apt update

sudo apt install -y openjdk-17-jdk

Example .env entry (Linux)

java_path=/usr/lib/jvm/java-17-openjdk-amd64

Install Android Command-line tools

Install the android NDK & SDK and provide the paths to the installation in your .env file.

Example install commands

Download & Install command line tools

SDK url Repository (MacOS)

https://dl.google.com/android/repository/commandlinetools-mac-11076708_latest.zip

SDK url Repository (Linux)

https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip

Download the file

curl -o </path/to/downloads> <sdk_url_from_above>

Create an install dir and unzip the file (replace $HOME with your absolute path)

mkdir <$HOME>/Android/sdk

unzip -o </path/to/downloads>/cmdline-tools.zip -d <$HOME>/Android/sdk

Accept android SDK licenses

yes | JAVA_HOME=<PATH/TO/JAVA> sudo <$HOME>/Android/sdk/cmdline-tools/bin/sdkmanager --licenses --sdk_root=<$HOME>/Android/sdk || echo "Failed to accept the license"

Note: if you installed java manually instead of using the installer you may need to set the JAVA_HOME var in your PATH or pass in the environment variabnle as shown above and below.

Install Android SDK & NDK

Install platform-tools

JAVA_HOME="</path/to/java>" sudo </path/to/sdkmanager> "platform-tools" --sdk_root=</path/to/sdk>

Install build-tools;34.0.0

JAVA_HOME="</path/to/java>" sudo </path/to/sdkmanager> "build-tools;34.0.0" --sdk_root=</path/to/sdk>

Install platforms;android-34

JAVA_HOME="</path/to/java>" sudo </path/to/sdkmanager> "platforms;android-34" --sdk_root=</path/to/sdk>

Install ndk;25.1.8937393

JAVA_HOME="</path/to/java>" sudo </path/to/sdkmanager> "ndk;25.1.8937393" --sdk_root=</path/to/sdk>

Set the paths to the binaries in your .env (replace $HOME with your absolute path)

Examples (MacOS)

sdk_path=<$HOME>/Android/sdk

ndk_path=<$HOME>/Android/sdk/ndk/26.1.10909125

Install Android Bundle tool

Install Android bundletool

https://github.com/google/bundletool/releases

or install with brew on macos

brew install bundletool

It is reccomended that you install your bundletools .jar within your Android directory, something like $HOME/Android/sdk/bundle-tools

Set the path to your bundle tool .jar in your .env

Examples

bundletool_path=<$HOME>/Android/sdk/bundle-tools/bundletool.jar

or

bundletool_path=/opt/homebrew/bundletool

Android Cargo.Toml configuration

Add the following dependencies

[dependencies]
android-activity = { version = "0.5", features = ["native-activity"] }
log = "0.4"

your Cargo.toml must have the following library designation

[lib]
name="<app_name>"
crate-type=["cdylib"]

your target_sdk_version must be installed in your ~Android/sdk/platforms path

[package.metadata.android]
target_sdk_version=31

Create a Lib.rs in ~/src

Unlike other outputs, android apps require first building a cdylib, we've already designated those settings in the cargo.toml, however, your project must also contain a ~/src/lib.rs file with a main activity.

Example lib.rs

use android_activity::AndroidApp;

#[unsafe(no_mangle)]
pub extern "C" fn android_main(app: AndroidApp) {
    loop {
        log::info!("Hello from Rust on Android!");
    }
}