Building CrisOS v2: Compile and Generate a Boot ISO

CrisOS v2 uses a straightforward Makefile-based build system. All C source files are compiled with -ffreestanding -m32 -nostdlib, linked with a custom linker script (linker.ld), and packaged into a bootable GRUB ISO using grub-mkrescue. The entire process — from a clean checkout to a running VM — is handled by a handful of make targets.

Prerequisites

The following tools must be available on your PATH before building:

Tool	Purpose	Notes
`i686-elf-gcc`	Cross-compiler (recommended)	Falls back to system `gcc` if not found
`i686-elf-ld`	Cross-linker (recommended)	Falls back to system `ld` if not found
`make`	Build orchestration	GNU Make required
`python3`	Rootfs image builder	Invoked as `python` by default; override with `PYTHON=python3`
`grub-mkrescue` + `grub-pc-bin`	ISO generation	Required for `make echo-iso` and `make run`
`qemu-system-i386`	Testing	Required for `make run`

On Ubuntu/Debian you can install most dependencies in one shot:

sudo apt install build-essential gcc-multilib grub-pc-bin grub-common \
     xorriso qemu-system-x86 python3

Cross-Compiler Auto-Detection

The Makefile probes for i686-elf-gcc at the start of every build. If the cross-compiler toolchain is present it is used exclusively; otherwise the build falls back to the system gcc/ld. The exact detection block from the Makefile is:

ifeq ($(shell command -v i686-elf-gcc >/dev/null 2>&1 && echo yes),yes)
	CC  = i686-elf-gcc
	AS  = i686-elf-gcc
	LD  = i686-elf-ld
else
	CC  = gcc
	AS  = gcc
	LD  = ld
endif

Using a dedicated i686-elf cross-compiler is strongly recommended. It eliminates host-ABI contamination and ensures the output is always a clean 32-bit ELF binary regardless of whether your host is 32-bit or 64-bit.

Compiler and Linker Flags

These flags are defined at the top of the Makefile and applied to every translation unit:

CFLAGS  = -ffreestanding -O2 -Wall -Wextra -m32 -nostdlib -std=c99 -I src
ASFLAGS = -m32 -ffreestanding
LDFLAGS = -m elf_i386 -nostdlib

-ffreestanding — tells GCC the standard library is not available and main is not the entry point.
-m32 — emit 32-bit i386 code regardless of the host architecture.
-nostdlib — do not link against libc or the GCC startup files.
-std=c99 — enforce the C99 standard throughout.
-I src — add src/ to the include search path so headers can be included without path prefixes.

Source Files

The Makefile organises sources into three variables: Kernel C sources (SRCS)

SRCS  = src/kernel.c     \
        src/kstring.c    \
        src/gdt.c        \
        src/idt.c        \
        src/fs.c         \
        src/vfs.c        \
        src/shell.c      \
        src/boot.c       \
        src/systemd.c    \
        src/lcp.c        \
        src/gui.c        \
        src/memory.c     \
        src/calc.c       \
        src/calc_app.c

Driver C sources (DRV_SRCS)

DRV_SRCS = drivers/console.c  \
           drivers/keyboard.c \
           drivers/mouse.c    \
           drivers/timer.c    \
           drivers/pic.c

Assembly sources (ASMS)

ASMS  = src/asm_utils.S  \
        src/math_asm.S   \
        boot/boot.S

Driver object files are prefixed with drv_ in build/ (e.g. build/drv_console.o) to avoid name collisions with same-named kernel sources.

Build Targets

make — compile and link the kernel

