From 719175e54aeb9a1a6d0113520547c8c5ef32554d Mon Sep 17 00:00:00 2001 From: Rolf Bjarne Kvinge Date: Tue, 11 Nov 2025 13:35:21 +0100 Subject: [PATCH 1/3] Update the recommended way of choosing which Xcode to use. We're deprecating the MD_APPLE_SDK_ROOT variable and the setting files. References: * https://github.com/dotnet/macios/pull/24021 * https://github.com/dotnet/macios-devtools/pull/140 --- docs/macios/includes/choose-xcode-version.md | 20 ++++++++++---------- docs/troubleshooting.md | 9 +++++---- 2 files changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/macios/includes/choose-xcode-version.md b/docs/macios/includes/choose-xcode-version.md index da552b356..fb3f2efaf 100644 --- a/docs/macios/includes/choose-xcode-version.md +++ b/docs/macios/includes/choose-xcode-version.md @@ -5,18 +5,18 @@ ms.date: 03/19/2024 ## Build with a specific version of Xcode -If you have multiple versions of Xcode installed on your Mac, it's possible to specify which Xcode version should be used when building your app. There are a number of approaches that can be used to accomplish this, but the recommended approach is to set the `MD_APPLE_SDK_ROOT` environment variable to the path of the Xcode version. +If you have multiple versions of Xcode installed on your Mac, it's possible to specify which Xcode version should be used when building your app. There are a number of approaches that can be used to accomplish this, but there are two recommended approaches: -> [!WARNING] -> Using `xcode-select -s` to set the version of Xcode to use isn't recommended. +1. Use `sudo xcode-select --switch ...` to choose the system's currently selected version of Xcode (this requires admin credentials). It's also possible to do this from inside Xcode (Settings -> Locations -> Command Line Tools). -To set the `MD_APPLE_SDK_ROOT` environment variable for the duration of the current terminal session: +1. Use the `DEVELOPER_DIR` environment variable for the duration of the current terminal session: -1. Open the **Terminal** application. -1. Type the following command, substituting in your version of Xcode, and press Enter: + 1. Open the **Terminal** application. + 1. Type the following command, substituting in your version of Xcode, and press Enter: - ```zsh - export MD_APPLE_SDK_ROOT=/Applications/Xcode_14.1.0.app - ``` + ```zsh + export DEVELOPER_DIR=/Applications/Xcode_14.1.0.app + ``` + + If you want to set this environment variable permanently, you can add the `export` command to your shell profile, such as *.zprofile*. -If you want to set this environment variable permanently, you can add the `export` command to your shell profile, such as *.zprofile*. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index f5485a353..ac8a73aba 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -170,14 +170,15 @@ xcrun: error: unable to find utility "dsymutil", not a developer tool or in PATH When building an app, .NET for iOS and .NET for Mac Catalyst use the following process to determine which version of Xcode to use: -1. If the `MD_APPLE_SDK_ROOT` environment variable is set, use its value. -1. If the *~/Library/Preferences/Xamarin/Settings.plist* file exists, use the value defined inside it. +1. If the `MD_APPLE_SDK_ROOT` environment variable is set, use its value. _This environment variable will be deprecated in a future release; do not use it._ +1. If the *~/Library/Preferences/Xamarin/Settings.plist* or *~/Library/Preferences/maui/Settings.plist* file exists, use the value defined inside it. _These files will be deprecated in a future release; do not use them._ 1. Use the value of `xcode-select -p`. 1. Use `/Applications/Xcode.app`. -Therefore, the recommended approach to specifying the location of Xcode on your machine is to set the `MD_APPLE_SDK_ROOT` environment variable to the path of the Xcode version. For more information, see [Build with a specific version of Xcode](~/ios/cli.md). +The recommended approach to specify the location of Xcode on yoru machine is to: -You can then safely delete *~/Library/Preferences/Xamarin/Settings.plist* from your machine. +1. Delete *~/Library/Preferences/Xamarin/Settings.plist* or *~/Library/Preferences/maui/Settings.plist* files (if they exist). +2. Either use `xcode-select --switch ...` to select the system's version of Xcode, or set the `DEVELOPER_DIR` environment variable to the path of Xcode. For more information, see [Build with a specific version of Xcode](~/ios/cli.md). ## Diagnose issues in Blazor Hybrid apps From b68026cca4e17519c87b22c8aaae1d50856ac9d2 Mon Sep 17 00:00:00 2001 From: Rolf Bjarne Kvinge Date: Tue, 11 Nov 2025 13:43:05 +0100 Subject: [PATCH 2/3] Fix typo --- docs/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index ac8a73aba..8e3d21f98 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -175,7 +175,7 @@ When building an app, .NET for iOS and .NET for Mac Catalyst use the following p 1. Use the value of `xcode-select -p`. 1. Use `/Applications/Xcode.app`. -The recommended approach to specify the location of Xcode on yoru machine is to: +The recommended approach to specify the location of Xcode on your machine is to: 1. Delete *~/Library/Preferences/Xamarin/Settings.plist* or *~/Library/Preferences/maui/Settings.plist* files (if they exist). 2. Either use `xcode-select --switch ...` to select the system's version of Xcode, or set the `DEVELOPER_DIR` environment variable to the path of Xcode. For more information, see [Build with a specific version of Xcode](~/ios/cli.md). From 6bfaa9150888b422aa674408faba7dd131b3754f Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Tue, 11 Nov 2025 14:20:15 +0100 Subject: [PATCH 3/3] Update docs/macios/includes/choose-xcode-version.md --- docs/macios/includes/choose-xcode-version.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/macios/includes/choose-xcode-version.md b/docs/macios/includes/choose-xcode-version.md index fb3f2efaf..1743357f0 100644 --- a/docs/macios/includes/choose-xcode-version.md +++ b/docs/macios/includes/choose-xcode-version.md @@ -19,4 +19,3 @@ If you have multiple versions of Xcode installed on your Mac, it's possible to s ``` If you want to set this environment variable permanently, you can add the `export` command to your shell profile, such as *.zprofile*. -