INSTALL THE BUILD TOOLCHAIN (SteamOS)
=====================================

This is section 6 of ~/ringout-build/BUILD-ON-THE-DECK.md, on its own, because
it is the one part that needs your sudo password and cannot be run over ssh.

Run in Konsole, Desktop Mode.


THE COMMANDS
------------

    sudo steamos-readonly disable
    sudo pacman-key --init
    sudo pacman-key --populate archlinux
    sudo pacman -S base-devel clang glibc linux-api-headers cmake ninja

(pacman-key is only needed the first time, or after a SteamOS update. Harmless
to run again.)

Add llvm to that list if you want the profile-guided build described below:

    sudo pacman -S base-devel clang glibc linux-api-headers cmake ninja llvm

Installing clang does NOT give you llvm-profdata. Checked on this Deck: clang
20.1.8 installed, llvm-profdata still missing. It ships in the separate llvm
package. Nothing but the profile step uses it.


DO NOT ADD --needed
-------------------

This Deck right now is the exact case that flag breaks:

    pacman's database says glibc owns 504 files under /usr/include
    188 are actually on disk

With --needed, pacman looks at the database, decides glibc is already
installed, installs NOTHING, and leaves 316 headers missing. The build then
fails much later with an error about a missing header, which looks like a
different problem entirely.

Without it, you are reinstalling at the version you already have. That is a
file restore, not an upgrade, and it is safe.


NEVER USE -Sy OR -Syu
---------------------

SteamOS pins snapshot repositories. Without -Sy you get the version already
pinned. With it you can pull a newer snapshot into a system that was not built
for it, and that is what actually breaks Decks.


WHY clang IS IN THE LIST
------------------------

The profile-guided build is clang-only - both setup.sh and the module's
CMakeLists check for it - and it is worth about 13% of CPU time. Measured on
this Deck: 493.52 Gcyc without the profile, 429.30 Gcyc with. A gcc build
produces a correct module that is about 13% slower.

BUT: clang alone is not enough on this Deck, and this is worth understanding
before you expect the 13%.

The profiles that ship in the package were generated by LLVM 22. An indexed
profile can only be read by an LLVM at least as new as the one that wrote it,
and SteamOS ships clang 20. So on a stock Deck the build says

    module: this clang cannot read the shipped PGO profile

and builds without it. Confirmed here on the PAL build: the module came out
23 MB instead of the 39 MB a profiled build produces.

The fix is to make a profile with the clang you have, which is what

    ./setup.sh --deck --pgo /path/to/your/disc.iso

does - it needs the llvm package above, takes about 30 extra minutes once, and
is section 2b of BUILD-ON-THE-DECK.md.


AFTER
-----

Check it took:

    for t in clang gcc cmake ninja python3; do printf '%-8s ' "$t"; command -v $t || echo MISSING; done
    printf 'int main(void){return 0;}' > /tmp/t.c && cc /tmp/t.c -o /tmp/t && echo "compiles: OK"
    pacman -Ql glibc | grep -c /usr/include/

Expected: all five present, "compiles: OK", and the header count now matching
the 504 the database claims.

Compile something rather than looking for one header. stdatomic.h ships with
the COMPILER (/usr/lib/clang/20/include/), not with glibc, so checking for it
answers a different question than the one you are asking. Only an actual
compile covers both halves.

If you installed llvm too:

    command -v llvm-profdata || echo "MISSING - --pgo cannot merge counts"

Then tell Claude, and the build runs from step 2.


IF YOU WANT TO UNDO IT AGAIN
----------------------------

~/Desktop/REMOVE-TOOLCHAIN.txt
