docs/build: mention gcc/gnat version match issue

Signed-off-by: Leah Rowe <leah@libreboot.org>

site/docs/build/index.md

@@ -22,6 +22,33 @@ libreboot from the available source code.
 The following document describes how `lbmk` works, and how you can make changes
 to it: [libreboot maintenance manual](../maintain/)
 
+Debian Trixie/Sid
+=================
+
+Debian Trixie, the testing release as of 3 January 2025, and Debian Sid,
+provide `gnat` and `gcc` as you expect, but `gnat` resolves to `gnat-13` and
+installs `gcc-13` as a dependency, while `gcc` resolves to `gcc-14` and other
+toolchain components correspond to this version.
+
+The GCC/GNAT versions need to match during build time, so Libreboot's build
+system hacks the `PATH` environmental variable, setting up symlinks, matching
+GNAT to GCC or GNAT to GCC. When you run `./mk dependencies debian`, you get
+GNAT 13 and GCC 14. This seems to make most boards compile; in our testing, the
+KGPE-D16 board failed to compile in this configuration. This PATH hack is only
+done for compiling the coreboot crossgcc toolchain, and nothing else; after that,
+coreboot's toolchain is used.
+
+For better reliability, you should, after running the dependencies script,
+remove `gnat` and install `gnat-14` instead, which is available on this day
+of 3 December 2025, but currently marked experimental. When you install
+GNAT 14, GNAT 13 is removed but `gnat` (in `PATH`) still won't resolve to
+anything. Libreboot *still* accomodates this, detecting and matching the GCC
+and GNAT versions, which would in this instance match version 14 between them,
+so that `gnat` and `gcc` are both in PATH at build time, resolving to v14.x.
+
+GNAT is used by coreboot, because some of the Intel graphics devices are
+initialised natively, with code written in Ada spark (called `libgfxinit`).
+
 MIPS cross compiler
 ===================
 

site/docs/build/index.uk.md

@@ -30,6 +30,33 @@ libreboot з доступного джерельного коду.
 Наступний документ описує те, як працює `lbmk`, і як ви можете робити зміни
 до нього: [керівництво обслуговування libreboot](../maintain/)
 
+Debian Trixie/Sid
+=================
+
+Debian Trixie, the testing release as of 3 January 2025, and Debian Sid,
+provide `gnat` and `gcc` as you expect, but `gnat` resolves to `gnat-13` and
+installs `gcc-13` as a dependency, while `gcc` resolves to `gcc-14` and other
+toolchain components correspond to this version.
+
+The GCC/GNAT versions need to match during build time, so Libreboot's build
+system hacks the `PATH` environmental variable, setting up symlinks, matching
+GNAT to GCC or GNAT to GCC. When you run `./mk dependencies debian`, you get
+GNAT 13 and GCC 14. This seems to make most boards compile; in our testing, the
+KGPE-D16 board failed to compile in this configuration. This PATH hack is only
+done for compiling the coreboot crossgcc toolchain, and nothing else; after that,
+coreboot's toolchain is used.
+
+For better reliability, you should, after running the dependencies script,
+remove `gnat` and install `gnat-14` instead, which is available on this day
+of 3 December 2025, but currently marked experimental. When you install
+GNAT 14, GNAT 13 is removed but `gnat` (in `PATH`) still won't resolve to
+anything. Libreboot *still* accomodates this, detecting and matching the GCC
+and GNAT versions, which would in this instance match version 14 between them,
+so that `gnat` and `gcc` are both in PATH at build time, resolving to v14.x.
+
+GNAT is used by coreboot, because some of the Intel graphics devices are
+initialised natively, with code written in Ada spark (called `libgfxinit`).
+
 MIPS cross compiler
 ===================