Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions .github/workflows/bindings.yml
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ jobs:
- name: Stand-in
if: steps.mode.outputs.fixture == 'true'
working-directory: source
run: just ffi standin && cp ffi/moq/ffi.toml ffi/target/moq-ffi/ffi.toml
run: just ffi standin
- id: facts
working-directory: source
run: python3 -I ../rust2/ffi/release/package.py facts --manifest-path "$MANIFEST" >> "$GITHUB_OUTPUT"
Expand Down Expand Up @@ -210,7 +210,7 @@ jobs:
- name: Stand-in
if: needs.facts.outputs.fixture == 'true'
working-directory: source
run: just ffi standin && cp ffi/moq/ffi.toml ffi/target/moq-ffi/ffi.toml
run: just ffi standin
- name: Exporter
working-directory: rust2/ffi
env:
Expand Down Expand Up @@ -283,7 +283,7 @@ jobs:
- name: Stand-in
if: needs.facts.outputs.fixture == 'true'
working-directory: source
run: just ffi standin && cp ffi/moq/ffi.toml ffi/target/moq-ffi/ffi.toml
run: just ffi standin
# The tools that build and repair, apart from the CPython the consumers test on.
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
Expand Down Expand Up @@ -448,7 +448,7 @@ jobs:
- name: Stand-in
if: needs.facts.outputs.fixture == 'true'
working-directory: source
run: just ffi standin && cp ffi/moq/ffi.toml ffi/target/moq-ffi/ffi.toml
run: just ffi standin
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
pattern: ${{ needs.facts.outputs.name }}-build-apple-*
Expand Down Expand Up @@ -632,7 +632,7 @@ jobs:
- name: Stand-in
if: needs.facts.outputs.web-fixture == 'true'
working-directory: source
run: just ffi standin "" web && cp ffi/moq/web.toml ffi/target/moq-ffi-web/ffi.toml
run: just ffi standin "" web
# npm packs, and Node's WASI runs the native example.
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
Expand Down Expand Up @@ -730,7 +730,7 @@ jobs:
- name: Stand-in
if: needs.facts.outputs.fixture == 'true'
working-directory: source
run: just ffi standin && cp ffi/moq/ffi.toml ffi/target/moq-ffi/ffi.toml
run: just ffi standin
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
pattern: ${{ needs.facts.outputs.name }}-build-*
Expand Down
2 changes: 1 addition & 1 deletion bench/ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -706,7 +706,7 @@ and Kotlin's calls trail it by 1.2 to 4 times, behind JNI's per-call cost and th

