[Binding Creator] Enhance documentation for adding new frameworks and clarify Xtro checks - #26028

dalexsoto · 2026-07-09T22:17:59Z

No description provided.

… clarify Xtro checks

dalexsoto · 2026-07-09T22:20:07Z

+> ⚠️ **Xcode 27: `simctl create` dropped `--json`.** mlaunch auto-creates the sim device via `simctl create … --json`, which now fails with `MT1008 … simctl: unrecognized option '--json'`. Workaround: **pre-create** the device with the exact name mlaunch expects so it finds it instead of creating it, e.g. `xcrun simctl create "iPhone 16 Pro - iOS 27.0" <devicetype-id> <runtime-id>`, then re-run mlaunch. (Environment-specific to Xcode 27 until mlaunch is updated.)
+


@rolfbjarne did copilot actually catch a bug or just needs better docs? 😂

Yeah, this might be an mlaunch bug! mlaunch passing --json when creating simulators might just be accidental, and it worked in the past accidentally.

Copilot

Pull request overview

This PR improves the macios-binding-creator skill documentation to better guide contributors through (1) adding bindings for an entirely new Apple framework and (2) understanding what XTRO does and does not validate, plus a few high-impact test/debug workflow clarifications.

Changes:

Added a cross-reference and warning in SKILL.md for the extra build/test wiring required when binding a brand-new framework.
Expanded the test workflow reference to clarify XTRO selector coverage (native → managed only) and added practical notes for documentation baselines and desktop introspection pitfalls.
Added a detailed “Registering a Brand-New Framework” checklist (with build gotchas) and additional binding patterns to binding-patterns.md.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
.agents/skills/macios-binding-creator/SKILL.md	Adds prominent warnings/links about brand-new framework wiring and correct preprocessor symbol ordering for Mac Catalyst.
.agents/skills/macios-binding-creator/references/test-workflow.md	Clarifies XTRO selector behavior, documentation baseline expectations, and adds troubleshooting guidance for simulator creation and desktop introspection.
.agents/skills/macios-binding-creator/references/binding-patterns.md	Introduces a checklist for registering new frameworks and documents build/test “gotchas” and NS_TYPED_ENUM set-wrapping patterns.

dalexsoto · 2026-07-09T22:21:12Z

+- **Unbound Objective-C class** → alias it to `Foundation.NSObject` with a `using` at the top of the API-definition file (a short comment naming the owning framework helps reviewers). Precedent: `src/browserenginekit.cs:47` aliases the XPC `xpc_object_t` type this way — `using OS_xpc_object = Foundation.NSObject;` — for its `xpc_object_t` parameters/returns. (This is *different* from platform-stubbing an otherwise-bound type under `#if` — for that, see "Platform Exclusion for Manual Types" below.)
+- **C primitive** (`kern_return_t`, `IOReturn`, `io_service_t`, …) → map to a plain integer / `IntPtr`, never a bound type. Verified precedent: `kern_return_t` → `int` in `src/IOSurface/IOSurface.cs` (`// kern_return_t` → `public int Lock (...)`). For other C typedefs, confirm the width/signedness from the header before choosing `int`/`uint`/`nint`/`IntPtr`.
+
+> ⚠️ Reviewers may ask "why not bind this type?" — the answer is that the owning framework is deliberately out of macios's scope (IOKit-family), so the NSObject-alias / integer fallback is the intended convention, not a shortcut.


HAHAHA those pesky human meatbags 😂

vs-mobiletools-engineering-service2 · 2026-07-10T01:54:41Z

🔥 Failed to compute test summaries on VSTS: test results 🔥

Failed to compute test summaries: Unable to understand the test result '# ⚠️ arm64 - Mac Golden Gate (27): Tests skipped, incorrect beta version' for test 'Tests on macOS Golden Gate (27)'.

Pipeline on Agent
Merge 3f74d3c into 9f3bb3d

