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:

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:

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:

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:

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):

../../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.

10 KiB Raw Blame History