MontaukOS/toolchain/README.md

# MontaukOS Toolchains

Two cross toolchains live here, both installed to `toolchain/local/`:

| Script | Triple | Purpose |
|--------|--------|---------|
| `build-toolchain.sh` | `x86_64-elf` | Bare-metal compiler for the kernel |
| `build-montauk-toolchain.sh` | `x86_64-montauk` | OS-aware compiler for userspace programs |

Both use Binutils 2.43.1 + GCC 14.2.0 and share the source trees in
`src/`. The Montauk target is added by the patches in `patches/` plus
the target header `files/montauk.h` (installed as
`gcc/config/montauk.h` in the GCC tree).

## The x86_64-montauk target

`x86_64-montauk-gcc` knows the Montauk userspace ABI, so a hosted
program builds with no special flags:

```bash
toolchain/local/bin/x86_64-montauk-gcc hello.c -o hello.elf
```

What the target does by default:

- Links static, non-PIE `ET_EXEC` binaries (what the kernel ELF loader
  in `kernel/src/Sched/ElfLoader.cpp` accepts), text at 0x400000.
- `-z max-page-size=0x1000` — the loader maps 4 KiB pages; the x86-64
  default of 2 MiB segment alignment would bloat every binary.
- Startup/link line: `crt1.o crti.o crtbegin.o ... -lc crtend.o crtn.o`
  taken from the sysroot (`toolchain/sysroot/usr/lib`), which is
  assembled from `programs/lib/libc` by the build script.
- Headers resolve against the sysroot (`toolchain/sysroot/usr/include`),
  assembled from `programs/include/libc` plus the `montauk/` SDK
  headers. `#include <stdio.h>` just works; no `-nostdinc` needed.
- `-mno-red-zone` (the project-wide userspace convention). Standard
  hard-float SysV ABI otherwise; pass `-mno-sse` etc. per program if
  wanted.
- Defines `__montauk__` / `__MONTAUK__`.

The in-tree programs are built `-fno-exceptions -fno-rtti` (the project
convention), but that is a project style choice, not a toolchain limit —
see the STL section below.

## C++ standard library (hosted libstdc++)

`build-montauk-toolchain.sh` builds and installs a **hosted** libstdc++
(`all-target-libstdc++-v3`), so the full STL is available to
`x86_64-montauk-g++` with no special flags:

```bash
toolchain/local/bin/x86_64-montauk-g++ app.cpp -o app.elf
```

Headers live in `toolchain/local/x86_64-montauk/include/c++/14.2.0/`,
the library in `toolchain/local/x86_64-montauk/lib/libstdc++.a`.
`_GLIBCXX_HOSTED` follows `__STDC_HOSTED__`, i.e. 1 for ordinary
compiles.

Note that `toolchain/sysroot/usr/include/` *also* holds a freestanding
C++ subset (copied from `kernel/freestnd-cxx-hdrs`, which is what the
kernel and the in-tree programs build against). That directory is last
on the include search path, so for a plain `g++` invocation the hosted
headers win and the freestanding copies are shadowed. Check
`g++ -x c++ -E -v -` if you ever need to confirm the order.

### What works

Link-verified with the cross compiler, no flags beyond the source file:

| Feature | Status |
|---------|--------|
| `<string>`, `<vector>`, `<map>`, `<algorithm>` | works |
| `<memory>` (`unique_ptr`, `shared_ptr`, `make_*`) | works |
| Exceptions (`throw` / `catch`, `std::exception`) | works |
| RTTI (`typeid`, `dynamic_cast`) | works |
| `<iostream>`, `<sstream>` | works (links a large binary — see below) |
| Static constructors | works (`crt1.c` runs `.init_array`) |

`toolchain/files/cxx-test.cpp` is the on-OS regression check for this;
`make devkit` compiles it to `0:/sdk/bin/cxx-test.elf`. Run it on the
target to confirm the above at **runtime** rather than just at link
time — that is the authoritative check, since a clean link does not by
itself prove exception unwinding works on hardware.

### What does not work

- **Threads.** libstdc++ is built `gthr-single`
  (`_GLIBCXX_HAS_GTHREADS` is undefined), because the libc has no
  pthreads. `std::thread`, `std::mutex`, `std::condition_variable`,
  `std::async` and `std::call_once` do not exist — code using them
  fails to *compile*, not to link.

  Consequence worth knowing: in single-threaded mode libstdc++ selects
  the **non-atomic** `shared_ptr` refcount path. The kernel does have
  real threads (`SYS_THREAD_SPAWN/EXIT/JOIN/SELF`,
  `programs/include/montauk/thread.h`), so it is possible to spawn
  threads and share a `shared_ptr` across them — that will corrupt the
  refcount and is a silent use-after-free. Do not do it until a
  pthreads/gthreads shim exists and libstdc++ is rebuilt against it.

- **`<iostream>` is expensive.** It drags in the static locale and
  iostream init machinery; a hello-world using it links to roughly
  5.7 MB versus ~1.8 MB for `<string>` + `<vector>`. Prefer `<cstdio>`
  where binary size matters, which on a ramdisk image is most places.

- **`libm.a` is an empty stand-in.** The math functions live inside
  `libc.a` (the g++ driver links `-lm` unconditionally, hence the empty
  archive). Roughly 50 functions are present — `sqrt`, `sin`, `cos`,
  `pow`, `log`, `exp`, `atan2`, `hypot`, `floor`, `ceil`, `fmod`,
  `round` and some `float` variants. Absent: `fma`, `cbrt`, `expm1`,
  `log1p`, `erf`, `tgamma`, `nearbyint`, `remquo`, most remaining
  `float` variants, and all `long double` variants. Ports that need
  these have to add them to `programs/lib/libc/libc.c`.

