[tools/msbuild] Add support for mergeable libraries. Fixes #20262. by rolfbjarne · Pull Request #24710 · dotnet/macios

rolfbjarne · 2026-02-13T15:11:20Z

Summary

Adds MSBuild support for mergeable libraries by detecting mergeable framework/dylib metadata and stripping it when requested during native reference processing.

This includes:

a new StripMergeableLibraries build property
a StripMergeableLibraryMetadata task wired into native reference handling
Mach-O support for detecting mergeable-library atom info
tests for mergeable frameworks and dylibs across Apple platforms
documentation for the new build property

Testing

Added unit/task coverage for mergeable library stripping behavior.
Added pack/project test coverage for mergeable framework and dylib references.

Fixes #20262.

Add support for detecting and stripping mergeable library metadata (LC_ATOM_INFO) from frameworks embedded in app bundles. Mergeable libraries are dylibs/frameworks built with -make_mergeable that contain extra static linking metadata, roughly doubling their size. When used as dynamic libraries, this metadata is unnecessary. Changes: - Add LC_ATOM_INFO (0x36) to LoadCommands enum in MachO.cs - Add HasAtomInfo property and IsMergeableLibrary() method for detection - Add -no_atom_info flag to SymbolStrip task when stripping frameworks - Add tests for detection and stripping of mergeable libraries Fixes #20262

Add a new StripMergeableLibraries MSBuild property that controls whether LC_ATOM_INFO (mergeable library metadata) is stripped from frameworks during symbol stripping. The property defaults to the value of Optimize, so Release builds strip the metadata (reducing app size) while Debug builds preserve it. Changes: - SymbolStrip task: add StripMergeableLibraries property, conditionally pass -no_atom_info to strip. - Xamarin.Shared.props: define StripMergeableLibraries defaulting to Optimize. - Xamarin.Shared.targets: pass StripMergeableLibraries to SymbolStrip. - test-libraries: add XMergeableTest framework built with -Wl,-make_mergeable, including plists for all RIDs. - NativeMergeableFrameworkReferencesApp: test app that references the mergeable framework. - ProjectTest.cs: add test cases for building the mergeable framework app and verifying atom info stripping behavior. - MergeableLibraryTests.cs: add test for preserving atom info when StripMergeableLibraries is false.

Add a binding project that embeds the XMergeableTest mergeable framework, with pack tests verifying the nupkg contains the framework correctly. - bindings-framework-test/dotnet-mergeable: binding project referencing XMergeableTest.framework with IsBindingProject=true. - PackTest.cs: BindingMergeableFrameworksProject test verifying dotnet pack produces correct nupkg structure with the mergeable framework. - ProjectTest.cs: BuildNativeMergeableFrameworkReferencesApp_AtomInfoStripping test verifying atom info is stripped when Optimize=true and preserved when Optimize=false.

Add a new StripMergeableLibraryMetadata MSBuild task and target that strips LC_ATOM_INFO from frameworks in the app bundle. This runs independently of the regular symbol stripping (_NativeStripFiles), which is disabled for simulator builds, debug builds, and macOS/MacCatalyst. The new task: - Scans the app bundle's Frameworks directory for .framework directories - Checks each framework executable with MachO.IsMergeableLibrary() - Only strips frameworks that actually have LC_ATOM_INFO - Runs strip -no_atom_info on matching frameworks This ensures mergeable library metadata is stripped when StripMergeableLibraries=true (i.e. Optimize=true), regardless of whether NoSymbolStrip is enabled.

- Remove RuntimeIdentifier from NativeMergeableFrameworkReferencesApp platform projects (default values are chosen automatically). - Add NativeMergeableDylibReferencesApp test app referencing a standalone mergeable dylib (libMergeableFramework.dylib). - Add libMergeableFramework.dylib build rule in test-libraries Makefile. - Extend StripMergeableLibraryMetadata task to also scan dylib directories (e.g. MonoBundle) for mergeable libraries. - Add BuildNativeMergeableDylibReferencesApp_AtomInfoStripping test verifying dylib atom info stripping behavior. All 8 integration tests and 10 unit tests pass.

…braries

Fix the optimized-build default, pass StripPath through to the metadata stripping task, scan the app bundle root for standalone dylibs, and handle missing fat-file entries safely. Also restore the missing MachO closing brace reported by CI. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 35b9fddd-0b2f-4427-9990-90225546e53a

…braries

Pass -S when removing atom info so strip preserves symbols needed by indirect symbol table entries in other architecture slices. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…braries

Copilot

🟡 Changes recommended

The new MergeableLibraryTests invoke xcrun without an OS guard, which can break test runs on non-macOS agents.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

tests/dotnet/UnitTests/ProjectTest.cs:690

💡 suggestion: Same as above for the dylib variant: only macOS/Mac Catalyst are covered. Adding iOS/tvOS simulator cases would strengthen confidence that mergeable dylibs are stripped correctly in mobile app bundles too.

		[Test]
		[TestCase (ApplePlatform.MacOSX, "osx-arm64", true)] // Optimize=true should strip atom info
		[TestCase (ApplePlatform.MacOSX, "osx-arm64", false)] // Optimize=false should preserve atom info
		[TestCase (ApplePlatform.MacCatalyst, "maccatalyst-arm64", true)]
		[TestCase (ApplePlatform.MacCatalyst, "maccatalyst-arm64", false)]

Files reviewed: 39/39 changed files
Comments generated: 3
Review effort level: Lite

