docs/config_file: Add docs for config file

taken from the wiki with some added information.

Author: har7an

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