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 ## Filesystem layout
  20
  21 - Each directory, excluding `scripts` and `disabled`, corresponds to a docker image
  22 - `scripts` contains files shared by docker images
  23 - `disabled` contains images that are not build travis
  24
  25 ## Cross toolchains
  26
  27 A number of these images take quite a long time to compile as they're building
  28 whole gcc toolchains to do cross builds with. Much of this is relatively
  29 self-explanatory but some images use [crosstool-ng] which isn't quite as self
  30 explanatory. Below is a description of where these `*.config` files come form,
  31 how to generate them, and how the existing ones were generated.
  32
  33 [crosstool-ng]: https://github.com/crosstool-ng/crosstool-ng
  34
  35 ### Generating a `.config` file
  36
  37 If you have a `linux-cross` image lying around you can use that and skip the
  38 next two steps.
  39
  40 - First we spin up a container and copy `build_toolchain_root.sh` into it. All
  41   these steps are outside the container:
  42
  43 ```
  44 # Note: We use ubuntu:15.10 because that's the "base" of linux-cross Docker
  45 # image
  46 $ docker run -it ubuntu:15.10 bash
  47 $ docker ps
  48 CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
  49 cfbec05ed730        ubuntu:15.10        "bash"              16 seconds ago      Up 15 seconds                           drunk_murdock
  50 $ docker cp build_toolchain_root.sh drunk_murdock:/
  51 ```
  52
  53 - Then inside the container we build crosstool-ng by simply calling the bash
  54   script we copied in the previous step:
  55
  56 ```
  57 $ bash build_toolchain_root.sh
  58 ```
  59
  60 - Now, inside the container run the following command to configure the
  61   toolchain. To get a clue of which options need to be changed check the next
  62   section and come back.
  63
  64 ```
  65 $ ct-ng menuconfig
  66 ```
  67
  68 - Finally, we retrieve the `.config` file from the container and give it a
  69   meaningful name. This is done outside the container.
  70
  71 ```
  72 $ docker drunk_murdock:/.config arm-linux-gnueabi.config
  73 ```
  74
  75 - Now you can shutdown the container or repeat the two last steps to generate a
  76   new `.config` file.
  77
  78 ### Toolchain configuration
  79
  80 Changes on top of the default toolchain configuration used to generate the
  81 `.config` files in this directory. The changes are formatted as follows:
  82
  83 ```
  84 $category > $option = $value -- $comment
  85 ```
  86
  87 ### `arm-linux-gnueabi.config`
  88
  89 For targets: `arm-unknown-linux-gnueabi`
  90
  91 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
  92 - Target options > Target Architecture = arm
  93 - Target options > Architecture level = armv6 -- (+)
  94 - Target options > Floating point = software (no FPU) -- (\*)
  95 - Operating System > Target OS = linux
  96 - Operating System > Linux kernel version = 3.2.72 -- Precise kernel
  97 - C-library > glibc version = 2.14.1
  98 - C compiler > gcc version = 4.9.3
  99 - C compiler > C++ = ENABLE -- to cross compile LLVM
 100
 101 ### `arm-linux-gnueabihf.config`
 102
 103 For targets: `arm-unknown-linux-gnueabihf`
 104
 105 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 106 - Target options > Target Architecture = arm
 107 - Target options > Architecture level = armv6 -- (+)
 108 - Target options > Use specific FPU = vfp -- (+)
 109 - Target options > Floating point = hardware (FPU) -- (\*)
 110 - Target options > Default instruction set mode = arm -- (+)
 111 - Operating System > Target OS = linux
 112 - Operating System > Linux kernel version = 3.2.72 -- Precise kernel
 113 - C-library > glibc version = 2.14.1
 114 - C compiler > gcc version = 4.9.3
 115 - C compiler > C++ = ENABLE -- to cross compile LLVM
 116
 117 ### `armv7-linux-gnueabihf.config`
 118
 119 For targets: `armv7-unknown-linux-gnueabihf`
 120
 121 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 122 - Target options > Target Architecture = arm
 123 - Target options > Suffix to the arch-part = v7
 124 - Target options > Architecture level = armv7-a -- (+)
 125 - Target options > Use specific FPU = vfpv3-d16 -- (\*)
 126 - Target options > Floating point = hardware (FPU) -- (\*)
 127 - Target options > Default instruction set mode = thumb -- (\*)
 128 - Operating System > Target OS = linux
 129 - Operating System > Linux kernel version = 3.2.72 -- Precise kernel
 130 - C-library > glibc version = 2.14.1
 131 - C compiler > gcc version = 4.9.3
 132 - C compiler > C++ = ENABLE -- to cross compile LLVM
 133
 134 (\*) These options have been selected to match the configuration of the arm
 135       toolchains shipped with Ubuntu 15.10
 136 (+) These options have been selected to match the gcc flags we use to compile C
 137     libraries like jemalloc. See the mk/cfg/arm(v7)-uknown-linux-gnueabi{,hf}.mk
 138     file in Rust's source code.
 139
 140 ## `aarch64-linux-gnu.config`
 141
 142 For targets: `aarch64-unknown-linux-gnu`
 143
 144 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 145 - Target options > Target Architecture = arm
 146 - Target options > Bitness = 64-bit
 147 - Operating System > Target OS = linux
 148 - Operating System > Linux kernel version = 4.2.6
 149 - C-library > glibc version = 2.17 -- aarch64 support was introduced in this version
 150 - C compiler > gcc version = 5.2.0
 151 - C compiler > C++ = ENABLE -- to cross compile LLVM
 152
 153 ## `powerpc-linux-gnu.config`
 154
 155 For targets: `powerpc-unknown-linux-gnu`
 156
 157 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 158 - Path and misc options > Patches origin = Bundled, then local
 159 - Path and misc options > Local patch directory = /tmp/patches
 160 - Target options > Target Architecture = powerpc
 161 - Target options > Emit assembly for CPU = powerpc -- pure 32-bit PowerPC
 162 - Operating System > Target OS = linux
 163 - Operating System > Linux kernel version = 2.6.32.68 -- ~RHEL6 kernel
 164 - C-library > glibc version = 2.12.2 -- ~RHEL6 glibc
 165 - C compiler > gcc version = 4.9.3
 166 - C compiler > C++ = ENABLE -- to cross compile LLVM
 167
 168 ## `powerpc64-linux-gnu.config`
 169
 170 For targets: `powerpc64-unknown-linux-gnu`
 171
 172 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 173 - Path and misc options > Patches origin = Bundled, then local
 174 - Path and misc options > Local patch directory = /tmp/patches
 175 - Target options > Target Architecture = powerpc
 176 - Target options > Bitness = 64-bit
 177 - Target options > Emit assembly for CPU = power4 -- (+)
 178 - Target options > Tune for CPU = power6 -- (+)
 179 - Operating System > Target OS = linux
 180 - Operating System > Linux kernel version = 2.6.32.68 -- ~RHEL6 kernel
 181 - C-library > glibc version = 2.12.2 -- ~RHEL6 glibc
 182 - C compiler > gcc version = 4.9.3
 183 - C compiler > C++ = ENABLE -- to cross compile LLVM
 184
 185 (+) These CPU options match the configuration of the toolchains in RHEL6.
 186
 187 ## `s390x-linux-gnu.config`
 188
 189 For targets: `s390x-unknown-linux-gnu`
 190
 191 - Path and misc options > Prefix directory = /x-tools/${CT\_TARGET}
 192 - Path and misc options > Patches origin = Bundled, then local
 193 - Path and misc options > Local patch directory = /build/patches
 194 - Target options > Target Architecture = s390
 195 - Target options > Bitness = 64-bit
 196 - Operating System > Target OS = linux
 197 - Operating System > Linux kernel version = 2.6.32.68 -- ~RHEL6 kernel
 198 - C-library > glibc version = 2.12.2 -- ~RHEL6 glibc
 199 - C compiler > gcc version = 4.9.3
 200 - C compiler > gcc extra config = --with-arch=z10 -- LLVM's minimum support
 201 - C compiler > C++ = ENABLE -- to cross compile LLVM