Clarify dylib handling and skip unchanged libraries using per-library stamps. Register generated stamps as FileWrites for incremental cleanup. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 35b9fddd-0b2f-4427-9990-90225546e53a

Use zero-length stamp files with deterministic names without computing a SHA. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 35b9fddd-0b2f-4427-9990-90225546e53a

…braries

Hash each absolute library path before creating its incremental stamp file. This keeps stamp names deterministic and unique without exceeding the filesystem's per-component length limit for deeply nested app bundles. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…braries

vs-mobiletools-engineering-service2 · 2026-09-07T18:00:42Z

✅ API diff for current PR / commit

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 )

✅ 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: ab786e188a59a195dfd5baa4db0cfc7525978e66 [PR build]

vs-mobiletools-engineering-service2 · 2026-09-07T20:08:09Z

🚀 [CI Build #ab786e1] Test results 🚀

Test results

✅ All tests passed on VSTS: test results.

🎉 All 264 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. 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 7 tests passed. Html Report (VSDrops) Download
✅ linker (iOS): All 31 tests passed. Html Report (VSDrops) Download
✅ linker (MacCatalyst): All 31 tests passed. Html Report (VSDrops) Download
✅ linker (macOS): All 21 tests passed. Html Report (VSDrops) Download
✅ linker (tvOS): All 31 tests passed. Html Report (VSDrops) Download
✅ monotouch (iOS): All 25 tests passed. Html Report (VSDrops) Download
✅ monotouch (MacCatalyst): All 25 tests passed. Html Report (VSDrops) Download
✅ monotouch (macOS): All 20 tests passed. Html Report (VSDrops) Download
✅ monotouch (tvOS): All 25 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

Linux Build Verification

✅ Linux build succeeded

Pipeline on Agent
Hash: ab786e188a59a195dfd5baa4db0cfc7525978e66 [PR build]

rolfbjarne and others added 4 commits February 12, 2026 17:25

Auto-format source code

9ebf2af

This comment has been minimized.

Sign in to view

rolfbjarne added the copilot label Feb 16, 2026

rolfbjarne added 4 commits February 17, 2026 11:21

[tests] Use arm64 runtime identifiers in mergeable library tests

2c4267d

Merge remote-tracking branch 'origin/main' into dev/rolf/mergeable-li…

c5264a1

…braries

This comment has been minimized.

Sign in to view

rolfbjarne and others added 2 commits September 3, 2026 07:18

Merge remote-tracking branch 'origin/main' into dev/rolf/mergeable-li…

c8cd8fe

…braries

This comment has been minimized.

Sign in to view

rolfbjarne and others added 2 commits September 4, 2026 10:01

[msbuild] Fix stripping universal mergeable dylibs

d2bb947

Pass -S when removing atom info so strip preserves symbols needed by indirect symbol table entries in other architecture slices. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Merge remote-tracking branch 'origin/main' into dev/rolf/mergeable-li…

c312fa8

…braries

This comment has been minimized.

Sign in to view

rolfbjarne requested a lite review from Copilot September 4, 2026 14:02

Copilot started reviewing on behalf of rolfbjarne September 4, 2026 14:02 View session

Copilot AI reviewed Sep 4, 2026

View reviewed changes

Comment thread tests/msbuild/Xamarin.MacDev.Tasks.Tests/TaskTests/MergeableLibraryTests.cs

Comment thread msbuild/Xamarin.MacDev.Tasks/Tasks/SymbolStrip.cs Outdated

Comment thread tests/dotnet/UnitTests/ProjectTest.cs

rolfbjarne commented Sep 4, 2026

View reviewed changes

Comment thread msbuild/Xamarin.Shared/Xamarin.Shared.targets

Comment thread tests/msbuild/Xamarin.MacDev.Tasks.Tests/TaskTests/MergeableLibraryTests.cs

Comment thread tests/dotnet/UnitTests/ProjectTest.cs

rolfbjarne and others added 3 commits September 4, 2026 17:47

Simplify mergeable library stamps

ce1c8a1

Use zero-length stamp files with deterministic names without computing a SHA. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 35b9fddd-0b2f-4427-9990-90225546e53a

Merge remote-tracking branch 'origin/main' into dev/rolf/mergeable-li…

729ba3d

…braries

This comment has been minimized.

Sign in to view

Merge branch 'main' into dev/rolf/mergeable-libraries

8b80584

rolfbjarne enabled auto-merge (squash) September 7, 2026 11:17

rolfbjarne added the ready-to-review This PR is ready to review/merge. label Sep 7, 2026

dalexsoto previously approved these changes Sep 7, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

rolfbjarne removed the ready-to-review This PR is ready to review/merge. label Sep 7, 2026

rolfbjarne and others added 2 commits September 7, 2026 18:30

Merge remote-tracking branch 'origin/main' into dev/rolf/mergeable-li…

ab786e1

…braries

rolfbjarne dismissed dalexsoto’s stale review via ab786e1 September 7, 2026 17:21

Uh oh!

Conversation

rolfbjarne commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Suppressed comments (1)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Sep 7, 2026

✅ API diff for current PR / commit

✅ API diff vs stable

ℹ️ Generator diff

Uh oh!

vs-mobiletools-engineering-service2 commented Sep 7, 2026

🚀 [CI Build #ab786e1] Test results 🚀

Test results

Tests counts

macOS tests

Linux Build Verification

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rolfbjarne commented Feb 13, 2026 •

edited

Loading