[tools/msbuild] Add InlineDlfcnMethodsStep as an opt-in custom linker step by rolfbjarne · Pull Request #24888 · dotnet/macios

rolfbjarne · 2026-03-12T12:31:23Z

Add a new custom linker step that replaces runtime Dlfcn.dlsym calls with
direct native symbol lookups via P/Invokes to __Internal. This improves
startup performance and app size, and ensures the native linker can see symbol
references that would otherwise only be resolved at runtime.

Two modes are supported, controlled by the InlineDlfcnMethods MSBuild
property:

strict: inlines all calls to ObjCRuntime.Dlfcn APIs.
compatibility: only inlines calls that reference symbols from [Field]
attributes.

Post-trimming MSBuild targets ensure native code is only generated for symbols
that survive trimming (ILTrim or NativeAOT):

_CollectPostILTrimInformation: scans trimmed assemblies for surviving
inlined dlfcn P/Invokes, with per-assembly caching for incremental builds.
_CollectPostNativeAOTTrimInformation: reads unresolved symbols from the
NativeAOT object file or static library and filters for inlined dlfcn symbols.
_PostTrimmingProcessing: generates native C code for surviving symbols and
adds it to the native link inputs.

Extends MachO.cs with LC_SYMTAB parsing to read unresolved symbols from both
Mach-O object files and static libraries.

Contributes towards #17693.

… step Add a new custom linker step that replaces runtime `Dlfcn.dlsym` calls with direct native symbol lookups via P/Invokes to `__Internal`. This improves startup performance and app size, and ensures the native linker can see symbol references that would otherwise only be resolved at runtime. Two modes are supported, controlled by the `InlineDlfcnMethods` MSBuild property: * `strict`: inlines all calls to `ObjCRuntime.Dlfcn` APIs. * `compatibility`: only inlines calls that reference symbols from `[Field]` attributes. Post-trimming MSBuild targets ensure native code is only generated for symbols that survive trimming (ILTrim or NativeAOT): * `_CollectPostILTrimInformation`: scans trimmed assemblies for surviving inlined dlfcn P/Invokes, with per-assembly caching for incremental builds. * `_CollectPostNativeAOTTrimInformation`: reads unresolved symbols from the NativeAOT object file or static library and filters for inlined dlfcn symbols. * `_PostTrimmingProcessing`: generates native C code for surviving symbols and adds it to the native link inputs. Extends `MachO.cs` with LC_SYMTAB parsing to read unresolved symbols from both Mach-O object files and static libraries. Contributes towards #17693.

Copilot

Pull request overview

Adds an opt-in build+linker pipeline to inline ObjCRuntime.Dlfcn symbol lookups into direct __Internal P/Invokes, with post-trimming symbol discovery (ILTrim + NativeAOT) and native C code generation to keep only surviving symbol references.

Changes:

