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.
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.
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
- 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
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
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)
* [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)
.\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
-# Build CoreCLR on MacOS
+# Build CoreCLR on macOS
* [Environment](#environment)
* [Build the Runtime](#build-the-runtime)
## 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>
### 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
* [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.
## 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
* `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).
```
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!
* [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)
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
### 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
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`.
#### 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
## 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.
## 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
-# 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
* It's recommended to use **Workloads** installation approach. The following are the minimum requirements:
* **.NET Desktop Development** with all default components,
* **Desktop Development with C++** with all default components.
-* The build tools (CMake, Ninja and Python) can be downloaded and installed separately (see detailed instructions in the [section below](#build-tools)) or by selecting the following **Individual Components**:
- * **C++ CMake tools for Windows** (includes Ninja, but might not work on ARM64 machines),
- * **Python 3 64-bit** (3.7.4 or newer).
* To build for Arm32 or Arm64, make sure that you have the right architecture-specific compilers installed. In the **Individual components** window, in the **Compilers, build tools, and runtimes** section:
- * For Arm32, check the box for _MSVC v143* VS 2022 C++ ARM build tools (Latest)_, which must be _v14.31_ or newer.
- * For Arm64, check the box for _MSVC v143* VS 2022 C++ ARM64 build tools (Latest)_, which must be _v14.31_ or newer.
+ * For Arm32, check the box for _MSVC v143* VS 2022 C++ ARM build tools (Latest)_.
+ * For Arm64, check the box for _MSVC v143* VS 2022 C++ ARM64 build tools (Latest)_.
* To build the tests, you will need some additional components:
- * **Windows 10 SDK (10.0.19041)** or newer. This component is installed by default as a part of **Desktop Development with C++** workload.
- * **C++/CLI support for v142 build tools (Latest)**, which must be v14.23 or newer.
+ * **C++/CLI support for v142 build tools (Latest)**.
A `.vsconfig` file is included in the root of the _dotnet/runtime_ repository that includes all components needed to build the _dotnet/runtime_ repository. You can [import `.vsconfig` in your Visual Studio installer](https://docs.microsoft.com/visualstudio/install/import-export-installation-configurations?view=vs-2022#import-a-configuration) to install all necessary components. You may get a message saying `Microsoft.Net.Component.4.5.2.TargetingPack has no matching workload or component found`. This is not an issue as long as you have a newer targeting pack installed.
* [Running the Tests](#running-the-tests)
* [Running Individual Tests](#running-individual-tests)
* [Tests Without a Main Method](#tests-without-a-main-method)
- * [PAL Tests (MacOS and Linux only)](#pal-tests-macos-and-linux-only)
+ * [PAL Tests (macOS and Linux only)](#pal-tests-macos-and-linux-only)
* [Building PAL Tests](#building-pal-tests)
* [Running PAL Tests](#running-pal-tests)
* [Modifying Tests](#modifying-tests)
In order to build CoreCLR tests, you will need to have built the runtime and the libraries (that is, _clr_ and _libs_ subsets). You can find more detailed instructions per platform in their dedicated docs:
* [Windows](/docs/workflow/building/coreclr/windows-instructions.md)
-* [MacOS](/docs/workflow/building/coreclr/macos-instructions.md)
+* [macOS](/docs/workflow/building/coreclr/macos-instructions.md)
* [Linux](/docs/workflow/building/coreclr/linux-instructions.md)
For CoreCLR testing purposes, it is more than enough to simply build the _libs_ subset, as far as it concerns the libraries. If you want to know more in-depth about them, they have their own [libraries dedicated docs section](/docs/workflow/building/libraries/README.md).
.\src\tests\build.cmd test JIT\Intrinsics\MathRoundDouble_ro.csproj test JIT\Intrinsics\MathFloorDouble_ro.csproj
```
-On MacOS and Linux:
+On macOS and Linux:
```bash
./src/tests/build.sh -test:JIT/Intrinsics/MathRoundDouble_ro.csproj -test:JIT/Intrinsics/MathFloorDouble_ro.csproj
.\src\tests\build.cmd dir JIT\Methodical\Arrays\lcs dir JIT\Methodical\cctor\misc\Desktop
```
-On MacOS and Linux:
+On macOS and Linux:
```bash
./src/tests/build.sh -dir:JIT/Methodical/Arrays/lcs -dir:JIT/Methodical/cctor/misc/Desktop
.\src\tests\build.cmd tree baseservices\exceptions tree JIT\Methodical
```
-On MacOS and Linux:
+On macOS and Linux:
```bash
./src/tests/build.sh -tree:baseservices/exceptions -tree:JIT/Methodical
.\src\tests\build.cmd dir JIT\Methodical\divrem\div -priority=1
```
-On MacOS and Linux:
+On macOS and Linux:
```bash
./src/tests/build.sh -dir:JIT/Methodical/divrem/div -priority1
```
-**NOTE**: Yes, you're seeing it right. The `priority` flag is a bit different between the Windows and MacOS/Linux scripts.
+**NOTE**: Yes, you're seeing it right. The `priority` flag is a bit different between the Windows and macOS/Linux scripts.
## Running the Tests
.\MathRoundDouble_ro.cmd
```
-On MacOS/Linux:
+On macOS/Linux:
```bash
export CORE_ROOT=<repo_root>/artifacts/tests/coreclr/<OS>.<Arch>.<Configuration>/Tests/Core_Root
.\MathRoundDouble_ro.cmd -coreroot <repo_root>\artifacts\tests\coreclr\windows.<Arch>.<Configuration>\Tests\Core_Root
```
-On MacOS/Linux:
+On macOS/Linux:
```bash
cd path/to/JIT/Intrinsics/MathRoundDouble_ro
Guide on how to run tests without a `Main()` Method coming soon!
-### PAL Tests (MacOS and Linux only)
+### PAL Tests (macOS and Linux only)
The PAL layer tests are exclusive to Unix-based operating systems. This section will go on how to work with them.
corerun HelloWorld.dll
```
-On MacOS and Linux:
+On macOS and Linux:
```bash
# Change osx to linux if you're on a Linux machine.
```powershell
# Note the '+=' since we're appending to the already existing PATH variable.
-# Also, replace the ';' with ':' if on Linux or MacOS.
+# Also, replace the ';' with ':' if on Linux or macOS.
$Env:PATH += ';<repo_root>\artifacts\bin\coreclr\windows.x64.Debug'
$Env:CORE_LIBRARIES = %ProgramFiles%\dotnet\shared\Microsoft.NETCore.App\7.0.0
corerun HelloWorld.dll
corerun HelloWorld.dll
```
-On MacOS and Linux:
+On macOS and Linux:
```bash
-# Change linux to osx if you're on a MacOS machine.
+# Change linux to osx if you're on a macOS machine.
export PATH="$PATH:<repo_root>/artifacts/tests/coreclr/linux.x64.Debug/Tests/Core_Root"
corerun HelloWorld.dll
```
```powershell
# Note the '+=' since we're appending to the already existing PATH variable.
-# Also, replace the ';' with ':' if on Linux or MacOS.
+# Also, replace the ';' with ':' if on Linux or macOS.
$Env:PATH += ';<repo_root>\artifacts\tests\coreclr\windows.x64.Debug\Tests\Core_Root'
.\corerun HelloWorld.dll
```
.\build.cmd -s clr+libs+packs+host
```
-For MacOS and Linux:
+For macOS and Linux:
```bash
./build.sh -s clr+libs+packs+host
We are using Windows x64 for this example. Make sure you set it to the platform and configuration you have your build in. The codenames for the most common OS's are:
* _Windows_: `win`
-* _MacOS_: `osx`
+* _macOS_: `osx`
* _Linux_: `linux`
-For example, if we were testing a MacOS ARM64 build, our `RuntimeIdentifier` would be `osx-arm64`.
+For example, if we were testing a macOS ARM64 build, our `RuntimeIdentifier` would be `osx-arm64`.
### Publish your App
projects / platform / upstream / dotnet / runtime.git / commitdiff