Welcome to hhuOS, a small operating system written in C++ and Assembler for the x86-architecture. The main purpose of this project is to show how different aspects of operating systems theory can be implemented and linked together. The system is not aimed to be a full-featured operating system for daily use.
This is a project by the Operating Systems group at the Heinrich Heine University Düsseldorf.
We provide nightly builds of our master and development branches via GitHub Releases. Execute the following commands to download and run the latest master build in QEMU (on Ubuntu 24.04):
sudo apt install wget qemu-system-x86
mkdir -p hhuOS
cd hhuOS
wget https://github.com/hhuOS/hhuOS/releases/download/nightly-master/hhuOS-master.tar.gz
tar -xzf hhuOS-master.tar.gz
./run.shThe OS will boot into a shell with some UNIX-like commands. Run ls /bin to see all available applications. Try out bug and dino for some old-fashioned games!
If QEMU hangs on a black screen, try executing ./run.sh --bios true --file hhuOS-limine.iso. There seems to be a problem with older QEMU versions and new OVMF images.
GCC (compatible with C++20), CMake (>=3.14) and some other dependencies are required to compile hhuOS. To install them, you can run the following command (on Ubuntu 24.04):
sudo apt install build-essential nasm gcc-multilib g++-multilib cmake libgl-dev python3 python3-setuptools xorriso dosfstools mtools unzip wget ffmpeg git recodeAfterward, clone this repository and execute the included build-script:
git clone https://github.com/hhuOS/hhuOS.git
cd hhuOS
git submodule update --init --recursive
./build.shTo test hhuOS in QEMU, simply execute the included run-script:
./run.shIf QEMU hangs on a black screen, try building an image with Limine bootloader and then running QEMU with a classic BIOS:
./build.sh --target limine
./run.sh --bios true --file hhuOS-limine.iso
There seems to be a problem with older QEMU versions and new OVMF images.
Congratulations! If you have made it this far, you have successfully compiled and run hhuOS! If you have not done so yet, you should definitely try out the included games bug, battlespace, dino and rogue3d, as well as the demo command, to see the capabilities of our user space game engine. There is also some ported software available for hhuOS (Scroll down for an exhaustive list).
When you are done tinkering with the OS, why not try to build your own application for hhuOS? Our wiki provides tutorials on how to set up a development environment and get started with app development for hhuOS.
|
Demonstration of some shell commands in hhuOS |
Network stack demo |
Bug Defender is a Space Invaders clone |
Battlespace is a 3D space shooter |
The classic gears demo using TinyGL |
Rotating textured cubes using TinyGL |
3D demo scene rendered with our game engine |
Rogue3D is a roguelike game |
Assets for the dino game have been taken from itch.io:
- Dino Characters by @ScissorMarks (CC BY 4.0)
- Dino Family by DemChing (CC BY 4.0)
- Pixel Adventure by Pixel Frog (CC0 1.0)
- Pixel Platformer by Kenney (CC0 1.0)
- Retro Cloud Tileset by ohnoponogames
Assets for the bug defender game have been taken from itch.io:
Assets for the battlespace game have been taken from itch.io:
3D-demo assets haven been taken from itch.io:
Assets for the mouse demo haven been taken from Icons8.
Music for the SoundBlaster demo has been taken from Bensound:
- Ukulele license code: 3M7PXYPYNOTSIGNQ
Doom has been ported to hhuOS using doomgeneric by ozkl (GPLv2)
- Available as
doomcommand in hhuOS. - Prebuilt versions of hhuOS on GitHub Releases do not include a WAD file. If you want to play Doom, build hhuOS from source. The shareware WAD file will be downloaded automatically.
Quake has been ported to hhuOS using quakegeneric by erysdren (GPLv2)
- Available as
quakecommand in hhuOS. - Prebuilt versions of hhuOS on GitHub Releases do not include a PAK file. If you want to play Quake, build hhuOS from source. The shareware PAK file will be downloaded automatically.
ClassiCube by UnknownShadow200 (License):
- Available as
classicubecommand in hhuOS. - Only single player mode is working (network functionality is currently not supported).
- Performance and visuals are limited by the software renderer.
Peanut-GB by deltabeard (MIT):
- Available as
peanut-gbcommand in hhuOS. - Joypad is mapped to WASD; A and B are mapped to K and J; Start is mapped to Space and Select is mapped to Enter. Use 'F1' and 'F2' to adjust screen scaling. Use 'F3' to cycle through color palettes and 'F4' to reset to default palette.
- Place your own ROM files in
disk/hdd0/user/gameboy/before building hhuOS to include them in the HDD image. - The following games are included in
/user/gameboy/:
clownmdemu by Clownacy (GNU AGPLv3):
- Available as
clownmdemucommand in hhuOS. - Joypad is mapped to arrow keys; ABC and XYZ buttons are mapped to A, S, D and Y(Z), X, C respectively; Start is mapped to Space and Mode is mapped to Enter. Use 'F1' and 'F2' to adjust screen scaling. Use 'F3' to cycle through color palettes and 'F4' to reset to default palette.
- Place your own ROM files in
disk/hdd0/user/megadrive/before building hhuOS to include them in the HDD image. - The following games are included in
/user/megadrive/:
- Try out the
tinyglcommand in hhuOS for some demos. - Used by our game engine to render 3D graphics.
PortableGL by rswinkle (MIT)
- Try out the
portableglcommand in hhuOS for some demos.