Handles part 2

CHANGELOG.md

@@ -16,12 +16,49 @@
 
 ### What's changed?
 
+- Trait interfaces defined in UDL need to be wrapped with `#[uniffi::trait_interface]`.
+- Trait interfaces performance has been improved.  If a trait interface handle is passed across the
+  FFI multiple times, UniFFI will only wrap the object once rather than each time it's passed.
+- The `NoPointer` singleton was renamed to `NoHandle`
+
+### What's new?
+
+- Rust traits `Display`, `Hash` and `Eq` exposed to Kotlin and Swift [#1817](https://github.com/mozilla/uniffi-rs/pull/1817)
+- Foreign types can now implement trait interfaces [#1791](https://github.com/mozilla/uniffi-rs/pull/1791)
+- Generated Python code is able to specify a package name for the module [#1784](https://github.com/mozilla/uniffi-rs/pull/1784)
+- UDL can describe async function [#1834](https://github.com/mozilla/uniffi-rs/pull/1834)
+- UDL files can reference types defined in procmacros in this crate - see
+  [the external types docs](https://mozilla.github.io/uniffi-rs/udl/ext_types.html)
+- Add support for [docstrings in UDL](https://mozilla.github.io/uniffi-rs/udl/docstrings.html)
+
+### Breaking changes for external bindings
+
 - The `rust_future_continuation_callback_set` FFI function was removed.  `rust_future_poll` now
   inputs the callback pointer.  External bindings authors will need to update their code.
+- The object handle FFI has changed.  External bindings generators will need to update their code to
+  use the new handle system:
+    * A single `FfiType::Handle` is used for all object handles.
+    * `FfiType::Handle` is always a 64-bit int.
+    * Foreign handles must always set the lowest bit of that int.
 
-### What's new?
+[All changes in [[UnreleasedUniFFIVersion]]](https://github.com/mozilla/uniffi-rs/compare/v0.25.2...HEAD).
+
+## v0.25.2 (backend crates: v0.25.2) - (_2023-11-20_)
+
+### What's fixed?
+
+- Fixed regression in the name of error enums in Kotlin [#1842](https://github.com/mozilla/uniffi-rs/pull/1842)
+- Fix regression when error types are in dicts etc [#1847](https://github.com/mozilla/uniffi-rs/pull/1847)
+
+[All changes in v0.25.2](https://github.com/mozilla/uniffi-rs/compare/v0.25.1...v0.25.2).
+
+## v0.25.1 (backend crates: v0.25.1) - (_2023-11-09_)
+
+[All changes in v0.25.1](https://github.com/mozilla/uniffi-rs/compare/v0.25.0...v0.25.1).
+
+### What's fixed?
 
-- Rust traits `Display`, `Hash` and `Eq` exposed to Kotlin and Swift.
+- Fixed several bugs with async functions were defined in multiple crates that get built together.
 
 ## v0.25.0 (backend crates: v0.25.0) - (_2023-10-18_)
 
@@ -49,7 +86,6 @@
 - Error types must now implement `Error + Send + Sync + 'static`.
 - Proc-macros: The `handle_unknown_callback_error` attribute is no longer needed for callback
   interface errors
-- Foreign types can now implement trait interfaces
 
 ### What's Fixed
 

Cargo.toml

@@ -30,14 +30,15 @@ members = [
   "fixtures/ext-types/uniffi-one",
   "fixtures/ext-types/lib",
   "fixtures/ext-types/proc-macro-lib",
+  "fixtures/ext-types/sub-lib",
 
+  "fixtures/docstring",
   "fixtures/foreign-executor",
   "fixtures/keywords/kotlin",
   "fixtures/keywords/rust",
   "fixtures/keywords/swift",
   "fixtures/metadata",
   "fixtures/proc-macro",
-  "fixtures/reexport-scaffolding-macro",
   "fixtures/regressions/enum-without-i32-helpers",
   "fixtures/regressions/fully-qualified-types",
   "fixtures/regressions/kotlin-experimental-unsigned-types",

docs/manual/src/SUMMARY.md

@@ -19,6 +19,7 @@
   - [External Types](./udl/ext_types.md)
     - [Declaring External Types](./udl/ext_types_external.md)
     - [Declaring Custom Types](./udl/custom_types.md)
+  - [Docstrings](./udl/docstrings.md)
 - [Procedural Macros: Attributes and Derives](./proc_macro/index.md)
 - [Futures and async support](./futures.md)
 

docs/manual/src/foreign_traits.md

@@ -22,6 +22,7 @@ a [compatible error type](./udl/errors.md) - see below for more on error handlin
 For example:
 
 ```rust,no_run
+#[uniffi::trait_interface]
 pub trait Keychain: Send + Sync + Debug {
   fn get(&self, key: String) -> Result<Option<String>, KeyChainError>;
   fn put(&self, key: String, value: String) -> Result<(), KeyChainError>;

docs/manual/src/kotlin/configuration.md

@@ -8,6 +8,7 @@ The generated Kotlin modules can be configured using a `uniffi.toml` configurati
 | ------------------ | -------  |------------ |
 | `package_name`     |  `uniffi` | The Kotlin package name - ie, the value used in the `package` statement at the top of generated files. |
 | `cdylib_name`      | `uniffi_{namespace}`[^1] | The name of the compiled Rust library containing the FFI implementation (not needed when using `generate --library`). |
+| `generate_immutable_records` | `false` | Whether to generate records with immutable fields (`val` instead of `var`). |
 | `custom_types`      | | A map which controls how custom types are exposed to Kotlin. See the [custom types section of the manual](../udl/custom_types.md#custom-types-in-the-bindings-code)|
 | `external_packages` | | A map of packages to be used for the specified external crates. The key is the Rust crate name, the value is the Kotlin package which will be used referring to types in that crate. See the [external types section of the manual](../udl/ext_types_external.md#kotlin)
 

docs/manual/src/proc_macro/index.md

@@ -23,7 +23,7 @@ true for all of UniFFI, so proceed with caution and the knowledge that things ma
 
 ## Build workflow
 
-Library mode is recommended when using UniFFI proc-macros (See the [Foreign language bindings docs](../tutorial/foreign_language_bindings.md) for more info).
+Be sure to use library mode when using UniFFI proc-macros (See the [Foreign language bindings docs](../tutorial/foreign_language_bindings.md) for more info).
 
 If your crate's API is declared using only proc-macros and not UDL files, call the `uniffi::setup_scaffolding` macro at the top of your source code:
 
@@ -84,6 +84,8 @@ impl MyObject {
 // Corresponding UDL:
 // [Trait]
 // interface MyTrait {};
+//
+// Note: `[uniffi::trait_interface]` is not needed when the trait is exported via a proc-macro.
 #[uniffi::export]
 trait MyTrait {
     // ...

docs/manual/src/swift/configuration.md

@@ -12,6 +12,7 @@ The generated Swift module can be configured using a `uniffi.toml` configuration
 | `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. |
 | `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`). |
 | `custom_types`      | | A map which controls how custom types are exposed to Swift. See the [custom types section of the manual](../udl/custom_types.md#custom-types-in-the-bindings-code)|
 
 

docs/manual/src/tutorial/Rust_scaffolding.md

@@ -14,7 +14,12 @@ uniffi = "0.XX.0"
 uniffi = { version = "0.XX.0", features = ["build"] }
 ```
 
-Then create a `build.rs` file next to `Cargo.toml` that uses `uniffi` to generate the Rust scaffolding code.
+As noted in [Describing the interface](udl_file.md), UniFFI currently supports two methods of interface definitions: UDL files and proc macros.
+If you are using only proc macros, you can skip some boilerplate in your crate setup as well.
+
+### Setup for crates using UDL
+
+Crates using UDL need a `build.rs` file next to `Cargo.toml`. This uses `uniffi` to generate the Rust scaffolding code.
 
 ```rust
 fn main() {
@@ -30,7 +35,18 @@ uniffi::include_scaffolding!("math");
 
 **Note:** The file name is always `<namespace>.uniffi.rs`.
 
-Great! `add` is ready to see the outside world!
+### Setup for crates using only proc macros
+
+If you are only using proc macros, you can skip `build.rs` entirely!
+All you need to do is add this to the top of `lib.rs`
+NOTE: This function takes an optional parameter, the [`namespace`](../udl/namespace.md) used by the component.
+If not specified, the crate name will be used as the namespace.
+
+```rust
+uniffi::setup_scaffolding!();
+```
+
+**⚠ Warning ⚠** Do not call both `uniffi::setup_scaffolding!()` and `uniffi::include_scaffolding!!()` in the same crate.
 
 ### Libraries that depend on UniFFI components
 

docs/manual/src/tutorial/foreign_language_bindings.md

@@ -38,11 +38,11 @@ creating a binary for each crate that uses UniFFI.  You can avoid this by creati
 
 Then your can run `uniffi-bindgen` from any create in your project using `cargo run -p uniffi-bindgen [args]`
 
-## Running uniffi-bindgen using a library file
+## Running uniffi-bindgen using a library file (RECOMMENDED)
 
 Use `generate --library` to generate foreign bindings by using a cdylib file built for your library.
 This flag was added in UniFFI 0.24 and can be more convenient than specifying the UDL file -- especially when multiple UniFFI-ed crates are built together in one library.
-The plan is to make library mode the default in a future UniFFI version.
+The plan is to make library mode the default in a future UniFFI version, and it is highly recommended to specify the flag for now (because some features simply don't work otherwise).
 
 Taking `example/arithmetic` as an example, you can generate the bindings with:
 ```