Building an iOS App in Rust, Part 1: Getting Started with Rust

Editor’s note: This is the first post in our series on building an iOS app in Rust.

The vast majority of apps that get developed for iOS and Android are written in the native languages provided by the platform: Swift or Objective-C on iOS, and Java on Android. I don’t expect that to change any time soon; however, sometimes there’s a need for something more.

If you’re developing an app on multiple platforms more or less independently, you’ll face certain challenges. Functionality will be duplicated (obviously), which means you have two different codebases that need to be maintained. Bugs can crop up on one platform or the other or both, and new features have to be added to each. An alternative approach, which Dropbox talked about at last year’s UIKonf and CppCon (video 1, video 2), is to develop a library that can be shared by both platforms.

Developing a cross-platform library is challenging for a number of reasons, not the least of which that the choice of language is pretty limited. There are some tools, like Google’s J2ObjC, which allow you to write in one platform’s language (Java, in this case) and have it automatically translated into another platform’s language (Objective-C). A more traditional approach is to develop in C or C++, languages that are portable to both platforms and that can be called by both platforms.

I’m not going to try and sell you on the merits of going down this road—there are big pros and big cons. I suspect that this approach is probably the wrong one for most applications, but it’s still a very interesting area to explore. C++ is the reigning king of the hill for portable, native library development, but there’s a new challenger with an exciting amount of development behind it.

Rust describes itself as “a systems programming language that runs blazingly fast, prevents almost all crashes and eliminates data races.” It’s been in development for quite a while (about eight years, at the time of this writing), and the Rust team released version 1.0 on May 15 of this year.

Rust is often compared with Go (probably because they entered the public eye around the same time and both described themselves as systems programming languages), but the comparison isn’t really fair to either: they have very different aims in mind. Rust’s goal is to be a safer alternative to C++ without giving up the control and performance that C++ provides.

Roadmap

This post is the first in a (long) series. We’re going to end up with a simple but nontrivial app that can ask Flickr for its recent photos, display thumbnails in a UICollectionView and show the full image when a thumbnail is tapped:

The trick is that we’re going to put all the smarts in the Rust layer. We’ll roughly follow an MVVM (Model—View—View Model) architecture where the Model and View Model layers are implemented in Rust, and the iOS side is just the View layer. (This app is a variant of one that you’ll build while going through the next edition of our iOS Programming Guide, to be published in the second half of 2015.)

While the app is simple, we’ll touch on a lot of advanced topics getting Rust and iOS to play nicely together. Here’s the plan for this blog series:

1. Getting Started with Rust on iOS (that’s this post)
2. Passing Data between Rust and iOS
3. Sharing a View Model between Rust and iOS
4. Writing a Flickr Client in Rust
5. Tying it All Together: Rustorama

I’ll cover some basic Rust syntax as we go through the post, but if this is your first experience with the language, consider reading through the Rust book. I’ll be glossing over some fairly advanced things in the later posts out of necessity.

Installing Rust with multirust

This section assumes you’re running Mac OS X and have not installed Rust. If either of those isn’t true, you’ll need to tweak these instructions.

There are three different versions of the Rust compiler available at any given time: stable, beta and nightly. Every six weeks, the current nightly becomes the new beta and the current beta becomes the new stable; this is called the six-week train model.

A slick tool for managing multiple Rust installations is multirust. We’ll use it to manage a version of the Rust compiler for targeting iOS.

Go ahead and install multirust and set the nightly as your default Rust compiler. (I’ve omitted copying the instructions from the multirust repository in case they change in the future, but at the moment, there’s a one-liner you can run to set everything up.) You should be able to replicate the following, although your build dates and version hashes will be different:

$ multirust show-default
multirust: default toolchain: nightly
multirust: default location: /Users/john/.multirust/toolchains/nightly

rustc 1.1.0-nightly (c42c1e7a6 2015-05-02) (built 2015-05-01)
cargo 0.2.0-nightly (efb482d 2015-04-30) (built 2015-05-01)

$ rustc -V
rustc 1.1.0-nightly (c42c1e7a6 2015-05-02) (built 2015-05-01)

Try a “Hello, World” program:

