cargo-xbuild
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.
Alternative: The build-std feature of cargo
Cargo 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:
- the normal
cargo {check, build, run, test}commands can be used - no external tool must be installed
- less bugs and breakage because it is always up to date with rustc/cargo
- faster compilation since the compiler can build the sysroot concurrently to the project crates
- it might be stablized one day
So it is strongly recommended to try the build-std feature of cargo instead of using this crate.
Dependencies
-
The
rust-srccomponent, which you can install withrustup component add rust-src. -
Rust and Cargo.
Installation of 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.
Usage
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.
Configuration
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
- The
memcpyflag defines whether thememfeature of thecompiler_builtinscrate should be activated. Turning this flag off allows to specify own versions of thememcpy,memsetetc. functions. - The
sysroot_pathflag specifies the directory where the sysroot should be placed. - The
panic_immediate_abortflag specifies whether thepanic_immediate_abortfeature the ofcorecrate should be defined.
Environment Variables
In addition to the above configuration keys, cargo-xbuild can be also configured through the following environment variables:
- The
XBUILD_SYSROOT_PATHvariable can be used to specify wherecargo-xbuildshould place the generated sysroot. This variables takes precendence over thepackage.metadata.cargo-xbuild.sysroot_pathconfiguration key. - When the
XBUILD_KEEP_TEMPvariable is set, the temporary directory used for compiling the sysroot is not deleted. This is useful for debugging. For convenience,cargo-xbuildalso prints the directory name when the environment variable is set.
Dev channel
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
Using on Android
It's possible to run cargo-xbuild on your Android phone:
Install Termux and Nightly Rustc
- Install termux
- Install fish shell and set as default (optional):
pkg install fish; chsh -s fish; fish - Install some basic tools:
pkg install wget tar - Add the community repository by its-pointless:
wget https://its-pointless.github.io/setup-pointless-repo.sh; bash setup-pointless-repo.sh - Install rust nightly:
pkg install rustc cargo rustc-nightly - Prepend the nightly rustc path to your
$PATHin order to use nightly (fish syntax):set -U fish_user_paths $PREFIX/opt/rust-nightly/bin/ $fish_user_paths rustc --versionshould now return a nightly version
(Optional) Install Git and Clone your Repository
- Install git:
pkg install git - Clone a repository of your choice:
git clone https://github.com/phil-opp/blog_os.git
Install Xbuild
- Install cargo-xbuild:
cargo install cargo-xbuild - Add the cargo bin directory to your
$PATH(fish syntax):set -U fish_user_paths ~/.cargo/bin/ $fish_user_paths - Now
cargo xbuildshould 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.
Providing the Rust Source Code
The Rust source code corresponding to our installed nightly is available in the its-pointless repository:
- Download it:
wget https://github.com/its-pointless/its-pointless.github.io/raw/master/rust-src-nightly.tar.xz - Extract it:
tar xf rust-src-nightly.tar.xz - Set the
XARGO_RUST_SRCenvironment 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!
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
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.
11 Dec 15, 2022
13 Jun 21, 2023
4 Nov 30, 2022
8 Sep 16, 2022
16 Sep 21, 2022
14 Jan 7, 2023
11 Jul 27, 2022
69 Feb 1, 2023
13 May 18, 2023
36 Jul 16, 2024
3 May 3, 2022
3 Oct 30, 2022
4 Aug 3, 2022
92 Jan 4, 2023
839 Jan 6, 2023
3 Jul 12, 2023
1 Oct 19, 2021
128 Jan 4, 2023
5 Sep 8, 2023