From 4eaccd9c8144849128f11de57a645afd286c77b1 Mon Sep 17 00:00:00 2001 From: Rolf Bjarne Kvinge Date: Tue, 5 May 2026 08:40:47 +0200 Subject: [PATCH 1/3] Update macios docs for our Xcode 26.4 release. --- docs/ios/building-apps/build-items.md | 34 +++++++++++ docs/ios/building-apps/build-properties.md | 66 +++++++++++----------- docs/ios/building-apps/build-targets.md | 32 ++++++++++- 3 files changed, 98 insertions(+), 34 deletions(-) diff --git a/docs/ios/building-apps/build-items.md b/docs/ios/building-apps/build-items.md index 00c3ee7..ff18c07 100644 --- a/docs/ios/building-apps/build-items.md +++ b/docs/ios/building-apps/build-items.md @@ -309,6 +309,40 @@ the `CollectAppManifestsDependsOn` property: ``` +## ReferenceNativeSymbol + +The item group `ReferenceNativeSymbol` can be used to specify how we should +handle a given native symbol: either ignore it, or ask the native linker to +keep it (by passing the symbol as `-u ...` or in a symbol file to the native +linker). + +There are two supported types of metadata: + +* `SymbolType`: either `ObjectiveCClass`, `Function` or `Field`. Used to + compute the complete native name of a symbol (for instance, the native + symbol for the Objective-C class `MyClass` is `_OBJC_CLASS_$_MyClass`, + while for a function `MyFunction` it's just `_MyFunction`. +* `SymbolMode`: either `Ignore` or not set. `Ignore` means to not pass the given + symbol to the native linker, the default is to do so. + +`SymbolType` is required, while `SymbolMode` isn't. + +Example symbol to keep: + +```xml + + + +``` + +Example symbol to ignore: + +```xml + + + +``` + ### SkipCodesignItems An item group that specifies files or directories in the app bundle that should not be signed. diff --git a/docs/ios/building-apps/build-properties.md b/docs/ios/building-apps/build-properties.md index 08f9a27..c93f44b 100644 --- a/docs/ios/building-apps/build-properties.md +++ b/docs/ios/building-apps/build-properties.md @@ -17,6 +17,12 @@ The full path to the `altool` tool. The default behavior is to use `xcrun altool`. +## ACToolPath + +The full path to the `actool` tool. + +The default behavior is to use `xcrun actool`. + ## AppBundleResourcePrefix The directory where resources are stored (this prefix will be removed when copying resources to the app bundle). @@ -344,6 +350,20 @@ Only applicable to macOS and Mac Catalyst projects. See [BuildIpa](#buildipa) for iOS and tvOS projects. +## Device + +Specifies which mobile device or emulator to target when using `dotnet run +--device ` or MSBuild targets that interact with devices (such as +`Run`, `Install`, or `Uninstall`). + +The value can be anything the command-line tools `simctl` or `devicectl` +accept for the device name; this is typically either the UDID or the name of +the device. For example, for the device `My iOS Device` with UDID `00001111-012301230123ABCD`, use +either `-p:Device="My iOS Device"` or `-p:Device=00001111-012301230123ABCD`. + +For more information about device selection, see the +[.NET SDK device selection specification](https://github.com/dotnet/sdk/blob/2b9fc02a265c735f2132e4e3626e94962e48bdf5/documentation/specs/dotnet-run-for-maui.md). + ## DeviceSpecificBuild If the build should be specific to the selected device. @@ -517,6 +537,12 @@ Default: true Where the generated source from the generator are saved. +## IBToolPath + +The full path to the `ibtool` tool. + +The default behavior is to use `xcrun ibtool`. + ## IncludeAllAppIcons Set the `IncludeAllAppIcons` property to true to automatically include all app @@ -1079,37 +1105,7 @@ Only applicable to macOS and Mac Catalyst apps. ## ReferenceNativeSymbol -The item group `ReferenceNativeSymbol` can be used to specify how we should -handle a given native symbol: either ignore it, or ask the native linker to -keep it (by passing the symbol as `-u ...` or in a symbol file to the native -linker). - -There are two supported types of metadata: - -* `SymbolType`: either `ObjectiveCClass`, `Function` or `Field`. Used to - compute the complete native name of a symbol (for instance, the native - symbol for the Objective-C class `MyClass` is `_OBJC_CLASS_$_MyClass`, - while for a function `MyFunction` it's just `_MyFunction`. -* `SymbolMode`: either `Ignore` or not set. `Ignore` means to not pass the given - symbol to the native linker, the default is to do so. - -`SymbolType` is required, while `SymbolMode` isn't. - -Example symbol to keep: - -```xml - - - -``` - -Example symbol to ignore: - -```xml - - - -``` +See [ReferenceNativeSymbol](build-items.md#referencenativesymbols) ## RequireLinkWithAttributeForObjectiveCClassSearch @@ -1291,6 +1287,12 @@ It's also possible to use a platform-specific property: * [macOSMinimumVersion](#macosminimumversion) * [MacCatalystMinimumVersion](#maccatalystminimumversion) +## TextureAtlasPath + +The full path to the `TextureAtlas` tool. + +The default behavior is to use `xcrun TextureAtlas`. + ## TrimMode Specifies the trimming granularity. @@ -1328,7 +1330,7 @@ The default trim mode depends on numerous factors, and may also change in the fu The current (as of .NET 9) default values are: -* iOS and iOS: `partial` when building for device, `copy` when building for the simulator. +* iOS and tvOS: `partial` when building for device, `copy` when building for the simulator. * macOS: always `copy`. * Mac Catalyst: `partial` when building for the `"Release"` configuration, `copy` otherwise. diff --git a/docs/ios/building-apps/build-targets.md b/docs/ios/building-apps/build-targets.md index fb548e6..86a0ff2 100644 --- a/docs/ios/building-apps/build-targets.md +++ b/docs/ios/building-apps/build-targets.md @@ -16,11 +16,39 @@ Builds the source code within a project and all dependencies. Removes all files generated by the build process. +## ComputeAvailableDevices + +Queries and returns a list of available iOS or tvOS devices and simulators that can be used with `dotnet run`. + +This target is called automatically by the .NET SDK's `dotnet run` command to +support device selection via the `--device` option. It returns a `@(Devices)` +item group where each device has the following metadata: + +- **Description**: The name of the device (e.g., "iPhone 16 - iOS 26.0" for simulators, "My iPhone 16" for physical devices) +- **Type**: Either "Device" or "Simulator" +- **OSVersion**: The OS version of the device +- **UDID**: The UDID of the device +- **RuntimeIdentifier**: The RuntimeIdentifier of the device + +For example, to list all available devices: + +```shell +$ dotnet build -t:ComputeAvailableDevices +``` + +This target is part of the [.NET SDK device selection specification](https://github.com/dotnet/sdk/blob/2b9fc02a265c735f2132e4e3626e94962e48bdf5/documentation/specs/dotnet-run-for-maui.md) and enables commands like: + +```shell +$ dotnet run --device UDID +``` + +Added in .NET 11. + ## Run Builds the source code within a project and all dependencies, and then deploys and runs it -on a default simulator/device. A specific deployment target can be set by using the `$(_DeviceName)` property. +on a default simulator/device. A specific deployment target can be set by using the `$(Device)` property. ```dotnetcli -dotnet build -t:Run project.csproj -p:_DeviceName=$(MY_DEVICE_UDID) +dotnet build -t:Run project.csproj -p:Device=$(MY_DEVICE_UDID) ``` From 3553b3a1259fd31d55ca39f96f0a0e1a2bbf062d Mon Sep 17 00:00:00 2001 From: Rolf Bjarne Kvinge Date: Tue, 5 May 2026 08:45:50 +0200 Subject: [PATCH 2/3] Fix typo --- docs/ios/building-apps/build-properties.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ios/building-apps/build-properties.md b/docs/ios/building-apps/build-properties.md index c93f44b..c676b36 100644 --- a/docs/ios/building-apps/build-properties.md +++ b/docs/ios/building-apps/build-properties.md @@ -1105,7 +1105,7 @@ Only applicable to macOS and Mac Catalyst apps. ## ReferenceNativeSymbol -See [ReferenceNativeSymbol](build-items.md#referencenativesymbols) +See [ReferenceNativeSymbol](build-items.md#referencenativesymbol) ## RequireLinkWithAttributeForObjectiveCClassSearch From 4b3c115ea95ade85306f56d931222e418af1c829 Mon Sep 17 00:00:00 2001 From: Rolf Bjarne Kvinge Date: Tue, 5 May 2026 18:52:44 +0200 Subject: [PATCH 3/3] Reverts --- docs/ios/building-apps/build-properties.md | 8 +++----- docs/ios/building-apps/build-targets.md | 4 ++-- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/ios/building-apps/build-properties.md b/docs/ios/building-apps/build-properties.md index c676b36..93bf58b 100644 --- a/docs/ios/building-apps/build-properties.md +++ b/docs/ios/building-apps/build-properties.md @@ -352,14 +352,12 @@ See [BuildIpa](#buildipa) for iOS and tvOS projects. ## Device -Specifies which mobile device or emulator to target when using `dotnet run ---device ` or MSBuild targets that interact with devices (such as -`Run`, `Install`, or `Uninstall`). +Specifies which mobile device or simulator to target when using `dotnet run --device ` or MSBuild targets that interact with devices (such as `Run`, `Install`, or `Uninstall`). The value can be anything the command-line tools `simctl` or `devicectl` accept for the device name; this is typically either the UDID or the name of -the device. For example, for the device `My iOS Device` with UDID `00001111-012301230123ABCD`, use -either `-p:Device="My iOS Device"` or `-p:Device=00001111-012301230123ABCD`. +the device. For example, for the device `My iOS Device` with UDID `0000-aaaabbbb`, use +either `-p:Device="My iOS Device"` or `-p:Device=0000-aaaabbbb`. For more information about device selection, see the [.NET SDK device selection specification](https://github.com/dotnet/sdk/blob/2b9fc02a265c735f2132e4e3626e94962e48bdf5/documentation/specs/dotnet-run-for-maui.md). diff --git a/docs/ios/building-apps/build-targets.md b/docs/ios/building-apps/build-targets.md index 86a0ff2..fbf0abf 100644 --- a/docs/ios/building-apps/build-targets.md +++ b/docs/ios/building-apps/build-targets.md @@ -47,8 +47,8 @@ Added in .NET 11. ## Run Builds the source code within a project and all dependencies, and then deploys and runs it -on a default simulator/device. A specific deployment target can be set by using the `$(Device)` property. +on a default simulator/device. A specific deployment target can be set by using the `$(Device)` property. ```dotnetcli -dotnet build -t:Run project.csproj -p:Device=$(MY_DEVICE_UDID) +dotnet build -t:Run project.csproj -p:Device= ```