Compiles every .c and .S file listed above into build/*.o, then links them with linker.ld to produce build/kernel.bin.

make

The linker script places the Multiboot header at 0x00100000 and lays out .text, .rodata, .data, and .bss sections in order.

make iso — build rootfs and stage boot files

Runs the all target, then invokes tools/build_rootfs.py to pack the contents of rootfs/ into a CRFS image at iso/boot/rootfs.bin. Finally it copies build/kernel.bin to iso/boot/kernel.bin.

make iso

make echo-iso — generate the bootable ISO

Runs the iso step, then calls grub-mkrescue to assemble everything under iso/ into a bootable hybrid ISO at os.iso. If grub-mkrescue is not installed, a warning is printed instead.

make echo-iso

make run — launch in QEMU

Runs the full echo-iso pipeline and then boots the resulting image with 512 MB of RAM:

make run
# Equivalent to:
qemu-system-i386 -cdrom os.iso -m 512M

make clean — remove all build artefacts

Deletes build/, os.iso, iso/boot/kernel.bin, and iso/boot/rootfs.bin. The iso/ directory skeleton and GRUB configuration are left intact.

make clean

Build Output Structure

After a successful make echo-iso the working tree looks like this:

build/
  kernel.bin          # final ELF kernel binary
  boot.o              # Multiboot entry point
  asm_utils.o         # low-level ASM utilities
  math_asm.o          # arithmetic ASM routines
  *.o                 # compiled kernel object files
  drv_*.o             # compiled driver object files
iso/
  boot/
    kernel.bin        # copy of the kernel (loaded by GRUB)
    rootfs.bin        # CRFS rootfs image (passed as Multiboot module)
    grub/
      grub.cfg        # GRUB menu configuration
      core.img        # GRUB core image
      eltorito.img    # El Torito boot image
      theme.txt       # optional GRUB theme
os.iso                # final bootable hybrid ISO image

Complete Makefile

View full Makefile

ifeq ($(shell command -v i686-elf-gcc >/dev/null 2>&1 && echo yes),yes)
	CC  = i686-elf-gcc
	AS  = i686-elf-gcc
	LD  = i686-elf-ld
else
	CC  = gcc
	AS  = gcc
	LD  = ld
endif

BUILD_DIR = build
ISO_DIR   = iso
PYTHON    ?= python

KERNEL = $(BUILD_DIR)/kernel.bin
ROOTFS = $(ISO_DIR)/boot/rootfs.bin
QEMU   = qemu-system-i386

CFLAGS  = -ffreestanding -O2 -Wall -Wextra -m32 -nostdlib -std=c99 -I src
ASFLAGS = -m32 -ffreestanding
LDFLAGS = -m elf_i386 -nostdlib

SRC_DIR  = src
DRV_DIR  = drivers

SRCS  = $(SRC_DIR)/kernel.c \
        $(SRC_DIR)/kstring.c \
        $(SRC_DIR)/gdt.c \
        $(SRC_DIR)/idt.c \
        $(SRC_DIR)/fs.c \
        $(SRC_DIR)/vfs.c \
        $(SRC_DIR)/shell.c \
        $(SRC_DIR)/boot.c \
        $(SRC_DIR)/systemd.c \
        $(SRC_DIR)/lcp.c \
        $(SRC_DIR)/gui.c \
        $(SRC_DIR)/memory.c \
        $(SRC_DIR)/calc.c \
        $(SRC_DIR)/calc_app.c

DRV_SRCS = $(DRV_DIR)/console.c \
           $(DRV_DIR)/keyboard.c \
           $(DRV_DIR)/mouse.c \
           $(DRV_DIR)/timer.c \
           $(DRV_DIR)/pic.c

ASMS  = $(SRC_DIR)/asm_utils.S \
        $(SRC_DIR)/math_asm.S \
        boot/boot.S

OBJS  = $(patsubst $(SRC_DIR)/%.c,$(BUILD_DIR)/%.o,$(SRCS))
OBJS += $(patsubst $(DRV_DIR)/%.c,$(BUILD_DIR)/drv_%.o,$(DRV_SRCS))
OBJS += $(BUILD_DIR)/boot.o \
        $(BUILD_DIR)/asm_utils.o \
        $(BUILD_DIR)/math_asm.o

all: $(KERNEL)

$(BUILD_DIR):
	mkdir -p $(BUILD_DIR)

$(ISO_DIR)/boot/grub:
	mkdir -p $(ISO_DIR)/boot/grub

$(BUILD_DIR)/boot.o: boot/boot.S | $(BUILD_DIR)
	$(AS) $(ASFLAGS) -c boot/boot.S -o $@

$(BUILD_DIR)/asm_utils.o: src/asm_utils.S | $(BUILD_DIR)
	$(AS) $(ASFLAGS) -c src/asm_utils.S -o $@

$(BUILD_DIR)/math_asm.o: src/math_asm.S | $(BUILD_DIR)
	$(AS) $(ASFLAGS) -c src/math_asm.S -o $@

$(BUILD_DIR)/%.o: $(SRC_DIR)/%.c | $(BUILD_DIR)
	$(CC) $(CFLAGS) -c $< -o $@

$(BUILD_DIR)/drv_%.o: $(DRV_DIR)/%.c | $(BUILD_DIR)
	$(CC) $(CFLAGS) -c $< -o $@

$(KERNEL): $(OBJS) linker.ld | $(BUILD_DIR)
	$(LD) $(LDFLAGS) -T linker.ld -o $(KERNEL) $(OBJS)

$(ROOTFS): tools/build_rootfs.py rootfs/README.txt rootfs/info.txt | $(ISO_DIR)/boot/grub
	$(PYTHON) tools/build_rootfs.py rootfs $(ROOTFS)

iso: all $(ROOTFS)
	cp $(KERNEL) $(ISO_DIR)/boot/kernel.bin

echo-iso: iso
	@if command -v grub-mkrescue >/dev/null 2>&1; then \
		grub-mkrescue -o os.iso $(ISO_DIR); \
	else \
		echo "Instala grub-mkrescue para crear os.iso"; \
	fi

run: echo-iso
	$(QEMU) -cdrom os.iso -m 512M

clean:
	rm -rf $(BUILD_DIR) os.iso $(ISO_DIR)/boot/kernel.bin $(ISO_DIR)/boot/rootfs.bin

.PHONY: all iso echo-iso run clean

If you encounter a linker error such as cannot find -lgcc or unrecognised emulation name elf_i386, your system binutils may lack 32-bit support. Install the multilib package and retry:

sudo apt install gcc-multilib

Get Started

Architecture

Subsystems

Tools

Development

Building CrisOS v2: Compile and Generate a Boot ISO

Prerequisites

Cross-Compiler Auto-Detection

Compiler and Linker Flags

Source Files

Build Targets

Build Output Structure

Complete Makefile

Build docs developers (and LLMs) love

Get Started

Architecture

Subsystems

Tools

Development

Documentation Index

​Prerequisites

​Cross-Compiler Auto-Detection

​Compiler and Linker Flags

​Source Files

​Build Targets

​Build Output Structure

​Complete Makefile

Build docs developers (and LLMs) love

Prerequisites

Cross-Compiler Auto-Detection

Compiler and Linker Flags

Source Files

Build Targets

Build Output Structure

Complete Makefile