$ cat > hello-world.rs
fn main() {
    println!("Hello, world!");
}
<Ctrl-D>
$ rustc hello-world.rs
$ ./hello-world
Hello, world!

Building a Cross Compiler

This part is not for the faint of time: this will take at least an hour, maybe a few. We need to build a Rust toolchain that can create executables for all five iOS platforms: armv7, armv7s, arm64 and the 32- and 64-bit simulators. We’re going to build off of the master branch, the same as the nightly releases.

First, clone the Rust compiler’s repository and get its submodules (this assumes you have SSH set up with Github; feel free to clone however you normally would):

$ git clone git@github.com:rust-lang/rust.git
$ cd rust
$ git submodule update --init --recursive

Next, create a subdirectory for all the build artifacts and cd into it:

$ mkdir build
$ cd build

Finally, configure the build to target all five architectures, and set up an appropriate installation prefix. In the following, we’ll install to our home directory:

$ ../configure --target=armv7-apple-ios,armv7s-apple-ios,i386-apple-ios,aarch64-apple-ios,x86_64-apple-ios --prefix=$HOME/rustc-ios
... snipping lots of output ...

At last, start the build:

$ make -j8 && make install

Go watch a movie or something; come back when your laptop fans stop spinning.

All done? Let’s tell multirust about your brand new toolchain, naming it ios:

$ multirust update ios --link-local $HOME/rustc-ios
multirust: creating link from /Users/john/rustc-ios

One final cleanup step. multirust expects to be able to find Cargo, Rust’s package manager and build tool extraordinaire, but we’ve only installed the Rust compiler itself. We don’t really need to go and build Cargo, because the Rust nightly you installed in the previous section also installed Cargo. Instead, we can create a symlink in the right place:

$ ln -s $HOME/.multirust/toolchains/nightly/bin/cargo $HOME/rustc-ios/bin

Ask multirust to run your ios version of rustc and Cargo, just to make sure all is well:

$ multirust run ios rustc -V
rustc 1.1.0-dev (ce1150b9f 2015-05-04) (built 2015-05-03)
$ multirust run ios cargo -V
cargo 0.2.0-nightly (efb482d 2015-04-30) (built 2015-05-01)

Hello, World: Building the Rust Library

Now that all the painful waiting is done, let’s get to the fun part: writing a Rust library and calling it from an iOS app. Create a clean working space somewhere, and create directories to hold the Rust component and the iOS component:

$ mkdir -p rust-ios-part-1/{ios,rust}
$ cd rust-ios-part-1

You probably noticed above that we were able to use multirust run ios ... to run commands from the ios toolchain we installed. It would be awfully tedious to type that every time, so multirust provides a directory-level override. Set that up now, so that any Rust commands you issue in this directory (or any descendent directory) will use your ios toolchain:

$ multirust override ios
multirust: using existing install for 'ios'
multirust: override toolchain for '/Users/john/rust-ios-app-part-1' set to 'ios'

We’ll build the Rust library first. Change into your rust directory and tell Cargo to create a new library called hello for you:

$ cd rust
$ cargo new hello
$ cd hello

If you dig around under hello, you’ll find two files:

• Cargo.toml is the manifest file describing your library. Cargo.toml is like a Rust-specific Makefile. It contains the names of your input files and any library or executable targets your project defines, as well as any dependencies your project uses.

• src/lib.rs is the placeholder file created for you. This is where we’ll put whatever Rust code we write. (In later posts we’ll use more files, but this one is fine for “Hello, world.”)

Let’s start by updating src/lib.rs. There are Rust plugins for many popular editors; Google around for yours if you’d like. Delete the default code in src/lib.rs and replace it with this:

#[no_mangle]
pub extern fn rust_hello_world() -> i32 {
    println!("Hello, I'm in Rust code! I'm about to return 10.");
    10
}

Walking through each line:

