Clarify Cross.toml usage

[JayKickliter]

This is a continuation of #532. At first glance, without any context, some of the comments in cross_toml.md are not very clear:

---

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:

[build.env]
volumes = ["VOL1_ARG", "VOL2_ARG"]

At first I thought "VOL1_ARG" was just a place-holder for a literal volume path. It took me a while to figure out that the capitalization is because it represents a volume that defined in an environment variable on the host. Next question is, what should "VOL1_ARG" look like? Does it contain only the source volume, or source and destination? What can it be used for?

---

passthrough = ["IMPORTANT_ENV_VARIABLES"]

To someone very new to cross, who may not entirely understand the implications of building inside a container, it may not be clear that these are global variables defined need to still be defined by the end-user and that will simply be redefined inside the container. Or put another way, one can't do

[build.env]
passthrough = ["MY_PARTICULAR_VAR=some_value"]

(I think?), but instead needs to define the following in Cross.toml

[build.env]
passthrough = ["MY_PARTICULAR_VAR"]

followed by something like the following when using cross

$ MY_PARTICULAR_VAR=some_value cross build

[JayKickliter]

To be clear, I still don't know how or why to use some of these features, and my guesses above may be completely wrong.

[Emilgardis]

question is, what should "VOL1_ARG" look like? Does it contain only the source volume, or source and destination? What can it be used for?

This is: https://github.com/cross-rs/cross#mounting-volumes-into-the-build-environment

The whole situation is also bettered with #682, I'll make sure to provide more explanation for the values.

basically, build.env.volumes takes a list of environment variables with paths to mount in the container. build.env.passthrough will make the environment variable exposed inside the container.

To someone very new to cross, who may not entirely understand the implications of building inside a container

good point, we could maybe clarify better/simpler how cross actually works. I'll leave a quick explanation here if anyone is interested.

The cross tool utilizes docker to containerize the process of cross-compilation, it does this by providing the needed cross-compilation tools inside an image, and with cross build you'll mount/attach your rust installation and source files to build with cargo.

[Alexhuszagh]

I've been in favor of adding MY_PARTICULAR_VAR=some_value personally, but since we should be able to forward it to Docker as-is, since we use the docker run --env ${VAR} ... syntax anyway.

The offending lines are below, and I think we can just remove them as split on the first = symbol, if present:

cross/src/docker.rs

Lines 118 to 120 in 1689de1

	if var.contains('=') {
	bail!("environment variable names must not contain the '=' character");
	}

[Emilgardis]

that sounds good, I'll add it to #682, I've also done a similar thing there but for the toml,

cross/docs/cross_toml.md

Line 21 in c132c6c

var.ARG1 = "value"

[Alexhuszagh]

I've added #743 to track this.

[Alexhuszagh]

FYI: #748 has been merged, so you can now define the variable in env.passthrough. This, if built on cross from main, now works:

[build.env]
passthrough = ["VAR=VALUE"]

$VAR will then be available inside the container with the value of VALUE.

[Alexhuszagh]

I've extensively updated the Wiki documentation for this reason. This should make it very clear what each variable means, and why. I'll be looking through the source code to see if any config option is not documented (EDIT: everything is documented). For example:

build

[build]
xargo = true                                   # enable the use of xargo by default
default-target = "x86_64-unknown-linux-gnu"    # use this target if none is explicitly provided

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:

[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.

target.TARGET

The target key allows you to specify parameters for specific compilation targets.

[target.aarch64-unknown-linux-gnu]
xargo = false              # disable the use of xargo
image = "test-image"       # use a different image for the target
runner = "custom-runner"   # wrapper to run the binary