Skip to content

Getting Started

Jump to bottom
Galfurian edited this page Aug 19, 2026 · 8 revisions

This guide will help you set up your development environment for MentOS.

Prerequisites

MentOS is compatible with Unix-based operating systems. It has been tested on:

  • Ubuntu (20.04+)
  • WSL1 / WSL2 (Windows Subsystem for Linux)
  • macOS (via cross-compilation using i686 toolchains)
  • ARM-based Linux (Ubuntu ARM, Apple Silicon VMs)

Installation

Ubuntu / WSL1 / WSL2

Install the required development tools and QEMU:

sudo apt-get update && sudo apt-get upgrade -y
sudo apt-get install -y git build-essential nasm make cmake cmake-curses-gui e2fsprogs gcc-multilib
sudo apt-get install -y qemu-system-x86 mtools xorriso
sudo apt-get install -y gdb cgdb

What each of the less obvious ones is for:

Package Why
nasm assembles boot.S and crt0.S (they are NASM syntax, not GAS)
e2fsprogs provides mke2fs, which builds rootfs.img; also debugfs for inspecting it
gcc-multilib lets a 64-bit host GCC emit the 32-bit code MentOS needs
qemu-system-x86 provides the qemu-system-i386 binary the build invokes
mtools, xorriso needed by grub-mkrescue for the GRUB/ISO boot targets and make qemu-test
cmake-curses-gui provides ccmake, the interactive option browser

Note: On some distributions, QEMU is exposed as qemu-system-i386 (installed by qemu-system-x86).

Compiler versions. The CI is the practical compatibility reference: MentOS is built there with GCC 12, 13, 14 and Clang 17, 18, 19 (.github/workflows/compiler-compatibility.yml), and tested with GCC 14 / Clang 19 (.github/workflows/ubuntu.yml). Anything in that range should work; much older compilers are untested.

ARM Systems (Ubuntu ARM / Apple Silicon)

For ARM-based Linux, you need i686-elf-gcc (bare-metal cross-compiler). This is required because tools/toolchain-i686-elf.cmake specifically expects it.

Option 1: Check your distribution's package manager (easiest if available):

apt-cache search i686-elf-gcc
apt-get install gcc-i686-elf

If gcc-i686-elf is not in your repos, try:

Option 2: Use a pre-built toolchain (recommended):

Download pre-built i686-elf toolchains from:

Option 3: Build from source (complex):

See osdev.org's GCC Cross-Compiler guide for detailed instructions using crosstool-ng or source builds.

Once installed and in your $PATH, use the toolchain file when building (see Building MentOS).

macOS

For macOS, install the i686 bare-metal cross-compiler using Homebrew:

brew install nasm cmake i686-elf-gcc
brew install qemu

(The first line is exactly what .github/workflows/macos.yml runs; qemu is extra, for actually running what you build.)

When building MentOS on macOS, always use the provided toolchain file:

cd MentOS
mkdir build && cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=../tools/toolchain-i686-elf.cmake
make

The toolchain file (tools/toolchain-i686-elf.cmake) configures CMake to use the i686-elf-gcc cross-compiler with the correct bare-metal compilation flags.

Verify Installation

Check that all tools are installed correctly:

gcc --version
nasm --version
cmake --version
qemu-system-i386 --version

Clone the Repository

git clone https://github.com/mentos-team/MentOS.git
cd MentOS

Optional Tools

For GRUB Booting

If you want to boot MentOS from GRUB in QEMU:

sudo apt-get install -y grub-common grub-pc-bin xorriso

For Better Debugging

We recommend cgdb (curses-based GDB frontend):

sudo apt-get install -y cgdb

Next Steps

Now that your environment is set up:

  1. Building MentOS - Compile the operating system. That page is the authoritative reference for build targets and CMake options; this page only covers getting the tools installed.
  2. Running MentOS - Launch in QEMU, log in (the shell is /bin/shell), and try the userspace programs
  3. Architecture - Understand the project structure
  4. Development Guide - Make your first change
  5. Debugging - When something goes wrong

Troubleshooting

Missing qemu-system-x86

If qemu-system-x86 is not found, try:

sudo apt-get install -y qemu-system-i386

CMake Version Too Old

The root CMakeLists.txt declares cmake_minimum_required(VERSION 3.1...3.22). Check your version:

cmake --version

If it's too old, install from the official CMake website or use a PPA.

Cross-compilation Issues

If you're on ARM and get compilation errors:

  1. Verify the cross-compiler is installed: i686-elf-gcc --version
  2. Ensure you're using the toolchain file: cmake .. -DCMAKE_TOOLCHAIN_FILE=../tools/toolchain-i686-elf.cmake
  3. Do NOT use manual -DCMAKE_C_COMPILER flags - the toolchain file handles this

Next: Building MentOS →

Clone this wiki locally