rust-raspberrypi-OS-tutorials is a step-by-step tutorial for developing an operating system in Rust, aimed at Raspberry Pi (Raspberry Pi 3 / 4). Each chapter (tutorial) is a bootable, standalone kernel version, and subsequent chapters expand on the functionality of the previous ones. The author breaks down common OS tasks from the basics of “writing characters to the serial port” to “setting up virtual memory and handling exceptions,” making it suitable for enthusiasts with no background to those with some embedded/system knowledge to self-learn.
Installation and Quick Start (Practical Steps) Below is a commonly used, less error-prone process. Assuming you are using Linux, macOS can also follow the tutorial but with slight differences.
- 1. Environment Preparation (Most Reliable Method)
- • Install Docker (simple and convenient, the author also encourages using Docker).
- • Add the current user to the docker group (Linux): sudo usermod -aG docker $USER then log back in.
- • If rustup is not installed: curl –proto ‘=https’ –tlsv1.2 -sSf https://sh.rustup.rs | sh
- • Activate the environment: source $HOME/.cargo/env
- • Install auxiliary tools: cargo install cargo-binutils rustfilt
- • git clone https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials
- • cd rust-raspberrypi-OS-tutorials
- • Carefully read the tl;dr and diff in each tutorial’s README. Start with tutorial 1, which runs fastest on QEMU.
- • It is recommended to use VSCode + Rust Analyzer for editing, which facilitates type reading and navigation.
- • Prepare an SD card and place the chainloader/image according to the instructions in Chapter 5.
- • Connect the USB-serial (e.g., CP2102 chip) to the Raspberry Pi’s GND, GPIO14/15 (TX/RX), and open the serial tool to view the output.
- • Starting from Chapter 6, you can more conveniently dynamically load the kernel via UART without having to manually change files each time.
Quick Overview Table (Key Commands/Tools)
| Item | Recommended Practice |
| Rust Installation | rustup (curl script) |
| Essential Cargo Tools | cargo-binutils, rustfilt |
| Simulator | QEMU (quick verification) |
| Real Machine Debugging | USB serial (CP2102 recommended), GDB + OpenOCD (advanced) |
| One-click Environment | Docker (repository comes with container) |
| Editor | VSCode + Rust Analyzer |
User Experience & Learning Path Recommendations
- • Recommended order: tutorial1 → tutorial2 → … take it step by step, do not skip. Each chapter explains why things are done this way, and the diff helps you see the changes.
- • Development rhythm: first run on QEMU, then on Raspberry Pi. QEMU can quickly debug logic, while real hardware gives you a “real feel”.
- • Documentation and Code: The author is very responsible, with many chapters containing detailed text, and each tutorial can generate code documentation with make doc, making it easy to read internal implementations.
Advantages (Why Strongly Recommended)
- • Based on Rust: fewer memory errors, modern language, strong type system.
- • Clear step-by-step tutorials: suitable for those exploring OS from scratch.
- • Supports both real machines and virtual machines: complete development experience.
- • Docker reduces environmental costs: beginners hardly need to struggle with toolchains.
- • Active community and translations (with some Chinese README segments), open-source, and extensible.
Disadvantages (Practical Reminders)
- • Rust learning curve: If you have no Rust experience, you need to learn the language basics first (though the author provides many tips in the tutorial).
- • ARM architecture complexity: low-level details can still be confusing, especially MMU and exceptions.
- • Some chapters’ documentation is still being improved: not every chapter has lengthy detailed explanations, requiring understanding through reading code and diffs.
- • macOS users may encounter some minor issues related to Docker/ruby (the author has noted this, but patience is required).
Conclusion — Who is it Suitable For? If you are someone who wants to learn operating system principles while also wanting to run code on real hardware, this tutorial is almost tailor-made for you. It lowers the barrier for traditional bare-metal development significantly: Rust brings safety, Docker saves you from dependency troubles, and the chapter-based tutorials allow learning in chunks rather than having to swallow a thick book all at once. As for the drawbacks, you will still need to spend time grappling with Rust and ARM details, but this is almost an unavoidable “growth cost.”
Project Address: https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials