Deployed 1cdf56b to 0.28 with MkDocs 1.6.0 and mike 2.1.1

0.28/Motivation.html

@@ -1483,11 +1483,11 @@ <h2 id="how">How?</h2>
 <p>Using UniFFI, you can:</p>
 <ul>
 <li>Implement your software component as a <code>cdylib</code> crate in Rust; let's say the code is in <code>./src/lib.rs</code>.</li>
-<li>Specify the desired component API using an <em>Interface Definition Language</em> (specifically, a variant of WebIDL) in a separate file like <code>./src/lib.udl</code>.</li>
-<li>Run <code>uniffi-bindgen scaffolding ./src/lib.udl</code> to generate a bunch of boilerplate rust code that exposes this API as a C-compatible FFI layer,
-  and include it as part of your crate.</li>
+<li>Optionally, describe parts of your component API using proc-macros directly in <code>lib.rs</code>.</li>
+<li>Optionally, describe parts of your component API using an <em>Interface Definition Language</em> in a separate file like <code>./src/lib.udl</code>. UniFFI will generate a bunch of boilerplate Rust code that exposes this API as a C-compatible FFI layer, and include it as part of your crate.</li>
 <li><code>cargo build</code> your crate as normal to produce a shared library.</li>
-<li>Run <code>uniffi-bindgen generate ./src/lib.udl -l kotlin</code> to generate a Kotlin library that can load your shared library
+<li>Run <code>uniffi-bindgen generate ... -l kotlin</code> (see <a href="tutorial/foreign_language_bindings.html">the bindgen docs</a> for omitted arg details)
+  to generate a Kotlin library that can load your shared library
   and expose it to Kotlin code using your nice high-level component API!</li>
 <li>Or <code>-l swift</code> or <code>-l python</code> to produce bindings for other languages.</li>
 </ul>

0.28/futures.html

@@ -898,6 +898,15 @@
       </ul>
     </nav>
 
+</li>
+
+        <li class="md-nav__item">
+  <a href="#cancelling-async-code" class="md-nav__link">
+    <span class="md-ellipsis">
+      Cancelling async code.
+    </span>
+  </a>
+
 </li>
 
     </ul>
@@ -1459,6 +1468,15 @@
       </ul>
     </nav>
 
+</li>
+
+        <li class="md-nav__item">
+  <a href="#cancelling-async-code" class="md-nav__link">
+    <span class="md-ellipsis">
+      Cancelling async code.
+    </span>
+  </a>
+
 </li>
 
     </ul>
@@ -1549,6 +1567,12 @@ <h3 id="python-uniffi_set_event_loop">Python: <code>uniffi_set_event_loop()</cod
 Use <code>uniffi_set_event_loop()</code> to handle this case.
 It should be called before the Rust code makes the async call and passed an eventloop to use.</p>
 <p>Note that <code>uniffi_set_event_loop</code> cannot be glob-imported because it's not part of the library's <code>__all__</code>.</p>
+<h2 id="cancelling-async-code">Cancelling async code.</h2>
+<p>We don't directly support cancellation in UniFFI even when the underlying platforms do.
+You should build your cancellation in a separate, library specific channel; for example, exposing a <code>cancel()</code> method that sets a flag that the library checks periodically.</p>
+<p>Cancellation can then be exposed in the API and be mapped to one of the error variants, or None/empty-vec/whatever makes sense.
+There's no builtin way to cancel a future, nor to cause/raise a platform native async cancellation error (eg, a swift <code>CancellationError</code>).</p>
+<p>See also https://github.com/mozilla/uniffi-rs/pull/1768.</p>
 
 
 

0.28/index.html

@@ -1382,10 +1382,12 @@ <h1 id="uniffi">UniFFI</h1>
 <p>UniFFI is a tool that automatically generates foreign-language bindings targeting Rust libraries.
 The repository can be found on <a href="https://github.com/mozilla/uniffi-rs/">github</a>.
 It fits in the practice of consolidating business logic in a single Rust library while targeting multiple platforms, making it simpler to develop and maintain a cross-platform codebase.
-Note that this tool will not help you ship a Rust library to these platforms, but simply not have to write bindings code by hand. <a href="https://i.kym-cdn.com/photos/images/newsfeed/000/572/078/d6d.jpg">Related</a>.</p>
+Note that this tool will not help you ship a Rust library to these platforms, but it will help you avoid writing bindings code by hand.
+<a href="https://i.kym-cdn.com/photos/images/newsfeed/000/572/078/d6d.jpg">Related</a>.</p>
 <h2 id="design">Design</h2>
