docs: replace the known-broken flag table with tested-toolchain facts

The table steered packagers away from -flto because BEESTRACE built its
std::function from a lambda that captured nothing whenever the trace
message was a plain string literal.  GCC read the resulting empty
_Any_data union as uninitialized, and -Werror turned the false positive
into a build failure on GCC 12 and 14.  BEESTRACE now init-captures
__FUNCTION__, so the closure is never empty and the warning no longer
fires; both -flto rows describe a problem that no longer exists.

The -D_GLIBCXX_ASSERTIONS row was never traced to a specific bug, only
to "possibly in libstdc++", and no reproducer survives.  Drop it along
with the rest rather than leave a claim in the install instructions that
nobody can check.

Replace it with what is actually true now.  `make build-check' builds
bees and runs its unit tests with GCC and with clang, each with -flto,
so record clang alongside GCC as a tested compiler, say that -flto is
tested, and name the check.

Keep the note that bees builds with -Wall -Wextra -Werror -O3 and no
other flags, and say why it matters: -Werror is what turns a new warning
into a failed build, which is the part packagers need to know.

Document the one way an LTO build reliably goes wrong: overriding CXX
without CC.  LTO leaves compiler-specific intermediate code in the
object files and the linker can only read the form matching the plugin
it loaded, so a mixed pair fails with "plugin needed to handle lto
object" and undefined references.  bees compiles C as well as C++, which
is enough for a half-overridden toolchain to break the link -- and the
error names neither the compilers nor the flag that caused it.

Assisted-by: Claude-Code:claude-opus-5
Signed-off-by: Zygo Blaxell <bees@furryterror.org>

diff --git a/docs/install.md b/docs/install.md
index cd7278c50eded1803bac1040fd6b5a84b3d97a19..05e57c4be6215360af41b0ce38699ca17be10143 100644 (file)
--- a/docs/install.md
+++ b/docs/install.md
@@ -4,24 +4,23 @@ Building bees
 Dependencies
 ------------
 
-* C++17 compiler (tested with GCC 11 through 14)
-
-  bees uses `-Wall -Wextra -Werror -O3` and no other compiler flags.
-  Be careful when adding extra flags such as `-flto` or
-  `-D_GLIBCXX_ASSERTIONS` when building bees for distribution; these
-  interact with known GCC bugs that produce false-positive warnings,
-  breaking the build or crashing at runtime.  Known-broken combinations:
-
-  | GCC version | Flag(s) | Notes |
-  |---|---|---|
-  | 12 | `-flto=auto` | False-positive `-Wmaybe-uninitialized`; toolchain bug, not a bees bug |
-  | 12 | `-D_GLIBCXX_ASSERTIONS` | Separate bug, possibly in libstdc++ |
-  | 13 | — | All flags work correctly |
-  | 14 | `-flto=auto` | Same `-Wmaybe-uninitialized` regression as GCC 12 |
-
-  If your distribution's build system adds LTO or assertion flags by
-  default, you may need to disable them for bees (e.g. with a `%define
-  _lto_cflags %nil` spec override on RPM-based distros).
+* C++17 compiler (tested with GCC 11 through 14, and clang 19)
+
+  bees builds with `-Wall -Wextra -Werror -O3` and needs no other
+  compiler flags.  `-Werror` makes any new compiler warning fatal, so
+  adding flags that change which warnings fire can break the build.
+
+  `-flto` is tested.  `make build-check` builds bees and runs its unit
+  tests with GCC and with clang, both with `-flto`.
+
+  Set `CC` and `CXX` to the same toolchain when building with `-flto`.
+  LTO leaves compiler-specific intermediate code in the object files,
+  and the linker loads the plugin for whichever toolchain drives the
+  link, which cannot read the other's.  bees compiles C as well as C++,
+  including `lib/xxhash.c` and the generated `src/bees-version.c`, so
+  overriding only `CXX` is enough to fail the link with `plugin needed
+  to handle lto object` and undefined references to `XXH64` and
+  `BEES_VERSION`.
 
 * btrfs-progs