foundry

@@ -53,7 +53,7 @@ foundry/ ├── rootfs/               files copied onto the disk as they are (readme, notes, the self-test) │   └── etc/              passwd, hosts... for the later ext2 root (not in the image yet) ├── toolchain/           foundry-cc (gcc + musl, static-PIE); musl/ pinned by SHA256, downloaded into cache/-├── c/                    our own C programs (M2)+├── c/                    our own C programs: hello-musl, fprobe (the libc self-check) ├── ports/                other people's C programs, one directory each (dash first) ├── scripts/              mkimage, build-kernel, run-qemu, run-headless, compare-image... ├── docs/                 how it all fits together (start with docs/glossary.md)

@@ -59,6 +59,8 @@ there, with its own target dir (`out/kernel-target`). - `scripts/run-headless.sh` gets `KERNEL_BANNER`, `KERNEL_VERSION` and   `BIN_COUNT` (the `dir bin | wc -l` result) from the Makefile, so the   expected lines don't need hand edits for a plain version bump.+- `scripts/expect-foundry.txt`: Foundry OS's own expected lines; it may use+  `@KERNEL_VERSION@`.  ## History of bumps 

@@ -37,7 +37,7 @@ Inside the ext2 root: |---|---|---| | **M1** | Foundry OS builds the same image; the kernel's self-test passes on it | **done**: `make test` passes; `make compare` shows the same 44 programs (47 since the 0.20.0 pin) and identical non-program files | | M1b | `rbrt` becomes a real library crate; rbsh's parser tests run on the host | next |-| M2 | musl hello + probes in `/bin`, built with plain `musl-gcc -static-pie` | the toolchain pieces exist (`make musl`, `c/hello-musl.c`) |+| **M2** | musl hello + probes in `/bin`, built static-PIE with `toolchain/foundry-cc` | **done**: `hello-musl` and `fprobe` (40 checks incl. timerfd) in `/bin`, checked by `make test` | | M3 | dash as `/bin/sh`, ext2 root (contract v2), Rust `/sbin/init` | needs kernel K5 | | M4 | sbase tools | needs testing per tool (docs/syscall-gaps.md) | | M5 | busybox in `/usr/lib/busybox` | `bzip2` for the tarball |

@@ -1,10 +1,10 @@ # Porting a C program to Foundry OS -*Status: groundwork only (milestone M2 adds the first C programs to the image).*+*Status: milestone M2. `hello-musl` and `fprobe` (in `c/`) are built this way, live in `/bin`, and `make test` checks their output.*  ## The toolchain -Rustbelt 0.19.0 loads **static-PIE** programs (`ET_DYN` with no+Rustbelt (since 0.19.0) loads **static-PIE** programs (`ET_DYN` with no `PT_INTERP`), so C programs need no special link tricks any more. Every C program and port is built as a static-PIE: @@ -32,9 +32,46 @@ The binaries also run on the Linux host, which is handy because configure scripts run their test programs.  The old `rb-cc` wrapper from the proposal (crt1.o, `-Ttext-segment`,-`--defsym=_DYNAMIC`, `--no-relax`, for `ET_EXEC` at Rustbelt's high user-base) is retired. The kernel keeps one program built that way (`vdsotest`)-as a loader test.+`--defsym=_DYNAMIC`, `--no-relax`, for `ET_EXEC` at Rustbelt's old high+user base) is retired.++### Plain `-static` (ET_EXEC) works too, since 0.20.0, but we don't use it++Rustbelt 0.20.0 moved user space down to start at `0x40_0000`, so an+ordinary `gcc -static` / `musl-gcc -static` program (an `ET_EXEC` fixed at+`0x400000`) runs as it is. Checked on 2026-10-31 with a one-off image+(not part of `make test`):++```+hello-exec  (Debian musl-gcc -O2 -static)                       ET_EXEC, entry 0x4010c8, no INTERP+hello-exec2 (gcc -specs out/sysroot/lib/musl-pie.specs -static -no-pie)  same+A:/ $ hello-exec+hello from musl on Rustbelt 0.20.0 (Foundry OS, ET_EXEC)+A:/ $ hello-exec2+hello from musl on Rustbelt 0.20.0 (Foundry OS, ET_EXEC)+```++Foundry OS still builds everything as **static-PIE**: it works on 0.19.0+and later, gets a random load address, and doesn't depend on where the+kernel puts user space. Treat ET_EXEC as "good to know" (e.g. a+third-party binary you can't rebuild), not something to rely on. The+kernel tests it with its own fixtures (`exechello`, `execthreads`,+`timerfdtest`).++## Our own C programs (c/)++```+c/hello-musl.c   one line: "hello from musl on Rustbelt 0.20.0 (Foundry OS, static-PIE)"+c/fprobe.c       the libc self-check: 40 checks, "fprobe: all 40 checks passed"+```++To add one: write `c/NAME.c`, add `NAME` to `FOUNDRY_C` in `config.mk`,+run it from the "Foundry OS" block at the end of+`rootfs/scripts/selftest.sh`, and add the lines it must print to+`scripts/expect-foundry.txt`. `make test` then builds it (`make cprogs`,+with `toolchain/foundry-cc`), puts it in `/bin`, boots, and checks.+If you add or remove a check in `fprobe`, update the count in+`expect-foundry.txt` too.  ## Adding a port