-<p>UniFFI requires to write an Interface Definition Language (based on <a href="https://heycam.github.io/webidl/">WebIDL</a>) file describing the methods and data structures available to the targeted languages.
-This .udl (UniFFI Definition Language) file, whose definitions must match with the exposed Rust code, is then used to generate Rust <em>scaffolding</em> code and foreign-languages <em>bindings</em>. This process can take place either during the build process or be manually initiated by the developer.</p>
+<p>UniFFI requires you to describe your interface via either proc-macros or in an Interface Definition Language (based on <a href="https://webidl.spec.whatwg.org/">WebIDL</a>) file.
+These definitions describe the methods and data structures available to the targeted languages, and are used to generate Rust <em>scaffolding</em> code and foreign-language <em>bindings</em>.
+This process can take place either during the build process or be manually initiated by the developer.</p>
 <p><img alt="uniffi diagram" src="uniffi_diagram.png" /></p>
 <h2 id="supported-languages">Supported languages</h2>
 <ul>

0.28/kotlin/configuration.html

@@ -1482,6 +1482,11 @@ <h2 id="available-options">Available options</h2>
 <td><code>android</code></td>
 <td>Use the <a href="https://developer.android.com/reference/android/system/SystemCleaner"><code>android.system.SystemCleaner</code></a> instead of <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/ref/Cleaner.html"><code>java.lang.ref.Cleaner</code></a>. Fallback in both instances is the one shipped with JNA.</td>
 </tr>
+<tr>
+<td><code>kotlin_target_version</code></td>
+<td><code>"x.y.z"</code></td>
+<td>When provided, it will enable features in the bindings supported for this version. The build process will fail if an invalid format is used.</td>
+</tr>
 </tbody>
 </table>
 <h2 id="example">Example</h2>

0.28/proc_macro/index.html

@@ -1819,7 +1819,7 @@ <h2 id="the-uniffiexport-attribute">The <code>#[uniffi::export]</code> attribute
 <p>Arguments and receivers can also be references to these types, for example:</p>
 <div class="highlight"><pre><span></span><code><span class="c1">// Input data types as references</span>
 <span class="cp">#[uniffi::export]</span>
