Releases Contribute Contact Support Main Site seL4 on GitHub

Rust: How to Use

Using these crates requires a compatible Rust toolchain. See the project’s rust-toolchain.toml for the particular toolchain version that is used for testing. Note that these crates use nightly-only features, so, if you are using a stable toolchain, you must set the environment variable RUSTC_BOOTSTRAP=1.

These crates are not yet hosted on crates.io. Use them either as Git or path Cargo dependencies.

Environment Variables

Some of these crates depend, at build time, on external components and configuration. In all cases, information for locating these dependencies is passed to the dependant crates via environment variables which are interpreted by build.rs scripts. Here is a list of environment variables and the crates which use them:

  • sel4-config and sel4-sys, whose dependants include sel4, sel4-root-task, sel4-microkit, and many more, use $SEL4_INCLUDE_DIRS (defaulting to $SEL4_PREFIX/libsel4/include if $SEL4_PREFIX is set) which must contain a colon-separated list of include paths for the libsel4 headers. See the the sel4 crate’s rustdoc for more information.
  • sel4-platform-info, whose dependants include sel4-kernel-loader, uses $SEL4_PLATFORM_INFO (defaulting to $SEL4_PREFIX/support/platform_gen.yaml if $SEL4_PREFIX is set) which must contain the path of the platform_gen.yaml file from the seL4 kernel build system.
  • sel4-kernel-loader uses $SEL4_KERNEL (defaulting to $SEL4_PREFIX/bin/kernel.elf if $SEL4_PREFIX is set) which must contain the path of the seL4 kernel (as an ELF executable).

Language Runtime Crates

Two language runtime crates, one for root tasks and another for Microkit protection domains, provide runtime elements such as an entry point, thread-local storage, panic handling, a stack, and a heap. See their API docs (linked below) for information on how to use them.

  • sel4-root-task: A runtime for root tasks that supports thread-local storage and unwinding, and provides a global allocator. rustdoc
  • sel4-microkit: A runtime for seL4 Microkit protection domains, including an implementation of libmicrokit and abstractions for IPC. rustdoc

Choosing a --target argument for rustc

rustc’s baremetal builtin target triples (e.g. aarch64-unknown-none) will suffice, but we provide a collection of custom target specifications that are tuned specifically for use in seL4 userspace, and that cover a range of language runtime configurations. See the source directory that contains them for more information.

Demos

These demos provide concrete examples of how to integrate these crates into a seL4-based project: