Doc improvements (dotnet#76863)

- Use proper macOS capitalization
- Delete superfluous details

Co-authored-by: Theodore Tsirpanis <[email protected]>

Author: jkotas

docs/design/coreclr/botr/xplat-minidump-generation.md

@@ -40,9 +40,9 @@ Like the severe memory corruption case, if the signal handler (`SIGSEGV`) gets c
 
 There will be some differences gathering the crash information but these platforms still use ELF format core dumps so that part of the utility should be much different. The mechanism used for Linux to give _createdump_ permission to use ptrace and access the /proc doesn't exists on these platforms.
 
-### OS X ###
+### macOS ###
 
-On .NET 5.0, createdump supported generating dumps on MacOS but instead of the MachO dump format, it generates the ELF coredumps. This wad because of time constraints developing a MachO dump writer on the generation side and a MachO reader for the diagnostics tooling side (dotnet-dump and CLRMD). This means the native debuggers like gdb and lldb will not work with dumps obtained from apps running on a 5.0 runtime, but the dotnet-dump tool will allow the managed state to be analyzed. Because of this behavior an additional environment variable will need to be set (COMPlus_DbgEnableElfDumpOnMacOS=1) along with the ones below in the Configuration/Policy section.
+On .NET 5.0, createdump supported generating dumps on macOS but instead of the MachO dump format, it generates the ELF coredumps. This wad because of time constraints developing a MachO dump writer on the generation side and a MachO reader for the diagnostics tooling side (dotnet-dump and CLRMD). This means the native debuggers like gdb and lldb will not work with dumps obtained from apps running on a 5.0 runtime, but the dotnet-dump tool will allow the managed state to be analyzed. Because of this behavior an additional environment variable will need to be set (COMPlus_DbgEnableElfDumpOnMacOS=1) along with the ones below in the Configuration/Policy section.
 
 Starting .NET 6.0, native Mach-O core files get generated and the variable COMPlus_DbgEnableElfDumpOnMacOS has been deprecated.
 

docs/design/mono/diagnostics-tracing.md

@@ -10,8 +10,8 @@ MonoVM includes support for EventPipe and DiagnosticServer components used to ge
 
 Due to differences between runtimes many of the NativeRuntimeEvents won't apply to MonoVM. Only a selected amount of NativeRuntimeEvents will initially be added to MonoVM. Current supported NativeRuntimeEvents can be viewed in MonoVM include file, https://github.com/dotnet/runtime/blob/main/src/mono/mono/eventpipe/gen-eventing-event-inc.lst. Since primary focus is EventPipe and mobile platforms (iOS/Android), ETW and LTTng providers have currently not been integrated/enabled for NativeRuntimeEvents on MonoVM.
 
-MonoVM runs on a variety of platforms and depending on platform capabilities MonoVM support different build configurations of EventPipe and DiagnosticServer. For desktop platforms (Windows, Linux, MacOS), MonoVM build DiagnosticServer using
-`NamedPipes` (Windows) or `UnixDomainSockets` (Linux, MacOS) support. This is in line with CoreCLR build configuration of the DiagnosticServer, working in the same way.
+MonoVM runs on a variety of platforms and depending on platform capabilities MonoVM support different build configurations of EventPipe and DiagnosticServer. For desktop platforms (Windows, Linux, macOS), MonoVM build DiagnosticServer using
+`NamedPipes` (Windows) or `UnixDomainSockets` (Linux, macOS) support. This is in line with CoreCLR build configuration of the DiagnosticServer, working in the same way.
 
 On mobile platforms (Android/iOS) or other remote sandboxed environments, MonoVM DiagnosticServer component can be build using TCP/IP support to better handle remote targets. It also handles the connect scenario (runtime act as TCP/IP client connecting back to tooling), as well as the listening scenario (runtime act as a TCP/IP listener waiting for tooling to connect). Depending on platform, allowed capabilities (some platforms won't allow listening on sockets) and tracing scenarios (startup tracing needs suspended runtime), a combination of these scenarios can be used.
 

docs/design/security/unix-tmp.md

@@ -7,12 +7,12 @@ are used to Windows may inadvertently create security risk if they use the same
 Most notably, the Windows model for temporary files is that the operating system provides each user with a *unique*, *user-owned* temporary directory.
 Moreover, all Windows users, including the service and system users, have designated user folders, including temporary folders.
 
-The Unix model is very different. The temp directory, assuming there is one, is often a global folder (except on MacOS).
+The Unix model is very different. The temp directory, assuming there is one, is often a global folder (except on macOS).
 If possible, prefer a library function like `GetTempPath()` to find the folder. Otherwise,
 the `TMPDIR` environment variable is used to store the location of this folder. This variable is
 widely used and supported, but it is not mandatory for all Unix implementations. It should be the preferred
 mechanism for finding the Unix temporary folder if a library method is not available. It will commonly
-point to either the `/tmp` or `/var/tmp` folder. These folders are not used for MacOS, so it is not recommended
+point to either the `/tmp` or `/var/tmp` folder. These folders are not used for macOS, so it is not recommended
 to use them directly.
 
 Because the temporary directory is often global, any use of the temp directory should be carefully

docs/infra/test-configurations.md

@@ -38,7 +38,7 @@ All builds are
   - Linux arm32 Release
   - Linux arm32 musl Release
   - FreeBSD x64 (build only)
-- MacOS 11.6.4 x64
+- macOS 11.6.4 x64
   - x64 Release
   - arm64 Release
 

docs/workflow/building/coreclr/README.md

@@ -14,7 +14,7 @@ Here is a brief overview on how to build the common form of CoreCLR in general.
 
 To build just CoreCLR, use the `subset` flag to the `build.sh` or `build.cmd` script at the repo root. Note that specifying `-subset` explicitly is not necessary if it is the first argument (i.e. `./build.sh --subset clr` and `./build.sh clr` are equivalent). However, if you specify any other argument beforehand, then you must specify the `-subset` flag.
 
-For Linux and MacOS:
+For Linux and macOS:
 
 ```bash
 ./build.sh --subset clr
@@ -89,7 +89,7 @@ If you want to force a full rebuild of the subsets you specified when calling th
 Now that you've got the general idea on how the _CoreCLR_ builds work, here are some further documentation links on platform-specific caveats and features.
 
 * [Build CoreCLR on Windows](windows-instructions.md)
-* [Build CoreCLR on MacOS](macos-instructions.md)
+* [Build CoreCLR on macOS](macos-instructions.md)
 * [Build CoreCLR on Linux](linux-instructions.md)
 * [Build CoreCLR on FreeBSD](freebsd-instructions.md)
 

docs/workflow/building/coreclr/cross-building.md

@@ -3,7 +3,7 @@
 * [Windows Cross-Building](#windows-cross-building)
   * [Cross-Compiling for ARM32 and ARM64 on Windows](#cross-compiling-for-arm32-and-arm64-on-windows)
   * [Cross-Compiling for x86 on Windows](#cross-compiling-for-x86-on-windows)
-* [MacOS Cross-Building](#macos-cross-building)
+* [macOS Cross-Building](#macos-cross-building)
 * [Linux Cross-Building](#linux-cross-building)
   * [Generating the ROOTFS](#generating-the-rootfs)
     * [ROOTFS for FreeBSD](#rootfs-for-freebsd)
@@ -39,11 +39,11 @@ Building for x86 doesn't require any additional software installed or configured
 .\build.cmd -s clr -c Release -arch x86
 ```
 
-## MacOS Cross-Building
+## macOS Cross-Building
 
-This section will go over cross-compiling on MacOS. Currently, MacOS allows you to cross-compile between x64 and ARM64.
+This section will go over cross-compiling on macOS. Currently, macOS allows you to cross-compile between x64 and ARM64.
 
-Similarly to targeting Windows x86, the native tooling you installed back in the [MacOS requirements doc](/docs/workflow/requirements/macos-requirements.md) has the capabilities to effectuate the cross-compilation. You have simply to pass the `-cross` flag, along with the designated architecture. For example, for an arm64 build on an Intel x64 Mac:
+Similarly to targeting Windows x86, the native tooling you installed back in the [macOS requirements doc](/docs/workflow/requirements/macos-requirements.md) has the capabilities to effectuate the cross-compilation. You have simply to pass the `-cross` flag, along with the designated architecture. For example, for an arm64 build on an Intel x64 Mac:
 
 ```bash
 ./build.sh -s clr -c Release --cross -a arm64

docs/workflow/building/coreclr/macos-instructions.md

@@ -1,4 +1,4 @@
-# Build CoreCLR on MacOS
+# Build CoreCLR on macOS
 
 * [Environment](#environment)
 * [Build the Runtime](#build-the-runtime)
@@ -9,11 +9,11 @@ This guide will walk you through building CoreCLR on macOS.
 
 ## Environment
 
-Ensure you have all of the prerequisites installed from the [MacOS Requirements](/docs/workflow/requirements/macos-requirements.md).
+Ensure you have all of the prerequisites installed from the [macOS Requirements](/docs/workflow/requirements/macos-requirements.md).
 
 ## Build the Runtime
 
-To build CoreCLR on MacOS, run `build.sh` while specifying the `clr` subset:
+To build CoreCLR on macOS, run `build.sh` while specifying the `clr` subset:
 
 ```bash
 ./build.sh --subset clr <other args>
@@ -27,7 +27,7 @@ After the build has completed, there should be some files placed in `artifacts/b
 
 ### Cross-Compilation
 
-It is possible to get a MacOS ARM64 build using an Intel x64 Mac and vice versa, an x64 one using an M1 Mac. Instructions on how to do this are in the [cross-building doc](/docs/workflow/building/coreclr/cross-building.md#macos-cross-building).
+It is possible to get a macOS ARM64 build using an Intel x64 Mac and vice versa, an x64 one using an M1 Mac. Instructions on how to do this are in the [cross-building doc](/docs/workflow/building/coreclr/cross-building.md#macos-cross-building).
 
 ## Create the Core_Root
 

docs/workflow/building/coreclr/windows-instructions.md

@@ -2,12 +2,9 @@
 
 * [Environment](#environment)
 * [Build the Runtime](#build-the-runtime)
-  * [Using the Command Line](#using-the-command-line)
-    * [CoreCLR](#coreclr)
-      * [Cross-Compilation](#cross-compilation)
-    * [Core_Root](#core_root)
-    * [Native ARM64 (Experimental)](#native-arm64-experimental)
-  * [Using Visual Studio](#using-visual-studio)
+  * [Cross-Compilation](#cross-compilation)
+* [Core_Root](#core_root)
+* [Native ARM64 (Experimental)](#native-arm64-experimental)
 
 This guide will walk you through building CoreCLR on Windows.
 
@@ -17,14 +14,6 @@ Ensure you have all of the prerequisites installed from the [Windows Requirement
 
 ## Build the Runtime
 
-As the main development platform for .NET, Windows has more than one way to build the _dotnet/runtime_ repo. You can do it entirely through the command-line as you'd do in Linux and MacOS, or you can leverage the integration with Visual Studio that the repository provides. This document will go on about both ways so you can choose whichever fits your needs best, or even use a combination of both.
-
-### Using the Command Line
-
-This section will cover how to build the product using the command-line.
-
-#### CoreCLR
-
 To build CoreCLR on Windows, run `build.cmd` while specifying the `clr` subset:
 
 ```cmd
@@ -37,15 +26,15 @@ After the build has completed, there should be some files placed in `artifacts/b
 * `coreclr.dll`: The CoreCLR runtime itself.
 * `System.Private.CoreLib.dll`: The core managed library, containing definitions of `Object` and base functionality.
 
-##### Cross-Compilation
+### Cross-Compilation
 
 It is possible to get Windows x86, ARM32, and ARM64 builds using an x64 machine. Instructions on how to do this are in the [cross-building doc](/docs/workflow/building/coreclr/cross-building.md#windows-cross-building).
 
-#### Core_Root
+## Core_Root
 
 The Core_Root provides one of the main ways to test your build. Full instructions on how to build it in the [CoreCLR testing doc](/docs/workflow/testing/coreclr/testing.md), and we also have a detailed guide on how to use it for your own testing in [its own dedicated doc](/docs/workflow/testing/using-corerun-and-coreroot.md).
 
-#### Native ARM64 (Experimental)
+## Native ARM64 (Experimental)
 
 Building natively on ARM64 requires you to have installed the appropriate ARM64 build tools and Windows SDK, as specified in the [Windows requirements doc](/docs/workflow/requirements/windows-requirements.md).
 
@@ -56,7 +45,3 @@ build.cmd -s clr -c Release -arch arm64 -msbuild
 ```
 
 Since this is still in an experimental phase, the recommended way for building ARM64 is cross-compiling from an x64 machine. Instructions on how to do this can be found at the [cross-building doc](/docs/workflow/building/coreclr/cross-building.md#cross-compiling-for-arm32-and-arm64).
-
-### Using Visual Studio
-
-Visual Studio instructions coming soon!

docs/workflow/debugging/coreclr/debugging-runtime.md

@@ -5,7 +5,7 @@
     * [Using Visual Studio Open Folder with CMake](#using-visual-studio-open-folder-with-cmake)
   * [Using Visual Studio Code](#using-visual-studio-code)
   * [Using SOS with Windbg or Cdb on Windows](#using-sos-with-windbg-or-cdb-on-windows)
-* [Debugging CoreCLR on Linux and MacOS](#debugging-coreclr-on-linux-and-macos)
+* [Debugging CoreCLR on Linux and macOS](#debugging-coreclr-on-linux-and-macos)
   * [SOS on Unix](#sos-on-unix)
   * [Debugging CoreCLR with lldb](#debugging-coreclr-with-lldb)
     * [Disabling Managed Attach/Debugging](#disabling-managed-attachdebugging)
@@ -117,9 +117,9 @@ Under normal circumstances, SOS usually comes shipped with Windbg, so no additio
 
 For more information on SOS commands click [here](https://github.com/dotnet/diagnostics/blob/master/documentation/sos-debugging-extension-windows.md).
 
-## Debugging CoreCLR on Linux and MacOS
+## Debugging CoreCLR on Linux and macOS
 
-Very similarly to Windows, Linux and MacOS also require to have at least the _clr_ subset built prior to attempting to debug, most preferably under the _Debug_ configuration:
+Very similarly to Windows, Linux and macOS also require to have at least the _clr_ subset built prior to attempting to debug, most preferably under the _Debug_ configuration:
 
 ```bash
 ./build.sh -s clr -c Debug
@@ -137,20 +137,20 @@ If for some reason `System.Private.CoreLib.dll` is missing, you can rebuild it w
 
 ### SOS on Unix
 
-For Linux and MacOS, you have to install SOS by yourself, as opposed to Windows' Windbg. The instructions are very similar however, and you can find them on these two links:
+For Linux and macOS, you have to install SOS by yourself, as opposed to Windows' Windbg. The instructions are very similar however, and you can find them on these two links:
 
 * The official [Microsoft docs on SOS](https://docs.microsoft.com/dotnet/core/diagnostics/dotnet-sos).
 * The instructions at the [diagnostics repo](https://github.com/dotnet/diagnostics/blob/master/documentation/installing-sos-instructions.md).
 
-It might also be the case that you would need the latest changes in SOS, or you're working with a not-officially-supported scenario that actually works. The most common occurrence of this scenario is when using MacOS Arm64. In this case, you have to build SOS from the diagnostics repo (linked above). Once you have it done, then simply load it to your `lldb`. More details in the following section.
+It might also be the case that you would need the latest changes in SOS, or you're working with a not-officially-supported scenario that actually works. The most common occurrence of this scenario is when using macOS Arm64. In this case, you have to build SOS from the diagnostics repo (linked above). Once you have it done, then simply load it to your `lldb`. More details in the following section.
 
 ### Debugging CoreCLR with lldb
 
 **NOTE**: Only `lldb` is supported to use with SOS. You can also use `gdb`, `cgdb`, or other debuggers, but you might not have access to SOS.
 
 1. Perform a build of the _clr_ subset of the runtime repo.
 2. Start lldb passing `corerun`, the app to run (e.g. `HelloWorld.dll`), and any arguments this app might need: `lldb /path/to/corerun /path/to/app.dll <app args go here>`
-3. If you're using the installed version of SOS, you can skip this step. If you built SOS manually, you have to load it before starting the debugging session: `plugin load /path/to/built/sos/libsosplugin.so`. Note that `.so` is for Linux, and `.dylib` is for MacOS. You can find more information in the diagnostics repo [private sos build doc](https://github.com/dotnet/diagnostics/blob/main/documentation/using-sos-private-build.md).
+3. If you're using the installed version of SOS, you can skip this step. If you built SOS manually, you have to load it before starting the debugging session: `plugin load /path/to/built/sos/libsosplugin.so`. Note that `.so` is for Linux, and `.dylib` is for macOS. You can find more information in the diagnostics repo [private sos build doc](https://github.com/dotnet/diagnostics/blob/main/documentation/using-sos-private-build.md).
 4. Launch program: `process launch -s`
 5. To stop breaks on _SIGUSR1_ signals used by the runtime run the following command: `process handle -s false SIGUSR1`
 6. Set a breakpoint where CoreCLR is initialized, as it's the most stable point to begin debugging: `breakpoint set -n coreclr_execute_assembly`.
@@ -159,7 +159,7 @@ It might also be the case that you would need the latest changes in SOS, or you'
 
 #### Disabling Managed Attach/Debugging
 
-The `DOTNET_EnableDiagnostics` _environment variable_ can be used to disable managed debugging. This prevents the various OS artifacts used for debugging, such as named pipes and semaphores on Linux and MacOS, from being created.
+The `DOTNET_EnableDiagnostics` _environment variable_ can be used to disable managed debugging. This prevents the various OS artifacts used for debugging, such as named pipes and semaphores on Linux and macOS, from being created.
 
 ```bash
 export DOTNET_EnableDiagnostics=0

docs/workflow/requirements/freebsd-requirements.md

@@ -17,7 +17,7 @@ Since there is no official build and FreeBSD package, native build on FreeBSD is
 
 ## Docker
 
-Install Docker. For further instructions on installation, see [here](https://docs.docker.com/install/). You can find the official .NET images in [their Docker hub](https://hub.docker.com/_/microsoft-dotnet).
+Install Docker. For further instructions on installation, see [here](https://docs.docker.com/install/).
 
 All the required build tools are included in the Docker images used to do the build, so no additional setup is required.
 

docs/workflow/requirements/linux-requirements.md

@@ -17,17 +17,15 @@ Install Docker. For further installation instructions, see [here](https://docs.d
 
 ## Environment
 
-These instructions are written assuming the current Ubuntu LTS, since that's the officially used distribution. Pull Requests are welcome to address other environments as long as they don't break the ability to use Ubuntu LTS.
+These instructions are written assuming the current Ubuntu LTS. Pull Requests are welcome to address other environments.
 
 Minimum RAM required to build is 1GB. The build is known to fail on 512 MB VMs ([dotnet/runtime#4069](https://github.com/dotnet/runtime/issues/4069)).
 
 ### Toolchain Setup
 
-Building the repo requires CMake 3.14.5 or newer on Linux. Add Kitware's APT feed to your configuration for a newer version of CMake (optional). See their instructions at their [website](https://apt.kitware.com/).
-
 Install the following packages for the toolchain:
 
-* CMake
+* CMake 3.14.5 or newer
 * llvm
 * lld
 * clang

docs/workflow/requirements/macos-requirements.md

@@ -1,10 +1,10 @@
-# Requirements to build dotnet/runtime on MacOS
+# Requirements to build dotnet/runtime on macOS
 
 * [Environment](#environment)
   * [Xcode](#xcode)
   * [Toolchain Setup](#toolchain-setup)
 
-This guide will walk you through the requirements needed to build _dotnet/runtime_ on MacOS. We'll start by showing how to set up your environment from scratch.
+This guide will walk you through the requirements needed to build _dotnet/runtime_ on macOS. We'll start by showing how to set up your environment from scratch.
 
 ## Environment