Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
e764163
chore(quest): claim quest/m1/ffi-packaging/c.md
kixelated Nov 19, 2026
61af158
feat(ffi): release C and C++ archives
kixelated Nov 19, 2026
b54db19
quest: finish quest/m1/ffi-packaging/c.md
kixelated Nov 19, 2026
695416e
fix(ffi): keep std's weak references weak, and read Mach-O symbols wi…
kixelated Nov 19, 2026
6cd24e7
fix(ffi): compare only a caller's C check, and find a prerelease only…
kixelated Nov 19, 2026
d5f727c
fix(ffi): name the shared library by its whole version, and require C…
kixelated Nov 19, 2026
0f83d57
fix(ffi): hide C's common symbols in the Mach-O prelink
kixelated Nov 19, 2026
f324068
fix(ffi): define C's common symbols for the Mach-O prelink, as ld-pri…
kixelated Nov 19, 2026
b502063
fix(ffi): count private external definitions before defining commons
kixelated Nov 19, 2026
92f573f
fix(ffi): escape the names GNU dialects predefine as macros
kixelated Nov 19, 2026
569e69f
quest: follow up on C++ names that escape alike
kixelated Nov 19, 2026
ab2c957
fix(ffi): keep each GNU macro name and its underscored forms apart in…
kixelated Nov 19, 2026
4d4d8d1
fix(ffi): name the shared C target <lib>_shared, and quote consume-c'…
kixelated Nov 19, 2026
5d94bfe
quest: record the maintainer's follow-up answers
kixelated Nov 19, 2026
20ef02c
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-packaging/c
kixelated Nov 19, 2026
5990d8a
test(ffi): drop the duplicate json import the merge left
kixelated Nov 19, 2026
5f09d6f
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-packaging/c
kixelated Nov 19, 2026
f7c3761
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-packaging/c
kixelated Nov 19, 2026
53413a7
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-packaging/c
kixelated Nov 19, 2026
55fa067
ffi: lock moq's C++ surface at the escaped Transport::unix_
kixelated Nov 19, 2026
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
5 changes: 4 additions & 1 deletion .github/workflows/bindings-test.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name: Binding packages test

# bindings.yml on the api fixture, whose Python and web consumers must print native Rust's
# bindings.yml on the api fixture, whose Python, C++, and web consumers must print native Rust's
# transcript byte for byte, and on moq's stand-in facade at the exporter's moq pin, its first consumer.
# Read-only: nothing here publishes.
on:
Expand All @@ -18,6 +18,8 @@ jobs:
features: doubled
example: transcript
python-check: ffi/tests/api.py
# api.cpp rather than api.c, whose broken cases name items only wasm32 has.
c-check: ffi/tests/api.cpp
web-manifest-path: ffi/fixtures/api/Cargo.toml
scope: kixel-ai
web-check: ffi/tests/api.ts
Expand All @@ -34,6 +36,7 @@ jobs:
manifest-path: ffi/target/moq-ffi/Cargo.toml
python-check: ffi/moq/moq.py
swift-check: ffi/moq/moq.swift
c-check: ffi/moq/moq.cpp
# moq's wasm32 stand-in, which leaves moq-tokio out, as no wasm32 target builds it.
web-manifest-path: ffi/target/moq-ffi-web/Cargo.toml
scope: kixel-ai
Expand Down
62 changes: 60 additions & 2 deletions .github/workflows/bindings.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
name: Binding packages

