]>
Commit | Line | Data |
---|---|---|
32a655c1 SL |
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 | ||
60c5eb7d XL |
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 | ||
7cac9316 XL |
26 | ## Filesystem layout |
27 | ||
28 | - Each directory, excluding `scripts` and `disabled`, corresponds to a docker image | |
29 | - `scripts` contains files shared by docker images | |
416331ca | 30 | - `disabled` contains images that are not built on CI |
7cac9316 | 31 | |
abe05a73 XL |
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" | |
ff7c6d11 | 46 | 2. Go to "Shared Folders", click "Add shared folder" (the folder icon with |
abe05a73 XL |
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* | |
ff7c6d11 | 53 | * Make Permanent: ☑ *checked* |
abe05a73 XL |
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 | ||
32a655c1 SL |
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} | |
9fa01778 XL |
141 | - Path and misc options > Patches origin = Bundled, then local |
142 | - Path and misc options > Local patch directory = /tmp/patches | |
32a655c1 SL |
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 | |
9fa01778 XL |
148 | - C-library > glibc version = 2.16.0 |
149 | - C compiler > gcc version = 5.2.0 | |
32a655c1 SL |
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} | |
9fa01778 XL |
157 | - Path and misc options > Patches origin = Bundled, then local |
158 | - Path and misc options > Local patch directory = /tmp/patches | |
32a655c1 SL |
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 | |
9fa01778 XL |
166 | - C-library > glibc version = 2.16.0 |
167 | - C compiler > gcc version = 5.2.0 | |
32a655c1 SL |
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} | |
e1599b0c | 175 | - Path and misc options > Patches origin = Bundled only |
32a655c1 SL |
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 | |
e1599b0c XL |
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 | |
32a655c1 SL |
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 | ||
abe05a73 | 194 | ### `aarch64-linux-gnu.config` |
32a655c1 SL |
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 | ||
abe05a73 | 207 | ### `powerpc-linux-gnu.config` |
32a655c1 SL |
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 | |
cc61c64b | 215 | - Target options > Emit assembly for CPU = powerpc -- pure 32-bit PowerPC |
32a655c1 SL |
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 | |
9fa01778 | 219 | - C compiler > gcc version = 5.2.0 |
32a655c1 SL |
220 | - C compiler > C++ = ENABLE -- to cross compile LLVM |
221 | ||
abe05a73 | 222 | ### `powerpc64-linux-gnu.config` |
32a655c1 SL |
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 | |
9fa01778 | 236 | - C compiler > gcc version = 5.2.0 |
32a655c1 SL |
237 | - C compiler > C++ = ENABLE -- to cross compile LLVM |
238 | ||
239 | (+) These CPU options match the configuration of the toolchains in RHEL6. | |
240 | ||
abe05a73 | 241 | ### `s390x-linux-gnu.config` |
32a655c1 SL |
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 | |
9fa01778 | 247 | - Path and misc options > Local patch directory = /tmp/patches |
32a655c1 SL |
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 | |
9fa01778 | 253 | - C compiler > gcc version = 5.2.0 |
32a655c1 SL |
254 | - C compiler > gcc extra config = --with-arch=z10 -- LLVM's minimum support |
255 | - C compiler > C++ = ENABLE -- to cross compile LLVM |