You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/tests/docker.md
+32-33
Original file line number
Diff line number
Diff line change
@@ -1,36 +1,44 @@
1
1
# Testing with Docker
2
2
3
-
The Rust tree includes [Docker] image definitions for the platforms used on
4
-
GitHub Actions in [`src/ci/docker`].
5
-
The script [`src/ci/docker/run.sh`] is used to build the Docker image, run it,
6
-
build Rust within the image, and run the tests.
7
-
8
-
You can run these images on your local development machine. This can be
9
-
helpful to test environments different from your local system. First you will
3
+
The [`src/ci/docker`] directory includes [Docker] image definitions for Linux-based jobs executed on GitHub Actions (non-Linux jobs run outside Docker). You can run these jobs on your local development machine, which can be
4
+
helpful to test environments different from your local system. You will
10
5
need to install Docker on a Linux, Windows, or macOS system (typically Linux
11
6
will be much faster than Windows or macOS because the latter use virtual
12
-
machines to emulate a Linux environment). To enter interactive mode which will
13
-
start a bash shell in the container, run `src/ci/docker/run.sh --dev <IMAGE>`
14
-
where `<IMAGE>` is one of the directory names in `src/ci/docker` (for example
15
-
`x86_64-gnu` is a fairly standard Ubuntu environment).
16
-
17
-
The docker script will mount your local Rust source tree in read-only mode,
18
-
and an `obj` directory in read-write mode. All of the compiler artifacts will
19
-
be stored in the `obj` directory. The shell will start out in the `obj`
20
-
directory. From there, you can run `../src/ci/run.sh` which will run the build
21
-
as defined by the image.
22
-
23
-
Alternatively, you can run individual commands to do specific tasks. For
24
-
example, you can run `../x test tests/ui` to just run UI tests.
25
-
Note that there is some configuration in the [`src/ci/run.sh`] script that you
26
-
may need to recreate. Particularly, set `submodules = false` in your
27
-
`config.toml` so that it doesn't attempt to modify the read-only directory.
7
+
machines to emulate a Linux environment).
8
+
9
+
Jobs running in CI are configured through a set of bash scripts, and it is not always trivial to reproduce their behavior locally. If you want to run a CI job locally in the simplest way possible, you can use a provided helper Python script that tries to replicate what happens on CI as closely as possible:
Some additional notes about using the Docker images:
17
+
If the above script does not work for you, you would like to have more control of the Docker image execution, or you want to understand what exactly happens during Docker job execution, then continue reading below.
30
18
19
+
## The `run.sh` script
20
+
The [`src/ci/docker/run.sh`] script is used to build a specific Docker image, run it,
21
+
build Rust within the image, and either run tests or prepare a set of archives designed for distribution. The script will mount your local Rust source tree in read-only mode, and an `obj` directory in read-write mode. All the compiler artifacts will be stored in the `obj` directory. The shell will start out in the `obj`directory. From there, it will execute `../src/ci/run.sh` which starts the build as defined by the Docker image.
22
+
23
+
You can run `src/ci/docker/run.sh <image-name>` directly. A few important notes regarding the `run.sh` script:
24
+
- There is some configuration used on CI that you may need to recreate. In particular, set `submodules = false` in your `config.toml` so that it doesn't attempt to modify the read-only directory.
25
+
-`<image-name>` corresponds to a single directory located in one of the `src/ci/docker/host-*` directories. Note that image name does not necessarily correspond to a job name, as some jobs execute the same image, but with different environment variables or Docker build arguments (this is a part of the complexity that makes it difficult to run CI jobs locally).
26
+
- If you are executing a "dist" job (job beginning with `dist-`), you should set the `DEPLOY=1` environment variable.
27
+
- If you are executing an "alternative dist" job (job beginning with `dist-` and ending with `-alt`), you should set the `DEPLOY_ALT=1` environment variable.
31
28
- Some of the std tests require IPv6 support. Docker on Linux seems to have it
32
29
disabled by default. Run the commands in [`enable-docker-ipv6.sh`] to enable
33
30
IPv6 before creating the container. This only needs to be done once.
31
+
32
+
### Interactive mode
33
+
34
+
Sometimes, it can be useful to build a specific Docker image, and then run custom commands inside it, so that you can experiment with how the given system behaves. You can do that using an interactive mode, which will
35
+
start a bash shell in the container, using `src/ci/docker/run.sh --dev <image-name>`.
36
+
37
+
When inside the Docker container, you can run individual commands to do specific tasks. For
38
+
example, you can run `../x test tests/ui` to just run UI tests.
39
+
40
+
Some additional notes about using the interactive mode:
41
+
34
42
- The container will be deleted automatically when you exit the shell, however
35
43
the build artifacts persist in the `obj` directory. If you are switching
36
44
between different Docker images, the artifacts from previous environments
@@ -45,15 +53,6 @@ Some additional notes about using the Docker images:
45
53
containers. With the container name, run `docker exec -it <CONTAINER>
46
54
/bin/bash` where `<CONTAINER>` is the container name like `4ba195e95cef`.
47
55
48
-
The approach described above is a relatively low-level interface for running the Docker images
49
-
directly. If you want to run a full CI Linux job locally with Docker, in a way that is as close to CI as possible, you can use the following command:
0 commit comments