Introduces InlineDlfcnMethodsStep + GenerateInlinedDlfcnNativeCodeStep and corresponding InlineDlfcnMethods MSBuild property wiring.
Adds post-trimming MSBuild tasks/targets to detect surviving inlined symbols (ILTrim scanning + NativeAOT unresolved-symbol parsing) and generate/compile native glue code.
Extends Mach-O parsing to read unresolved symbols and adds/adjusts tests and test variations for the new modes.

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tools/mtouch/Errors.resx	Adds new MX2254–MX2257 warning strings for the inlining step.
tools/mtouch/Errors.designer.cs	Regenerated resource accessors for new MX225x entries.
tools/linker/MonoTouch.Tuner/ProcessExportedFields.cs	Collects `[Field]` symbol names for compatibility mode.
tools/linker/MonoTouch.Tuner/ListExportedSymbols.cs	Skips adding required field symbols when dlfcn inlining is enabled.
tools/dotnet-linker/Steps/InlineDlfcnMethodsStep.cs	New custom linker step that rewrites Dlfcn calls into generated helpers + P/Invokes.
tools/dotnet-linker/Steps/GenerateInlinedDlfcnNativeCodeStep.cs	Emits a symbol list file for later post-trimming MSBuild steps.
tools/dotnet-linker/LinkerConfiguration.cs	Adds `InlineDlfcnMethods` configuration and symbol tracking collections.
tools/dotnet-linker/AppBundleRewriter.cs	Adds type/method references used by the new inlining step.
tools/common/MachO.cs	Adds LC_SYMTAB parsing and unresolved-symbol extraction for Mach-O/static libraries.
tests/xharness/Jenkins/TestVariationsFactory.cs	Adds new CI variations to exercise inline-dlfcn modes (incl. NativeAOT).
tests/monotouch-test/ObjCRuntime/DlfcnTest.cs	Adds tests for `[Field]`-backed constants and adjusts behavior under strict mode.
tests/monotouch-test/Foundation/AttributedStringTest.cs	Removes legacy field-absence test that would conflict with new behavior.
tests/monotouch-test/CoreFoundation/ProxyTest.cs	Removes legacy field-absence test that would conflict with new behavior.
tests/common/test-variations.csproj	Adds `inline-dlfcn-methods-compat` and `inline-dlfcn-methods-strict` test variations.
msbuild/Xamarin.MacDev.Tasks/Tasks/PostTrimmingProcessing.cs	Generates native C glue for surviving symbols and outputs compile/link items.
msbuild/Xamarin.MacDev.Tasks/Tasks/ComputeNativeAOTSurvivingNativeSymbols.cs	Filters NativeAOT unresolved symbols to determine surviving inlined-dlfcn symbols.
msbuild/Xamarin.MacDev.Tasks/Tasks/CompileNativeCode.cs	Ensures output directory exists before compiling native files.
msbuild/Xamarin.MacDev.Tasks/Tasks/CollectUnresolvedNativeSymbols.cs	New task to extract unresolved symbols from a NativeAOT static library.
msbuild/Xamarin.MacDev.Tasks/Tasks/CollectPostILTrimInformation.cs	New task to scan trimmed assemblies and cache surviving inlined-dlfcn P/Invokes.
dotnet/targets/Xamarin.Shared.Sdk.targets	Wires property defaults, custom linker steps, and post-trimming targets into the SDK.
docs/code/native-symbols.md	New doc explaining the native symbol pipeline and InlineDlfcnMethods modes.
docs/building-apps/build-properties.md	Documents the new `InlineDlfcnMethods` MSBuild property and defaults.
.github/copilot-instructions.md	Adds MSBuild guidance (DeviceSpecificIntermediateOutputPath) to repo copilot instructions.

Files not reviewed (1)

tools/mtouch/Errors.designer.cs: Language not supported

You can also share your feedback on Copilot code review. Take the survey.

tools/mtouch/Errors.resx

tests/xharness/Jenkins/TestVariationsFactory.cs

msbuild/Xamarin.MacDev.Tasks/Tasks/CollectUnresolvedNativeSymbols.cs

msbuild/Xamarin.MacDev.Tasks/Tasks/CompileNativeCode.cs

Copilot · 2026-03-12T12:38:00Z

tools/dotnet-linker/Steps/InlineDlfcnMethodsStep.cs

