Documentation/building/linux-instructions.md

   1 Build CoreCLR on Linux
   2 ======================
   3
   4 This guide will walk you through building CoreCLR on Linux.  Before building there is environment setup that needs to happen to pull in all the dependencies required by the build.  There are two suggested ways to go about doing this. First you are able to use the Docker environments provided by https://github.com/dotnet/dotnet-buildtools-prereqs-docker, or you can set up the environment yourself. The documentation will go over both ways of building. Note that using docker only allows you to leverage our existing images which have a setup environment.
   5
   6 [Build using Docker](#Build-using-Docker)
   7
   8 [Build with own environment](#Environment)
   9
  10 Build using Docker
  11 ==================
  12
  13 Install Docker, see https://docs.docker.com/install/
  14
  15 Building using Docker will require that you choose the correct image for your environment. Note that the OS is strictly speaking not extremely important, for example if you are on Ubuntu 18.04 and build using the Ubuntu 16.04 x64 image there should be no issues. The target architecture is more important, as building arm32 using the x64 image will not work, there will be missing rootfs components required by the build. See [Docker Images](#Docker-Images) for more information on choosing an image to build with.
  16
  17 Please note that when choosing an image choosing the same image as the host os you are running on you willa allow you to run the product/tests outside of the docker container you built in.
  18
  19 Once you have chosen an image the build is one command run from the root of the coreclr repository:
  20
  21 ```sh
  22 docker run --rm -v /home/dotnet-bot/coreclr:/coreclr -w /coreclr mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-16.04-c103199-20180628134544 ./build.sh
  23 ```
  24
  25 Dissecting the command:
  26
  27 `--rm: erase the created container after use`
  28
  29 `-v: mount the coreclr repository under /coreclr`
  30
  31 `-w: set /coreclr as working directory for the container`
  32
  33 `mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-16.04-c103199-20180628134544: image name`
  34
  35 `./build.sh: command to be run in the container`
  36
  37 If you are attempting to cross build for arm/arm64 then use the crossrootfs location to set the ROOTFS_DIR. The command would add `-e ROOTFS_DIR=<crossrootfs location>`. See [Docker Images](#Docker-Images) for the crossrootfs location. In addition you will need to specify `cross`.
  38
  39 ```sh
  40 docker run --rm -v /home/dotnet-bot/coreclr:/coreclr -w /coreclr -e ROOTFS_DIR=/crossrootfs/arm64 mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-16.04-cross-arm64-a3ae44b-20180315221921 ./build.sh arm64 cross
  41 ```
  42
  43 Note that instructions on building the crossrootfs location can be found at https://github.com/dotnet/coreclr/blob/master/Documentation/building/cross-building.md. These instructions are suggested only if there are plans to change the rootfs, or the Docker images for arm/arm64 are insufficient for you build.
  44
  45 Docker Images
  46 =============
  47
  48 | OS                          | Target Arch     | Image location                                                                                      | crossrootfs location | Clang Version |
  49 | --------------------------- | --------------- | --------------------------------------------------------------------------------------------------- | -------------------- | ------------- |
  50 | Ubuntu 16.04                | x64             | `mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-16.04-c103199-20180628134544`                   | -                    | -             |
  51 | Alpine                      | x64             | `mcr.microsoft.com/dotnet-buildtools/prereqs:alpine-3.6-e2521f8-20180716231200`                     | -                    | -             |
  52 | CentOS 6 (build for RHEL 6) | x64             | `mcr.microsoft.com/dotnet-buildtools/prereqs:centos-6-376e1a3-20174311014331`                       | -                    | -             |
  53 | CentOS 7 (build for RHEL 7) | x64             | `mcr.microsoft.com/dotnet-buildtools/prereqs:centos-7-d485f41-20173404063424`                       | -                    | -             |
  54 | Ubuntu 16.04                | arm32(armhf)    | `mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-16.04-cross-14.04-23cacb0-20190528233931`             | `/crossrootfs/arm`   | -             |
  55 | Ubuntu 16.04                | arm64 (arm64v8) | `mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-16.04-cross-arm64-a3ae44b-20180315221921`       | `/crossrootfs/arm64` | -             |
  56 | Alpine                      | arm64 (arm64v8) | `mcr.microsoft.com/dotnet-buildtools/prereqs:ubuntu-16.04-cross-arm64-alpine10fcdcf-20190208200917` | `/crossrootfs/arm64` | -clang5.0     |
  57
  58 Environment
  59 ===========
  60
  61 These instructions are written assuming the Ubuntu 16.04/18.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 16.04/18.04 LTS.
  62
  63 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)).
  64
  65 Toolchain Setup
  66 ---------------
  67
  68 Install the following packages for the toolchain:
  69
  70 - cmake
  71 - llvm-3.9
  72 - clang-3.9
  73 - lldb-3.9
  74 - liblldb-3.9-dev
  75 - libunwind8
  76 - libunwind8-dev
  77 - gettext
  78 - libicu-dev
  79 - liblttng-ust-dev
  80 - libcurl4-openssl-dev
  81 - libssl-dev
  82 - libkrb5-dev
  83 - libnuma-dev (optional, enables numa support)
  84
  85 Note: ARM clang has a known issue with CompareExchange
  86 ([#15074](https://github.com/dotnet/coreclr/issues/15074)), so for ARM you must
  87 use clang-4.0 or higher.  Moreover, when building with clang-5.0, the
  88 following errors occur:
  89
  90 ```
  91 coreclr/src/debug/inc/arm/primitives.h:66:1: error: __declspec attribute 'selectany' is
  92       not supported [-Werror,-Wignored-attributes]
  93 ```
  94
  95 This is fixed in clang-5.0.2, which can be installed from the apt
  96 repository listed below.
  97
  98 For other version of Debian/Ubuntu, please visit http://apt.llvm.org/.
  99
 100 Then install the packages you need:
 101
 102     ~$ 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
 103
 104 You now have all the required components.
 105
 106 If you are using Fedora, then you will need to install the following packages:
 107
 108     ~$ sudo dnf install llvm cmake clang lldb-devel libunwind-devel lttng-ust-devel libicu-devel numactl-devel
 109
 110 Git Setup
 111 ---------
 112
 113 This guide assumes that you've cloned the coreclr repository.
 114
 115 Set the maximum number of file-handles
 116 --------------------------------------
 117
 118 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`.
 119
 120 On Fedora:
 121
 122 `$ sudo dnf install mono-devel`
 123
 124 Build the Runtime and Microsoft Core Library
 125 =============================================
 126
 127 To build the runtime on Linux, run build.sh from the root of the coreclr repository:
 128
 129 ```
 130 ./build.sh
 131 ```
 132
 133 After the build is completed, there should some files placed in `bin/Product/Linux.x64.Debug`.  The ones we are interested in are:
 134
 135 * `corerun`: The command line host.  This program loads and starts the CoreCLR runtime and passes the managed program you want to run to it.
 136 * `libcoreclr.so`: The CoreCLR runtime itself.
 137 * `System.Private.CoreLib.dll`: Microsoft Core Library.
 138
 139 Create the Core_Root
 140 ===================
 141
 142 The Core_Root folder will have the built binaries, from `build.sh` and it will also include the CoreFX packages required to run tests.
 143
 144 ```
 145 ./build-test.sh generatelayoutonly
 146 ```
 147
 148 After the build is complete you will be able to find the output in the `bin/tests/Linux.x64.Debug/Tests/Core_Root` folder.
 149
 150 Running a single test
 151 ===================
 152
 153 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 an environment variable to the Core_Root folder.
 154
 155 ```sh
 156 export CORE_ROOT=/home/dotnet-bot/coreclr/bin/tests/Linux.x64.Debug/Tests/Core_Root
 157 $CORE_ROOT/corerun hello_world.dll
 158 ```