Repository files navigation

An OpenEmebdded/Yocto layer providing pre-built toolchains for theRust programming language.

• meta-rust-bin
  • Basic Example
  • Features
    • Use with Yocto Release 4.0 (kirkstone) and Above
    • Use with Yocto Release 3.4 (honister) and Above
  • Advanced Features
    • Specifying Cargo Features
    • Using Components Individually
  • Pre-built vs. Compiled
  • Adding Support for New Versions
  • Copyright

A basic class for cargo-based executables is provided. The following is asimple recipe called gpio_utils.bb that builds thegpio-utilscrate from branch master.

SUMMARY="GPIO Utilities"HOMEPAGE="git://github.com/rust-embedded/gpio-utils"LICENSE="MIT"inheritcargo_bin# Enable network for the compile task allowing cargo to download dependenciesdo_compile[network]="1"SRC_URI="git://github.com/rust-embedded/gpio-utils.git;protocol=https;branch=master"SRCREV="02b0658cd7e13e46f6b1a5de3fd9655711749759"S="${WORKDIR}/git"LIC_FILES_CHKSUM="file://LICENSE-MIT;md5=935a9b2a57ae70704d8125b9c0e39059"

As you can see, there is almost no overhead introduced from thecargo_bin classbeyond simply inheriting it. Thecargo_bin class adds the appropriate Rustdependencies as well as default compile and install steps.

Warning
In previous versions ofmeta-rust-bin the classcargo was used insteadofcargo_bin. Follow thisguide if youare updating yourmeta-rust-bin layer from an old version.

Currently supported:

• Current stable rust release (usually shortly after release) and severalprevious releases, seethe versioned recipes.
• x86 (32 and 64-bit), ARM (32 and 64-bit) build systems.
• All Linux architectures that Rust itself supports (Multiple flavors of:x86, ARM, PPC, and MIPS)
• Statically-linked libstd, dynamically-linked system libraries (libc, libm,etc)

Future:

• Building and installingdev andstaticdev packages (i.e. allow buildand install of static and dynamic library builds).
• Debug builds with separated debug info to allow gdbserver usage.
• Running Rust/Cargo on target.
• Vendoring of Cargo dependencies (to better play with the Yocto offlinebuild model).
• Use of a shared libstd across all Rust packages on a target system(provides space savings).
• Total static linking using MUSL.

From Yocto version 4.0 network access from tasks is disabled by default onkernels which support this feature (on most recent distros such as CentOS 8 andDebian 11 onwards). The taskdo_compile need to access the network because itdownloads dependencies, so add the following line to the recipe:

do_compile[network]="1"

To avoid conflicts with the offical Rust layer of Yocto, the classcargo ofmeta-rust-bin was renamed tocargo_bin.

If you are updatingmeta-rust-bin from an old version please make sure toupdate the inherited class of your recipe tocargo_bin.

After the update it's safe to remove the previously usedBBMASK:

BBMASK="poky/meta/recipes-devtools/rust"

Because Yocto is primarily used for embedded development, it is likely thatprojects will have differing features based on whether the crate is run on thehardware or in development on a PC. Cargo features can be easily specified byadding a space-separated list ofCARGO_FEATURES to the recipe:

CARGO_FEATURES="feature1 feature2"

Although thecargo class is the easiest way to use this layer, the componentsit provides may also be used directly. To add the Rust compiler plus target andhost standard libraries to the environment, depend on or installrust-bin. Tomanually installcargo depend on or installcargo-bin.

Note that while there is nothing explicitly preventing the installation of Ruston the target, it hasn't been tested and is likely not to work. Pull requestsare welcome!

This layer exists as a tradeoff against other options, e.g. themeta-rust project. Both exist to satisfydifferent requirements.

Because this layer uses the upstream compiled versions of Rust and Cargo, itwill never be able to support architectures or options not supported by theRust team itself.

Also, because this layer uses pre-built Rust standard libraries, it is possiblethat the standard libraries provided with this layer will be less efficientthan code produced by a custom-compiled standard library.

However, using pre-built tools has advantages:

• Updating the layer to a new version of Rust is as easy as updatingchecksums and file names, so new versions of Rust are available quickly.
• In almost all modern systems, it is faster to download the binaries than itis to download source and build the Rust toolchain from scratch.
• Compatability across multiple versions of Yocto is maximized since onlybasic, stable recipe features are used.
• Trivial support for all architectures supported by upstream Rust.

When a new version of rust is released, adding support for this new version canbe done by runningbuild-new-version.sh as follows:

./build-new-version.sh <version>

This will create two new recipes:

• recipes-devtools/rust/rust-bin-.bb
• recipes-devtools/rust/cargo-bin-.bb

Where the cargo version generated is the one packaged with the associatedrelease of rust itself (using the published channel data consumed by othertools like rustup).

For latest nightly version:

./build-new-version.sh nightly

For specified nightly version:

./build-new-version.sh nightly 2019-07-08

Copyright (c) 2016, the meta-rust-bin authors.Licensed under the Apache License, Version 2.0 <LICENSE-APACHE orhttp://www.apache.org/license/LICENSE-2.0> or the MIT license<LICENSE-MIT or http://opensource.org/licenses/MIT>, at youroption.  This file may not be copied, modified, or distributedexcept according to those terms.