Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CRISTOP-bot/cris-os-v2/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning the CrisOS v2 repository, compiling the freestanding i386 kernel, packing the CRFS rootfs image, generating a bootable ISO with GRUB, and launching the system inside QEMU — from a fresh checkout to an interactive shell prompt in about five minutes.

​
Prerequisites

Before you start, make sure the following tools are available on your host machine:
ToolNotes
gcc or i686-elf-gccA C compiler that can target 32-bit i386. A bare-metal cross-compiler is recommended but not required.
makeStandard GNU Make for running the build targets.
qemu-system-i386QEMU machine emulator — install via your package manager (e.g. qemu-system-x86).
grub-mkrescuePart of GRUB 2 utilities — needed only to produce a bootable ISO.
Python 3Used by tools/build_rootfs.py to pack the rootfs directory into a CRFS binary image.
If i686-elf-gcc is not found on your PATH, the Makefile automatically falls back to the system gcc. The detection happens at the top of the Makefile using command -v i686-elf-gcc, so no manual configuration is required.

​
Build and Run

1

Clone the repository

Grab the source code from GitHub and enter the project directory:
git clone https://github.com/CRISTOP-bot/cris-os-v2.git
cd cris-os-v2
2

Build the kernel

Run make (or make all) to compile all C and Assembly sources and link them into the kernel binary:
make
The Makefile compiles every .c file in src/ and drivers/, assembles boot/boot.S, src/asm_utils.S, and src/math_asm.S, then links the objects via linker.ld using these flags:
CFLAGS  = -ffreestanding -O2 -Wall -Wextra -m32 -nostdlib -std=c99 -I src
ASFLAGS = -m32 -ffreestanding
LDFLAGS = -m elf_i386 -nostdlib
On success, the kernel ELF binary is written to:
build/kernel.bin
3

Build the rootfs and create a bootable ISO

Run make echo-iso to pack the rootfs, copy the kernel into the ISO tree, and invoke grub-mkrescue:
make echo-iso
This target does three things in sequence:
  1. Runs tools/build_rootfs.py rootfs iso/boot/rootfs.bin — walks the rootfs/ directory and writes a CRFS-format binary image (4-byte magic CRFS, version field, file entry table, then file data).
  2. Copies build/kernel.bin to iso/boot/kernel.bin.
  3. Calls grub-mkrescue -o os.iso iso/ to produce a hybrid El Torito ISO using the GRUB configuration in iso/boot/grub/grub.cfg.
The final output is:
os.iso
4

Run in QEMU

Launch the ISO in a QEMU virtual machine with 512 MB of RAM:
make run
This is equivalent to:
qemu-system-i386 -cdrom os.iso -m 512M
GRUB reads iso/boot/grub/grub.cfg, loads kernel.bin and the rootfs.bin module, and hands control to the start symbol in boot/boot.S. The kernel clears the screen, initializes all subsystems in order (GDT → IDT → PIC → timer → keyboard → mouse → VFS → services), and drops into the shell.You should see:
================================
        CrisOS Kernel
================================

[ OK ] Console initialized
[ OK ] PIC initialized (IRQs 0-15 remapped)
[ OK ] PIT timer initialized (100 Hz)
[ OK ] Keyboard initialized
[ OK ] Multiboot modules detected
[ INFO ] Mounting rootfs...
[ OK ] Rootfs mounted
[ OK ] VFS initialized
[ OK ] Boot manager initialized
[ OK ] Service manager initialized
[ OK ] LCP package manager initialized

[ASM] 7 + 5 = 12

Launching shell...

>
GDT and IDT are initialized silently before the PIC. No console output is produced for those two steps — they are confirmed working only if the system continues past the PIC initialization line without a fault.
5

Use the shell

Once the > prompt appears, you can issue commands. Here is a short interactive session demonstrating the built-in commands:
> help
Commands: help clear ls pwd cd mkdir rmdir rm touch
           cp mv cat grep echo uname whoami df stat panic
           reboot lcp systemctl bootctl gui asm calc
           kblayout mouse

> uname
CrisOS i386

> ls
README.txt
info.txt
lcp_repo.txt
bin
boot
share
systemd

> cat README.txt
Bienvenido a MiniOS.
Usa los comandos ls y cat para explorar archivos.

> asm add 42 58
= 100

> calc 3 + 4 * 2
= 11

> lcp search editor
editor-lite
nano-cris
textpad

> whoami
cris

> df
Filesystem  1K-blocks  Used  Avail  Mounted on
rootfs      64        8     56     /

​
Make Targets Reference

TargetWhat it does
makeCompiles all C and Assembly sources and links build/kernel.bin.
make isoBuilds the kernel, packs iso/boot/rootfs.bin from rootfs/, and copies build/kernel.bin to iso/boot/kernel.bin.
make echo-isoRuns make iso, then calls grub-mkrescue to produce os.iso.
make runRuns make echo-iso, then launches qemu-system-i386 -cdrom os.iso -m 512M.
make cleanRemoves build/, os.iso, iso/boot/kernel.bin, and iso/boot/rootfs.bin.

Build docs developers (and LLMs) love

Get started for freeTalk to us