1  # Compiling Arti for iOS
  2  
  3  ## Limitation
  4  At the moment of writing this guide, Arti does not have a stable Rust API yet. For that reason, no proper bindings are provided.
  5  You'll need to write these bindings yourself by leveraging Rust FFI for C.
  6  
  7  There are also rough edges, which will hopefully get polished over time. Most of these should be explained below.
  8  
  9  This guide assumes you already have installed Cargo and XCode (but not that you used both together).
 10  
 11  Apple requires to have MacOS installed to develop iOS apps, this guide won't work for Linux, Windows or other BSDs.
 12  
 13  Finally: These guidelines are correct as far as we know, but they haven't
 14  been tested by many people. If you find any problems in them, please let us
 15  know!
 16  
 17  ## Installing the requirements
 18  
 19  First install targets so Rust know how to compile to iOS
 20  ```sh
 21  $ rustup target add aarch64-apple-ios \
 22  	aarch64-apple-ios-sim \
 23  	x86_64-apple-ios
 24  ```
 25  
 26  ## Configuring a Rust project
 27  
 28  To create a new project in the directory you're in. You can do:
 29  ```sh
 30  $ cargo init <project-name> --lib
 31  ```
 32  
 33  You'll then need to add some content to the Cargo.toml.
 34  
 35  First add the subcrates of arti you want to use to the `[dependencies]` section. You'll have to add `features=["static"]` to crates that support this feature
 36  (at the moment tor-rtcompat, tor-dirmgr and arti-client): otherwise they will fail either to compile or to run.
 37  
 38  You'll probably want to add some other dependencies, like futures, but these are not technically requirements.
 39  
 40  You'll also need to specify what kind of lib this is. By default, it's a Rust lib that can only be used in the rust ecosystem.
 41  We want it to be a static library:
 42  ```toml
 43  [lib]
 44  name = "arti_mobile"
 45  crate-type = ["staticlib"]
 46  ```
 47  
 48  You are good to start programming in `src/lib.rs`.
 49  To make your functions available to Swift, you need to set certain modifiers on them.
 50  ```rust
 51  // defined the function my_function which will be exported without mangling its name, as a C-compatible function.
 52  #[no_mangle]
 53  pub extern "C" fn my_function( /* parameters omitted */ ) {..}
 54  ```
 55  
 56  You also need to add these functions to a C header file which will be imported later in XCode.
 57  ```C
 58  // You'll probably need to import stdbool, stdint and stdlib for the type definitions they contain
 59  
 60  void my_function(void);
 61  ```
 62  
 63  There exist a tool to build this header file for you, see in `Tips and caveats` below.
 64  
 65  Once you are satisfied with your code, you can compile it by running these commands. (This is a good time to take a coffee break)
 66  ```sh
 67   ## build for 64bit iPhone/iPad (32bit is no longer supported since iOS 11)
 68  $ cargo build --locked --target aarch64-apple-ios
 69   ## build for M1 based Mac (emulator)
 70  $ cargo build --locked --target aarch64-apple-ios-sim
 71   ## build for x86 based Mac (emulator)
 72  $ cargo build --locked --target x86_64-apple-ios
 73  ```
 74  
 75  You can add `--release` to each of this commands to build release libs that are smaller and faster, but take longer to compile.
 76  
 77  ## The Swift part
 78  
 79  I'll assume you already have a project setup. This can be a brand new project, or an already existing one.
 80  
 81  First you'll need to add the native library and its header to your project.
 82  
 83  Open your project settings Go in Build Settings and search Objective-C Bridging Header. Set it to the path
 84  to your C header file.
 85  
 86  Now close XCode, and open your project.pbxproj in a text editor. Jump to `LD_RUNPATH_SEARCH_PATHS`. You 
 87  should find it two times, in a section named Debug and an other named Release.
 88  
 89  In the Debug section, after `LD_RUNPATH_SEARCH_PATHS`, add the following:
 90  ```
 91  "LIBRARY_SEARCH_PATHS[sdk=iphoneos*][arch=arm64]" = (
 92  	"$(inherited)",
 93  	"../<path_to_rust_project>/target/aarch64-apple-ios/debug",
 94  );
 95  "LIBRARY_SEARCH_PATHS[sdk=iphonesimulator*][arch=arm64]" = (
 96  	"$(inherited)",
 97  	"../<path_to_rust_project>/target/aarch64-apple-ios-sim/debug",
 98  );
 99  "LIBRARY_SEARCH_PATHS[sdk=iphonesimulator*][arch=x86_64]" = (
100  	"$(inherited)",
101  	"../<path_to_rust_project>/target/x86_64-apple-ios/debug",
102  );
103  OTHER_LDFLAGS = (
104  	"$(inherited)",
105  	"-larti_mobile", /* replace arti-mobile with what you put as name in [lib] in Cargo.toml */
106  );
107  ```
108  
109  In the Release section, add the same block, but replace `debug` at the end of each path with `release`.
110  
111  Now you can start calling your Rust functions from Swift like normal functions. Types are a bit difficult to
112  work with, strings get transformed into char\* at the FFI interface, and Swift consider them as 
113  `Optional<UnsafeMutablePointer<CChar>>` which need unwrapping and conversion before being used. You also
114  need to free such a pointer by passing it back to Rust and dropping the value there. Otherwise these
115  functions should work almost as any other.
116  
117  You can now build your application, and test it in an emulator or on your device. Hopefully it should work.
118  
119  ## Tips and caveats
120  
121  You can find a sample project to build a very basic app using Arti [here](https://gitlab.torproject.org/trinity-1686a/arti-mobile-example/).
122  It does not respect most good practices of app development, but should otherwise be a good starting point.
123  
124  ## Generating C headers from Rust code
125  Instead of writing C headers manually and hopping to not make mistakes, it's possible to generate them
126  automatically by using cbindgen. First install it.
127  ```sh
128  $ cargo install cbindgen
129  ```
130  
131  Then use bindgen to generate the headers. You should put all functions you want to export in a single rust file.
132  ```sh
133  $ cbindgen src/lib.rs -l c > arti-mobile.h
134  ```
135  
136  ### Debugging and stability
137  Arti logs events to help debugging. By default these logs are not available on iOS.
138  You can make Arti export its logs to OSLog by adding a couple dependencies and writing a bit of code:
139  
140  ```toml
141  # in [dependencies] in Cargo.toml
142  tracing-subscriber = "0.3.3"
143  tracing-oslog = "0.1.2"
144  ```
145  
146  ```rust
147  use tracing_subscriber::fmt::Subscriber;
148  use tracing_subscriber::prelude::*;
149  
150  Subscriber::new()
151    .with(tracing_oslog::OsLogger::layer("rust.arti")?)
152    .init(); // this must be called only once, otherwise your app will probably crash
153  ```
154  
155  You should take great care about your rust code not unwinding into Swift Runtime: If it does, it will crash your app with no error message to help you.
156  If your code can panic, you should use `catch_unwind` to capture it before it reaches Swift.
157  
158  ## Async and Swift
159  Arti relies a lot on Rust futures. There is no easy way to use these futures from Swift. The easiest ways is probably to block on futures
160  if you are okay with it. Otherwise you have to pass callbacks from Swift to Rust, and make so they are called when the future completes.
161  
162  Eventually, Arti will provide a set of blocking APIs for use for embedding;
163  please get in touch if you want to help design them.