+			// Handle Dlfcn functions of the form (libraryHandle, symbolName)
+			if (mr.Parameters.Count == 2 && mr.Parameters [0].ParameterType.FullName == "System.IntPtr" && mr.Parameters [1].ParameterType.FullName == "System.String") {
+				if (instr.Previous.OpCode != OpCodes.Ldstr) {
+					Driver.Log ("Unknown Dlfcn code sequence for: {0} called in {1}", FormatMethod (mr), FormatMethod (method));


This code path logs an unknown Dlfcn IL pattern but does not emit a warning (unlike other pattern mismatches later in the method). For an opt-in transformation step, consider reporting MX2255 here as well so users understand why a call was not inlined (and can share the exact method/pattern in bug reports).

Suggested change

Driver.Log ("Unknown Dlfcn code sequence for: {0} called in {1}", FormatMethod (mr), FormatMethod (method));

Driver.Log ("MX2255: Unknown Dlfcn code sequence for: {0} called in {1}", FormatMethod (mr), FormatMethod (method));

Copilot · 2026-03-12T12:38:00Z

tools/dotnet-linker/Steps/InlineDlfcnMethodsStep.cs

+
+				// In compatibility mode, only inline symbols from [Field] attributes.
+				var ldstr = instr.Previous;
+				var symbolName = (string) ldstr.Operand!;


There are several uses of the null-forgiving operator when reading ldstr.Operand (for example casting (string) ldstr.Operand!). This can hide invalid IL patterns and may produce NullReferenceException/InvalidCastException during linking. Prefer pattern-matching the operand (ldstr.Operand is string symbolName) and warning (MX2255) when it isn't a string.

Suggested change

var symbolName = (string) ldstr.Operand!;

if (ldstr.Operand is not string symbolName) {

Report (ErrorHelper.CreateWarning (Configuration.Application, 9003 /* Unknown or unsupported Dlfcn pattern: '{0}' in method '{1}'. The call will not be inlined. Please file an issue at https://github.com/dotnet/macios/issues/new. */, method, Errors.MX2255, FormatMethod (mr), FormatMethod (method)));

continue;

}

Copilot · 2026-03-12T12:38:00Z

tools/dotnet-linker/Steps/InlineDlfcnMethodsStep.cs

+						Report (ErrorHelper.CreateWarning (Configuration.Application, 9003 /* Unknown or unsupported Dlfcn pattern: '{0}' in method '{1}'. The call will not be inlined. Please file an issue at https://github.com/dotnet/macios/issues/new. */, method, Errors.MX2255, FormatMethod (mr), FormatMethod (method)));
+						continue;
+					}
+					var returnType = gim.GenericArguments [0];
+					if (returnType.IsGenericInstance) {
+						Report (ErrorHelper.CreateWarning (Configuration.Application, 9004 /* Unknown or unsupported Dlfcn pattern: '{0}' in method '{1}'. The call will not be inlined. Please file an issue at https://github.com/dotnet/macios/issues/new. */, method, Errors.MX2255, FormatMethod (mr), FormatMethod (method)));


These warnings use codes 9000-9006 while emitting the MX2255 message text. This makes the warning IDs inconsistent with the resources added for this step (225x in Errors.resx) and harder to discover/filter. Consider using 2255 for these cases (or adding distinct MX900x resources if different warning IDs are intentional).

Suggested change

Report (ErrorHelper.CreateWarning (Configuration.Application, 9003 /* Unknown or unsupported Dlfcn pattern: '{0}' in method '{1}'. The call will not be inlined. Please file an issue at https://github.com/dotnet/macios/issues/new. */, method, Errors.MX2255, FormatMethod (mr), FormatMethod (method)));

continue;

}

var returnType = gim.GenericArguments [0];

if (returnType.IsGenericInstance) {

Report (ErrorHelper.CreateWarning (Configuration.Application, 9004 /* Unknown or unsupported Dlfcn pattern: '{0}' in method '{1}'. The call will not be inlined. Please file an issue at https://github.com/dotnet/macios/issues/new. */, method, Errors.MX2255, FormatMethod (mr), FormatMethod (method)));

Report (ErrorHelper.CreateWarning (Configuration.Application, 2255 /* Unknown or unsupported Dlfcn pattern: '{0}' in method '{1}'. The call will not be inlined. Please file an issue at https://github.com/dotnet/macios/issues/new. */, method, Errors.MX2255, FormatMethod (mr), FormatMethod (method)));

continue;

}

var returnType = gim.GenericArguments [0];

if (returnType.IsGenericInstance) {

Report (ErrorHelper.CreateWarning (Configuration.Application, 2255 /* Unknown or unsupported Dlfcn pattern: '{0}' in method '{1}'. The call will not be inlined. Please file an issue at https://github.com/dotnet/macios/issues/new. */, method, Errors.MX2255, FormatMethod (mr), FormatMethod (method)));

Replace the string-based InlineDlfcnMethods property with a strongly-typed InlineDlfcnMethodsMode enum with Disabled, Strict, and Compat values. The parser accepts 'compatibility' as an alias for Compat to maintain compatibility with existing MSBuild property values. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

- Replace Driver.Log with Report(MX2255 warning) for unknown Dlfcn patterns - Replace (string) ldstr.Operand! casts with pattern matching (is not string) - Replace all 900x warning codes with consistent 2255 code Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

vs-mobiletools-engineering-service2 · 2026-03-18T16:58:31Z

✅ [CI Build #7a40438] Build passed (Build packages) ✅

Pipeline on Agent
Hash: 7a40438cb4756f368554dec652d659d4d22d63da [PR build]

vs-mobiletools-engineering-service2 · 2026-03-18T17:10:03Z

✅ [PR Build #7a40438] Build passed (Detect API changes) ✅

Pipeline on Agent
Hash: 7a40438cb4756f368554dec652d659d4d22d63da [PR build]

vs-mobiletools-engineering-service2 · 2026-03-18T17:12:52Z

🔥 Failed to compare API and create generator diff 🔥

** Error: Working directory isn't clean - check build log for more information.

Pipeline on Agent
Hash: 7a40438cb4756f368554dec652d659d4d22d63da [PR build]

vs-mobiletools-engineering-service2 · 2026-03-18T17:37:02Z

✅ [CI Build #7a40438] Build passed (Build macOS tests) ✅

Pipeline on Agent
Hash: 7a40438cb4756f368554dec652d659d4d22d63da [PR build]

vs-mobiletools-engineering-service2 · 2026-03-18T18:27:53Z

🔥 [CI Build #7a40438] Test results 🔥

Test results

❌ Tests failed on VSTS: test results

0 tests crashed, 5 tests failed, 157 tests passed.

Failures

❌ linker tests

1 tests failed, 43 tests passed.

Failed tests

trimmode link/iOS - simulator/Debug: LaunchFailure

Html Report (VSDrops) Download

❌ monotouch tests (iOS)

1 tests failed, 13 tests passed.

Failed tests

monotouch-test/iOS - simulator/Release (NativeAOT, .NET 11 defaults): LaunchFailure

Html Report (VSDrops) Download

❌ monotouch tests (macOS)

1 tests failed, 11 tests passed.

Failed tests

monotouch-test/macOS/Debug (static registrar, ARM64): BuildFailure

Html Report (VSDrops) Download

❌ monotouch tests (tvOS)

2 tests failed, 12 tests passed.

Failed tests

monotouch-test/tvOS - simulator/Release (strict inline dlfcn): BuildFailure
monotouch-test/tvOS - simulator/Release (NativeAOT, .NET 11 defaults): BuildFailure

Html Report (VSDrops) Download

Successes

✅ 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 6 tests passed. Html Report (VSDrops) Download
✅ monotouch (MacCatalyst): All 15 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 Monterey (12): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Ventura (13): All 5 tests passed. Html Report (VSDrops) Download
✅ 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

Pipeline on Agent
Hash: 7a40438cb4756f368554dec652d659d4d22d63da [PR build]

rolfbjarne requested a review from Copilot March 12, 2026 12:31

rolfbjarne added the copilot label Mar 12, 2026

Copilot started reviewing on behalf of rolfbjarne March 12, 2026 12:31 View session

rolfbjarne mentioned this pull request Mar 12, 2026

[net11.0] [tools/msbuild] Add InlineDlfcnMethodsStep as an opt-in custom linker step #24889

Draft

Copilot AI reviewed Mar 12, 2026

View reviewed changes

Auto-format source code

2e48a39

This comment has been minimized.

Sign in to view

rolfbjarne and others added 3 commits March 16, 2026 12:43

sqinlinedlfcn

583b796

Merge remote-tracking branch 'origin/main' into dev/rolf/inline-dlfcn

65a47a5

This comment has been minimized.

Sign in to view

rolfbjarne and others added 3 commits March 17, 2026 09:23

Only compile when connected.

f60e676

Update tools/mtouch/Errors.resx

ce4906b

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update tests/xharness/Jenkins/TestVariationsFactory.cs

4925f35

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

This comment has been minimized.

Sign in to view

rolfbjarne and others added 2 commits March 17, 2026 14:15

IOSurface is now working in the simulator.

f74b4fd

This comment has been minimized.

Sign in to view

rolfbjarne mentioned this pull request Mar 18, 2026

Migrate GenerateReferencesStep from ILLink pipeline #24914

Draft

Merge remote-tracking branch 'origin/main' into dev/rolf/inline-dlfcn

7a40438

	Driver.Log ("Unknown Dlfcn code sequence for: {0} called in {1}", FormatMethod (mr), FormatMethod (method));
	Driver.Log ("MX2255: Unknown Dlfcn code sequence for: {0} called in {1}", FormatMethod (mr), FormatMethod (method));

Conversation

rolfbjarne commented Mar 12, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

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.

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.

vs-mobiletools-engineering-service2 commented Mar 18, 2026

✅ [CI Build #7a40438] Build passed (Build packages) ✅

Uh oh!

vs-mobiletools-engineering-service2 commented Mar 18, 2026

✅ [PR Build #7a40438] Build passed (Detect API changes) ✅

Uh oh!

vs-mobiletools-engineering-service2 commented Mar 18, 2026

Uh oh!

vs-mobiletools-engineering-service2 commented Mar 18, 2026

✅ [CI Build #7a40438] Build passed (Build macOS tests) ✅

Uh oh!

vs-mobiletools-engineering-service2 commented Mar 18, 2026

🔥 [CI Build #7a40438] Test results 🔥

Test results

Failures

❌ linker tests

Failed tests

❌ monotouch tests (iOS)

Failed tests

❌ monotouch tests (macOS)

Failed tests