[Documentation] Improve documentation for Xcode integration to help solve runtime issues

Current issue

I wanted to propose to extend Xcode Integration documentation by section that explain possible issues with adding new Build Phase and Build Rules in Xcode 13 and newers, while building project or working with SwiftUI's Live Preview.

As both Build Phase that builds static library and custom Build Rule that generates .swift files, can trigger changes in project files when Xcode is indexing, this can lead to random build failures and also makes it impossible to work with SwiftUI Previews.

This is know issue amongst other libraries that generate code in Build Phases, some issues mentioning that: https://github.com/Brightify/Cuckoo/issues/400 https://github.com/mac-cain13/R.swift/issues/719 Some libraries are already including instructions on how to integrate Build Phase / Build Rule without breaking Xcode indexing and SwiftUI Previews in their install instructions: https://github.com/mac-cain13/R.swift/issues/719 and it could be a good idea to include those instructions as well for uniffi.

Although this is not uniffi-specific issue, given that this is still not a common knowledge amongst iOS community (unless someone has used lots of code generation tools), it could be good to provide more detailed instructions.

Proposed solution

Custom script for Build Rule should be changed from this:

$HOME/.cargo/bin/uniffi-bindgen generate $INPUT_FILE_PATH --language swift --out-dir $INPUT_FILE_DIR/Generated

to:

# Skip during indexing phase in XCode 13+ 
if [ $ACTION == "indexbuild" ]; then
  echo "Not building *.udl files during indexing."
  exit 0 
fi

# Skip for preview builds
if [ "${ENABLE_PREVIEWS}" = "YES" ]; then
  echo "Not building *.udl files during preview builds."
  exit 0
fi

$HOME/.cargo/bin/uniffi-bindgen generate $INPUT_FILE_PATH --language swift --out-dir $INPUT_FILE_DIR/Generated

And similar instructions should be added regarding Build Phase, maybe one of the build phases within example iOS project could be given as example:

$HOME/.cargo/bin/uniffi-bindgen generate $INPUT_FILE_PATH --language swift --out-dir $INPUT_FILE_DIR/Generated

if [ $ACTION != "indexbuild" ]; then
    $HOME/.cargo/bin/uniffi-bindgen generate $INPUT_FILE_PATH --language swift --out-dir $INPUT_FILE_DIR/Generated
fi

Example implementation of solution:

We've introduced those changes within parity-signer repo https://github.com/paritytech/parity-signer/pull/1234

Next Steps

If accepted I can prepare a PR with updated documentation for Xcode integration or provide more detailed instructions to whoever is managing that 🙏🏻 Maybe this could be included in an example iOSApp project to showcase best practices during integration process.

┆Issue is synchronized with this Jira Task ┆friendlyId: UNIFFI-189

mozilla / uniffi-rs