The Rust compiler has been supporting Android for a long time now. However when you ask rustc to compile for Android, what it produces is an executable that you can only run through debugging tools. When we talk about developing for Android, what we usually want is an apk or Android package. An apk is a file that contains the Android application in addition to various resource files and that can be installed then run by an average user.
To automate building an apk, you may have heard of the
android-rs-glue repository, which Servo uses. Through a weird trick, it would capture the arguments that rustc passed to the linker and instead manually invoke the linker itself, then setup a build directory and run the normal Android package building process.
One of the difficult part of setting up an Android environment was compiling Rust for Android. This would require some steps are not necessarily easy for everyone. But now that the Rustup utility appeared, you can obtain an Android-compatible with just
rustup target add arm-linux-androideabi. Now only the only difficult part left was setting up android-rs-glue.
A few days ago, I started reworking the content of
android-rs-glue to make it much easier to use. The initial part of the rework has just landed.
Now, all you need to do is to compile for Android is:
- Download the Android SDK and NDK, unzip them somewhere, and export the
ANDROID_HOME environment variables to point to their content.
- Obtain an Android-compatible rustc. If you installed rustup, this is done with
rustup target add arm-linux-androideabi.
cargo install cargo-apk.
In the future this may be even more simplified by the fact that
rustup could automatically distribute the NDK.
Now go to your project's path and run
cargo apk install. Provided that all the libraries you use support Android, you won't need to make any modification to your source code.
This should build your crate just like any other crate, except that the final output is an Android package that runs the
main function of your program at startup. Once this is done, it automatically runs
adb install -r <path to apk> to install the app on your device so you can test it. If you don't want to install the package, just run
If you run
cargo apk on a hello world program, starting the application will write
hello world to the logs and show a black screen. This is obviously not very useful.
In order to interface with the Android environment, you will need to use the
android_glue crate. This crate provides the functions required to capture user input and draw to the window through OpenGL or Vulkan.
It is important to note, however, that no function will allow you to get a native Android UI. This build system and this library are meant for applications that handle everything themselves, like video games. If you want a regular app you should write in Java.
Customizing the apk
In order to customize the apk, you can put additional elements in your Cargo.toml, like the basic example shows. Only a few values exist yet. This remains to be documented.
A few notes
- Contributors are welcome! Your contributions is even more valuable if you are familiar with Android apps development in general. Even if you are afraid of the technical complexity there are a lot of areas where work is needed, like being able to costumize the app's icon, or handling non-debug builds.
- Apps that use glutin should work out of the box, as glutin supports
android_glue. EDIT: glutin hasn't been updated yet, so if you try now you will get the old version of android_glue and likely a panic.
- For the moment
cargo-apk only runs on Linux 64bits because of this precise line of code. PRs welcome!
- Cargo-apk supports Android packages that provide multiple binaries for multiple platforms. Unfortunately this isn't customizable yet and it defaults to just