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 three (contract v2): the ext2 root, the FAT32 data disk and the exFAT share. The old v1 image has one. |
| **FAT32 / ext2 / exFAT** | File system formats. ext2 is the Unix-style format of our root (A:: permissions, symlinks). FAT32 is the data disk (B:; simple, no permissions or symlinks). exFAT is the share (C:), the format of USB sticks and SD cards that Windows, macOS and Linux all read and write. |
| **partition** | One slice of a disk, used as if it were a disk of its own, with its own file system. The GPT says where each one is and its *type* (e.g. "Linux root"), which is how the kernel finds the root. |
| **mount** | Making a file system appear under a folder. The root partition is mounted at `/`, the share at `/mnt/share`. Drive letters (`A:`, `B:`, `C:`) are rbsh's shortcuts for these folders. |
| **root file system** | The file system mounted at `/`, holding the system itself (`/bin`, `/sbin`, `/etc`). Ours is ext2, drive `A:`. |
| **init / pid 1** | The first program the kernel starts (process number 1): ours is `/sbin/init` (rust/init). It starts the shells, starts a new one when one exits, and *reaps orphans*. |
| **orphan, reaping** | When a process exits, its parent must collect ("reap") its exit status with `wait`, or it lingers as a *zombie*. If the parent died first, the child is an *orphan*; the kernel hands it to init, which reaps it. |
| **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. |
| **sbase** | suckless's collection of small Unix tools (`sort`, `sed`, `find`...), one short C file each. Foundry OS ships it in `/usr/lib/sbase` (M4), off the default `PATH`; call a tool by its full path. Its sister project **ubase** has the Linux-only tools (`df`, `id`, `mount`). |
| **xfail** | "expected failure": a test for something we *know* doesn't work yet (e.g. a missing syscall). It is reported, not counted as a failure, and if it ever starts working the test says **XPASS** so we update the list. |
| **FIFO** (named pipe) | A pipe with a name in the file system, made by `mkfifo`: one program writes into it, another reads. Needs the `mknod` syscall. |
| **chroot** | "Change root": run a program so that it sees a chosen directory as `/`. Used for build sandboxes. |