Merge remote-tracking branch 'upstream/main' into release-v0.28.x

CHANGELOG.md

@@ -6,6 +6,19 @@
 
 ## [[UnreleasedUniFFIVersion]] (backend crates: [[UnreleasedBackendVersion]]) - (_[[ReleaseDate]]_)
 
+### What's new?
+
+- Added the `uniffi-bindgen-swift` binary. It works like `uniffi-bindgen` but with additional
+ Swift-specific features. See
+ https://mozilla.github.io/uniffi-rs/latest/swift/uniffi-bindgen-swift.html for details.
+
+- Removed the [old and outdated diplomat comparison](https://github.com/mozilla/uniffi-rs/blob/69ecfbd7fdf587a4ab24d1234e2d6afb8a496581/docs/diplomat-and-macros.md) doc
+
+### What's fixed?
+
+- `uniffi.toml` of crates without a `lib` type where ignored in 0.28.1
+- Python: Fixed a bug when enum/error names were not proper camel case (HTMLError instead of HtmlError).
+
 [All changes in [[UnreleasedUniFFIVersion]]](https://github.com/mozilla/uniffi-rs/compare/v0.28.1...HEAD).
 
 ## v0.28.1 (backend crates: v0.28.1) - (_2024-08-09_)

README.md

@@ -43,8 +43,7 @@ FFI - [Abbreviation, Foreign Function Interface]
 
 Other tools we know of which try and solve a similarly shaped problem are:
 
-* [Diplomat](https://github.com/rust-diplomat/diplomat/) - see our [writeup of
- the different approach taken by that tool](docs/diplomat-and-macros.md)
+* [Diplomat](https://github.com/rust-diplomat/diplomat/), which is focused more on C/C++ interop.
 * [Interoptopus](https://github.com/ralfbiedert/interoptopus/)
 
 (Please open a PR if you think other tools should be listed!)

docs/manual/src/swift/configuration.md

@@ -13,7 +13,7 @@ more likely to change than other configurations.
 | `module_name` | `{namespace}`[^1] | The name of the Swift module containing the high-level foreign-language bindings. |
 | `ffi_module_name` | `{module_name}FFI` | The name of the lower-level C module containing the FFI declarations. |
 | `ffi_module_filename` | `{ffi_module_name}` | The filename stem for the lower-level C module containing the FFI declarations. |
-| `generate_module_map` | `true` | Whether to generate a `.modulemap` file for the lower-level C module with FFI declarations.    |
+| `generate_module_map` | `true` | Whether to generate a `.modulemap` file for the lower-level C module with FFI declarations. (ignored by `uniffi-bindgen-swift`) | 
 | `omit_argument_labels` | `false` | Whether to omit argument labels in Swift function definitions. |
 | `generate_immutable_records` | `false` | Whether to generate records with immutable fields (`let` instead of `var`). |
 | `experimental_sendable_value_types` | `false` | Whether to mark value types as `Sendable'. |

docs/manual/src/swift/overview.md

@@ -25,20 +25,10 @@ Concepts from the UDL file map into Swift as follows:
  * If this happens inside a non-throwing Swift function, it will be converted
  into a fatal Swift error that cannot be caught.
 
-Conceptually, the generated bindings are split into two Swift modules, one for the low-level
-C FFI layer and one for the higher-level Swift bindings. For a UniFFI component named "example"
-we generate:
+## Generated files
 
-* A C header file `exampleFFI.h` declaring the low-level structs and functions for calling
- into Rust, along with a corresponding `exampleFFI.modulemap` to expose them to Swift.
-* A Swift source file `example.swift` that imports the `exampleFFI` module and wraps it
- to provide the higher-level Swift API.
+UniFFI generates several kinds of files for Swift bindings:
 
-Splitting up the bindings in this way gives you flexibility over how both the Rust code
-and the Swift code are distributed to consumers. For example, you may choose to compile
-and distribute the Rust code for several UniFFI components as a single shared library
-in order to reduce the compiled code size, while distributing their Swift wrappers as
-individual modules.
-
-For more technical details on how the bindings work internally, please see the
-[module documentation](https://docs.rs/uniffi_bindgen/latest/uniffi_bindgen/bindings/swift/index.html)
+* C header files declaring the FFI structs/functions used by the Rust scaffolding code
+* A modulemap, which defines a Swift module for the C FFI definitions in the header file.
+* A Swift source file that defines the Swift API used by consumers. This imports the FFI module.

docs/manual/src/swift/uniffi-bindgen-swift.md

@@ -0,0 +1,48 @@
+# uniffi-bindgen-swift
+
+Swift bindings can be generated like other languages using `uniffi-bindgen -l swift`. However, you
+can also use the `uniffi-bindgen-swift` binary which gives greater control over Swift-specific
+features:
+
+* Select which kind of files to generate: headers, modulemaps, and/or Swift sources.
+* Generate a single modulemap for a library.
+* Generate XCFramework-compatible modulemaps.
+* Customize the modulemap module name.
+* Customize the modulemap filename.
+
+`uniffi-bindgen-swift` can be added to your project using the same general steps as `uniffi-bindgen`.
+See https://mozilla.github.io/uniffi-rs/latest/tutorial/foreign_language_bindings.html#creating-the-bindgen-binary.
+The Rust source for the binary should be:
+
+```
+fn main() {
+ uniffi::uniffi_bindgen_swift()
+}
+```
+
+`uniffi-bindgen-swift` always inputs a library path and runs in "library mode". This means
+proc-macro-based bindings generation is always supported.
+
+## Examples:
+
+
+Generate .swift source files for a library
+```
+cargo run -p uniffi-bindgen-swift -- target/release/mylibrary.a build/swift --swift-sources
+```
+
+Generate .h files for a library
+```
+cargo run -p uniffi-bindgen-swift -- target/release/mylibrary.a build/swift/Headers --headers
+```
+
+
+Generate a modulemap
+```
+cargo run -p uniffi-bindgen-swift -- target/release/mylibrary.a build/swift/Modules --modulemap --modulemap-filename mymodule.modulemap
+```
+
+Generate a Xcframework-compatible modulemap
+```
+cargo run -p uniffi-bindgen-swift -- target/release/mylibrary.a build/swift/Modules --xcframework --modulemap --modulemap-filename mymodule.modulemap
+```