Setup
This training session is presented as a linear series of patches to https://github.com/coliasgroup/seL4-summit-2024-rust-training-code, starting at commit 46869faeee42, and ending with commit f0e140493945.
Each patch, or step, as we shall call them, is an instructive modification to a code example.
You are encouraged (but by no means required) to attempt those marked as exercises in this text on your own.
Note that while most step patches include tests, the reader is not expected to write tests for exercises themselves.
Clone the repository and checkout the starting commit:
git clone https://github.com/coliasgroup/seL4-summit-2024-rust-training-code
cd seL4-summit-2024-rust-training-code
git checkout 46869faeee42
Observe the steps ahead:
git log 46869faeee42..f0e140493945
Each step header contains two icons. Clicking the clipboard copies the commit hash corresponding to the step to the clipboard. The GitHub icon is a link to the commit on GitHub.
Use any Git workflow that works for you. For example, you could cherry-pick the steps that are not marked as exercises after examining and understanding them, and then attempt the exercises on your own, using those step commits as hints when necessary.
Docker
We will work inside of a Docker container built with docker/Dockerfile. This Dockerfile installs some build-time dependencies, and then builds seL4, seL4 Microkit, and some additional programs and tools.
Build the image:
make -C docker build
Run a container in the background:
make -C docker run
Start a shell inside the container:
make -C docker exec
The rest of this text assumes that you are in a shell inside the container.
Two Workspaces
To simplify our Cargo invocations, this repository's Rust code has been divided between two distinct workspaces: workspaces/root-task and workspaces/microkit.
Both are subject to the top-level .cargo/config.toml, whereas workspaces/root-task/.cargo/config.toml and workspaces/microkit/.cargo/config.toml each apply to only one.
These workspace-specific config.toml files demonstrate all that is required to configure the crates in the rust-sel4 project:
- An environment variable pointing at
libsel4(which includes the kernel configuration). See the relevant crate docs for information on this environment variable. - A reference to a custom rustc target specification (the location of the target specification is given at .cargo/config.toml:8, which refers to target-specs).
VSCode + Dev Containers
If you want help from rust-analyzer, the Rust Language Server, you can use VSCode with the Dev Containers extension. This will enable you to run VSCode inside of the container you just built, which contains the seL4 build artifacts that rust-analyzer will require to analyzer your code.
This repository provides a separate Dev Container configuration for each workspace:
To work in a particular workspace, open this repository in VSCode, run > Dev Containers: Reopen in Container, and select the corresponding configuration.
You should now be able to use the rust-analyzer VSCode extension normally for the code in the selected workspace.
Rustdoc
Rustdoc for the rust-sel4 project is hosted here:
https://sel4.github.io/rust-sel4/
However, for the sake of consistency, rustdoc for the particular configurations studied in this text are hosted here too. There is one set of rustdoc for each of the two workspace configurations mentioned in Two Workspaces. Rustdoc does not generate an index page, but you can navigate across crates within a workspace configuration using the sidebar present on top-level rustdoc page for any module.