From 420eeaae9e21e82b904be8ba1d00f18460ad3724 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 21:58:20 -0800 Subject: [PATCH 1/6] chore(quest): claim quest/m1/ffi-guide.md Quest-Claim: bf0a498154aab493 From ead00488e0b667f744ca1a03a852b30bc6c09b1d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 22:16:25 -0800 Subject: [PATCH 2/6] ffi: a help note on every refusal, and a guide to writing a facade Co-Authored-By: Claude Sonnet 5.5 --- ffi/FACADE.md | 139 +++++++++++++ ffi/README.md | 2 + ffi/fixtures/reject/expected.txt | 177 ++++++++++++++++ ffi/src/collect.rs | 4 +- ffi/src/driver.rs | 17 +- ffi/src/help.rs | 324 +++++++++++++++++++++++++++++ ffi/src/main.rs | 1 + ffi/tests/fixtures.rs | 22 +- quest/m1/ffi-guide.md | 18 -- quest/m1/ffi-refusals/no-config.md | 4 +- 10 files changed, 683 insertions(+), 25 deletions(-) create mode 100644 ffi/FACADE.md create mode 100644 ffi/src/help.rs delete mode 100644 quest/m1/ffi-guide.md diff --git a/ffi/FACADE.md b/ffi/FACADE.md new file mode 100644 index 000000000..65ac5f0a6 --- /dev/null +++ b/ffi/FACADE.md @@ -0,0 +1,139 @@ +# Writing a facade for rust2-ffi + +[rust2-ffi](README.md) exports the `pub` API of one crate, the facade, and refuses +what it cannot map. +A stock crate's whole API rarely maps, so a facade is a small crate of your own that +re-exports what maps and wraps what does not. +This guide goes from a crate you want in another language to a facade with no refusals. +[The README's rules](README.md#rules) are the full table of what maps. + +## The loop + +1. Make a crate whose library is the facade, depending on the crate at one version: + + ```toml + [package] + name = "shortlink" + version = "0.0.0" + edition = "2024" + + [dependencies] + url = "=2.5.8" + ``` + + Start with `pub use url::*;` in `src/lib.rs`: it is the whole API, and what refuses is + your list of work. +2. Count it with a census, which exports nothing: + + ```bash + echo 'exclude = []' > ffi.toml + rust2-ffi --config ffi.toml --census census --manifest-path Cargo.toml + ``` + +3. Read `census/.md`, as below, and fix the top construct. +4. Repeat until the census refuses nothing, then export with `--out dir`. + +Each refusal is also a compile error at its span when you export, with a `help:` note naming +the change to make. The census only gathers them. + +## What exports + +A facade exports what its `pub` items and their signatures name, by fixed rules: + +- Integers but `i128`, floats, `bool`, `char`, `String`, `&str`, `&[u8]`, `Vec`, + `Option`, `BTreeMap`, `Duration`, socket addresses, and `Result` map by value. + A `Result`'s error becomes each language's own error. +- A struct of `pub` fields that map is a record, copied across; an enum is a C enum or a + tagged union. +- Any other type is an object: an opaque handle with its `pub` methods, which is the usual + shape of a library's type. +- A trait is a callback interface C can implement; a closure parameter is a C function. +- `async fn` and `Future` returns are futures every language awaits in its own way. +- A generic type exports at the instances the facade's signatures and impls name. + +What does not map is, in short: a borrow that outlives the call, a type of another crate no +rule names, an iterator, a `&mut` of a slice, a `Result` with a `()` error, an `unsafe fn`, +and a generic with no bound the exporter maps. + +## What refuses, and what to change + +A refusal reads as a rustc error at the item's span: + +```text +error: rust2-ffi: cannot export method `Link::set_port`: unit error `std::result::Result<(), ()>`; ... + --> src/lib.rs:26:2 + | +26 | pub fn set_port(&mut self, port: Option) -> Result<(), ()> { + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + | + = help: return a `bool` for `Result<(), ()>` or an `Option` for `Result`, or give the error a value, ... +``` + +The name after `cannot export` is the item, then the **construct**, which the census ranks +and the `help:` note is keyed by. A construct whose detail is a type names it in backticks. +The common ones, from refusals in the crates.io top 300: + +| Construct | Seen in | Change | +| --- | --- | --- | +| foreign type | `url`'s `path_segments` returns `Split` | Collect it into a `Vec`, or use `BTreeMap` for `HashMap`. | +| unit error | `url`'s `set_port` returns `Result<(), ()>` | Return a `bool`, an `Option`, or an error with a value. | +| borrowed return that is not Clone | `walkdir`'s `file_name` returns `&OsStr` | Return an owned `OsString`, or a `String`. | +| returned borrow of a value written back | `uuid`'s `encode_lower` returns `&mut str` of a buffer it was given | Return an owned `String`. | +| &mut of a slice | `base64`'s `encode_engine_slice` writes into `&mut [u8]` | Return the bytes as a `Vec`. | +| unsized type | `base64`'s `encode_engine` takes `T: AsRef<[u8]>` | Take `&[u8]` or `Vec`. | +| 'static borrow | `url`'s `ParseOptions::base_url` holds `Option<&Url>` | Hold an owned value, such as an `Arc` or a clone. | +| generic parameter | `shlex`'s `join` takes any `IntoIterator` | Take `Vec`, or bound it by `Into`, `AsRef`, or `Fn`. | +| closure signature | `walkdir`'s `sort_by` returns an `Ordering` | Return a value C holds, such as an integer or `bool`. | +| unsafe fn | `shlex`'s `from_bytes` | Export a safe function that checks what it needs. | +| macro | `indexmap`'s `indexmap!` | Export a function that does the same. | +| re-export of a whole crate | `url`'s `pub use form_urlencoded;` | Re-export its items, `pub use dep::*;`, or wrap the few it needs. | + +Where the crate's own type is the problem, as in `Url`'s methods above, the facade defines a +type of its own around it and exposes the methods that map, each calling the original: + +```rust +pub struct Link(url::Url); + +impl Link { + pub fn parse(text: &str) -> Result { + url::Url::parse(text).map(Link) + } + + pub fn segments(&self) -> Vec { + match self.0.path_segments() { + Some(segments) => segments.map(str::to_string).collect(), + None => Vec::new(), + } + } + + pub fn set_port(&mut self, port: Option) -> bool { + self.0.set_port(port).is_ok() + } +} +``` + +This exports with no refusals: `Link` is an object, `parse` fails with `ParseError`'s message, +and every other method is a call a language can make. + +## Reading the census + +`census/.md` holds, in order: + +- **A table of counts**: types, functions, methods and fields, traits, constants, and what + share of each exports. +- **Refusals by construct**: each construct, how many items it refuses (an item refused for + several counts under each), and the first span. Fix the top row first: it is the most items + for one change. +- **Refusals by type or path**: the same by the type the construct names, as 18 items + refused for `[u8]` points at one signature shape. +- **Refused items**: each item, its span, and every reason, which is what the compile error + prints. +- **The config that exports what maps**: the `exclude` that leaves the refused items out, + which the export accepts today. +- **What exports another way, or is left out and listed**: a value exported as an object + since a field does not map, a `#[doc(hidden)]` item, what C can never hold, such as an + object no export returns, and a type alias. None of these is an error; they need no change + unless you want them exported as they are. + +A census that refuses nothing is the facade done. Its counts show the share of the API +that exports, so one that is low is a facade whose wrapper types are still to write. diff --git a/ffi/README.md b/ffi/README.md index a5462979f..caa789d36 100644 --- a/ffi/README.md +++ b/ffi/README.md @@ -7,6 +7,8 @@ Every language's generator but Python's builds on the C ABI. It targets facades written for the exporter's mapping rules. A stock crate's whole public API is not generally exportable: generic and borrow signatures can be refused, and the census also lists API items left out by those rules. +[Writing a facade](FACADE.md) goes from a crate to a facade with no refusals, and says +what each refusal asks you to change. ```bash rust2-ffi --config ffi.toml (--out dir | --census dir | --api file) [--manifest-path Cargo.toml] [--target triple]... [--with file]... [--baseline api.json] [-- cargo args] diff --git a/ffi/fixtures/reject/expected.txt b/ffi/fixtures/reject/expected.txt index 300096844..fdf4f1057 100644 --- a/ffi/fixtures/reject/expected.txt +++ b/ffi/fixtures/reject/expected.txt @@ -1,188 +1,365 @@ fixtures/reject/src/lib.rs:1017:2: rust2-ffi: cannot export method `Risky::new`: unsafe fn; exclude it in the config to leave it out + help: make it safe, or export a safe function that checks the preconditions and calls it fixtures/reject/src/lib.rs:1023:1: rust2-ffi: cannot export fn `poll_risky`: Poll with no Context or waiter parameter `std::task::Poll<()>`; exclude it in the config to leave it out + help: take a `&mut Context`, or a waiter, which a poll registers its wake through fixtures/reject/src/lib.rs:1039:1: rust2-ffi: cannot export fn `poll_loose`: Poll with no Context or waiter parameter `std::task::Poll<()>`; exclude it in the config to leave it out + help: take a `&mut Context`, or a waiter, which a poll registers its wake through fixtures/reject/src/lib.rs:1046:1: rust2-ffi: cannot export fn `among`: 3 optional borrowed objects, past the 2 Swift takes, which overloads each with and without it since its optional holds an object only by consuming it; exclude it in the config to leave it out + help: take at most two optional borrowed objects, or split the function, or group them into a record fixtures/reject/src/lib.rs:1052:1: rust2-ffi: cannot export fn `wrapped`: error holding an object Swift cannot copy, as `Swift.Error` requires; exclude it in the config to leave it out + help: hold values, a `String`, or a `Copy` handle in the error, since `Swift.Error` must be copyable fixtures/reject/src/lib.rs:1057:1: rust2-ffi: cannot export fn `sum_pair`: array of an element other than u8 `[u16; 2]`; exclude it in the config to leave it out + help: take `&[T]` or `Vec`; an array of other elements only returns fixtures/reject/src/lib.rs:1062:1: rust2-ffi: cannot export fn `empty`: empty array `[u8; 0]`; exclude it in the config to leave it out + help: remove the zero-length array, which C cannot hold fixtures/reject/src/lib.rs:1068:1: rust2-ffi: cannot export enum `Wide`: discriminant outside `i32` `Large = 1099511627776`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:1070:2: note: has this discriminant + help: give each variant a discriminant within `i32`, as a C enum holds fixtures/reject/src/lib.rs:106:1: rust2-ffi: cannot export fn `forever_mut`: 'static borrow `&'static mut [u8]`; &mut of a slice `[u8]`; exclude it in the config to leave it out + help: take an owned value, such as a `String` or an `Arc`, where the handle keeps it; only `&str` and `&[u8]` may be kept + help: take `&[u8]` and return the changed `Vec`, or hold the buffer in an object; C lends no buffer mutably fixtures/reject/src/lib.rs:1075:1: rust2-ffi: cannot export enum `Huge`: discriminant outside `i32` `Large = 18446744073709551616`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:1077:2: note: has this discriminant + help: give each variant a discriminant within `i32`, as a C enum holds fixtures/reject/src/lib.rs:1082:1: rust2-ffi: cannot export enum `Top`: discriminant outside `i32` `Large = 340282366920938463463374607431768211455`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:1084:2: note: has this discriminant + help: give each variant a discriminant within `i32`, as a C enum holds fixtures/reject/src/lib.rs:1088:1: rust2-ffi: cannot export fn `raw`: unsafe fn; exclude it in the config to leave it out + help: make it safe, or export a safe function that checks the preconditions and calls it fixtures/reject/src/lib.rs:1093:1: rust2-ffi: cannot export fn `sum`: C-variadic function; exclude it in the config to leave it out + help: make it safe, or export a safe function that checks the preconditions and calls it fixtures/reject/src/lib.rs:1099:1: rust2-ffi: cannot export fn `custom`: uncallable ABI `"custom"`; exclude it in the config to leave it out + help: make it safe, or export a safe function that checks the preconditions and calls it fixtures/reject/src/lib.rs:1113:2: rust2-ffi: cannot export method `Raw::peek`: unsafe fn; exclude it in the config to leave it out + help: make it safe, or export a safe function that checks the preconditions and calls it fixtures/reject/src/lib.rs:1119:1: rust2-ffi: cannot export trait `Trusted`: unsafe trait; exclude it in the config to leave it out + help: make the trait safe, or take an exported type instead of the trait fixtures/reject/src/lib.rs:1124:1: rust2-ffi: cannot export trait `Hazard`: unsafe fn `risk`; exclude it in the config to leave it out + help: make it safe, or export a safe function that checks the preconditions and calls it fixtures/reject/src/lib.rs:1129:1: rust2-ffi: cannot export fn `trust`: trait object `dyn Trusted`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:1119:1: note: C cannot implement `Trusted`: unsafe trait + help: take a generic `impl Trait` or an `Arc` of one of the crate's traits C can implement, or a closure `impl Fn(..)` fixtures/reject/src/lib.rs:112:1: rust2-ffi: cannot export fn `boxed`: reference inside a parameter `std::boxed::Box<&str>`; exclude it in the config to leave it out + help: take the reference as the whole parameter, or as `Some` of an `Option`, and an owned value inside a `Box` or a struct fixtures/reject/src/lib.rs:1134:1: rust2-ffi: cannot export fn `hazard`: trait object `dyn Hazard`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:1124:1: note: C cannot implement `Hazard`: unsafe fn `risk` + help: take a generic `impl Trait` or an `Arc` of one of the crate's traits C can implement, or a closure `impl Fn(..)` fixtures/reject/src/lib.rs:1139:1: rust2-ffi: cannot export fn `wide_non_zero`: NonZero `u128`; exclude it in the config to leave it out + help: use `NonZero` of an integer of 64 bits or fewer fixtures/reject/src/lib.rs:1161:1: rust2-ffi: cannot export fn `wrap`: returned object that borrows `View<'_>`; exclude it in the config to leave it out + help: return an owned object that borrows nothing, or a guard of a `&mut self` method borrowing the receiver alone fixtures/reject/src/lib.rs:1166:1: rust2-ffi: cannot export fn `hidden_wrap`: returned object that borrows `impl std::clone::Clone + '_`; exclude it in the config to leave it out + help: return an owned object that borrows nothing, or a guard of a `&mut self` method borrowing the receiver alone fixtures/reject/src/lib.rs:1182:1: rust2-ffi: cannot export fn `picked`: closure signature `&'static Mark`; exclude it in the config to leave it out + help: take and return values a callback maps: integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error fixtures/reject/src/lib.rs:1187:1: rust2-ffi: cannot export fn `maybe_picked`: closure signature `std::option::Option<&'static Mark>`; exclude it in the config to leave it out + help: take and return values a callback maps: integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error fixtures/reject/src/lib.rs:1192:1: rust2-ffi: cannot export fn `hidden_answer`: opaque type `impl std::marker::Copy`; exclude it in the config to leave it out + help: return a named type, or an `impl Trait` hiding an exported object that captures no borrow, as `+ use<>` ensures fixtures/reject/src/lib.rs:1197:1: rust2-ffi: cannot export fn `hidden_items`: opaque type `impl std::marker::Copy`; exclude it in the config to leave it out + help: return a named type, or an `impl Trait` hiding an exported object that captures no borrow, as `+ use<>` ensures fixtures/reject/src/lib.rs:11:1: rust2-ffi: cannot export fn `map`: foreign type `std::collections::HashMap`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:1202:1: rust2-ffi: cannot export fn `hidden_option`: opaque type `impl std::clone::Clone`; exclude it in the config to leave it out + help: return a named type, or an `impl Trait` hiding an exported object that captures no borrow, as `+ use<>` ensures fixtures/reject/src/lib.rs:1207:1: rust2-ffi: cannot export fn `boxed_bytes`: boxed slice of bytes `std::boxed::Box<[u8]>`; exclude it in the config to leave it out + help: use `Vec` or `bytes::Bytes` instead of `Box<[u8]>` fixtures/reject/src/lib.rs:1212:1: rust2-ffi: cannot export fn `count_later`: iterator of borrows in a future or callback; exclude it in the config to leave it out + help: take `Vec` or `impl IntoIterator` of owned items, which the future or callback may keep fixtures/reject/src/lib.rs:1217:1: rust2-ffi: cannot export fn `count_opaques`: generic parameter `std::iter::Iterator`; exclude it in the config to leave it out + help: bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type fixtures/reject/src/lib.rs:1222:1: rust2-ffi: cannot export fn `unpin_resolver`: trait object `dyn tls::held::Resolver + std::marker::Unpin`; exclude it in the config to leave it out + help: take a generic `impl Trait` or an `Arc` of one of the crate's traits C can implement, or a closure `impl Fn(..)` fixtures/reject/src/lib.rs:1227:1: rust2-ffi: cannot export fn `borrowed_resolver`: returned object that borrows `std::sync::Arc<(dyn tls::held::Resolver + 'a)>`; exclude it in the config to leave it out + help: return an owned object that borrows nothing, or a guard of a `&mut self` method borrowing the receiver alone fixtures/reject/src/lib.rs:1232:1: rust2-ffi: cannot export fn `peek_resolver`: reference to a handle inside a value `std::option::Option>`; exclude it in the config to leave it out + help: take the object as `&T` itself, not inside an `Option` or a `Box`, which move it out of the caller's handle fixtures/reject/src/lib.rs:1237:1: rust2-ffi: cannot export fn `peek_codec`: trait object `dyn tls::held::Codec`; exclude it in the config to leave it out + help: take a generic `impl Trait` or an `Arc` of one of the crate's traits C can implement, or a closure `impl Fn(..)` fixtures/reject/src/lib.rs:1252:1: rust2-ffi: cannot export fn `pump_pipe`: generic parameter `tls::held::Stream`; exclude it in the config to leave it out + help: bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type fixtures/reject/src/lib.rs:1257:1: rust2-ffi: cannot export fn `pump_sink`: generic parameter `tls::held::Sink`; exclude it in the config to leave it out + help: bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type fixtures/reject/src/lib.rs:1262:1: rust2-ffi: cannot export fn `widen`: generic parameter `tls::held::Width`; exclude it in the config to leave it out + help: bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type fixtures/reject/src/lib.rs:1278:2: rust2-ffi: cannot export method `Counter::try_bump`: `&mut self` of a value returning a Result; exclude it in the config to leave it out + help: return the changed value with the result, or make the type an object by giving it a private field, since a failure would lose the change fixtures/reject/src/lib.rs:1283:2: rust2-ffi: cannot export method `Counter::bump_later`: `&mut self` of a value in a future; exclude it in the config to leave it out + help: take `&self`, or return the changed value instead of mutating it, or make the type an object by giving it a private field fixtures/reject/src/lib.rs:1288:2: rust2-ffi: cannot export method `Counter::bump_ref`: returned borrow of a value written back `&u8`; exclude it in the config to leave it out + help: return an owned value, or make the type an object by giving it a private field, so `&mut self` writes nothing back fixtures/reject/src/lib.rs:128:1: rust2-ffi: cannot export fn `poll_ready`: Poll with no Context or waiter parameter `std::task::Poll`; exclude it in the config to leave it out + help: take a `&mut Context`, or a waiter, which a poll registers its wake through fixtures/reject/src/lib.rs:1295:1: rust2-ffi: cannot export fn `object_alone`: JObject with no &mut jni::Env; exclude it in the config to leave it out + help: take a `&mut jni::Env` beside the `JObject` fixtures/reject/src/lib.rs:1300:1: rust2-ffi: cannot export fn `two_envs`: several JNI envs; exclude it in the config to leave it out + help: take one `&mut jni::Env` fixtures/reject/src/lib.rs:1305:1: rust2-ffi: cannot export fn `env_later`: JNI value lent to a future; exclude it in the config to leave it out + help: take JNI's `&mut Env` and `JObject` in a plain function, which Kotlin calls, not in a callback or a future fixtures/reject/src/lib.rs:1310:1: rust2-ffi: cannot export fn `env_counted`: &mut of a value beside a JNI value; exclude it in the config to leave it out + help: take the value by value and return the changed one, or drop the JNI value fixtures/reject/src/lib.rs:1316:1: rust2-ffi: cannot export fn `shared_env`: JNI type other than a parameter's &mut Env or JObject `jni::Env<'_>`; exclude it in the config to leave it out + help: take only `&mut jni::Env` or `JObject` of jni's types, and as a parameter fixtures/reject/src/lib.rs:1321:1: rust2-ffi: cannot export fn `java_string`: JNI type other than a parameter's &mut Env or JObject `jni::objects::JString<'_>`; exclude it in the config to leave it out + help: take only `&mut jni::Env` or `JObject` of jni's types, and as a parameter fixtures/reject/src/lib.rs:1330:1: rust2-ffi: cannot export fn `visit`: trait object `dyn Visit`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:1326:1: note: C cannot implement `Visit`: JNI value in a callback `&mut jni::Env<'_>` + help: take a generic `impl Trait` or an `Arc` of one of the crate's traits C can implement, or a closure `impl Fn(..)` fixtures/reject/src/lib.rs:1336:1: rust2-ffi: cannot export fn `keep_object`: 'static borrow `jni::objects::JObject<'static>`; exclude it in the config to leave it out + help: take an owned value, such as a `String` or an `Arc`, where the handle keeps it; only `&str` and `&[u8]` may be kept fixtures/reject/src/lib.rs:1341:1: rust2-ffi: cannot export fn `bound_object`: 'static borrow `&mut jni::Env<'a>`; 'static borrow `jni::objects::JObject<'a>`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:1341:21: note: `'a` is `'static`, as a handle outlives every call fixtures/reject/src/lib.rs:1341:21: note: `'a` is `'static`, as a handle outlives every call + help: take an owned value, such as a `String` or an `Arc`, where the handle keeps it; only `&str` and `&[u8]` may be kept fixtures/reject/src/lib.rs:1365:2: rust2-ffi: cannot export method `Slot::view`: returned object that borrows `SlotView<'_, u8>`; exclude it in the config to leave it out + help: return an owned object that borrows nothing, or a guard of a `&mut self` method borrowing the receiver alone fixtures/reject/src/lib.rs:1371:2: rust2-ffi: cannot export method `Slot::peek`: returned object that borrows `SlotView<'_, u8>`; exclude it in the config to leave it out + help: return an owned object that borrows nothing, or a guard of a `&mut self` method borrowing the receiver alone fixtures/reject/src/lib.rs:1423:2: rust2-ffi: cannot export method `Slot::hold`: returned object that borrows `SlotHold<'a>`; exclude it in the config to leave it out + help: return an owned object that borrows nothing, or a guard of a `&mut self` method borrowing the receiver alone fixtures/reject/src/lib.rs:1431:2: rust2-ffi: cannot export method `Slot::tag`: returned object that borrows `SlotTag<'_>`; exclude it in the config to leave it out + help: return an owned object that borrows nothing, or a guard of a `&mut self` method borrowing the receiver alone fixtures/reject/src/lib.rs:1436:2: rust2-ffi: cannot export method `Slot::lens`: returned object that borrows `SlotLens<'_>`; exclude it in the config to leave it out + help: return an owned object that borrows nothing, or a guard of a `&mut self` method borrowing the receiver alone fixtures/reject/src/lib.rs:1441:2: rust2-ffi: cannot export method `Slot::peer`: returned object that borrows `SlotPeer<'_>`; exclude it in the config to leave it out + help: return an owned object that borrows nothing, or a guard of a `&mut self` method borrowing the receiver alone fixtures/reject/src/lib.rs:145:2: rust2-ffi: cannot export method `Link::session`: borrowed return that is not Clone `tls::held::Handoff`; exclude it in the config to leave it out + help: return an owned value or a `Clone` type, since a borrowed return crosses as a clone fixtures/reject/src/lib.rs:1477:1: rust2-ffi: cannot export fn `unit_error`: unit error `std::result::Result<(), ()>`; exclude it in the config to leave it out + help: return an `Option` or a `bool`, or give the error a value, such as a `String` or an error type of yours fixtures/reject/src/lib.rs:1482:1: rust2-ffi: cannot export fn `unit_error_later`: unit error `std::result::Result`; exclude it in the config to leave it out + help: return an `Option` or a `bool`, or give the error a value, such as a `String` or an error type of yours fixtures/reject/src/lib.rs:1513:1: rust2-ffi: cannot export fn `race`: instance holding a foreign future `reject::Either<((), std::pin::Pin + std::marker::Send>>), ((), std::pin::Pin + std::marker::Send>>)>`; exclude it in the config to leave it out + help: name a future of `()` C implements, or make the instance own no future fixtures/reject/src/lib.rs:1521:1: rust2-ffi: cannot export fn `park`: instance holding a foreign future `reject::Parked + std::marker::Send>>>`; exclude it in the config to leave it out + help: name a future of `()` C implements, or make the instance own no future fixtures/reject/src/lib.rs:1527:1: rust2-ffi: cannot export instance `Bits`: union; exclude it in the config to leave it out + help: use a struct or an enum fixtures/reject/src/lib.rs:1533:1: rust2-ffi: cannot export fn `bits`: refused type `reject::Bits`; exclude it in the config to leave it out + help: fix the refusal of the type it names first, or use a type that exports fixtures/reject/src/lib.rs:1539:1: rust2-ffi: cannot export instance `Tail`: unsized type; exclude it in the config to leave it out + help: pass `&str` or `&[T]` instead, or return an owned `String` or `Vec`; a struct whose last field is unsized needs a sized form fixtures/reject/src/lib.rs:1542:1: rust2-ffi: cannot export fn `tail`: 'static borrow `&'static Tail`; refused type `reject::Tail`; exclude it in the config to leave it out + help: take an owned value, such as a `String` or an `Arc`, where the handle keeps it; only `&str` and `&[u8]` may be kept + help: fix the refusal of the type it names first, or use a type that exports fixtures/reject/src/lib.rs:162:1: rust2-ffi: cannot export fn `measure`: foreign type `tls::held::Local`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:167:1: rust2-ffi: cannot export instance `Cell>`: type argument `std::vec::Vec`; exclude it in the config to leave it out + help: instantiate it at types that map, such as integers, `String`, or an exported type; `&str`, `Cow`, and other borrows do not fixtures/reject/src/lib.rs:167:1: rust2-ffi: cannot export instance `Cell`: type argument `tls::held::Cert`; exclude it in the config to leave it out + help: instantiate it at types that map, such as integers, `String`, or an exported type; `&str`, `Cow`, and other borrows do not fixtures/reject/src/lib.rs:16:1: rust2-ffi: cannot export fn `generic`: generic parameter `std::marker::Copy`; exclude it in the config to leave it out + help: bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type fixtures/reject/src/lib.rs:170:1: rust2-ffi: cannot export fn `sealed`: refused type `reject::Cell`; exclude it in the config to leave it out + help: fix the refusal of the type it names first, or use a type that exports fixtures/reject/src/lib.rs:199:1: rust2-ffi: cannot export fn `echo`: borrowing output of a future from a function that is not async `&str`; exclude it in the config to leave it out + help: make it an `async fn`, or return an output that borrows nothing fixtures/reject/src/lib.rs:204:1: rust2-ffi: cannot export fn `blame`: borrowing output of a future from a function that is not async `std::result::Result>`; exclude it in the config to leave it out + help: make it an `async fn`, or return an output that borrows nothing fixtures/reject/src/lib.rs:209:1: rust2-ffi: cannot export fn `relay`: borrowing output of a future from a function that is not async `&str`; exclude it in the config to leave it out + help: make it an `async fn`, or return an output that borrows nothing fixtures/reject/src/lib.rs:214:1: rust2-ffi: cannot export fn `resolve`: borrowing output of a future from a function that is not async `&str`; exclude it in the config to leave it out + help: make it an `async fn`, or return an output that borrows nothing fixtures/reject/src/lib.rs:219:1: rust2-ffi: cannot export fn `spend`: closure signature `tls::held::Token`; exclude it in the config to leave it out + help: take and return values a callback maps: integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error fixtures/reject/src/lib.rs:21:1: rust2-ffi: cannot export fn `nested`: nested Option `std::option::Option>>`; exclude it in the config to leave it out + help: use one `Option`, or wrap the inner one in an enum, since C has one `None` per option fixtures/reject/src/lib.rs:224:1: rust2-ffi: cannot export fn `mint`: closure signature `tls::held::Token`; exclude it in the config to leave it out + help: take and return values a callback maps: integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error fixtures/reject/src/lib.rs:234:1: rust2-ffi: cannot export fn `spent`: reference to a handle inside a value `[tls::held::Token]`; exclude it in the config to leave it out + help: take the object as `&T` itself, not inside an `Option` or a `Box`, which move it out of the caller's handle fixtures/reject/src/lib.rs:244:1: rust2-ffi: cannot export fn `adopt`: generic parameter `std::convert::Into`; exclude it in the config to leave it out + help: bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type fixtures/reject/src/lib.rs:256:2: rust2-ffi: cannot export method `Cell::nest`: instance holding an instance of a type inside it `reject::Cell>`; exclude it in the config to leave it out + help: do not nest the generic type in itself at a deeper instance, as `Cell>` does fixtures/reject/src/lib.rs:275:2: rust2-ffi: cannot export method `Pong>::ping`: instance holding an instance of a type inside it `reject::Ping>>`; exclude it in the config to leave it out + help: do not nest the generic type in itself at a deeper instance, as `Cell>` does fixtures/reject/src/lib.rs:286:1: rust2-ffi: cannot export instance `Grow<(u32,)>`: type argument `(u32,)`; exclude it in the config to leave it out + help: instantiate it at types that map, such as integers, `String`, or an exported type; `&str`, `Cow`, and other borrows do not fixtures/reject/src/lib.rs:289:2: rust2-ffi: cannot export method `Grow::grow`: refused type `reject::Grow<(u32,)>`; exclude it in the config to leave it out + help: fix the refusal of the type it names first, or use a type that exports fixtures/reject/src/lib.rs:300:1: rust2-ffi: cannot export instance `Shell<(u32,)>`: type argument `(u32,)`; exclude it in the config to leave it out + help: instantiate it at types that map, such as integers, `String`, or an exported type; `&str`, `Cow`, and other borrows do not fixtures/reject/src/lib.rs:309:1: rust2-ffi: cannot export fn `shell`: refused type `reject::Shell<(u32,)>`; exclude it in the config to leave it out + help: fix the refusal of the type it names first, or use a type that exports fixtures/reject/src/lib.rs:30:1: rust2-ffi: cannot export fn `peek`: reference to a handle inside a value `std::boxed::Box`; exclude it in the config to leave it out + help: take the object as `&T` itself, not inside an `Option` or a `Box`, which move it out of the caller's handle fixtures/reject/src/lib.rs:320:1: rust2-ffi: cannot export fn `probe`: const generic `N`; exclude it in the config to leave it out + help: pass the const parameter to a generic type in the signature, so each instance an export names supplies its values fixtures/reject/src/lib.rs:325:1: rust2-ffi: cannot export fn `excluded_cell`: excluded type `reject::Cell`; exclude it in the config to leave it out + help: the config leaves this type out, so leave out each item that names it too fixtures/reject/src/lib.rs:330:1: rust2-ffi: cannot export fn `listed`: refused type `reject::Cell>`; exclude it in the config to leave it out + help: fix the refusal of the type it names first, or use a type that exports fixtures/reject/src/lib.rs:335:1: rust2-ffi: cannot export instance `Fixed<'a'>`: const argument `'a'`; exclude it in the config to leave it out + help: use a `bool` or an integer below 128 bits for a const argument fixtures/reject/src/lib.rs:338:1: rust2-ffi: cannot export fn `fixed`: refused type `reject::Fixed<'a'>`; exclude it in the config to leave it out + help: fix the refusal of the type it names first, or use a type that exports fixtures/reject/src/lib.rs:343:9: rust2-ffi: cannot export use `HashSet`: re-export of the standard library's item `std`; exclude it in the config to leave it out + help: name the standard library's type in signatures, where it maps by role, instead of re-exporting it fixtures/reject/src/lib.rs:346:1: rust2-ffi: cannot export fn `lend`: Waker outside a parameter or a return; exclude it in the config to leave it out + help: take or return a `Waker` only as a parameter or a return, not in a field or a collection fixtures/reject/src/lib.rs:354:2: rust2-ffi: cannot export field `Tag::label`: 'static borrow `&'static str`; exclude it in the config to leave it out + help: take an owned value, such as a `String` or an `Arc`, where the handle keeps it; only `&str` and `&[u8]` may be kept fixtures/reject/src/lib.rs:35:1: rust2-ffi: cannot export static `COUNT`: static; exclude it in the config to leave it out + help: export a function returning the value, or a `const` fixtures/reject/src/lib.rs:364:1: rust2-ffi: cannot export fn `gather`: closure signature `std::vec::Vec`; exclude it in the config to leave it out + help: take and return values a callback maps: integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error fixtures/reject/src/lib.rs:369:1: rust2-ffi: cannot export fn `attempt`: closure signature `std::result::Result`; exclude it in the config to leave it out + help: take and return values a callback maps: integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error fixtures/reject/src/lib.rs:374:1: rust2-ffi: cannot export fn `consume`: reader not lent as &mut `impl std::io::Read + std::io::Seek`; exclude it in the config to leave it out + help: take the reader as `&mut R` fixtures/reject/src/lib.rs:379:1: rust2-ffi: cannot export fn `retain`: reader kept past the call `R`; exclude it in the config to leave it out + help: do not return or keep the reader, which C lends only for the call fixtures/reject/src/lib.rs:384:1: rust2-ffi: cannot export fn `rewrite`: reader bound `std::io::Write`; exclude it in the config to leave it out + help: bound the reader by `Read` and `Seek` alone fixtures/reject/src/lib.rs:389:1: rust2-ffi: cannot export fn `read_later`: reader kept past the call `impl std::io::Read + std::io::Seek`; exclude it in the config to leave it out + help: do not return or keep the reader, which C lends only for the call fixtures/reject/src/lib.rs:394:1: rust2-ffi: cannot export fn `twice`: closure bound `std::clone::Clone`; exclude it in the config to leave it out + help: bound the closure by `Fn`, `FnMut`, or `FnOnce` alone, besides `Send`, `Sync`, and a lifetime fixtures/reject/src/lib.rs:39:1: rust2-ffi: cannot export macro `noop`: macro; exclude it in the config to leave it out + help: export a function that does what the macro does, or mark the macro `#[doc(hidden)]` fixtures/reject/src/lib.rs:400:1: rust2-ffi: cannot export fn `both`: closure type taken twice `F`; exclude it in the config to leave it out + help: take the closure's type once, with a type parameter for each closure fixtures/reject/src/lib.rs:406:1: rust2-ffi: cannot export fn `read`: lent object that borrows `&Text<'_>`; exclude it in the config to leave it out + help: name no lifetime on the lent type, or fix it to `'static`, since a handle holds it at `'static` fixtures/reject/src/lib.rs:411:1: rust2-ffi: cannot export fn `count_words`: Vec of references `&str`; exclude it in the config to leave it out + help: take owned items, or only return the references: C lends nothing inside a collection, tuple, or iterator fixtures/reject/src/lib.rs:416:1: rust2-ffi: cannot export fn `count_some`: Vec of references `std::option::Option<&str>`; exclude it in the config to leave it out + help: take owned items, or only return the references: C lends nothing inside a collection, tuple, or iterator fixtures/reject/src/lib.rs:421:1: rust2-ffi: cannot export fn `count_slice`: slice of references `&str`; exclude it in the config to leave it out + help: take owned items, or only return the references: C lends nothing inside a collection, tuple, or iterator fixtures/reject/src/lib.rs:426:1: rust2-ffi: cannot export fn `peek_all`: reference to a handle inside a value `[Opaque]`; exclude it in the config to leave it out + help: take the object as `&T` itself, not inside an `Option` or a `Box`, which move it out of the caller's handle fixtures/reject/src/lib.rs:431:1: rust2-ffi: cannot export fn `none_opaque`: borrowed return that is not Clone `[Opaque]`; exclude it in the config to leave it out + help: return an owned value or a `Clone` type, since a borrowed return crosses as a clone fixtures/reject/src/lib.rs:443:1: rust2-ffi: cannot export fn `stash`: generic parameter `std::convert::Into`; exclude it in the config to leave it out + help: bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type fixtures/reject/src/lib.rs:458:1: rust2-ffi: cannot export fn `hold`: generic parameter `std::convert::Into`; exclude it in the config to leave it out + help: bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type fixtures/reject/src/lib.rs:463:1: rust2-ffi: cannot export fn `bound`: generic parameter `std::convert::Into`; exclude it in the config to leave it out + help: bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type fixtures/reject/src/lib.rs:468:1: rust2-ffi: cannot export fn `kept`: generic parameter `std::convert::Into`; exclude it in the config to leave it out + help: bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type fixtures/reject/src/lib.rs:47:1: rust2-ffi: cannot export fn `excluded`: excluded type `Excluded`; exclude it in the config to leave it out + help: the config leaves this type out, so leave out each item that names it too fixtures/reject/src/lib.rs:482:1: rust2-ffi: cannot export fn `holder`: generic parameter `std::convert::Into`; exclude it in the config to leave it out + help: bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type fixtures/reject/src/lib.rs:496:1: rust2-ffi: cannot export fn `lender`: generic parameter `std::convert::Into`; exclude it in the config to leave it out + help: bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type fixtures/reject/src/lib.rs:511:1: rust2-ffi: cannot export fn `outlived`: generic parameter `std::convert::Into`; exclude it in the config to leave it out + help: bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type fixtures/reject/src/lib.rs:526:1: rust2-ffi: cannot export fn `paired`: generic parameter `std::convert::Into`; exclude it in the config to leave it out + help: bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type fixtures/reject/src/lib.rs:52:1: rust2-ffi: cannot export fn `letters`: Range `char`; exclude it in the config to leave it out + help: use `Range` or `Bound` of an integer of 64 bits or fewer fixtures/reject/src/lib.rs:549:1: rust2-ffi: cannot export fn `pinner`: generic parameter `std::convert::Into`; exclude it in the config to leave it out + help: bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type fixtures/reject/src/lib.rs:564:1: rust2-ffi: cannot export fn `grows`: growing conversion `Grows`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:556:1: note: applies past the recursion limit + help: break the chain of `From` impls, which names ever more types fixtures/reject/src/lib.rs:594:1: rust2-ffi: cannot export fn `call`: ambiguous conversion `std::vec::Vec`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:571:1: note: `std::string::String` converts too, which C passes alike + help: convert from one of the sources, as `&str` and `String` are one value, not both a `String` and a `Vec`, which C passes alike fixtures/reject/src/lib.rs:599:1: rust2-ffi: cannot export fn `alphabet`: Range `char`; exclude it in the config to leave it out + help: use `Range` or `Bound` of an integer of 64 bits or fewer fixtures/reject/src/lib.rs:604:1: rust2-ffi: cannot export fn `naturals`: foreign type `std::ops::RangeFrom`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:609:1: rust2-ffi: cannot export fn `opaques`: borrowed return that is not Clone `Opaque`; exclude it in the config to leave it out + help: return an owned value or a `Clone` type, since a borrowed return crosses as a clone fixtures/reject/src/lib.rs:614:1: rust2-ffi: cannot export fn `tried`: foreign type `std::vec::IntoIter`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:619:1: rust2-ffi: cannot export fn `eventually`: foreign type `std::vec::IntoIter`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:645:1: rust2-ffi: cannot export fn `tallied`: unmet bound `u32: std::convert::From`; exclude it in the config to leave it out + help: implement the bound for the type, or loosen it; an instance exports only where every bound holds fixtures/reject/src/lib.rs:650:1: rust2-ffi: cannot export fn `drain`: trait object `dyn Source`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:624:1: note: C cannot implement `Source`: callback signature `items` + help: take a generic `impl Trait` or an `Arc` of one of the crate's traits C can implement, or a closure `impl Fn(..)` fixtures/reject/src/lib.rs:655:1: rust2-ffi: cannot export fn `summed_forever`: 'static borrow `&'static [u32]`; exclude it in the config to leave it out + help: take an owned value, such as a `String` or an `Arc`, where the handle keeps it; only `&str` and `&[u8]` may be kept fixtures/reject/src/lib.rs:660:1: rust2-ffi: cannot export fn `retext_last`: 'static borrow `&'a [std::string::String]`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:660:20: note: `'a` is `'static`, as a handle outlives every call + help: take an owned value, such as a `String` or an `Arc`, where the handle keeps it; only `&str` and `&[u8]` may be kept fixtures/reject/src/lib.rs:667:1: rust2-ffi: cannot export fn `outlast`: 'static borrow `&'b [std::string::String]`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:667:20: note: `'b` is `'static`, as a handle outlives every call + help: take an owned value, such as a `String` or an `Arc`, where the handle keeps it; only `&str` and `&[u8]` may be kept fixtures/reject/src/lib.rs:66:2: rust2-ffi: cannot export method `Text::view`: returned object that borrows `Text<'_>`; exclude it in the config to leave it out + help: return an owned object that borrows nothing, or a guard of a `&mut self` method borrowing the receiver alone fixtures/reject/src/lib.rs:674:1: rust2-ffi: cannot export fn `retext_into`: 'static borrow `&'a [std::string::String]`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:674:20: note: `'a` is `'static`, as a handle outlives every call + help: take an owned value, such as a `String` or an `Arc`, where the handle keeps it; only `&str` and `&[u8]` may be kept fixtures/reject/src/lib.rs:683:1: rust2-ffi: cannot export fn `ones`: foreign type `std::iter::Repeat`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:689:1: rust2-ffi: cannot export fn `long_words`: foreign type `std::iter::Filter`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:695:1: rust2-ffi: cannot export fn `kept_in`: foreign type `std::iter::Filter`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:6:1: rust2-ffi: cannot export fn `pair`: tuple of references `(&str, u8)`; exclude it in the config to leave it out + help: take owned items, or only return the references: C lends nothing inside a collection, tuple, or iterator fixtures/reject/src/lib.rs:712:1: rust2-ffi: cannot export fn `launched`: foreign type `std::iter::Chain`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:729:1: rust2-ffi: cannot export fn `launches`: foreign type `std::iter::Flatten`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:752:1: rust2-ffi: cannot export fn `pumped`: foreign type `std::iter::Flatten`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:766:1: rust2-ffi: cannot export fn `skipped`: foreign type `std::iter::Skip`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:771:1: rust2-ffi: cannot export fn `merged`: foreign type `std::iter::Copied`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:778:1: rust2-ffi: cannot export fn `values`: foreign type `std::collections::btree_map::IntoValues`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:77:1: rust2-ffi: cannot export fn `first`: borrowed return that is not Clone `Opaque`; exclude it in the config to leave it out + help: return an owned value or a `Clone` type, since a borrowed return crosses as a clone fixtures/reject/src/lib.rs:784:1: rust2-ffi: cannot export fn `floats`: collection not built from its items `std::collections::BTreeSet`; exclude it in the config to leave it out + help: use a standard collection, or one implementing `FromIterator` of its items fixtures/reject/src/lib.rs:789:1: rust2-ffi: cannot export fn `zeros`: foreign type `std::iter::RepeatN`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:794:1: rust2-ffi: cannot export fn `successes`: foreign type `std::iter::Flatten`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:814:1: rust2-ffi: cannot export fn `allocated`: foreign type `std::vec::IntoIter`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:821:1: rust2-ffi: cannot export fn `flattened`: foreign type `std::iter::Flatten`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:845:1: rust2-ffi: cannot export fn `lent`: foreign type `std::vec::IntoIter`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:863:1: rust2-ffi: cannot export fn `halves`: foreign type `std::str::Split`; exclude it in the config to leave it out + help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:868:1: rust2-ffi: cannot export fn `settled`: Poll with no Context or waiter parameter `std::task::Poll`; exclude it in the config to leave it out + help: take a `&mut Context`, or a waiter, which a poll registers its wake through fixtures/reject/src/lib.rs:873:1: rust2-ffi: cannot export fn `poll_named`: poll's parameter taken by value that is not Copy `std::string::String`; exclude it in the config to leave it out + help: take it by reference, or make it `Copy`, since each poll calls the function again fixtures/reject/src/lib.rs:879:1: rust2-ffi: cannot export fn `poll_first`: borrowed Poll `&u8`; exclude it in the config to leave it out + help: return an owned `Poll` that borrows nothing from its arguments fixtures/reject/src/lib.rs:885:1: rust2-ffi: cannot export fn `poll_until`: poll's parameter taken by value that is not Copy `impl Fn(u8) -> bool`; exclude it in the config to leave it out + help: take it by reference, or make it `Copy`, since each poll calls the function again fixtures/reject/src/lib.rs:896:1: rust2-ffi: cannot export fn `context_later`: Context of a function returning a future; exclude it in the config to leave it out + help: take a `Context` only in a function returning `Poll`; a function returning a future makes its own fixtures/reject/src/lib.rs:915:1: rust2-ffi: cannot export fn `poll_ticket`: Poll with no Context or waiter parameter `std::task::Poll`; exclude it in the config to leave it out + help: take a `&mut Context`, or a waiter, which a poll registers its wake through fixtures/reject/src/lib.rs:920:1: rust2-ffi: cannot export fn `poll_both`: several task parameters; exclude it in the config to leave it out + help: take one `Context` or one waiter, not several fixtures/reject/src/lib.rs:927:1: rust2-ffi: cannot export fn `poll_bump`: &mut of a value in a future; exclude it in the config to leave it out + help: take the value by value and return the changed one, or hold it in an object changed through `&self` fixtures/reject/src/lib.rs:934:1: rust2-ffi: cannot export fn `peek_some`: reference to a handle inside a value `std::boxed::Box`; exclude it in the config to leave it out + help: take the object as `&T` itself, not inside an `Option` or a `Box`, which move it out of the caller's handle fixtures/reject/src/lib.rs:939:1: rust2-ffi: cannot export fn `bump_some`: &mut of a value inside an Option `std::option::Option<&mut u32>`; exclude it in the config to leave it out + help: take the `&mut` value directly, not inside an `Option` fixtures/reject/src/lib.rs:946:1: rust2-ffi: cannot export fn `rest`: returned borrow of a value written back `&[u8]`; exclude it in the config to leave it out + help: return an owned value, or make the type an object by giving it a private field, so `&mut self` writes nothing back fixtures/reject/src/lib.rs:951:1: rust2-ffi: cannot export fn `fill`: returned borrow of a value written back `impl std::future::Future`; &mut of a value in a future; exclude it in the config to leave it out + help: return an owned value, or make the type an object by giving it a private field, so `&mut self` writes nothing back + help: take the value by value and return the changed one, or hold it in an object changed through `&self` fixtures/reject/src/lib.rs:956:1: rust2-ffi: cannot export fn `zero`: &mut of a slice `[u8]`; exclude it in the config to leave it out + help: take `&[u8]` and return the changed `Vec`, or hold the buffer in an object; C lends no buffer mutably fixtures/reject/src/lib.rs:961:1: rust2-ffi: cannot export fn `reseat`: &mut of another crate's Arc `std::sync::Arc`; exclude it in the config to leave it out + help: take `&Arc`, or the `Arc` by value, since an opaque handle cannot be replaced in place fixtures/reject/src/lib.rs:974:2: rust2-ffi: cannot export method `Keeper::check`: borrowed return that is not Clone `Opaque`; exclude it in the config to leave it out + help: return an owned value or a `Clone` type, since a borrowed return crosses as a clone fixtures/reject/src/lib.rs:985:9: rust2-ffi: cannot export use `dep`: re-export of a whole crate `dep`; exclude it in the config to leave it out + help: re-export the crate's items with `pub use dep::*;`, or wrap the few types a signature needs in types of your own fixtures/reject/src/lib.rs:988:9: rust2-ffi: cannot export use `renamed`: re-export of a whole crate `dep`; exclude it in the config to leave it out + help: re-export the crate's items with `pub use dep::*;`, or wrap the few types a signature needs in types of your own fixtures/reject/src/lib.rs:999:2: rust2-ffi: cannot export method `Tally::poll_bump`: `&mut self` of a value; exclude it in the config to leave it out + help: take `&self`, or return the changed value instead of mutating it, or make the type an object by giving it a private field fixtures/reject/src/lib.rs:99:2: rust2-ffi: cannot export method `Text::later`: returned object that borrows `impl std::future::Future>`; exclude it in the config to leave it out + help: return an owned object that borrows nothing, or a guard of a `&mut self` method borrowing the receiver alone diff --git a/ffi/src/collect.rs b/ffi/src/collect.rs index bdb1c138b..618e65109 100644 --- a/ffi/src/collect.rs +++ b/ffi/src/collect.rs @@ -56,14 +56,14 @@ const FOREIGN: [(&str, &str, &str); 3] = [ /// The construct of another crate's type named both by value and in an `Arc`, whose handle /// holds the `Arc`. -const BOTH: &str = "another crate's type both by value and in an Arc"; +pub(crate) const BOTH: &str = "another crate's type both by value and in an Arc"; /// The construct of an instance inference missed: a bug in the exporter, not the crate. pub(crate) const NOT_INFERRED: &str = "instance not inferred"; /// What C can never hold: left out and listed in the census rather than refused, since /// exporting it would need constructors or returns the crate has no use for. -const UNHELD: [&str; 5] = [ +pub(crate) const UNHELD: [&str; 5] = [ "object no export returns", "value no export returns", "generic type no export instantiates", diff --git a/ffi/src/driver.rs b/ffi/src/driver.rs index 8ee0dec4d..be9e9f546 100644 --- a/ffi/src/driver.rs +++ b/ffi/src/driver.rs @@ -600,7 +600,7 @@ impl Export { // Swift exports the API without what takes a JNI value, which only Kotlin passes. let rest = api.without_jni(); for refusal in crate::swift::refusals(&abi.without_jni(&rest)) { - tcx.dcx().span_err( + let mut err = tcx.dcx().struct_span_err( refusal.function.span, format!( "rust2-ffi: cannot export {} `{}`: {}; exclude it in the config to leave it out", @@ -609,6 +609,10 @@ impl Export { refusal.why ), ); + if let Some(help) = crate::help::of(refusal.construct) { + err = err.with_help(help); + } + err.emit(); } let can_generate = tcx.dcx().has_errors().is_none(); let baseline = match self.baseline(tcx, &target) { @@ -652,7 +656,8 @@ fn stop_on_errors(tcx: TyCtxt<'_>) -> Compilation { } } -/// Emits `refusal` as an error at its span, with every reason and its notes, then `advice`. +/// Emits `refusal` as an error at its span, with every reason, its notes, and how to change the +/// facade, then `advice`. fn refuse(tcx: TyCtxt<'_>, refusal: &collect::Refusal, advice: &str) { let reasons: Vec = refusal .why @@ -674,6 +679,14 @@ fn refuse(tcx: TyCtxt<'_>, refusal: &collect::Refusal, advice: &str) { for (span, note) in refusal.why.iter().filter_map(|why| why.note.as_ref()) { err = err.with_span_note(*span, note.clone()); } + // One note a construct, in the order found, though several reasons may share one. + let mut helped: Vec<&str> = Vec::new(); + for help in refusal.why.iter().filter_map(|why| crate::help::of(why.construct)) { + if !helped.contains(&help) { + helped.push(help); + err = err.with_help(help); + } + } err.emit(); } diff --git a/ffi/src/help.rs b/ffi/src/help.rs new file mode 100644 index 000000000..082700144 --- /dev/null +++ b/ffi/src/help.rs @@ -0,0 +1,324 @@ +//! What to change in a facade to clear each refusal: the `help:` note of its error. +//! +//! Keyed by the refusal's construct, the name the census ranks it by. `of` is total over +//! every construct that refuses an item, which a test checks against the collector's source. + +/// The note for `construct`, or none for one that is no refusal of the facade: a left-out item +/// the census lists, or the exporter's own bug. +pub(crate) fn of(construct: &str) -> Option<&'static str> { + Some(match construct { + // Items. + "re-export of a whole crate" => { + "re-export the crate's items with `pub use dep::*;`, or wrap the few types a signature needs in types of your own" + } + "re-export of the standard library's item" => { + "name the standard library's type in signatures, where it maps by role, instead of re-exporting it" + } + "macro" => "export a function that does what the macro does, or mark the macro `#[doc(hidden)]`", + "static" => "export a function returning the value, or a `const`", + "item kind" => "export a function, type, trait, or constant that wraps it, or mark it `#[doc(hidden)]`", + "excluded type" => "the config leaves this type out, so leave out each item that names it too", + "doc(hidden) type" => "remove `#[doc(hidden)]` from the type, or mark this item `#[doc(hidden)]` too", + "discriminant outside `i32`" => "give each variant a discriminant within `i32`, as a C enum holds", + "non-exhaustive variant" => "remove `#[non_exhaustive]` from the variant, since a binding lists every field", + + // Types. + "union" => "use a struct or an enum", + "unsized type" => { + "pass `&str` or `&[T]` instead, or return an owned `String` or `Vec`; a struct whose last field is unsized needs a sized form" + } + "recursive value" => { + "hold the child behind an `Arc`, or make the type an object by giving it a private field, so it is no value that holds itself" + } + "generic type" => "give the trait no type parameters, since only a trait C can implement exports", + "type argument" => { + "instantiate it at types that map, such as integers, `String`, or an exported type; `&str`, `Cow`, and other borrows do not" + } + "instance holding an instance of a type inside it" => { + "do not nest the generic type in itself at a deeper instance, as `Cell>` does" + } + "unmet bound of the instance" | "unmet bound" => { + "implement the bound for the type, or loosen it; an instance exports only where every bound holds" + } + "const argument" => "use a `bool` or an integer below 128 bits for a const argument", + "const generic" => { + "pass the const parameter to a generic type in the signature, so each instance an export names supplies its values" + } + "constant type" | "constant value" => { + "export a `bool` or an integer below 128 bits, a value that evaluates at compile time, or a function returning the value" + } + "type" => "use a type the README's rules table maps, or wrap it in one of your own", + "128-bit integer" => "use `u128`, which exports, or an integer of 64 bits or fewer", + "NonZero" => "use `NonZero` of an integer of 64 bits or fewer", + "Range" | "Bound" => "use `Range` or `Bound` of an integer of 64 bits or fewer", + "never type" => "return `()`, or no value, instead of `!`", + "raw pointer" => "take a reference, `Vec`, or `&[u8]`, or wrap the pointer in a safe type of your own", + "function value" => "take a generic `impl Fn(..)` instead of a function pointer or a closure's type", + "opaque type" => { + "return a named type, or an `impl Trait` hiding an exported object that captures no borrow, as `+ use<>` ensures" + } + "type parameter" => { + "bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `Read + Seek`, or take a concrete type" + } + "generic parameter" => { + "bound it by a trait the exporter maps, such as `Into`, `AsRef`, `Fn(..)`, or `IntoIterator`, or one of the crate's own traits, or take a concrete type" + } + "foreign type" => { + "use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types" + } + "refused type" => "fix the refusal of the type it names first, or use a type that exports", + "type not reachable from the crate root" => { + "re-export the type with `pub use` from the root, or make it public in its own crate" + } + "instance holding a foreign future" => "name a future of `()` C implements, or make the instance own no future", + "object in a value" => { + "hold a `Copy` handle, or make the containing type an object by giving it a private field" + } + "Arc" => { + "take an `Arc` of a type that is `Send` and `Sync` and maps, or the type itself, which C holds as an `Arc` already" + } + "&mut of another crate's Arc" => { + "take `&Arc`, or the `Arc` by value, since an opaque handle cannot be replaced in place" + } + "another crate's type both by value and in an Arc" => { + "name the type one way across the facade's signatures, behind an `Arc` or by value" + } + "Pin" => "take `Pin<&mut F>` only of a future in a poll, or take the value unpinned", + "Waker outside a parameter or a return" => { + "take or return a `Waker` only as a parameter or a return, not in a field or a collection" + } + "Context outside a return or a polled parameter" => { + "take `&mut Context` as the parameter of a function returning `Poll`, or take a `Waker`" + } + "nested Option" => "use one `Option`, or wrap the inner one in an enum, since C has one `None` per option", + "Result outside a return" => "return the `Result`, instead of taking or holding it", + "unit outside a return" => "leave `()` out of fields, collections, and options, or use a `bool`", + "unit error" => { + "return a `bool` for `Result<(), ()>` or an `Option` for `Result`, or give the error a value, such as a `String` or an error type of yours" + } + "array of an element other than u8" => "take `&[T]` or `Vec`; an array of other elements only returns", + "array of unknown length" => "write the length as a literal, not a const generic parameter", + "empty array" => "remove the zero-length array, which C cannot hold", + "array too long" => "take a slice, `&[u8]`, instead of an array this long", + "boxed slice of bytes" => "use `Vec` or `bytes::Bytes` instead of `Box<[u8]>`", + "boxed slice of references" + | "Vec of references" + | "slice of references" + | "collection of references" + | "iterator of references" + | "tuple of references" => { + "take owned items, or only return the references: C lends nothing inside a collection, tuple, or iterator" + } + "collection not built from its items" => { + "use a standard collection, or one implementing `FromIterator` of its items" + } + "trait object" => { + "take a generic `impl Trait` or an `Arc` of one of the crate's traits C can implement, or a closure `impl Fn(..)`" + } + "reference field" => "make the field owned, a `String`, `Vec`, or `Arc`, since a field holds no borrow", + "reference to a handle inside a value" => { + "take the object as `&T` itself, not inside an `Option` or a `Box`, which move it out of the caller's handle" + } + "borrowed return that is not Clone" => { + "return an owned value or a `Clone` type, since a borrowed return crosses as a clone" + } + "&mut of a slice" => { + "take `&[u8]` and return the changed `Vec`, or hold the buffer in an object; C lends no buffer mutably" + } + "reader not lent as &mut" => "take the reader as `&mut R`", + "'static borrow" => { + "take an owned value, such as a `String` or an `Arc`, where the handle keeps it; only `&str` and `&[u8]` may be kept" + } + "reference inside a parameter" => { + "take the reference as the whole parameter, or as `Some` of an `Option`, and an owned value inside a `Box` or a struct" + } + "returned object that borrows" => { + "return an owned object that borrows nothing, or a guard of a `&mut self` method borrowing the receiver alone" + } + "lent object that borrows" => { + "name no lifetime on the lent type, or fix it to `'static`, since a handle holds it at `'static`" + } + "returned borrow of a value written back" => { + "return an owned value, or make the type an object by giving it a private field, so `&mut self` writes nothing back" + } + + // Functions. + "unsafe fn" | "C-variadic function" | "uncallable ABI" => { + "make it safe, or export a safe function that checks the preconditions and calls it" + } + "`&mut self` of a value" + | "`&mut self` of a value in a future" + | "`&mut self` of a value beside a JNI value" => { + "take `&self`, or return the changed value instead of mutating it, or make the type an object by giving it a private field" + } + "`&mut self` of a value returning a Result" => { + "return the changed value with the result, or make the type an object by giving it a private field, since a failure would lose the change" + } + "&mut of a value inside an Option" => "take the `&mut` value directly, not inside an `Option`", + "&mut of a value in a callback" | "&mut of a value in a future" => { + "take the value by value and return the changed one, or hold it in an object changed through `&self`" + } + "&mut of a value beside a JNI value" => { + "take the value by value and return the changed one, or drop the JNI value" + } + "receiver" => "take `self`, `&self`, or `&mut self`", + "several task parameters" => "take one `Context` or one waiter, not several", + "Poll with no Context or waiter parameter" => { + "take a `&mut Context`, or a waiter, which a poll registers its wake through" + } + "borrowed Poll" => "return an owned `Poll` that borrows nothing from its arguments", + "Context of a function returning a future" => { + "take a `Context` only in a function returning `Poll`; a function returning a future makes its own" + } + "borrowing output of a future from a function that is not async" => { + "make it an `async fn`, or return an output that borrows nothing" + } + "poll taking self by value" => "take `&mut self`, or make the type `Copy`, so each poll can call it again", + "poll's parameter taken by value that is not Copy" => { + "take it by reference, or make it `Copy`, since each poll calls the function again" + } + "iterator of borrows in a future or callback" => { + "take `Vec` or `impl IntoIterator` of owned items, which the future or callback may keep" + } + "iterator in a callback" => "take a `Vec` or a slice, not an iterator", + "reader lent to a future" => "read the bytes first, and pass them as `Vec`", + "JNI value in a callback" | "JNI value lent to a future" => { + "take JNI's `&mut Env` and `JObject` in a plain function, which Kotlin calls, not in a callback or a future" + } + "several JNI envs" => "take one `&mut jni::Env`", + "JObject with no &mut jni::Env" => "take a `&mut jni::Env` beside the `JObject`", + "JNI type other than a parameter's &mut Env or JObject" => { + "take only `&mut jni::Env` or `JObject` of jni's types, and as a parameter" + } + "callback bound" => "fix the refusal of the trait it names first, or take a concrete type", + "ambiguous conversion" => { + "convert from one of the sources, as `&str` and `String` are one value, not both a `String` and a `Vec`, which C passes alike" + } + "growing conversion" => "break the chain of `From` impls, which names ever more types", + "closure type taken twice" => "take the closure's type once, with a type parameter for each closure", + "closure bound" => { + "bound the closure by `Fn`, `FnMut`, or `FnOnce` alone, besides `Send`, `Sync`, and a lifetime" + } + "closure signature" => { + "take and return values a callback maps: `bool`, integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error" + } + "reader bound" => "bound the reader by `Read` and `Seek` alone", + "reader kept past the call" => "do not return or keep the reader, which C lends only for the call", + + // Traits. + "unsafe trait" => "make the trait safe, or take an exported type instead of the trait", + "trait with a blanket impl" => { + "implement the trait for the types it covers, not for every `T`, so C's implementation cannot clash" + } + "supertrait" => "drop the supertrait, which only a marker such as `Send` or `Sync` may be", + "async trait method" => "return the value directly, since C implements no async method", + "callback signature" => { + "take and return values C passes, such as integers, `String`, and objects by reference, and return no `Result` or `Future`" + } + "trait method without &self" => "take `&self` or `&mut self`, which C calls its implementation through", + "associated type" | "associated const" => { + "move it into the methods' signatures or a function, since C implements methods alone" + } + + // The Swift binding's. + "optional borrowed objects past what Swift overloads" => { + "take at most two optional borrowed objects, or split the function, or group them into a record" + } + "error holding an object Swift cannot copy" => { + "hold values, a `String`, or a `Copy` handle in the error, since `Swift.Error` must be copyable" + } + _ => return None, + }) +} + +#[cfg(test)] +mod tests { + use proc_macro2::{Delimiter, TokenStream, TokenTree}; + + use crate::collect::{BOTH, NOT_INFERRED, UNHELD}; + + /// Each string literal's value, which `tokens` holds at `i`, if it is one. + fn string(tokens: &[TokenTree], i: usize) -> Option { + let TokenTree::Literal(lit) = tokens.get(i)? else { + return None; + }; + let text = lit.to_string(); + Some(text.strip_prefix('"')?.strip_suffix('"')?.to_string()) + } + + /// Every construct `source` names: the first argument of `why(..)`, the value of a + /// `construct:` field, the arms of a `let construct = match`, and what `left_out.insert` + /// takes. + fn constructs(stream: TokenStream, found: &mut Vec) { + let tokens: Vec = stream.into_iter().collect(); + for (i, token) in tokens.iter().enumerate() { + match token { + TokenTree::Ident(ident) if ident == "why" => { + if let Some(TokenTree::Group(group)) = tokens.get(i + 1) + && group.delimiter() == Delimiter::Parenthesis + { + let inner: Vec = group.stream().into_iter().collect(); + found.extend(string(&inner, 0)); + } + } + TokenTree::Ident(ident) if ident == "construct" => { + // `construct: "a" | "b"` in a struct or a pattern. + if matches!(tokens.get(i + 1), Some(TokenTree::Punct(p)) if p.as_char() == ':') { + let mut at = i + 2; + while let Some(value) = string(&tokens, at) { + found.push(value); + match tokens.get(at + 1) { + Some(TokenTree::Punct(p)) if p.as_char() == '|' => at += 2, + _ => break, + } + } + } + // `let construct = match .. { .. => "a", .. }`. + if matches!(tokens.get(i + 1), Some(TokenTree::Punct(p)) if p.as_char() == '=') + && matches!(tokens.get(i + 2), Some(TokenTree::Ident(m)) if m == "match") + && let Some(TokenTree::Group(arms)) = tokens[i + 3..] + .iter() + .find(|t| matches!(t, TokenTree::Group(g) if g.delimiter() == Delimiter::Brace)) + { + let arms: Vec = arms.stream().into_iter().collect(); + for (j, arm) in arms.iter().enumerate() { + if matches!(arm, TokenTree::Punct(p) if p.as_char() == '>') + && matches!(arms.get(j.wrapping_sub(1)), Some(TokenTree::Punct(p)) if p.as_char() == '=') + { + found.extend(string(&arms, j + 1)); + } + } + } + } + TokenTree::Ident(ident) if ident == "left_out" => { + if let Some(TokenTree::Group(group)) = tokens.get(i + 3) + && group.delimiter() == Delimiter::Parenthesis + { + let inner: Vec = group.stream().into_iter().collect(); + found.extend(string(&inner, inner.len().wrapping_sub(1))); + } + } + TokenTree::Group(group) => constructs(group.stream(), found), + _ => {} + } + } + } + + /// Every construct the collector or Swift refuses an item for has a note saying how to + /// change the facade, so a new construct lands with its note. + #[test] + fn every_refusal_has_help() { + let mut found = vec![BOTH.to_string()]; + for source in [include_str!("collect.rs"), include_str!("swift.rs")] { + let stream: TokenStream = source.parse().expect("the source tokenizes"); + constructs(stream, &mut found); + } + // A sanity floor: the scan must still find the constructs it reads. + assert!(found.len() > 100, "the scan found {} constructs", found.len()); + let missing: Vec<&String> = found + .iter() + .filter(|c| !UNHELD.contains(&c.as_str()) && c.as_str() != NOT_INFERRED && super::of(c).is_none()) + .collect(); + assert!(missing.is_empty(), "no `help` for the constructs {missing:?}"); + } +} diff --git a/ffi/src/main.rs b/ffi/src/main.rs index eb4b1c054..c37651937 100644 --- a/ffi/src/main.rs +++ b/ffi/src/main.rs @@ -39,6 +39,7 @@ mod dart; mod driver; mod glue; mod go; +mod help; mod ir; mod js; mod kotlin; diff --git a/ffi/tests/fixtures.rs b/ffi/tests/fixtures.rs index 1c9f270e6..9abcd537d 100644 --- a/ffi/tests/fixtures.rs +++ b/ffi/tests/fixtures.rs @@ -3448,7 +3448,11 @@ fn reject() { let out = scratch().join("reject").join("out"); let output = export("reject", &out, &[], &[]); assert!(!output.status.success(), "exporting reject succeeded"); - let errors = errors(&output); + let errors = refusals(&output); + // Every refusal says how to change the facade. + for error in &errors { + assert!(error.contains("\n\thelp: "), "no help for {error}"); + } let expected = std::fs::read_to_string(manifest_dir().join("fixtures/reject/expected.txt")).unwrap(); if std::env::var_os("UPDATE_EXPECT").is_some() { std::fs::write( @@ -3558,6 +3562,16 @@ fn lacks() { /// Each of rust2-ffi's errors the export printed, sorted: at its span, then each of its /// notes at its own. fn errors(output: &Output) -> Vec { + diagnostics(output, false) +} + +/// [`errors`], each with its `help:` notes after its span notes, which a refusal carries +/// for how to change the facade. A baseline break's names a path, so [`errors`] leaves it out. +fn refusals(output: &Output) -> Vec { + diagnostics(output, true) +} + +fn diagnostics(output: &Output, helps: bool) -> Vec { let stderr = String::from_utf8_lossy(&output.stderr); let lines: Vec<&str> = stderr.lines().collect(); let at = |i: usize| { @@ -3580,6 +3594,12 @@ fn errors(output: &Output) -> Vec { { let error = errors.last_mut().expect("a note follows its error"); *error += &format!("\n\t{}: note: {note}", at(i)); + } else if helps + && ours + && let Some(help) = line.trim_start().strip_prefix("= help: ") + { + let error = errors.last_mut().expect("a help follows its error"); + *error += &format!("\n\thelp: {help}"); } } errors.sort(); diff --git a/quest/m1/ffi-guide.md b/quest/m1/ffi-guide.md deleted file mode 100644 index 911392e37..000000000 --- a/quest/m1/ffi-guide.md +++ /dev/null @@ -1,18 +0,0 @@ -# [S] Onboard a crate that is not moq - -## Goal - -Each refusal kind carries a `help:` note saying how to change the facade, such as -`HashMap` to `BTreeMap` or a borrowed return to an owned one, and `ffi/README.md` links a -short guide to writing a facade for the exporter: what exports, what refuses, and how to -read the census. - -## Plan - -Found by the 2026-11-18 language audit: refusals are rustc diagnostics at their spans but -say only what is refused; the README's scope note says a stock crate needs a facade, and -nothing shows how to write one. The nightly corpus's refusals (`just ffi corpus`, whose -report lists each crate's) are the examples to write the notes against. The "exclude it in the config" suffix goes -with [the config](/quest/m1/ffi-refusals/no-config.md), not here. - -Public API: refusal messages. diff --git a/quest/m1/ffi-refusals/no-config.md b/quest/m1/ffi-refusals/no-config.md index 72f5bb8b7..3ee72cbd6 100644 --- a/quest/m1/ffi-refusals/no-config.md +++ b/quest/m1/ffi-refusals/no-config.md @@ -8,8 +8,8 @@ no config: an item it cannot export fails the export with a span. Deleted: `ffi/moq/ffi.toml`, the `--config` flag, `RUST2_FFI_CONFIG`, and `config.rs`'s `Config` and `exclude`, with the fixtures' `ffi/fixtures/api/ffi.toml` and `ffi/fixtures/reject/ffi.toml` and the exclude tests in `ffi/tests/fixtures.rs`; -`ffi/README.md` and the recipes stop naming them. `config.rs`'s `Package` and environment -constants stay. Also deleted: the `--config` parsing rust2-ffi takes from +`ffi/README.md`, [`ffi/FACADE.md`](/ffi/FACADE.md) (its loop and census steps), and the +recipes stop naming them. `config.rs`'s `Package` and environment constants stay. Also deleted: the `--config` parsing rust2-ffi takes from `driver/src/cargo.rs`, which already has `parse_configless`; `go/bench/ffi.toml` and the `--config` in `go/justfile`'s bench recipe, whose `package` and `prefix` keys `config.rs` already rejects; and "exclude it in the config" in `ffi/src/driver.rs`'s refusal notes and From 23bdd60a104db084e708c89b14f50849adcecadf Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 22:24:37 -0800 Subject: [PATCH 3/6] ffi: refresh the reject fixture's expected help notes Co-Authored-By: Claude Sonnet 5.5 --- ffi/fixtures/reject/expected.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/ffi/fixtures/reject/expected.txt b/ffi/fixtures/reject/expected.txt index fdf4f1057..4de4effa4 100644 --- a/ffi/fixtures/reject/expected.txt +++ b/ffi/fixtures/reject/expected.txt @@ -51,9 +51,9 @@ fixtures/reject/src/lib.rs:1161:1: rust2-ffi: cannot export fn `wrap`: returned fixtures/reject/src/lib.rs:1166:1: rust2-ffi: cannot export fn `hidden_wrap`: returned object that borrows `impl std::clone::Clone + '_`; exclude it in the config to leave it out help: return an owned object that borrows nothing, or a guard of a `&mut self` method borrowing the receiver alone fixtures/reject/src/lib.rs:1182:1: rust2-ffi: cannot export fn `picked`: closure signature `&'static Mark`; exclude it in the config to leave it out - help: take and return values a callback maps: integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error + help: take and return values a callback maps: `bool`, integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error fixtures/reject/src/lib.rs:1187:1: rust2-ffi: cannot export fn `maybe_picked`: closure signature `std::option::Option<&'static Mark>`; exclude it in the config to leave it out - help: take and return values a callback maps: integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error + help: take and return values a callback maps: `bool`, integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error fixtures/reject/src/lib.rs:1192:1: rust2-ffi: cannot export fn `hidden_answer`: opaque type `impl std::marker::Copy`; exclude it in the config to leave it out help: return a named type, or an `impl Trait` hiding an exported object that captures no borrow, as `+ use<>` ensures fixtures/reject/src/lib.rs:1197:1: rust2-ffi: cannot export fn `hidden_items`: opaque type `impl std::marker::Copy`; exclude it in the config to leave it out @@ -126,9 +126,9 @@ fixtures/reject/src/lib.rs:1441:2: rust2-ffi: cannot export method `Slot::pe fixtures/reject/src/lib.rs:145:2: rust2-ffi: cannot export method `Link::session`: borrowed return that is not Clone `tls::held::Handoff`; exclude it in the config to leave it out help: return an owned value or a `Clone` type, since a borrowed return crosses as a clone fixtures/reject/src/lib.rs:1477:1: rust2-ffi: cannot export fn `unit_error`: unit error `std::result::Result<(), ()>`; exclude it in the config to leave it out - help: return an `Option` or a `bool`, or give the error a value, such as a `String` or an error type of yours + help: return a `bool` for `Result<(), ()>` or an `Option` for `Result`, or give the error a value, such as a `String` or an error type of yours fixtures/reject/src/lib.rs:1482:1: rust2-ffi: cannot export fn `unit_error_later`: unit error `std::result::Result`; exclude it in the config to leave it out - help: return an `Option` or a `bool`, or give the error a value, such as a `String` or an error type of yours + help: return a `bool` for `Result<(), ()>` or an `Option` for `Result`, or give the error a value, such as a `String` or an error type of yours fixtures/reject/src/lib.rs:1513:1: rust2-ffi: cannot export fn `race`: instance holding a foreign future `reject::Either<((), std::pin::Pin + std::marker::Send>>), ((), std::pin::Pin + std::marker::Send>>)>`; exclude it in the config to leave it out help: name a future of `()` C implements, or make the instance own no future fixtures/reject/src/lib.rs:1521:1: rust2-ffi: cannot export fn `park`: instance holding a foreign future `reject::Parked + std::marker::Send>>>`; exclude it in the config to leave it out @@ -161,11 +161,11 @@ fixtures/reject/src/lib.rs:209:1: rust2-ffi: cannot export fn `relay`: borrowing fixtures/reject/src/lib.rs:214:1: rust2-ffi: cannot export fn `resolve`: borrowing output of a future from a function that is not async `&str`; exclude it in the config to leave it out help: make it an `async fn`, or return an output that borrows nothing fixtures/reject/src/lib.rs:219:1: rust2-ffi: cannot export fn `spend`: closure signature `tls::held::Token`; exclude it in the config to leave it out - help: take and return values a callback maps: integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error + help: take and return values a callback maps: `bool`, integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error fixtures/reject/src/lib.rs:21:1: rust2-ffi: cannot export fn `nested`: nested Option `std::option::Option>>`; exclude it in the config to leave it out help: use one `Option`, or wrap the inner one in an enum, since C has one `None` per option fixtures/reject/src/lib.rs:224:1: rust2-ffi: cannot export fn `mint`: closure signature `tls::held::Token`; exclude it in the config to leave it out - help: take and return values a callback maps: integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error + help: take and return values a callback maps: `bool`, integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error fixtures/reject/src/lib.rs:234:1: rust2-ffi: cannot export fn `spent`: reference to a handle inside a value `[tls::held::Token]`; exclude it in the config to leave it out help: take the object as `&T` itself, not inside an `Option` or a `Box`, which move it out of the caller's handle fixtures/reject/src/lib.rs:244:1: rust2-ffi: cannot export fn `adopt`: generic parameter `std::convert::Into`; exclude it in the config to leave it out @@ -203,9 +203,9 @@ fixtures/reject/src/lib.rs:354:2: rust2-ffi: cannot export field `Tag::label`: ' fixtures/reject/src/lib.rs:35:1: rust2-ffi: cannot export static `COUNT`: static; exclude it in the config to leave it out help: export a function returning the value, or a `const` fixtures/reject/src/lib.rs:364:1: rust2-ffi: cannot export fn `gather`: closure signature `std::vec::Vec`; exclude it in the config to leave it out - help: take and return values a callback maps: integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error + help: take and return values a callback maps: `bool`, integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error fixtures/reject/src/lib.rs:369:1: rust2-ffi: cannot export fn `attempt`: closure signature `std::result::Result`; exclude it in the config to leave it out - help: take and return values a callback maps: integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error + help: take and return values a callback maps: `bool`, integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error fixtures/reject/src/lib.rs:374:1: rust2-ffi: cannot export fn `consume`: reader not lent as &mut `impl std::io::Read + std::io::Seek`; exclude it in the config to leave it out help: take the reader as `&mut R` fixtures/reject/src/lib.rs:379:1: rust2-ffi: cannot export fn `retain`: reader kept past the call `R`; exclude it in the config to leave it out From 2c5db3be484ed4b2185c18bfd92cc326da621152 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 22:52:45 -0800 Subject: [PATCH 4/6] ffi: answer CodeRabbit's four notes on the facade guide and help table The guide names the one refusal with no note and tells a wrapper's author to narrow the glob; the collection note says why a set of floats fails, and the closure note keeps references to parameters. Co-Authored-By: Claude Sonnet 5.5 --- ffi/FACADE.md | 10 ++++++++-- ffi/fixtures/reject/expected.txt | 14 +++++++------- ffi/src/help.rs | 4 ++-- 3 files changed, 17 insertions(+), 11 deletions(-) diff --git a/ffi/FACADE.md b/ffi/FACADE.md index 65ac5f0a6..eedc7e28f 100644 --- a/ffi/FACADE.md +++ b/ffi/FACADE.md @@ -33,8 +33,9 @@ This guide goes from a crate you want in another language to a facade with no re 3. Read `census/.md`, as below, and fix the top construct. 4. Repeat until the census refuses nothing, then export with `--out dir`. -Each refusal is also a compile error at its span when you export, with a `help:` note naming -the change to make. The census only gathers them. +Each refusal is also a compile error at its span when you export. Most carry a `help:` note +naming the change to make. The census only gathers them. An `instance not inferred` error is +a bug in `rust2-ffi`, so it has no note and no facade change fixes it. ## What exports @@ -112,6 +113,11 @@ impl Link { } ``` +A wrapper replaces the type it wraps: replace the `pub use url::*;` glob with explicit +re-exports of the items that map, such as `pub use url::ParseError;`, and drop `Url` from +them. A kept `pub use url::Url;` exports the original type beside `Link`, and the census +goes on reporting its refused methods. + This exports with no refusals: `Link` is an object, `parse` fails with `ParseError`'s message, and every other method is a call a language can make. diff --git a/ffi/fixtures/reject/expected.txt b/ffi/fixtures/reject/expected.txt index 4de4effa4..6ca115597 100644 --- a/ffi/fixtures/reject/expected.txt +++ b/ffi/fixtures/reject/expected.txt @@ -51,9 +51,9 @@ fixtures/reject/src/lib.rs:1161:1: rust2-ffi: cannot export fn `wrap`: returned fixtures/reject/src/lib.rs:1166:1: rust2-ffi: cannot export fn `hidden_wrap`: returned object that borrows `impl std::clone::Clone + '_`; exclude it in the config to leave it out help: return an owned object that borrows nothing, or a guard of a `&mut self` method borrowing the receiver alone fixtures/reject/src/lib.rs:1182:1: rust2-ffi: cannot export fn `picked`: closure signature `&'static Mark`; exclude it in the config to leave it out - help: take and return values a callback maps: `bool`, integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error + help: take a `bool`, integer, `String`, opaque value, or object by reference (parameters only), and return an owned `bool`, integer, `String`, opaque value, or an `Option` of one, or a `Result` of one with a `String` error: a callback returns no reference fixtures/reject/src/lib.rs:1187:1: rust2-ffi: cannot export fn `maybe_picked`: closure signature `std::option::Option<&'static Mark>`; exclude it in the config to leave it out - help: take and return values a callback maps: `bool`, integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error + help: take a `bool`, integer, `String`, opaque value, or object by reference (parameters only), and return an owned `bool`, integer, `String`, opaque value, or an `Option` of one, or a `Result` of one with a `String` error: a callback returns no reference fixtures/reject/src/lib.rs:1192:1: rust2-ffi: cannot export fn `hidden_answer`: opaque type `impl std::marker::Copy`; exclude it in the config to leave it out help: return a named type, or an `impl Trait` hiding an exported object that captures no borrow, as `+ use<>` ensures fixtures/reject/src/lib.rs:1197:1: rust2-ffi: cannot export fn `hidden_items`: opaque type `impl std::marker::Copy`; exclude it in the config to leave it out @@ -161,11 +161,11 @@ fixtures/reject/src/lib.rs:209:1: rust2-ffi: cannot export fn `relay`: borrowing fixtures/reject/src/lib.rs:214:1: rust2-ffi: cannot export fn `resolve`: borrowing output of a future from a function that is not async `&str`; exclude it in the config to leave it out help: make it an `async fn`, or return an output that borrows nothing fixtures/reject/src/lib.rs:219:1: rust2-ffi: cannot export fn `spend`: closure signature `tls::held::Token`; exclude it in the config to leave it out - help: take and return values a callback maps: `bool`, integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error + help: take a `bool`, integer, `String`, opaque value, or object by reference (parameters only), and return an owned `bool`, integer, `String`, opaque value, or an `Option` of one, or a `Result` of one with a `String` error: a callback returns no reference fixtures/reject/src/lib.rs:21:1: rust2-ffi: cannot export fn `nested`: nested Option `std::option::Option>>`; exclude it in the config to leave it out help: use one `Option`, or wrap the inner one in an enum, since C has one `None` per option fixtures/reject/src/lib.rs:224:1: rust2-ffi: cannot export fn `mint`: closure signature `tls::held::Token`; exclude it in the config to leave it out - help: take and return values a callback maps: `bool`, integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error + help: take a `bool`, integer, `String`, opaque value, or object by reference (parameters only), and return an owned `bool`, integer, `String`, opaque value, or an `Option` of one, or a `Result` of one with a `String` error: a callback returns no reference fixtures/reject/src/lib.rs:234:1: rust2-ffi: cannot export fn `spent`: reference to a handle inside a value `[tls::held::Token]`; exclude it in the config to leave it out help: take the object as `&T` itself, not inside an `Option` or a `Box`, which move it out of the caller's handle fixtures/reject/src/lib.rs:244:1: rust2-ffi: cannot export fn `adopt`: generic parameter `std::convert::Into`; exclude it in the config to leave it out @@ -203,9 +203,9 @@ fixtures/reject/src/lib.rs:354:2: rust2-ffi: cannot export field `Tag::label`: ' fixtures/reject/src/lib.rs:35:1: rust2-ffi: cannot export static `COUNT`: static; exclude it in the config to leave it out help: export a function returning the value, or a `const` fixtures/reject/src/lib.rs:364:1: rust2-ffi: cannot export fn `gather`: closure signature `std::vec::Vec`; exclude it in the config to leave it out - help: take and return values a callback maps: `bool`, integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error + help: take a `bool`, integer, `String`, opaque value, or object by reference (parameters only), and return an owned `bool`, integer, `String`, opaque value, or an `Option` of one, or a `Result` of one with a `String` error: a callback returns no reference fixtures/reject/src/lib.rs:369:1: rust2-ffi: cannot export fn `attempt`: closure signature `std::result::Result`; exclude it in the config to leave it out - help: take and return values a callback maps: `bool`, integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error + help: take a `bool`, integer, `String`, opaque value, or object by reference (parameters only), and return an owned `bool`, integer, `String`, opaque value, or an `Option` of one, or a `Result` of one with a `String` error: a callback returns no reference fixtures/reject/src/lib.rs:374:1: rust2-ffi: cannot export fn `consume`: reader not lent as &mut `impl std::io::Read + std::io::Seek`; exclude it in the config to leave it out help: take the reader as `&mut R` fixtures/reject/src/lib.rs:379:1: rust2-ffi: cannot export fn `retain`: reader kept past the call `R`; exclude it in the config to leave it out @@ -311,7 +311,7 @@ fixtures/reject/src/lib.rs:778:1: rust2-ffi: cannot export fn `values`: foreign fixtures/reject/src/lib.rs:77:1: rust2-ffi: cannot export fn `first`: borrowed return that is not Clone `Opaque`; exclude it in the config to leave it out help: return an owned value or a `Clone` type, since a borrowed return crosses as a clone fixtures/reject/src/lib.rs:784:1: rust2-ffi: cannot export fn `floats`: collection not built from its items `std::collections::BTreeSet`; exclude it in the config to leave it out - help: use a standard collection, or one implementing `FromIterator` of its items + help: the collection must build from its items, which a `BTreeSet` or `BTreeMap` of a type without `Ord`, such as `f64`, cannot: key it by an ordered type, or take a `Vec` and build the collection inside the facade fixtures/reject/src/lib.rs:789:1: rust2-ffi: cannot export fn `zeros`: foreign type `std::iter::RepeatN`; exclude it in the config to leave it out help: use a type that maps, such as `BTreeMap` for a `HashMap` and `Vec` for an iterator, or wrap it in a type of your own whose methods take and return mapped types fixtures/reject/src/lib.rs:794:1: rust2-ffi: cannot export fn `successes`: foreign type `std::iter::Flatten`; exclude it in the config to leave it out diff --git a/ffi/src/help.rs b/ffi/src/help.rs index 082700144..a0a8f844e 100644 --- a/ffi/src/help.rs +++ b/ffi/src/help.rs @@ -110,7 +110,7 @@ pub(crate) fn of(construct: &str) -> Option<&'static str> { "take owned items, or only return the references: C lends nothing inside a collection, tuple, or iterator" } "collection not built from its items" => { - "use a standard collection, or one implementing `FromIterator` of its items" + "the collection must build from its items, which a `BTreeSet` or `BTreeMap` of a type without `Ord`, such as `f64`, cannot: key it by an ordered type, or take a `Vec` and build the collection inside the facade" } "trait object" => { "take a generic `impl Trait` or an `Arc` of one of the crate's traits C can implement, or a closure `impl Fn(..)`" @@ -200,7 +200,7 @@ pub(crate) fn of(construct: &str) -> Option<&'static str> { "bound the closure by `Fn`, `FnMut`, or `FnOnce` alone, besides `Send`, `Sync`, and a lifetime" } "closure signature" => { - "take and return values a callback maps: `bool`, integers, `String`, objects by reference, opaque values, an `Option`, or a `Result` with a `String` error" + "take a `bool`, integer, `String`, opaque value, or object by reference (parameters only), and return an owned `bool`, integer, `String`, opaque value, or an `Option` of one, or a `Result` of one with a `String` error: a callback returns no reference" } "reader bound" => "bound the reader by `Read` and `Seek` alone", "reader kept past the call" => "do not return or keep the reader, which C lends only for the call", From 071b3117704646278c42ccd59b10391098f83e3b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 22:59:03 -0800 Subject: [PATCH 5/6] ffi: keep the facade guide's wrapper example consistent about ParseError Co-Authored-By: Claude Sonnet 5.5 --- ffi/FACADE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ffi/FACADE.md b/ffi/FACADE.md index eedc7e28f..c50609654 100644 --- a/ffi/FACADE.md +++ b/ffi/FACADE.md @@ -114,8 +114,8 @@ impl Link { ``` A wrapper replaces the type it wraps: replace the `pub use url::*;` glob with explicit -re-exports of the items that map, such as `pub use url::ParseError;`, and drop `Url` from -them. A kept `pub use url::Url;` exports the original type beside `Link`, and the census +re-exports of the items that map, and drop `Url` from them. This example re-exports none, so +`ParseError` stays a message; re-export it to hand callers the enum instead. A kept `pub use url::Url;` exports the original type beside `Link`, and the census goes on reporting its refused methods. This exports with no refusals: `Link` is an object, `parse` fails with `ParseError`'s message, From ac9e6e85d146ca52ea72dd9a7c827cdc07206773 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 22:59:07 -0800 Subject: [PATCH 6/6] ffi: wrap the guide's wrapper paragraph Co-Authored-By: Claude Sonnet 5.5 --- ffi/FACADE.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/ffi/FACADE.md b/ffi/FACADE.md index c50609654..b1adbfa05 100644 --- a/ffi/FACADE.md +++ b/ffi/FACADE.md @@ -115,8 +115,9 @@ impl Link { A wrapper replaces the type it wraps: replace the `pub use url::*;` glob with explicit re-exports of the items that map, and drop `Url` from them. This example re-exports none, so -`ParseError` stays a message; re-export it to hand callers the enum instead. A kept `pub use url::Url;` exports the original type beside `Link`, and the census -goes on reporting its refused methods. +`ParseError` stays a message; re-export it to hand callers the enum instead. A kept +`pub use url::Url;` exports the original type beside `Link`, and the census goes on +reporting its refused methods. This exports with no refusals: `Link` is an object, `parse` fails with `ParseError`'s message, and every other method is a call a language can make.