|author||Rob Tsuk <firstname.lastname@example.org>||Mon Oct 14 12:06:53 2019 -0700|
|committer||Rob Tsuk <email@example.com>||Mon Oct 21 12:33:09 2019 -0700|
Remove the Normal run mode Since Fuchsia will no longer execute files from /tmp, this mode is no longer needed. Instead the default mode is to run by creating a package and letting fx serve install/update it. To make this change more ergonomic, fargo will provide a default sandbox file that should work for binaries that don't require any special permissions. Also fixed a bug where the wrong flag for killall is being passed on Linux. Also updated the README. Change-Id: Iebd3794825edd01f1ecde05e46c8fa6349b7eddf
fargo 0.2.0 Fargo is a prototype Fuchsia-specific wrapper around Cargo. USAGE: fargo [FLAGS] [OPTIONS] <SUBCOMMAND> FLAGS: --disable-cross-env Disable the setting of CC, AR and such environmental variables -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 --manifest-path <manifest-path> Path to Cargo.toml SUBCOMMANDS: autotest Auto build and test in Fuchsia device or emulator build Build binary targeting Fuchsia device or emulator build-rustc Build rustc targeting Fuchsia cargo Run a cargo command for Fuchsia. Use -- to indicate that all following arguments should be passed to cargo. check Check binary targeting Fuchsia device or emulator configure Run a configure script for the cross compilation environment doc Build a package's documentation enable-networking Enable networking for a running emulator fmt Run cargo fmt using the Fuchsia toolchain help Prints this message or the help of the given subcommand(s) list-devices List visible Fuchsia devices make-package Make a Fuchsia package from an unstripped binary 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 run-on-target Act as as custom runner for Cargo targeting a Fuchsia device 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 write-config Write a .cargo/config file to allow cargo to operate correctly for Fuchsia
fargo-test directory contains something one can use to test-drive.
Since at the moment fargo requires the FUCHSIA_DIR environmental variable be set to the path to a Fuchsia source tree containing a Fuchsia build, the first step is to build Fuchsia.
The Fuchsia Getting Started instruction are what you need. Make sure that
fx serve is running pointed at this Fuchsia build.
Once this build is complete, clone and build fargo. For this you will need a working host Rust installation, most easily installed with rustup.
git clone https://fuchsia.googlesource.com/fargo cd fargo cargo install --force --path .
Fargo uses the values set by
./scripts/fx set to know what build directory to use.
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.
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
Note that fargo start now depends on an environment using fx set. If that isn‘t the way you start Fuchsia emulators, use fargo enable-networking after you’ve started the emulator.
If all is well, you should see a successful test pass just as if you had ran cargo test on any other rust project.
Additionally, if you are using qemu you need to enable networking, otherwise fargo won't be able to use
fx shell to invoke the test binary.
Sometimes you want to pass parameters through fargo and cargo and on to somethinglike rustc. To make this easier fargo will convert a “++” parameter to “--” when invoking cargo. For example, the following command:
fargo cargo rustc -- ++ --emit=llvm-ir
will get cargo to cause rustc to emil llvm ir files.
fargo run has the options,
--run-with-sessionctl, that will use
tiles_ctl add to launch the Rust binary. Use this option when running if your binaries wants to provide a view provider service
fargo --write-config will create a .cargo directory with a config file that tells cargo how to compile artifacts for Fuchsia and how to run them. Creating such a config file might allow some tools to work that otherwise would not be able to compile artifacts for Fuchsia.
The config file created will be for the architecture and debug/release options that are passed to fargo with the
write-config command. If you wish to switch to a different architecture or build, re-run
For problems getting the Fuchsia build to complete, the getting started page on fuchsia.dev is the best place to start looking for help.
For fargo itself, the best place for help is the rust-fuchsia Google group.
By default fargo will use the copies of cargo and rustc provided in
$FUCHSIA_DIR/buildtools. To change this behavior, set the environmental variables
FARGO_RUSTC before running fargo.
If you need to be using a different version of nightly for some reason, you'll need the
x86_64-fuchsia target. If you installed rust with rustup you can install the target with:
rustup default nightly rustup target add x86_64-fuchsia
CARGO_TARGET_[X86_64|AARCH64]_UNKNOWN_FUCHSIA_RUNNER - set to the fargo binary to run remotely on simulator or device.
CARGO_TARGET_[X86_64|AARCH64]_UNKNOWN_FUCHSIA_RUSTFLAGS - set to provide linker flags
CARGO_TARGET_[X86_64|AARCH64]_UNKNOWN_FUCHSIA_LINKER - set to specify the linker
RUSTC - set to cause cargo to use the copy of rustc in buildtools
RUSTDOC - set to cause cargo to use the copy of rustdoc in buildtools
FUCHSIA_SHARED_ROOT - set to the directory containing shared libraries for the current selected architecture. Useful for build scripts.
ZIRCON_BUILD_ROOT - set to the zircon build directory for the current architecture. Useful for build scripts.
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.
fargo sets the following environmental variables before invoking configure:
CC, CXX, RANLIB, LD, AR, CFLAGS, CXXFLAGS, CPPFLAGS LDFLAGS, PKG_CONFIG_PATH, PKG_CONFIG_LIBDIR, PKG_CONFIG_ALL_STATIC
--disable-cross-env option will prevent these environmental variables from being set when invoking cargo. This is useful when the components being built by C or C++ are intended for the host, not the target.
The goal is to transition fargo to using something like an SDK instead.