Mined four real Copilot sessions that ran the skill (Xcode 27 binding tasks: WebKit, VideoToolbox, Vision, UserNotifications) and fixed the gaps they exposed. All edits were triple-checked read-only by Opus 4.8, Sonnet 5, and GPT-5.5 (unanimous approval). - Error enums: add a NEVER-availability-attributes anti-pattern. The generic "each new enum member needs its own [iOS]" rule is build-breaking for error enums (cecil EnumTest.NoAvailabilityOnError, no allowlist). Hit in 2 of 4 sessions. - Enum members: rework the per-member availability rule to match the native header (add nothing when the member inherits), and add a multi-platform inheritance note (bgen back-fills the parent's older version via FindHighestIntroducedAttributes). - Elevate the named-delegate rule (never Action<T>/Func<T> for callbacks) into a SKILL.md Step 4 anti-pattern; it was buried in a reference and missed (required a user correction in WebKit). - Document introspection host-OS version gating in Step 6c: validate brand-new-SDK APIs on a matching-runtime simulator, not on a host macOS older than the SDK. - Add a training log under .agents/training-logs/. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5a002881-ea12-47a9-aed1-e64eb7b173c1

rolfbjarne

Looks good!

rolfbjarne · 2026-07-10T10:21:27Z

+> ⚠️ **Xcode 27: `simctl create` dropped `--json`.** mlaunch auto-creates the sim device via `simctl create … --json`, which now fails with `MT1008 … simctl: unrecognized option '--json'`. Workaround: **pre-create** the device with the exact name mlaunch expects so it finds it instead of creating it, e.g. `xcrun simctl create "iPhone 16 Pro - iOS 27.0" <devicetype-id> <runtime-id>`, then re-run mlaunch. (Environment-specific to Xcode 27 until mlaunch is updated.)
+


Yeah, this might be an mlaunch bug! mlaunch passing --json when creating simulators might just be accidental, and it worked in the past accidentally.

@rolfbjarne

Applied @rolfbjarne's review comments (skill approved, but several statements needed correcting). Each fix was verified against the repo and triple-checked read-only by GPT-5.6 Sol, Opus 4.8, Sonnet 5, and GPT-5.6 Terra. - Named delegates: downgrade the absolute "NEVER use Action<T>/Func<T>" rule to "PREFER a named delegate when a parameter's meaning isn't obvious" — Action<T>/Func<T> now support nullable type arguments, so the [NullAllowed] rationale is gone; named delegates still uniquely give parameter names + XML docs. (SKILL.md + binding-patterns.md) - Host-OS gating: remove the incorrect "(and may TCC-crash)". A member unavailable on the host OS is skipped by SkipDueToAttribute (IsAvailableOnHostPlatform), not crashed; TCC crashes are separate. - Introspection selectors: clarify ApiSelectorTest can't catch a privatized-but-still-implemented selector (respondsToSelector stays true), so don't rely on it to decide which bindings to remove. - Frameworks.cs sort: describe the real convention — grouped by the entry's OS version (newest last), case-insensitive alphabetical within each group — and note older groups have historical drift. - Cecil docs: lead with the WRITE_KNOWN_FAILURES=1 self-update; note the full-baseline rewrite can also drop now-fixed entries. - mlaunch --json: frame as a likely mlaunch bug. - Reference follow-up issues #26052 (generate-frameworks-constants not rebuilt when tools/common/Frameworks.cs changes) and #26053 (xtro report extra/unknown selectors), both filed at the maintainer's request. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5a002881-ea12-47a9-aed1-e64eb7b173c1

vs-mobiletools-engineering-service2 · 2026-07-12T03:53:58Z

🔥 Failed to compute test summaries on VSTS: test results 🔥

Failed to compute test summaries: Unable to understand the test result '# ⚠️ arm64 - Mac Golden Gate (27): Tests skipped, incorrect beta version' for test 'Tests on macOS Golden Gate (27)'.

Pipeline on Agent
Merge d17b65e into d263f74

vs-mobiletools-engineering-service2 · 2026-07-12T12:41:10Z

❗ API diff for current PR / commit (Breaking changes)

NET (empty diffs)

iOS: vsdrops gist ( ❗ Breaking changes ❗ )
tvOS: vsdrops gist ( ❗ Breaking changes ❗ )
MacCatalyst: vsdrops gist ( ❗ Breaking changes ❗ )
macOS: vsdrops gist ( ❗ Breaking changes ❗ )

✅ API diff vs stable

NET (empty diffs)

iOS: vsdrops gist ( No breaking changes )
tvOS: vsdrops gist ( No breaking changes )
MacCatalyst: vsdrops gist ( No breaking changes )
macOS: vsdrops gist ( No breaking changes )

ℹ️ Generator diff

Generator Diff: vsdrops (html) vsdrops (raw diff) gist (raw diff) - Please review changes)

