{"id":13472643,"url":"https://github.com/theseus-os/Theseus","last_synced_at":"2025-03-26T17:31:02.691Z","repository":{"id":36995292,"uuid":"97989275","full_name":"theseus-os/Theseus","owner":"theseus-os","description":"Theseus is a modern OS written from scratch in Rust that explores 𝐢𝐧𝐭𝐫𝐚𝐥𝐢𝐧𝐠𝐮𝐚𝐥 𝐝𝐞𝐬𝐢𝐠𝐧: closing the semantic gap between compiler and hardware by maximally leveraging the power of language safety and affine types. Theseus aims to shift OS responsibilities like resource management into the compiler.","archived":false,"fork":false,"pushed_at":"2024-09-22T18:48:20.000Z","size":135404,"stargazers_count":2901,"open_issues_count":67,"forks_count":173,"subscribers_count":36,"default_branch":"theseus_main","last_synced_at":"2024-10-30T05:26:06.366Z","etag":null,"topics":["intralingual","kernel","operating-system","research","rust","theseus"],"latest_commit_sha":null,"homepage":"https://www.theseus-os.com/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theseus-os.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE-MIT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["kevinaboos"],"custom":null}},"created_at":"2017-07-21T21:52:39.000Z","updated_at":"2024-10-28T16:59:47.000Z","dependencies_parsed_at":"2024-10-30T03:51:28.397Z","dependency_job_id":null,"html_url":"https://github.com/theseus-os/Theseus","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theseus-os%2FTheseus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theseus-os%2FTheseus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theseus-os%2FTheseus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theseus-os%2FTheseus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theseus-os","download_url":"https://codeload.github.com/theseus-os/Theseus/tar.gz/refs/heads/theseus_main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245702173,"owners_count":20658560,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["intralingual","kernel","operating-system","research","rust","theseus"],"created_at":"2024-07-31T16:00:56.621Z","updated_at":"2025-03-26T17:31:01.946Z","avatar_url":"https://github.com/theseus-os.png","language":"Rust","readme":"# Theseus OS\n\n[![Documentation](https://img.shields.io/badge/view-docs-blue)](https://theseus-os.github.io/Theseus/doc/___Theseus_Crates___/index.html)\n[![Book](https://img.shields.io/badge/view-book-blueviolet)](https://theseus-os.github.io/Theseus/book/index.html)\n[![Blog](https://img.shields.io/badge/view-blog-orange)](https://theseus-os.com)\n[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?style=flat\u0026logo=discord\u0026logoColor=white)](https://discord.gg/NuUnqeYT8R)\n\u003cbr\u003e\n[![Build Action](https://img.shields.io/github/actions/workflow/status/theseus-os/Theseus/docs.yaml?label=build)](https://github.com/theseus-os/Theseus/actions/workflows/docs.yaml)\n[![Clippy Action](https://img.shields.io/github/actions/workflow/status/theseus-os/Theseus/check-clippy.yaml?label=clippy)](https://github.com/theseus-os/Theseus/actions/workflows/check-clippy.yaml)\n[![QEMU tests](https://img.shields.io/github/actions/workflow/status/theseus-os/Theseus/test.yaml?label=QEMU%20tests)](https://github.com/theseus-os/Theseus/actions/workflows/test.yaml)\n\n\nTheseus is a new OS written from scratch in [Rust](https://www.rust-lang.org/) 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.\n\nFor more info, check out Theseus's [documentation](#Documentation) or our [published academic papers](https://theseus-os.github.io/Theseus/book/misc/papers_presentations.html), which describe Theseus's design and implementation. \n\nTheseus 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. \nWe 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.\n\n\n# Quick start\nOn Linux (Debian-like distros), do the following:\n 1. Obtain the Theseus repository (with all submodules):    \n    ```\n    git clone --recurse-submodules --depth 1 https://github.com/theseus-os/Theseus.git\n    ```\n 2. Install Rust:\n    ```\n    curl https://sh.rustup.rs -sSf | sh\n    ```\n 3. Install dependencies:\n    ```\n    sudo apt-get install make gcc nasm pkg-config grub-pc-bin mtools xorriso qemu qemu-kvm wget\n    ```\n 4. Build and run (in QEMU):\n    ```sh\n    cd Theseus\n    make run\n    ```\n    To exit QEMU, press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e, then \u003ckbd\u003eX\u003c/kbd\u003e.\n\nSee below for more detailed instructions.\n\n\n# Building and Running Theseus\n**Note:** when you first check out the project, be sure to get all the submodule repositories too:\n```\ngit submodule update --init --recursive\n```\n\nCurrently, we support building Theseus on the following platforms:\n * Linux, 64-bit Debian-based distributions like Ubuntu, tested on Ubuntu 16.04, 18.04, 20.04. \n   - Arch Linux and Fedora have also been reported to work correctly. \n * Windows, using the Windows Subsystem for Linux (WSL), tested on the Ubuntu version of WSL and WSL2.\n * MacOS, tested on versions High Sierra (v10.13), Catalina (v10.15), and Ventura (v13.5).\n * Docker, atop any host OS that can run a Docker container.\n\n\n## Setting up the build environment\n\nFirst, install Rust by following the [setup instructions here](https://www.rust-lang.org/en-US/install.html). On Linux, just run:\n```sh\ncurl https://sh.rustup.rs -sSf | sh\n```\n\n### Building on Linux or WSL (Windows Subsystem for Linux)\nInstall the following dependencies using your package manager:\n```bash\nsudo apt-get install make gcc nasm pkg-config grub-pc-bin mtools xorriso qemu qemu-kvm wget\n```\n\n  * Or:\n    ```bash\n    # Arch Linux\n    sudo pacman -S make gcc nasm pkg-config grub mtools xorriso qemu wget\n\n    # Fedora\n    sudo dnf install make gcc nasm pkg-config grub2 mtools xorriso qemu wget\n    ```\n\nIf you're on WSL, also do the following steps:\n  * Install an X Server for Windows; we suggest using [Xming](https://sourceforge.net/projects/xming/) or [VcXsvr](https://sourceforge.net/projects/vcxsrv/).\n    * You'll likely need to invoke those X servers with the `-ac` argument (or use the GUI to disable access control). \n  * Setup an X display as follows:\n    * on original WSL (version 1), run:\n      ```sh\n      export DISPLAY=:0\n      ```\n    * on WSL2 (version 2), run:\n      ```sh\n      export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0\n      ```\n\n    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.\n  * 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.\n  * **NOTE**: WSL and WSL2 do not currently support using KVM.\n\n### Building on MacOS\n  * Install [HomeBrew](https://brew.sh/), then run the MacOS build setup script:\n    ```sh\n    sh ./scripts/mac_os_build_setup.sh\n    ```\n    If things go wrong, remove the following build directories and try to run the script again.\n    ```sh\n    rm -rf /tmp/theseus_tools_src\n    ```\n  * **NOTE**: on MacOS, you need to run `gmake` instead of `make` for build commands (or you can simply create a shell alias).\n    * This is because HomeBrew installs its binaries in a way that doesn't conflict with built-in versions of system utilities.\n  \n  * *(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:\n    ```sh\n    arch -x86_64 bash   # or another shell of your choice\n    ```\n    and possibly adjust your system `PATH` if both x86 and ARM homebrew binaries are installed:\n    ```sh\n    export PATH=/usr/local/Homebrew/bin:$PATH\n    ```\n\n### Building using Docker\nNote: building and running Theseus within a Docker container may be slower than on a native host OS.\n 1. Ensure docker scripts are executable:\n    ```\n    chmod +x docker/*.sh\n    ```   \n 2. *(Skip if docker is already installed.)*  Install [Docker Engine](https://docs.docker.com/engine/install/). We provide a convenience script for this on Ubuntu:\n    ```\n    ./docker/install_docker_ubuntu.sh\n    ``` \n    * After docker installs, enable your user account to run docker without root privileges:   \n      `sudo groupadd docker; sudo usermod -aG docker $USER`    \n      Then, **log out and log back in** (or restart your computer) for the user/group changes to take effect.\n \n 3. Build the docker image:     \n    ```\n    ./docker/build_docker.sh\n    ```    \n    This does not build Theseus, but rather only creates a docker image that contains all the necessary dependencies to build and run Theseus. \n 4. Run the new docker image locally as a container:    \n    ```\n    ./docker/run_docker.sh\n    ```   \n    Now you can run `make run` or other Theseus-specific build/run commands from within the docker container's shell.\n\nNotes on Docker usage:    \n  * 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.\n  * KVM doesn't currently work in docker. To run Theseus in QEMU using KVM, you can build Theseus within docker, exit the container (via \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e`), and then run `make orun host=yes` on your host machine.\n\n\n## Building and Running\nBuild the default Theseus OS image and run it in QEMU:   \n```sh\nmake run\n```\n\nOr, build a full Theseus OS image with all features and crates enabled:\n```sh\nmake full   ## or `make all`\n```\n\nRun `make help` to see other make targets and the various command-line options.\n\n\n## Using the Limine bootloader instead of GRUB\nTo use Limine instead of GRUB, clone pre-built limine and pass `bootloader=limine` to make:\n```sh\ngit clone https://github.com/limine-bootloader/limine.git limine-prebuilt\ngit -C limine-prebuilt reset --hard 3f6a330\nmake run bootloader=limine\n```\nFeel free to try newer versions, however they may not work.\n\n\n## Targeting ARMv8 (aarch64)\nSupport for Theseus on aarch64 is an ongoing effort, but most of the core subsystems are complete.\n\nTo build and run Theseus on aarch64, first install the required dependencies:\n* On Debian-like Linux (Ubuntu, etc):\n  ```bash\n  sudo apt-get install qemu-system-arm gcc-aarch64-linux-gnu\n  ```\n* On Arch Linux:\n  ```bash\n  sudo pacman -S aarch64-linux-gnu-gcc qemu-system-aarch64\n  ```\n* On macOS, the `mac_os_build_setup` script should have already installed this for you, but if not:\n  ```zsh\n  brew install aarch64-elf-gcc aarch64-elf-binutils\n\n  ```\n\nThen, build Theseus and run it in QEMU:\n```bash\nmake ARCH=aarch64 run\n```\n\nDoing a \"full\" build of all Theseus crates isn't yet supported on aarch64,\nas our aarch64 support in Theseus doesn't yet cover *all* crates in the entire repo.\n\n\n## Using QEMU\nQEMU allows us to run Theseus quickly and easily in its own virtual machine.\nTo release your keyboard and mouse focus from the QEMU window, press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eG\u003c/kbd\u003e, or \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e on some systems, or just \u003ckbd\u003eCmd\u003c/kbd\u003e + \u003ckbd\u003eTab\u003c/kbd\u003e out to another app on macOS.\nTo exit QEMU, in the terminal window that you originally ran `make run`, press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e then \u003ckbd\u003eX\u003c/kbd\u003e, or you can also click the GUI `ⓧ` button on the title bar if running QEMU in graphical mode.\n\nTo investigate the hardware/machine state of the running QEMU VM, you can switch to the QEMU console by pressing \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e.\nSwitch back to the main window with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e.\nOn Mac, manually select `VGA` or `compact_monitor0` under `View` from the QEMU menu bar.\n\nTo access/expose a PCI device in QEMU using PCI passthrough via VFIO, see [these instructions](https://theseus-os.github.io/Theseus/book/running/virtual_machine/pci_passthrough.html).\n\nLinux does not support the ICMP protocol (for `ping`) for guest OSes in QEMU by default, so to allow `ping` to work on Theseus, you may need to run the following in your Linux host machine:\n```sh\nsudo sh -c \"echo \\\"0 2147483647\\\" \u003e /proc/sys/net/ipv4/ping_group_range\"\n```\n\n### KVM Support\nWhile not strictly required, KVM will speed up the execution of QEMU.\nTo install KVM, run the following command:    \n```sh\nsudo apt-get install kvm\n```  \nTo enable KVM support, add `host=yes` to your make command, e.g.,    \n```\nmake run host=yes\n```\n\nNote that KVM acceleration is only supported on native Linux hosts.\n\n\n# Documentation\nTheseus includes two forms of documentation:\n1. The [source-level documentation](https://theseus-os.github.io/Theseus/doc/___Theseus_Crates___/index.html), generated from code and inline comments (via *rustdoc*).\n    * Intended for Theseus developers and contributors, or those who want low-level details.\n2. The [book-style documentation](https://theseus-os.github.io/Theseus/book/index.html), written in Markdown.\n    * Useful for high-level descriptions of design concepts and key components.\n\nTo build the documentation yourself, set up your local build environment and then run the following:\n```sh\nmake view-doc   ## for the source-level docs\nmake view-book  ## for the Theseus book\n```\n\n# Other\n\n## Booting on Real Hardware\nWe have tested Theseus on a variety of real machines, including Intel NUC devices, various Thinkpad laptops, and Supermicro servers. \nCurrently, we have only tested booting Theseus via USB or PXE using a traditional BIOS bootloader rather than UEFI, but UEFI is fully supported so it should work.\n\nTo boot over USB, simply run `make usb drive=sdc`, in which `sdc` is the device node for the USB disk itself *(**not a partition** like sdc2)* to which you want to write the OS image.\nOn WSL or other host environments where `/dev` device nodes don't exist, you can simply run `make iso` and burn the `.iso` file in the `build/` directory to a USB, e.g., using [Rufus](https://rufus.ie/) on Windows.\n\nTo boot Theseus over PXE (network boot), see [this set of separate instructions](https://theseus-os.github.io/Theseus/book/running/pxe.html).\n\n\n## Debugging Theseus on QEMU\nGDB has built-in support for QEMU, but it doesn't play nicely with OSes that run in 64-bit long mode. In order to get it working properly with our OS in Rust, we need to patch it and build it locally. The hard part has already been done for us ([details here](https://os.phil-opp.com/set-up-gdb/)), so we can just quickly set it up with the following commands.  \n\n1. Install the following packages:\n    ```\n    sudo apt-get install texinfo flex bison python-dev ncurses-dev\n    ```\n\n2. From the base Theseus directory, run this script to download and build GDB from an existing patched repo:\n    ```\n    curl -sf https://raw.githubusercontent.com/phil-opp/binutils-gdb/rust-os/build-rust-os-gdb.sh | sh\n    ```\n    After that, you should have a `rust-os-gdb` directory that contains the `gdb` executables and scripts. \n\n3. Run Theseus in QEMU using `make run` (or `make run_pause` to pause QEMU until we attach GDB).\n\n4. In another terminal window, run the following to start GDB and attach it to the running QEMU instance:\n    ```\n    make gdb \n    ```\n    QEMU will be paused until we move the debugger forward, with standard GDB commands like `n` to step through the next instruction or `c` to continue execution. Any standard GDB commands will now work.\n\n### Connecting GDB to aarch64 Theseus on QEMU\nWe don't yet have a patched version of GDB for aarch64 targets, but we can use the existing `gdb-multiarch` package to \n\n1. Install the required package:\n    ```sh\n    sudo apt-get install gdb-multiarch\n    ```\n\n2. Build Theseus for aarch64 and run it in QEMU:\n    ```sh\n    make ARCH=aarch64 run ## or use `run_pause`\n    ```\n3. In another terminal window, run the following to start GDB and attach it to the running QEMU instance:\n    ```sh\n    gdb-multiarch -ex \"target remote :1234\"\n    ```\n\n4. Within GDB, symbols aren't yet supported, but you can view assembly code with `layout asm` and set breakpoints on virtual addresses.\n\n## IDE Setup  \nOur personal preference is to use VS Code, which has excellent cross-platform support for Rust. Other options are available [here](https://areweideyet.com/).\n\nFor VS Code, recommended plugins are:\n * **rust-analyzer**, by matklad\n * **Better TOML**, by bungcip\n * **x86 and x86_64 Assembly**, by 13xforever\n \n\n## Acknowledgements\nWe would like to express our thanks to the [OS Dev wiki](https://wiki.osdev.org/) and its community and to Philipp Oppermann's [blog_os](https://os.phil-opp.com/) for serving as excellent starting points for Theseus. The early days of Theseus's development progress are indebted to these resources. \n\n\n## License\nTheseus's source code is licensed under the MIT License. See the [LICENSE-MIT](LICENSE-MIT) file for more. \n\n\n## Contributing\nWe adhere to similar development and code style guidelines as the core Rust language project. See more [here](https://theseus-os.github.io/Theseus/book/contribute/contribute.html).\n\nPRs and issues are welcome from anyone; because Theseus is an experimental OS, certain features may be deprioritized or excluded from the main branch. Don't hesitate to ask or mention something though! :smile:\n","funding_links":["https://github.com/sponsors/kevinaboos"],"categories":["Rust","Applications","应用程序 Applications","General Operating System","Open Source Operating Systems"],"sub_categories":["Operating systems","操作系统 Operating systems"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheseus-os%2FTheseus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheseus-os%2FTheseus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheseus-os%2FTheseus/lists"}