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.
-
The
rust-src
component, which you can install withrustup component add rust-src
. -
Rust and Cargo.
$ cargo install cargo-xbuild
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"
- The
memcpy
flag defines whether themem
feature of thecompiler_builtins
crate should be activated. Turning this flag off allows to specify own versions of thememcpy
,memset
etc. functions. - The
sysroot_path
flag specifies the directory where the sysroot should be placed.
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/libcore`
$ 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:
- 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
$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 version
- Install git:
pkg install git
- Clone a repository of your choice:
git clone https://github.com/phil-opp/blog_os.git
- 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 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:
- 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_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
- 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.
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.