Documentation/building/osx-instructions.md

   1 Build CoreCLR on OS X
   2 =====================
   3
   4 This guide will walk you through building CoreCLR on OS X. We'll start by showing how to set up your environment from scratch.
   5
   6 Environment
   7 ===========
   8
   9 These instructions were validated on macOS 10.12. Sierra. On older versions coreFX will fail to build properly because of SSL API changes.
  10
  11 If your machine has Command Line Tools for XCode 6.3 installed, you'll need to update them to the 6.3.1 version or higher in order to successfully build. There was an issue with the headers that shipped with version 6.3 that was subsequently fixed in 6.3.1.
  12
  13 Git Setup
  14 ---------
  15
  16 Clone the CoreCLR and CoreFX repositories (either upstream or a fork).
  17
  18 ```sh
  19 git clone https://github.com/dotnet/coreclr
  20 # Cloning into 'coreclr'...
  21 ```
  22
  23 This guide assumes that you've cloned the coreclr and corefx repositories into `~/git/coreclr` and `~/git/corefx` on your OS X machine. If your setup is different, you'll need to pay careful attention to the commands you run. In this guide, I'll always show what directory I'm in.
  24
  25 CMake
  26 -----
  27
  28 CoreCLR has a dependency on CMake for the build. You can download it from [CMake downloads](http://www.cmake.org/download/).
  29
  30 Alternatively, you can install CMake from [Homebrew](http://brew.sh/).
  31
  32 ```sh
  33 brew install cmake
  34 ```
  35
  36 ICU
  37 ---
  38 ICU (International Components for Unicode) is also required to build and run. It can be obtained via [Homebrew](http://brew.sh/).
  39
  40 ```sh
  41 brew install icu4c
  42 brew link --force icu4c
  43 ```
  44
  45 Build the Runtime and Microsoft Core Library
  46 ============================================
  47
  48 To Build CoreCLR, run build.sh from the root of the coreclr repo.
  49
  50 ```sh
  51 ./build.sh
  52 ```
  53
  54 After the build has completed, there should some files placed in `bin/Product/OSX.x64.Debug`. The ones we are interested in are:
  55
  56 - `corerun`: The command line host. This program loads and starts the CoreCLR runtime and passes the managed program you want to run to it.
  57 - `libcoreclr.dylib`: The CoreCLR runtime itself.
  58 - `System.Private.CoreLib.dll`: Microsoft Core Library.
  59
  60 Create the Core_Root
  61 ===================
  62
  63 The Core_Root folder will have the built binaries, from `build.sh` and it will also include the CoreFX packages required to run tests.
  64
  65 ```
  66 ./build-test.sh generatelayoutonly
  67 ```
  68
  69 After the build is complete you will be able to find the output in the `bin/tests/OSX.x64.Debug/Tests/Core_Root` folder.
  70
  71 Running a single test
  72 ===================
  73
  74 After `build-test.sh` is run, corerun from the Core_Root folder is ready to be run. This can be done by using the full absolute path to corerun, or by setting
  75 an environment variable to the Core_Root folder.
  76
  77 ```sh
  78 export CORE_ROOT=/path/to/coreclr/bin/tests/OSX.x64.Debug/Tests/Core_Root
  79 $CORE_ROOT/corerun hello_world.dll
  80 ```