fargo v0.1.0 Fargo is a prototype Fuchsia-specific wrapper around Cargo USAGE: fargo [FLAGS] [OPTIONS] [SUBCOMMAND] FLAGS: --debug-os Use debug user.bootfs and ssh keys -h, --help Prints help information -V, --version Prints version information -v, --verbose Print verbose output while performing commands OPTIONS: -N, --device-name <device-name> Name of device to target, needed if there are multiple devices visible on the network SUBCOMMANDS: autotest Auto build and test in Fuchsia device or emulator build Build binary targeting Fuchsia device or emulator build-tests Build tests for Fuchsia device or emulator cargo Run a cargo command for Fuchsia. Use -- to indicate that all following arguments should be passed to cargo. configure Run a configure script for the cross compilation environment help Prints this message or the help of the given subcommand(s) list-devices List visible Fuchsia devices pkg-config Run pkg-config for the cross compilation environment restart Stop all Fuchsia emulators and start a new one run Run binary on Fuchsia device or emulator ssh Open a shell on Fuchsia device or emulator start Start a Fuchsia emulator stop Stop all Fuchsia emulators test Run unit tests on Fuchsia device or emulator
fargo-test directory contains something one can use to test-drive.
Since at the moment fargo requires the FUCHSIA_ROOT environmental variable be set to the path to a Fuchsia release build, the first step is to build Fuchsia.
The Fuchsia Getting Started instruction are what you need. Since a release build is what fargo expects to find you‘ll want to pass --release to fset. The Rust components that fargo needs to cross compile are also not built by default, so you’ll have to select something other than the default modules.
If you are planning to use Qemu to run your Fuchsia Rust code, a good choice for modules is below, in env.sh form or underlying script as one prefers.
fset x86-64 --release --modules packages/gn/boot_headless,garnet/packages/zircon_rust
packages/gn/gen.py -m packages/gn/boot_headless,garnet/packages/zircon_rust --release
packages/gn/boot_headless does in this instance is prevent the user shell from being launched after boot. Since the user shell requires Mozart, and Mozart has a hard dependency on the Vulkan graphics and compute API, and Qemu cannot support Vulkan,
packages/gn/boot_headless is pretty much a requirement for Qemu.
If you want a quicker compile, limiting the modules to
packages/gn/garnet,garnet/packages/runtime_config,garnet/packages/zircon_rust will compile a lot fewer packages but still be usable with Fargo.
Once this build is complete, clone and build fargo.
git clone https://fuchsia.googlesource.com/fargo cd fargo cargo install
Fargo uses ssh to communicate between your host computer and either Qemu or a real device to copy build results and execute them. For Qemu there is a bit of tricky set up to do.
Finally, you need to be using nightly (as opposed to stable) and have the
x86_64-unknown-fuchsia target installed. If you installed rust with rustup you can install the target with:
rustup default nightly rustup target add x86_64-unknown-fuchsia
If you installed Rust some other way, you'll have to do some research about how to get the nightly build and
x86_64-unknown-fuchsia support into your installation.
Now to verify if fargo is working correctly, try starting a fuchsia machine and executing a test.
fargo start cd fargo/fargo-test fargo test
If all is well, you should see a successful test pass just as if you had ran cargo test on any other rust project.
Do note that fargo does not check the fuchsia target env var. Meaning
fargo start will start a fuchsia server using x86-64-release unless you pass it the --debug-os option, in which case it will use the debug build. So make sure you use a fuchsia target you built with the rust module enabled.
Additionally, if you are using qemu you need to enable networking, otherwise fargo won't be able to copy the binary onto then fuchsia machine to run the tests.
For problems getting the Fuchsia build to complete, the #fuchsia IRC channel on freenode is the best bet.
For fargo itself, that IRC channel can also work of one of the more Rust-aware folks happens to be paying attention. More reliable is the rust-fuchsia Google group.
Some crates are wrappers around libraries written in other languages. An example of one such crate is cairo-rs. Cargo has to know what libraries need to be linked to a binary using such a crate and where to find those libraries.
Cargo uses build.rs files to locate such libraries. This provides a challenge for Fargo, as it is unlikely that such build.rs files would know how to cross compile their libraries for Fuchsia.
Luckily, many of the crates of interest which have native dependencies use pkg-config as one of the ways to find native dependencies. Fargo provides functions to set up and use a Fuchsia-specific pkg-config directory.
fargo pkg-config is a wrapper around pkg-config that sets the environment so that only packages found in the Fuchsia-specific pkg-config directory are visible. This is useful to test if a particular package is already installed.
fargo configure is a wrapper around a package's automake configure script. It takes care of setting up environmental variables such that many automake based packages will properly cross-compile.
scripts/build_cairo_support.sh for an example of how to use these functions to build native support.
The goal is to transition fargo to using something like an SDK instead.