foundry

# Glossary: the words used in Foundry OS

| Word | What it means here |
|---|---|
| **kernel** | The program that owns the hardware: memory, CPUs, disks, network. Ours is **Rustbelt**, in its own repo. |
| **userland** | Everything that is not the kernel: the shell, `ls`, the C library. It runs in the CPU's unprivileged mode ("ring 3"). Foundry OS *is* a userland. |
| **syscall** | A request a program makes to the kernel ("open this file", "start this program"). Rustbelt uses Linux's syscall numbers, plus a few of its own (500-505). |
| **disk image** | A plain file holding every byte of a virtual hard disk. QEMU uses it as a disk. Ours is `out/foundry.img`. |
| **GPT** | The partition table at the start of the disk: it says where each partition starts and what it is for. Ours has one partition, at sector 2048 (1 MiB). |
| **FAT32 / ext2 / exFAT** | File system formats. FAT32 is what the image uses today (simple, no permissions or symlinks). ext2 is the Unix-style format we will move the OS to. exFAT is for sharing files with Windows/macOS. |
| **mtools** | Programs (`mcopy`, `mmd`) that write files *into* a FAT image file directly, so building the image needs no root and no mounting. |
| **QEMU** | A program that pretends to be a whole PC, so we can boot Rustbelt + Foundry OS without real hardware. "Headless" means no window: output goes to the terminal and a log. |
| **boot contract** | The short agreement between kernel and OS about what the disk image must contain: [boot-contract.md](boot-contract.md). |
| **pinned commit** | One exact version of the kernel (`KERNEL_REV` in `config.mk`). We build against it until we change it on purpose. |
| **`no_std`** | Rust without its standard library (no files, threads or `println!` from Rust itself). Our Rust programs bring their own small runtime, `rbrt`. |
| **Cargo workspace** | Several Rust packages built together with one `cargo build` and one `Cargo.lock` (`rust/Cargo.toml`). |
| **ELF** | The executable file format of Linux and Rustbelt. `ET_EXEC` = a program fixed at one address; `ET_DYN` = position-independent (a shared library or a PIE). |
| **static binary** | A program with everything it needs copied into the one file: no `.so` libraries, no dynamic loader at run time. Rustbelt has no dynamic loader, so all our programs are static. |
| **PIE / static-PIE** | **P**osition-**I**ndependent **E**xecutable: a program that can be loaded at any address. A *static-PIE* is static **and** position-independent: it fixes up its own addresses when it starts. Rustbelt 0.19.0 can load these, so C programs can be built with the ordinary `musl-gcc -static-pie` and no special link tricks (the old `rb-cc` wrapper is not needed any more). |
| **libc** | The C standard library (`printf`, `malloc`, `fopen`). It turns those calls into syscalls. |
| **musl** | A small, clean libc (Alpine Linux uses it). Easy to read, easy to link statically. Our C programs will use it. |
| **sysroot** | A folder that looks like the root of the *target* system as far as the compiler cares: `include/` (headers like `stdio.h`) and `lib/` (`libc.a`, start files `crt1.o`...). The compiler reads those instead of the build machine's own. `make musl` makes `out/sysroot`. |
| **cross toolchain** | A compiler setup that builds programs for a different system than the one it runs on (here: for Rustbelt, on Debian). |
| **tarball** | A `.tar.gz` archive of a project's source code, as released. We never commit them: they are downloaded into `cache/` and checked by **SHA256**, a fingerprint of the exact bytes. |
| **port** | Someone else's program (dash, busybox) adapted to build for our system: `ports/<name>/`. |
| **fixture** | A test program that checks the *kernel* (fork, signals, raw syscalls). The kernel repo owns them; they are not part of Foundry OS. |
| **git subtree split** | A git command that takes one folder of a repo (here the kernel's `user/`) and makes a new history containing only that folder, with all its old commits. We merged that history in here, so `git log --follow` still shows how each file grew. |
| **drive letters** | `A:`, `B:`... are **rbsh** syntax only (DOS style): `A:` = `/`, `B:` = `/mnt/disk0` (our disk), `C:`-`E:` = the other disks. The kernel knows nothing about them. |