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
  42 ([#15074](https://github.com/dotnet/coreclr/issues/15074)), so for ARM you must
  43 use clang-4.0 or higher.  Moreover, when building with clang-5.0, the
  44 following errors occur:
  45
  46 ```
  47 coreclr/src/debug/inc/arm/primitives.h:66:1: error: __declspec attribute 'selectany' is
  48       not supported [-Werror,-Wignored-attributes]
  49 ```
  50
  51 This is fixed in clang-5.0.2, which can be installed from the apt
  52 repository listed below.
  53
  54 For other version of Debian/Ubuntu, please visit http://apt.llvm.org/.
  55
  56 Then install the packages you need:
  57
  58     ~$ 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
  59
  60 The lldb 3.9 package needs a lib file symbolic link fixed:
  61
  62     cd /usr/lib/llvm-3.9/lib
  63     sudo ln -s ../../x86_64-linux-gnu/liblldb-3.9.so.1 liblldb-3.9.so.1
  64
  65 You now have all the required components.
  66
  67 If you are using Fedora, then you will need to install the following packages:
  68
  69     ~$ sudo dnf install llvm cmake clang lldb-devel libunwind-devel lttng-ust-devel libicu-devel numactl-devel
  70
  71 Git Setup
  72 ---------
  73
  74 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.
  75
  76 Set the maximum number of file-handles
  77 --------------------------------------
  78
  79 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`.
  80
  81 On Fedora:
  82
  83 `$ sudo dnf install mono-devel`
  84
  85 Build the Runtime and Microsoft Core Library
  86 =============================================
  87
  88 To build the runtime on Linux, run build.sh from the root of the coreclr repository:
  89
  90 ```
  91 ellismg@linux:~/git/coreclr$ ./build.sh
  92 ```
  93
  94 After the build is completed, there should some files placed in `bin/Product/Linux.x64.Debug`.  The ones we are interested in are:
  95
  96 * `corerun`: The command line host.  This program loads and starts the CoreCLR runtime and passes the managed program you want to run to it.
  97 * `libcoreclr.so`: The CoreCLR runtime itself.
  98 * `System.Private.CoreLib.dll`: Microsoft Core Library.
  99
 100 Build the Framework
 101 ===================
 102
 103 ```
 104 ellismg@linux:~/git/corefx$ ./build.sh
 105 ```
 106
 107 After the build is complete you will be able to find the output in the `bin` folder.
 108
 109 Build for ARM/Linux
 110 ===================
 111
 112 The CI system and official builds use Docker to build ARM for Linux (for example, see the latest build [here](https://ci.dot.net/job/dotnet_coreclr/job/master/job/arm_cross_checked_ubuntu/lastSuccessfulBuild/consoleText)). The Docker container has pre-built rootfs directories containing the required tools. To build this way, do the following:
 113
 114 * Install Docker, probably Community Edition, on Windows, Mac, or Linux, from https://www.docker.com/. Some useful post-install setup is:
 115   * Linux: add your user to the docker group, this will avoid running docker with `sudo`:
 116
 117     `sudo usermod -a <your account name> -G docker`
 118
 119   * Windows: switch to Linux containers. This can be done by right clicking on the Docker icon in the lower right corner and clicking "Switch to Linux containers".
 120 * Build using the Docker container (this is a `bash` script, for simplicity):
 121
 122 ```
 123 ROOT=/Users/me/git/coreclr
 124 DOCKER_ARGS="run -i --rm -v ${ROOT}:/mnt/coreclr -w /mnt/coreclr -e ROOTFS_DIR=/crossrootfs/arm -e CAC_ROOTFS_DIR=/crossrootfs/x86 microsoft/dotnet-buildtools-prereqs:ubuntu-14.04-cross-e435274-20180426002420"
 125 docker ${DOCKER_ARGS} /mnt/coreclr/build.sh arm checked cross crosscomponent
 126 docker ${DOCKER_ARGS} /mnt/coreclr/build-test.sh arm checked cross generatelayoutonly
 127 ```
 128
 129 Make sure you update the `ROOT` environment to point to your git clone of the coreclr repo.
 130
 131 The current Docker tag being used by the CI can be found in the `getDockerImageName` function in the [netci.groovy](https://github.com/dotnet/coreclr/blob/master/netci.groovy) file.
 132
 133 Libunwind issue
 134 ---------------
 135 ARM libunwind versions before 1.3 require a fix. The fix allows libunwind not to break when it is ordered to access inaccessible memory locations. See [this](https://github.com/dotnet/coreclr/pull/3923) issue for history.
 136
 137 If required, first import the patch from the libunwind upstream: http://git.savannah.gnu.org/gitweb/?p=libunwind.git;a=commit;h=770152268807e460184b4152e23aba9c86601090.
 138
 139 Then, expand the coverage of the upstream patch by:
 140
 141 ```
 142 diff --git a/src/arm/Ginit.c b/src/arm/Ginit.c
 143 index 1ed3dbf..c643032 100644
 144 --- a/src/arm/Ginit.c
 145 +++ b/src/arm/Ginit.c
 146 @@ -128,6 +128,11 @@ access_mem (unw_addr_space_t as, unw_word_t addr, unw_word_t *val, int write,
 147  {
 148    if (write)
 149      {
 150 +      /* validate address */
 151 +      const struct cursor *c = (const struct cursor *) arg;
 152 +      if (c && validate_mem(addr))
 153 +        return -1;
 154 +
 155        Debug (16, "mem[%x] <- %x\n", addr, *val);
 156        *(unw_word_t *) addr = *val;
 157      }
 158 ```
 159
 160 Additional optimization levels for ARM/Linux: -Oz and -Ofast
 161 ------------------------------------------------------------
 162
 163 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.
 164
 165 | **Content** | **Build Mode** | **Clang/LLVM (Linux)** |
 166 | --- | --- | --- |
 167 | -O0 | Debug | Disable optimization to generate the most debuggable code |
 168 | -O1 | - | Optimize for code size and execution time |
 169 | -O2 | Checked | Optimize more for code size and execution time |
 170 | -O3 | Release | Optimize more for code size and execution time to make program run faster |
 171 | -Oz | - | Optimize more to reduce code size further |
 172 | -Ofast | - | Enable all the optimizations from O3 along with other aggressive optimizations |
 173
 174 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:
 175
 176 ```
 177 --- a/src/pal/tools/clang-compiler-override.txt
 178 +++ b/src/pal/tools/clang-compiler-override.txt
 179 @@ -3,13 +3,13 @@ SET (CMAKE_C_FLAGS_DEBUG_INIT          "-g -O0")
 180  SET (CLR_C_FLAGS_CHECKED_INIT          "-g -O2")
 181  # Refer to the below instruction to support __thread with -O2/-O3 on Linux/ARM
 182  # https://github.com/dotnet/coreclr/blob/master/Documentation/building/linux-instructions.md
 183 -SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -O3")
 184 +SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -Oz")
 185  SET (CMAKE_C_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
 186
 187  SET (CMAKE_CXX_FLAGS_INIT                "-Wall -Wno-null-conversion -std=c++11")
 188  SET (CMAKE_CXX_FLAGS_DEBUG_INIT          "-g -O0")
 189  SET (CLR_CXX_FLAGS_CHECKED_INIT          "-g -O2")
 190 -SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -O3")
 191 +SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -Oz")
 192  SET (CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
 193
 194  SET (CLR_DEFINES_DEBUG_INIT              DEBUG _DEBUG _DBG URTBLDENV_FRIENDLY=Checked BUILDENV_
 195 ```
 196
 197
 198 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:
 199 ```
 200 --- a/src/pal/tools/clang-compiler-override.txt
 201 +++ b/src/pal/tools/clang-compiler-override.txt
 202 @@ -3,13 +3,13 @@ SET (CMAKE_C_FLAGS_DEBUG_INIT          "-g -O0")
 203  SET (CLR_C_FLAGS_CHECKED_INIT          "-g -O2")
 204  # Refer to the below instruction to support __thread with -O2/-O3 on Linux/ARM
 205  # https://github.com/dotnet/coreclr/blob/master/Documentation/building/linux-instructions.md
 206 -SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -O3")
 207 +SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -Ofast")
 208  SET (CMAKE_C_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
 209
 210  SET (CMAKE_CXX_FLAGS_INIT                "-Wall -Wno-null-conversion -std=c++11")
 211  SET (CMAKE_CXX_FLAGS_DEBUG_INIT          "-g -O0")
 212  SET (CLR_CXX_FLAGS_CHECKED_INIT          "-g -O2")
 213 -SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -O3")
 214 +SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -Ofast")
 215  SET (CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
 216
 217  SET (CLR_DEFINES_DEBUG_INIT              DEBUG _DEBUG _DBG URTBLDENV_FRIENDLY=Checked BUILDENV_
 218 ```