Skip to content

ffi!: a pub.dev package with a build hook - #915

Draft
kixelated wants to merge 12 commits into
mainfrom
quest/m1/ffi-packaging/pubdev
Draft

kixelated wants to merge 12 commits into
mainfrom
quest/m1/ffi-packaging/pubdev

Conversation

@kixelated

@kixelated kixelated commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Finishes quest/m1/ffi-packaging/pubdev.md: the export writes a Dart package with a build hook, and the builder releases it to pub.dev.

Summary

  • The export's dart/ is a pub package: pubspec.yaml (named for the library's prefix, at the facade's version, sdk: ^3.10.0, on hooks, code_assets, and crypto), lib/<prefix>.dart (moved from dart/<prefix>.dart), and hook/build.dart (ffi/runtime/hook.dart, the same for every crate). The hook bundles the library as the asset package:<prefix>/<prefix>.dart its @Native functions name. The mode follows from what the package holds, never from trying one path and falling back:
    • with hook/release.json, which only a release writes: it downloads its target's library into the build's shared cache. It refuses one longer than, or of a SHA-256 other than, the release names, and an app targeting an older system than the library loads on.
    • without it: it runs Cargo on the crate beside it, ../Cargo.toml, with --release --features dart --target <app's>, through the NDK clang Flutter passes for Android. It reruns when a file Cargo's dep-info lists changes.
    • with neither: an error naming both.
  • Builder (package.py, bindings.yml):
    • Each host builds the Dart library of its targets, <crate>-<version>-dart-<target>.<so|dylib|dll>, the cdylib with the dart glue: Linux x64 and arm64 (glibc 2.28), macOS arm64 and x64 (10.15), iOS arm64 and its simulator (13.0), Windows x64, and Android arm64, armv7, and x86_64 (API 24) at Flutter's floors.
    • New android api and build legs, using NDK r28.2, Flutter's default; a new macos-x64 build leg, plus x86_64-apple-darwin staged on the apple api leg.
    • A pub job writes the package. Its pubspec takes Cargo's description, repository, and homepage, and it adds LICENSE, README.md, a CHANGELOG.md from changes.md, and hook/release.json naming each library on the release by size and SHA-256. It then runs dart pub publish --dry-run, which must find no warning, and dart analyze --fatal-infos with pub.dev's lints.
    • Consumers:
      • dart-consumer: a new app on Linux x64 and arm64, macOS, and Windows, on stable Dart and on Linux on 3.10.0. Its libraries are served from the loopback. It first checks that a tampered library is refused, then runs dart run and the dart build cli bundle.
      • flutter-consumer: a new Flutter app on an x86_64 API 24 emulator, driven through flutter run --machine and run again after a full hot restart.
      • On the linux-x64 build leg: an app on the export's own package, whose hook builds the crate from source.
  • Caller's release (release.yml): attests and uploads each Dart library with the C archives, then a pub job publishes through pub.dev's automated publishing in a pub environment. On a rerun, it diffs pub.dev's hosted archive instead of publishing again.
  • bindings-test.yml runs ffi/moq/moq.dart as the stand-in's dart-check. The fixtures now set Cargo's repository, the stand-in from moq-ffi's, as pub's dry run warns without one.
  • Docs: ffi/release/README.md (adoption steps, item 9, consumers) and ffi/README.md. The "Other registries" table loses its pub.dev row.

Decisions

The maintainer was away, so I took my recommendation on each open point:

  1. The package name is the library's prefix (moq for the stand-in, moq_ffi for moq-ffi, the name moq already publishes). An export whose prefix isn't a valid Dart package name fails. Rejected: the crate's name, which pub cannot spell with -.
  2. The mode depends on whether hook/release.json exists. Rejected: moq's hand-written hook's user_defines library override. It is a consumer config key, and building from source covers a checkout. Also rejected: finding a checkout by a fixed relative path (../../rs/moq-ffi), which only works for one repository's layout.
  3. Raw libraries on the <crate>-v<version> GitHub release, the XCFramework's host, URL derived as Swift's is (no new input). Size and SHA-256 live in release.json and the hook reads at most that size. There are no .sha256 assets, unlike moq's hook: pub's package hash already pins release.json.
  4. Targets add x86_64-apple-darwin and the three Android ABIs, the ones Flutter builds for by default (flutter build macos is universal, flutter build apk builds three ABIs). Not shipped: the x86_64 iOS simulator, Windows arm64, and Linux riscv64. The source build maps them.
  5. Floors are Flutter's defaults (Android 24, iOS 13.0, macOS 10.15). The hook checks them against the app's target. arm64 macOS is not checked, since every arm64 Mac runs 11.
  6. SDK floor ^3.10.0, where hooks went stable, tested by its own consumer leg. Dart 3.10's dart run prints "Running build hooks..." on stdout, which the consumer strips before comparing. code_assets ^2.2.0 for deploymentVersion; crypto costs nothing extra, since hooks already depends on it.
  7. LICENSE concatenates the crate's license files, as pub reads no other name. A crate with none gets Cargo's SPDX expression, and one with neither fails. README.md is the crate's readme, or a generated line. CHANGELOG.md is changes.md under the version.
  8. A dry-run warning fails the release (pub exits 65). That includes a missing repository, which is why both fixtures now set one.
  9. Source builds use --release. Hooks get no build mode, and the release profile is the one that ships.
  10. Publishing uses pub.dev's automated publishing on the tag push, in a pub environment. The first version is published by hand, since pub.dev configures it only for a package it holds. The job runs after github-release, so a package never names a library the release doesn't host yet.
  11. The source-build check runs only on the linux-x64 build leg. It costs one more release build of the crate there. The exporter's tests stay off the network, which dart pub get needs.
  12. The Flutter harness captures print in a zone and reports it base64-encoded in 800-character lines between markers. Android's log splits long lines, and a Linux desktop app's output bypasses app.log. A check therefore prints with print (documented as a dart-check rule).

