GUI-based debugging of iOS/macOS Rust projects in Xcode

README.md

Here's how to get your environment set up to:

1. Develop iOS and Android apps using Rust.
2. Enable GUI debugging of Rust projects in Xcode.

If you just want to enable GUI debugging of macOS Rust projects in Xcode, I'm not actually sure whether you need cargo-mobile at all. But one benefit of installing it is that it automatically installs rust-xcode-plugin for you, giving you syntax highlighting of Rust sources in Xcode.

Prerequisites

cargo-mobile

Install cargo-mobile. Follow the instructions on that repo to see any further prerequisites; at the time of writing, these are that you must:

1. have already installed Xcode (if you wish to develop on iOS)
2. have already installed the Android SDK & NDK (if you wish to develop on Android)

cargo install --git https://github.com/BrainiumLLC/cargo-mobile

Installing cargo-mobile does a few things: (click to expand)

• It provides the cargo mobile CLI tool for setting up the boilerplate for Rust-based iOS and Android apps. For example, here is how the iOS Rust project wry-ios-poc-new was generated:

  $ mkdir wry-ios-poc-new
  $ cd wry-ios-poc-new
  $ cargo mobile init
  Project name (wry-ios-poc-new): 
  Stylized name (Wry): 
  Domain (ca.lemarier): 
  Detected template packs:
    [0] bevy
    [1] bevy-demo
    [2] wgpu
    [3] winit
    Enter an index for a template pack above.
  Template pack (0): 3           
  Detected development teams:
    [0] lemarier (VPP2V83UFS)
    Enter an index for a team above, or enter a team ID manually.
  Apple development team (0): 0

• It installs a rust-xcode-plugin, which adds syntax highlighting support for Rust files in Xcode
• It runs the following commands to add the iOS and Android toolchains:
  • iOS:

  rustup target add \
      aarch64-apple-ios \
      x86_64-apple-ios

  • Android:

  rustup target add \
      aarch64-linux-android \
      armv7-linux-androideabi \
      i686-linux-android \
      x86_64-linux-android

Project setup

Assuming the following directory structure, where:

• wry is a Rust library.
• wry-ios-poc-new is a project initialised with cargo-mobile for building a Rust-based app that deploys to multiple platforms including iOS and macOS. You can expand the details in the prerequisites above to see exactly how it was initialised.

.
├── wry
└── wry-ios-poc-new

In wry-ios-poc-new/cargo.toml, ensure that the wry crate is installed locally:

[dependencies]
mobile-entry-point = "0.1.0"
- wry = { git ="https://github.com/tauri-apps/wry", branch = "feat/ios" }
+ wry = { path = "../wry" }

This change means that your wry project's build will be generated from these local sources, so you'll be able to alter them from within Xcode (or another IDE).

In wry-ios-poc-new/gen/apple/project.yml, add a file group to the root of the local wry project directory:

- fileGroups: [../../src]
+ fileGroups: [../../src, ../../../wry]

Side-note: you could instead reference the sub-directory ../../../wry/src if you only care about the sources and don't want easy access to the wry/Cargo.toml file.

Now the wry sources will be visible within your Xcode project, so you can set breakpoints upon lines and your run target will respect them.

Again in wry-ios-poc-new/gen/apple/project.yml: wry-ios-poc-new makes use of a WebView, so the framework "WebKit" needs to be added to the iOS and macOS targets, otherwise you'll get a runtime error. You don't need to add WebKit to all Rust projects, just this particular one.

Now be sure to run xcodegen generate to regenerate the Xcode project.

Finally, select the target wry-ios_iOS in Xcode and run it on either a simulator or a real device in Debug configuration (by default, Cargo is configured only to include debug symbols in debug mode).

Incidentally, if you do want to debug in release mode, you can add the following to your Cargo.toml file:

+ [profile.release]
+ debug = true

The result can be seen in this screenshot below. We can set breakpoints and alter the code. 🥳 Note that we don't get auto-complete or any intelligence when editing the Rust sources – that's still unsolved for Xcode. You may find yourself editing the Rust sources in one IDE and debugging it in another for now.

breakpoints.png