Pipeline on Agent
Hash: 33d8a5258d0521420961e38b2d93de7932f3d0eb [PR build]

vs-mobiletools-engineering-service2 · 2026-07-12T14:22:02Z

✅ [CI Build #5677708] Prepare .NET Release succeeded ✅

📦 Published NuGet packages (32 packages)

iOS

Microsoft.iOS.Ref.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.iOS.Runtime.ios-arm64.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.iOS.Runtime.ios.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.iOS.Runtime.iossimulator-arm64.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.iOS.Runtime.iossimulator-x64.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.iOS.Sdk.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.iOS.Templates.27.0.10236-xcode27.0.nupkg
Microsoft.iOS.Windows.Sdk.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.NET.Sdk.iOS.Manifest-10.0.400-preview.0.27.0.10236-xcode27.0.nupkg

MacCatalyst

Microsoft.MacCatalyst.Ref.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.MacCatalyst.Runtime.maccatalyst-arm64.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.MacCatalyst.Runtime.maccatalyst-x64.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.MacCatalyst.Runtime.maccatalyst.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.MacCatalyst.Sdk.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.MacCatalyst.Templates.27.0.10236-xcode27.0.nupkg
Microsoft.NET.Sdk.MacCatalyst.Manifest-10.0.400-preview.0.27.0.10236-xcode27.0.nupkg

macOS

Microsoft.macOS.Ref.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.macOS.Runtime.osx-arm64.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.macOS.Runtime.osx-x64.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.macOS.Runtime.osx.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.macOS.Sdk.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.macOS.Templates.27.0.10236-xcode27.0.nupkg
Microsoft.NET.Sdk.macOS.Manifest-10.0.400-preview.0.27.0.10236-xcode27.0.nupkg

tvOS

Microsoft.NET.Sdk.tvOS.Manifest-10.0.400-preview.0.27.0.10236-xcode27.0.nupkg
Microsoft.tvOS.Ref.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.tvOS.Runtime.tvos-arm64.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.tvOS.Runtime.tvos.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.tvOS.Runtime.tvossimulator-arm64.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.tvOS.Runtime.tvossimulator-x64.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.tvOS.Sdk.net10.0_27.0.27.0.10236-xcode27.0.nupkg
Microsoft.tvOS.Templates.27.0.10236-xcode27.0.nupkg

Other

Sharpie.Bind.Tool.27.0.0.236-xcode27.0.nupkg

Pipeline on Agent
Hash: 56777080755077ab2de03bd8204d678c6f3abaca [PR build]

vs-mobiletools-engineering-service2 · 2026-07-12T20:05:31Z

🚀 [CI Build #b95a064] Test results 🚀

Test results

✅ All tests passed on VSTS: test results.

🎉 All 191 tests passed 🎉

Tests counts

✅ assembly-processing: All 1 tests passed. Html Report (VSDrops) Download
✅ cecil: All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (iOS): All 1 tests passed. [attempt 2] Html Report (VSDrops) Download
✅ dotnettests (MacCatalyst): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (macOS): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (Multiple platforms): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (tvOS): All 1 tests passed. Html Report (VSDrops) Download
✅ framework: All 2 tests passed. Html Report (VSDrops) Download
✅ fsharp: All 4 tests passed. Html Report (VSDrops) Download
✅ generator: All 5 tests passed. Html Report (VSDrops) Download
✅ interdependent-binding-projects: All 4 tests passed. Html Report (VSDrops) Download
✅ introspection: All 6 tests passed. Html Report (VSDrops) Download
✅ linker (iOS): All 15 tests passed. Html Report (VSDrops) Download
✅ linker (MacCatalyst): All 15 tests passed. Html Report (VSDrops) Download
✅ linker (macOS): All 21 tests passed. Html Report (VSDrops) Download
✅ linker (tvOS): All 15 tests passed. Html Report (VSDrops) Download
✅ monotouch (iOS): All 18 tests passed. Html Report (VSDrops) Download
✅ monotouch (MacCatalyst): All 17 tests passed. [attempt 2] Html Report (VSDrops) Download
✅ monotouch (macOS): All 18 tests passed. Html Report (VSDrops) Download
✅ monotouch (tvOS): All 18 tests passed. Html Report (VSDrops) Download
✅ msbuild: All 2 tests passed. Html Report (VSDrops) Download
✅ sharpie: All 1 tests passed. Html Report (VSDrops) Download
✅ windows: All 3 tests passed. Html Report (VSDrops) Download
✅ xcframework: All 4 tests passed. Html Report (VSDrops) Download
✅ xtro: All 1 tests passed. Html Report (VSDrops) Download

macOS tests

✅ Tests on macOS Sonoma (14): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Sequoia (15): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Tahoe (26): All 5 tests passed. Html Report (VSDrops) Download
⚠️ Tests on macOS Golden Gate (27): Tests skipped, incorrect beta version. Html Report (VSDrops) Download

Linux Build Verification

✅ Linux build succeeded

Pipeline on Agent
Hash: b95a064a214dc6ac86a79a3aba9ec2ef4d029e73 [PR build]

[Binding Creator] Enhance documentation for adding new frameworks and…

3f74d3c

… clarify Xtro checks

dalexsoto added this to the xcode27 milestone Jul 9, 2026

dalexsoto requested review from Copilot and rolfbjarne July 9, 2026 22:17

dalexsoto added the copilot label Jul 9, 2026

Copilot started reviewing on behalf of dalexsoto July 9, 2026 22:18 View session

dalexsoto commented Jul 9, 2026

View reviewed changes

Copilot AI reviewed Jul 9, 2026

View reviewed changes

dalexsoto commented Jul 9, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

rolfbjarne approved these changes Jul 10, 2026

View reviewed changes

Copilot started work on behalf of dalexsoto July 10, 2026 22:45 View session

Copilot finished work on behalf of dalexsoto July 10, 2026 22:47

Copilot started work on behalf of dalexsoto July 10, 2026 22:48 View session

Copilot finished work on behalf of dalexsoto July 10, 2026 22:49

This was referenced Jul 12, 2026

generate-frameworks-constants is not rebuilt when tools/common/Frameworks.cs changes #26052

Closed

[xtro] Report extra/unknown selectors (managed bindings with no native declaration) #26053

Closed

This comment has been minimized.

Sign in to view

Merge branch 'xcode27.0' into dev/alex/moreskillz

b95a064

This comment has been minimized.

Sign in to view

rolfbjarne approved these changes Jul 13, 2026

View reviewed changes

dalexsoto merged commit f0d5574 into xcode27.0 Jul 13, 2026
55 checks passed

dalexsoto deleted the dev/alex/moreskillz branch July 13, 2026 14:11

		> ⚠️ Xcode 27: `simctl create` dropped `--json`. mlaunch auto-creates the sim device via `simctl create … --json`, which now fails with `MT1008 … simctl: unrecognized option '--json'`. Workaround: pre-create the device with the exact name mlaunch expects so it finds it instead of creating it, e.g. `xcrun simctl create "iPhone 16 Pro - iOS 27.0" <devicetype-id> <runtime-id>`, then re-run mlaunch. (Environment-specific to Xcode 27 until mlaunch is updated.)

Uh oh!

Conversation

dalexsoto commented Jul 9, 2026

Uh oh!

dalexsoto Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

rolfbjarne Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

dalexsoto Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Jul 10, 2026

🔥 Failed to compute test summaries on VSTS: test results 🔥

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

rolfbjarne left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rolfbjarne Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Jul 12, 2026

🔥 Failed to compute test summaries on VSTS: test results 🔥

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Jul 12, 2026

❗ API diff for current PR / commit (Breaking changes)

✅ API diff vs stable

ℹ️ Generator diff

Uh oh!

This comment has been minimized.

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Jul 12, 2026

✅ [CI Build #5677708] Prepare .NET Release succeeded ✅

iOS

MacCatalyst

macOS

tvOS

Other

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Jul 12, 2026

🚀 [CI Build #b95a064] Test results 🚀

Test results

Tests counts

macOS tests

Linux Build Verification

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants