src/ci/docker/README.md

   1 # Docker images for CI
   2
   3 This folder contains a bunch of docker images used by the continuous integration
   4 (CI) of Rust. An script is accompanied (`run.sh`) with these images to actually
   5 execute them. To test out an image execute:
   6
   7 ```
   8 ./src/ci/docker/run.sh $image_name
   9 ```
  10
  11 for example:
  12
  13 ```
  14 ./src/ci/docker/run.sh x86_64-gnu
  15 ```
  16
  17 Images will output artifacts in an `obj` dir at the root of a repository.
  18
  19 **NOTE**: Re-using the same `obj` dir with different docker images with
  20 the same target triple (e.g. `dist-x86_64-linux` and `dist-various-1`)
  21 may result in strange linker errors, due shared library versions differing between platforms.
  22
  23 If you encounter any issues when using multiple Docker images, try deleting your `obj` directory
  24 before running your command.
  25
  26 ## Filesystem layout
  27
  28 - Each directory, excluding `scripts` and `disabled`, corresponds to a docker image
  29 - `scripts` contains files shared by docker images
  30 - `disabled` contains images that are not built on CI
  31
  32 ## Docker Toolbox on Windows
  33
  34 For Windows before Windows 10, the docker images can be run on Windows via
  35 [Docker Toolbox]. There are several preparation needs to be made before running
  36 a Docker image.
  37
  38 1. Stop the virtual machine from the terminal with `docker-machine stop`
  39
  40 2. If your Rust source is placed outside of `C:\Users\**`, e.g. if you place the
  41     repository in the `E:\rust` folder, please add a shared folder from
  42     VirtualBox by:
  43
  44     1. Select the "default" virtual machine inside VirtualBox, then click
  45         "Settings"
  46     2. Go to "Shared Folders", click "Add shared folder" (the folder icon with
  47         a plus sign), fill in the following information, then click "OK":
  48
  49         * Folder path: `E:\rust`
  50         * Folder name: `e/rust`
  51         * Read-only: ☐ *unchecked*
  52         * Auto-mount: ☑ *checked*
  53         * Make Permanent: ☑ *checked*
  54
  55 3. VirtualBox might not support creating symbolic links inside a shared folder
  56     by default. You can enable it manually by running these from `cmd.exe`:
  57
  58     ```bat
  59     cd "C:\Program Files\Oracle\VirtualBox"
  60     VBoxManage setextradata default VBoxInternal2/SharedFoldersEnableSymlinksCreate/e/rust 1
  61     ::                                                                              ^~~~~~
  62     ::                                                                              folder name
  63     ```
  64
  65 4. Restart the virtual machine from terminal with `docker-machine start`.
  66
  67 To run the image,
  68
  69 1. Launch the "Docker Quickstart Terminal".
  70 2. Execute `./src/ci/docker/run.sh $image_name` as explained at the beginning.
  71
  72 [Docker Toolbox]: https://www.docker.com/products/docker-toolbox
  73
  74 ## Cross toolchains
  75
  76 A number of these images take quite a long time to compile as they're building
  77 whole gcc toolchains to do cross builds with. Much of this is relatively
  78 self-explanatory but some images use [crosstool-ng] which isn't quite as self
  79 explanatory. Below is a description of where these `*.config` files come form,
  80 how to generate them, and how the existing ones were generated.
  81
  82 [crosstool-ng]: https://github.com/crosstool-ng/crosstool-ng
  83
  84 ### Generating a `.config` file
  85
  86 If you have a `linux-cross` image lying around you can use that and skip the
  87 next two steps.
  88
  89 - First we spin up a container and copy `build_toolchain_root.sh` into it. All
  90   these steps are outside the container:
  91
  92 ```
  93 # Note: We use ubuntu:15.10 because that's the "base" of linux-cross Docker
  94 # image
  95 $ docker run -it ubuntu:15.10 bash
  96 $ docker ps
  97 CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
  98 cfbec05ed730        ubuntu:15.10        "bash"              16 seconds ago      Up 15 seconds                           drunk_murdock
  99 $ docker cp build_toolchain_root.sh drunk_murdock:/
 100 ```
 101
 102 - Then inside the container we build crosstool-ng by simply calling the bash
 103   script we copied in the previous step:
 104
 105 ```
 106 $ bash build_toolchain_root.sh
 107 ```
 108
 109 - Now, inside the container run the following command to configure the
 110   toolchain. To get a clue of which options need to be changed check the next
 111   section and come back.
 112
 113 ```
 114 $ ct-ng menuconfig
 115 ```
 116
 117 - Finally, we retrieve the `.config` file from the container and give it a
 118   meaningful name. This is done outside the container.
 119
 120 ```
 121 $ docker drunk_murdock:/.config arm-linux-gnueabi.config
 122 ```
 123
 124 - Now you can shutdown the container or repeat the two last steps to generate a
 125   new `.config` file.
 126
 127 ### Toolchain configuration
 128
 129 Changes on top of the default toolchain configuration used to generate the
 130 `.config` files in this directory. The changes are formatted as follows:
 131
 132 ```
 133 $category > $option = $value -- $comment
 134 ```
 135
 136 ### `arm-linux-gnueabi.config`
 137
 138 For targets: `arm-unknown-linux-gnueabi`
 139
 140 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 141 - Path and misc options > Patches origin = Bundled, then local
 142 - Path and misc options > Local patch directory = /tmp/patches
 143 - Target options > Target Architecture = arm
 144 - Target options > Architecture level = armv6 -- (+)
 145 - Target options > Floating point = software (no FPU) -- (\*)
 146 - Operating System > Target OS = linux
 147 - Operating System > Linux kernel version = 3.2.72 -- Precise kernel
 148 - C-library > glibc version = 2.16.0
 149 - C compiler > gcc version = 5.2.0
 150 - C compiler > C++ = ENABLE -- to cross compile LLVM
 151
 152 ### `arm-linux-gnueabihf.config`
 153
 154 For targets: `arm-unknown-linux-gnueabihf`
 155
 156 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 157 - Path and misc options > Patches origin = Bundled, then local
 158 - Path and misc options > Local patch directory = /tmp/patches
 159 - Target options > Target Architecture = arm
 160 - Target options > Architecture level = armv6 -- (+)
 161 - Target options > Use specific FPU = vfp -- (+)
 162 - Target options > Floating point = hardware (FPU) -- (\*)
 163 - Target options > Default instruction set mode = arm -- (+)
 164 - Operating System > Target OS = linux
 165 - Operating System > Linux kernel version = 3.2.72 -- Precise kernel
 166 - C-library > glibc version = 2.16.0
 167 - C compiler > gcc version = 5.2.0
 168 - C compiler > C++ = ENABLE -- to cross compile LLVM
 169
 170 ### `armv7-linux-gnueabihf.config`
 171
 172 For targets: `armv7-unknown-linux-gnueabihf`
 173
 174 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 175 - Path and misc options > Patches origin = Bundled only
 176 - Target options > Target Architecture = arm
 177 - Target options > Suffix to the arch-part = v7
 178 - Target options > Architecture level = armv7-a -- (+)
 179 - Target options > Use specific FPU = vfpv3-d16 -- (\*)
 180 - Target options > Floating point = hardware (FPU) -- (\*)
 181 - Target options > Default instruction set mode = thumb -- (\*)
 182 - Operating System > Target OS = linux
 183 - Operating System > Linux kernel version = 3.2.101
 184 - C-library > glibc version = 2.17.0
 185 - C compiler > gcc version = 8.3.0
 186 - C compiler > C++ = ENABLE -- to cross compile LLVM
 187
 188 (\*) These options have been selected to match the configuration of the arm
 189       toolchains shipped with Ubuntu 15.10
 190 (+) These options have been selected to match the gcc flags we use to compile C
 191     libraries like jemalloc. See the mk/cfg/arm(v7)-uknown-linux-gnueabi{,hf}.mk
 192     file in Rust's source code.
 193
 194 ### `aarch64-linux-gnu.config`
 195
 196 For targets: `aarch64-unknown-linux-gnu`
 197
 198 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 199 - Target options > Target Architecture = arm
 200 - Target options > Bitness = 64-bit
 201 - Operating System > Target OS = linux
 202 - Operating System > Linux kernel version = 4.2.6
 203 - C-library > glibc version = 2.17 -- aarch64 support was introduced in this version
 204 - C compiler > gcc version = 5.2.0
 205 - C compiler > C++ = ENABLE -- to cross compile LLVM
 206
 207 ### `powerpc-linux-gnu.config`
 208
 209 For targets: `powerpc-unknown-linux-gnu`
 210
 211 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 212 - Path and misc options > Patches origin = Bundled, then local
 213 - Path and misc options > Local patch directory = /tmp/patches
 214 - Target options > Target Architecture = powerpc
 215 - Target options > Emit assembly for CPU = powerpc -- pure 32-bit PowerPC
 216 - Operating System > Target OS = linux
 217 - Operating System > Linux kernel version = 2.6.32.68 -- ~RHEL6 kernel
 218 - C-library > glibc version = 2.12.2 -- ~RHEL6 glibc
 219 - C compiler > gcc version = 5.2.0
 220 - C compiler > C++ = ENABLE -- to cross compile LLVM
 221
 222 ### `powerpc64-linux-gnu.config`
 223
 224 For targets: `powerpc64-unknown-linux-gnu`
 225
 226 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 227 - Path and misc options > Patches origin = Bundled, then local
 228 - Path and misc options > Local patch directory = /tmp/patches
 229 - Target options > Target Architecture = powerpc
 230 - Target options > Bitness = 64-bit
 231 - Target options > Emit assembly for CPU = power4 -- (+)
 232 - Target options > Tune for CPU = power6 -- (+)
 233 - Operating System > Target OS = linux
 234 - Operating System > Linux kernel version = 2.6.32.68 -- ~RHEL6 kernel
 235 - C-library > glibc version = 2.12.2 -- ~RHEL6 glibc
 236 - C compiler > gcc version = 5.2.0
 237 - C compiler > C++ = ENABLE -- to cross compile LLVM
 238
 239 (+) These CPU options match the configuration of the toolchains in RHEL6.
 240
 241 ### `s390x-linux-gnu.config`
 242
 243 For targets: `s390x-unknown-linux-gnu`
 244
 245 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 246 - Path and misc options > Patches origin = Bundled, then local
 247 - Path and misc options > Local patch directory = /tmp/patches
 248 - Target options > Target Architecture = s390
 249 - Target options > Bitness = 64-bit
 250 - Operating System > Target OS = linux
 251 - Operating System > Linux kernel version = 2.6.32.68 -- ~RHEL6 kernel
 252 - C-library > glibc version = 2.12.2 -- ~RHEL6 glibc
 253 - C compiler > gcc version = 5.2.0
 254 - C compiler > gcc extra config = --with-arch=z10 -- LLVM's minimum support
 255 - C compiler > C++ = ENABLE -- to cross compile LLVM