Skip to content

Commit c87a52a

Browse files
EmilgardisEmilgardis
authored
Docs: Restructure docs folder (#1438)
Sort of a follow-up to #1315 which revealed a "mismatch" between what the `README` and `docs/` folder immediately provide as info compared to what's actually available. This restructures the `docs/` folder and adds information from various sources to it: - The README, - The Wiki - Examples found in the Wiki At the moment this duplicates a decent amount of information already available on the Wiki. Strictly speaking this was already the case before this MR, where the `README` and `cross_toml` each contained information from the Wiki. My motivation for moving these things into the `docs/` folder is that: 1. I'm much more used to finding information in a `docs` folder than to check for the Wiki. Most projects just don't use the Wiki 2. I usually expect the documentation to be part of what I check out, and the Wiki is *not* a part of this repo, but its own repo 3. Docs can be updated *as part of the same PR* that updates the respective code, and arbitrary checkouts of the repo will always contain the docs *valid for that version* On a personal note, I much prefer editing text in an editor I'm comfortable with, and Browsers don't fall into that category. I'm curious to hear your thoughts on this proposed change.
2 parents f272b47 + f647ed2 commit c87a52a

14 files changed

+1274
-356
lines changed

‎README.md

Lines changed: 121 additions & 232 deletions
Large diffs are not rendered by default.

‎docs/cargo_configuration.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
<!--toc:start-->
2+
- [Configuring `cross`](#configuring-cross)
3+
- [Configuring Cargo through environment variables](#configuring-cargo-through-environment-variables)
4+
- [Use Xargo instead of Cargo](#use-xargo-instead-of-cargo)
5+
<!--toc:end-->
6+
7+
# Configuring `cross`
8+
9+
Please refer to the following docs:
10+
11+
- [config file](./config_file.md)
12+
- [env variables](./environment_variables.md)
13+
14+
15+
# Configuring Cargo through environment variables
16+
17+
When cross-compiling, `cargo` does not use environment variables such as
18+
`RUSTFLAGS`, and must be provided using `CARGO_TARGET_${TARGET}_${OPTION}`.
19+
Please note that some of these may be provided by the image themselves, such as
20+
runners, and should be overwritten with caution. A list of important flags
21+
includes:
22+
23+
- `CARGO_TARGET_${TARGET}_LINKER`: specify a custom linker passed to rustc.
24+
- `CARGO_TARGET_${TARGET}_RUNNER`: specify the wrapper to run executables.
25+
- `CARGO_TARGET_${TARGET}_RUSTFLAGS`: add additional flags passed to rustc.
26+
27+
Any of the following [flags][cargo-flags] can be provided, and are converted to
28+
uppercase. For example, changing `foo-bar` would be provided as
29+
`CARGO_TARGET_${TARGET}_FOO_BAR`.
30+
31+
For example, to run binaries on `i686-unknown-linux-gnu` with Qemu, first
32+
create a custom image containing Qemu, and run with the following command:
33+
34+
```
35+
CARGO_TARGET_I686_UNKNOWN_LINUX_GNU_RUNNER=qemu-i386 cross run ...
36+
```
37+
38+
39+
# Use Xargo instead of Cargo
40+
41+
By default, `cross` uses `xargo` to build your Cargo project only for all
42+
non-standard targets (i.e. something not reported by rustc/rustup). However,
43+
you can use the `build.xargo` or `target.{{TARGET}}.xargo` field in
44+
`Cross.toml` to force the use of `xargo`:
45+
46+
```toml
47+
# all the targets will use `xargo`
48+
[build]
49+
xargo = true
50+
```
51+
52+
Or,
53+
54+
```toml
55+
# only this target will use `xargo`
56+
[target.aarch64-unknown-linux-gnu]
57+
xargo = true
58+
```
59+
60+
`xargo = false` will work the opposite way (pick cargo always) and is useful
61+
when building for custom targets that you know to work with cargo.
62+
63+
64+
[cargo-flags]: https://doc.rust-lang.org/cargo/reference/config.html#target

‎docs/config_file.md

Lines changed: 304 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,304 @@
1+
<!--toc:start-->
2+
- [`build`](#build)
3+
- [`build.env`](#buildenv)
4+
- [`build.dockerfile`](#builddockerfile)
5+
- [`build.zig`](#buildzig)
6+
- [`target.TARGET`](#targettarget)
7+
- [`target.TARGET.pre-build`](#targettargetpre-build)
8+
- [`target.TARGET.image`](#targettargetimage)
9+
- [`target.TARGET.env`](#targettargetenv)
10+
- [`target.TARGET.dockerfile`](#targettargetdockerfile)
11+
- [`target.TARGET.zig`](#targettargetzig)
12+
<!--toc:end-->
13+
14+
> **Note**: Additional configuration is available through
15+
> [environment variables](./environment_variables.md)
16+
17+
You can place a `Cross.toml` file in the root of your Cargo project or use a
18+
`CROSS_CONFIG` environment variable to tweak cross's behavior. You can also use
19+
`package.metadata.cross.KEY` in `Cargo.toml`, and the priority of settings is
20+
environment variables override `Cross.toml` options, which override
21+
`Cargo.toml` options. Annotated examples of both
22+
[`Cross.toml`][example-cross-toml] and [`Cargo.toml`][example-cargo-toml] are
23+
provided.
24+
25+
For example, the `[build]` table in `Cross.toml` is identical to setting
26+
`[package.metadata.cross.build]` in `Cargo.toml`.
27+
28+
The `cross` configuration in the `Cross.toml` file can contain the following
29+
elements:
30+
31+
32+
# `build`
33+
34+
The `build` key allows you to set global variables, e.g.:
35+
36+
> *NOTE*: `$CROSS_DEB_ARCH` is automatically provided by cross,
37+
> [see here][custom_images_automatic_arch].
38+
39+
```toml
40+
[build]
41+
build-std = false # do not build the std library. has precedence over xargo
42+
xargo = true # enable the use of xargo by default
43+
zig = false # do not use zig cc for the builds
44+
default-target = "x86_64-unknown-linux-gnu" # use this target if none is explicitly provided
45+
pre-build = [ # additional commands to run prior to building the package
46+
"dpkg --add-architecture $CROSS_DEB_ARCH",
47+
"apt-get update && apt-get --assume-yes install libssl-dev:$CROSS_DEB_ARCH"
48+
]
49+
```
50+
51+
52+
# `build.env`
53+
54+
With the `build.env` key you can globally set volumes that should be mounted in
55+
the Docker container or environment variables that should be passed through.
56+
For example:
57+
58+
```toml
59+
[build.env]
60+
volumes = ["VOL1_ARG", "VOL2_ARG=/path/to/volume"]
61+
passthrough = ["VAR1_ARG", "VAR2_ARG=VALUE"]
62+
```
63+
64+
Note how in the environment variable passthrough, we can provide a definition
65+
for the variable as well. `VAR1_ARG` will be the value of the environment
66+
variable on the host, while `VAR2_ARG` will be `VALUE`. Likewise, the path to
67+
the volume for `VOL1_ARG` will be the value of the environment variable on the
68+
host, while `VOL2_ARG` will be `/path/to/volume`.
69+
70+
71+
# `build.dockerfile`
72+
73+
> If the image you want to use is already available from a container registry,
74+
> check out the `target.TARGET.image` option below.
75+
76+
The `build.dockerfile` key lets you provide a custom Docker image for all
77+
targets, except those specified `target.TARGET.dockerfile`. The value can be
78+
provided as either a table or a string. If `build.dockerfile` is set to a
79+
string, it's equivalent to setting `build.dockerfile.file` to that value. For
80+
example, using only a string:
81+
82+
```toml
83+
[build]
84+
dockerfile = "./Dockerfile"
85+
```
86+
87+
Or using a table:
88+
89+
```toml
90+
[build.dockerfile]
91+
file = "./Dockerfile" # the dockerfile to use relative to the `Cargo.toml`
92+
context = "." # the context folder to build the script in. defaults to `.`
93+
build-args = { ARG1 = "foo" } # https://docs.docker.com/engine/reference/builder/#arg
94+
```
95+
96+
`cross` will build and use the image that was built instead of the default
97+
image. It's recommended to base your custom image on the default Docker image
98+
that `cross` uses: `ghcr.io/cross-rs/{{TARGET}}:{{VERSION}}` (where
99+
`{{VERSION}}` is `cross`'s version). This way you won't have to figure out how
100+
to install a cross-C toolchain in your custom image.
101+
102+
> *NOTE*: `$CROSS_DEB_ARCH` is automatically provided by cross, [see
103+
> here][custom_images_automatic_arch].
104+
105+
``` Dockerfile
106+
FROM ghcr.io/cross-rs/aarch64-unknown-linux-gnu:latest
107+
108+
RUN dpkg --add-architecture $CROSS_DEB_ARCH && \
109+
apt-get update && \
110+
apt-get install --assume-yes libfoo:$CROSS_DEB_ARCH
111+
```
112+
113+
`cross` will provide the argument `CROSS_BASE_IMAGE` which points to the
114+
default image `cross` would use for the target. Instead of the above, you can
115+
also then do the following:
116+
117+
```Dockerfile
118+
ARG CROSS_BASE_IMAGE
119+
FROM $CROSS_BASE_IMAGE
120+
RUN ...
121+
```
122+
123+
124+
# `build.zig`
125+
126+
The `build.zig` key lets you use `zig cc` as a cross-compiler, enabling
127+
cross-compilation to numerous architectures and glibc versions using a single
128+
Docker image. Note that `zig cc` doesn't support all targets: only a subset of
129+
our Linux GNU targets, so it might be better to set these values in
130+
`target.TARGET.zig` instead. The value can be provided as either a table, a bool,
131+
or a string. If `build.zig` is set to a string, it's equivalent to setting
132+
`build.zig.version` to that value and `build.zig.enable` to true:
133+
134+
```toml
135+
[build]
136+
zig = "2.17"
137+
```
138+
139+
If `build.zig` is set to a bool, it's equivalent to setting `build.zig.enable`
140+
to that value:
141+
142+
```toml
143+
[build]
144+
zig = true
145+
```
146+
147+
Or using a table:
148+
149+
```toml
150+
[build.zig]
151+
enable = true # enable or disable the use of zig cc
152+
version = "2.17" # the glibc version to use
153+
image = "myimage" # a custom image containing zig to use
154+
```
155+
156+
157+
# `target.TARGET`
158+
159+
The `target` key allows you to specify parameters for specific compilation
160+
targets:
161+
162+
```toml
163+
[target.aarch64-unknown-linux-gnu]
164+
build-std = false # always build the std library. has precedence over xargo
165+
xargo = false # disable the use of xargo
166+
image = "test-image" # use a different image for the target
167+
runner = "qemu-user" # wrapper to run the binary (must be `qemu-system`, `qemu-user`, or `native`).
168+
```
169+
170+
171+
# `target.TARGET.pre-build`
172+
173+
The `pre-build` field can reference a file to copy and run. This file is
174+
relative to the container context, which would be the workspace root, or the
175+
current directory if `--manifest-path` is used. For more involved scripts,
176+
consider using `target.TARGET.dockerfile` instead to directly control the
177+
execution.
178+
179+
This script will be invoked as `RUN ./pre-build-script $CROSS_TARGET` where
180+
`$CROSS_TARGET` is the target triple.
181+
182+
```toml
183+
[target.aarch64-unknown-linux-gnu]
184+
pre-build = "./scripts/my-script.sh"
185+
```
186+
187+
```bash
188+
$ cat ./scripts/my-script.sh
189+
#!/usr/bin/env bash
190+
191+
apt-get install libssl-dev -y
192+
```
193+
194+
`pre-build` can also be a list of commands to directly run inside the image:
195+
196+
> *NOTE*: `$CROSS_DEB_ARCH` is automatically provided by cross, [see
197+
> here][custom_images_automatic_arch].
198+
199+
```toml
200+
[target.aarch64-unknown-linux-gnu]
201+
pre-build = [
202+
"dpkg --add-architecture $CROSS_DEB_ARCH",
203+
"apt-get update",
204+
"apt-get install --assume-yes libfoo:$CROSS_DEB_ARCH"
205+
]
206+
```
207+
208+
209+
# `target.TARGET.image`
210+
211+
```toml
212+
[target.aarch64-unknown-linux-gnu]
213+
image = "my/image:latest"
214+
```
215+
216+
In the example above, `cross` will use a image named `my/image:latest` instead of
217+
the default one. Normal Docker behavior applies, so:
218+
219+
- Docker will first look for a local image named `my/image:latest`
220+
- If it doesn't find a local image, then it will look in Docker Hub.
221+
- If only `image:latest` is specified, then Docker won't look in Docker Hub.
222+
- If the tag is omitted, then Docker will use the `latest` tag.
223+
224+
The `image` key can also take the toolchains/platforms supported by the image:
225+
226+
```toml
227+
[target.aarch64-unknown-linux-gnu]
228+
image.name = "alpine:edge"
229+
image.toolchain = ["x86_64-unknown-linux-musl", "linux/arm64=aarch64-unknown-linux-musl"] # Defaults to `x86_64-unknown-linux-gnu`
230+
```
231+
232+
233+
234+
# `target.TARGET.env`
235+
236+
The `env` key allows you to specify environment variables that should be used
237+
for a specific compilation target. This is similar to `build.env`, but allows
238+
you to be more specific per target:
239+
240+
```toml
241+
[target.x86_64-unknown-linux-gnu.env]
242+
volumes = ["VOL1_ARG", "VOL2_ARG=/path/to/volume"]
243+
passthrough = ["VAR1_ARG", "VAR2_ARG=VALUE"]
244+
```
245+
246+
247+
# `target.TARGET.dockerfile`
248+
249+
The `dockerfile` key lets you provide a custom Docker image for the
250+
given target. The value can be provided as either a table or a string. If
251+
`target.TARGET.dockerfile` is set to a string, it's equivalent to setting
252+
`target.(...).dockerfile.file` to that value. For example, using only a string:
253+
254+
```toml
255+
[target.aarch64-unknown-linux-gnu]
256+
dockerfile = "./Dockerfile"
257+
```
258+
259+
Or using a table:
260+
261+
```toml
262+
[target.aarch64-unknown-linux-gnu.dockerfile]
263+
file = "./Dockerfile" # the dockerfile to use relative to the `Cargo.toml`
264+
context = "." # the context folder to build the script in. defaults to `.`
265+
build-args = { ARG1 = "foo" } # https://docs.docker.com/engine/reference/builder/#arg
266+
```
267+
268+
269+
# `target.TARGET.zig`
270+
271+
The `target.TARGET.zig` key lets you use `zig cc` as a cross-compiler, enabling
272+
cross-compilation to numerous architectures and glibc versions using a single
273+
Docker image. The value can be provided as either a table, a bool, or a string.
274+
If `target.TARGET.zig` is set to a string, it's equivalent to setting
275+
`target.TARGET.zig.version` to that value and `target.TARGET.zig.enable` to
276+
true:
277+
278+
```toml
279+
[target.aarch64-unknown-linux-gnu]
280+
zig = "2.17"
281+
```
282+
283+
If `target.TARGET.zig` is set to a bool, it's equivalent to setting
284+
`target.TARGET.zig.enable` to that value:
285+
286+
```toml
287+
[target.aarch64-unknown-linux-gnu]
288+
zig = true
289+
```
290+
291+
Or using a table:
292+
293+
```toml
294+
[target.aarch64-unknown-linux-gnu.zig]
295+
enable = true # enable or disable the use of zig cc
296+
version = "2.17" # the glibc version to use
297+
image = "myimage" # a custom image containing zig to use
298+
```
299+
300+
301+
302+
[example-cross-toml]: https://github.com/cross-rs/wiki_assets/blob/main/Configuration/Cross.toml
303+
[example-cargo-toml]: https://github.com/cross-rs/wiki_assets/blob/main/Configuration/Cargo.toml
304+
[custom_images_automatic_arch]: ./custom_images.md#automatic-target-architecture-on-debian

0 commit comments

Comments
 (0)