DOCS

docs/build/toolchain.md

@@ -0,0 +1,52 @@
+# Build Toolchain
+
+BoredOS is built cross-compiled from a host system (such as macOS or Linux) to target the generic `x86_64-elf` platform.
+
+## Prerequisites
+
+To build BoredOS, you need the following tools:
+
+1.  **x86_64 ELF GCC Cross-Compiler**:
+    -   `x86_64-elf-gcc`: The C compiler targeting the freestanding overarching ELF environment.
+    -   `x86_64-elf-ld`: The linker to combine object files into the final `boredos.elf` kernel binary and userland variables.
+
+2.  **NASM**:
+    -   Required to compile the `.asm` files in `src/arch/` and `src/userland/crt0.asm`. It formats the output as `elf64` objects to be linked alongside the C code.
+
+3.  **xorriso**:
+    -   A specialized tool to create ISO 9660 filesystem images.
+    -   *Why?* `xorriso` packages the compiled kernel, Limine bootloader, and asset files (fonts, images, userland binaries) into the final bootable `boredos.iso` CD-ROM image.
+
+4.  **QEMU** (Optional but highly recommended for testing):
+    -   `qemu-system-x86_64` is used for rapid emulation and testing.
+
+## Installation (macOS)
+
+You can easily install the complete toolchain using Homebrew:
+
+```sh
+brew install x86_64-elf-binutils x86_64-elf-gcc nasm xorriso qemu
+```
+
+## Installation (Linux)
+
+Depending on your distribution, the installation commands vary. Note that some distributions may require you to build the `x86_64-elf` cross-compiler from source if it isn't available in their default repositories.
+
+### Debian / Ubuntu
+```sh
+sudo apt update
+sudo apt install build-essential bison flex libgmp3-dev libmpc-dev libmpfr-dev texinfo nasm xorriso qemu-system-x86
+```
+*(Note: You will need to build the `x86_64-elf` cross-compiler from source or find a compatible PPA, as it is not in the default Debian/Ubuntu repositories.)*
+
+### Arch Linux
+Arch Linux provides the regular tools in its standard repositories and the cross-compiler via the AUR:
+```sh
+sudo pacman -S nasm xorriso qemu-full
+yay -S x86_64-elf-gcc x86_64-elf-binutils
+```
+
+### Fedora
+```sh
+sudo dnf install make gcc gcc-c++ bison flex gmp-devel mpfr-devel libmpc-devel texinfo nasm xorriso qemu
+```

docs/build/usage.md

@@ -0,0 +1,58 @@
+# Building, Running, and Deployment
+
+BoredOS uses a single top-level `Makefile` to orchestrate the build process.
+
+## The Build Process
+
+When you run `make` in the root directory, the following stages occur automatically:
+
+1.  **Limine Setup (`limine-setup`)**:
+    If the Limine bootloader binaries are missing, the Makefile automatically clones the appropriate Limine binary release from GitHub and compiles its host utility.
+2.  **Kernel Compilation**:
+    All `.c` files in `src/core`, `src/mem`, `src/dev`, `src/sys`, `src/fs`, `src/wm`, and `src/net` are compiled into object files (`.o`) inside the `build/` directory using `x86_64-elf-gcc`.
+3.  **Kernel Assembly**:
+    All `.asm` files in `src/arch/` are assembled into object files using `nasm`.
+4.  **Kernel Linking**:
+    `x86_64-elf-ld` links the kernel object files together, instructed by the `linker.ld` script, outputting the `boredos.elf` kernel binary.
+5.  **Userland Compilation**:
+    The Makefile shifts into the `src/userland` directory, compiling the custom `libc` and generating `bin/*.elf` executable user applications.
+6.  **ISO Generation**:
+    The `iso_root` directory is staged. The kernel, Limine configuration, fonts, images, and userland applications are copied in. Finally, `xorriso` generates the `boredos.iso` bootable image.
+
+## Minimum System Requirements
+
+To run BoredOS successfully (either in emulation or on bare metal), your target machine should meet the following minimum requirements:
+
+-   **CPU**: An `x86_64` (64-bit) compatible processor.
+-   **Memory**: Approximately `~256 MB` of RAM.
+-   **Display**: A VGA-compatible display (required for the GUI Window Manager).
+-   **Networking (Optional)**: A compatible Network Interface Card (NIC) is required if you want to use the networking stack (e.g., an Intel E1000 or similar supported by the `net/nic/` drivers). Networking is not strictly required for the OS to boot or run offline applications.
+
+
+## Running in Emulation
+
+To test the generated ISO quickly without real hardware, use the QEMU emulator:
+
+```sh
+make run
+```
+
+This command invokes QEMU with specific arguments:
+-   `-m 4G`: Allocates 4 Gigabytes of RAM.
+-   `-cdrom boredos.iso`: Mounts the built OS image as a CD-ROM.
+-   `-netdev user...`: Sets up a basic NAT network interface for the OS's networking stack.
+-   `-smp 4`: Enables 4 CPU cores.
+-   `-drive file=disk.img...`: Attaches a raw disk image included in this release of BoredOS.
+
+## Running on Bare Metal
+
+> [CAUTION]
+> Running hobby operating systems on real hardware is at your own risk and may cause undefined behavior.
+
+To boot BoredOS on a physical PC:
+
+1.  Build the OS to get `boredos.iso`.
+2.  Use a flashing tool like **Balena Etcher** or `dd` to write the ISO to a USB flash drive.
+3.  Reboot your target computer, enter the BIOS/UEFI setup.
+4.  **Boot Configuration**: BoredOS supports booting on both modern **UEFI** systems and legacy **BIOS** systems natively via Limine. Ensure **Secure Boot** is disabled in your firmware settings.
+5.  Select the USB drive from the boot menu.