> ## Documentation Index > Fetch the complete documentation index at: https://kernel.mvhcloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Building MVH Kernel from Source: Flags and Targets > Step-by-step guide to compiling MVH Kernel. Covers toolchain requirements, build flags, output artifacts, and the Makefile targets. MVH Kernel compiles from a single, self-contained `Makefile` with no external build system, no package manager, and no generated configuration. You need a standard x86\_64 GCC toolchain and GNU Make. This page covers every compiler flag the build uses, all Makefile targets, the output artifacts you will find after a successful build, and notes on behaviours you need to be aware of during development. ## Toolchain requirements | Tool | Minimum requirement | Notes | | ------------ | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **GCC** | Any version with x86\_64 and freestanding support | Use `x86_64-elf-gcc` for a dedicated cross-compiler, or a native `gcc` with multilib (`-m64` support). The `CC` variable in the Makefile defaults to `gcc`. | | **GNU ld** | Any version supporting `elf_x86_64` emulation | Supplied by GNU Binutils. The `LD` variable defaults to `ld`. The linker is invoked with `-m elf_x86_64 -nostdlib`. | | **GNU Make** | Any modern version | No features beyond standard POSIX make are used. | If your host system's native `gcc` does not support `-m64` (for example, on a 32-bit host), install a `x86_64-elf` cross-compiler and set the `CC` variable when invoking make: ```bash theme={null} make CC=x86_64-elf-gcc LD=x86_64-elf-ld ``` ## Building the kernel Run `make` from the repository root: ```bash theme={null} make ``` The build system creates the `build/` directory if it does not exist, compiles each source module into a `.o` object file, then links everything with `linker.ld` into the final kernel binary. ## Makefile targets | Target | Command | Description | | ----------------- | ------------ | ----------------------------------------------------------------- | | **all** (default) | `make` | Compiles all modules and produces `build/kernel.elf`. | | **clean** | `make clean` | Removes the entire `build/` directory and all compiled artefacts. | ```bash theme={null} # Build the kernel make # Remove all build artefacts make clean ``` ## Compiler flags The Makefile applies the following `CFLAGS` to every C source file in the kernel: ```makefile theme={null} CFLAGS := -m64 -mno-red-zone -std=c11 -ffreestanding -fno-pie -fno-stack-protector \ -fno-builtin -fno-unwind-tables -fno-asynchronous-unwind-tables \ -fno-omit-frame-pointer -Wall -Wextra -Werror -O2 -Iinclude ``` The table below explains each flag and why it is required: | Flag | Purpose | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-m64` | Target the x86\_64 (64-bit) instruction set. | | `-mno-red-zone` | Disable the 128-byte red zone below the stack pointer. Required for kernel code because hardware interrupts do not respect the red zone and will corrupt it. | | `-std=c11` | Compile against the C11 standard. | | `-ffreestanding` | Declare a freestanding environment — no libc, no hosted runtime. The compiler will not assume the presence of `main`, `printf`, or any standard library function. | | `-fno-pie` | Do not generate position-independent executable code. The kernel is linked at a fixed physical address (`0x200000`) and must not use GOT/PLT relocations. | | `-fno-stack-protector` | Disable stack canary instrumentation. Stack protector requires a `__stack_chk_guard` symbol provided by libc, which is not available in this freestanding environment. | | `-fno-builtin` | Prevent GCC from substituting calls to standard library builtins (e.g., replacing a loop with `memset`). The kernel provides its own memory routines. | | `-fno-unwind-tables` / `-fno-asynchronous-unwind-tables` | Suppress `.eh_frame` and `.eh_frame_hdr` generation. Unwinding tables are unused in the kernel and add unnecessary size. | | `-fno-omit-frame-pointer` | **Required.** Preserve the frame pointer (`rbp`) in every function. MVH Kernel's panic handler walks the `rbp` chain to produce a bounded stack trace. Omitting frame pointers would break crash diagnostics. | | `-Wall -Wextra -Werror` | Enable all standard and extra warnings and treat every warning as a build error. The kernel must compile cleanly with no suppressed warnings. | | `-O2` | Enable level-2 optimisation. Produces faster, smaller code while remaining compatible with the other flags above. | | `-Iinclude` | Add the `include/` directory to the compiler's header search path so all `#include ` headers resolve correctly. | Assembly source files (`entry64.S` and `interrupt64.S`) are assembled with only `-m64 -c` — the full `CFLAGS` are not applied to assembly. ## Output artifacts A successful `make` produces a single output file: | Artifact | Path | Description | | ----------------- | ------------------ | ------------------------------------------------------------------------------------ | | **Kernel binary** | `build/kernel.elf` | ELF64 binary for x86\_64. This is the only file you need to pass to your bootloader. | MVH Kernel does not include a bootloader. `build/kernel.elf` is the kernel binary only. You must load it with your own bootloader that enters x86\_64 Long Mode, identity-maps the first GiB of physical memory, and jumps to `_kernel64_start`. See the [Quickstart](/quickstart) for integration instructions. You can inspect the output binary with standard ELF tools: ```bash theme={null} # Verify the ELF format and architecture file build/kernel.elf # Inspect section layout and sizes objdump -h build/kernel.elf # Print the entry point address readelf -h build/kernel.elf | grep Entry ``` ## Entry point The kernel entry point is `_kernel64_start`, defined in `src/entry64.S` and declared as the ELF entry in `linker.ld`: ```asm theme={null} ENTRY(_kernel64_start) ``` The kernel is linked at a base address of `0x200000` (2 MiB). The linker script arranges sections in the following order: | Section | Alignment | Permissions | | --------- | --------- | -------------------------------------------- | | `.text` | 4 KiB | Read, Execute | | `.rodata` | 4 KiB | Read only | | `.data` | 4 KiB | Read, Write | | `.bss` | 4 KiB | Read, Write (zero-initialised by entry stub) | The `.text.entry` section — containing `_kernel64_start` — is kept first within `.text` via a `KEEP` directive so the entry point always lands at the lowest address in the binary. ## Kernel modules compiled The Makefile compiles the following modules into the final binary: ```text Architecture & Entry theme={null} entry64.S — 64-bit entry point and halt loop interrupt64.S — Low-level interrupt stubs arch/interrupt.c — IDT, PIC remapping, interrupt dispatch ``` ```text Core theme={null} core/log.c — Kernel log ring buffer core/panic.c — Panic handler with register dump and stack trace core/sync.c — Atomics, spinlocks, mutexes ``` ```text Hardware Abstraction theme={null} hal/hal.c — Hardware abstraction layer ``` ```text Memory theme={null} memory/pmm.c — Physical page allocator memory/vmm.c — Virtual memory manager and page mapping memory/heap.c — Coalescing kernel heap ``` ```text Drivers theme={null} drivers/vga.c — VGA text-mode driver drivers/serial.c — 16550 UART serial driver drivers/keyboard.c — PS/2 keyboard driver (EN-US) drivers/cpu.c — CPUID and CPU diagnostics drivers/rtc.c — CMOS real-time clock drivers/pci.c — PCI configuration space driver drivers/timer.c — PIT 8254 system timer ``` ```text Filesystem theme={null} fs/ramfs.c — Volatile RAM filesystem fs/vfs.c — Virtual filesystem boundary ``` ```text Device & Task theme={null} device/device.c — Device manager registry task/task.c — Kernel task registry kernel.c — kernel_main and interactive shell ``` ## Notes on faulttest The `faulttest` and `faulttest page` shell commands **intentionally halt the kernel**. `faulttest` triggers an exception without a CPU error code to validate the exception-dispatch path. `faulttest page` triggers a page fault to validate CR2 reporting and page-fault error-code decoding. Do not run either command in a production or integration environment unless you intend to test panic handling and are prepared for the system to stop.