# The shared, read-only builder of a crate's rust2-ffi Python wheels, Swift package, Go
# module, and web package, which a release workflow ffi/release/package.py's `init` writes
# The shared, read-only builder of a crate's rust2-ffi Python wheels, Swift package, C archives,
# Go module, and web package, which a release workflow ffi/release/package.py's `init` writes
# calls at a pinned rust2 commit.
# It publishes nothing and holds no credentials: the caller's own jobs publish what it
# uploads, once its consumers pass. See ffi/release/README.md.
Expand All @@ -28,6 +28,10 @@ on:
description: The main.swift of an executable run on the installed Swift package
default: ''
type: string
c-check:
description: A C or C++ program built by clean CMake and pkg-config consumers of each C archive
default: ''
type: string
web-manifest-path:
description: The Cargo.toml of the package whose wasm32-wasip1 export the npm and JSR package holds, often manifest-path; without it, no web package
default: ''
Expand Down Expand Up @@ -327,11 +331,14 @@ jobs:
env:
PYTHON_CHECK: ${{ inputs.python-check }}
SWIFT_CHECK: ${{ inputs.swift-check }}
C_CHECK: ${{ inputs.c-check }}
GO_CHECK: ${{ inputs.go-check }}
run: |
mkdir -p dist/checks
if [[ -n "$PYTHON_CHECK" ]]; then cp "source/$PYTHON_CHECK" dist/checks/check.py; fi
if [[ -n "$SWIFT_CHECK" ]]; then cp "source/$SWIFT_CHECK" dist/checks/main.swift; fi
# Its extension says whether it is C or C++.
if [[ -n "$C_CHECK" ]]; then mkdir dist/checks/c && cp "source/$C_CHECK" dist/checks/c/; fi
if [[ -n "$GO_CHECK" ]]; then cp "source/$GO_CHECK" dist/checks/main.go; fi
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
Expand Down Expand Up @@ -525,6 +532,57 @@ jobs:
MODULE: ${{ needs.facts.outputs.module }}
run: bash rust2/ffi/release/consume-swift.sh swift apple

