Cargo-xbuild is a wrapper for cargo build
, which cross compiles the sysroot crates core
, compiler_builtins
, and alloc
for custom targets. It is a simplified fork of xargo
, which is in maintainance mode.
build-std
feature of cargoCargo now has its own feature for cross compiling the sysroot: build-std
. You can use it by passing -Z build-std=core,alloc
to cargo build
. Alternatively, you can specify the following in a .cargo/config.toml
file:
[unstable]
build-std = ["core", "compiler_builtins", "alloc"]
The above requires at least Rust nightly 2020–07–15. With the above config in place, the normal cargo build
command will now automatically cross-compile the specified sysroot crates.
The compiler may emit references to memset
, memcpy
, etc which are usually provided by the platform's libc but luckily compiler_builtins
has a mem
feature that will provide implementations of those functions. To enable that feature we can use the unstable cargo flag -Z build-std-features=compiler-builtins-mem
or specify the following in a config.toml
:
[unstable]
build-std = ["core", "compiler_builtins", "alloc"]
+build-std-features = ["compiler-builtins-mem"]
Note that using the compiler-builtins-mem
requires at least Rust nightly 2020-09-30. For older versions you need to add a dependency on the rlibc
crate to provide implementations of memset
, memcpy
, etc, which the compiler expects. Note that you need to add an extern crate rlibc
statement in order for this to work (even in the 2018 edition of Rust). This is required to get cargo to link the otherwise unused crate.
Compared to cargo-xbuild
, there are many advantages of using cargo
's own feature:
cargo {check, build, run, test}
commands can be usedSo it is strongly recommended to try the build-std
feature of cargo instead of using this crate.
The rust-src
component, which you can install with rustup component add rust-src
.
Rust and Cargo.
cargo-xbuild
In case you decide to use cargo-xbuild
instead of cargo's build-std
feature for some reason, you can install this crate through:
$ cargo install cargo-xbuild
Note: The latest version of cargo-xbuild
supports all nightlies after 2020-07-30. If you are on an older nightly, you need to install version 0.5.35: cargo install cargo-xbuild --version 0.5.35
.
Just use cargo xbuild
instead of cargo build
when cross-compiling for a custom target.
cargo xbuild --target your-target-name.json
Instead of the "can't find crate for core
" error you would get with a plain cargo build
, this crate cross-compiles the core
, compiler_builtins
, and alloc
crates and then invokes cargo build
with a modified sysroot. The sysroot is compiled in the target
directory of your crate.
All additional arguments (e.g. --release
or --verbose
) are forwarded to cargo build
.
To configure cargo-xbuild
create a package.metadata.cargo-xbuild
table in your Cargo.toml
. The following options are available:
[package.metadata.cargo-xbuild]
memcpy = true
sysroot_path = "target/sysroot"
panic_immediate_abort = false
memcpy
flag defines whether the mem
feature of the compiler_builtins
crate should be activated. Turning this flag off allows to specify own versions of the memcpy
, memset
etc. functions.sysroot_path
flag specifies the directory where the sysroot should be placed.panic_immediate_abort
flag specifies whether the panic_immediate_abort
feature the of core
crate should be defined.In addition to the above configuration keys, cargo-xbuild
can be also configured through the following environment variables:
XBUILD_SYSROOT_PATH
variable can be used to specify where cargo-xbuild
should place the generated sysroot. This variables takes precendence over the package.metadata.cargo-xbuild.sysroot_path
configuration key.XBUILD_KEEP_TEMP
variable is set, the temporary directory used for compiling the sysroot is not deleted. This is useful for debugging. For convenience, cargo-xbuild
also prints the directory name when the environment variable is set.If you want to use a local Rust source instead of rust-src
rustup component, you can set the XARGO_RUST_SRC
environment variable.
# The source of the `core` crate must be in `$XARGO_RUST_SRC/core`
$ export XARGO_RUST_SRC=/path/to/rust/src
$ cargo xbuild --target msp430-none-elf.json
It's possible to run cargo-xbuild on your Android phone:
pkg install fish; chsh -s fish; fish
pkg install wget tar
wget https://its-pointless.github.io/setup-pointless-repo.sh; bash setup-pointless-repo.sh
pkg install rustc cargo rustc-nightly
$PATH
in order to use nightly (fish syntax): set -U fish_user_paths $PREFIX/opt/rust-nightly/bin/ $fish_user_paths
rustc --version
should now return a nightly versionpkg install git
git clone https://github.com/phil-opp/blog_os.git
cargo install cargo-xbuild
$PATH
(fish syntax): set -U fish_user_paths ~/.cargo/bin/ $fish_user_paths
cargo xbuild
should be available.It does not work yet because it needs access to the rust source code. By default it tries to use rustup for this, but we have no rustup support so we need a different way.
The Rust source code corresponding to our installed nightly is available in the its-pointless
repository:
wget https://github.com/its-pointless/its-pointless.github.io/raw/master/rust-src-nightly.tar.xz
tar xf rust-src-nightly.tar.xz
XARGO_RUST_SRC
environment variable to tell cargo-xbuild the source path (fish syntax): set -Ux XARGO_RUST_SRC ~/rust-src-nightly/rust-src/lib/rustlib/src/rust/src
Now cargo-xbuild should no longer complain about a missing rust-src
component. However it will throw an I/O error after building the sysroot. The problem is that the downloaded Rust source code has a different structure than the source provided by rustup. We can fix this by adding a symbolic link:
ln -s ~/../usr/opt/rust-nightly/bin ~/../usr/opt/rust-nightly/lib/rustlib/aarch64-linux-android/bin
Now cargo xbuild --target your-target.json
should work!
Licensed under either of
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.