Documentation/building/linux-instructions.md

   1 Build CoreCLR on Linux
   2 ======================
   3
   4 This guide will walk you through building CoreCLR on Linux.  We'll start by showing how to set up your environment from scratch.
   5
   6 Environment
   7 ===========
   8
   9 These instructions are written assuming the Ubuntu 14.04 LTS, since that's the distro the team uses. Pull Requests are welcome to address other environments as long as they don't break the ability to use Ubuntu 14.04 LTS.
  10
  11 There have been reports of issues when using other distros or versions of Ubuntu (e.g. [Issue 95](https://github.com/dotnet/coreclr/issues/95)). If you're on another distribution, consider using docker's `ubuntu:14.04` image.
  12
  13 Minimum RAM required to build is 1GB. The build is known to fail on 512 MB VMs ([Issue 536](https://github.com/dotnet/coreclr/issues/536)).
  14
  15 Toolchain Setup
  16 ---------------
  17
  18 Install the following packages for the toolchain:
  19
  20 - cmake
  21 - llvm-3.9
  22 - clang-3.9
  23 - lldb-3.9
  24 - liblldb-3.9-dev
  25 - libunwind8
  26 - libunwind8-dev
  27 - gettext
  28 - libicu-dev
  29 - liblttng-ust-dev
  30 - libcurl4-openssl-dev
  31 - libssl-dev
  32 - libkrb5-dev
  33 - libnuma-dev (optional, enables numa support)
  34
  35 In order to get clang-3.9, llvm-3.9 and lldb-3.9 on Ubuntu 14.04, we need to add an additional package source:
  36
  37     ~$ echo "deb http://llvm.org/apt/trusty/ llvm-toolchain-trusty-3.9 main" | sudo tee /etc/apt/sources.list.d/llvm.list
  38     ~$ wget -O - http://llvm.org/apt/llvm-snapshot.gpg.key | sudo apt-key add -
  39     ~$ sudo apt-get update
  40
  41 Note: arm clang has a known issue with CompareExchange (#15074), so for arm you have to use clang-4.0 or higher, the official build uses clang-5.0.
  42
  43 For other version of Debian/Ubuntu, please visit http://apt.llvm.org/.
  44
  45 Then install the packages you need:
  46
  47     ~$ sudo apt-get install cmake llvm-3.9 clang-3.9 lldb-3.9 liblldb-3.9-dev libunwind8 libunwind8-dev gettext libicu-dev liblttng-ust-dev libcurl4-openssl-dev libssl-dev libnuma-dev libkrb5-dev
  48
  49 The lldb 3.9 package needs a lib file symbolic link fixed:
  50
  51     cd /usr/lib/llvm-3.9/lib
  52     sudo ln -s ../../x86_64-linux-gnu/liblldb-3.9.so.1 liblldb-3.9.so.1
  53
  54 You now have all the required components.
  55
  56 If you are using Fedora, then you will need to install the following packages:
  57
  58     ~$ sudo dnf install llvm cmake clang lldb-devel libunwind-devel lttng-ust-devel libicu-devel numactl-devel
  59
  60 Git Setup
  61 ---------
  62
  63 This guide assumes that you've cloned the corefx and coreclr repositories into `~/git/corefx` and `~/git/coreclr` on your Linux 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.
  64
  65 Set the maximum number of file-handles
  66 --------------------------------------
  67
  68 To ensure that your system can allocate enough file-handles for the corefx build run `sysctl fs.file-max`. If it is less than 100000, add `fs.file-max = 100000` to `/etc/sysctl.conf`, and then run `sudo sysctl -p`.
  69
  70 On Fedora:
  71
  72 `$ sudo dnf install mono-devel`
  73
  74 Build the Runtime and Microsoft Core Library
  75 =============================================
  76
  77 To build the runtime on Linux, run build.sh from the root of the coreclr repository:
  78
  79 ```
  80 ellismg@linux:~/git/coreclr$ ./build.sh
  81 ```
  82
  83 After the build is completed, there should some files placed in `bin/Product/Linux.x64.Debug`.  The ones we are interested in are:
  84
  85 * `corerun`: The command line host.  This program loads and starts the CoreCLR runtime and passes the managed program you want to run to it.
  86 * `libcoreclr.so`: The CoreCLR runtime itself.
  87 * `System.Private.CoreLib.dll`: Microsoft Core Library.
  88
  89 Build the Framework
  90 ===================
  91
  92 ```
  93 ellismg@linux:~/git/corefx$ ./build.sh
  94 ```
  95
  96 After the build is complete you will be able to find the output in the `bin` folder.
  97
  98 Build for ARM/Linux
  99 ===================
 100
 101 Libunwind-arm requires fixes that are not included in Ubuntu 14.04, yet. The fix allows libunwind-arm not to break when it is ordered to access unaccessible memory locations.
 102
 103 First, import the patch from the libunwind upstream: http://git.savannah.gnu.org/gitweb/?p=libunwind.git;a=commit;h=770152268807e460184b4152e23aba9c86601090
 104
 105 Then, expand the coverage of the upstream patch by:
 106
 107 ```
 108 diff --git a/src/arm/Ginit.c b/src/arm/Ginit.c
 109 index 1ed3dbf..c643032 100644
 110 --- a/src/arm/Ginit.c
 111 +++ b/src/arm/Ginit.c
 112 @@ -128,6 +128,11 @@ access_mem (unw_addr_space_t as, unw_word_t addr, unw_word_t *val, int write,
 113  {
 114    if (write)
 115      {
 116 +      /* validate address */
 117 +      const struct cursor *c = (const struct cursor *) arg;
 118 +      if (c && validate_mem(addr))
 119 +        return -1;
 120 +
 121        Debug (16, "mem[%x] <- %x\n", addr, *val);
 122        *(unw_word_t *) addr = *val;
 123      }
 124 ```
 125
 126 Additional optimization levels for ARM/Linux: -Oz and -Ofast
 127 ============================================================
 128
 129 This instruction is to enable additional optimization levels such as -Oz and -Ofast on ARM/Linux. The below table shows what we have to enable for the code optimization of the CoreCLR run-time either the size or speed on embedded devices.
 130
 131 | **Content** | **Build Mode** | **Clang/LLVM (Linux)** |
 132 | --- | --- | --- |
 133 | -O0 | Debug | Disable optimization to generate the most debuggable code |
 134 | -O1 | - | Optimize for code size and execution time |
 135 | -O2 | Checked | Optimize more for code size and execution time |
 136 | -O3 | Release | Optimize more for code size and execution time to make program run faster |
 137 | -Oz | - | Optimize more to reduce code size further |
 138 | -Ofast | - | Enable all the optimizations from O3 along with other aggressive optimizations |
 139
 140 If you want to focus on the size reduction for low-end devices, you have to modify clang-compile-override.txt to enable -Oz flag in the release build as following:
 141
 142 ```
 143 --- a/src/pal/tools/clang-compiler-override.txt
 144 +++ b/src/pal/tools/clang-compiler-override.txt
 145 @@ -3,13 +3,13 @@ SET (CMAKE_C_FLAGS_DEBUG_INIT          "-g -O0")
 146  SET (CLR_C_FLAGS_CHECKED_INIT          "-g -O2")
 147  # Refer to the below instruction to support __thread with -O2/-O3 on Linux/ARM
 148  # https://github.com/dotnet/coreclr/blob/master/Documentation/building/linux-instructions.md
 149 -SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -O3")
 150 +SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -Oz")
 151  SET (CMAKE_C_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
 152
 153  SET (CMAKE_CXX_FLAGS_INIT                "-Wall -Wno-null-conversion -std=c++11")
 154  SET (CMAKE_CXX_FLAGS_DEBUG_INIT          "-g -O0")
 155  SET (CLR_CXX_FLAGS_CHECKED_INIT          "-g -O2")
 156 -SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -O3")
 157 +SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -Oz")
 158  SET (CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
 159
 160  SET (CLR_DEFINES_DEBUG_INIT              DEBUG _DEBUG _DBG URTBLDENV_FRIENDLY=Checked BUILDENV_
 161 ```
 162
 163
 164 If you want to focus on the speed optimization for high-end devices, you have to modify clang-compile-override.txt to enable -Ofast flag in the release build as following:
 165 ```
 166 --- a/src/pal/tools/clang-compiler-override.txt
 167 +++ b/src/pal/tools/clang-compiler-override.txt
 168 @@ -3,13 +3,13 @@ SET (CMAKE_C_FLAGS_DEBUG_INIT          "-g -O0")
 169  SET (CLR_C_FLAGS_CHECKED_INIT          "-g -O2")
 170  # Refer to the below instruction to support __thread with -O2/-O3 on Linux/ARM
 171  # https://github.com/dotnet/coreclr/blob/master/Documentation/building/linux-instructions.md
 172 -SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -O3")
 173 +SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -Ofast")
 174  SET (CMAKE_C_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
 175
 176  SET (CMAKE_CXX_FLAGS_INIT                "-Wall -Wno-null-conversion -std=c++11")
 177  SET (CMAKE_CXX_FLAGS_DEBUG_INIT          "-g -O0")
 178  SET (CLR_CXX_FLAGS_CHECKED_INIT          "-g -O2")
 179 -SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -O3")
 180 +SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -Ofast")
 181  SET (CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
 182
 183  SET (CLR_DEFINES_DEBUG_INIT              DEBUG _DEBUG _DBG URTBLDENV_FRIENDLY=Checked BUILDENV_
 184 ```
 185