Skip to content
Draft
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 .github/workflows/bindings-test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,8 @@ jobs:
go-module: example.com/api
# No swift-check: api.swift compiles against the fixture's own test export, of the host
# and wasm32-wasip1, not this one's targets. Its transcript stays the exporter's tests'.
# Nor a dart-check: api.dart, as api.go, names wasm32 items this export lacks, so the
# Dart consumers resolve the library alone.

moq:
name: moq stand-in
Expand All @@ -66,3 +68,5 @@ jobs:
scope: kixel-ai
# Under the export's own module, `moq`, which moq.go imports.
go-check: ffi/moq/moq.go
# The export's package, `moq`, which moq.dart imports.
dart-check: ffi/moq/moq.dart
211 changes: 208 additions & 3 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, C archives,
# Go module, and web package, which a release workflow ffi/release/package.py's `init` writes
# Go module, pub.dev package, 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 Down Expand Up @@ -64,6 +64,10 @@ on:
description: The main.go of a program, importing the module's packages, run against it
default: ''
type: string
dart-check:
description: The main.dart of a program, importing the package as package:<lib>/<lib>.dart, run by Dart and Flutter apps on it
default: ''
type: string
checks-artifact:
description: An artifact of the caller's run unpacked over its checkout before the checks are read, for checks it generates
default: ''
Expand All @@ -89,6 +93,8 @@ env:
CARGO_TERM_COLOR: always
MANIFEST: ${{ inputs.manifest-path }}
FEATURES: ${{ inputs.features }}
# The NDK the Android libraries build with: Flutter's default.
NDK: 28.2.13676358

