mirror of
https://github.com/JannisHeydemann/BoredOS.git
synced 2026-05-30 02:16:58 +00:00
docs: update syscall reference and add installation guides
This commit is contained in:
boreddevnl
27
docs/installation/README.md
Normal file
27
docs/installation/README.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# BoredOS Installation
|
||||
|
||||
## Requirements
|
||||
|
||||
- Disk with at least **1 GB** (2,097,152 sectors)
|
||||
- UEFI firmware
|
||||
- A running BoredOS live environment (ISO)
|
||||
|
||||
## Quick Start (UEFI)
|
||||
|
||||
```
|
||||
boredos_install --uefi /dev/sda
|
||||
```
|
||||
|
||||
After installation, reboot and select the target disk from your firmware boot menu.
|
||||
|
||||
## Manual Steps
|
||||
|
||||
```
|
||||
fdisk /dev/sda
|
||||
mkfs_fat -F 32 -n EFI /dev/sda1
|
||||
mkfs_fat -F 32 -n BOREDOS /dev/sda2
|
||||
boredos_install --no-partition --no-format --uefi /dev/sda
|
||||
```
|
||||
|
||||
|
||||
See `install_guide.md` for a full walkthrough and `internals.md` for a deep dive into how the process works.
|
||||
73
docs/installation/advanced.md
Normal file
73
docs/installation/advanced.md
Normal file
@@ -0,0 +1,73 @@
|
||||
# Advanced Installation
|
||||
|
||||
## Skipping Steps
|
||||
|
||||
All major phases can be skipped independently:
|
||||
|
||||
```
|
||||
boredos_install --no-partition --no-format --uefi /dev/sda
|
||||
```
|
||||
|
||||
The destructive warning is only shown when `--no-partition` AND `--no-format` are both absent.
|
||||
|
||||
## `/mnt/boot` Operations
|
||||
|
||||
The installer mounts the ESP at `/mnt/boot` and unmounts it when finished.
|
||||
|
||||
## FAT32 Limitations
|
||||
|
||||
FAT32 does not support Unix file permissions, ownership, or timestamps. These attributes are **not** preserved during installation. This is expected and documented.
|
||||
|
||||
## Custom Device Names
|
||||
|
||||
Use `--esp-dev` and `--root-dev` to bypass auto-detection:
|
||||
|
||||
```
|
||||
boredos_install --uefi --esp-dev sda1 --root-dev sda2 /dev/sda --no-partition --no-format
|
||||
```
|
||||
|
||||
Provided device names are still validated via `sys_disk_get_info` before use.
|
||||
|
||||
### Step 1: Partitioning
|
||||
Run `fdisk` interactively on your target device.
|
||||
|
||||
```bash
|
||||
fdisk /dev/sda
|
||||
```
|
||||
|
||||
Inside the interactive shell:
|
||||
1. Type `n` to create a new partition (the ESP).
|
||||
2. Press Enter for the default start offset (1mb).
|
||||
3. Enter the size using suffixes like `b`, `mb`, or `gb` (e.g., `512mb` for a 512 MB ESP).
|
||||
4. Type `n` again for the second partition (the Root).
|
||||
5. Press Enter for the default start offset (aligned after the ESP).
|
||||
6. Press Enter for the default size (rest of the disk).
|
||||
7. Type `w` to write the partition table.
|
||||
8. Type 'Q' to quit.
|
||||
|
||||
> [!NOTE]
|
||||
> Interactive mode in `fdisk` currently creates standard partitions. When using `boredos_install` later, you may need to specify the ESP device manually with `--esp-dev sda1` if it isn't automatically detected as an EFI System Partition.
|
||||
|
||||
### Step 2: Formatting
|
||||
Initialize the partitions with FAT32. Use the labels `EFI` and `BOREDOS` to match the expected system layout.
|
||||
|
||||
```bash
|
||||
mkfs_fat -F 32 -n EFI /dev/sda1
|
||||
mkfs_fat -F 32 -n BOREDOS /dev/sda2
|
||||
```
|
||||
|
||||
### Step 3: Installation
|
||||
The easiest way to perform the file copy and bootloader setup is to use the installer in "copy only" mode. This ensures that hidden flags (like the root detection file) are placed correctly.
|
||||
|
||||
```bash
|
||||
boredos_install --no-partition --no-format --uefi --esp-dev sda1 /dev/sda
|
||||
```
|
||||
|
||||
#### What this step does:
|
||||
1. **Mounts** `/dev/sda2` to `/mnt` and `/dev/sda1` to `/mnt/boot`.
|
||||
2. **Identifies** the root by creating an empty file at `/mnt/Library/.boredos_root`.
|
||||
3. **Copies** the system structure: `/bin`, `/Library`, `/docs`, and `/root` are mirrored to `/mnt`.
|
||||
4. **Deploys** the kernel and initrd: `boredos.elf` and `initrd.tar` are copied to the ESP (`/mnt/boot/`).
|
||||
5. **Configures** Limine: Writes a `limine.conf` to the ESP and copies the EFI bootloader to `/mnt/boot/EFI/BOOT/BOOTX64.EFI`.
|
||||
|
||||
For a deep dive into why these steps are performed, see the [Installation Internals](internals.md) guide.
|
||||
31
docs/installation/install_guide.md
Normal file
31
docs/installation/install_guide.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Install Guide
|
||||
|
||||
## UEFI Installation
|
||||
|
||||
1. Boot from the BoredOS ISO.
|
||||
2. Run `boredos_install --uefi /dev/sda`.
|
||||
3. Type `y` when prompted and press Enter.
|
||||
4. After completion, reboot and select the disk.
|
||||
|
||||
## limine.conf Notes
|
||||
|
||||
**UEFI** uses `boot():/boredos.elf` — the `boot():` URL scheme refers to the EFI System Partition.
|
||||
|
||||
**Root selection** uses `root=/dev/<partition>` in `cmdline:` to choose the writable root partition (for example `root=/dev/sda2`).
|
||||
|
||||
**TOS acceptance** uses `--accept-tos` in `cmdline:` when you want to bypass the prompt.
|
||||
|
||||
**Live vs disk override** supports `--live` and `--disk` in `cmdline:`. Use `--live` for ISO/USB live boots and `--disk` for installed systems.
|
||||
|
||||
## Options
|
||||
|
||||
| Flag | Description |
|
||||
|---|---|
|
||||
| `--no-partition` | Skip fdisk (use existing partitions) |
|
||||
| `--no-format` | Skip mkfs (use existing filesystem) |
|
||||
| `--no-files` | Skip file copy |
|
||||
| `--no-bootloader` | Skip limine.conf and EFI file copy |
|
||||
| `--esp-size N` | ESP size in MB (default: 512) |
|
||||
| `--esp-dev DEV` | Explicit ESP device name |
|
||||
| `--root-dev DEV` | Explicit root device name |
|
||||
| `-y` | Auto-accept the destructive warning |
|
||||
57
docs/installation/internals.md
Normal file
57
docs/installation/internals.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# Installation Internals: How, Why, and What
|
||||
|
||||
This document explains the technical details of the BoredOS installation process, the design decisions behind it, and the resulting system layout.
|
||||
|
||||
## How the installation works
|
||||
|
||||
The BoredOS installation follows a strict five-phase sequence:
|
||||
|
||||
1. **Partitioning (GPT/MBR)**: The disk is prepared with a partition table. For UEFI systems, we use GPT (GUID Partition Table) and create at least two partitions: an EFI System Partition (ESP) and a data partition.
|
||||
2. **Formatting (FAT32)**: Both partitions are formatted with FAT32.
|
||||
- The ESP is labeled `EFI`.
|
||||
- The root partition is labeled `BOREDOS`.
|
||||
3. **Mounting & Flagging**: The root partition is mounted to `/mnt`. A special marker file is created at `/Library/.boredos_root`. This file is used by the kernel during boot to differentiate between a persistent disk and a live ISO/RAM disk.
|
||||
4. **System Mirroring**: The installer performs a recursive copy of the live system's essential including but not limited to:
|
||||
- `/bin`: All userland binaries.
|
||||
- `/Library`: System assets, fonts, icons, and configuration.
|
||||
- `/docs`: Documentation and manuals.
|
||||
- `/root`: The default user home directory.
|
||||
5. **Bootloader Setup**:
|
||||
- The ESP is mounted to `/mnt/boot`.
|
||||
- The kernel (`boredos.elf`) and the initial RAM disk (`initrd.tar`) are copied to the root of the ESP.
|
||||
- The Limine EFI binary is placed at `/EFI/BOOT/BOOTX64.EFI`.
|
||||
- A `limine.conf` is generated with the correct `root=/dev/sdXX` parameter.
|
||||
|
||||
## Why it works this way
|
||||
|
||||
### FAT32 for Everything
|
||||
BoredOS currently uses FAT32 as its primary filesystem for both the boot partition and the root partition.
|
||||
- **Universal Support**: FAT32 is natively understood by UEFI firmware, making it the only choice for the ESP.
|
||||
- **Simplicity**: By using FAT32 for the root partition as well, the kernel only needs one robust filesystem driver to handle both boot-time loading and runtime persistent storage.
|
||||
- **Interoperability**: You can easily mount BoredOS partitions on other operating systems (Windows, Linux, macOS) to transfer files.
|
||||
|
||||
### The ESP/Root Split
|
||||
Even though both use FAT32, we split the disk into two partitions to follow the UEFI specification. The ESP is meant to be small and strictly for bootloader files, while the root partition contains the entire userland. This separation allows for cleaner upgrades and multi-boot scenarios.
|
||||
|
||||
### Limine Bootloader
|
||||
We chose [Limine](https://limine-bootloader.org/) because of its excellent support for modern protocols, its simplicity in configuration, and its lightweight footprint. It handles the transition from UEFI/BIOS environment to the kernel seamlessly.
|
||||
|
||||
## What the installation does
|
||||
|
||||
After a successful installation, your disk will look like this:
|
||||
|
||||
### Partition 1: EFI System Partition (ESP)
|
||||
- `/boredos.elf`: The actual kernel binary.
|
||||
- `/initrd.tar`: The basic system image loaded into RAM at boot.
|
||||
- `/limine.conf`: The bootloader configuration.
|
||||
- `/EFI/BOOT/BOOTX64.EFI`: The bootloader entry point for UEFI firmware.
|
||||
|
||||
### Partition 2: BoredOS Root
|
||||
- `/bin/`: Executables.
|
||||
- `/Library/`: System data.
|
||||
- `.boredos_root`: Hidden marker file.
|
||||
- `fonts/`, `images/`, `man/`: System resources.
|
||||
- `/docs/`: System documentation.
|
||||
- `/root/`: Persistent user files.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user