1. #[no_mangle] tells the Rust compiler not to perform its default name mangling on the function name. This will result in the rust_hello_world symbol being exported just like it would if it had been written in C.
2. pub marks the function as public, i.e., callable by code outside of this library. extern fn tells the Rust compiler to use C calling conventions for this function, meaning any language that knows how to call C functions can now call this Rust function. rust_hello_world() is the name of the function; the empty parentheses indicate it takes no arguments. -> i32 states that the return value of this function is an i32, i.e., a 32-bit signed integer.
3. println!("..."); will print the string on stdout. It’s analogous to Swift’s println function. (The ! means that println! in Rust is actually a macro, but that’s not important for our purposes.)
4. 10, as the last line of the function without a semicolon, is the value returned by the function. Rust does have a return keyword, so we could have written return 10; instead, but that isn’t idiomatic. The Rust book’s functions chapter discusses this in more detail.

At this point, if you were developing a normal Rust library, you could build it via cargo build and go about your merry way. We have a few more steps to take to build a library suitable for iOS, though. By default, Cargo will create libhello.rlib, where rlib stands for “Rust library.” We need a traditional static library, so update Cargo.toml, adding the [lib] section below:

[package]
name = "hello"
version = "0.1.0"
authors = ["John Gallagher <jgallagher@bignerdranch.com>"]

[lib]
name = "hello"
crate-type = ["staticlib"]

Now we can tell Cargo to build a static library, and we’ll specify that we want one for the 64-bit iOS simulator:

$ cargo build --target x86_64-apple-ios
   Compiling hello v0.1.0 (file:///Users/john/github/bignerdranch/rust-ios-app-part-1/rust/hello)
note: link against the following native artifacts when linking against this static library
note: the order and any duplication can be significant on some platforms, and so may need to be preserved
note: library: System
note: library: objc
note: framework: Foundation
note: framework: Security
note: library: pthread
note: library: c
note: library: m
$ ls target/x86_64-apple-ios/debug/
build/      deps/       examples/   libhello.a  native/

For real development, we’ll actually want to use lipo to create a fat library for all five iOS architectures. That isn’t something currently supported by Cargo, so there is a Makefile in the repo for this blog post that will tell Cargo to build all five architectures and then combine them into a fat library.

There’s one last thing we need: a C header file that we can import on the iOS side. There isn’t a tool (yet) for creating C headers for a Rust library, so we will create a header manually. Still in your rust directory, create hello.h and give it the following contents:

#pragma once

#include <stdint.h>

int32_t rust_hello_world(void);

This type signature matches our Rust function above: it takes no arguments and returns a 32-bit signed integer.

Hello, World: Building the iOS App

Hop into Xcode and create a new Single-View project. Put it into the rust-ios-part-1/ios directory you created above. I’ll assume you want to use Swift; if you’re using Objective-C, things are actually simpler, so you can probably manage just fine.

Find the hello.h and libhello.a files you created in the previous section, and drag them both into your Xcode project. (Make sure you grab the libhello.a under target/x86_64-apple-ios/debug, or the one you created using the Makefile, if you did that.) In order for your Swift code to be able to see hello.h, you need to include it in your app’s bridging header. By default, Swift projects don’t have one. You can either create one manually or add a new class to your project, select Objective-C as the language, click “Yes” when Xcode asks if you want a bridging header, then delete the Objective-C files.

Once you have a bridging header, add hello.h to it:

//
//  Use this file to import your target's public headers that you would like
//  to expose to Swift.
//
#import "hello.h"

Open up AppDelegate.swift, and try calling your Rust function:

func application(application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?)
    -> Bool
{
    let result = rust_hello_world()
    println("I called Rust and got \(result)")
    return true
}

Try to build and run your app. You’ll need to have a 64-bit simulator selected, such as the iPhone 6 simulator. If you get a linker error about missing the symbol _rust_hello_world, make sure you added the correct libhello.a to your app target.

You should see the following in the Xcode console:

Hello, I'm in Rust code! I'm about to return 10.
I called Rust and got 10

Congratulations! You’ve written a Rust library and used it on iOS!

Next Steps

In the next post, we’ll build on all the setup you’ve done. We’ll talk about how to pass non-primitive data types like strings to and from Rust, as well as how to pass more complicated data structures and objects. Stay tuned!

All the code, both Rust and Swift, from this post is on GitHub.

Editor’s note: Be sure to check out the other posts in this series: Part 2, Part 3.