## Refreshing the sysroot

The sysroot is rebuilt every time `build-montauk-toolchain.sh` runs
(the compiler build steps are skipped once installed). After changing
libc headers or the libc itself, re-run the script to refresh it.

## Layout

```
toolchain/
  build-toolchain.sh           # bare-metal x86_64-elf (kernel)
  build-montauk-toolchain.sh   # x86_64-montauk (userspace)
  patches/                     # Montauk target patches (checked in)
  files/montauk.h              # GCC target header (checked in)
  src/                         # downloaded + patched sources (ignored)
  build/                       # build trees (ignored)
  local/                       # install prefix (ignored)
  sysroot/                     # generated target sysroot (ignored)
```

## Native binutils (runs on MontaukOS)

The whole native SDK (binutils + GCC below, staged for the OS image) is
built by one idempotent script — this is what a fresh clone should run:

```bash
make sdk          # from the repo root; wraps toolchain/build-native-sdk.sh
```

It invokes build-montauk-toolchain.sh first (cross compiler + sysroot),
applies the host-build fix-ups listed under "Host-build gotchas", and
strips the staged binaries. To force a rebuild after libc changes:
`rm -rf toolchain/native toolchain/native-gcc toolchain/build/binutils-native
toolchain/build/gcc-native` and re-run. The manual steps below are kept
as a reference for what the script does.

Binutils can be cross-compiled to run *on* MontaukOS itself
(`--host=x86_64-montauk`), the first step toward a self-hosted GCC:

```bash
mkdir -p toolchain/build/binutils-native && cd toolchain/build/binutils-native
export PATH=$PWD/../../local/bin:$PATH
../../src/binutils-2.43.1/configure \
    --build=x86_64-pc-linux-gnu --host=x86_64-montauk \
    --target=x86_64-montauk --prefix=/sdk \
    --disable-nls --disable-werror --disable-gprofng --disable-gold \
    --disable-plugins --disable-shared --enable-static
make -j$(nproc) all-gas all-ld all-binutils
make install-strip-gas install-strip-ld install-strip-binutils \
    DESTDIR=$PWD/../../native
```

## Native GCC (runs on MontaukOS)

GCC itself cross-builds for the montauk host (build dir
toolchain/build/gcc-native, install DESTDIR toolchain/native-gcc):

```bash
../../src/gcc-14.2.0/configure \
    --build=x86_64-pc-linux-gnu --host=x86_64-montauk \
    --target=x86_64-montauk --prefix=/sdk \
    --with-native-system-header-dir=/sdk/include \
    --with-build-sysroot=$PWD/../../sysroot \
    --enable-languages=c,c++ --disable-nls --disable-shared \
    --disable-multilib --disable-gcov --disable-lto --disable-plugin \
    --disable-bootstrap --disable-fixincludes --with-newlib \
    --enable-initfini-array --disable-wchar_t --disable-libstdcxx-pch \
    --with-gnu-as --with-gnu-ld
ac_cv_c_bigendian=no make -j$(nproc) all-gcc
make install-gcc DESTDIR=$PWD/../../native-gcc
```

Host-build gotchas, in the order they bite:
- The bundled gmp/mpfr/mpc/isl/gettext carry their own config.sub
  copies; overwrite each with the patched top-level one.
- Remove the src tree's gettext symlink (--disable-nls does not skip
  it, and its gnulib needs more locale surface than the libc has).
- gmp.h sniffs the libc's stdio include-guard name to detect FILE;
  the Montauk stdio.h defines the conventional _STDIO_H marker.
- The gcc subdir configure cannot run host binaries to probe
  endianness; preset ac_cv_c_bigendian=no.
- The build sysroot needs an sdk -> usr symlink so
  --with-native-system-header-dir=/sdk/include resolves at build time.

The devkit target ships gcc/g++/cpp as .elf in 0:/sdk/bin, cc1 +
cc1plus + collect2 (and a copy of ld for collect2's search) under
0:/sdk/libexec/gcc/x86_64-montauk/14.2.0, libgcc.a + crtbegin/crtend
under 0:/sdk/lib/gcc/x86_64-montauk/14.2.0, and a 0:/tmp scratch dir
for driver intermediates.

Notes:
- Build only `all-gas all-ld all-binutils`. gprof needs fscanf with
  %[] scansets (not in the Montauk libc); gold and gprofng are
  disabled outright.
- The libc gained a large POSIX surface for this port (fd functions,
  full errno/signal sets, struct stat, sys/wait.h, utime.h, wchar.h,
  sys/param.h, memory.h, bsearch, sscanf field widths, ...). pex-style
  process spawning (fork/exec/pipe) is stubbed to fail with ENOSYS:
  the tools themselves never spawn, and real process plumbing is the
  posix_spawn milestone that needs kernel support (exit codes in
  SYS_WAITPID, fd redirection wiring).
- The `devkit` target in programs/GNUmakefile ships the staged tools
  into the OS image at 0:/sdk/bin (as.elf, ld.elf, ar.elf, ...) with a
  target-side sysroot at 0:/sdk/include + 0:/sdk/lib (libc.a, crt
  objects, the real hosted libstdc++.a plus its c++/ headers, and an
  empty libm stand-in) - the Montauk SDK. On-OS g++ therefore gets the
  same STL as the cross compiler; see the C++ standard library section
  above for what is and is not supported. The kernel
  resolves driveless absolute paths ("/sdk/lib") against the cwd
  drive, so the --prefix=/sdk layout works natively. The shell
  searches 0:/sdk/bin and tab-completes it. Future ports configure
  with --prefix=/sdk. If toolchain/native/ has not been built the
  devkit step is skipped and the image builds without it.