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
4 changes: 4 additions & 0 deletions ffi/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

41 changes: 40 additions & 1 deletion ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ attributes in the Rust source.
Every language's generator but Python's builds on the C ABI.

```bash
rust2-ffi --config ffi.toml (--out dir | --census dir | --api file) [--manifest-path Cargo.toml] [--target triple]... [--with file]... [-- cargo args]
rust2-ffi --config ffi.toml (--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 @@ -184,6 +184,41 @@ package, features, and `exclude`, from the same sources: a staged span's file is
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.

## The API lock

Each export writes its API, merged across every target it serves, to `api.json` in `--out`,
in the format `--api` writes. `--baseline file` fails the export, writing nothing, where its
API breaks the one in `file`, with an error at each item that names how:

- an item removed, or no longer on one of the baseline's targets, and a target the baseline
serves that the export does not;
- a function's receiver, parameter, return, error, or asyncness changed, a constant's type
changed, a trait method added or changed, or a trait impl such as `Clone` dropped;
- a record's or variant's field added, removed, moved, or of another type, a variant
removed or of another value or, in an enum with fields, at another place, which is its C
tag, one added to an enum another crate matches exhaustively, and an enum gaining its
first variant with fields or losing its last, which changes it between a C enum and a
struct;
- the library's name, which every C name starts with;
- a C name that now names another item: since a name depends on every item exported
([The C ABI](#the-c-abi)), adding `audio::encoder_finish` renames `audio_encoder::finish`
to `moq_audio_encoder_finish_`, and a C caller of the old name would call the new item.
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
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 covers C's names, while a language's own names for a clash its generator renames are not
compared.

The baseline is a lockfile, not config: the consumer commits it beside `Cargo.lock`, the
export reads it only to compare, and the export is the same with or without it. It refuses a
baseline that is the `api.json` it would write. To accept a
break, export without `--baseline` and commit the `api.json` it writes. Its spans are relative
to the workspace and cargo's home, as a staged API's are, so a removed item's error points
where it was while its file is unchanged.

## The C ABI

- **Handles** are `Arc`s, and a call borrows the value as Rust's receiver or parameter
Expand Down Expand Up @@ -940,6 +975,10 @@ build must fail its contract check. The `target` test exports a package for the
binding, which builds for each, and staged with `--api` and `--with`; a build for a target
not exported fails, and items that differ between the two are refused, naming both.
The `reject` fixture's expected errors, each with its notes, are `fixtures/reject/expected.txt`.
The `lock` test exports the `lock` fixture for wasm32, staged, and the host, then again
against that export's `api.json`: its `added` feature only adds and must pass, and its `next`
feature breaks the API twice for each kind of break, once in an item only wasm32 has, each
error matching `fixtures/lock/expected.txt`.
moq's crates export through `target/moq-ffi`, an empty library on each that `just ffi moq`
writes in place of moq-ffi's remainder. `moq/moq.c` publishes and subscribes to a moq-net
track in one process, polling each read, scopes an origin to moq-pattern's patterns and
Expand Down
21 changes: 21 additions & 0 deletions ffi/fixtures/lock/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
[package]
name = "lock-fixture"
description = "An API whose features break it, or add to it, against the baseline exported without them"
version = "0.0.0"
edition = "2024"
license = "MIT OR Apache-2.0"
publish = false

# The export's prefix.
[lib]
name = "lock"

[features]
# Breaks the API twice for each kind of break: a C name another item takes, an item
# removed, a signature changed, a field changed, and a variant changed.
next = []
# Adds to the API, which the baseline lets pass.
added = []

[lints]
workspace = true
15 changes: 15 additions & 0 deletions ffi/fixtures/lock/expected.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
fixtures/lock/src/lib.rs:106:1: rust2-ffi: the API breaks the baseline at enum `lock::Mode`: variant `Idle` is added to an exhaustive enum
fixtures/lock/src/lib.rs:113:1: rust2-ffi: the API breaks the baseline at enum `lock::Shape`: variant `Circle`'s field `0`'s type changed
fixtures/lock/src/lib.rs:123:1: rust2-ffi: the API breaks the baseline at enum `lock::Stroke`: variant `Solid`'s tag 0 is now 1; variant `Dashed`'s tag 1 is now 0
fixtures/lock/src/lib.rs:135:1: rust2-ffi: the API breaks the baseline at enum `lock::Level`: a variant with fields makes it a struct in C
fixtures/lock/src/lib.rs:176:1: rust2-ffi: the API breaks the baseline at const `lock::DEPTH`: its type: it was `u32`, and is now `u64`
fixtures/lock/src/lib.rs:182:1: rust2-ffi: the API breaks the baseline at const `lock::PAGES`: its type: it was `u16`, and is now `i16`
fixtures/lock/src/lib.rs:191:1: rust2-ffi: the API breaks the baseline at tuple `((u32,), u64, u8)`: its C name `lock_tuple_tuple_u32_u64_u8` is now `lock_tuple_tuple_u32_u64_u8_`, and `lock_tuple_tuple_u32_u64_u8` names tuple `((u32, u64), u8)`
fixtures/lock/src/lib.rs:21:2: rust2-ffi: the API breaks the baseline at const `lock::limits_max::RATE`: its C name `LOCK_LIMITS_MAX_RATE` is now `LOCK_LIMITS_MAX_RATE_`, and `LOCK_LIMITS_MAX_RATE` names const `lock::limits::MAX_RATE`
fixtures/lock/src/lib.rs:30:1: rust2-ffi: the API breaks the baseline at fn `lock::removed`: it is removed
fixtures/lock/src/lib.rs:36:1: rust2-ffi: the API breaks the baseline at fn `lock::portable`: it is no longer on wasm32-unknown-unknown
fixtures/lock/src/lib.rs:46:1: rust2-ffi: the API breaks the baseline at fn `lock::scale`: its parameter `x`'s type; its return type
fixtures/lock/src/lib.rs:66:2: rust2-ffi: the API breaks the baseline at fn `lock::Meter::add`: its parameter `n`'s type
fixtures/lock/src/lib.rs:7:2: rust2-ffi: the API breaks the baseline at fn `lock::audio_encoder::finish`: its C name `lock_audio_encoder_finish` is now `lock_audio_encoder_finish_`, and `lock_audio_encoder_finish` names fn `lock::audio::encoder_finish`
fixtures/lock/src/lib.rs:86:1: rust2-ffi: the API breaks the baseline at struct `lock::Size`: field `depth` is added, which every value must now give
fixtures/lock/src/lib.rs:94:1: rust2-ffi: the API breaks the baseline at struct `lock::Canvas`: field `width`'s type changed
2 changes: 2 additions & 0 deletions ffi/fixtures/lock/ffi.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Nothing left out.
exclude = []
198 changes: 198 additions & 0 deletions ffi/fixtures/lock/src/lib.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,198 @@
//! An API exported for the host and wasm32, whose `next` feature breaks it in pairs and
//! whose `added` feature only adds to it.

/// Its C name, `lock_audio_encoder_finish`, is taken by `audio::encoder_finish` in `next`,
/// which comes first by path.
pub mod audio_encoder {
pub fn finish(level: u32) -> u32 {
level
}
}

#[cfg(feature = "next")]
pub mod audio {
pub fn encoder_finish(level: u32) -> u32 {
level + 1
}
}

/// `LOCK_LIMITS_MAX_RATE`, which `limits::MAX_RATE` takes in `next`.
pub mod limits_max {
pub const RATE: u32 = 60;
}

#[cfg(feature = "next")]
pub mod limits {
pub const MAX_RATE: u32 = 30;
}

#[cfg(not(feature = "next"))]
pub fn removed() -> u32 {
1
}

/// Not on wasm32 in `next`.
#[cfg(any(not(feature = "next"), not(target_arch = "wasm32")))]
pub fn portable() -> u32 {
2
}

#[cfg(not(feature = "next"))]
pub fn scale(x: u32) -> u32 {
x * 2
}

#[cfg(feature = "next")]
pub fn scale(x: u64) -> u64 {
x * 2
}

#[cfg_attr(feature = "added", derive(Clone))]
pub struct Meter {
total: u64,
}

impl Meter {
pub fn new() -> Self {
Self { total: 0 }
}

#[cfg(not(feature = "next"))]
pub fn add(&mut self, n: u32) {
self.total += u64::from(n);
}

#[cfg(feature = "next")]
pub fn add(&mut self, n: u16) {
self.total += u64::from(n);
}

#[cfg(feature = "added")]
pub fn reset(&mut self) {
self.total = 0;
}

pub fn total(&self) -> u64 {
self.total
}
}

impl Default for Meter {
fn default() -> Self {
Self::new()
}
}

pub struct Size {
pub width: u32,
#[cfg(feature = "next")]
pub depth: u32,
}

/// Only wasm32's API has it, so only the staged target's API breaks.
#[cfg(target_arch = "wasm32")]
pub struct Canvas {
#[cfg(not(feature = "next"))]
pub width: u32,
#[cfg(feature = "next")]
pub width: u64,
}

#[cfg(target_arch = "wasm32")]
pub fn canvas(width: u32) -> Canvas {
Canvas { width: width.into() }
}

pub enum Mode {
Fast,
Slow,
#[cfg(feature = "next")]
Idle,
}

pub enum Shape {
#[cfg(not(feature = "next"))]
Circle(u32),
#[cfg(feature = "next")]
Circle(f64),
Square(u32),
}

/// Its tags are its variants' places, which `next` swaps.
#[non_exhaustive]
pub enum Stroke {
#[cfg(feature = "next")]
Dashed(u32),
Solid(u32),
#[cfg(not(feature = "next"))]
Dashed(u32),
#[cfg(feature = "added")]
Dotted(u32),
}

/// A C enum, which a variant with fields in `next` makes a struct.
#[non_exhaustive]
pub enum Level {
Low,
#[cfg(feature = "added")]
High,
#[cfg(feature = "next")]
Custom(u8),
}

/// A handle `added` makes `Clone`, so copies of it may share one value.
#[cfg_attr(feature = "added", derive(Clone))]
pub struct Token {
id: u32,
}

impl Token {
pub fn new(id: u32) -> Self {
Self { id }
}

pub fn id(&self) -> u32 {
self.id
}
}

pub fn pick(mode: Mode, shape: Shape, stroke: Stroke, size: Size, level: Level) -> u32 {
let _ = (shape, stroke, size, level);
match mode {
Mode::Fast => 1,
_ => 0,
}
}

#[cfg(feature = "added")]
pub fn extra() -> u32 {
3
}

/// A constant `next` widens, on the host alone.
#[cfg(all(not(feature = "next"), not(target_arch = "wasm32")))]
pub const DEPTH: u32 = 8;
#[cfg(all(feature = "next", not(target_arch = "wasm32")))]
pub const DEPTH: u64 = 8;

/// A constant `next` makes signed, on wasm32 alone.
#[cfg(all(not(feature = "next"), target_arch = "wasm32"))]
pub const PAGES: u16 = 4;
#[cfg(all(feature = "next", target_arch = "wasm32"))]
pub const PAGES: i16 = 4;

/// A constant whose value `added` changes, which is no break.
#[cfg(not(feature = "added"))]
pub const LIMIT: u32 = 10;
#[cfg(feature = "added")]
pub const LIMIT: u32 = 20;

/// A tuple whose C name, `lock_tuple_tuple_u32_u64_u8`, `next` gives another tuple too.
pub fn nested(x: ((u32,), u64, u8)) -> u32 {
x.0.0
}

#[cfg(feature = "next")]
pub fn flat(x: ((u32, u64), u8)) -> u32 {
x.0.0
}
2 changes: 1 addition & 1 deletion ffi/src/abi.rs
Original file line number Diff line number Diff line change
Expand Up @@ -589,7 +589,7 @@ impl<'a> Abi<'a> {

/// A type by its key, with each tuple spelled as Rust spells it, which tells apart
/// tuples that share a C name.
fn spell(&self, ty: &Type) -> String {
pub fn spell(&self, ty: &Type) -> String {
match ty {
Type::Tuple(elements) => {
let elements: Vec<String> = elements.iter().map(|e| self.spell(e)).collect();
Expand Down
Loading