# Each C archive unpacked alone, with no checkout, Rust, or source path: a new CMake project
# finding it by its CPS file and by its config package, and on Linux and macOS a pkg-config
# build, each linking the static and the shared library.
c:
needs: [facts, build, agree]
strategy:
fail-fast: false
matrix:
include:
- host: linux-x64
os: ubuntu-24.04
- host: linux-arm64
os: ubuntu-24.04-arm
- host: apple-darwin
os: macos-26
- host: windows
os: windows-latest
runs-on: ${{ matrix.os }}
timeout-minutes: 20
defaults:
run:
shell: bash
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: ${{ needs.facts.outputs.rust2 }}
ref: ${{ needs.facts.outputs.rust2-sha }}
path: rust2
sparse-checkout: ffi/release
persist-credentials: false
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: ${{ needs.facts.outputs.name }}-build-${{ matrix.host }}
path: dist
# The oldest CMake that reads CPS is 4.3; the config package serves older ones too.
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: '3.13'
- name: Consume
run: |
python -m pip install cmake==4.4.5
if [[ "$RUNNER_OS" == macOS ]] && ! command -v pkg-config > /dev/null; then brew install pkgconf; fi
shopt -s nullglob
archives=(dist/c/*)
[[ ${#archives[@]} == 1 ]] || { echo "::error::expected one C archive, found ${archives[*]}"; exit 1; }
args=(--archive "${archives[0]}")
if [[ -f dist/native.txt ]]; then args+=(--native dist/native.txt); fi
checks=(dist/checks/c/*)
if [[ ${#checks[@]} == 1 ]]; then args+=(--check "${checks[0]}"); fi
python -I rust2/ffi/release/package.py consume-c "${args[@]}"

# The web binding's npm and JSR packages: web-manifest-path exported for wasm32-wasip1
# alone, the binding's only target, and its module built beside it; with native Rust's
# output on that target, which the consumers compare with.
Expand Down
4 changes: 3 additions & 1 deletion ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -481,7 +481,9 @@ packages place it in.

- **Names** are the C names without the prefix, in a namespace of it: `moq_track_Producer`
is `moq::track_Producer`, and its method `moq_track_Producer_append_group` is
`moq::track_Producer::append_group`. A keyword takes a trailing `_` (`counter::new_`),
`moq::track_Producer::append_group`. A keyword, or a macro GNU dialects predefine
(`unix`, `linux`, `i386`, as in moq-tokio's `tokio::unix_`, and each of them followed by
underscores, so `unix_` becomes `unix__`), takes a trailing `_` (`counter::new_`),
as does a member named as its class or one of its fields, and a parameter named as a
member or as anything in the namespace, which it would hide.
- **Objects** are classes owning their handle through a `std::unique_ptr` whose deleter
Expand Down
91 changes: 62 additions & 29 deletions ffi/release/README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Binding releases

A crate's [rust2-ffi](/ffi/README.md) export, released as Python wheels, a Swift package,
a Go module, and a web package on npm and JSR. Two halves, split where Cargo's knowledge
ends:
C and C++ archives, a Go module, and a web package on npm and JSR. Two halves, split where
Cargo's knowledge ends:

- **The builder**, [`bindings.yml`](/.github/workflows/bindings.yml) over `package.py`,
shared and read-only. It derives everything from Cargo metadata and the export: package
Expand Down Expand Up @@ -56,8 +56,9 @@ A Cargo prerelease, such as `1.0.0-rc.1`, is a GitHub prerelease too.
The builder takes the crate's `Cargo.toml`, the `go-module` path, which without it is the
export's own `<prefix>` that no proxy serves, and optional inputs the caller's tests own:
`features` to ship, an `example` whose stdout is native Rust's transcript, and the
`python-check`, `swift-check`, and `go-check` programs that must print it through the
installed packages. Without a check, a consumer only imports the module. The web package
`python-check`, `swift-check`, `c-check`, and `go-check` programs that must print it through
the installed packages. Without a check, a consumer only imports the module, or links a
function of each C and C++ header. A `c-check` is C or C++ by its extension. The web package
takes `web-manifest-path`, the package exported for `wasm32-wasip1`, often the crate's own,
which no Cargo fact says builds for the web, and `scope`; and an optional `web-check`, a
TypeScript module importing the binding as `./web/<module>.ts` does beside an export,
Expand Down Expand Up @@ -97,7 +98,36 @@ crate apart from it takes `web-features` and `web-example` instead.
revision, since a package resolved by version cannot depend on a revision. Rust's
native link libraries become linker settings, per platform where they differ; any
other flag fails the build.
7. Go: one module for every target, at the module path and `v<version>`, the major
7. C and C++: an archive per wheel target, `<crate>-<version>-<target>.tar.gz`, or `.zip`
on Windows, built like the wheels, Linux's against glibc 2.28 and macOS's at 11.0. It
holds `include/` with both headers, the static and shared libraries, and three ways to
find them, each naming the native libraries the static library needs, from rustc's
`--print native-static-libs`:
- `lib/cmake/<lib>/<lib>-config.cmake`, whose `find_package(<lib>)` gives `<lib>::<lib>`,
the static library, and `<lib>::<lib>_shared`;
- `lib/cps/<lib>.cps`, the [Common Package Specification](https://cps-org.github.io/cps/)
of the same two components, which CMake 4.3 and newer prefers;
- `lib/pkgconfig/<lib>.pc`, which links the shared library, as the linker prefers it to
the static one beside it; `--static` adds the native libraries, for a prefix that holds
only the static library. None on Windows, whose MSVC has no pkg-config convention.

The shared library's SONAME, or `@rpath` install name on macOS, holds the whole version,
`lib<lib>.so.0.4.12` or `lib<lib>.0.4.12.dylib`: every binding checks at load that the
library's [contract](/ffi/README.md#the-c-abi) is its header's, so no two releases'
libraries can stand in for each other. A build-time request is another matter, as header
and library come together: the CMake and CPS versions accept one within Cargo's
compatible line, 0.4 for 0.4.12, and a prerelease only by a request naming no version.
Both targets require C11 and C++17 of what links them, the headers' floor.
On Windows it is `bin/<lib>.dll` with `lib/<lib>.dll.lib`, beside the static `lib/<lib>.lib`.

The static library is one object prelinked from Rust's archive (`ld -r`, then `objcopy`
on ELF and the linker's exported-symbols list on Mach-O) whose only global symbols are
the C ABI's, `<lib>_*`. So its std and compiler-builtins, with unmangled symbols such as
`__addvdi3`, cannot clash with another Rust static library in the same program, which
each build checks by linking one beside it. MSVC's linker has no relocatable link, so the
Windows static library keeps every symbol: a program with two Rust static libraries
there links the DLL instead.
8. Go: one module for every target, at the module path and `v<version>`, the major
version's `/vN` suffix checked: the export's `go/`, whose runtime's `#cgo` lines link
`rt/lib<prefix>_<goos>_<goarch>.a` for `linux/amd64` and `linux/arm64` (built against
glibc 2.28), `darwin/arm64` and `ios/arm64` (the Swift package's macOS and iOS device
Expand All @@ -112,35 +142,38 @@ crate apart from it takes `web-features` and `web-example` instead.
limit, each platform's library moves to a module of its own, whose one package's `#cgo`
line links it and which the runtime imports under that platform's build constraint, so
`go get` downloads only the platform it builds for.
8. The release's `api.json`, and `changes.md`, the items removed, changed, and added since
9. The release's `api.json`, and `changes.md`, the items removed, changed, and added since
the previous release's, by kind and Rust path; the caller's release publishes the first
as an asset and the second as its notes.
9. Consumers, with no checkout, Rust, or source path: each wheel installed with
`--no-index --no-deps` into a fresh environment on its oldest CPython, run with `-I`
from an empty directory; and the Swift package built by its own scheme for macOS, iOS,
and the iOS Simulator, then consumed by a new executable package that runs the check;
and the Go module, unpacked from its zip into a new module that requires it, vetted,
built with the newest Go and no `CGO_LDFLAGS`, and run on Linux x64 and arm64, macOS, and
Windows. With an `example`, each must print native Rust's stdout byte for byte.
8. Web: `web-manifest-path` exported for `wasm32-wasip1` alone, whose `web/` holds the
TypeScript, its JavaScript and declarations, and a `package.json`
([TypeScript (web)](/ffi/README.md#typescript-web)), and its module built at
`opt-level = "s"` unless the crate's release profile sets a level, as a page downloads
it. The npm package is the JavaScript, declarations, and module, named
`@<scope>/<crate>` with Cargo's description, license, and URLs, packed by `npm pack`;
the JSR package is the TypeScript and module with a `jsr.json` exporting each module by
name, refused past JSR's 20 MiB. The example runs for `wasm32-wasip1` under Node's WASI,
native Rust on the binding's target. A new npm project installs the tarball, as an
app would, and the `web-check`, or else a `load()`, runs on Node, Deno, and Bun, and
bundled by Vite and by webpack into a browser's script that Node runs, each finding the
module where `load` looks by default; and `deno publish --dry-run` checks the JSR
package, its types against Deno's included.
10. Consumers, with no checkout, Rust, or source path: each wheel installed with
`--no-index --no-deps` into a fresh environment on its oldest CPython, run with `-I`
from an empty directory; and the Swift package built by its own scheme for macOS, iOS,
and the iOS Simulator, then consumed by a new executable package that runs the check;
and each C archive unpacked alone, built by a new CMake project through its CPS file and
through its config package, and on Linux and macOS by pkg-config, linking each library,
where a shared consumer must record the versioned name; and the Go module, unpacked from
its zip into a new module that requires it, vetted, built with the newest Go and no
`CGO_LDFLAGS`, and run on Linux x64 and arm64, macOS, and Windows.
With an `example`, each must print native Rust's stdout byte for byte.
11. Web: `web-manifest-path` exported for `wasm32-wasip1` alone, whose `web/` holds the
TypeScript, its JavaScript and declarations, and a `package.json`
([TypeScript (web)](/ffi/README.md#typescript-web)), and its module built at
`opt-level = "s"` unless the crate's release profile sets a level, as a page downloads
it. The npm package is the JavaScript, declarations, and module, named
`@<scope>/<crate>` with Cargo's description, license, and URLs, packed by `npm pack`;
the JSR package is the TypeScript and module with a `jsr.json` exporting each module by
name, refused past JSR's 20 MiB. The example runs for `wasm32-wasip1` under Node's WASI,
native Rust on the binding's target. A new npm project installs the tarball, as an
app would, and the `web-check`, or else a `load()`, runs on Node, Deno, and Bun, and
bundled by Vite and by webpack into a browser's script that Node runs, each finding the
module where `load` looks by default; and `deno publish --dry-run` checks the JSR
package, its types against Deno's included.

rust2 runs it on every manual Check and nightly through
[`bindings-test.yml`](/.github/workflows/bindings-test.yml): on the api fixture, whose
wheels and web package must print its native transcript, and on moq's stand-in facade at
the exporter's moq pin, through `moq/moq.py`, `moq/moq.swift`, and `moq/moq.go`, with its
wasm32 stand-in as the web package.
wheels, C++ consumers, and web package must print its native transcript, and on moq's
stand-in facade at the exporter's moq pin, through `moq/moq.py`, `moq/moq.swift`,
`moq/moq.cpp`, and `moq/moq.go`, with its wasm32 stand-in as the web package.

## Other registries

Expand Down
Loading