Make it clear you can install multiple versions (#38919)

* Make it clear you can install multiple versions

* more clarifications

* fix link

docs/core/install/how-to-detect-installed-versions.md

@@ -95,20 +95,20 @@ Microsoft.WindowsDesktop.App 8.0.0 [C:\Program Files\dotnet\shared\Microsoft.Win
 ::: zone pivot="os-linux"
 
 ```bash
-Microsoft.AspNetCore.All 2.1.7 [/home/user/dotnet/shared/Microsoft.AspNetCore.All]
-Microsoft.AspNetCore.All 2.1.13 [/home/user/dotnet/shared/Microsoft.AspNetCore.All]
-Microsoft.AspNetCore.App 2.1.7 [/home/user/dotnet/shared/Microsoft.AspNetCore.App]
-Microsoft.AspNetCore.App 2.1.13 [/home/user/dotnet/shared/Microsoft.AspNetCore.App]
-Microsoft.AspNetCore.App 3.1.0 [/home/user/dotnet/shared/Microsoft.AspNetCore.App]
-Microsoft.AspNetCore.App 5.0.0 [/home/user/dotnet/shared/Microsoft.AspNetCore.App]
-Microsoft.AspNetCore.App 6.0.0 [/home/user/dotnet/shared/Microsoft.AspNetCore.App]
-Microsoft.NETCore.App 2.1.7 [/home/user/dotnet/shared/Microsoft.NETCore.App]
-Microsoft.NETCore.App 2.1.13 [/home/user/dotnet/shared/Microsoft.NETCore.App]
-Microsoft.NETCore.App 3.1.0 [/home/user/dotnet/shared/Microsoft.NETCore.App]
-Microsoft.NETCore.App 5.0.0 [/home/user/dotnet/shared/Microsoft.NETCore.App]
-Microsoft.NETCore.App 6.0.0 [/home/user/dotnet/shared/Microsoft.NETCore.App]
-Microsoft.NETCore.App 7.0.0 [/home/user/dotnet/shared/Microsoft.NETCore.App]
-Microsoft.NETCore.App 8.0.0 [/home/user/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.AspNetCore.All 2.1.7 [/usr/lib/dotnet/shared/Microsoft.AspNetCore.All]
+Microsoft.AspNetCore.All 2.1.13 [/usr/lib/dotnet/shared/Microsoft.AspNetCore.All]
+Microsoft.AspNetCore.App 2.1.7 [/usr/lib/dotnet/shared/Microsoft.AspNetCore.App]
+Microsoft.AspNetCore.App 2.1.13 [/usr/lib/dotnet/shared/Microsoft.AspNetCore.App]
+Microsoft.AspNetCore.App 3.1.0 [/usr/lib/dotnet/shared/Microsoft.AspNetCore.App]
+Microsoft.AspNetCore.App 5.0.0 [/usr/lib/dotnet/shared/Microsoft.AspNetCore.App]
+Microsoft.AspNetCore.App 6.0.0 [/usr/lib/dotnet/shared/Microsoft.AspNetCore.App]
+Microsoft.NETCore.App 2.1.7 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.1.13 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 3.1.0 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 5.0.0 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 6.0.0 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 7.0.0 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 8.0.0 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]
 ```
 
 ::: zone-end
@@ -156,13 +156,19 @@ _C:\\program files\\dotnet\\shared\\{runtime-type}\\{version}\\_
 ::: zone pivot="os-linux"
 
 - **dotnet executable**\
-_/home/user/share/dotnet/dotnet_
+_/home/user/.dotnet/dotnet_\
+_/usr/lib/dotnet/dotnet_\
+_/usr/share/dotnet/dotnet_\
 
 - **.NET SDK**\
-_/home/user/share/dotnet/sdk/{version}/_
+_/home/user/.dotnet/sdk/{version}/_\
+_/usr/lib/dotnet/sdk/{version}/_\
+_/usr/share/dotnet/sdk/{version}/_\
 
 - **.NET Runtime**\
-_/home/user/share/dotnet/shared/{runtime-type}/{version}/_
+_/home/user/.dotnet/shared/{runtime-type}/{version}/_\
+_/usr/lib/dotnet/shared/{runtime-type}/{version}/_\
+_/usr/share/dotnet/shared/{runtime-type}/{version}/_\
 
 ::: zone-end
 

docs/core/install/linux-scripted-manual.md

@@ -131,7 +131,9 @@ Different versions of .NET can be extracted to the same folder, which coexist si
 
 ### Example
 
-The following commands set the environment variable `DOTNET_ROOT` to the current working directory followed by `.dotnet`. They then create the directory if it doesn't exist and extract the contents of the file specified by the `DOTNET_FILE` environment variable to the `.dotnet` directory. Both the `.dotnet` directory and its `tools` subdirectory are added to the `PATH` environment variable.
+<!-- Note, this content is copied in macos.md. Any fixes should be applied there too, though content may be different -->
+
+The following commands use Bash to set the environment variable `DOTNET_ROOT` to the current working directory followed by `.dotnet`. That directory is created if it doesn't exist. The `DOTNET_FILE` environment variable is the filename of the .NET binary release you want to install. This file is extracted to the `DOTNET_ROOT` directory. Both the `DOTNET_ROOT` directory and its `tools` subdirectory are added to the `PATH` environment variable.
 
 > [!IMPORTANT]
 > If you run these commands, remember to change the `DOTNET_FILE` value to the name of the .NET binary you downloaded.
@@ -145,7 +147,13 @@ mkdir -p "$DOTNET_ROOT" && tar zxf "$DOTNET_FILE" -C "$DOTNET_ROOT"
 export PATH=$PATH:$DOTNET_ROOT:$DOTNET_ROOT/tools
 ```
 
-The preceding install script approach allows installing different versions into separate locations so you can choose explicitly which one to use by which app. However, you can still install multiple versions of .NET to the same folder.
+You can install more than one version of .NET in the same folder.
+
+You can also install .NET to the home directory identified by the `HOME` variable or `~` path:
+
+```bash
+export DOTNET_ROOT=$HOME/.dotnet
+```
 
 ## Verify downloaded binaries
 
@@ -157,7 +165,7 @@ The preceding install script approach allows installing different versions into
 
 If you used the previous install script, the variables set only apply to your current terminal session. Add them to your shell profile. There are many different shells available for Linux and each has a different profile. For example:
 
-- **Bash Shell**: *~/.bash_profile*, *~/.bashrc*
+- **Bash Shell**: *~/.bash_profile* or *~/.bashrc*
 - **Korn Shell**: *~/.kshrc* or *.profile*
 - **Z Shell**: *~/.zshrc* or *.zprofile*
 
@@ -173,7 +181,7 @@ Set the following two environment variables in your shell profile:
 
 - `PATH`
 
-  This variable should include both the `DOTNET_ROOT` folder and the user's _.dotnet/tools_ folder:
+  This variable should include both the `DOTNET_ROOT` folder and the `DOTNET_ROOT/tools` folder:
 
   ```bash
   export PATH=$PATH:$DOTNET_ROOT:$DOTNET_ROOT/tools

docs/core/install/macos-notarization-issues.md

@@ -12,7 +12,7 @@ Beginning with macOS Catalina (version 10.15), all software built after June 1,
 
 ## Installing .NET
 
-The installers for .NET (both runtime and SDK) have been notarized since February 18, 2020. Prior released versions aren't notarized. You can manually install a non-notarized version of .NET by first downloading the installer, and then using the `sudo installer` command. For more information, see [Download and manually install for macOS](./macos.md#download-and-manually-install).
+The installers for .NET (both runtime and SDK) have been notarized since February 18, 2020. Prior released versions aren't notarized. You can manually install a non-notarized version of .NET by first downloading the installer, and then using the `sudo installer` command. For more information, see [Download and manually install for macOS](./macos.md#manual-install).
 
 ## Native appHost
 

docs/core/install/macos.md

@@ -81,61 +81,87 @@ brew update
 brew install mono-libgdiplus
 ```
 
-## Install with an installer
+## Automated install
 
 macOS has standalone installers that can be used to install .NET:
 
 - ✔️ [.NET 8 downloads](https://dotnet.microsoft.com/download/dotnet/8.0)
 - ✔️ [.NET 7 downloads](https://dotnet.microsoft.com/download/dotnet/7.0)
 - ✔️ [.NET 6 downloads](https://dotnet.microsoft.com/download/dotnet/6.0)
 
-## Download and manually install
+## Manual install
 
 <!-- Note, this content is taken from linux-scripted-manual.md but changed for macOS. Any fixes should be applied there too, though content may be different -->
 
 As an alternative to the macOS installers for .NET, you can download and manually install the SDK and runtime. Manual installation is usually performed as part of continuous integration testing. For a developer or user, it's generally better to use an [installer](https://dotnet.microsoft.com/download/dotnet).
 
-First, download a **binary** release for either the SDK or the runtime from one of the following sites. If you install the .NET SDK, you won't need to install the corresponding runtime:
+Download a **binary** release for either the SDK or the runtime from one of the following sites. The .NET SDK includes the corresponding runtime:
 
 - ✔️ [.NET 8 downloads](https://dotnet.microsoft.com/download/dotnet/8.0)
 - ✔️ [.NET 7 downloads](https://dotnet.microsoft.com/download/dotnet/7.0)
 - ✔️ [.NET 6 downloads](https://dotnet.microsoft.com/download/dotnet/6.0)
 - [All .NET downloads](https://dotnet.microsoft.com/download/dotnet)
 
-Next, extract the downloaded file and use the `export` command to set `DOTNET_ROOT` to the extracted folder's location and then ensure .NET is in PATH. This should make the .NET CLI commands available at the terminal. For more information about .NET environment variables, see [.NET SDK and CLI environment variables](../tools/dotnet-environment-variables.md#net-sdk-and-cli-environment-variables).
+Extract the downloaded file and use the `export` command to set `DOTNET_ROOT` to the extracted folder's location and then ensure .NET is in PATH. Exporting `DOTNET_ROOT` makes the .NET CLI commands available in the terminal. For more information about .NET environment variables, see [.NET SDK and CLI environment variables](../tools/dotnet-environment-variables.md#net-sdk-and-cli-environment-variables).
 
-Alternatively, after downloading the .NET binary, the following commands can be run from the directory where the file is saved to extract the runtime. These commands also make the .NET CLI commands available at the terminal and set the required environment variables. **Remember to change the `DOTNET_FILE` value to the name of the downloaded binary**:
+Different versions of .NET can be extracted to the same folder, which coexist side-by-side.
+
+### Example
+
+The following commands use Bash to set the environment variable `DOTNET_ROOT` to the current working directory followed by `.dotnet`. That directory is created if it doesn't exist. The `DOTNET_FILE` environment variable is the filename of the .NET binary release you want to install. This file is extracted to the `DOTNET_ROOT` directory. Both the `DOTNET_ROOT` directory and its `tools` subdirectory are added to the `PATH` environment variable.
+
+> [!IMPORTANT]
+> If you run these commands, remember to change the `DOTNET_FILE` value to the name of the .NET binary you downloaded.
 
 ```bash
 DOTNET_FILE=dotnet-sdk-8.0.100-osx-x64.tar.gz
-export DOTNET_ROOT=$(pwd)/dotnet
+export DOTNET_ROOT=$(pwd)/.dotnet
 
 mkdir -p "$DOTNET_ROOT" && tar zxf "$DOTNET_FILE" -C "$DOTNET_ROOT"
 
 export PATH=$PATH:$DOTNET_ROOT
 ```
 
-> [!TIP]
-> The preceding `export` commands only make the .NET CLI commands available for the terminal session in which it was run.
->
-> You can edit your shell profile to permanently add the commands. There are a number of different shells available for Linux and each has a different profile. For example:
->
-> - **Bash Shell**: *~/.bash_profile*, *~/.bashrc*
-> - **Korn Shell**: *~/.kshrc* or *.profile*
-> - **Z Shell**: *~/.zshrc* or *.zprofile*
->
-> Edit the appropriate source file for your shell and add `:$HOME/dotnet` to the end of the existing `PATH` statement. If no `PATH` statement is included, add a new line with `export PATH=$PATH:$HOME/dotnet`.
->
-> Also, add `export DOTNET_ROOT=$HOME/dotnet` to the end of the file.
+You can install more than one version of .NET in the same folder.
+
+You can also install .NET to the home directory identified by the `HOME` variable or `~` path:
 
-This approach lets you install different versions into separate locations and choose explicitly which one to use by which application.
+```bash
+export DOTNET_ROOT=$HOME/.dotnet
+```
 
 ## Verify downloaded binaries
 
 [!INCLUDE [verify-download-intro](includes/verify-download-intro.md)]
 
 [!INCLUDE [verify-download-macos-linux](includes/verify-download-macos-linux.md)]
 
+## Set environment variables system-wide
+
+If you used the instructions in the [Manual install example](#example) section, the variables set only apply to your current terminal session. Add them to your shell profile. There are many different shells available for macOS and each has a different profile. For example:
+
+- **Bash Shell**: *~/.profile*, */etc/profile*
+- **Korn Shell**: *~/.kshrc* or *.profile*
+- **Z Shell**: *~/.zshrc* or *.zprofile*
+
+Set the following two environment variables in your shell profile:
+
+- `DOTNET_ROOT`
+
+  This variable is set to the folder .NET was installed to, such as `$HOME/.dotnet`:
+
+  ```bash
+  export DOTNET_ROOT=$HOME/.dotnet
+  ```
+
+- `PATH`
+
+  This variable should include both the `DOTNET_ROOT` folder and the `DOTNET_ROOT/tools` folder:
+
+  ```bash
+  export PATH=$PATH:$DOTNET_ROOT:$DOTNET_ROOT/tools
+  ```
+
 ## Arm-based Macs
 
 The following sections describe things you should consider when installing .NET on an Arm-based Mac.

docs/core/runtime-discovery/troubleshoot-app-launch.md

@@ -240,15 +240,15 @@ For more information on installation using the script, see [Install with bash au
 You can download a binary archive of .NET from the [download page](https://dotnet.microsoft.com/download/dotnet). From the **Binaries** column of the runtime download, download the binary release matching the required architecture. Extract the downloaded archive to the ".NET location" specified in the error message.
 
 ::: zone pivot="os-windows"
-For more details on manual installation, see [Install .NET on Windows](../install/windows.md#install-with-powershell-automation)
+For more information about manual installation, see [Install .NET on Windows](../install/windows.md#install-with-powershell-automation)
 ::: zone-end
 
 ::: zone pivot="os-linux"
-For more details on manual installation, see [Install .NET on Linux](../install/linux.md#manual-installation)
+For more information about manual installation, see [Install .NET on Linux](../install/linux.md#manual-installation)
 ::: zone-end
 
 ::: zone pivot="os-macos"
-For more details on manual installation, see [Install .NET on macOS](../install/macos.md#download-and-manually-install)
+For more information about manual installation, see [Install .NET on macOS](../install/macos.md#manual-install)
 ::: zone-end
 
 ### Configure roll-forward behavior