Theseus OS

<br>

Theseus is a new OS written from scratch in Rust to experiment with novel OS structure, better state management, and how to leverage intralingual design principles to shift OS responsibilities like resource management into the compiler.

For more info, check out Theseus's documentation or our published academic papers, which describe Theseus's design and implementation.

Theseus is under active development, and although it is not yet mature, we envision that Theseus will be useful in high-end embedded systems or edge datacenter environments. We are continually working to improve the OS, including its fault recovery abilities for higher system availability without redundancy, as well as easier and more arbitrary live evolution and runtime flexibility.

Quick start

On Linux (Debian-like distros), do the following:

1. Obtain the Theseus repository (with all submodules):

   git clone --recurse-submodules --depth 1 https://github.com/theseus-os/Theseus.git
   

2. Install Rust:

   curl https://sh.rustup.rs -sSf | sh
   

3. Install dependencies:

   sudo apt-get install make gcc nasm pkg-config grub-pc-bin mtools xorriso qemu qemu-kvm wget
   

4. Build and run (in QEMU):

   cd Theseus
   make run
   

   To exit QEMU, press <kbd>Ctrl</kbd> + <kbd>A</kbd>, then <kbd>X</kbd>.

See below for more detailed instructions.

Building and Running Theseus

Note: when you first check out the project, be sure to get all the submodule repositories too:

git submodule update --init --recursive

Currently, we support building Theseus on the following platforms:

• Linux, 64-bit Debian-based distributions like Ubuntu, tested on Ubuntu 16.04, 18.04, 20.04.
  • Arch Linux and Fedora have also been reported to work correctly.
• Windows, using the Windows Subsystem for Linux (WSL), tested on the Ubuntu version of WSL and WSL2.
• MacOS, tested on versions High Sierra (v10.13), Catalina (v10.15), and Ventura (v13.5).
• Docker, atop any host OS that can run a Docker container.

Setting up the build environment

First, install Rust by following the setup instructions here. On Linux, just run:

curl https://sh.rustup.rs -sSf | sh

Building on Linux or WSL (Windows Subsystem for Linux)

Install the following dependencies using your package manager:

sudo apt-get install make gcc nasm pkg-config grub-pc-bin mtools xorriso qemu qemu-kvm wget

• Or:

  # Arch Linux
  sudo pacman -S make gcc nasm pkg-config grub mtools xorriso qemu wget
  
  # Fedora
  sudo dnf install make gcc nasm pkg-config grub2 mtools xorriso qemu wget
  

If you're on WSL, also do the following steps:

• Install an X Server for Windows; we suggest using Xming or VcXsvr.

  • You'll likely need to invoke those X servers with the -ac argument (or use the GUI to disable access control).

• Setup an X display as follows:

  • on original WSL (version 1), run:

    export DISPLAY=:0
    

  • on WSL2 (version 2), run:

    export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0
    

  You'll need to do this each time you open up a new WSL terminal, so it's best to add it to the end of your .bashrc or .profile file in your $HOME directory.

• If you get an error like Could not initialize SDL (No available video device) ... or any type of GTK or video device error, then make sure that your X Server is running and that you have set the DISPLAY environment variable above.

• NOTE: WSL and WSL2 do not currently support using KVM.

Building on MacOS

• Install HomeBrew, then run the MacOS build setup script:

  sh ./scripts/mac_os_build_setup.sh
  

  If things go wrong, remove the following build directories and try to run the script again.

  rm -rf /tmp/theseus_tools_src
  

• NOTE: on MacOS, you need to run gmake instead of make for build commands (or you can simply create a shell alias).

  • This is because HomeBrew installs its binaries in a way that doesn't conflict with built-in versions of system utilities.

• (This is typically not necessary): if you're building Theseus on older Apple Silicon (M1 chips), you may need to use bash with x86 emulation:

  arch -x86_64 bash   # or another shell of your choice
  

  and possibly adjust your system PATH if both x86 and ARM homebrew binaries are installed:

  export PATH=/usr/local/Homebrew/bin:$PATH
  

Building using Docker

Note: building and running Theseus within a Docker container may be slower than on a native host OS.

1. Ensure docker scripts are executable:

   chmod +x docker/*.sh
   

2. (Skip if docker is already installed.) Install Docker Engine. We provide a convenience script for this on Ubuntu:

   ./docker/install_docker_ubuntu.sh
   

   • After docker installs, enable your user account to run docker without root privileges:
     sudo groupadd docker; sudo usermod -aG docker $USER
     Then, log out and log back in (or restart your computer) for the user/group changes to take effect.

3. Build the docker image:

   ./docker/build_docker.sh
   

   This does not build Theseus, but rather only creates a docker image that contains all the necessary dependencies to build and run Theseus.

4. Run the new docker image locally as a container:

   ./docker/run_docker.sh
   

   Now you can run make run or other Theseus-specific build/run commands from within the docker container's shell.

Notes on Docker usage:

• The docker-based workflow should only require you to re-run the run_docker.sh script multiple times when re-building or running Theseus after modifying its code. You shouldn't need to re-run build_docker.sh multiple times, though it won't hurt.
• KVM doesn't currently work in docker. To run Theseus in QEMU using KVM, you can build Theseus within docker, exit the container (via <kbd>Ctrl</kbd> + <kbd>D</kbd>), and then run make orun host=yes` on your host machine.

Building and Running

Build the default Theseus OS image and run it in QEMU:

make run

Or, build a full Theseus OS image with all features and crates enabled:

make full   ## or `make all`

Run make help to see other make targets and the various command-line options.

Using the Limine bootloader instead of GRUB

To use Limine instead of GRUB, clone pre-built limine and pass bootloader=limine to make:

git clone https://github.com/limine-bootloader/limine.git limine-prebuilt
git -C limine-prebuilt reset --hard 3f6a330
make run bootloader=limine

Feel free to try newer versions, however they may not work.

Targeting ARMv8 (aarch64)

Support for Theseus on aarch64 is an ongoing effort, but most of the core subsystems are complete.

To build and run Theseus on aarch64, first install the required dependencies:

• On Debian-like Linux (Ubuntu, etc):

  sudo apt-get install qemu-system-arm gcc-aarch64-linux-gnu
  

• On Arch Linux:

  sudo pacman -S aarch64-linux-gnu-gcc qemu-system-aarch64
  

• On macOS, the mac_os_build_setup script should have already installed this for you, but if not:

  brew install aarch64-elf-gcc aarch64-elf-binutils
  
  

Then, build Theseus and run it in QEMU:

make ARCH=aarch64 run

Doing a "full" build of all Theseus crates isn't yet supported on aarch64, as our aarch64 support in Theseus doesn't yet cover all crates in the entire repo.

Using QEMU

QEMU allows us to run Theseus quickly and easily in its own virtual machine. To release your keyboard and mouse focus from the QEMU window, press <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>G</kbd>, or <kbd>Ctrl</kbd> + <kbd>Alt</kbd> on some systems, or just <kbd>Cmd</kbd> + <kbd>Tab</kbd> out to another app on macOS. To exit QEMU, in the terminal window that you originally ran make run, press <kbd>Ctrl</kbd> + <kbd>A</kbd> then <kbd>X</kbd>, or you can also click the GUI ⓧ button on the title bar if running QEMU in graphical mode.

To investigate the hardware/machine state of the running QEMU VM, you can switch to the QEMU console by pressing <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>2</kbd>. Switch back to the main window with <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>1</kbd>. On Mac, manually select VGA or compact_monitor0 under View from the QEMU menu bar.

To access/expose a PCI device in QEMU using PCI passthrough v