hhuTOS

hhuTOS = hhu Teaching Operating System.

This file describes all commands needed for building, running, and debugging hhuTOS.

Last update: 07.04.2025.

Preparation

Rust Compiler

For building hhuTOS, a rust nightly toolchain is needed. To install rust use rustup. The toolchain nightly-2025-03-10 is confirmed to work with hhuTOS. We also need cargo-make.

rustup toolchain install nightly-2025-03-10
rustup override set nightly-2025-03-10
cargo install --no-default-features cargo-make

Furthermore, we need to install the build-essential tools, as well as the Netwide Assembler (nasm) for building hhuTOS. We use GRUB as a bootloader and need xorriso for building a bootable ISO image. Last but not least, QEMU is recommended to run hhuTOS in a virtual machine and GDB for debugging.

On Ubuntu 24.04 you can install all the above with a single apt command:

sudo apt install build-essential nasm grub-pc xorriso qemu-system-x86 gdb

On macOS, we can install most of the tools via brew:

brew install x86_64-elf-binutils nasm xorriso qemu x86_64-elf-gdb

Unfortunately the correct GRUB version cannot be installed via brew and needs to be compiled manually:

brew install x86_64-elf-gcc
git clone git://git.savannah.gnu.org/grub.git && cd grub
./bootstrap
./autogen.sh
./configure --disable-werror TARGET_CC=x86_64-elf-gcc TARGET_OBJCOPY=x86_64-elf-objcopy TARGET_STRIP=x86_64-elf-strip TARGET_NM=x86_64-elf-nm TARGET_RANLIB=x86_64-elf-ranlib --target=x86_64-elf --prefix=$HOME/opt/grub
make -j8
make install

As a last step, we need to add GRUB to our PATH variable:

export PATH=$PATH:~/opt/grub/bin

Compiling

For a full build run:

cargo make

Running

To run the image, use the following command, which will automatically build hhuTOS and run it in QEMU:

cargo make qemu

Debugging

hhuTOS contains configuration files for VSCode. To use VSCode for Debugging, just install the Rust and C++ extensions (Memory Viewer is also recommended) and the debug target qemu-gdb should appear in the Run and Debug tab in VSCode. Just click the play button to start a debugging session.

It is also possible to debug hhuTOS via GDB in a terminal. To start QEMU with GDB-server run the following command in a terminal (this should open qemu but not boot hhuTOS yet):

cargo make qemu-gdb

Open another terminal and start a GDB debugging session:

cargo make gdb

For more convenient debugging, we recommend starting GDB with the integrated Terminal UI (TUI):

cargo make gdbt