The web binding runs over its own export of the stand-in, `target/moq-ffi-web`: the same
crates less moq-tokio, which pulls in rustls-native-certs, with no wasm32-wasip1 platform
module, and so less the items that name it ([`moq/web.toml`](../../ffi/moq/web.toml)).
module.
Nothing builds for wasm32-unknown-unknown, where getrandom 0.4 has no backend without a
config flag. `export.ts` imports the generated modules as a caller would, and disposes each
handle and payload it gets. A browser gives no process CPU clock, so its columns are wall
Expand Down
3 changes: 3 additions & 0 deletions driver/src/cargo.rs
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,9 @@ fn parse(args: &[String], usage: &str, configured: bool) -> Result<Option<Args<O
"--census" => &mut census,
_ => &mut manifest,
};
if slot.is_some() {
return Err(format!("{arg} is given twice\n\n{usage}"));
}
*slot = Some(absolute(Path::new(value))?);
}
"--" => {
Expand Down
5 changes: 1 addition & 4 deletions ffi/FACADE.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,7 @@ This guide goes from a crate you want in another language to a facade with no re
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
rust2-ffi --census census --manifest-path Cargo.toml
```

3. Read `census/<package>.md`, as below, and fix the top construct.
Expand Down Expand Up @@ -135,8 +134,6 @@ and every other method is a call a language can make.
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
Expand Down
54 changes: 24 additions & 30 deletions ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ be refused, and the census also lists API items left out by those rules.
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]
rust2-ffi (--out dir | --census dir | --api file) [--manifest-path Cargo.toml] [--target triple]... [--with file]... [--baseline api.json] [-- cargo args]
```

It runs `cargo check` on the package with itself as `RUSTC_WRAPPER`, for each `--target`
Expand Down Expand Up @@ -58,18 +58,9 @@ An export again rewrites only the files whose content changed, and removes from
export stays fresh. The crate's version, `0.0.0+<hash>`, hashes its Rust sources and
manifest, so exports that differ build apart in a target directory they share.

```toml
# ffi.toml, beside the package's Cargo.toml unless --manifest-path says otherwise.
# Paths from the facade's root left out: a module, an item, or one method or field. A type
# no facade module re-exports goes by its crate's name and its public path there. Each
# must name something exported, or what a `cfg` leaves out of this build, as moq-tokio's
# `unix` is on Windows. Nothing else leaves an item out. As in rustdoc, a path a
# method or constant shares with a field names the method, and `field@` the field.
# A `cfg`-stripped item is found through a glob re-export only while its source module
# keeps an exported item; under a glob of a module a `cfg` empties, the exclude fails as
# naming nothing exported.
exclude = ["track::Producer::poll_closed"]
```
It reads no config: the package is in the current directory unless `--manifest-path` says
where, and an item the rules cannot export fails the export at its span. Nothing leaves an
item out but the source itself: `#[doc(hidden)]`, or a `cfg` that leaves it out of a build.

## Rules

Expand Down Expand Up @@ -107,7 +98,7 @@ public path names, or an error taken by value, is held by value as an opaque han
| a type parameter or `impl` taken by value and bounded by `Future` or `IntoFuture`, whose every bound `Pin<Box<dyn Future<Output = ()> + Send>>` meets, as kio's `clock::timeout` takes, or taken as `Pin<&mut F>` by a poll, as kio's `Waiter::poll_future` takes | `<prefix>_foreign_future`: a future of `()` C implements, which Rust takes as that type, or which the future the poll makes owns and pins; a future of another output is refused |
| a type parameter or `impl` bounded by `Read` and `Seek` alone, behind `&mut`, which no lifetime bound or return lets outlive the call, as moq-mux's `container::mp4::repair` takes | `<prefix>_foreign_reader`: a `read` and a `seek` C implements and their data, lent for the call; any other reader is refused |
| `fn` and inherent `pub` methods | functions named through their type |
| an object's `Deref` to an exported type, followed as far as the chain reaches | the target's `pub` methods and fields, a record's too, on the object, as auto-deref finds them: a method the object or a nearer target has, exported or not, hides a method, and a field a field; a `&mut self` method or a setter only while every `Deref` on the way is a `DerefMut`; and the config names each by the object's path |
| an object's `Deref` to an exported type, followed as far as the chain reaches | the target's `pub` methods and fields, a record's too, on the object, as auto-deref finds them: a method the object or a nearer target has, exported or not, hides a method, and a field a field; a `&mut self` method or a setter only while every `Deref` on the way is a `DerefMut`; and the census names each by the object's path |
| a `()` parameter of a function, not of a callback's method | nothing: C passes no argument for it |
| `Result<T, E>` | `bool f(..., T *out, E *err)`; an `E` of another crate that implements `Display`, such as `anyhow::Error` or `io::Error`, is `String`, its message; a `()` error, as once_cell's `race::OnceBool::set` returns, is refused, having no value to raise |
| a returned tuple `(A, B)` | one out pointer each: `void f(..., A *out0, B *out1)` |
Expand Down Expand Up @@ -151,7 +142,7 @@ public path names, or an error taken by value, is held by value as an opaque han
| `impl IntoIterator<Item = X>`, where `X` is no type parameter | `Vec<X>`, or `&[Y]` where `X` is `&Y` |
| `impl io::Read`, not bounded by `Seek` | `&[u8]` |
| `impl Iterator<Item = X>` taken | `Vec<X>`, whose items Rust iterates; for `X` of `&str` or `&[u8]`, an array of buffers C lends for the call; an iterator of other references, or one a future or a callback takes, is refused |
| another type parameter | `serde_json::Value` for a serde `Serialize` or `Deserialize` bound, else the first of `String`, `Bytes`, and `Vec<u8>` meeting its bounds, or a foreign implementation of its one exported trait; else an instance of the function at each type the exports implement a trait bounding it for, through a blanket impl at each type implementing what the impl requires, as `&X` where that meets its bounds too and no bound, its own or one a supertrait implies, makes it outlive the call, so C keeps its handle, and, as an argument of a generic type, at each argument of an instance that meets its bounds and makes each generic type the signature names an instance |
| another type parameter | `serde_json::Value` for a serde `Serialize`, `Deserialize`, or `Deserializer` bound, as a derived `deserialize` takes, else the first of `String`, `Bytes`, and `Vec<u8>` meeting its bounds, or a foreign implementation of its one exported trait; else an instance of the function at each type the exports implement a trait bounding it for, through a blanket impl at each type implementing what the impl requires, as `&X` where that meets its bounds too and no bound, its own or one a supertrait implies, makes it outlive the call, so C keeps its handle, and, as an argument of a generic type, at each argument of an instance that meets its bounds and makes each generic type the signature names an instance |
| a const parameter of a function | an instance of the function at each value an instance of a generic type the signature passes it to has there, where each generic type the signature then names is an instance |
| a const argument | a `bool` or an integer below 128 bits; any other is refused |

Expand All @@ -166,11 +157,21 @@ maps, which may name more. Inference finishes before any type is mapped, so mapp
never adds an instance. An instance that holds an instance of a type inside it, such as
`Cell<Cell<u8>>`, is refused, as it could name ever deeper ones.

A field holding a reference, as `&'a mut ClientConfig` in rustls's
`DangerousClientConfig` is, is read through it, lent where it is not `Clone`, and has no
setter, since no borrow C holds outlives a call. A returned `Cow<'_, str>` or
`Cow<'_, [u8]>` crosses as the string or bytes it owns, a copy C would make of a borrow
anyway; a `Cow` anywhere else is refused, as C would hand Rust its form. A future owns
its output before it ends, so it may return a `Cow` only on its own, in an `Option`, or
as a tuple's element, and an error's only as `Cow<str>`, whose message crosses. Another crate's
type that only refused items name, as `std::net::TcpListener` in moq-tokio's
`server::Streams` is, is one no export returns, so those items are left out with it.

A record or enum holds only values and `Copy` handles: one with a field that does not map,
or that holds itself, is an object instead, and the census lists it. A borrowed return is
returned as a clone, so it must be `Clone`, and a handle in it is a new handle to the
clone, but for an object a `&self` method of an object returns borrowed from its receiver
alone, or an object's `pub` field holds, bare or as an `Option`'s `Some`: that one, if not `Clone`, is a lent handle, which holds its receiver and checks it
alone, or an object's `pub` field holds, bare or as an `Option`'s `Some`, through a `Box` too: that one, if not `Clone`, is a lent handle, which holds its receiver and checks it
on each use, on one thread at a time where the receiver is not `Sync`. A handle outlives every call, so every lifetime an
object takes is `'static`, as is every lifetime that must outlive one; any other lifetime
is the call's. A signature may not lend C's borrow for one that is `'static`, but for a
Expand Down Expand Up @@ -231,7 +232,7 @@ A target's check may need its own C toolchain, as moq's `aws-lc-sys` and `ring`
for a check, which only its own host may have. `--api file` writes one target's API, with
the spans of its items, instead of exporting; an export elsewhere adds it with
`--with file`, as though it had checked that target too. Both must check the same
package, features, and `exclude`, from the same sources: a staged span's file is relative
package and features, from the same sources: a staged span's file is relative
to the workspace's root or cargo's home, so a checkout at another path keeps it, and is
dropped for the other target's span where the file differs.

Expand Down Expand Up @@ -260,7 +261,7 @@ API breaks the one in `file`, with an error at each item that names how:
A tuple's struct, known by its Rust spelling, is renamed the same way when another
tuple's elements run together into its name.

An item is known by its kind and Rust path, as `exclude` names it. An addition passes: a new
An item is known by its kind and Rust path. An addition passes: a new
item, method, trait impl, or a variant of a `#[non_exhaustive]` enum. A constant's value and
an item's docs may change. The check runs once, on the API every language is generated from;
it compares C's names and the C++, Kotlin, Python, Swift, Go, and Dart generators' own
Expand Down Expand Up @@ -473,10 +474,7 @@ Linux's exports, as the merge queue runs on, since a header names its targets.
every instance the item exports at, so one an upstream change adds can lengthen another's
name. A type instance's methods are named through it, and a function instance appends
its arguments' names, a reference's by what it borrows and a const's by its value: the
api fixture's `drain` is `api_drain_4` at `Batch` and `api_drain_2` at `Batch<2>`. An
`exclude` of a type or method by the generic type's path leaves it out of every
instance, and by the instance's path
(`"mux::catalog::Producer<moq::mux::catalog::hang::Extra>::stats"`) out of that one.
api fixture's `drain` is `api_drain_4` at `Batch` and `api_drain_2` at `Batch<2>`.

## C++

Expand Down Expand Up @@ -1384,13 +1382,9 @@ runtime package and each crate's include [`runtime/rt.go`](runtime/rt.go) and

`--census dir` exports nothing. It writes `<package>.md` for the facade, which counts what exports and ranks every refusal by construct and by the type it names,
lists each refused item at its span, a binding's own refusals such as Swift's included,
then the `exclude` list that exports the rest, and
what else it left out, such as what C can never hold and the traits C cannot implement, and why.
That list is checked by collecting again with it: it holds what Swift alone refuses, and
not an instance only refused items named, which nothing names once they are left out.
It ignores the config's `exclude`, but lists each exclude that leaves out an item that
would export, and fails on it, so the list holds only what the export refuses. It also
fails on an `instance not inferred` refusal, which is a bug in the exporter's inference
each of which fails the export, and what else it left out, such as what C can never hold
and the traits C cannot implement, and why. It fails on an `instance not inferred` refusal,
which is a bug in the exporter's inference
rather than in the crate.

## TypeScript (web)
Expand Down Expand Up @@ -1621,7 +1615,7 @@ entry, and the nightly fails on an entry that matches no call of the fixed set.
The corpus (`tests/fixtures/corpus.rs`) exports stock crates as a consumer would: each
crate of `corpus/crates.txt`, the top crates on crates.io by downloads that are libraries
building as they are, pinned by `corpus/Cargo.lock`, through a facade of its own, `pub use
<crate>::*;`. Each is censused, then exported with the `exclude` its census writes, and
<crate>::*;`. Each is censused, then, where the census refuses nothing, exported, and
its glue, C and C++ programs including its headers (compiled, not linked, since a crate
may call a platform library the host lacks), its Kotlin, Python, Swift, Go, and Dart
built; a panic, an error, or a binding that does not build fails it, a refusal not.
Expand Down
24 changes: 23 additions & 1 deletion ffi/fixtures/api/examples/transcript.rs
Original file line number Diff line number Diff line change
Expand Up @@ -442,6 +442,10 @@ fn main() {
let mut list = Node::new(1, None);
list.push(2);
println!("node {}", list.sum());
match list.next.as_deref() {
Some(next) => println!("node next {}", next.value),
None => println!("node next none"),
}

let tally = Tally::new();
tally.bump();
Expand Down Expand Up @@ -716,6 +720,10 @@ fn main() {
drop(draft);
println!("dropped {}", ledger.published());
println!("receipt {}", ledger.receipt().count());
let tab = ledger.tab();
println!("tab {}", tab.ledger.published());
println!("tab label {}", tab.label);
drop(tab);
// Members a `Deref` reaches: past an unexported target, beside a method of the same
// name, and a field a method's path shares.
let mut marker = api::Marker::new("m", 3, 5);
Expand Down Expand Up @@ -836,7 +844,21 @@ fn main() {
);
let doc: serde_json::Value = r#"{"b": [1, 2.5, null], "a": "\u00e9"}"#.parse().unwrap();
println!("json {}", api::encode(&doc));
println!("timed text {}", api::timed_text(&doc));
println!(
"cow {} {} {} {}",
api::unescaped(r"a\b"),
api::unescaped("plain"),
api::unzeroed(&[1, 0, 2]).len(),
api::unzeroed(&[3]).len()
);
let pair: serde_json::Value = "[1, 2]".parse().unwrap();
let spot = api::Spot::deserialize(pair).unwrap();
println!("spot {} {}", spot.x, spot.y);
let text: serde_json::Value = "\"x\"".parse().unwrap();
match api::Spot::deserialize(text) {
Ok(spot) => println!("spot {} {}", spot.x, spot.y),
Err(err) => println!("spot err {err}"),
}
println!("tagged {}", api::tagged(doc, "t"));
println!(
"entries {}",
Expand Down
40 changes: 0 additions & 40 deletions ffi/fixtures/api/ffi.toml

This file was deleted.

Loading