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 To match conditions in rusts CI, also set the environment variable `DEPLOY=1`, e.g.:
  20 ```
  21 DEPLOY=1 ./src/ci/docker/run.sh x86_64-gnu
  22 ```
  23
  24 **NOTE**: Re-using the same `obj` dir with different docker images with
  25 the same target triple (e.g. `dist-x86_64-linux` and `dist-various-1`)
  26 may result in strange linker errors, due shared library versions differing between platforms.
  27
  28 If you encounter any issues when using multiple Docker images, try deleting your `obj` directory
  29 before running your command.
  30
  31 ## Filesystem layout
  32
  33 - Each host architecture has its own `host-{arch}` directory, and those
  34   directories contain a subdirectory for each Docker image (plus the `disabled`
  35   subdirectory).
  36 - `host-{arch}/disabled` contains images that are not built on CI.
  37 - `scripts` contains files shared by multiple Docker images.
  38
  39 ## Docker Toolbox on Windows
  40
  41 For Windows before Windows 10, the docker images can be run on Windows via
  42 [Docker Toolbox]. There are several preparation needs to be made before running
  43 a Docker image.
  44
  45 1. Stop the virtual machine from the terminal with `docker-machine stop`
  46
  47 2. If your Rust source is placed outside of `C:\Users\**`, e.g. if you place the
  48     repository in the `E:\rust` folder, please add a shared folder from
  49     VirtualBox by:
  50
  51     1. Select the "default" virtual machine inside VirtualBox, then click
  52         "Settings"
  53     2. Go to "Shared Folders", click "Add shared folder" (the folder icon with
  54         a plus sign), fill in the following information, then click "OK":
  55
  56         * Folder path: `E:\rust`
  57         * Folder name: `e/rust`
  58         * Read-only: ☐ *unchecked*
  59         * Auto-mount: ☑ *checked*
  60         * Make Permanent: ☑ *checked*
  61
  62 3. VirtualBox might not support creating symbolic links inside a shared folder
  63     by default. You can enable it manually by running these from `cmd.exe`:
  64
  65     ```bat
  66     cd "C:\Program Files\Oracle\VirtualBox"
  67     VBoxManage setextradata default VBoxInternal2/SharedFoldersEnableSymlinksCreate/e/rust 1
  68     ::                                                                              ^~~~~~
  69     ::                                                                              folder name
  70     ```
  71
  72 4. Restart the virtual machine from terminal with `docker-machine start`.
  73
  74 To run the image,
  75
  76 1. Launch the "Docker Quickstart Terminal".
  77 2. Execute `./src/ci/docker/run.sh $image_name` as explained at the beginning.
  78
  79 [Docker Toolbox]: https://www.docker.com/products/docker-toolbox
  80
  81 ## Cross toolchains
  82
  83 A number of these images take quite a long time to compile as they're building
  84 whole gcc toolchains to do cross builds with. Much of this is relatively
  85 self-explanatory but some images use [crosstool-ng] which isn't quite as self
  86 explanatory. Below is a description of where these `*.config` files come form,
  87 how to generate them, and how the existing ones were generated.
  88
  89 [crosstool-ng]: https://github.com/crosstool-ng/crosstool-ng
  90
  91 ### Generating a `.config` file
  92
  93 **NOTE:** Existing Dockerfiles can also be a good guide for the process and order
  94 of script execution.
  95
  96 If you have a `linux-cross` image lying around you can use that and skip the
  97 next two steps.
  98
  99 - First we spin up a container and copy all scripts into it. All
 100   these steps are outside the container:
 101
 102 ```
 103 # Note: We use ubuntu:16.04 because that's the "base" of linux-cross Docker
 104 # image, or simply run ./src/ci/docker/run.sh once, which will download the correct
 105 # one and you can check it out with `docker images`
 106 $ docker run -it ubuntu:16.04 bash
 107 # in another terminal:
 108 $ docker ps
 109 CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
 110 cfbec05ed730        ubuntu:16.04        "bash"              16 seconds ago      Up 15 seconds                           drunk_murdock
 111 $ docker cp src/ci/docker/scripts drunk_murdock:/tmp/
 112 ```
 113
 114 - Then inside the container we build crosstool-ng by simply calling the bash
 115   script we copied in the previous step:
 116
 117 ```
 118 $ cd /tmp/scripts
 119 # Download packages necessary for building
 120 $ bash ./cross-apt-packages.sh
 121 # Download and build crosstool-ng
 122 $ bash ./crosstool-ng.sh
 123 ```
 124
 125 - In case you want to adjust or start from an existing config, copy that
 126   to the container. `crosstool-ng` will automatically load `./.config` if
 127   present. Otherwise one can use the TUI to load any config-file.
 128
 129 ```
 130 $ docker cp arm-linux-gnueabi.config drunk_murdock:/tmp/.config
 131 ```
 132
 133 - Now, inside the container run the following command to configure the
 134   toolchain. To get a clue of which options need to be changed check the next
 135   section and come back.
 136
 137 ```
 138 $ cd /tmp/
 139 $ ct-ng menuconfig
 140 ```
 141
 142 - Finally, we retrieve the `.config` file from the container and give it a
 143   meaningful name. This is done outside the container.
 144
 145 ```
 146 $ docker cp drunk_murdock:/tmp/.config arm-linux-gnueabi.config
 147 ```
 148
 149 - Now you can shutdown the container or repeat the two last steps to generate a
 150   new `.config` file.
 151
 152 ### Toolchain configuration
 153
 154 Changes on top of the default toolchain configuration used to generate the
 155 `.config` files in this directory. The changes are formatted as follows:
 156
 157 ```
 158 $category > $option = $value -- $comment
 159 ```
 160
 161 ### `arm-linux-gnueabi.config`
 162
 163 For targets: `arm-unknown-linux-gnueabi`
 164
 165 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 166 - Path and misc options > Patches origin = Bundled only
 167 - Target options > Target Architecture = arm
 168 - Target options > Architecture level = armv6 -- (+)
 169 - Target options > Floating point = software (no FPU) -- (\*)
 170 - Operating System > Target OS = linux
 171 - Operating System > Linux kernel version = 3.2.101
 172 - C-library > glibc version = 2.17.0
 173 - C compiler > gcc version = 8.3.0
 174 - C compiler > C++ = ENABLE -- to cross compile LLVM
 175
 176 ### `arm-linux-gnueabihf.config`
 177
 178 For targets: `arm-unknown-linux-gnueabihf`
 179
 180 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 181 - Path and misc options > Patches origin = Bundled only
 182 - Target options > Target Architecture = arm
 183 - Target options > Architecture level = armv6 -- (+)
 184 - Target options > Use specific FPU = vfp -- (+)
 185 - Target options > Floating point = hardware (FPU) -- (\*)
 186 - Target options > Default instruction set mode = arm -- (+)
 187 - Operating System > Target OS = linux
 188 - Operating System > Linux kernel version = 3.2.101
 189 - C-library > glibc version = 2.17.0
 190 - C compiler > gcc version = 8.3.0
 191 - C compiler > C++ = ENABLE -- to cross compile LLVM
 192
 193 ### `armv7-linux-gnueabihf.config`
 194
 195 For targets: `armv7-unknown-linux-gnueabihf`
 196
 197 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 198 - Path and misc options > Patches origin = Bundled only
 199 - Target options > Target Architecture = arm
 200 - Target options > Suffix to the arch-part = v7
 201 - Target options > Architecture level = armv7-a -- (+)
 202 - Target options > Use specific FPU = vfpv3-d16 -- (\*)
 203 - Target options > Floating point = hardware (FPU) -- (\*)
 204 - Target options > Default instruction set mode = thumb -- (\*)
 205 - Operating System > Target OS = linux
 206 - Operating System > Linux kernel version = 3.2.101
 207 - C-library > glibc version = 2.17.0
 208 - C compiler > gcc version = 8.3.0
 209 - C compiler > C++ = ENABLE -- to cross compile LLVM
 210
 211 (\*) These options have been selected to match the configuration of the arm
 212       toolchains shipped with Ubuntu 15.10
 213 (+) These options have been selected to match the gcc flags we use to compile C
 214     libraries like jemalloc. See the mk/cfg/arm(v7)-uknown-linux-gnueabi{,hf}.mk
 215     file in Rust's source code.
 216
 217 ### `aarch64-linux-gnu.config`
 218
 219 For targets: `aarch64-unknown-linux-gnu`
 220
 221 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 222 - Path and misc options > Use a mirror = ENABLE
 223 - Path and misc options > Base URL = https://ci-mirrors.rust-lang.org/rustc
 224 - Target options > Target Architecture = arm
 225 - Target options > Bitness = 64-bit
 226 - Operating System > Target OS = linux
 227 - Operating System > Linux kernel version = 4.1.49
 228 - Binary utilities > Version of binutils = 2.32
 229 - C-library > glibc version = 2.17 -- aarch64 support was introduced in this version
 230 - C compiler > gcc version = 8.3.0
 231 - C compiler > C++ = ENABLE -- to cross compile LLVM
 232
 233 ### `i586-linux-gnu.config`
 234
 235 For targets: `i586-unknown-linux-gnu`
 236
 237 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 238 - Path and misc options > Patches origin = Bundled only
 239 - Target options > Target Architecture = x86
 240 - Target options > Architecture level = i586
 241 - Target options > Target CFLAGS = -Wa,-mrelax-relocations=no
 242 - Operating System > Target OS = linux
 243 - Operating System > Linux kernel version = 3.2.101
 244 - Binary utilities > Version of binutils = 2.32
 245 - Binary utilities > binutils extra config = --enable-compressed-debug-sections=none -- (\*)
 246 - C-library > glibc version = 2.17.0
 247 - C compiler > gcc version = 8.3.0
 248 - C compiler > C++ = ENABLE
 249
 250 (\*) Compressed debug is enabled by default for gas (assembly) on Linux/x86 targets,
 251      but that makes our `compiler_builtins` incompatible with binutils < 2.32.
 252
 253 ### `mips-linux-gnu.config`
 254
 255 For targets: `mips-unknown-linux-gnu`
 256
 257 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 258 - Path and misc options > Use a mirror = ENABLE
 259 - Path and misc options > Base URL = https://ci-mirrors.rust-lang.org/rustc
 260 - Path and misc options > Patches origin = Bundled, then local
 261 - Path and misc options > Local patch directory = /tmp/patches
 262 - Target options > Target Architecture = mips
 263 - Target options > ABI = o32
 264 - Target options > Endianness = Big endian
 265 - Target options > Bitness = 32-bit
 266 - Target options > Architecture level = mips32r2
 267 - Operating System > Target OS = linux
 268 - Operating System > Linux kernel version = 4.4.174
 269 - Binary utilities > Version of binutils = 2.32
 270 - C-library > glibc version = 2.23
 271 - C compiler > gcc version = 8.3.0
 272 - C compiler > gcc extra config = --with-fp-32=xx --with-odd-spreg-32=no
 273 - C compiler > C++ = ENABLE -- to cross compile LLVM
 274
 275 ### `mipsel-linux-gnu.config`
 276
 277 For targets: `mipsel-unknown-linux-gnu`
 278
 279 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 280 - Path and misc options > Use a mirror = ENABLE
 281 - Path and misc options > Base URL = https://ci-mirrors.rust-lang.org/rustc
 282 - Path and misc options > Patches origin = Bundled, then local
 283 - Path and misc options > Local patch directory = /tmp/patches
 284 - Target options > Target Architecture = mips
 285 - Target options > ABI = o32
 286 - Target options > Endianness = Little endian
 287 - Target options > Bitness = 32-bit
 288 - Target options > Architecture level = mips32r2
 289 - Operating System > Target OS = linux
 290 - Operating System > Linux kernel version = 4.4.174
 291 - Binary utilities > Version of binutils = 2.32
 292 - C-library > glibc version = 2.23
 293 - C compiler > gcc version = 8.3.0
 294 - C compiler > gcc extra config = --with-fp-32=xx --with-odd-spreg-32=no
 295 - C compiler > C++ = ENABLE -- to cross compile LLVM
 296
 297 ### `mips64-linux-gnu.config`
 298
 299 For targets: `mips64-unknown-linux-gnuabi64`
 300
 301 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 302 - Path and misc options > Use a mirror = ENABLE
 303 - Path and misc options > Base URL = https://ci-mirrors.rust-lang.org/rustc
 304 - Path and misc options > Patches origin = Bundled, then local
 305 - Path and misc options > Local patch directory = /tmp/patches
 306 - Target options > Target Architecture = mips
 307 - Target options > ABI = n64
 308 - Target options > Endianness = Big endian
 309 - Target options > Bitness = 64-bit
 310 - Target options > Architecture level = mips64r2
 311 - Operating System > Target OS = linux
 312 - Operating System > Linux kernel version = 4.4.174
 313 - Binary utilities > Version of binutils = 2.32
 314 - C-library > glibc version = 2.23
 315 - C compiler > gcc version = 8.3.0
 316 - C compiler > C++ = ENABLE -- to cross compile LLVM
 317
 318 ### `mips64el-linux-gnu.config`
 319
 320 For targets: `mips64el-unknown-linux-gnuabi64`
 321
 322 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 323 - Path and misc options > Use a mirror = ENABLE
 324 - Path and misc options > Base URL = https://ci-mirrors.rust-lang.org/rustc
 325 - Path and misc options > Patches origin = Bundled, then local
 326 - Path and misc options > Local patch directory = /tmp/patches
 327 - Target options > Target Architecture = mips
 328 - Target options > ABI = n64
 329 - Target options > Endianness = Little endian
 330 - Target options > Bitness = 64-bit
 331 - Target options > Architecture level = mips64r2
 332 - Operating System > Target OS = linux
 333 - Operating System > Linux kernel version = 4.4.174
 334 - Binary utilities > Version of binutils = 2.32
 335 - C-library > glibc version = 2.23
 336 - C compiler > gcc version = 8.3.0
 337 - C compiler > C++ = ENABLE -- to cross compile LLVM
 338
 339 ### `powerpc-linux-gnu.config`
 340
 341 For targets: `powerpc-unknown-linux-gnu`
 342
 343 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 344 - Path and misc options > Use a mirror = ENABLE
 345 - Path and misc options > Base URL = https://ci-mirrors.rust-lang.org/rustc
 346 - Target options > Target Architecture = powerpc
 347 - Target options > Emit assembly for CPU = powerpc -- pure 32-bit PowerPC
 348 - Operating System > Target OS = linux
 349 - Operating System > Linux kernel version = 3.2.101
 350 - Binary utilities > Version of binutils = 2.30
 351 - C-library > glibc version = 2.17 -- ~RHEL7 glibc
 352 - C compiler > gcc version = 8.3.0
 353 - C compiler > C++ = ENABLE -- to cross compile LLVM
 354
 355 ### `powerpc64-linux-gnu.config`
 356
 357 For targets: `powerpc64-unknown-linux-gnu`
 358
 359 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 360 - Path and misc options > Use a mirror = ENABLE
 361 - Path and misc options > Base URL = https://ci-mirrors.rust-lang.org/rustc
 362 - Target options > Target Architecture = powerpc
 363 - Target options > Bitness = 64-bit
 364 - Target options > Emit assembly for CPU = power4 -- (+)
 365 - Target options > Tune for CPU = power6 -- (+)
 366 - Operating System > Target OS = linux
 367 - Operating System > Linux kernel version = 3.2.101
 368 - Binary utilities > Version of binutils = 2.32
 369 - C-library > glibc version = 2.17 -- ~RHEL7 glibc
 370 - C compiler > gcc version = 8.3.0
 371 - C compiler > C++ = ENABLE -- to cross compile LLVM
 372
 373 (+) These CPU options match the configuration of the toolchains in RHEL6.
 374
 375 ### `s390x-linux-gnu.config`
 376
 377 For targets: `s390x-unknown-linux-gnu`
 378
 379 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 380 - Path and misc options > Use a mirror = ENABLE
 381 - Path and misc options > Base URL = https://ci-mirrors.rust-lang.org/rustc
 382 - Target options > Target Architecture = s390
 383 - Target options > Bitness = 64-bit
 384 - Operating System > Target OS = linux
 385 - Operating System > Linux kernel version = 3.2.101
 386 - Binary utilities > Version of binutils = 2.32
 387 - C-library > glibc version = 2.17 -- ~RHEL7 glibc
 388 - C compiler > gcc version = 8.3.0
 389 - C compiler > gcc extra config = --with-arch=z10 -- LLVM's minimum support
 390 - C compiler > C++ = ENABLE -- to cross compile LLVM