A hobby x86-64 operating system written in C and Assembly. Doom runs in userland today; the long-term target is reliable boots on real hardware.

• Limine-based boot, SMP-ready kernel, and uACPI hardware discovery.
• Preemptive scheduler with fork/exec/wait, signals, shared memory, and fast syscalls.
• Virtual file system with FAT32 read/write, block cache, and /dev nodes (null, zero, tty0, fb0).
• Mosh interactive shell (history, completion, job control) plus a small /bin.
• doomgeneric port bundled as a userland game target.
• Vendored Tiny C Compiler (TCC) 0.9.24 under vendor/tcc-0.9.24/.
• Vendored GNU binutils 2.45 under vendor/binutils-2.45/ for native assembler/linker work.

• ✅ Run classic Doom in userland
• 🚀 Bring-up on real hardware (current long-term objective)
• 🎨 Complete graphical user interface with compositor and window manager (next major milestone)

An x86_64-elf cross-compiler is preferred; the build falls back to the host compiler when unavailable.

make binutils    # build the native binutils toolchain into build/bin/
make userland    # build libc and user programs only
make build       # build kernel + disk image (runs userland build when needed)
make run         # launch meniOS in QEMU
make check       # run cppcheck against kernel sources

To point at a custom toolchain:

export MENIOS_HOST_CC=/opt/cross/bin/x86_64-elf-gcc
export MENIOS_CROSS_PREFIX=x86_64-elf   # default prefix

MeniOS ships with a growing collection of userland utilities in /bin:

• mosh — Interactive shell with history, tab completion, and job control
• cat, echo, env, true, false — Standard POSIX utilities
• touch — Create files and update timestamps
• realpath — Canonicalize file paths
• head — Display first lines of files
• stat — Display detailed file metadata (validated)
• shutdown — Clean ACPI power-off (#372)

• as — GNU assembler (x86-64)
• ld — GNU linker
• objdump — Object file disassembler and analyzer
• nm — Symbol table viewer
• ar — Archive creator and manager
• ranlib — Archive index generator
• objcopy — Binary format translator
• strip — Binary symbol stripper
• strings — Extract ASCII strings from binaries
• size — Section size analyzer
• readelf — ELF header and section viewer

All binutils tools fully operational on meniOS!

# In meniOS shell (/bin/mosh)
cd /HOME

# Assemble, link, and inspect a binary
as --64 -o hello.o HELLO.S
ld -o hello hello.o
objdump -d hello
nm hello

# Create a static library
ar rcs libhello.a hello.o
ranlib libhello.a
nm libhello.a

# Analyze binaries
size hello
readelf -h hello
strings hello

The complete binutils 2.45 suite is fully operational on meniOS with native metadata support on tmpfs and FAT32. Core tools, including ar and ranlib, now preserve permissions when working in /tmp or FAT-based paths; read-only pseudo filesystems (/dev, /proc) continue to refuse metadata changes by design.

Implementation Details:

• Native syscalls: chmod/fchmod/utime implemented across tmpfs and FAT32 (pseudo-fs remain read-only and ignore metadata changes)
• FAT32 stat metadata now surfaces DOS attributes and timestamp fields (archived/hidden/system flags preserved)
• Host harness: Forwards metadata operations to host OS for cross-platform testing
• Printf formatting: Dynamic field width support (*) enables proper table display in size

Verification: Complete native validation sweep performed on 2025-10-29 confirmed all 11 tools working correctly.

See issue #191 (CLOSED) for the complete binutils integration documentation.

• Roadmaps — milestone breakdowns for shell, buddy allocator, GCC toolchain, Doom integration, GUI stack, and more.
  • docs/road/road_to_gui.md — complete GUI roadmap (Cairo, compositor, window manager, desktop environment)
• docs/tools.md — overview of the Menios toolchain wrapper scripts.
• docs/MILESTONES.md — high-level progress tracker.
• docs/architecture/code_structure.md — reference for the current kernel/userland layout and naming conventions.
• scheduler_issues.md — notes on ready-queue redesign.
• CONTRIBUTING.md & CODING.md — contribution workflow and style guide.

• make test — build and run the host Unity suite (uses Docker automatically on macOS).
• make coverage — rerun the suite with gcov instrumentation and write a summary to build/gcov/summary.txt.
• make coverage-report — regenerate the coverage summary from existing .gcda/.gcno data.
• Boot with make run after kernel, IPC, filesystem, or other low-level changes to catch runtime regressions that host tests will miss.

app/        user programs (doom helpers, shell utilities, demos)
build/      generated artifacts (kernel, userland, disk images, SDK)
docs/       architecture notes, roadmaps, design references
include/    exported kernel/libc headers (mirrors source hierarchy)
src/        kernel and shared libc sources
test/       Unity-based host tests and stubs
user/       libc runtime pieces (crt0, stdio glue) shared by apps
vendor/     third-party dependencies (uACPI, doomgeneric, binutils)
tools/      build helpers and automation scripts

Bug reports, documentation updates, and code patches are welcome. Start with the issues tagged good first issue or nice to have, and check tasks.json because it is the source of truth for tracked work. Keep C and assembly changes on the existing two-space, brace-on-same-line style, and update tests or docs when behavior changes. The full workflow lives in CONTRIBUTING.md and CODING.md. Please also review the Code of Conduct and Security Policy before submitting changes.

MeniOS is released under the MIT License. See LICENSE for details.

Key third-party components:

• Limine — modern x86-64 bootloader.
• uACPI — ACPI interpreter and tables.
• doomgeneric — portable Doom engine interface.

Special thanks to the broader OSDev community and everyone sharing documentation and tooling that make projects like this possible.