Public API

  • Breaking, export layout: dart/<prefix>.dart moves to dart/lib/<prefix>.dart, beside the new dart/pubspec.yaml and dart/hook/build.dart. To migrate, depend on dart/ as a package, or point a package config's packageUri at lib/.
  • Breaking: an export whose library prefix is no Dart package name (uppercase letters, a reserved word) fails.
  • Builder: a new dart-check input; new <crate>-pub artifact, android and macos-x64 build legs, android api leg; new package.py commands pub, consume-dart, consume-source, consume-flutter.
  • Caller's release: a new pub job and pub environment; Dart libraries on the GitHub release and in the attestations. A caller re-runs package.py init or copies the job.
  • No wire impact.

Validation

  • Local, on the api fixture exported for the host:
    • A clean app depending on dart/ by path: dart run ran the hook, which built the crate with Cargo and printed the transcript. A second run took 1s, from cache. Its dependencies were the export's sources and the facade's, from Cargo's dep-info.
    • package.py pub with the host's library and stand-ins for the others, then dart pub publish --dry-run: no warnings. dart analyze --fatal-infos with pub.dev's lints, hook included: no issues.
    • consume-dart: refused the tampered library on its SHA-256, and printed the check's output under dart run and from the dart build cli bundle, on Dart 3.13 and 3.10.0. A wrong expected transcript failed with a diff.
    • consume-flutter --platform linux (Flutter 3.47.4, Linux desktop under Xvfb): a check that crosses into Rust printed the same lines under dart run and in the Flutter app, both before and after a full hot restart. The check made objects, had Rust call a Dart implementation from another thread, awaited a future bound to a home, and had Rust await a Dart future. This exercises the leaked per-isolate Home and Rust's OnceLock'd API table across a restart.
  • just ci: passes.
  • python3 -I ffi/release/test_package.py: 65 tests, including new ones for pub_package.
  • Release builder on this branch: Check run 44723787915, pending. Its Android emulator leg is the first run on Android.

Follow-ups

  • moq-dev/moq (for /quest-plan there): move moq_ffi to this release. Turn on pub.dev's automated publishing for moq's moq-ffi-v{{version}} tags in a pub environment, then delete dart/moq_ffi/hook/build.dart and its packaging.
  • kixel-ai/rust2#909's quest/m1/ffi-packaging/api-checks.md owns running the api fixture's checks with their generated transcripts. api.dart belongs in it too, and the Dart consumers resolve the library alone until then.
  • quest/m1/ffi-packaging/maven.md can build its jniLibs on the android legs this adds.

Models

Size: M
Implementer: Claude Code, claude-opus-5-5, unknown effort (arm B)

(Written by Claude Opus 5.5)

Review

Rewritten by quest review after each round.

  • Head: e538a08

  • Base: origin/main at 31c21f8

  • Risk: high, it changes .github/workflows/bindings-test.yml, which is always high, as are 1 more of its paths: workflows run with the repository's secrets and decide what merges and ships

  • Classified: high by the always-high paths

  • Reviewer: Codex, gpt-6.1-sol, high effort

  • Session: 01a1f89d-681d-7a81-bf31-52e538727850, round 8

  • Score: 10/10, The incremental changes handle relative export paths in sdists and include Android’s required log library in Go link flags, with no new issues found.

  • Rounds: 8; first round 2 (medium 2); findings 2 (medium 2): fixed 2, refuted 0, open 0

  • Findings: none

  • Reviewer: Codex, gpt-6.1-sol, medium effort, shadow

  • Session: 01a1f89d-681d-72a3-a4fc-a5273d0932b1

  • Rounds: 3; first round 2 (medium 2); findings 2 (medium 2): fixed 2, refuted 0, open 0

@coderabbitai

coderabbitai Bot commented Nov 20, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

kixelated and others added 3 commits November 20, 2026 02:41
The export writes dart/ as a Dart package: pubspec.yaml, lib/<prefix>.dart, and
hook/build.dart, which builds the crate beside it with Cargo. The builder builds each
Dart target's library, Android's through the NDK, writes the pub.dev package whose
hook/release.json names each by size and SHA-256 on the release, and checks it in
clean Dart apps and a Flutter app on an Android emulator through a hot restart.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title A pub.dev package with a build hook ffi!: a pub.dev package with a build hook Nov 20, 2026
kixelated and others added 2 commits November 20, 2026 03:06
…ts manifests and lock

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codspeed

codspeed Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Merging this PR will degrade performance by 5.36%

1 warning

⚠️ 25 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

⚡ 3 improved benchmarks
❌ 2 regressed benchmarks
✅ 80 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

Benchmark BASE HEAD Efficiency
❌ write 902.3 ms 1,445 ms -37.55%
❌ throughput[100] 8 s 9.9 s -19.06%
⚡ loop 11.5 s 9.6 s +20.6%
⚡ woken 10.4 s 9.3 s +11.81%
⚡ ready 3.7 s 3.3 s +11.42%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


Comparing quest/m1/ffi-packaging/pubdev (e538a08) with main (31c21f8)

Open in CodSpeed

kixelated and others added 6 commits November 20, 2026 04:33
… 3.14's AOT resolves

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ndles it at

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rt now names

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Dart libraries build on main's Intel Mac leg in place of this branch's, whose consumer
now runs there too, and the source hook resolves the facade path main's export writes
relative to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… writes

#909's sdist keyed each local package by its absolute path and #917 made the generated
manifest spell them relative to the export, so the sdist refused every export on a
checkout without a symlink, and unreached_types expected the absolute spelling.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant