# Porting a C program to Foundry OS

*Status: groundwork only (milestone M2 adds the first C programs to the image).*

## The toolchain

Rustbelt 0.19.0 loads **static-PIE** programs, so C programs need no special
tricks any more. With Debian's musl (`musl-tools`):

```sh
musl-gcc -O2 -static-pie c/hello-musl.c -o out/hello-musl
```

That makes an `ET_DYN` file with no `PT_INTERP`: a static-PIE. It runs on the
Linux host too, which is handy (configure scripts run their test programs).

The old `rb-cc` wrapper from the proposal (crt1.o, `-Ttext-segment`,
`--defsym=_DYNAMIC`, `--no-relax`) was only needed for `ET_EXEC` at
Rustbelt's high user base. Don't use it for new programs. The kernel keeps
one program built that way (`vdsotest`) as a loader test.

## Our own musl (`make musl`)

`make musl` downloads musl into `cache/` (SHA256-checked, see
`toolchain/musl/`) and installs a static-only musl into `out/sysroot`
(`include/`, `lib/libc.a`, the `crt*.o` start files, and a `bin/musl-gcc`
wrapper).

**Known gap (M2 to-do):** musl's own generated `musl-gcc` wrapper does not
handle `-static-pie`. Its specs file always adds the dynamic-loader path, so
the result gets a `PT_INTERP` and is refused. Debian's `musl-gcc` handles
this properly, so use that until `toolchain/musl/` ships its own
`musl-gcc.specs` (or a small `foundry-cc` wrapper) with the `static-pie` case.

## Adding a port

```
ports/<name>/<name>.sha256   "SHA256  <tarball>"
ports/<name>/<name>.url      where to download it
ports/<name>/patches/        0001-*.patch ...
ports/<name>/build.sh        unpack from cache/, patch, CC=musl-gcc ./configure --host=x86_64-linux-musl,
                             make, install into out/staging (busybox/sbase: under /usr/lib/busybox)
```

Then boot it (`make test` / `make run`), try it, and note any missing
syscall in [syscall-gaps.md](syscall-gaps.md). `run --trace prog` in rbsh
shows every syscall, and `syscall_N(...) = -38 ENOSYS` marks the ones
Rustbelt doesn't have.