ginnOS (Ginn short for Ginnungagap, and OS short for Operating System) is a unix-like hobby operating system, written from scratch in c and assembly, which i'm developing alongside a course on operating systems i'm taking at DTU.
I started this project because i wanted to understand how an operating system is really coded instead of just theory. I plan to keep building and improving it as i learn more.
The name ginnOS is taken from Ginnungagap, the primordial void in Norse mythology from which the world was created.
"That was the age when nothing was; / There was no sand, nor sea, nor cool waves, / No earth nor sky nor grass there, / Only Ginnungagap."
- Völuspá, Poetic Edda
I've recently started on writing documentation for this project in obsidian and hosting it using quartz, this can be read at: https://lassedtu.github.io/ginnOS-docs/
git clone https://github.com/lassedtu/ginnOS
cd ginnOSOnly install what this two-stage build needs:
brew install gmp mpfr libmpc texinfo nasm qemuCreate build directories:
mkdir -p "$HOME/src/cross"
mkdir -p "$HOME/opt/cross"
cd "$HOME/src/cross"Build and install binutils:
curl -LO https://ftp.gnu.org/gnu/binutils/binutils-2.42.tar.xz
tar -xf binutils-2.42.tar.xz
mkdir -p build-binutils
cd build-binutils
../binutils-2.42/configure \
--target=i686-elf \
--prefix="$HOME/opt/cross" \
--with-sysroot \
--disable-nls \
--disable-werror
make -j"$(sysctl -n hw.ncpu)"
make install
cd ..Build and install GCC (C only):
curl -LO https://ftp.gnu.org/gnu/gcc/gcc-14.2.0/gcc-14.2.0.tar.xz
tar -xf gcc-14.2.0.tar.xz
mkdir -p build-gcc
cd build-gcc
../gcc-14.2.0/configure \
--target=i686-elf \
--prefix="$HOME/opt/cross" \
--disable-nls \
--enable-languages=c \
--without-headers
make -j"$(sysctl -n hw.ncpu)" all-gcc all-target-libgcc
make install-gcc install-target-libgcc
cd ..echo 'export PATH="$HOME/opt/cross/bin:$PATH"' >> ~/.zshrc
source ~/.zshrci686-elf-gcc --version
i686-elf-ld --version
i686-elf-objcopy --version
nasm -v
qemu-system-i386 --versionA shell.nix is included at the project root. It pulls in the i686-elf cross-compiler, binutils, NASM, QEMU, and Python 3, no manual toolchain build required.
nix-shellAll required tools (i686-elf-gcc, i686-elf-ld, i686-elf-objcopy, nasm, qemu-system-i386, python3) will be on your PATH inside the shell.
make
make rungit clone https://github.com/lassedtu/ginnOS
cd ginnOSOnly install what this two-stage build needs:
sudo apt update
sudo apt install build-essential curl nasm qemu-system-x86 \
libgmp-dev libmpfr-dev libmpc-dev texinfo bison flex \
python3 e2fsprogsCreate build directories:
mkdir -p "$HOME/src/cross"
mkdir -p "$HOME/opt/cross"
cd "$HOME/src/cross"Build and install binutils:
curl -LO https://ftp.gnu.org/gnu/binutils/binutils-2.42.tar.xz
tar -xf binutils-2.42.tar.xz
mkdir -p build-binutils
cd build-binutils
../binutils-2.42/configure \
--target=i686-elf \
--prefix="$HOME/opt/cross" \
--with-sysroot \
--disable-nls \
--disable-werror
make -j"$(nproc)"
make install
cd ..Build and install GCC (C only):
curl -LO https://ftp.gnu.org/gnu/gcc/gcc-14.2.0/gcc-14.2.0.tar.xz
tar -xf gcc-14.2.0.tar.xz
mkdir -p build-gcc
cd build-gcc
../gcc-14.2.0/configure \
--target=i686-elf \
--prefix="$HOME/opt/cross" \
--disable-nls \
--enable-languages=c \
--without-headers
make -j"$(nproc)" all-gcc all-target-libgcc
make install-gcc install-target-libgcc
cd ..echo 'export PATH="$HOME/opt/cross/bin:$PATH"' >> ~/.bashrc
source ~/.bashrcIf you use zsh instead of bash, append the same line to ~/.zshrc.
i686-elf-gcc --version
i686-elf-ld --version
i686-elf-objcopy --version
nasm -v
qemu-system-i386 --versionginnOS uses make, a cross-compiler, NASM, and QEMU. On Windows, the simplest way to get all of that working is WSL2 with Ubuntu, you get the same Linux toolchain as on a native install, without fighting MSYS or native Windows ports.
Open PowerShell as Administrator and run:
wsl --install -d UbuntuRestart if Windows asks you to. When you're back, Ubuntu will finish setup and prompt you to create a Linux user account.
If WSL is already installed and you only need the distro:
wsl --list --online
wsl --install -d UbuntuOpen Ubuntu (Start menu, or type wsl in PowerShell) and work from the Linux filesystem, for example ~/projects/ginnOS.
Avoid building from /mnt/c/... if you can; file I/O across the Windows/Linux boundary is noticeably slower and can cause odd issues with tools like make.
mkdir -p ~/projects
cd ~/projects
git clone https://github.com/lassedtu/ginnOS
cd ginnOSEverything from here is the same as on native Ubuntu. In your WSL terminal, follow the Ubuntu / Debian Toolchain Setup section:
- Install host dependencies
- Build the i686 cross compiler manually
- Add the cross toolchain to
PATH - Verify required tools
Once that is done, build from the project root, see Build and Run below. QEMU should open in its own window; on most Windows 11 + WSL2 setups this works without extra configuration.
From project root:
make
make runThe ext2 helper now builds an image from a real folder tree.
Default root folder:
Generate an ext2 image using the default folder:
make ext2-image
make run-ext2Generate an ext2 image from any folder on your machine:
make ext2-image EXT2_SOURCE_DIR=/absolute/path/to/your/folderOptionally force a custom image size (MiB):
make ext2-image EXT2_SOURCE_DIR=/absolute/path/to/your/folder EXT2_SIZE_MB=64If omitted, the helper auto-sizes the image from folder contents.
If you want the ext2 helper available on macOS, install:
brew install e2fsprogsThe helper tool is located at:
-
Nanobyte: https://www.youtube.com/@nanobyte-dev Operating system tutorials that have been a big help.
-
OSDev Wiki: https://wiki.osdev.org/ The main reference used for low level concepts and implementation.