-<span class="k">fn</span><span class="w"> </span><span class="nf">process_data</span><span class="p">(</span><span class="n">a</span><span class="p">:</span><span class="w"> </span><span class="kp">&amp;</span><span class="nc">MyRecord</span><span class="p">,</span><span class="w"> </span><span class="n">b</span><span class="p">:</span><span class="w"> </span><span class="kp">&amp;</span><span class="nc">MyEnum</span><span class="p">,</span><span class="w"> </span><span class="n">c</span><span class="p">:</span><span class="w"> </span><span class="nb">Option</span><span class="o">&lt;&amp;</span><span class="n">MyRecord</span><span class="o">&gt;</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
+<span class="k">fn</span><span class="w"> </span><span class="nf">process_data</span><span class="p">(</span><span class="n">a</span><span class="p">:</span><span class="w"> </span><span class="kp">&amp;</span><span class="nc">MyRecord</span><span class="p">,</span><span class="w"> </span><span class="n">b</span><span class="p">:</span><span class="w"> </span><span class="kp">&amp;</span><span class="nc">MyEnum</span><span class="p">,</span><span class="w"> </span><span class="n">c</span><span class="p">:</span><span class="w"> </span><span class="kp">&amp;</span><span class="nb">Option</span><span class="o">&lt;</span><span class="n">MyRecord</span><span class="o">&gt;</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
 <span class="w">    </span><span class="o">..</span><span class="p">.</span>
 <span class="p">}</span>
 

0.28/tutorial/foreign_language_bindings.html

@@ -1534,9 +1534,9 @@ <h1 id="foreign-language-bindings">Foreign-language bindings</h1>
 <p>The next step is to have UniFFI generate source code for your foreign language. It doesn't help you build this code, it just generates it for you.</p>
 <h2 id="creating-the-bindgen-binary">Creating the bindgen binary</h2>
 <p>First, make sure you have installed all the <a href="Prerequisites.html">prerequisites</a>.</p>
-<p>Ideally you would then run the <code>uniffi-bindgen</code> binary from the <code>uniffi</code> crate to generate your bindings.  However, this
-is only available with <a href="https://doc.rust-lang.org/cargo/reference/unstable.html#artifact-dependencies">Cargo nightly</a>.
-To work around this, you need to create a binary in your project that does the same thing.</p>
+<p>Ideally you would then run the <code>uniffi-bindgen</code> binary from the <code>uniffi</code> crate to generate your bindings,
+but if not on <a href="https://doc.rust-lang.org/cargo/reference/unstable.html#artifact-dependencies">Cargo nightly</a>,
+you need to create a binary in your project that does the same thing.</p>
 <p>Add the following to your <code>Cargo.toml</code>:</p>
 <div class="highlight"><pre><span></span><code><span class="k">[[bin]]</span>
 <span class="c1"># This can be whatever name makes sense for your project, but the rest of this tutorial assumes uniffi-bindgen.</span>
@@ -1550,11 +1550,10 @@ <h2 id="creating-the-bindgen-binary">Creating the bindgen binary</h2>
 </code></pre></div></p>
 <p>You can now run <code>uniffi-bindgen</code> from your project using <code>cargo run --features=uniffi/cli --bin uniffi-bindgen [args]</code></p>
 <h3 id="multi-crate-workspaces">Multi-crate workspaces</h3>
-<p>If your project consists of multiple crates in a Cargo workspace, then the process outlined above would require you
-creating a binary for each crate that uses UniFFI.  You can avoid this by creating a separate crate for running <code>uniffi-bindgen</code>:
-  - Name the crate <code>uniffi-bindgen</code>
+<p>In a multiple crates workspace, you can create a separate crate for running <code>uniffi-bindgen</code>:
+  - Name the crate <code>uniffi-bindgen</code>, add it to your workspace.
   - Add this dependency to <code>Cargo.toml</code>: <code>uniffi = {version = "0.XX.0", features = ["cli"] }</code>
-  - Follow the steps from the previous section to add the <code>uniffi-bindgen</code> binary target</p>
+  - As above, add the <code>uniffi-bindgen</code> binary target</p>
 <p>Then your can run <code>uniffi-bindgen</code> from any crate in your project using <code>cargo run -p uniffi-bindgen [args]</code></p>
 <h2 id="running-uniffi-bindgen-using-a-library-file">Running uniffi-bindgen using a library file</h2>
 <p>Use <code>generate --library</code> to generate foreign bindings by using a cdylib file built for your library.

0.28/udl/errors.html

@@ -1474,7 +1474,7 @@ <h2 id="interfaces-as-errors">Interfaces as errors</h2>
 <span class="p">}</span>
 
 <span class="k">impl</span><span class="w"> </span><span class="n">MyError</span><span class="w"> </span><span class="p">{</span>
-<span class="w">    </span><span class="k">fn</span><span class="w"> </span><span class="nf">message</span><span class="p">(</span><span class="o">&amp;</span><span class="bp">self</span><span class="p">)</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="nb">String</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="bp">self</span><span class="p">.</span><span class="n">to_string</span><span class="p">()</span><span class="w"> </span><span class="p">}</span>
+<span class="w">    </span><span class="k">fn</span><span class="w"> </span><span class="nf">message</span><span class="p">(</span><span class="o">&amp;</span><span class="bp">self</span><span class="p">)</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="nb">String</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="bp">self</span><span class="p">.</span><span class="n">to_string</span><span class="p">()</span><span class="w"> </span><span class="p">}</span>
 <span class="p">}</span>
 
 <span class="k">impl</span><span class="w"> </span><span class="nb">From</span><span class="o">&lt;</span><span class="n">anyhow</span><span class="p">::</span><span class="n">Error</span><span class="o">&gt;</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="n">MyError</span><span class="w"> </span><span class="p">{</span>

0.28/udl/ext_types.html

@@ -1444,26 +1444,31 @@ <h2 id="types-in-another-crate">Types in another crate</h2>
 <p><a href="ext_types_external.html">There's a whole page about that!</a></p>
 <h2 id="types-from-procmacros-in-this-crate">Types from procmacros in this crate.</h2>
 <p>If your crate has types defined via <code>#[uniffi::export]</code> etc you can make them available
-to the UDL file in your own crate via a <code>typedef</code> with a <code>[Rust=]</code> attribute. Eg, your Rust
-might have:</p>
+to the UDL file in your own crate via a <code>typedef</code> describing the concrete type.</p>
 <p><div class="highlight"><pre><span></span><code><span class="cp">#[derive(uniffi::Record)]</span>
 <span class="k">pub</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">One</span><span class="w"> </span><span class="p">{</span>
 <span class="w">    </span><span class="n">inner</span><span class="p">:</span><span class="w"> </span><span class="kt">i32</span><span class="p">,</span>
 <span class="p">}</span>
 </code></pre></div>
 you can use it in your UDL:</p>
-<div class="highlight"><pre><span></span><code>[Rust<span class="o">=</span><span class="s2">&quot;record&quot;</span>]
-typedef<span class="w"> </span>extern<span class="w"> </span>One;
+<div class="highlight"><pre><span></span><code>typedef<span class="w"> </span>record<span class="w"> </span>One;
 
 namespace<span class="w"> </span>app<span class="w"> </span>{
 <span class="w">    </span><span class="o">//</span><span class="w"> </span>use<span class="w"> </span>the<span class="w"> </span>procmacro<span class="w"> </span>type.
 <span class="w">    </span>One<span class="w"> </span>get_one(One?<span class="w"> </span>one);
 }
 </code></pre></div>
 <p>Supported values:
-*  "enum", "trait", "callback", "trait_with_foreign"
-* For records, either "record" or "dictionary"
-* For objects, either "object" or "interface"</p>
+* Enums: <code>enum</code>
+* Records: <code>record</code>, <code>dictionary</code> or <code>struct</code>
+* Objects: <code>object</code>, <code>impl</code> or <code>interface</code>
+* Traits: <code>trait</code>, <code>callback</code> or <code>trait_with_foreign</code></p>
+<p>eg:
+<div class="highlight"><pre><span></span><code>typedef enum MyEnum;
+typedef interface MyObject;
+</code></pre></div></p>
+<p>Note that in 0.28 and prior, we also supported this capability with a <code>[Rust=]</code> attribute.
+This attribute is deprecated and may be removed in a later version.</p>