jobs:
facts:
Expand Down Expand Up @@ -190,6 +196,10 @@ jobs:
- host: windows
os: windows-latest
targets: x86_64-pc-windows-msvc x86_64-pc-windows-gnu aarch64-pc-windows-msvc
# The Dart package's and the Go module's Android libraries, through the NDK.
- host: android
os: ubuntu-24.04
targets: aarch64-linux-android armv7-linux-androideabi x86_64-linux-android
runs-on: ${{ matrix.os }}
timeout-minutes: 60
defaults:
Expand Down Expand Up @@ -217,6 +227,11 @@ jobs:
if: needs.facts.outputs.fixture == 'true'
working-directory: source
run: just ffi standin
- name: Android NDK
if: matrix.host == 'android'
run: |
"$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" --install "ndk;$NDK" > /dev/null
echo "ANDROID_NDK_HOME=$ANDROID_HOME/ndk/$NDK" >> "$GITHUB_ENV"
# musl-gcc, which a build script's cc compiles musl's C with.
- if: runner.os == 'Linux'
run: sudo apt-get update -q && sudo apt-get install -yq musl-tools
Expand Down Expand Up @@ -267,14 +282,17 @@ jobs:
- host: apple-catalyst
os: macos-26
targets: aarch64-apple-ios-macabi
# Intel macOS's Go library, which the export's Go links once its API is merged, and
# its native output; named apart from apple-*, the Swift package's slices.
# Intel macOS's Go and Dart libraries, which the export's Go links once its API is
# merged, and its native output; named apart from apple-*, the Swift package's slices.
- host: darwin-x64
os: macos-15-intel
targets: x86_64-apple-darwin
- host: windows
os: windows-latest
targets: x86_64-pc-windows-msvc x86_64-pc-windows-gnu
- host: android
os: ubuntu-24.04
targets: aarch64-linux-android armv7-linux-androideabi x86_64-linux-android
runs-on: ${{ matrix.os }}
timeout-minutes: 90
defaults:
Expand Down Expand Up @@ -312,6 +330,11 @@ jobs:
macOS) python -m pip install delocate==0.13.0 ;;
Windows) python -m pip install delvewheel==1.13.2 ;;
esac
- name: Android NDK
if: matrix.host == 'android'
run: |
"$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" --install "ndk;$NDK" > /dev/null
echo "ANDROID_NDK_HOME=$ANDROID_HOME/ndk/$NDK" >> "$GITHUB_ENV"
- name: Exporter
working-directory: rust2/ffi
env:
Expand Down Expand Up @@ -392,6 +415,7 @@ jobs:
SWIFT_CHECK: ${{ inputs.swift-check }}
C_CHECK: ${{ inputs.c-check }}
GO_CHECK: ${{ inputs.go-check }}
DART_CHECK: ${{ inputs.dart-check }}
run: |
mkdir -p dist/checks
stage() {
Expand All @@ -402,6 +426,19 @@ jobs:
# A file's extension says whether it is C or C++.
if [[ -n "$C_CHECK" ]]; then stage "$C_CHECK" dist/checks/c "check.${C_CHECK##*.}"; fi
if [[ -n "$GO_CHECK" ]]; then cp "source/$GO_CHECK" dist/checks/main.go; fi
if [[ -n "$DART_CHECK" ]]; then cp "source/$DART_CHECK" dist/checks/main.dart; fi
# The export's own package, as a checkout depends on it: its hook builds the crate.
- uses: dart-lang/setup-dart@2286a0c042b44434fe26d292bbce8d34f7ec662b # v1.8.2
if: matrix.host == 'linux-x64'
with:
sdk: stable
- name: Dart from source
if: matrix.host == 'linux-x64'
run: |
args=()
if [[ -f dist/checks/main.dart ]]; then args+=(--check dist/checks/main.dart); fi
if [[ -f dist/native.txt ]]; then args+=(--native dist/native.txt); fi
python3 -I rust2/ffi/release/package.py consume-source --export export "${args[@]}"
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: ${{ needs.facts.outputs.name }}-build-${{ matrix.host }}
Expand Down Expand Up @@ -970,3 +1007,171 @@ jobs:
if [[ -f dist/checks/main.go ]]; then args+=(--check dist/checks/main.go); fi
if [[ -f dist/native.txt ]]; then args+=(--native dist/native.txt); fi
python3 -I rust2/ffi/release/package.py consume-go --proxy proxy "${args[@]}"

# The pub.dev package: the export's, its hook/release.json naming each target's library on
# the release by size and SHA-256, and what pub asks of a package beside, which pub checks
# as publishing would, and the analyzer with the lints pub.dev scores it by.
pub:
needs: [facts, build, agree, changes]
runs-on: ubuntu-24.04
timeout-minutes: 15
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
path: source
persist-credentials: false
- 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
ffi/tests/dart_lints.yaml
sparse-checkout-cone-mode: false
persist-credentials: false
- uses: taiki-e/install-action@3a3daafd3b7f23b8f65d9f5ba2db203fb59b79e2 # v2.90.2
if: needs.facts.outputs.fixture == 'true'
with:
tool: just
- name: Stand-in
if: needs.facts.outputs.fixture == 'true'
working-directory: source
run: just ffi standin
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
pattern: ${{ needs.facts.outputs.name }}-build-*
path: builds
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: ${{ needs.facts.outputs.name }}-release
path: release
- uses: dart-lang/setup-dart@2286a0c042b44434fe26d292bbce8d34f7ec662b # v1.8.2
with:
sdk: stable
- name: Package
env:
NAME: ${{ needs.facts.outputs.name }}
URL: https://github.com/${{ github.repository }}/releases/download/${{ needs.facts.outputs.tag }}/
run: |
mkdir -p pub/libs
cp builds/*/dart/* pub/libs/
cd source
python3 -I ../rust2/ffi/release/package.py pub --manifest-path "$MANIFEST" --export "../builds/$NAME-build-linux-x64/export" --libs ../pub/libs --url "$URL" --changes ../release/changes.md --out ../pub/package
# Each in a copy, as resolving writes into the package.
- name: Check
run: |
cp -R pub/package publish
(cd publish && dart pub publish --dry-run)
cp -R pub/package lint
cp rust2/ffi/tests/dart_lints.yaml lint/analysis_options.yaml
(cd lint && dart pub get && dart analyze --fatal-infos .)
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: ${{ needs.facts.outputs.name }}-pub
path: pub
if-no-files-found: error

# New Dart apps depending on the package, its libraries served from the loopback as the
# release hosts them: one its hook refuses a library of other bytes, and one run by `dart
# run` and from `dart build cli`'s bundle, on the newest Dart and on 3.10, the oldest the
# package takes.
dart-consumer:
needs: [facts, pub]
strategy:
fail-fast: false
matrix:
include:
- host: linux-x64
os: ubuntu-24.04
sdk: stable
- host: linux-x64
os: ubuntu-24.04
sdk: 3.10.0
- host: linux-arm64
os: ubuntu-24.04-arm
sdk: stable
- host: apple-darwin
os: macos-26
sdk: stable
- host: darwin-x64
os: macos-15-intel
sdk: stable
- host: windows
os: windows-latest
sdk: stable
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: dart-lang/setup-dart@2286a0c042b44434fe26d292bbce8d34f7ec662b # v1.8.2
with:
sdk: ${{ matrix.sdk }}
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: ${{ needs.facts.outputs.name }}-pub
path: pub
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: ${{ needs.facts.outputs.name }}-build-${{ matrix.host }}
path: dist
- name: Run
run: |
args=()
if [[ -f dist/checks/main.dart ]]; then args+=(--check dist/checks/main.dart); fi
if [[ -f dist/native.txt ]]; then args+=(--native dist/native.txt); fi
python3 -I rust2/ffi/release/package.py consume-dart --package pub/package --libs pub/libs "${args[@]}"

# A new Flutter app depending on the package, its libraries served from the loopback,
# run on an x86_64 Android emulator, which this runner's KVM runs at speed, then again
# after a hot restart, which keeps the library and Rust's statics but not the isolate.
flutter-consumer:
needs: [facts, pub]
runs-on: ubuntu-24.04
timeout-minutes: 45
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 }}-pub
path: pub
# The check and native Rust's output, as Linux on x86_64 printed it.
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: ${{ needs.facts.outputs.name }}-build-linux-x64
path: dist
- uses: subosito/flutter-action@1a449444c387b1966244ae4d4f8c696479add0b2 # v2.23.0
with:
channel: stable
- name: Enable KVM
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
- name: Arguments
run: |
args="--package pub/package --libs pub/libs --platform android --device emulator-5554"
if [[ -f dist/checks/main.dart ]]; then args+=" --check dist/checks/main.dart"; fi
if [[ -f dist/native.txt ]]; then args+=" --native dist/native.txt"; fi
echo "ARGS=$args" >> "$GITHUB_ENV"
# Flutter's oldest Android, the floor the hook checks the app's against.
- uses: reactivecircus/android-emulator-runner@a421e43855164a8197daf9d8d40fe71c6996bb0d # v2.38.0
with:
api-level: 24
arch: x86_64
script: python3 -I rust2/ffi/release/package.py consume-flutter $ARGS
2 changes: 1 addition & 1 deletion bench/ffi/report.py
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@
("Python", ["python/moq.py"], ["src/python"]),
("Swift", ["swift"], []),
("Go", ["go"], []),
("Dart", ["dart/moq.dart"], ["src/dart"]),
("Dart", ["dart/lib/moq.dart"], ["src/dart"]),
]

# The TypeScript, under the wasm32 stand-in's export, and the glue its module builds with.
Expand Down
22 changes: 16 additions & 6 deletions ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,8 @@ Beside the C header, `include/<prefix>.hpp` holds the same API in C++, over a he
name. `python/<prefix>.py` holds it in Python, over a CPython
extension the crate builds with `--features python`, `swift/<prefix>.swift` holds it in
Swift, over the C header as a clang module, `go/` holds it in Go, a package per crate
over the C ABI through cgo, and `dart/<prefix>.dart` holds it in Dart, over the C ABI through
`dart:ffi` and what the crate builds with `--features dart`. When `wasm32-wasip1` is among
over the C ABI through cgo, and `dart/` holds it as a Dart package, `lib/<prefix>.dart` over
the C ABI through `dart:ffi` and what the crate builds with `--features dart`. When `wasm32-wasip1` is among
the targets, `web/` holds it in TypeScript for the web, ES modules over the `.wasm` the
crate builds with `--target wasm32-wasip1 --features web`.
An export again rewrites only the files whose content changed, and removes from
Expand Down Expand Up @@ -496,6 +496,8 @@ Linux's exports, as the merge queue runs on, since a header names its targets.
panic or a failed check that aborts goes to logcat as `rust2-ffi` and to bionic's abort
message, which shows in the tombstone, `ApplicationExitInfo`, and Play vitals, since an
app's stderr goes nowhere.
- **Apple**: the build script links the library with room in its header for the longest
install name, as Dart and Flutter rename it to the path they bundle it at.
- **Names** are the prefix, then the item's path from the facade's root, each segment in
Rust's case, joined by `_`: `track::Producer::append_group` is
`moq_track_Producer_append_group`, and moq-net's `session::Stats` and `Session::stats`
Expand Down Expand Up @@ -1366,10 +1368,18 @@ other than one in its own form, `module <path>` and `go 1.24`.

## Dart

`<prefix>.dart` is the library `package:<prefix>/<prefix>.dart` over the C ABI through
`dart:ffi`, tested on Dart 3.13. Each C function is an `@Native` external, which finds
the shared library the crate builds with `--features dart` as the package's native asset:
the library's own URI, mapped to the library by a build hook or by `--native-assets`.
`dart/` is the package `<prefix>`, whose `lib/<prefix>.dart` is the library
`package:<prefix>/<prefix>.dart` over the C ABI through `dart:ffi`, tested on Dart 3.13 and,
as its `pubspec.yaml` says, taken by Dart 3.10 and later, whose build hooks are stable. Each
C function is an `@Native` external, which finds the shared library the crate builds with
`--features dart` as the package's native asset: the library's own URI, which the package's
`hook/build.dart` maps to the library when an app depending on it builds or runs. In an
export, the hook builds the crate beside the package, `../Cargo.toml`, with Cargo, on the
target the app builds for, for the Android NDK of an app's Flutter build, and reruns when a
source the build read changes, Cargo's dep-info says which. A release's adds
`hook/release.json`, from which it downloads the library instead
([Binding releases](release/README.md)). The prefix must name a Dart package, lowercase
letters, digits, and `_` and no reserved word, or the export fails.

- **Names** are the C names without the prefix: a type in Pascal case and a member in
camel case, so `moq_track_Producer` is `TrackProducer`, and its method
Expand Down
1 change: 1 addition & 0 deletions ffi/fixtures/api/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ description = "Each construct rust2-ffi exports, driven from C by tests/api.c"
version = "0.0.0"
edition = "2024"
license = "MIT OR Apache-2.0"
repository = "https://github.com/kixel-ai/rust2"
publish = false

# Named apart from the package: the export's prefix, which the export must follow.
Expand Down
8 changes: 5 additions & 3 deletions ffi/justfile
Original file line number Diff line number Diff line change
Expand Up @@ -500,13 +500,13 @@ dart-program dir main:
aarch64) arch=arm64 ;;
*) arch=x64 ;;
esac
printf '{"configVersion": 2, "packages": [{"name": "moq", "rootUri": "file://%s/dart/", "packageUri": "./"}]}\n' "$out" > "$dir/.dart_tool/package_config.json"
printf '{"configVersion": 2, "packages": [{"name": "moq", "rootUri": "file://%s/dart/", "packageUri": "lib/"}]}\n' "$out" > "$dir/.dart_tool/package_config.json"
printf 'format-version: [1, 0, 0]\nnative-assets:\n %s_%s:\n "package:moq/moq.dart": [absolute, "%s"]\n' "{{ os() }}" "$arch" "$out/target/release/$lib" > "$dir/native_assets.yaml"
dart analyze --fatal-infos "$dir"
# pub.dev scores the library with the lints in tests/dart_lints.yaml, which the analyzer reads from the directory it analyzes.
rm -rf "$dir-lint"
mkdir "$dir-lint"
cp "$out"/dart/*.dart "$dir-lint"
cp "$out"/dart/lib/*.dart "$dir-lint"
cp tests/dart_lints.yaml "$dir-lint/analysis_options.yaml"
dart analyze --fatal-infos "$dir-lint"
sdk=$(dirname "$(dirname "$(realpath "$(command -v dart)")")")
Expand Down Expand Up @@ -659,8 +659,9 @@ standin checkout="" web="":
fi
ffi=$(cd "$src" && cargo metadata --format-version 1 --no-deps | jq -c '.packages[] | select(.name == "moq-ffi")')
features=$(jq -c '[.dependencies[] | select(.kind == null) | {key: .name, value: .features}] | from_entries' <<< "$ffi")
# moq-ffi's license, which a package of the stand-in states as moq-ffi's would.
# moq-ffi's license and repository, which a package of the stand-in states as moq-ffi's would.
license=$(jq -r '.license // empty' <<< "$ffi")
repository=$(jq -r '.repository // empty' <<< "$ffi")
mkdir -p "$dir/src"
# Replace a file only when its content changes, so an unchanged stand-in, and the
# export over it, stay fresh.
Expand All @@ -675,6 +676,7 @@ standin checkout="" web="":
printf '# Generated by just ffi standin, from %s.\n' "$src"
printf '[package]\nname = "moq-ffi"\nversion = "0.0.0"\nedition = "2024"\npublish = false\n'
if [ -n "$license" ]; then printf 'license = "%s"\n' "$license"; fi
if [ -n "$repository" ]; then printf 'repository = "%s"\n' "$repository"; fi
printf '\n'
# The prefix of every C name.
printf '[lib]\nname = "moq"\n\n[dependencies]\n'
Expand Down
Loading
Loading