{"id":389,"date":"2022-01-31T11:18:51","date_gmt":"2022-01-31T11:18:51","guid":{"rendered":"https:\/\/blog.mozilla.org\/data\/?p=389"},"modified":"2022-01-31T11:18:51","modified_gmt":"2022-01-31T11:18:51","slug":"this-week-in-glean-building-and-deploying-a-rust-library-on-ios","status":"publish","type":"post","link":"https:\/\/blog.mozilla.org\/data\/2022\/01\/31\/this-week-in-glean-building-and-deploying-a-rust-library-on-ios\/","title":{"rendered":"This Week in Glean: Building and Deploying a Rust library on iOS"},"content":{"rendered":"

(\u201cThis Week in Glean\u201d is a series of blog posts that the Glean Team at Mozilla is using to try to communicate better about our work. They could be release notes, documentation, hopes, dreams, or whatever: so long as it is inspired by Glean.) All \u201cThis Week in Glean\u201d blog posts are listed in the TWiG index<\/a> (and on the Mozilla Data blog<\/a>).<\/p>\n

\n

We ship the Glean SDK for multiple platforms, one of them being iOS applications. Previously I talked about how we got it to build on the Apple ARM machines<\/a>. Today we will take a closer look at how to bundle a Rust static library into an iOS application.<\/p>\n

The Glean SDK project was set up in 2019 and we have evolved its project configuration over time. A lot has changed in Xcode since then, so for this article we\u2019re starting with a fresh Xcode project, a fresh Rust library and put it all together step by step.
\nThis is essentially an update to the Building and Deploying a Rust library on iOS<\/a> article from 2017.<\/p>\n

For future readers: This was done using Xcode 13.2.1 and rustc 1.58.1.
\nOne note: I learned iOS development to the extent required to ship Glean iOS. I\u2019ve never written a full iOS application and lack a lot of experience with Xcode.<\/em><\/p>\n

The application<\/h2>\n

The premise of our application is easy:<\/p>\n

\n

Show a non-interactive message to the user with data from a Rust library.<\/p>\n<\/blockquote>\n

Let\u2019s get started on that.<\/p>\n

The project<\/h2>\n

We start with a fresh iOS project. Go to File -> New -> Project, then choose the iOS App template, give it a name such as ShippingRust<\/code>, select where to store it and finally create it. You\u2019re greeted with ContentView.swift<\/code> and the following code:<\/p>\n

import SwiftUI\r\n\r\nstruct ContentView: View {\r\n    var body: some View {\r\n        Text("Hello, world!")\r\n            .padding()\r\n    }\r\n}<\/code><\/pre>\n
You can build and run it now. This will open the Simulator and display \u201cHello, world!\u201d. We\u2019ll get back to the Swift application later.<\/p>\n
The Rust parts<\/h2>\n
First we set up the Rust library.<\/p>\n
In a terminal navigate to your ShippingRust<\/code> project directory. In there create a new Rust crate:<\/p>\n
\n
<\/a>cargo<\/span> new --lib<\/span> shipping-rust-ffi<\/span><\/code><\/pre>\n<\/div>\n
We will need a static library, so we change the crate type in the generated shipping-rust-ffi\/Cargo.toml<\/code>. Add the following below the package configuration:<\/p>\n
\n
<\/a>[<\/span>lib<\/span>]<\/span><\/span>\r\n<\/a>crate-type<\/span> =<\/span> [<\/span>"staticlib"<\/span>]<\/span><\/span><\/code><\/pre>\n<\/div>\n
Let\u2019s also turn the project into a Cargo workspace. Create a new top-level Cargo.toml<\/code> with the content:<\/p>\n
\n
<\/a>[<\/span>workspace<\/span>]<\/span><\/span>\r\n<\/a>members<\/span> =<\/span> [<\/span><\/span>\r\n<\/a>  "shipping-rust-ffi"<\/span><\/span>\r\n<\/a>]<\/span><\/span><\/code><\/pre>\n<\/div>\n
cargo build<\/code> in the project directory should work now and create a new static library.<\/p>\n
\n
<\/a>$<\/span> ls -l<\/span> target\/debug\/libshipping_rust_ffi.a<\/span>\r\n<\/a>-rw-r--r--<\/span> 2 jer staff 16061952 Jan 28 13:09 target\/debug\/libshipping_rust_ffi.a<\/span><\/code><\/pre>\n<\/div>\n
Let\u2019s add some code to shipping-rust-ffi\/src\/lib.rs<\/code> next. Nothing fancy, a simple function taking some arguments and returning the sum:<\/p>\n
\n
<\/a>use<\/span> std::os::raw::<\/span>c_int<\/span>;<\/span><\/span>\r\n<\/a><\/span>\r\n<\/a>#[<\/span>no_mangle]<\/span><\/span>\r\n<\/a>pub<\/span> extern<\/span> "C"<\/span> fn<\/span> shipping_rust_addition(a:<\/span> c_int<\/span>,<\/span> b:<\/span> c_int<\/span>) -><\/span> c_int<\/span> {<\/span><\/span>\r\n<\/a>    a +<\/span> b<\/span>\r\n<\/a>}<\/span><\/span><\/code><\/pre>\n<\/div>\n
The no_mangle<\/code> ensures the name lands in the compiled library as-is and the extern \"C\"<\/code> makes sure it uses the right ABI.<\/p>\n
We now have a Rust library exporting a C-ABI compatible interface. We can now consume this in our iOS application.<\/p>\n
The Xcode parts<\/h2>\n
Before we can use the code we need a bit more setup. Strap in, there\u2019s a lot of fiddly manual steps now1<\/sup><\/a>.<\/p>\n
We start by linking against the libshipping_rust_ffi.a<\/code> library. In your Xcode project open your target configuration2<\/sup><\/a>, go to \u201cBuild Phases\u201d, then look for \u201cLink Binary with Libraries\u201d. Add a new one, in the popup select \u201cAdd files\u201d on the bottom left and look for the target\/debug\/libshipping_rust_ffi.a<\/code> file. Yes, that\u2019s actually for the wrong target. This is just for the name, we\u2019ll fix up the path next. Go to \u201cBuild Settings\u201d and search for \u201cLibrary Search Paths\u201d. It probably has the path to file in there right now for both Debug<\/code> and Release<\/code> builds. Remove that one for Debug<\/code>, then add a new row by clicking the small +<\/code> symbol. Select the Any Driverkit<\/code> matcher. It doesn\u2019t matter which matcher you choose or what value you give it, but when we overwrite this manually in the next step I\u2019ll assume you chose Any Driverkit<\/code>. Do the same for the Release<\/code> configuration.<\/p>\n
Once that\u2019s done, save your project and go back to your project directory. We will modify the project configuration to have Xcode look for the library based on the target it is building for3<\/sup><\/a>. Open up ShippingRust.xcodeproj\/project.pbxproj<\/code> in a text editor, then search for the first line with \"LIBRARY_SEARCH_PATHS[sdk=driverkit*]\"<\/code>. It should be in a section saying \/* Debug *\/<\/code>. Remove the LIBRARY_SEARCH_PATHS<\/code> line and add 3 new ones:<\/p>\n
"LIBRARY_SEARCH_PATHS[sdk=iphoneos*][arch=arm64]" = "$(PROJECT_DIR)\/target\/aarch64-apple-ios\/debug";\r\n"LIBRARY_SEARCH_PATHS[sdk=iphonesimulator*][arch=arm64]" = "$(PROJECT_DIR)\/target\/aarch64-apple-ios-sim\/debug";\r\n"LIBRARY_SEARCH_PATHS[sdk=iphonesimulator*][arch=x86_64]" = "$(PROJECT_DIR)\/target\/x86_64-apple-ios\/debug";<\/code><\/pre>\n
Look for the next line with \"LIBRARY_SEARCH_PATHS[sdk=driverkit*]\"<\/code>, now in a \/* Release *\/<\/code> section and replace it with:<\/p>\n
"LIBRARY_SEARCH_PATHS[sdk=iphoneos*][arch=arm64]" = "$(PROJECT_DIR)\/target\/aarch64-apple-ios\/release";\r\n"LIBRARY_SEARCH_PATHS[sdk=iphonesimulator*][arch=arm64]" = "$(PROJECT_DIR)\/target\/aarch64-apple-ios-sim\/release";\r\n"LIBRARY_SEARCH_PATHS[sdk=iphonesimulator*][arch=x86_64]" = "$(PROJECT_DIR)\/target\/x86_64-apple-ios\/release";<\/code><\/pre>\n
Save the file and return focus back to Xcode. If you didn\u2019t make any typos Xcode should still have your project open. In the settings you will find the library search paths as we\u2019ve just defined them. If you messed something up Xcode will complain that it cannot read the project file if you try to go to the settings.<\/p>\n
Next we need to teach Xcode how to compile Rust code. Once again go to your target settings, selecting the \u201cBuild Phases\u201d tab again.<\/p>\n
There add a new \u201cRun Script\u201d phase, give it the name \u201cBuild Rust library\u201d (double-click the \u201cRun Script\u201d section header), and set the command to:<\/p>\n
\n
<\/a>bash<\/span> ${PROJECT_DIR}<\/span>\/bin\/compile-library.sh shipping-rust-ffi $buildvariant<\/span><\/span><\/code><\/pre>\n<\/div>\n
The compile-library.sh<\/code> script is going to do the heavy lifting. The first argument is the crate name we want to compile, the second is the build variant to select. This is not yet defined, so let\u2019s do it first.<\/p>\n
Go to the \u201cBuild Settings\u201d tab and click the +<\/code> button to add a new \u201cUser-Defined Setting\u201d. Give it the name buildvariant<\/code> and choose a value based on the build variant: debug<\/code> for Debug<\/code> and release<\/code> for Release<\/code>.<\/p>\n
Now we need the actual script to build the Rust library for the right targets. It\u2019s a bit long to write out, but the logic is not too complex: First we select the Cargo profile to use based on our buildvariant<\/code> (that is whether to pass --release<\/code> or not), then we set up LIBRARY_PATH<\/code> if necessary and finally compile the Rust library for the selected target. Xcode passes the architectures to build in ARCHS<\/code>. It\u2019s either x86_64<\/code> for simulator builds on Intel Mac hardware or arm64<\/code>. If it\u2019s arm64<\/code> it can be either the simulator or an actual hardware target. Those differ, but we can know which is which from what\u2019s in LLVM_TARGET_TRIPLE_SUFFIX<\/code> and select the right Rust target.<\/p>\n
Let\u2019s put all of that into a compile-library.sh<\/code> script. Create a new directory bin<\/code> in your project directory. In there create the file with the following content:<\/p>\n
\n
<\/a>#!\/usr\/bin\/env bash<\/span><\/span>\r\n<\/a><\/span>\r\n<\/a>if<\/span> [<\/span> "<\/span>$#<\/span>"<\/span> -ne<\/span> 2 ]<\/span><\/span>\r\n<\/a>then<\/span><\/span>\r\n<\/a>    echo<\/span> "Usage (note: only call inside xcode!):"<\/span><\/span>\r\n<\/a>    echo<\/span> "compile-library.sh <FFI_TARGET> <buildvariant>"<\/span><\/span>\r\n<\/a>    exit<\/span> 1<\/span>\r\n<\/a>fi<\/span><\/span>\r\n<\/a><\/span>\r\n<\/a># what to pass to cargo build -p, e.g. your_lib_ffi<\/span><\/span>\r\n<\/a>FFI_TARGET=$1<\/span><\/span>\r\n<\/a># buildvariant from our xcconfigs<\/span><\/span>\r\n<\/a>BUILDVARIANT=$2<\/span><\/span>\r\n<\/a><\/span>\r\n<\/a>RELFLAG=<\/span><\/span>\r\n<\/a>if<\/span> [[<\/span> "<\/span>$BUILDVARIANT<\/span>"<\/span> !=<\/span> "debug"<\/span> ]];<\/span> then<\/span><\/span>\r\n<\/a>  RELFLAG=<\/span>--release<\/span>\r\n<\/a>fi<\/span><\/span>\r\n<\/a><\/span>\r\n<\/a>set<\/span> -euvx<\/span><\/span>\r\n<\/a><\/span>\r\n<\/a>if<\/span> [[<\/span> -n<\/span> "<\/span>${DEVELOPER_SDK_DIR<\/span>:-<\/span>}<\/span>"<\/span> ]];<\/span> then<\/span><\/span>\r\n<\/a>  # Assume we're in Xcode, which means we're probably cross-compiling.<\/span><\/span>\r\n<\/a>  # In this case, we need to add an extra library search path for build scripts and proc-macros,<\/span><\/span>\r\n<\/a>  # which run on the host instead of the target.<\/span><\/span>\r\n<\/a>  # (macOS Big Sur does not have linkable libraries in \/usr\/lib\/.)<\/span><\/span>\r\n<\/a>  export<\/span> LIBRARY_PATH=<\/span>"<\/span>${DEVELOPER_SDK_DIR}<\/span>\/MacOSX.sdk\/usr\/lib:<\/span>${LIBRARY_PATH<\/span>:-<\/span>}<\/span>"<\/span><\/span>\r\n<\/a>fi<\/span><\/span>\r\n<\/a><\/span>\r\n<\/a>IS_SIMULATOR=<\/span>0<\/span>\r\n<\/a>if<\/span> [<\/span> "<\/span>${LLVM_TARGET_TRIPLE_SUFFIX<\/span>-<\/span>}<\/span>"<\/span> =<\/span> "-simulator"<\/span> ]<\/span>;<\/span> then<\/span><\/span>\r\n<\/a>  IS_SIMULATOR=<\/span>1<\/span>\r\n<\/a>fi<\/span><\/span>\r\n<\/a><\/span>\r\n<\/a>for<\/span> arch in<\/span> $ARCHS<\/span>;<\/span> do<\/span><\/span>\r\n<\/a>  case<\/span> "<\/span>$arch<\/span>"<\/span> in<\/span><\/span>\r\n<\/a>    x86_64)<\/span><\/span>\r\n<\/a>      if<\/span> [<\/span> $IS_SIMULATOR<\/span> -eq<\/span> 0 ]<\/span>;<\/span> then<\/span><\/span>\r\n<\/a>        echo<\/span> "Building for x86_64, but not a simulator build. What's going on?"<\/span> >&<\/span>2<\/span><\/span>\r\n<\/a>        exit<\/span> 2<\/span>\r\n<\/a>      fi<\/span><\/span>\r\n<\/a><\/span>\r\n<\/a>      # Intel iOS simulator<\/span><\/span>\r\n<\/a>      export<\/span> CFLAGS_x86_64_apple_ios=<\/span>"-target x86_64-apple-ios"<\/span><\/span>\r\n<\/a>      $HOME<\/span>\/.cargo\/bin\/cargo<\/span> build -p<\/span> $FFI_TARGET<\/span> --lib<\/span> $RELFLAG<\/span> --target<\/span> x86_64-apple-ios<\/span>\r\n<\/a>      ;;<\/span><\/span>\r\n<\/a><\/span>\r\n<\/a>    arm64)<\/span><\/span>\r\n<\/a>      if<\/span> [<\/span> $IS_SIMULATOR<\/span> -eq<\/span> 0 ]<\/span>;<\/span> then<\/span><\/span>\r\n<\/a>        # Hardware iOS targets<\/span><\/span>\r\n<\/a>        $HOME<\/span>\/.cargo\/bin\/cargo<\/span> build -p<\/span> $FFI_TARGET<\/span> --lib<\/span> $RELFLAG<\/span> --target<\/span> aarch64-apple-ios<\/span>\r\n<\/a>      else<\/span><\/span>\r\n<\/a>        $HOME<\/span>\/.cargo\/bin\/cargo<\/span> build -p<\/span> $FFI_TARGET<\/span> --lib<\/span> $RELFLAG<\/span> --target<\/span> aarch64-apple-ios-sim<\/span>\r\n<\/a>      fi<\/span><\/span>\r\n<\/a>  esac<\/span><\/span>\r\n<\/a>done<\/span><\/span><\/code><\/pre>\n<\/div>\n
And now we\u2019re done with the setup for compiling the Rust library automatically as part of the Xcode project build.<\/p>\n
The code parts<\/h2>\n
We now have an Xcode project that builds our Rust library and links against it. We now need to use this library!<\/p>\n
Swift speaks Objective-C, which is an extension to C, but we need to tell it about the things available. In C land that\u2019s done with a header. Let\u2019s create a new file, select the \u201cHeader File\u201d template and name it FfiBridge.h<\/code>. This will create a new file with this content:<\/p>\n
\n
<\/a>#ifndef FfiBridge_h<\/span><\/span>\r\n<\/a>#define FfiBridge_h<\/span><\/span>\r\n<\/a><\/span>\r\n<\/a><\/span>\r\n<\/a>#endif <\/span>\/* FfiBridge_h *\/<\/span><\/span><\/code><\/pre>\n<\/div>\n
Here we need to add the definition of our function. As a reminder this is its definition in Rust:<\/p>\n
\n
<\/a>extern<\/span> "C"<\/span> fn<\/span> shipping_rust_addition(a:<\/span> c_int<\/span>,<\/span> b:<\/span> c_int<\/span>) -><\/span> c_int<\/span>;<\/span><\/span><\/code><\/pre>\n<\/div>\n
This translates to the following in C:<\/p>\n
\n
<\/a>int<\/span> shipping_rust_addition(int<\/span> a, int<\/span> b);<\/span><\/code><\/pre>\n<\/div>\n
Add that line between the #define<\/code> and #endif<\/code> lines. Xcode doesn\u2019t know about that file yet, so once more into the Build Settings<\/code> of the target. Search for Objective-C Bridging Header<\/code> and set it to $(PROJECT_DIR)\/ShippingRust\/FfiBridge.h<\/code>. In Build Phases<\/code> add a new Header Phase<\/code>. There you add the FfiBridge.h<\/code> as well.<\/p>\n
If it now all compiles we\u2019re finally ready to use our Rust library.<\/p>\n
Open up ContentView.swift<\/code> and change the code to call your Rust library:<\/p>\n
struct ContentView: View {\r\n    var body: some View {\r\n        Text("Hello, world! \\(shipping_rust_addition(30, 1))")\r\n            .padding()\r\n    }\r\n}<\/code><\/pre>\n
We simply interpolate the result of shipping_rust_addition(30, 1)<\/code> into the string displayed.<\/p>\n
Once we compile and run it in the simulator we see we\u2019ve succeeded at satisfying our premise:<\/p>\n
\n
Show a non-interactive message to the user with data from a Rust library.<\/p>\n<\/blockquote>\n
\n\"iOS
iOS simulator running our application showing \u201cHello, world! 31\u201d<\/figcaption><\/figure>\n
Compiling for any iOS device should work just as well.<\/p>\n
The next steps<\/h2>\n
This was a lot of setup for calling one simple function. Luckily this is a one-time setup. From here on you can extend your Rust library, define them in the header file and call them from Swift. If you go that route you should really start using cbindgen<\/a> to generate that header file automatically for you.<\/p>\n
This time we looked at building an iOS application directly calling a Rust library. That\u2019s not actually how Glean works. The Glean Swift SDK itself wraps the Rust library and exposes a Swift library. In a next blog post I\u2019ll showcase how we ship that as a Swift package.<\/p>\n
For Glean we\u2019re stepping away from manually writing our FFI functions. We\u2019re instead migrating our code base to use UniFFI<\/a>. UniFFI will generate the C API from an API definitions file and also comes with a bit of runtime code to handle conversion between Rust, C and Swift data types for us. We\u2019re not there yet for Glean, but you can try it on your own. Read the UniFFI documentation<\/a> and integrate it into your project. It should be possible to extent the setup we done her to also run the necessary steps for UniFFI. Eventually I\u2019ll document how we did it as well.<\/p>\n
\n
Footnotes:<\/em><\/p>\n
\n
\n
    \n
  1. \n
    And most of these steps are user-interface-dependent and might be different in future Xcode version. \ud83d\ude41\u21a9\ufe0e<\/a><\/p>\n<\/li>\n
  2. \n
    Click your project name in the tree view on the left. This gets you to the project configuration (backed by the ShippingRust.xcodeproj\/project.pbxproj<\/code> file). You should then see the Targets, including your ShippingRust<\/code> target and probably ShippingRustTests<\/code> as well. We need the former.\u21a9\ufe0e<\/a><\/p>\n<\/li>\n
  3. \n
    Previously we would have built a universal library containing the library of multiple targets. That doesn\u2019t work anymore now that arm64<\/code> can stand for both the simulator and hardware targets. Thus linking to the individual libraries is the way to go, as the now-deprecated cargo-lipo<\/code><\/a> also points out.\u21a9\ufe0e<\/a><\/p>\n<\/li>\n<\/ol>\n<\/section>\n","protected":false},"excerpt":{"rendered":"
    (\u201cThis Week in Glean\u201d is a series of blog posts that the Glean Team at Mozilla is using to try to communicate better about our work. They could be release … Read more<\/a><\/p>\n","protected":false},"author":1756,"featured_media":197,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[448297],"tags":[],"coauthors":[],"_links":{"self":[{"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/posts\/389"}],"collection":[{"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/users\/1756"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/comments?post=389"}],"version-history":[{"count":0,"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/posts\/389\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/media\/197"}],"wp:attachment":[{"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/media?parent=389"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/categories?post=389"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/tags?post=389"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/coauthors?post=389"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}