Doc generation improvements with UniFFI library mode

.cargo/config.toml

@@ -1,6 +1,7 @@
 [alias]
 regen-protobufs = ["run", "--bin", "protobuf-gen", "tools/protobuf_files.toml"]
 uniffi-bindgen = ["run", "--package", "embedded-uniffi-bindgen", "--"]
+uniffi-bindgen-library-mode = ["run", "--package", "uniffi-bindgen-library-mode", "--"]
 dev-install = ["install", "asdev"]
 verify_env = ["asdev", "verify_env"]
 fxa = ["run", "-p", "examples-fxa-client", "--"]

Cargo.toml

@@ -49,6 +49,7 @@ members = [
     "megazords/ios-rust/focus",
     "tools/protobuf-gen",
     "tools/embedded-uniffi-bindgen",
+    "tools/uniffi-bindgen-library-mode",
     "automation/swift-components-docs",
 
     "examples/*/",
@@ -119,14 +120,15 @@ default-members = [
 #    "testing/sync-test",
     "tools/protobuf-gen",
     "tools/embedded-uniffi-bindgen",
+    "tools/uniffi-bindgen-library-mode",
     "examples/*/",
     "testing/separated/*/",
 ]
 
 [workspace.dependencies]
 rusqlite = "0.31.0"
 libsqlite3-sys = "0.28.0"
-uniffi = "0.28.0"
+uniffi = "0.28.1"
 
 [profile.release]
 opt-level = "s"

automation/kotlin-components-docs/generate_docs.sh

@@ -10,24 +10,7 @@ KOTLIN_DIR="$WORKING_DIR/src/main/kotlin"
 
 # Generate Kotlin bindings using uniffi-bindgen
 CARGO=${CARGO:-cargo}  # Use the provided CARGO or fallback to cargo
-
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/remote_settings/src/remote_settings.udl" -l kotlin -o "$KOTLIN_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/nimbus/src/nimbus.udl" -l kotlin -o "$KOTLIN_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/support/error/src/errorsupport.udl" -l kotlin -o "$KOTLIN_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/support/rust-log-forwarder/src/rust_log_forwarder.udl" -l kotlin -o "$KOTLIN_DIR"
-
-# Repeat for other components
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/crashtest/src/crashtest.udl" -l kotlin -o "$KOTLIN_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/fxa-client/src/fxa_client.udl" -l kotlin -o "$KOTLIN_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/logins/src/logins.udl" -l kotlin -o "$KOTLIN_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/autofill/src/autofill.udl" -l kotlin -o "$KOTLIN_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/push/src/push.udl" -l kotlin -o "$KOTLIN_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/tabs/src/tabs.udl" -l kotlin -o "$KOTLIN_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/places/src/places.udl" -l kotlin -o "$KOTLIN_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/suggest/src/suggest.udl" -l kotlin -o "$KOTLIN_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/sync_manager/src/syncmanager.udl" -l kotlin -o "$KOTLIN_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/sync15/src/sync15.udl" -l kotlin -o "$KOTLIN_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/as-ohttp-client/src/as_ohttp_client.udl" -l kotlin -o "$KOTLIN_DIR"
+$CARGO uniffi-bindgen-library-mode android kotlin "$KOTLIN_DIR"
 
 # Generate documentation with increased memory
 (cd "$WORKING_DIR" && "$REPO_ROOT/gradlew" --max-workers=2 dokkaHtml -Dorg.gradle.vfs.watch=false)

automation/swift-components-docs/generate-swift-project.sh

@@ -49,30 +49,11 @@ SWIFT_DIR="$WORKING_DIR/Sources/$FRAMEWORK_NAME"
 mkdir -p "$INCLUDE_DIR"
 
 # Generate Swift bindings and headers using uniffi-bindgen
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/remote_settings/src/remote_settings.udl" -l swift -o "$SWIFT_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/nimbus/src/nimbus.udl" -l swift -o "$SWIFT_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/support/error/src/errorsupport.udl" -l swift -o "$SWIFT_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/support/rust-log-forwarder/src/rust_log_forwarder.udl" -l swift -o "$SWIFT_DIR"
+$CARGO uniffi-bindgen-library-mode ios swift "$SWIFT_DIR"
 
 # Move header files to the include directory
 mv "$SWIFT_DIR"/*.h "$INCLUDE_DIR"
 
-# Repeat for the other components if not focus
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/crashtest/src/crashtest.udl" -l swift -o "$SWIFT_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/fxa-client/src/fxa_client.udl" -l swift -o "$SWIFT_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/logins/src/logins.udl" -l swift -o "$SWIFT_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/autofill/src/autofill.udl" -l swift -o "$SWIFT_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/push/src/push.udl" -l swift -o "$SWIFT_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/tabs/src/tabs.udl" -l swift -o "$SWIFT_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/places/src/places.udl" -l swift -o "$SWIFT_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/suggest/src/suggest.udl" -l swift -o "$SWIFT_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/sync_manager/src/syncmanager.udl" -l swift -o "$SWIFT_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/sync15/src/sync15.udl" -l swift -o "$SWIFT_DIR"
-$CARGO uniffi-bindgen generate "$REPO_ROOT/components/as-ohttp-client/src/as_ohttp_client.udl" -l swift -o "$SWIFT_DIR"
-
-# Move the header files to the include directory
-mv "$SWIFT_DIR"/*.h "$INCLUDE_DIR"
-
 rm -rf "$WORKING_DIR"/Sources/"$FRAMEWORK_NAME"/*.modulemap
 
 echo "Successfully generated Swift bindings, headers, and module map."

tools/uniffi-bindgen-library-mode/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "uniffi-bindgen-library-mode"
+version = "0.1.0"
+authors = ["The Firefox Sync Developers <sync-team@mozilla.com>"]
+edition = "2021"
+license = "MPL-2.0"
+
+[dependencies]
+uniffi = { workspace = true, features = ["cli"] }
+uniffi_bindgen = { version = "0.28.1", features = ["cargo-metadata"] }
+clap = "4"
+cargo_metadata = "0.15"
+camino = "1"
+anyhow = "1"

tools/uniffi-bindgen-library-mode/README.md

@@ -0,0 +1,39 @@
+# Embedded uniffi-bindgen for this workspace
+
+This crate exists entirely to support running `cargo uniffi-bindgen` in the workspace
+root and having it correctly execute the `uniffi-bindgen` command provided by the
+version of `uniffi_bindgen` that's in use in the workspace.
+
+Say what?
+
+OK, so exposing a crate to Kotlin or Swift via `uniffi` is done in two halves:
+
+* On the Rust side, the crate needs to depend on `uniffi` for runtime support code.
+* On the foreign-language side, we need to run `uniffi-bindgen` as part of the build
+  process to generate the language bindings.
+
+It's very important that both halves use the exact same version of UniFFI, and UniFFI
+will *try* to error out if it detects this. But if you *don't* detect it then using
+mismatched versions of UniFFI will lead to an inscrutable linker failure at runtime.
+
+The simple way to use UniFFI is for developers to `cargo install uniffi_bindgen`
+on their system and then use the `uniffi-bindgen` command-line tool during the build.
+But unfortunately, this makes it painful to bump the version of the `uniffi` crate
+used by the components, and it greatly complicates doing local development on UniFFI
+itself.
+
+This crate offers a more complicated way that is also more robust to UniFFI version
+changes.
+
+First, configure all UniFFI-using crates to use the `builtin-bindgen` feature
+of `uniffi_build`.
+
+Then, instead of running the system-installed `uniffi-bindgen`, run our handy
+`cargo uniffi-bindgen` alias, which delegates to this crate. This will execute
+the `uniffi-bindgen` command-line tool *provided by the version of UniFFI specified
+in this crate*, letting us avoid having to install and update `uniffi-bindgen` at
+the system level
+
+You'll still have to ensure that all crates in this workspace are using the
+same version of UniFFI, but that's much simpler than controlling what's installed
+on everybody's build machine.