From 05645c9c32bfdda617054c50850436a56d92cd2f Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 6 Feb 2024 08:12:45 +0100
Subject: [PATCH 01/20] docs: Add "getting-started"

from the Wiki that details how to get started with using `cross`.
---
 README.md               |   4 +-
 docs/getting-started.md | 123 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 125 insertions(+), 2 deletions(-)
 create mode 100644 docs/getting-started.md

diff --git a/README.md b/README.md
index d15127a1d..e3ad8a107 100644
--- a/README.md
+++ b/README.md
@@ -36,8 +36,8 @@ New contributors are welcome! Please join our [Matrix room] and say hi.
 
 ## Dependencies
 
-See our [Getting Started](https://github.com/cross-rs/cross/wiki/Getting-Started) guide
-for detailed installation instructions.
+See our [Getting Started](./docs/getting-started.md) guide for detailed
+installation instructions.
 
 - [rustup](https://rustup.rs/)
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 000000000..d477aa3dd
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,123 @@
+<!--toc:start-->
+- [Installing Cross](#installing-cross)
+    - [Installing Rust via Rustup](#installing-rust-via-rustup)
+    - [Installing Cross](#installing-cross)
+- [Installing A Container Engine](#installing-a-container-engine)
+- [Cross-Compiling Your First Package](#cross-compiling-your-first-package)
+<!--toc:end-->
+
+New to cross? Cross-compilation? Container engines? Here's how to get up-and-running.
+
+# Installing Cross
+
+## Installing Rust via Rustup
+
+`cross` requires a `rustup` installation of Rust. To do so, the recommended
+instructions are documented [here](https://www.rust-lang.org/tools/install),
+but might differ on some platforms. For UNIX-like systems, run the following
+command in a terminal and follow the instructions to install Rust and add Rust
+to the path:
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+On Windows, download
+[rustup-init.exe](https://static.rust-lang.org/rustup/dist/i686-pc-windows-gnu/rustup-init.exe)
+or following the [other installation
+methods](https://forge.rust-lang.org/infra/other-installation-methods.html),
+say, to install from a package manager.
+
+On some platforms, such as NixOS, you might need to use a package manager since
+the default `rustup` install will fail. On NixOS, you should run the following,
+which will install `rustup` and the latest `stable` release of Rust.
+
+```bash
+nix-env -i rustup
+rustup toolchain install stable
+```
+
+Note that you might need additional tools on some platforms to get `rustc` and
+`cargo` working. On UNIX-like systems, this generally means an install of GCC
+or Clang. For example, on NixOS you will likely need to install GCC via
+`nix-env -i gcc` and then go into a GCC and Rust shell (`nix-shell -p gcc
+rustup`). On Alpine, you'll need to run `apk add libgcc gcc musl-dev`. Exact
+instructions will differ by OS and Linux distro, feel free to ask on the
+[discussion](https://github.com/cross-rs/cross/discussions) or our [Matrix
+room](https://matrix.to/#/#cross-rs:matrix.org) if you have any questions.
+
+
+## Installing Cross
+
+Once `cargo` is installed via `rustup`, and the necessary additional tools are
+present, you can now install `cross` via `cargo`:
+
+```bash
+cargo install cross
+# Optionally, if you have cargo-binstall, you can install via pre-built binary
+cargo binstall cross
+```
+
+Once `cross` is installed, you need a container engine and you can start
+cross-compiling.
+
+
+# Installing A Container Engine
+
+On Windows and macOS, we generally recommend you use Docker unless you know
+what you're doing. [Docker
+Desktop](https://www.docker.com/products/docker-desktop/) install instructions
+can be found [here](https://www.docker.com/products/docker-desktop/). On Linux,
+you can either install via [Docker
+Engine](https://docs.docker.com/engine/install/ubuntu/), [Docker
+Desktop](https://docs.docker.com/desktop/install/linux-install/) or
+[Podman](https://podman.io/getting-started/installation). We generally
+recommend Podman, since it runs rootless by default. If you choose to use
+Docker, make sure you add users to the [docker
+group](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)
+so it can be run without `sudo` (note that this has security implications) or
+use [rootless](https://docs.docker.com/engine/security/rootless/)<sup>†</sup>
+Docker.
+
+If you use Docker Desktop for Windows, ensure you're using the WSL2. Follow the
+[WSL2 installation
+instructions](https://docs.microsoft.com/en-us/windows/wsl/install) to enable
+the [WSL2 backend in docker](https://docs.docker.com/desktop/windows/wsl/).
+
+Once your container engine is installed, you can check that it is running via:
+
+```bash
+# or use podman, if installed
+$ docker ps -a
+```
+
+<sup>†</sup>Using rootless docker also requires setting the environment
+variable `CROSS_ROOTLESS_CONTAINER_ENGINE=1`.
+
+
+# Cross-Compiling Your First Package
+
+Once both `cross` and the container engine are installed, you can build your
+first package: this is all that's required.
+
+```bash
+$ cargo init --bin hello
+$ cd hello
+$ cross run --target aarch64-unknown-linux-gnu
+   Compiling hello v0.1.0 (/project)
+    Finished dev [unoptimized + debuginfo] target(s) in 0.64s
+     Running `/linux-runner aarch64 /target/aarch64-unknown-linux-gnu/debug/hello`
+Hello, world!
+```
+
+This will automatically install the Rust target required and the Docker image
+containing the toolchain to cross-compile your target.
+
+If you get an error similar to `error: toolchain
+'stable-x86_64-unknown-linux-gnu' does not support components`, try
+reinstalling that toolchain with rustup.
+
+```sh
+$ rustup toolchain uninstall stable-x86_64-unknown-linux-gnu
+$ rustup toolchain install stable-x86_64-unknown-linux-gnu --force-non-host
+```

From ae9cf8c2445af09fce2b9b4cc5d692e82bc37205 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 6 Feb 2024 08:16:52 +0100
Subject: [PATCH 02/20] docs: Add "unstable_features"

and remove the respective section from the README instead.
---
 README.md                 | 8 --------
 docs/unstable_features.md | 9 +++++++++
 2 files changed, 9 insertions(+), 8 deletions(-)
 create mode 100644 docs/unstable_features.md

diff --git a/README.md b/README.md
index e3ad8a107..295ce2d0a 100644
--- a/README.md
+++ b/README.md
@@ -260,14 +260,6 @@ passthrough = [
 
 For more detailed documentation on which environment variables are automatically passed to the build environment, see [Environment Variable Passthrough](https://github.com/cross-rs/cross/wiki/Configuration#environment-variable-passthrough) on our wiki.
 
-### Unstable Features
-
-Certain unstable features can enable additional functionality useful to
-cross-compiling. Note that these are unstable, and may be removed at any
-time (particularly if the feature is stabilized or removed), and will
-only be used on a nightly channel.
-
-- `CROSS_UNSTABLE_ENABLE_DOCTESTS=true`: also run doctests.
 
 ### Mounting volumes into the build environment
 
diff --git a/docs/unstable_features.md b/docs/unstable_features.md
new file mode 100644
index 000000000..865be600b
--- /dev/null
+++ b/docs/unstable_features.md
@@ -0,0 +1,9 @@
+Certain unstable features can enable additional functionality useful to
+cross-compiling. Note that these are unstable, and may be removed at any time
+(particularly if the feature is stabilized or removed), and will only be used
+on a nightly channel.
+
+Here is the list of currently available unstable features:
+
+- `CROSS_UNSTABLE_ENABLE_DOCTESTS`: enable or disable running doctests
+  (example: `true`)

From 5d6d33afcafa9ba4889db70b974242366f1cce24 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 6 Feb 2024 08:20:45 +0100
Subject: [PATCH 03/20] docs: Move `xargo` docs to new file.

---
 README.md                   | 23 -----------------------
 docs/cargo_configuration.md | 31 +++++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 23 deletions(-)
 create mode 100644 docs/cargo_configuration.md

diff --git a/README.md b/README.md
index 295ce2d0a..ec6481066 100644
--- a/README.md
+++ b/README.md
@@ -273,29 +273,6 @@ volumes = [
 ]
 ```
 
-### Use Xargo instead of Cargo
-
-By default, `cross` uses `xargo` to build your Cargo project only for all
-non-standard targets (i.e. something not reported by rustc/rustup). However,
-you can use the `build.xargo` or `target.{{TARGET}}.xargo` field in
-`Cross.toml` to force the use of `xargo`:
-
-```toml
-# all the targets will use `xargo`
-[build]
-xargo = true
-```
-
-Or,
-
-```toml
-# only this target will use `xargo`
-[target.aarch64-unknown-linux-gnu]
-xargo = true
-```
-
-`xargo = false` will work the opposite way (pick cargo always) and is useful
-when building for custom targets that you know to work with cargo.
 
 ## Supported targets
 
diff --git a/docs/cargo_configuration.md b/docs/cargo_configuration.md
new file mode 100644
index 000000000..5e8d8d6dc
--- /dev/null
+++ b/docs/cargo_configuration.md
@@ -0,0 +1,31 @@
+<!--toc:start-->
+- [Use Xargo instead of Cargo](#use-xargo-instead-of-cargo)
+<!--toc:end-->
+
+
+# Use Xargo instead of Cargo
+
+By default, `cross` uses `xargo` to build your Cargo project only for all
+non-standard targets (i.e. something not reported by rustc/rustup). However,
+you can use the `build.xargo` or `target.{{TARGET}}.xargo` field in
+`Cross.toml` to force the use of `xargo`:
+
+```toml
+# all the targets will use `xargo`
+[build]
+xargo = true
+```
+
+Or,
+
+```toml
+# only this target will use `xargo`
+[target.aarch64-unknown-linux-gnu]
+xargo = true
+```
+
+`xargo = false` will work the opposite way (pick cargo always) and is useful
+when building for custom targets that you know to work with cargo.
+
+
+[cargo-flags]: https://doc.rust-lang.org/cargo/reference/config.html#target

From 2fd1da11f30f9cdc75164801af3d520d94f58918 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 6 Feb 2024 08:31:09 +0100
Subject: [PATCH 04/20] docs: Move "custom images" documentation

into two separate files in the `docs/` dir and enrich it with
information taken from the Wiki.
---
 README.md             | 62 -------------------------------
 docs/config_file.md   | 71 +++++++++++++++++++++++++++++++++++
 docs/custom_images.md | 86 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 157 insertions(+), 62 deletions(-)
 create mode 100644 docs/config_file.md
 create mode 100644 docs/custom_images.md

diff --git a/README.md b/README.md
index ec6481066..60c3a5357 100644
--- a/README.md
+++ b/README.md
@@ -113,73 +113,11 @@ You can put your [configuration](docs/cross_toml.md) inside a `Cross.toml` file
 
 By setting the `CROSS_CONFIG` environment variable, you can tell `cross` where it should search for the config file. This way you are not limited to a `Cross.toml` file in the project root.
 
-### Custom Docker images
 
-`cross` provides default Docker images for the targets listed below. However, it
-can't cover every single use case out there. For other targets, or when the
-default image is not enough, you can use the `target.{{TARGET}}.image` field in
-`Cross.toml` to use custom Docker image for a specific target:
 
-```toml
-[target.aarch64-unknown-linux-gnu]
-image = "my/image:tag"
-```
-
-In the example above, `cross` will use a image named `my/image:tag` instead of
-the default one. Normal Docker behavior applies, so:
-
-- Docker will first look for a local image named `my/image:tag`
-
-- If it doesn't find a local image, then it will look in Docker Hub.
-
-- If only `image:tag` is specified, then Docker won't look in Docker Hub.
-
-- If only `tag` is omitted, then Docker will use the `latest` tag.
-
-#### Dockerfiles
-
-If you're using a custom Dockerfile, you can use `target.{{TARGET}}.dockerfile` to automatically build it
-
-```toml
-[target.aarch64-unknown-linux-gnu]
-dockerfile = "./path/to/where/the/Dockerfile/resides"
-```
-
-`cross` will build and use the image that was built instead of the default image.
 
-It's recommended to base your custom image on the default Docker image that
-cross uses: `ghcr.io/cross-rs/{{TARGET}}:{{VERSION}}` (where `{{VERSION}}` is cross's version).
-This way you won't have to figure out how to install a cross C toolchain in your
-custom image.
 
 
-``` Dockerfile
-FROM ghcr.io/cross-rs/aarch64-unknown-linux-gnu:latest
-
-RUN dpkg --add-architecture arm64 && \
-    apt-get update && \
-    apt-get install --assume-yes libfoo:arm64
-```
-
-If you want cross to provide the `FROM` instruction, you can do the following
-
-``` Dockerfile
-ARG CROSS_BASE_IMAGE
-FROM $CROSS_BASE_IMAGE
-
-RUN ...
-```
-
-#### Pre-build hook
-
-`cross` enables you to add dependencies and run other necessary commands in the image before using it.
-This action will be added to the used image, so it won't be ran/built every time you use `cross`.
-
-```toml
-[target.aarch64-unknown-linux-gnu]
-pre-build = ["dpkg --add-architecture arm64 && apt-get update && apt-get install --assume-yes libfoo:arm64"]
-```
-
 ### Docker in Docker
 
 When running `cross` from inside a container, `cross` needs access to
diff --git a/docs/config_file.md b/docs/config_file.md
new file mode 100644
index 000000000..47aa5b760
--- /dev/null
+++ b/docs/config_file.md
@@ -0,0 +1,71 @@
+<!--toc:start-->
+- [`build.dockerfile`](#builddockerfile)
+<!--toc:end-->
+
+You can place a `Cross.toml` file in the root of your Cargo project or use a
+`CROSS_CONFIG` environment variable to tweak cross's behavior. You can also use
+`package.metadata.cross.KEY` in `Cargo.toml`, and the priority of settings is
+environment variables override `Cross.toml` options, which override
+`Cargo.toml` options. Annotated examples of both
+[`Cross.toml`][example-cross-toml] and [`Cargo.toml`][example-cargo-toml] are
+provided.
+
+For example, the `[build]` table in `Cross.toml` is identical to setting
+`[package.metadata.cross.build]` in `Cargo.toml`.
+
+The `cross` configuration in the `Cross.toml` file can contain the following
+elements:
+
+
+# `build.dockerfile`
+
+> If the image you want to use is already available from a container registry,
+> check out the `target.TARGET.image` option below.
+
+The `build.dockerfile` key lets you provide a custom Docker image for all
+targets, except those specified `target.TARGET.dockerfile`. The value can be
+provided as either a table or a string. If `build.dockerfile` is set to a
+string, it's equivalent to setting `build.dockerfile.file` to that value. For
+example, using only a string:
+
+```toml
+[build]
+dockerfile = "./Dockerfile"
+```
+
+Or using a table:
+
+```toml
+[build.dockerfile]
+file = "./Dockerfile"         # the dockerfile to use relative to the `Cargo.toml`
+context = "."                 # the context folder to build the script in. defaults to `.`
+build-args = { ARG1 = "foo" } # https://docs.docker.com/engine/reference/builder/#arg
+```
+
+`cross` will build and use the image that was built instead of the default
+image. It's recommended to base your custom image on the default Docker image
+that `cross` uses: `ghcr.io/cross-rs/{{TARGET}}:{{VERSION}}` (where
+`{{VERSION}}` is `cross`'s version). This way you won't have to figure out how
+to install a cross-C toolchain in your custom image.
+
+> *NOTE*: `$CROSS_DEB_ARCH` is automatically provided by cross, [see
+> here][custom_images_automatic_arch].
+
+``` Dockerfile
+FROM ghcr.io/cross-rs/aarch64-unknown-linux-gnu:latest
+
+RUN dpkg --add-architecture $CROSS_DEB_ARCH && \
+    apt-get update && \
+    apt-get install --assume-yes libfoo:$CROSS_DEB_ARCH
+```
+
+`cross` will provide the argument `CROSS_BASE_IMAGE` which points to the
+default image `cross` would use for the target. Instead of the above, you can
+also then do the following:
+
+```Dockerfile
+ARG CROSS_BASE_IMAGE
+FROM $CROSS_BASE_IMAGE
+RUN ...
+```
+
diff --git a/docs/custom_images.md b/docs/custom_images.md
new file mode 100644
index 000000000..a88814e46
--- /dev/null
+++ b/docs/custom_images.md
@@ -0,0 +1,86 @@
+<!--toc:start-->
+- [Custom Images](#custom-images)
+- [Automatic Target Architecture on Debian](#automatic-target-architecture-on-debian)
+<!--toc:end-->
+
+# Custom Images
+
+`cross` provides default Docker images for the targets listed [in the
+README](../README.md#supported-targets). However, it can't cover every single
+use case out there.
+
+If you simply need to install a dependency availaible in ubuntus package
+manager, see [`target.TARGET.pre-build`][config-target-pre-build]:
+
+```toml
+[target.x86_64-unknown-linux-gnu]
+pre-build = [
+    "dpkg --add-architecture $CROSS_DEB_ARCH",
+    "apt-get update && apt-get install --assume-yes libssl-dev:$CROSS_DEB_ARCH"
+]
+```
+
+For FreeBSD targets, a few helper scripts are available for use in
+[`target.TARGET.pre-build`][config-target-pre-build]:
+
+```toml
+[target.x86_64-unknown-freebsd]
+pre-build = ["""
+export FREEBSD_MIRROR=$(/freebsd-fetch-best-mirror.sh) &&
+/freebsd-setup-packagesite.sh &&
+/freebsd-install-package.sh xen-tools
+"""]
+```
+
+For other targets, or when the default image is not enough, you can use the
+[`target.{{TARGET}}.dockerfile`][config_target_dockerfile] field
+in `Cross.toml` to use custom Docker image for a specific target:
+
+> *NOTE*: Refer to the [`build.dockerfile`][config_build_dockerfile] section of
+> the configuration for tips when writing your own `Dockerfile`.
+
+``` toml
+[target.aarch64-unknown-linux-gnu]
+dockerfile = "Dockerfile"
+```
+
+Or [`target.{{TARGET}}.image`][config_target_image] field in `Cross.toml` to
+use an already built image for the specific target:
+
+``` toml
+[target.aarch64-unknown-linux-gnu]
+image = "my/image:tag"
+```
+
+In the later example, `cross` will use a image named `my/image:tag` instead of
+the default one. Normal Docker behavior applies, so:
+
+- Docker will first look for a local image named `my/image:tag`
+- If it doesn't find a local image, then it will look in Docker Hub.
+- If only `image:tag` is specified, then Docker won't look in Docker Hub.
+- If only `tag` is omitted, then Docker will use the `latest` tag.
+
+
+# Automatic Target Architecture on Debian
+
+Custom images generated from config `dockerfile` or `pre-build` keys will
+export `CROSS_DEB_ARCH`, which allows you to install packages from
+Ubuntu/Debian repositories without having to specify the exact architecture.
+For example, to install `OpenSSL` for the target, you can do:
+
+```toml
+[target.aarch64-unknown-linux-gnu]
+pre-build = [
+  "dpkg --add-architecture $CROSS_DEB_ARCH", 
+  "apt-get update && apt-get --assume-yes install libssl-dev:$CROSS_DEB_ARCH"
+]
+```
+
+Here, `CROSS_DEB_ARCH` will automatically evaluate to `arm64`, without you
+having to explicitly provide it.
+
+
+[config-target-pre-build]: ./config.md#targettargetpre-build
+[config_target_dockerfile]: ./config.md#targettargetdockerfile
+[config_target_image]: ./config.md#targettargetimage
+[config_build_dockerfile]: ./config.md#builddockerfile

From ef2e377f6c46afc57757e32b85760563304e3014 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 6 Feb 2024 08:34:19 +0100
Subject: [PATCH 05/20] docs: Flesh out environment variable docs

with additional information from the wiki. Split up documentation in a
new file in the `docs/` directory and add references to other files
where appropriate.
---
 README.md                     |  28 --------
 docs/cargo_configuration.md   |  33 ++++++++++
 docs/config_file.md           |  37 +++++++++++
 docs/environment_variables.md | 116 ++++++++++++++++++++++++++++++++++
 4 files changed, 186 insertions(+), 28 deletions(-)
 create mode 100644 docs/environment_variables.md

diff --git a/README.md b/README.md
index 60c3a5357..c6393a375 100644
--- a/README.md
+++ b/README.md
@@ -170,34 +170,6 @@ environment variable.
 
 For example in case you want use [Podman], you can set `CROSS_CONTAINER_ENGINE=podman`.
 
-### Passing environment variables into the build environment
-
-By default, `cross` does not pass most environment variables into the build environment from the calling shell. This is chosen as a safe default as most use cases will not want the calling environment leaking into the inner execution environment. There are, however, some notable exceptions: most environment variables `cross` or [cargo reads](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-reads) are passed through automatically to the build environment.
-
-In the instances that you do want to pass through environment variables, this
-can be done via `build.env.passthrough` in your `Cross.toml`:
-
-```toml
-[build.env]
-passthrough = [
-    "RUST_BACKTRACE",
-    "RUST_LOG",
-    "TRAVIS",
-]
-```
-
-To pass variables through for one target but not others, you can use
-this syntax instead:
-
-```toml
-[target.aarch64-unknown-linux-gnu.env]
-passthrough = [
-    "RUST_DEBUG",
-]
-```
-
-For more detailed documentation on which environment variables are automatically passed to the build environment, see [Environment Variable Passthrough](https://github.com/cross-rs/cross/wiki/Configuration#environment-variable-passthrough) on our wiki.
-
 
 ### Mounting volumes into the build environment
 
diff --git a/docs/cargo_configuration.md b/docs/cargo_configuration.md
index 5e8d8d6dc..d02c09cb9 100644
--- a/docs/cargo_configuration.md
+++ b/docs/cargo_configuration.md
@@ -1,7 +1,40 @@
 <!--toc:start-->
+- [Configuring `cross`](#configuring-cross)
+- [Configuring Cargo through environment variables](#configuring-cargo-through-environment-variables)
 - [Use Xargo instead of Cargo](#use-xargo-instead-of-cargo)
 <!--toc:end-->
 
+# Configuring `cross`
+
+Please refer to the following docs:
+
+- [config file](./config_file.md)
+- [env variables](./environment_variables.md)
+
+
+# Configuring Cargo through environment variables
+
+When cross-compiling, `cargo` does not use environment variables such as
+`RUSTFLAGS`, and must be provided using `CARGO_TARGET_${TARGET}_${OPTION}`.
+Please note that some of these may be provided by the image themselves, such as
+runners, and should be overwritten with caution. A list of important flags
+includes:
+
+- `CARGO_TARGET_${TARGET}_LINKER`: specify a custom linker passed to rustc.
+- `CARGO_TARGET_${TARGET}_RUNNER`: specify the wrapper to run executables.
+- `CARGO_TARGET_${TARGET}_RUSTFLAGS`: add additional flags passed to rustc.
+
+Any of the following [flags][cargo-flags] can be provided, and are converted to
+uppercase. For example, changing `foo-bar` would be provided as
+`CARGO_TARGET_${TARGET}_FOO_BAR`.
+
+For example, to run binaries on `i686-unknown-linux-gnu` with Qemu, first
+create a custom image containing Qemu, and run with the following command:
+
+```
+CARGO_TARGET_I686_UNKNOWN_LINUX_GNU_RUNNER=qemu-i386 cross run ...
+```
+
 
 # Use Xargo instead of Cargo
 
diff --git a/docs/config_file.md b/docs/config_file.md
index 47aa5b760..5b1746b9f 100644
--- a/docs/config_file.md
+++ b/docs/config_file.md
@@ -1,7 +1,12 @@
 <!--toc:start-->
+- [`build.env`](#buildenv)
 - [`build.dockerfile`](#builddockerfile)
+- [`target.TARGET.env`](#targettargetenv)
 <!--toc:end-->
 
+> **Note**: Additional configuration is available through
+> [environment variables](./environment_variables.md)
+
 You can place a `Cross.toml` file in the root of your Cargo project or use a
 `CROSS_CONFIG` environment variable to tweak cross's behavior. You can also use
 `package.metadata.cross.KEY` in `Cargo.toml`, and the priority of settings is
@@ -17,6 +22,25 @@ The `cross` configuration in the `Cross.toml` file can contain the following
 elements:
 
 
+# `build.env`
+
+With the `build.env` key you can globally set volumes that should be mounted in
+the Docker container or environment variables that should be passed through.
+For example:
+
+```toml
+[build.env]
+volumes = ["VOL1_ARG", "VOL2_ARG=/path/to/volume"]
+passthrough = ["VAR1_ARG", "VAR2_ARG=VALUE"]
+```
+
+Note how in the environment variable passthrough, we can provide a definition
+for the variable as well. `VAR1_ARG` will be the value of the environment
+variable on the host, while `VAR2_ARG` will be `VALUE`. Likewise, the path to
+the volume for `VOL1_ARG` will be the value of the environment variable on the
+host, while `VOL2_ARG` will be `/path/to/volume`.
+
+
 # `build.dockerfile`
 
 > If the image you want to use is already available from a container registry,
@@ -69,3 +93,16 @@ FROM $CROSS_BASE_IMAGE
 RUN ...
 ```
 
+# `target.TARGET.env`
+
+The `env` key allows you to specify environment variables that should be used
+for a specific compilation target. This is similar to `build.env`, but allows
+you to be more specific per target:
+
+```toml
+[target.x86_64-unknown-linux-gnu.env]
+volumes = ["VOL1_ARG", "VOL2_ARG=/path/to/volume"]
+passthrough = ["VAR1_ARG", "VAR2_ARG=VALUE"]
+```
+
+
diff --git a/docs/environment_variables.md b/docs/environment_variables.md
new file mode 100644
index 000000000..2d60192c1
--- /dev/null
+++ b/docs/environment_variables.md
@@ -0,0 +1,116 @@
+<!--toc:start-->
+- [Configuring cross with environment variables](#configuring-cross-with-environment-variables)
+- [Environment-Variable passthrough](#environment-variable-passthrough)
+<!--toc:end-->
+
+# Configuring cross with environment variables
+
+Cross can be further customized by setting certain environment variables.
+In-depth documentation with examples can be found [here][env-examples].
+
+- `CROSS_CONTAINER_ENGINE`: The container engine to run cross in. Defaults to
+  `docker` then `podman`, whichever is found first (example: `docker`, see the
+  [FAQ][faq-container-engines]).
+- `XARGO_HOME`: Home for [`xargo`][xargo-project] (example: `~/.xargo`).
+- `NIX_STORE`: The directory for the [Nix store][nix-store] (example:
+  `/nix/store`).
+- `CROSS_CONTAINER_UID`: Set the user identifier for the cross command
+  (example: `1000`).
+- `CROSS_CONTAINER_GID`: Set the group identifier for the cross command
+  (example: `1000`).
+- `CROSS_CONTAINER_IN_CONTAINER`: Inform `cross` that it is running inside a
+  container (example: `true`, see the FAQ).
+- `CROSS_CONTAINER_OPTS`: Additional arguments to provide to the container
+  engine during `$engine run` (example: `--env MYVAR=1` where `engine=docker`).
+- `CROSS_CONFIG`: Specify the path to the `cross` config file (see [Config
+  File][cross-config-file]).
+- `CROSS_BUILD_OPTS`: Space separated flags to add when building a custom
+  image, i.e. `--network=host`
+- `CROSS_DEBUG`: Print debugging information for `cross`.
+- `CROSS_COMPATIBILITY_VERSION`: Use older `cross` behavior (example: `0.2.1`).
+- `CROSS_CUSTOM_TOOLCHAIN`: Specify that `rustup` is using a custom toolchain,
+  and therefore should not try to add targets/install components. Useful with
+  [`cargo-bisect-rustc`][cargo-bisect-rustc].
+- `CROSS_REMOTE`: Inform `cross` it is using a remote container engine, and use
+  data volumes rather than local bind mounts. See [Remote][docs-remote] for
+  more information using remote container engines.
+- `QEMU_STRACE`: Get a backtrace of system calls from “foreign” (non x86_64)
+  binaries when using `cross` run.
+- `CARGO_BUILD_TARGET`: Sets the default target, similar to specifying
+  `--target`.
+- `CROSS_ROOTLESS_CONTAINER_ENGINE`: Specify whether to container engine runs
+  as root or is rootless. If set to `auto` or not provided, it assumes `docker`
+  runs as root and all other container engines are rootless.
+- `CROSS_CONTAINER_USER_NAMESPACE`: Custom the [container user
+  namespace][container-user-namespace]. If set to `none`, user namespaces will
+  be disabled. If not provided or set to `auto`, it will use the default
+  namespace.
+- `CROSS_CUSTOM_TOOLCHAIN_COMPAT`: A descriptive name for a custom toolchain so
+  `cross` can convert it to a fully-qualified toolchain name.
+- `CROSS_CONTAINER_ENGINE_NO_BUILDKIT`: The container engine does not have
+  `buildx` command (or BuildKit support) when building custom images.
+
+All config file options can also be specified using environment variables. For
+example, setting `CROSS_BUILD_XARGO=1` is identical to setting `build.xargo =
+true`, and `CROSS_TARGET_AARCH64_UNKNOWN_LINUX_GNU_XARGO=1` is identical to
+`target.aarch64-unknown-linux-gnu.xargo = true`.
+
+
+# Environment-Variable passthrough
+
+By default, `cross` does not pass most environment variables into the build
+environment from the calling shell. This is chosen as a safe default as most
+use cases will not want the calling environment leaking into the inner
+execution environment. There are, however, some notable exceptions: most
+environment variables `cross` or `cargo` reads are passed through automatically
+to the build environment. The major exceptions are variables that are set by
+`cross` or conflict with our build environment, including:
+
+- `CARGO_HOME`
+- `CARGO_TARGET_DIR`
+- `CARGO_BUILD_TARGET_DIR`
+- `CARGO_BUILD_RUSTC`
+- `CARGO_BUILD_RUSTC_WRAPPER`
+- `CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER`
+- `CARGO_BUILD_RUSTDOC`
+- `CROSS_RUNNER`
+- `CROSS_RUSTC_MAJOR_VERSION`
+- `CROSS_RUSTC_MINOR_VERSION`
+- `CROSS_RUSTC_PATCH_VERSION`
+
+Otherwise, any environment variables that start with CARGO_ or CROSS_, and a
+few others, will be available in the build environment. For example, RUSTFLAGS
+and CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUSTFLAGS will both be automatically
+available in the build environment.
+
+In the instances that you do want to pass through additional environment
+variables, this can be done via `build.env.passthrough` in your `Cross.toml`:
+
+```toml
+[build.env]
+passthrough = [
+    "RUST_BACKTRACE",
+    "RUST_LOG",
+    "TRAVIS",
+]
+```
+
+To pass variables through for one target but not others, you can use
+this syntax instead:
+
+```toml
+[target.aarch64-unknown-linux-gnu.env]
+passthrough = [
+    "RUST_DEBUG",
+]
+```
+
+
+[env-examples]: https://github.com/cross-rs/wiki_assets/blob/main/Configuration/crossrc.bash_aliases
+[faq-container-engines]: https://github.com/cross-rs/cross/wiki/FAQ#explicitly-choose-the-container-engine
+[xargo-project]: https://github.com/japaric/xargo
+[nix-store]: https://nixos.org/manual/nix/stable/introduction.html
+[cross-config-file]: ./config_file.md
+[cargo-bisect-rustc]: https://github.com/rust-lang/cargo-bisect-rustc
+[docs-remote]: ./remote.md
+[container-user-namespace]: https://docs.docker.com/engine/security/userns-remap/

From f3c5401d902b8422dd5081d7380ff713fb9df838 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 6 Feb 2024 08:36:19 +0100
Subject: [PATCH 06/20] docs: Add `Remote` section from the Wiki.

---
 docs/remote.md | 136 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 136 insertions(+)
 create mode 100644 docs/remote.md

diff --git a/docs/remote.md b/docs/remote.md
new file mode 100644
index 000000000..ecd170679
--- /dev/null
+++ b/docs/remote.md
@@ -0,0 +1,136 @@
+<!--toc:start-->
+- [Getting Started](#getting-started)
+- [Data Volumes](#data-volumes)
+- [Managing Data](#managing-data)
+- [Private Dependencies](#private-dependencies)
+- [Environment Variables](#environment-variables)
+<!--toc:end-->
+
+
+# Getting Started
+
+To inform `cross` it is using a remote container engine, set the environment
+variable `CROSS_REMOTE=1`. Rather than use bind mounts to mount local volumes
+into the filesystem, it copies data from the local filesystem into data volumes
+on the remote host, ensuring all mounted volumes are present on the remote
+filesystem in the same location as they would be present on the host. A sample
+use with docker is:
+
+```bash
+CROSS_REMOTE=1 DOCKER_HOST=tcp://docker:2375/ cross build --target arm-unknown-linux-gnueabihf
+```
+
+If using [docker
+contexts](https://docs.docker.com/engine/context/working-with-contexts/), you
+do not need to provide `DOCKER_HOST`. This also works with podman and
+podman-remote. For podman remote, make sure the connection is
+[added](https://docs.podman.io/en/latest/markdown/podman-system-connection-add.1.html)
+to podman, and if using a connection that requires authentication, that it is
+set to the default identity, and that you do not use an identity (to avoid
+being prompted for a password on every command).
+
+An example with podman is:
+
+```bash
+podman system connection add cross tcp://localhost:8080 --default=true
+CROSS_REMOTE=1 CROSS_CONTAINER_ENGINE=podman cross build --target arm-unknown-linux-gnueabihf
+```
+
+Any command using `podman` can be replaced with `podman-remote`. Cross
+automatically detects if `podman` or `podman-remote` is being used, and adds in
+the `--remote` flag if needed.
+
+
+# Data Volumes
+
+Since we cannot use bind mounts directly, we create a data volume mounted at
+`/cross` in the container, and copy over all relevant data to that volume. To
+ensure paths are identical with those on the host, all data is then symlinked
+to the expected paths: for example, `/cross/home/user/project` becomes
+`/home/user/project`. The files will have the expected metadata as on the host.
+
+By default, `cross` does not copy the `cargo` registry, not the target
+directory. These can be enabled via the `CROSS_REMOTE_COPY_REGISTRY` and
+`CROSS_REMOTE_COPY_CACHE` environment variables. In order to minimize the
+number of calls to docker, which has large overhead, when copying only subsets
+of a directory, we copy all files to a temporary directory for faster
+performance.
+
+Since copying the entire toolchain remotely can take a long time, `cross` also
+supports persistent data volumes containing all data for the current toolchain.
+These can be created via:
+
+```bash
+cross-util volumes crate
+```
+
+`cross` will detect if a persistent data volume is present, and prefer it over
+a single-use volume. The persistent data volume will also contain the project
+files, and will reflect any changes to the local project by copying/removing
+changed files on every build.
+
+
+# Managing Data
+
+Due to the addition of temporary files/directories, persistent data volumes,
+and containers that may not be cleaned up, we've added utilities to clean up
+data cross introduces:
+
+```bash
+# VOLUMES
+# list all all persistent data volumes
+$ cross-util volumes list
+cross-stable-x86_64-unknown-linux-gnu-16b8c-fe5b13d68
+# create a persistent data volume for the current toolchain
+$ cross-util volumes create
+# remove the persistent data volume for the current toolchain
+$ cross-util volumes remove
+# remove all persistent data volumes
+$ cross-util volumes remove-all
+# prune all data volumes not currently used with a container
+# note that this affects more than just cross, and can
+# be highly destructive
+$ cross-util volumes prune
+
+# CONTAINERS
+# list all all hanging containers
+$ cross-util containers list
+# stop and remove all hanging containers
+$ cross-util containers remove-all
+```
+
+
+# Private Dependencies
+
+Note that for private dependencies, you will need to copy over the cargo
+registry, since it uses the host toolchain, and might only support single-use
+volumes (this has not been extensively tested):
+
+```bash
+CROSS_REMOTE_COPY_REGISTRY=1 CROSS_REMOTE=1 cross build --target arm-unknown-linux-gnueabihf
+```
+
+This is because the private dependencies are downloaded locally (to the host
+registry), and therefore must be updated remotely, which will not have access
+to SSH keys or other information inside the container.
+
+
+# Environment Variables
+
+Remote build behavior can be further customized by environment variables
+provided to the build command.
+
+- `CROSS_REMOTE`: Inform cross it is using a remote container engine, and use
+  data volumes rather than local bind mounts. 
+- `CROSS_REMOTE_COPY_REGISTRY`: Copy the `cargo` registry and git directories.
+  Is needed to support  private SSH dependencies.
+- `CROSS_REMOTE_COPY_CACHE`: Copy all directories, even those containing
+  `CACHETAG.DIR` (a cache directory [tag](https://bford.info/cachedir/)).
+- `CROSS_REMOTE_SKIP_BUILD_ARTIFACTS`: Do not copy any generated build
+  artifacts back to the host after finishing the build. If using persistent
+  data volumes, the artifacts will remain in the volume.
+
+For additional environment variables, refer to the [environment variables
+documentation][docs-env-vars].
+
+[docs-env-vars]: ./environment_variables.md

From 7f06f98610ef264bcead2d57259e9e0a797cf930 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 6 Feb 2024 08:37:51 +0100
Subject: [PATCH 07/20] docs: Add `Recipes` page from the Wiki.

---
 docs/recipes.md | 295 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 295 insertions(+)
 create mode 100644 docs/recipes.md

diff --git a/docs/recipes.md b/docs/recipes.md
new file mode 100644
index 000000000..0cefec824
--- /dev/null
+++ b/docs/recipes.md
@@ -0,0 +1,295 @@
+<!--toc:start-->
+- [OpenSSL](#openssl)
+  - [Vendored](#vendored)
+  - [Pre-build](#pre-build)
+  - [Custom dockerfile](#custom-dockerfile)
+- [sccache](#sccache)
+- [Redoxer](#redoxer)
+- [vcpkg, Meson, and Conan](#vcpkg-meson-and-conan)
+- [Using Clang and Software Collections on CentOS7](#using-clang-and-software-collections-on-centos7)
+<!--toc:end-->
+
+This contains recipes for common logic use cases.
+
+
+# OpenSSL
+
+You can either use the vendored or system packages for the
+[openssl](https://crates.io/crates/openssl) crate. See
+[openssl-certs](https://github.com/cross-rs/wiki_assets/tree/main/Recipes/openssl-certs)
+for a working project.
+
+## Vendored
+
+Use the vendored feature of the openssl crate by adding the following to your
+dependencies in `Cargo.toml`:
+
+```toml,cargo
+openssl = { version = "0.10", features = ["vendored"] }
+```
+
+## Pre-build
+
+To install OpenSSL in an image with `apt-get` available add the following to
+your [Cross
+configuration](./config_file.md):
+
+```toml
+[target.x86_64-unknown-linux-gnu]
+pre-build = [
+    "dpkg --add-architecture $CROSS_DEB_ARCH",
+    "apt-get update && apt-get install --assume-yes libssl-dev:$CROSS_DEB_ARCH"
+]
+```
+
+## Custom dockerfile
+
+A sample Dockerfile for `aarch64` with OpenSSL support is:
+
+```Dockerfile
+FROM ghcr.io/cross-rs/aarch64-unknown-linux-gnu:edge
+RUN dpkg --add-architecture arm64
+RUN apt-get update && apt-get install --assume-yes libssl-dev:arm64
+```
+
+Build this image and use it, as is described extensively in [Custom
+Images](./custom_images.md).
+
+
+# sccache
+
+sccache support can be done either by `sccache` from source or using a pre-built binary. See [sccache](https://github.com/cross-rs/wiki_assets/tree/main/Recipes/sccache) for a working project using pre-build hooks.
+
+1. Create a script to [install](#sccache-install-script) sccache in the image, either from a [pre-built binary](#sccache-prebuilt-binary) or [from source](#sccache-from-source).
+2. Extend a [Dockerfile](#sccache-dockerfile) to install sccache in the image.
+3. Passthrough the appropriate environment variables in [Cross.toml](#sccache-cross-toml) when using sccache.
+
+<h3 id="sccache-install-script">Install Script</h3>
+
+First, we need a script to copy into our image as `sccache.sh` (make sure the script is executable).
+
+<h4 id="sccache-prebuilt-binary">Pre-Built Binary</h4>
+
+```bash
+#!/bin/bash
+
+set -x
+set -euo pipefail
+
+# shellcheck disable=SC1091
+. lib.sh
+
+main() {
+    local triple
+    local tag
+    local td
+    local url="https://github.com/mozilla/sccache"
+    triple="${1}"
+
+    install_packages unzip tar
+
+    # Download our package, then install our binary.
+    td="$(mktemp -d)"
+    pushd "${td}"
+    tag=$(git ls-remote --tags --refs --exit-code \
+        "${url}" \
+        | cut -d/ -f3 \
+        | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' \
+        | sort --version-sort \
+        | tail -n1)
+    curl -LSfs "${url}/releases/download/${tag}/sccache-${tag}-${triple}.tar.gz" \
+        -o sccache.tar.gz
+    tar -xvf sccache.tar.gz
+    rm sccache.tar.gz
+    cp "sccache-${tag}-${triple}/sccache" "/usr/bin/sccache"
+    chmod +x "/usr/bin/sccache"
+
+    # clean up our install
+    purge_packages
+    popd
+    rm -rf "${td}"
+    rm "${0}"
+}
+
+main "${@}"
+```
+
+<h4 id="sccache-from-source">From Source</h4>
+
+When installing from source, we can toggle various features, however it is highly recommended to use the vendored OpenSSL.
+
+```bash
+#!/bin/bash
+
+set -x
+set -euo pipefail
+
+# shellcheck disable=SC1091
+. lib.sh
+
+main() {
+    local triple
+    local tag
+    local td
+    local url="https://github.com/mozilla/sccache"
+    triple="${1}"
+
+    install_packages ca-certificates curl unzip
+
+    # install rust and cargo to build sccache
+    export RUSTUP_HOME=/tmp/rustup
+    export CARGO_HOME=/tmp/cargo
+    curl --retry 3 -sSfL https://sh.rustup.rs -o rustup-init.sh
+    sh rustup-init.sh -y --no-modify-path
+    rm rustup-init.sh
+    export PATH="${CARGO_HOME}/bin:${PATH}"
+    rustup target add "${triple}"
+
+    # download the source code from the latest sccache release
+    td="$(mktemp -d)"
+    pushd "${td}"
+    tag=$(git ls-remote --tags --refs --exit-code \
+        "${url}" \
+        | cut -d/ -f3 \
+        | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' \
+        | sort --version-sort \
+        | tail -n1)
+    curl -LSfs "${url}/archive/refs/tags/${tag}.zip" \
+        -o sccache.zip
+    unzip sccache.zip
+    mv "sccache-${tag//v/}" sccache
+    rm sccache.zip
+
+    # build from source for the desired architecture
+    # you can also use additional features here
+    cd sccache
+    cargo build --release --target "${triple}" \
+        --features=all,"openssl/vendored"
+    cp "target/${triple}/release/sccache" "/usr/bin/sccache"
+
+    # clean up our install
+    rm -r "${RUSTUP_HOME}" "${CARGO_HOME}"
+    purge_packages
+    popd
+    rm -rf "${td}"
+    rm "${0}"
+}
+
+main "${@}"
+```
+
+<h3 id="sccache-dockerfile">Dockerfile</h3>
+
+Next, extend our Dockerfile and build our image, saved as `Dockerfile.${target}`, where `${target}` is replaced by our desired target (such as `x86_64-unknown-linux-musl`).
+
+```Dockerfile
+FROM ghcr.io/cross-rs/${target}:main
+ARG DEBIAN_FRONTEND=noninteractive
+
+COPY sccache.sh /
+RUN /sccache.sh x86_64-unknown-linux-musl
+
+ENV RUSTC_WRAPPER="/usr/bin/sccache"
+```
+
+Build our Docker image with:
+
+```bash
+docker build --tag ${target}:sccache \
+    --file Dockerfile.${target} .
+```
+
+<h3 id="sccache-cross-toml">Cross.toml</h3>
+
+Now, we need to passthrough our environment variables and ensure they're exported when running cross. In `Cross.toml`, define:
+
+```toml
+[target.${target}]
+image = "${target}:sccache"
+
+[build.env]
+passthrough = [
+    "SCCACHE_ERROR_LOG",
+    "SCCACHE_LOG",
+    "SCCACHE_AZURE_CONNECTION_STRING",
+    "SCCACHE_AZURE_BLOB_CONTAINER",
+    "SCCACHE_DIR",
+]
+```
+
+<h3 >Building with sccache</h3>
+
+Finally, we can run cross with our `sccache` environment variables defined using `cross`:
+
+```bash
+SCCACHE_LOG=trace SCCACHE_DIR=/path/to/sccache/cache \
+    cross build --target "${target}" --verbose
+```
+
+# Redoxer
+
+Redoxer support can be done by installing the necessary dependencies, Redoxer, and the Redoxer toolchain in a custom image. See [redoxer](https://github.com/cross-rs/wiki_assets/tree/main/Recipes/redoxer) for a working project using a custom Dockerfile.
+
+Please note that this requires a base Ubuntu version of 20.04, and therefore needs you to build the images with [newer Linux versions](https://github.com/cross-rs/cross/wiki/FAQ#newer-linux-versions).
+
+# vcpkg, Meson, and Conan
+
+Often C++ projects have complex build systems, due to a myriad of dependencies, competing build systems, and the lack of a built-in package manager. Some of the most popular build systems include GNU Make, CMake, and [Meson](https://mesonbuild.com/), and the two most popular package managers are [vcpkg](https://vcpkg.io/en/index.html) and [Conan](https://conan.io/). We have an entire [project](https://github.com/cross-rs/wiki_assets/tree/main/Recipes/vcpkg) with builds using CMake + Conan, Meson + Conan, and CMake + vcpkg.
+
+An example of building a project with an external `zlib` dependency using Meson and Conan is as follows. First, we create our Conan dependency file:
+
+**conanfile.py**
+
+```python
+from conans import ConanFile, Meson
+
+class ZlibExec(ConanFile):
+    name = "zlibexec"
+    version = "0.1"
+    settings = "os", "compiler", "build_type", "arch"
+    generators = "cmake", "pkg_config"
+    requires = "zlib/1.2.11"
+
+    def build(self):
+        meson = Meson(self)
+        meson.configure(build_folder="build")
+        meson.build()
+```
+
+Next, we need our Meson build file:
+
+**meson.build**
+
+```meson
+project('zlibexec', 'cpp')
+executable('zlibexec', 'zlib.cc', dependencies: dependency('zlib'))
+```
+
+Now, we need to build our project:
+
+```bash
+mkdir build && cd build
+conan install .. --build
+meson ..
+conan build ..
+```
+
+To make this magic happen, the project contains [Dockerfiles](https://github.com/cross-rs/wiki_assets/blob/main/Recipes/vcpkg/aarch64.Dockerfile) with Meson, Conan, and vcpkg installed where the CMake toolchains and Meson configurations automatically cross-compile for the desire architecture. These images are [automatically](https://github.com/cross-rs/wiki_assets/blob/main/Recipes/vcpkg/Cross.toml) built when running `cross` via [pre-build hooks](https://github.com/cross-rs/cross/wiki/Configuration#custom-images). In order to integrate these builds with Rust, rather than invoking the `meson` or `cmake` commands directly, you should use [meson-rs](https://docs.rs/meson/1.0.0/meson/) and [cmake-rs](https://docs.rs/cmake/latest/cmake/) to configure and build the projects.
+
+# Using Clang and Software Collections on CentOS7
+
+In order to use Clang on CentOS 7, you must both install the SCL repository, the LLVM toolset, and set the necessary paths to clang and LLVM. A sample Dockerfile is as follows:
+
+```Dockerfile
+FROM ghcr.io/cross-rs/x86_64-unknown-linux-gnu:main-centos
+
+RUN yum update -y && \
+    yum install centos-release-scl -y && \
+    yum install llvm-toolset-7 -y
+
+ENV LIBCLANG_PATH=/opt/rh/llvm-toolset-7/root/usr/lib64/ \
+    LIBCLANG_STATIC_PATH=/opt/rh/llvm-toolset-7/root/usr/lib64/ \
+    CLANG_PATH=/opt/rh/llvm-toolset-7/root/usr/bin/clang
+```
+
+Build this image and use it, as is described extensively in [Custom Images](./custom_images.md).

From 53963fbf4e70b43322c72da512a26f8414739271 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 6 Feb 2024 08:38:59 +0100
Subject: [PATCH 08/20] docs/custom_images: Add subsections

to improve readability.
---
 docs/custom_images.md | 24 +++++++++++++++++++-----
 1 file changed, 19 insertions(+), 5 deletions(-)

diff --git a/docs/custom_images.md b/docs/custom_images.md
index a88814e46..13f924f2e 100644
--- a/docs/custom_images.md
+++ b/docs/custom_images.md
@@ -1,5 +1,8 @@
 <!--toc:start-->
 - [Custom Images](#custom-images)
+  - [Adding Dependencies to Existing Images](#adding-dependencies-to-existing-images)
+  - [Custom Dockerfile](#custom-dockerfile)
+  - [Custom Image](#custom-image)
 - [Automatic Target Architecture on Debian](#automatic-target-architecture-on-debian)
 <!--toc:end-->
 
@@ -9,6 +12,8 @@
 README](../README.md#supported-targets). However, it can't cover every single
 use case out there.
 
+## Adding Dependencies to Existing Images
+
 If you simply need to install a dependency availaible in ubuntus package
 manager, see [`target.TARGET.pre-build`][config-target-pre-build]:
 
@@ -32,9 +37,11 @@ export FREEBSD_MIRROR=$(/freebsd-fetch-best-mirror.sh) &&
 """]
 ```
 
+## Custom Dockerfile
+
 For other targets, or when the default image is not enough, you can use the
 [`target.{{TARGET}}.dockerfile`][config_target_dockerfile] field
-in `Cross.toml` to use custom Docker image for a specific target:
+in `Cross.toml` to use a custom Docker image for a specific target:
 
 > *NOTE*: Refer to the [`build.dockerfile`][config_build_dockerfile] section of
 > the configuration for tips when writing your own `Dockerfile`.
@@ -44,16 +51,23 @@ in `Cross.toml` to use custom Docker image for a specific target:
 dockerfile = "Dockerfile"
 ```
 
-Or [`target.{{TARGET}}.image`][config_target_image] field in `Cross.toml` to
-use an already built image for the specific target:
+`cross` will build and use the image that was built instead of the default
+image.
+
+
+## Custom Image
+
+If there is a pre-built image for your specific target, you can use the
+[`target.{{TARGET}}.image`][config_target_image] field in `Cross.toml` to use
+that instead:
 
 ``` toml
 [target.aarch64-unknown-linux-gnu]
 image = "my/image:tag"
 ```
 
-In the later example, `cross` will use a image named `my/image:tag` instead of
-the default one. Normal Docker behavior applies, so:
+In thie case, `cross` will use a image named `my/image:tag` instead of the
+default one. Normal Docker behavior applies, so:
 
 - Docker will first look for a local image named `my/image:tag`
 - If it doesn't find a local image, then it will look in Docker Hub.

From 2a324bf0b46d8fa9e4a94d5891f6edcd36d9afd7 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 6 Feb 2024 08:39:19 +0100
Subject: [PATCH 09/20] docs/config_file: Add docs for config file

taken from the wiki with some added information.
---
 docs/config_file.md | 196 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 196 insertions(+)

diff --git a/docs/config_file.md b/docs/config_file.md
index 5b1746b9f..dafc46778 100644
--- a/docs/config_file.md
+++ b/docs/config_file.md
@@ -1,7 +1,14 @@
 <!--toc:start-->
+- [`build`](#build)
 - [`build.env`](#buildenv)
 - [`build.dockerfile`](#builddockerfile)
+- [`build.zig`](#buildzig)
+- [`target.TARGET`](#targettarget)
+- [`target.TARGET.pre-build`](#targettargetpre-build)
+- [`target.TARGET.image`](#targettargetimage)
 - [`target.TARGET.env`](#targettargetenv)
+- [`target.TARGET.dockerfile`](#targettargetdockerfile)
+- [`target.TARGET.zig`](#targettargetzig)
 <!--toc:end-->
 
 > **Note**: Additional configuration is available through
@@ -22,6 +29,26 @@ The `cross` configuration in the `Cross.toml` file can contain the following
 elements:
 
 
+# `build`
+
+The `build` key allows you to set global variables, e.g.:
+
+> *NOTE*: `$CROSS_DEB_ARCH` is automatically provided by cross, [see
+> here][custom_images_automatic_arch].
+
+```toml
+[build]
+build-std = false                              # do not build the std library. has precedence over xargo
+xargo = true                                   # enable the use of xargo by default
+zig = false                                    # do not use zig cc for the builds
+default-target = "x86_64-unknown-linux-gnu"    # use this target if none is explicitly provided
+pre-build = [                                  # additional commands to run prior to building the package
+    "dpkg --add-architecture $CROSS_DEB_ARCH", 
+    "apt-get update && apt-get --assume-yes install libssl-dev:$CROSS_DEB_ARCH"
+]                 
+```
+
+
 # `build.env`
 
 With the `build.env` key you can globally set volumes that should be mounted in
@@ -93,6 +120,117 @@ FROM $CROSS_BASE_IMAGE
 RUN ...
 ```
 
+
+# `build.zig`
+
+The `build.zig` key lets you use `zig cc` as a cross-compiler, enabling
+cross-compilation to numerous architectures and glibc versions using a single
+Docker image. Note that `zig cc` doesn't support all targets: only a subset of
+our Linux GNU targets, so it might be better to set these values in
+`target.TARGET.zig` instead. The value can be provided as either a table, a bool,
+or a string. If `build.zig` is set to a string, it's equivalent to setting
+`build.zig.version` to that value and `build.zig.enable` to true:
+
+```toml
+[build]
+zig = "2.17"
+```
+
+If `build.zig` is set to a bool, it's equivalent to setting `build.zig.enable`
+to that value:
+
+```toml
+[build]
+zig = true
+```
+
+Or using a table:
+
+```toml
+[build.zig]
+enable = true                 # enable or disable the use of zig cc
+version = "2.17"              # the glibc version to use
+image = "myimage"             # a custom image containing zig to use
+```
+
+
+# `target.TARGET`
+
+The `target` key allows you to specify parameters for specific compilation
+targets:
+
+```toml
+[target.aarch64-unknown-linux-gnu]
+build-std = false          # always build the std library. has precedence over xargo
+xargo = false              # disable the use of xargo
+image = "test-image"       # use a different image for the target
+runner = "qemu-user"       # wrapper to run the binary (must be `qemu-system`, `qemu-user`, or `native`).
+```
+
+
+# `target.TARGET.pre-build`
+
+The `pre-build` field can reference a file to copy and run. This file is
+relative to the container context, which would be the workspace root, or the
+current directory if `--manifest-path` is used. For more involved scripts,
+consider using `target.TARGET.dockerfile` instead to directly control the
+execution.
+
+This script will be invoked as `RUN ./pre-build-script $CROSS_TARGET` where
+`$CROSS_TARGET` is the target triple.
+
+```toml
+[target.aarch64-unknown-linux-gnu]
+pre-build = "./scripts/my-script.sh"
+```
+
+```bash
+$ cat ./scripts/my-script.sh
+#!/usr/bin/env bash
+
+apt-get install libssl-dev -y
+```
+
+`pre-build` can also be a list of commands to directly run inside the image:
+
+> *NOTE*: `$CROSS_DEB_ARCH` is automatically provided by cross, [see
+> here][custom_images_automatic_arch].
+
+```toml
+[target.aarch64-unknown-linux-gnu]
+pre-build = [
+    "dpkg --add-architecture $CROSS_DEB_ARCH",
+    "apt-get update",
+    "apt-get install --assume-yes libfoo:$CROSS_DEB_ARCH"
+]
+```
+
+
+# `target.TARGET.image`
+
+```toml
+[target.aarch64-unknown-linux-gnu]
+image = "my/image:latest"
+```
+
+In the example above, `cross` will use a image named `my/image:latest` instead of
+the default one. Normal Docker behavior applies, so:
+
+- Docker will first look for a local image named `my/image:latest`
+- If it doesn't find a local image, then it will look in Docker Hub.
+- If only `image:latest` is specified, then Docker won't look in Docker Hub.
+- If the tag is omitted, then Docker will use the `latest` tag.
+
+The `image` key can also take the toolchains/platforms supported by the image:
+
+```toml
+[target.aarch64-unknown-linux-gnu]
+image.name = "alpine:edge"
+image.toolchain = ["x86_64-unknown-linux-musl", "linux/arm64=aarch64-unknown-linux-musl"] # Defaults to `x86_64-unknown-linux-gnu`
+```
+
+
+
 # `target.TARGET.env`
 
 The `env` key allows you to specify environment variables that should be used
@@ -106,3 +244,61 @@ passthrough = ["VAR1_ARG", "VAR2_ARG=VALUE"]
 ```
 
 
+# `target.TARGET.dockerfile`
+
+The `dockerfile` key lets you provide a custom Docker image for the
+given target. The value can be provided as either a table or a string. If
+`target.TARGET.dockerfile` is set to a string, it's equivalent to setting
+`target.(...).dockerfile.file` to that value. For example, using only a string:
+
+```toml
+[target.aarch64-unknown-linux-gnu]
+dockerfile = "./Dockerfile"
+```
+
+Or using a table:
+
+```toml
+[target.aarch64-unknown-linux-gnu.dockerfile]
+file = "./Dockerfile"         # the dockerfile to use relative to the `Cargo.toml`
+context = "."                 # the context folder to build the script in. defaults to `.`
+build-args = { ARG1 = "foo" } # https://docs.docker.com/engine/reference/builder/#arg
+```
+
+
+# `target.TARGET.zig`
+
+The `target.TARGET.zig` key lets you use `zig cc` as a cross-compiler, enabling
+cross-compilation to numerous architectures and glibc versions using a single
+Docker image. The value can be provided as either a table, a bool, or a string.
+If `target.TARGET.zig` is set to a string, it's equivalent to setting
+`target.TARGET.zig.version` to that value and `target.TARGET.zig.enable` to
+true:
+
+```toml
+[target.aarch64-unknown-linux-gnu]
+zig = "2.17"
+```
+
+If `target.TARGET.zig` is set to a bool, it's equivalent to setting
+`target.TARGET.zig.enable` to that value:
+
+```toml
+[target.aarch64-unknown-linux-gnu]
+zig = true
+```
+
+Or using a table:
+
+```toml
+[target.aarch64-unknown-linux-gnu.zig]
+enable = true                 # enable or disable the use of zig cc
+version = "2.17"              # the glibc version to use
+image = "myimage"             # a custom image containing zig to use
+```
+
+
+
+[example-cross-toml]: https://github.com/cross-rs/wiki_assets/blob/main/Configuration/Cross.toml
+[example-cargo-toml]: https://github.com/cross-rs/wiki_assets/blob/main/Configuration/Cargo.toml
+[custom_images_automatic_arch]: ./custom_images.md#automatic-target-architecture-on-debian

From c2bef62bbc427566e7fd047c787da164f5d57257 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 6 Feb 2024 08:39:47 +0100
Subject: [PATCH 10/20] docs: Remove `cross_toml`

which is now superseeded by the new arrangement of files in the `docs/`
directory.
---
 docs/cross_toml.md | 119 ---------------------------------------------
 1 file changed, 119 deletions(-)
 delete mode 100644 docs/cross_toml.md

diff --git a/docs/cross_toml.md b/docs/cross_toml.md
deleted file mode 100644
index d3b0fac9c..000000000
--- a/docs/cross_toml.md
+++ /dev/null
@@ -1,119 +0,0 @@
-The `cross` configuration in the `Cross.toml` file, can contain the elements described below.
-
-If the configuration is given in the `Cargo.toml`, these table headers must be of the form `[package.metadata.cross.<KEY>]`.
-
-# `build`
-
-The `build` key allows you to set global variables, e.g.:
-
-```toml
-[build]
-xargo = true
-build-std = true
-default-target = "x86_64-unknown-linux-gnu"
-pre-build = ["apt-get update"] # can also be the path to a file to run
-```
-
-# `build.env`
-
-With the `build.env` key you can globally set volumes that should be mounted
-in the Docker container or environment variables that should be passed through.
-For example:
-
-```toml
-[build.env]
-volumes = ["VOL1_ARG", "VOL2_ARG"]
-passthrough = ["IMPORTANT_ENV_VARIABLES"]
-```
-
-# `target.TARGET`
-
-The `target` key allows you to specify parameters for specific compilation targets.
-
-```toml
-[target.aarch64-unknown-linux-gnu]
-xargo = false
-build-std = false
-zig = "2.17"
-image = "test-image"
-pre-build = ["apt-get update"] # can also be the path to a file to run
-runner = "custom-runner"
-```
-
-# `target.TARGET.pre-build`
-
-The `pre-build` field can also reference a file to copy and run. This file is relative to the container context, which would be the workspace root, or the current directory if `--manifest-path` is used. For more involved scripts, consider using `target.TARGET.dockerfile` instead to directly control the execution.
-
-This script will be invoked as `RUN ./pre-build-script $CROSS_TARGET` where `$CROSS_TARGET` is the target triple.
-
-```toml
-[target.aarch64-unknown-linux-gnu]
-pre-build = "./scripts/my-script.sh"
-```
-
-```sh
-$ cat ./scripts/my-script.sh
-#!/usr/bin/env bash
-
-apt-get install libssl-dev -y
-```
-
-# `target.TARGET.image`
-
-The `image` key can also take the toolchains/platforms supported by the image.
-
-```toml
-[target.aarch64-unknown-linux-gnu]
-image.name = "alpine:edge"
-image.toolchain = ["x86_64-unknown-linux-musl", "linux/arm64=aarch64-unknown-linux-musl"] # Defaults to `x86_64-unknown-linux-gnu`
-```
-
-# `target.TARGET.env`
-
-The `target` key allows you to specify environment variables that should be used for a specific compilation target.
-This is similar to `build.env`, but allows you to be more specific per target.
-
-```toml
-[target.x86_64-unknown-linux-gnu.env]
-volumes = ["VOL1_ARG", "VOL2_ARG"]
-passthrough = ["IMPORTANT_ENV_VARIABLES"]
-```
-
-# `target.TARGET.dockerfile`
-
-```toml
-[target.x86_64-unknown-linux-gnu.dockerfile]
-file = "./Dockerfile" # The dockerfile to use relative to the `Cargo.toml`
-context = "." # What folder to run the build script in
-build-args = { ARG1 = "foo" } # https://docs.docker.com/engine/reference/builder/#arg
-```
-
-also supports
-
-```toml
-[target.x86_64-unknown-linux-gnu]
-dockerfile = "./Dockerfile"
-```
-
-# `target.TARGET.zig`
-
-```toml
-[target.x86_64-unknown-linux-gnu.zig]
-enable = true       # enable use of the zig image
-version = "2.17"    # glibc version to use
-image = "zig:local" # custom zig image to use
-```
-
-also supports
-
-```toml
-[target.x86_64-unknown-linux-gnu]
-zig = true
-```
-
-or
-
-```toml
-[target.x86_64-unknown-linux-gnu]
-zig = "2.17"
-```

From ca69a437dcd463a64b5ffe73cb7c95b7774958a0 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 6 Feb 2024 08:40:37 +0100
Subject: [PATCH 11/20] README: Extend cross configuration section

and explicitly point towards environment-variable based configuration
which was previously missing. This should make that part of the
documentation easier to find.
---
 README.md | 29 +++++++++++++++++++----------
 1 file changed, 19 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index c6393a375..fc025dd26 100644
--- a/README.md
+++ b/README.md
@@ -91,12 +91,17 @@ Additional documentation can be found on the [wiki](https://github.com/cross-rs/
 
 ## Configuration
 
-You have three options to configure `cross`. All of these options use the TOML format for configuration and the possible configuration values are documented [here](docs/cross_toml.md).
+### Configuring cross behavior
 
-### Option 1: Configuring `cross` directly in your `Cargo.toml`
+You have four options to configure `cross`. All of these options use the TOML
+format for configuration and the possible configuration values are documented
+[here][config_file].
 
-You can directly set [configuration values](docs/cross_toml.md) in your `Cargo.toml` file, under the `[package.metadata.cross]` table, i.e. key prefix.
-An example config snippet would look like this:
+#### Option 1: Configuring `cross` directly in your `Cargo.toml`
+
+You can directly set [configuration values][config_file] in your `Cargo.toml`
+file, under the `[package.metadata.cross]` table, i.e. key prefix. An example
+config snippet would look like this:
 
 ```toml,cargo
 [package.metadata.cross.target.aarch64-unknown-linux-gnu]
@@ -105,17 +110,21 @@ image = "test-image"
 runner = "custom-runner"
 ```
 
-### Option 2: Configuring `cross` via a `Cross.toml` file
-
-You can put your [configuration](docs/cross_toml.md) inside a `Cross.toml` file in your project root directory.
-
-### Option 3: Using `CROSS_CONFIG` to specify the location of your configuration
+#### Option 2: Configuring `cross` via a `Cross.toml` file
 
-By setting the `CROSS_CONFIG` environment variable, you can tell `cross` where it should search for the config file. This way you are not limited to a `Cross.toml` file in the project root.
+You can put your [configuration][config_file] inside a `Cross.toml` file
+in your project root directory.
 
+#### Option 3: Using `CROSS_CONFIG` to specify the location of your configuration
 
+By setting the `CROSS_CONFIG` environment variable, you can tell `cross` where
+it should search for the config file. This way you are not limited to a
+`Cross.toml` file in the project root.
 
+#### Option 4: Configuring `cross` through environment variables
 
+Besides the TOML-based configuration files, config can be passed through
+[environment variables][docs_env_vars], too. 
 
 
 ### Docker in Docker

From 5018cf7dbda9870788fd75b56b4787dfb6c25afe Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 6 Feb 2024 08:41:28 +0100
Subject: [PATCH 12/20] README: Improve formatting

and limit text to 80 columns. Move a few hyperlinks to the bottom of the
file rather than spraying them in between text passages.
---
 README.md | 43 ++++++++++++++++---------------------------
 1 file changed, 16 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index fc025dd26..9deed87ec 100644
--- a/README.md
+++ b/README.md
@@ -40,19 +40,13 @@ See our [Getting Started](./docs/getting-started.md) guide for detailed
 installation instructions.
 
 - [rustup](https://rustup.rs/)
-
 - A Linux kernel with [binfmt_misc] support is required for cross testing.
 
-[binfmt_misc]: https://www.kernel.org/doc/html/latest/admin-guide/binfmt-misc.html
-
 One of these container engines is required. If both are installed, `cross` will
 default to `docker`.
 
 - [Docker]. Note that on Linux non-sudo users need to be in the `docker` group or use rootless docker.
-  Read the container engine [install guide][install] for the required installation and post-installation steps. Requires version 20.10 (API 1.40) or later.
-
-[install]: https://github.com/cross-rs/cross/wiki/Getting-Started#installing-a-container-engine
-
+  Read the container engine [install guide][docker_install] for the required installation and post-installation steps. Requires version 20.10 (API 1.40) or later.
 - [Podman]. Requires version 3.4.0 or later.
 
 ## Installation
@@ -87,7 +81,8 @@ $ cross test --target mips64-unknown-linux-gnuabi64
 $ cross rustc --target powerpc-unknown-linux-gnu --release -- -C lto
 ```
 
-Additional documentation can be found on the [wiki](https://github.com/cross-rs/cross/wiki).
+Additional documentation can be found on the
+[wiki](https://github.com/cross-rs/cross/wiki) or the `docs/` subfolder.
 
 ## Configuration
 
@@ -141,11 +136,12 @@ $ docker run -v /var/run/docker.sock:/var/run/docker.sock -v .:/project \
 The image running `cross` requires the rust development tools to be installed.
 
 With this setup `cross` must find and mount the correct host paths into the
-container used for cross compilation. This includes the original project directory as
-well as the root path of the parent container to give access to the rust build
-tools.
+container used for cross compilation. This includes the original project
+directory as well as the root path of the parent container to give access to
+the rust build tools.
 
-To inform `cross` that it is running inside a container set `CROSS_CONTAINER_IN_CONTAINER=true`.
+To inform `cross` that it is running inside a container set
+`CROSS_CONTAINER_IN_CONTAINER=true`.
 
 A development or CI container can be created like this:
 
@@ -180,19 +176,6 @@ environment variable.
 For example in case you want use [Podman], you can set `CROSS_CONTAINER_ENGINE=podman`.
 
 
-### Mounting volumes into the build environment
-
-In addition to passing environment variables, you can also specify environment
-variables pointing to paths which should be mounted into the container:
-
-```toml
-[target.aarch64-unknown-linux-gnu.env]
-volumes = [
-    "BUILD_DIR",
-]
-```
-
-
 ## Supported targets
 
 A target is considered as “supported” if `cross` can cross compile a
@@ -294,8 +277,10 @@ terminate.
 <!--[7] libc = emscripten and GCC = clang. The Docker images for these targets are currently not built automatically
 due to a [compiler bug](https://github.com/rust-lang/rust/issues/98216), you will have to build them yourself for now.-->
 
-Additional Dockerfiles for other targets can be found in [cross-toolchains](https://github.com/cross-rs/cross-toolchains).
-These include MSVC and Apple Darwin targets, which we cannot ship pre-built images of.
+Additional Dockerfiles for other targets can be found in
+[cross-toolchains](https://github.com/cross-rs/cross-toolchains). These include
+MSVC and Apple Darwin targets, which we cannot ship pre-built images of.
+
 
 ## Debugging
 
@@ -353,3 +338,7 @@ to intervene to uphold that code of conduct.
 [Docker]: https://www.docker.com
 [Podman]: https://podman.io
 [Matrix room]: https://matrix.to/#/#cross-rs:matrix.org
+[docker_install]: https://github.com/cross-rs/cross/wiki/Getting-Started#installing-a-container-engine
+[binfmt_misc]: https://www.kernel.org/doc/html/latest/admin-guide/binfmt-misc.html
+[config_file]: ./docs/config_file.md
+[docs_env_vars]: ./docs/environment_variables.md

From cd425602c75c554cb060d8ae37b1489ab3fc3a88 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 6 Feb 2024 08:42:30 +0100
Subject: [PATCH 13/20] README: Format "Targets" table.

---
 README.md | 142 ++++++++++++++++++++++++++++--------------------------
 1 file changed, 74 insertions(+), 68 deletions(-)

diff --git a/README.md b/README.md
index 9deed87ec..379f49d36 100644
--- a/README.md
+++ b/README.md
@@ -194,85 +194,91 @@ QEMU gets upset when you spawn multiple threads. This means that, if one of your
 unit tests spawns threads, then it's more likely to fail or, worst, never
 terminate.
 
-| Target                               |  libc  |   GCC   | C++ | QEMU  | `test` |
-|--------------------------------------|-------:|--------:|:---:|------:|:------:|
-| `aarch64-linux-android` [1]          | 9.0.8  | 9.0.8   | ✓   | 6.1.0 |   ✓    |
-| `aarch64-unknown-linux-gnu`          | 2.31   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `aarch64-unknown-linux-gnu:centos` [7] | 2.17   | 4.8.5   |     | 4.2.1 |   ✓    |
-| `aarch64-unknown-linux-musl`         | 1.2.3 | 9.2.0   | ✓   | 6.1.0 |   ✓    |
-| `arm-linux-androideabi` [1]          | 9.0.8  | 9.0.8   | ✓   | 6.1.0 |   ✓    |
-| `arm-unknown-linux-gnueabi`          | 2.31   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `arm-unknown-linux-gnueabihf`        | 2.31   | 8.5.0   | ✓   | 6.1.0 |   ✓    |
-| `arm-unknown-linux-musleabi`         | 1.2.3 | 9.2.0   | ✓   | 6.1.0 |   ✓    |
-| `arm-unknown-linux-musleabihf`       | 1.2.3 | 9.2.0   | ✓   | 6.1.0 |   ✓    |
-| `armv5te-unknown-linux-gnueabi`      | 2.31   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `armv5te-unknown-linux-musleabi`     | 1.2.3 | 9.2.0   | ✓   | 6.1.0 |   ✓    |
-| `armv7-linux-androideabi` [1]        | 9.0.8  | 9.0.8   | ✓   | 6.1.0 |   ✓    |
-| `armv7-unknown-linux-gnueabi`        | 2.31   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `armv7-unknown-linux-gnueabihf`      | 2.31   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `armv7-unknown-linux-musleabi`       | 1.2.3 | 9.2.0   | ✓   | 6.1.0 |   ✓    |
-| `armv7-unknown-linux-musleabihf`     | 1.2.3 | 9.2.0   | ✓   | 6.1.0 |   ✓    |
-| `i586-unknown-linux-gnu`             | 2.31   | 9.4.0   | ✓   | N/A   |   ✓    |
-| `i586-unknown-linux-musl`            | 1.2.3 | 9.2.0   | ✓   | N/A   |   ✓    |
-| `i686-unknown-freebsd`               | 1.5    | 6.4.0   | ✓   | N/A   |       |
-| `i686-linux-android` [1]             | 9.0.8  | 9.0.8   | ✓   | 6.1.0 |   ✓    |
-| `i686-pc-windows-gnu`                | N/A    | 9.4     | ✓   | N/A   |   ✓    |
-| `i686-unknown-linux-gnu`             | 2.31   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `mips-unknown-linux-gnu`             | 2.30   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `mips-unknown-linux-musl`            | 1.2.3  | 9.2.0   | ✓   | 6.1.0 |   ✓    |
-| `mips64-unknown-linux-gnuabi64`      | 2.30   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `mips64-unknown-linux-muslabi64`     | 1.2.3 | 9.2.0   | ✓   | 6.1.0 |   ✓    |
-| `mips64el-unknown-linux-gnuabi64`    | 2.30   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `mips64el-unknown-linux-muslabi64`   | 1.2.3 | 9.2.0   | ✓   | 6.1.0 |   ✓    |
-| `mipsel-unknown-linux-gnu`           | 2.30   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `mipsel-unknown-linux-musl`          | 1.2.3 | 9.2.0   | ✓   | 6.1.0 |   ✓    |
-| `powerpc-unknown-linux-gnu`          | 2.31   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `powerpc64-unknown-linux-gnu`        | 2.31   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `powerpc64le-unknown-linux-gnu`      | 2.31   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `riscv64gc-unknown-linux-gnu`        | 2.31   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `s390x-unknown-linux-gnu`            | 2.31   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `sparc64-unknown-linux-gnu`          | 2.31   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `sparcv9-sun-solaris`                | 1.22.7 | 8.4.0   | ✓   | N/A   |       |
-| `thumbv6m-none-eabi` [4]             | 3.3.0  | 9.2.1   |     | N/A   |       |
-| `thumbv7em-none-eabi` [4]            | 3.3.0  | 9.2.1   |     | N/A   |       |
-| `thumbv7em-none-eabihf` [4]          | 3.3.0  | 9.2.1   |     | N/A   |       |
-| `thumbv7m-none-eabi` [4]             | 3.3.0  | 9.2.1   |     | N/A   |       |
-| `thumbv7neon-linux-androideabi` [1]  | 9.0.8  | 9.0.8   | ✓   | 6.1.0 |   ✓    |
-| `thumbv7neon-unknown-linux-gnueabihf`| 2.31   | 9.4.0   | ✓   | N/A   |   ✓    |
-| `thumbv8m.base-none-eabi` [4]        | 3.3.0  | 9.2.1   |     | N/A   |       |
-| `thumbv8m.main-none-eabi` [4]        | 3.3.0  | 9.2.1   |     | N/A   |       |
-| `thumbv8m.main-none-eabihf` [4]      | 3.3.0  | 9.2.1   |     | N/A   |       |
-| `wasm32-unknown-emscripten` [6]        | 3.1.14 | 15.0.0  | ✓   | N/A   |   ✓    |
-| `x86_64-linux-android` [1]           | 9.0.8  | 9.0.8   | ✓   | 6.1.0 |   ✓    |
-| `x86_64-pc-windows-gnu`              | N/A    | 9.3     | ✓   | N/A   |   ✓    |
-| `x86_64-sun-solaris`                 | 1.22.7 | 8.4.0   | ✓   | N/A   |       |
-| `x86_64-unknown-freebsd`             | 1.5    | 6.4.0   | ✓   | N/A   |       |
-| `x86_64-unknown-dragonfly` [2] [3]   | 6.0.1  | 10.3.0  | ✓   | N/A   |       |
-| `x86_64-unknown-illumos`             | 1.20.4 | 8.4.0   | ✓   | N/A   |       |
-| `x86_64-unknown-linux-gnu`           | 2.31   | 9.4.0   | ✓   | 6.1.0 |   ✓    |
-| `x86_64-unknown-linux-gnu:centos` [5]  | 2.17   | 4.8.5   | ✓   | 4.2.1 |   ✓    |
-| `x86_64-unknown-linux-musl`          | 1.2.3 | 9.2.0   | ✓   | N/A   |   ✓    |
-| `x86_64-unknown-netbsd` [3]          | 9.2.0  | 9.4.0   | ✓   | N/A   |       |
+| Target                                 |  libc  |  GCC   | C++ | QEMU  | `test` |
+|----------------------------------------|-------:|-------:|:---:|------:|:------:|
+| `aarch64-linux-android` [1]            | 9.0.8  | 9.0.8  | ✓   | 6.1.0 |   ✓    |
+| `aarch64-unknown-linux-gnu`            | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `aarch64-unknown-linux-gnu:centos` [7] | 2.17   | 4.8.5  |     | 4.2.1 |   ✓    |
+| `aarch64-unknown-linux-musl`           | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |
+| `arm-linux-androideabi` [1]            | 9.0.8  | 9.0.8  | ✓   | 6.1.0 |   ✓    |
+| `arm-unknown-linux-gnueabi`            | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `arm-unknown-linux-gnueabihf`          | 2.31   | 8.5.0  | ✓   | 6.1.0 |   ✓    |
+| `arm-unknown-linux-musleabi`           | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |
+| `arm-unknown-linux-musleabihf`         | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |
+| `armv5te-unknown-linux-gnueabi`        | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `armv5te-unknown-linux-musleabi`       | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |
+| `armv7-linux-androideabi` [1]          | 9.0.8  | 9.0.8  | ✓   | 6.1.0 |   ✓    |
+| `armv7-unknown-linux-gnueabi`          | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `armv7-unknown-linux-gnueabihf`        | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `armv7-unknown-linux-musleabi`         | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |
+| `armv7-unknown-linux-musleabihf`       | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |
+| `i586-unknown-linux-gnu`               | 2.31   | 9.4.0  | ✓   | N/A   |   ✓    |
+| `i586-unknown-linux-musl`              | 1.2.3  | 9.2.0  | ✓   | N/A   |   ✓    |
+| `i686-unknown-freebsd`                 | 1.5    | 6.4.0  | ✓   | N/A   |        |
+| `i686-linux-android` [1]               | 9.0.8  | 9.0.8  | ✓   | 6.1.0 |   ✓    |
+| `i686-pc-windows-gnu`                  | N/A    | 9.4    | ✓   | N/A   |   ✓    |
+| `i686-unknown-linux-gnu`               | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `mips-unknown-linux-gnu`               | 2.30   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `mips-unknown-linux-musl`              | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |
+| `mips64-unknown-linux-gnuabi64`        | 2.30   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `mips64-unknown-linux-muslabi64`       | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |
+| `mips64el-unknown-linux-gnuabi64`      | 2.30   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `mips64el-unknown-linux-muslabi64`     | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |
+| `mipsel-unknown-linux-gnu`             | 2.30   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `mipsel-unknown-linux-musl`            | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |
+| `powerpc-unknown-linux-gnu`            | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `powerpc64-unknown-linux-gnu`          | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `powerpc64le-unknown-linux-gnu`        | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `riscv64gc-unknown-linux-gnu`          | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `s390x-unknown-linux-gnu`              | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `sparc64-unknown-linux-gnu`            | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `sparcv9-sun-solaris`                  | 1.22.7 | 8.4.0  | ✓   | N/A   |        |
+| `thumbv6m-none-eabi` [4]               | 3.3.0  | 9.2.1  |     | N/A   |        |
+| `thumbv7em-none-eabi` [4]              | 3.3.0  | 9.2.1  |     | N/A   |        |
+| `thumbv7em-none-eabihf` [4]            | 3.3.0  | 9.2.1  |     | N/A   |        |
+| `thumbv7m-none-eabi` [4]               | 3.3.0  | 9.2.1  |     | N/A   |        |
+| `thumbv7neon-linux-androideabi` [1]    | 9.0.8  | 9.0.8  | ✓   | 6.1.0 |   ✓    |
+| `thumbv7neon-unknown-linux-gnueabihf`  | 2.31   | 9.4.0  | ✓   | N/A   |   ✓    |
+| `thumbv8m.base-none-eabi` [4]          | 3.3.0  | 9.2.1  |     | N/A   |        |
+| `thumbv8m.main-none-eabi` [4]          | 3.3.0  | 9.2.1  |     | N/A   |        |
+| `thumbv8m.main-none-eabihf` [4]        | 3.3.0  | 9.2.1  |     | N/A   |        |
+| `wasm32-unknown-emscripten` [6]        | 3.1.14 | 15.0.0 | ✓   | N/A   |   ✓    |
+| `x86_64-linux-android` [1]             | 9.0.8  | 9.0.8  | ✓   | 6.1.0 |   ✓    |
+| `x86_64-pc-windows-gnu`                | N/A    | 9.3    | ✓   | N/A   |   ✓    |
+| `x86_64-sun-solaris`                   | 1.22.7 | 8.4.0  | ✓   | N/A   |        |
+| `x86_64-unknown-freebsd`               | 1.5    | 6.4.0  | ✓   | N/A   |        |
+| `x86_64-unknown-dragonfly` [2] [3]     | 6.0.1  | 10.3.0 | ✓   | N/A   |        |
+| `x86_64-unknown-illumos`               | 1.20.4 | 8.4.0  | ✓   | N/A   |        |
+| `x86_64-unknown-linux-gnu`             | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |
+| `x86_64-unknown-linux-gnu:centos` [5]  | 2.17   | 4.8.5  | ✓   | 4.2.1 |   ✓    |
+| `x86_64-unknown-linux-musl`            | 1.2.3  | 9.2.0  | ✓   | N/A   |   ✓    |
+| `x86_64-unknown-netbsd` [3]            | 9.2.0  | 9.4.0  | ✓   | N/A   |        |
 <!--| `asmjs-unknown-emscripten` [7]       | 3.1.14 | 15.0.0  | ✓   | N/A   |   ✓    |-->
 
-[1] libc = bionic; Only works with native tests, that is, tests that do not depends on the
-    Android Runtime. For i686 some tests may fails with the error `assertion
-    failed: signal(libc::SIGPIPE, libc::SIG_IGN) != libc::SIG_ERR`, see
-    [issue #140](https://github.com/cross-rs/cross/issues/140) for more
-    information.
+[1] libc = bionic; Only works with native tests, that is, tests that do not
+    depends on the Android Runtime. For i686 some tests may fails with the
+    error `assertion failed: signal(libc::SIGPIPE, libc::SIG_IGN) !=
+    libc::SIG_ERR`, see [issue
+    #140](https://github.com/cross-rs/cross/issues/140) for more information.
 
 [2] No `std` component available.
 
-[3] For some \*BSD and Solaris targets, the libc column indicates the OS release version
-    from which libc was extracted.
+[3] For some \*BSD and Solaris targets, the libc column indicates the OS
+    release version from which libc was extracted.
 
 [4] libc = newlib
 
-[5] Must change `image = "ghcr.io/cross-rs/x86_64-unknown-linux-gnu:main-centos"` in `Cross.toml` for `[target.x86_64-unknown-linux-gnu]` to use the CentOS7-compatible target.
+[5] Must change `image =
+    "ghcr.io/cross-rs/x86_64-unknown-linux-gnu:main-centos"` in `Cross.toml`
+    for `[target.x86_64-unknown-linux-gnu]` to use the CentOS7-compatible
+    target.
 
 [6] libc = emscripten and GCC = clang
 
-[7] Must change `image = "ghcr.io/cross-rs/aarch64-unknown-linux-gnu:main-centos"` in `Cross.toml` for `[target.aarch64-unknown-linux-gnu]` to use the CentOS7-compatible target.
+[7] Must change `image =
+    "ghcr.io/cross-rs/aarch64-unknown-linux-gnu:main-centos"` in `Cross.toml`
+    for `[target.aarch64-unknown-linux-gnu]` to use the CentOS7-compatible
+    target.
 
 <!--[7] libc = emscripten and GCC = clang. The Docker images for these targets are currently not built automatically
 due to a [compiler bug](https://github.com/rust-lang/rust/issues/98216), you will have to build them yourself for now.-->

From d9d099eba647575ec3e28a537aecd13ea9201dd9 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 6 Feb 2024 21:28:55 +0100
Subject: [PATCH 14/20] README: Update an example

fix a renamed TOML table key and update suboptimal linebreaks.
---
 README.md | 32 +++++++++++++++++++-------------
 1 file changed, 19 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 379f49d36..b97eeb978 100644
--- a/README.md
+++ b/README.md
@@ -95,14 +95,20 @@ format for configuration and the possible configuration values are documented
 #### Option 1: Configuring `cross` directly in your `Cargo.toml`
 
 You can directly set [configuration values][config_file] in your `Cargo.toml`
-file, under the `[package.metadata.cross]` table, i.e. key prefix. An example
+file, under the `[workspace.metadata.cross]` table, i.e. key prefix. An example
 config snippet would look like this:
 
 ```toml,cargo
-[package.metadata.cross.target.aarch64-unknown-linux-gnu]
-xargo = false
-image = "test-image"
-runner = "custom-runner"
+[workspace.metadata.cross.target.aarch64-unknown-linux-gnu]
+# Install libssl-dev:arm64, see <https://github.com/cross-rs/cross/blob/main/docs/custom_images.md#adding-dependencies-to-existing-images>
+pre-build = [
+    "dpkg --add-architecture $CROSS_DEB_ARCH", 
+    "apt-get update && apt-get --assume-yes install libssl-dev:$CROSS_DEB_ARCH"
+]
+[workspace.metadata.cross.target.armv7-unknown-linux-gnueabi]
+image = "my/image:latest"
+[workspace.metadata.cross.build]
+env.volumes = ["A_DIRECTORY=/path/to/volume"]
 ```
 
 #### Option 2: Configuring `cross` via a `Cross.toml` file
@@ -268,17 +274,17 @@ terminate.
 
 [4] libc = newlib
 
-[5] Must change `image =
-    "ghcr.io/cross-rs/x86_64-unknown-linux-gnu:main-centos"` in `Cross.toml`
-    for `[target.x86_64-unknown-linux-gnu]` to use the CentOS7-compatible
-    target.
+[5] Must change 
+    `image = "ghcr.io/cross-rs/x86_64-unknown-linux-gnu:main-centos"` in
+    `Cross.toml` for `[target.x86_64-unknown-linux-gnu]` to use the
+    CentOS7-compatible target.
 
 [6] libc = emscripten and GCC = clang
 
-[7] Must change `image =
-    "ghcr.io/cross-rs/aarch64-unknown-linux-gnu:main-centos"` in `Cross.toml`
-    for `[target.aarch64-unknown-linux-gnu]` to use the CentOS7-compatible
-    target.
+[7] Must change 
+    `image = "ghcr.io/cross-rs/aarch64-unknown-linux-gnu:main-centos"` in
+    `Cross.toml` for `[target.aarch64-unknown-linux-gnu]` to use the
+    CentOS7-compatible target.
 
 <!--[7] libc = emscripten and GCC = clang. The Docker images for these targets are currently not built automatically
 due to a [compiler bug](https://github.com/rust-lang/rust/issues/98216), you will have to build them yourself for now.-->

From 13cd074994970202606d52cb5b032fe8c69b1975 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 13 Feb 2024 06:25:35 +0100
Subject: [PATCH 15/20] docs/custom_images: Move architecture section up

to make sure it's more visible and deduplicate installation examples
with the `CROSS_DEB_ARCH` variable.
---
 docs/custom_images.md | 29 ++++++++++-------------------
 1 file changed, 10 insertions(+), 19 deletions(-)

diff --git a/docs/custom_images.md b/docs/custom_images.md
index 13f924f2e..8ebc2370b 100644
--- a/docs/custom_images.md
+++ b/docs/custom_images.md
@@ -1,11 +1,20 @@
 <!--toc:start-->
+- [Automatic Target Architecture on Debian](#automatic-target-architecture-on-debian)
 - [Custom Images](#custom-images)
   - [Adding Dependencies to Existing Images](#adding-dependencies-to-existing-images)
   - [Custom Dockerfile](#custom-dockerfile)
   - [Custom Image](#custom-image)
-- [Automatic Target Architecture on Debian](#automatic-target-architecture-on-debian)
 <!--toc:end-->
 
+# Automatic Target Architecture on Debian
+
+Custom images generated from config `dockerfile` or `pre-build` keys will
+export `CROSS_DEB_ARCH`, which allows you to install packages from
+Ubuntu/Debian repositories without having to specify the exact architecture.
+You can find an
+[example of this here](#adding-dependencies-to-existing-images).
+
+
 # Custom Images
 
 `cross` provides default Docker images for the targets listed [in the
@@ -75,24 +84,6 @@ default one. Normal Docker behavior applies, so:
 - If only `tag` is omitted, then Docker will use the `latest` tag.
 
 
-# Automatic Target Architecture on Debian
-
-Custom images generated from config `dockerfile` or `pre-build` keys will
-export `CROSS_DEB_ARCH`, which allows you to install packages from
-Ubuntu/Debian repositories without having to specify the exact architecture.
-For example, to install `OpenSSL` for the target, you can do:
-
-```toml
-[target.aarch64-unknown-linux-gnu]
-pre-build = [
-  "dpkg --add-architecture $CROSS_DEB_ARCH", 
-  "apt-get update && apt-get --assume-yes install libssl-dev:$CROSS_DEB_ARCH"
-]
-```
-
-Here, `CROSS_DEB_ARCH` will automatically evaluate to `arm64`, without you
-having to explicitly provide it.
-
 
 [config-target-pre-build]: ./config.md#targettargetpre-build
 [config_target_dockerfile]: ./config.md#targettargetdockerfile

From 19dd2aed53c8e32f6b95a050f7936ba56e5f3c5b Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 13 Feb 2024 06:35:33 +0100
Subject: [PATCH 16/20] docs/config_file: Fix suboptimal linebreak.

---
 docs/config_file.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/config_file.md b/docs/config_file.md
index dafc46778..13d935fe1 100644
--- a/docs/config_file.md
+++ b/docs/config_file.md
@@ -33,8 +33,8 @@ elements:
 
 The `build` key allows you to set global variables, e.g.:
 
-> *NOTE*: `$CROSS_DEB_ARCH` is automatically provided by cross, [see
-> here][custom_images_automatic_arch].
+> *NOTE*: `$CROSS_DEB_ARCH` is automatically provided by cross,
+> [see here][custom_images_automatic_arch].
 
 ```toml
 [build]

From d82f2234eb90d3ca650d2b0d466c75d12a02924a Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 13 Feb 2024 06:35:57 +0100
Subject: [PATCH 17/20] docs/env_var: Document missing variable from #661.

---
 docs/environment_variables.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/environment_variables.md b/docs/environment_variables.md
index 2d60192c1..bafc72f25 100644
--- a/docs/environment_variables.md
+++ b/docs/environment_variables.md
@@ -49,6 +49,10 @@ In-depth documentation with examples can be found [here][env-examples].
   `cross` can convert it to a fully-qualified toolchain name.
 - `CROSS_CONTAINER_ENGINE_NO_BUILDKIT`: The container engine does not have
   `buildx` command (or BuildKit support) when building custom images.
+- `CROSS_NO_WARNINGS`: Set to `1` to panic on warnings from `cross`, before
+  building the executables.
+  Use `0` to disable this behaviour.
+  The no warnings behaviour is implicitly enabled in CI pipelines.
 
 All config file options can also be specified using environment variables. For
 example, setting `CROSS_BUILD_XARGO=1` is identical to setting `build.xargo =

From 5b3cd39f07b332c8ce8bfc95a557d17eae4f9451 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 13 Feb 2024 07:04:47 +0100
Subject: [PATCH 18/20] cross_toml: Include correct docs file

instead of the `cross_toml` file that has been replaced as part of this
PR.
---
 src/cross_toml.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/cross_toml.rs b/src/cross_toml.rs
index 2884e9f57..b200abf79 100644
--- a/src/cross_toml.rs
+++ b/src/cross_toml.rs
@@ -1,4 +1,4 @@
-#![doc = include_str!("../docs/cross_toml.md")]
+#![doc = include_str!("../docs/config_file.md")]
 
 use crate::docker::custom::PreBuild;
 use crate::docker::PossibleImage;

From 936804eb2c879528ce9e1e63847ddeb558174d09 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 13 Feb 2024 07:05:40 +0100
Subject: [PATCH 19/20] chore: Fix warnings during docs build

and make sure that `cross_toml` shows up as part of the official
documentation along the way.
---
 src/cross_toml.rs    | 7 ++++++-
 src/docker/engine.rs | 2 +-
 src/docker/image.rs  | 2 +-
 src/lib.rs           | 5 +++--
 4 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/src/cross_toml.rs b/src/cross_toml.rs
index b200abf79..c78a812a0 100644
--- a/src/cross_toml.rs
+++ b/src/cross_toml.rs
@@ -1,4 +1,9 @@
-#![doc = include_str!("../docs/config_file.md")]
+//! The `Cross.toml` configuration file.
+//!
+//! For a detailed user documentation of the file and the contents please refer to the [docs in the
+//! repo][1].
+//!
+//! [1]: https://github.com/har7an/cross/blob/docs/restructure-docs-folder/docs/config_file.md
 
 use crate::docker::custom::PreBuild;
 use crate::docker::PossibleImage;
diff --git a/src/docker/engine.rs b/src/docker/engine.rs
index 0b65d05d1..0e42cb3f1 100644
--- a/src/docker/engine.rs
+++ b/src/docker/engine.rs
@@ -51,7 +51,7 @@ impl EngineType {
     /// Some container engines, especially podman, do not support the `type`
     /// key of `--cache-from` during the image build steps. They also do
     /// not support any tags for the `--cache-from` steps either. See:
-    /// https://docs.podman.io/en/latest/markdown/podman-build.1.html#cache-from
+    /// <https://docs.podman.io/en/latest/markdown/podman-build.1.html#cache-from>
     #[must_use]
     pub const fn supports_cache_from_type(&self) -> bool {
         matches!(self, Self::Docker | Self::Nerdctl)
diff --git a/src/docker/image.rs b/src/docker/image.rs
index cbce5c066..e1ff332bf 100644
--- a/src/docker/image.rs
+++ b/src/docker/image.rs
@@ -103,7 +103,7 @@ impl std::fmt::Display for PossibleImage {
 }
 /// The architecture/platform to use in the image
 ///
-/// https://github.com/containerd/containerd/blob/release/1.6/platforms/platforms.go#L63
+/// <https://github.com/containerd/containerd/blob/release/1.6/platforms/platforms.go#L63>
 #[derive(Debug, Clone, PartialEq, Eq, serde::Deserialize)]
 #[serde(try_from = "String")]
 pub struct ImagePlatform {
diff --git a/src/lib.rs b/src/lib.rs
index f10607e3a..08fe42c24 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -8,7 +8,8 @@
 //! <strong>⚠️ Warning:</strong> The cross library is for internal
 //! use only: only the command-line interface is stable. The library
 //! may change at any point for any reason. For documentation on the
-//! CLI, please see the repository <a href="https://github.com/cross-rs/cross">README</a>
+//! CLI, please see the repository <a href="https://github.com/cross-rs/cross">README</a>,
+//! <a href="https://github.com/cross-rs/cross/tree/main/docs">docs folder</a>
 //! or the <a href="https://github.com/cross-rs/cross/wiki">wiki</a>.
 //! </p>
 
@@ -33,7 +34,7 @@ mod tests;
 pub mod cargo;
 pub mod cli;
 pub mod config;
-mod cross_toml;
+pub mod cross_toml;
 pub mod docker;
 pub mod errors;
 mod extensions;

From f647ed28b3bf599ee057ad14593d1672d73735f4 Mon Sep 17 00:00:00 2001
From: Andreas Hartmann <hartan@7x.de>
Date: Tue, 20 Feb 2024 11:13:17 +0100
Subject: [PATCH 20/20] cross_toml: Fix docs URL

to point to the original repo instead of the fork for this PR.
---
 src/cross_toml.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/cross_toml.rs b/src/cross_toml.rs
index c78a812a0..7965ca552 100644
--- a/src/cross_toml.rs
+++ b/src/cross_toml.rs
@@ -3,7 +3,7 @@
 //! For a detailed user documentation of the file and the contents please refer to the [docs in the
 //! repo][1].
 //!
-//! [1]: https://github.com/har7an/cross/blob/docs/restructure-docs-folder/docs/config_file.md
+//! [1]: https://github.com/cross-rs/cross/blob/main/docs/config_file.md
 
 use crate::docker::custom::PreBuild;
 use crate::docker::PossibleImage;