Advanced Usage of `run.sh` and Interactive Mode

You can run `src/ci/docker/run.sh <image-name>` directly. A few important notes regarding the `run.sh` script: - When executed on CI, the script expects that all submodules are checked out. If some submodule that is accessed by the job is not available, the build will result in an error. You should thus make sure that you have all required submodules checked out locally. You can either do that manually through git, or set `submodules = true` in your `bootstrap.toml` and run a command such as `x build` to let bootstrap download the most important submodules (this might not be enough for the given CI job that you are trying to execute though). - `<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). - If you are executing a "dist" job (job beginning with `dist-`), you should set the `DEPLOY=1` environment variable. - 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. - Some of the std tests require IPv6 support. Docker on Linux seems to have it disabled by default. Run the commands in [`enable-docker-ipv6.sh`] to enable IPv6 before creating the container. This only needs to be done once. ### Interactive mode 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 start a bash shell in the container, using `src/ci/docker/run.sh --dev <image-name>`. When inside the Docker container, you can run individual commands to do specific tasks. For example, you can run `../x test tests/ui` to just run UI tests. Some additional notes about using the interactive mode: - The container will be deleted automatically when you exit the shell, however the build artifacts persist in the `obj` directory. If you are switching between different Docker images, the artifacts from previous environments stored in the `obj` directory may confuse the build system. Sometimes you will need to delete parts or all of the `obj` directory before building inside the container. - The container is bare-bones, with only a minimal set of packages. You may want to install some things like `apt install less vim`. - You can open multiple shells in the container. First you need the container name (a short hash), which is displayed in the shell prompt, or you can run `docker container ls` outside of the container to list the available containers. With the container name, run `docker exec -it <CONTAINER> /bin/bash` where `<CONTAINER>` is the container name like `4ba195e95cef`. The approach described above is a relatively low-level interface for running the Docker images 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: ```bash cargo run --manifest-path src/ci/citool/Cargo.toml run-local <job-name> # For example: cargo run --manifest-path src/ci/citool/Cargo.toml run-local dist-x86_64-linux-alt ```

This section provides additional details on using `src/ci/docker/run.sh`, including setting environment variables for 'dist' jobs, enabling IPv6 support, and utilizing interactive mode (`--dev`) for custom commands inside the Docker image. It also covers managing build artifacts in the `obj` directory, installing additional packages in the container, and opening multiple shells. Finally, it introduces a higher-level command using `cargo run` to run a full CI Linux job locally, closely replicating the CI environment.