update docs

docs/developer/glossary.md

@@ -0,0 +1,55 @@
+# Glossary
+
+Development reference and historical context. For current operating instructions, use the [user manual](../README.md). Acceptance applies only to the source and artifacts identified in each record.
+
+
+[Documentation index](README.md)
+
+| Term | Meaning in this repository |
+| --- | --- |
+| **M0** | Milestone zero: prepare and verify the workstation's cross-build environment. M1 adds the rootfs; M2 adds native init and ARM VM boot. |
+| **Host / build workstation** | The x86_64 Arch Linux computer running the build. |
+| **Target** | The platform being built for: AArch64 Linux on the Pi. |
+| **x86_64** | The processor architecture of the supported build workstation. |
+| **AArch64 / aarch64 / arm64** | Names commonly used for 64-bit ARM. Void uses `aarch64` for its glibc package target. |
+| **Cross-compilation** | Compiling on one platform to produce code for another. An x86_64 build can produce an ARM executable that does not run directly on its host. |
+| **Toolchain** | Compiler, linker, and related tools used to build software. |
+| **Sysroot** | Target headers and libraries made available to a cross compiler. It is not necessarily a bootable filesystem. |
+| **ABI** | Application binary interface: the machine-level conventions that compiled programs and libraries must agree on. Matching CPU architecture alone is insufficient. |
+| **libc** | The C runtime library. FDS uses glibc for conventional packages and musl inside its static Rust tools. |
+| **glibc** | GNU's C library, used by the main FDS userspace and Void `aarch64` packages. |
+| **musl** | An alternative C library used for static FDS-owned programs. It does not replace the system's glibc package set. |
+| **Static linking** | Including needed library code in an executable at build time, so it does not need those shared libraries at startup. It still needs the operating system/kernel. |
+| **Dynamic linking / loader** | Loading shared libraries when a program starts. The ARM glibc loader is `/lib/ld-linux-aarch64.so.1`. |
+| **ELF** | The executable/library file format inspected by `file` and `readelf`. The validator checks architecture and runtime requirements. |
+| **Rust target triple** | A name such as `aarch64-unknown-linux-musl` specifying the compiler's target platform and library environment. |
+| **Cargo / Rustup** | Cargo builds Rust projects; Rustup installs/selects Rust toolchains and target components. |
+| **QEMU user mode** | Executes a foreign-architecture Linux program on the host. It does not boot or emulate the entire Pi in the M0 example. |
+| **XBPS** | Void's package-management tools and package format, reused by FDS. It is separate from Arch's pacman. |
+| **xbps-src** | Void's source-package build system. It creates packages using recipes called templates. |
+| **Template** | An xbps-src package recipe describing source, dependencies, build actions, and packaging. |
+| **Submodule / gitlink** | A separate Git repository embedded at a path; the parent records the exact upstream commit it expects. |
+| **Pin** | An explicit version, commit, or digest chosen for an input. A source pin alone does not freeze every downloaded dependency. |
+| **Overlay** | An FDS-owned package directory copied into the build tree without modifying tracked upstream packages. |
+| **masterdir** | The generated Void build-container filesystem under `vendor/void-packages/masterdir-x86_64/`. This is not the target OS root. |
+| **hostdir** | xbps-src's generated cache/output directory under `vendor/void-packages/hostdir/`. |
+| **bubblewrap / bwrap** | The host tool used to isolate the build environment with Linux namespaces and mounts. No target init system runs inside this M0 container. |
+| **Manifest** | A generated record of package versions or file checksums used to inspect a particular build. |
+| **Rootfs** | The root filesystem used by a running OS, including programs, libraries, and configuration. `make rootfs` builds its archive. |
+| **Initramfs** | A small early userspace filesystem loaded with the kernel, used before switching to the main root filesystem. |
+| **PID 1 / init** | The first userspace process and the foundation of system startup, supervision, and shutdown. FDS uses native s6. |
+| **s6 / s6-rc** | FDS's process-supervision and service-dependency tools. The service database is compiled while building the image. |
+| **EROFS** | The read-only filesystem format used for SYSTEM and recovery images. |
+| **tmpfs** | A memory-backed filesystem for temporary state. Its contents do not persist through power loss. |
+| **GPT / PARTNAME** | Disk partition metadata and a partition's name. Stage0 discovers SYSTEM using `FDS_SYSTEM`, rather than a changing `/dev/sdX` name. |
+| **NVMe** | The internal solid-state storage interface/device. The FDS internal image holds boot, recovery, and machine configuration. |
+| **SYSTEM / DATA** | Cartridge roles: operating-system image and persistent user files, respectively. |
+| **PROGRAM / ENVIRONMENT** | Cartridge roles: application payload and activation/configuration of a known environment. |
+| **Bay topology** | Mapping a physical USB hub/port path to the user-facing BAY 01–12 labels. |
+| **Hotplug** | Inserting or removing a device while the machine is running. Detection does not by itself make removal safe. |
+| **sysfs / netlink** | Linux interfaces used by FDS to inspect devices and receive cartridge events. |
+| **Profile** | A known OS configuration or service selection activated by a cartridge. It is not an arbitrary root script supplied by media. |
+| **Safe eject** | Stopping users of a cartridge, flushing pending writes, unmounting it, then reporting it safe to remove. Use `fds eject BAY`. |
+
+For how these pieces fit together, read [Architecture](architecture.md). For
+commands that currently work, follow [Your first build](getting-started.md).