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.
cross-rs · Feb 13, 2024 · ef2e377 · ef2e377
1 parent 2fd1da1
commit ef2e377
Show file tree

Hide file tree

Showing 4 changed files with 186 additions and 28 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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/