Skip to content

Getting Started

Jump to bottom
Enrico Fraccaroli (Galfurian) edited this page Feb 3, 2026 · 7 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
sudo apt-get install -y gdb cgdb

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

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 i686-elf-gcc
brew install nasm
brew install cmake
brew install qemu

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
  2. Running MentOS - Launch in QEMU
  3. Architecture - Understand the project structure

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

MentOS requires CMake 3.1+ (as specified in the root CMakeLists). 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