1
1
[ ![ crates.io] ( https://img.shields.io/crates/v/cross.svg )] ( https://crates.io/crates/cross )
2
2
[ ![ crates.io] ( https://img.shields.io/crates/d/cross.svg )] ( https://crates.io/crates/cross )
3
- [ ![ Build Status] ( https://travis-ci.org/ rust-embedded/cross.svg?branch= master )] ( https://travis-ci.org /rust-embedded/cross )
3
+ [ ![ Build Status] ( https://img.shields.io/azure-devops/build/ rust-embedded/c0ce10ee-fd41-4551-b3e3-9612e8ab62f3/2/ master )] ( https://dev.azure.com /rust-embedded/cross/_build?definitionId=2 )
4
4
[ ![ Docker Pulls] ( https://img.shields.io/docker/pulls/rustembedded/cross )] ( https://hub.docker.com/r/rustembedded/cross )
5
5
6
6
# ` cross `
7
7
8
- > " Zero setup" cross compilation and " cross testing" of Rust crates
8
+ > “ Zero setup” cross compilation and “ cross testing” of Rust crates
9
9
10
10
This project is developed and maintained by the [ Tools team] [ team ] .
11
11
@@ -19,8 +19,6 @@ This project is developed and maintained by the [Tools team][team].
19
19
<em> ` cross test ` ing a crate for the aarch64-unknown-linux-gnu target</em >
20
20
</p>
21
21
22
- ** Disclaimer** : Only works on a x86_64 Linux host (e.g. Travis CI is supported)
23
-
24
22
## Features
25
23
26
24
- ` cross ` will provide all the ingredients needed for cross compilation without
@@ -29,7 +27,7 @@ This project is developed and maintained by the [Tools team][team].
29
27
- ` cross ` provides an environment, cross toolchain and cross compiled libraries
30
28
(e.g. OpenSSL), that produces the most portable binaries.
31
29
32
- - " cross testing" , ` cross ` can test crates for architectures other than i686 and
30
+ - “ cross testing” , ` cross ` can test crates for architectures other than i686 and
33
31
x86_64.
34
32
35
33
- The stable, beta and nightly channels are supported.
@@ -38,10 +36,10 @@ This project is developed and maintained by the [Tools team][team].
38
36
39
37
- [ rustup] ( https://rustup.rs/ )
40
38
41
- - [ Docker] ( https://www.docker.com/ ) . Note that non-sudo users need to be in the
42
- ` docker ` group. Read the official [ post-installation steps for Linux ] [ post ] .
39
+ - [ Docker] ( https://www.docker.com/ ) . Note that on Linux non-sudo users need to be in the
40
+ ` docker ` group. Read the official [ post-installation steps] [ post ] .
43
41
44
- [ post ] : https://docs.docker.com/engine/installation /linux/linux-postinstall/
42
+ [ post ] : https://docs.docker.com/install /linux/linux-postinstall/
45
43
46
44
- A Linux kernel with [ binfmt_misc] support is required for cross testing.
47
45
@@ -83,7 +81,7 @@ You can place a `Cross.toml` file in the root of your Cargo project to tweak
83
81
84
82
` cross ` provides default Docker images for the targets listed below. However, it
85
83
can't cover every single use case out there. For other targets, or when the
86
- default image is not enough, you can use the ` target.$ TARGET.image ` field in
84
+ default image is not enough, you can use the ` target.{{ TARGET}} .image ` field in
87
85
` Cross.toml ` to use custom Docker image for a specific target:
88
86
89
87
``` toml
@@ -103,12 +101,12 @@ the default one. Normal Docker behavior applies, so:
103
101
- If only ` tag ` is omitted, then Docker will use the ` latest ` tag.
104
102
105
103
It's recommended to base your custom image on the default Docker image that
106
- cross uses: ` rustembedded/cross:$ TARGET-$ VERSION ` (where ` $ VERSION` is cross's version).
104
+ cross uses: ` rustembedded/cross:{{ TARGET}}-{{ VERSION}} ` (where ` {{ VERSION}} ` is cross's version).
107
105
This way you won't have to figure out how to install a cross C toolchain in your
108
106
custom image. Example below:
109
107
110
108
``` Dockerfile
111
- FROM rustembedded/cross:aarch64-unknown-linux-gnu-0.1.4
109
+ FROM rustembedded/cross:aarch64-unknown-linux-gnu-0.1.15
112
110
113
111
RUN dpkg --add-architecture arm64 && \
114
112
apt-get update && \
@@ -129,7 +127,6 @@ environment.
129
127
In the instances that you do want to pass through environment variables, this
130
128
can be done via ` build.env.passthrough ` in your ` Cross.toml ` :
131
129
132
-
133
130
``` toml
134
131
[build .env ]
135
132
passthrough = [
@@ -153,7 +150,7 @@ passthrough = [
153
150
154
151
By default, ` cross ` uses ` cargo ` to build your Cargo project * unless* you are
155
152
building for one of the ` thumbv*-none-eabi* ` targets; in that case, it uses
156
- ` xargo ` . However, you can use the ` build.xargo ` or ` target.$ TARGET.xargo ` field
153
+ ` xargo ` . However, you can use the ` build.xargo ` or ` target.{{ TARGET}} .xargo ` field
157
154
in ` Cross.toml ` to force the use of ` xargo ` :
158
155
159
156
``` toml
@@ -175,8 +172,8 @@ that only support `xargo`.
175
172
176
173
## Supported targets
177
174
178
- A target is considered as " supported" if ` cross ` can cross compile a
179
- " non-trivial" (binary) crate, usually Cargo, for that target.
175
+ A target is considered as “ supported” if ` cross ` can cross compile a
176
+ “ non-trivial” (binary) crate, usually Cargo, for that target.
180
177
181
178
Testing support (` cross test ` ) is more complicated. It relies on [ QEMU]
182
179
emulation, so testing may fail due to QEMU bugs rather than bugs in your crate.
@@ -260,7 +257,7 @@ where libc was extracted.
260
257
### QEMU_STRACE (v0.1.9+)
261
258
262
259
You can set the QEMU_STRACE variable when you use ` cross run ` to get a backtrace
263
- of system calls from " foreign" (non x86_64) binaries.
260
+ of system calls from “ foreign” (non x86_64) binaries.
264
261
265
262
```
266
263
$ cargo new --bin hello && cd $_
@@ -276,14 +273,14 @@ $ QEMU_STRACE=1 cross run --target aarch64-unknown-linux-gnu
276
273
9 exit_group(0)
277
274
```
278
275
279
- ## Caveats / gotchas
276
+ ## Caveats
280
277
281
278
- path dependencies (in Cargo.toml) that point outside the Cargo project won't
282
279
work because ` cross ` use docker containers only mounts the Cargo project so
283
280
the container doesn't have access to the rest of the filesystem.
284
281
285
282
- ` cross ` will mount the Cargo project as READ ONLY. Thus, if any crate attempts
286
- to modify its " source" , the build will fail. Well behaved crates should only
283
+ to modify its “ source” , the build will fail. Well behaved crates should only
287
284
ever write to ` $OUT_DIR ` and never modify ` $CARGO_MANIFEST_DIR ` though.
288
285
289
286
## License
@@ -292,7 +289,7 @@ Licensed under either of
292
289
293
290
- Apache License, Version 2.0 ([ LICENSE-APACHE] ( LICENSE-APACHE ) or
294
291
http://www.apache.org/licenses/LICENSE-2.0 )
295
- - MIT license ([ LICENSE-MIT] ( LICENSE-MIT ) or http://opensource.org/licenses/MIT )
292
+ - MIT License ([ LICENSE-MIT] ( LICENSE-MIT ) or http://opensource.org/licenses/MIT )
296
293
297
294
at your option.
298
295
0 commit comments