Add Troubleshooting a failed build
The fourth page GH-96 named, deferred then because its material was scattered
across BUILDING.md, the log/stamp mechanics, and failure modes written down
nowhere at all.
Every message it quotes was read out of the source or reproduced, not recalled:
- the log lifecycle, from run() in lib/utils.sh -- a surviving log IS the
failure, because a successful recipe deletes its own
- "outdated but will not be rebuilt" (lib/utils.sh:229), the skip that
continues the build with the old library and fails nothing
- "refusing to produce a mixed-level workspace" (mediaforge.sh:473-481)
- the missing-.dwo symptom, reproduced by hiding one .dwo and re-running gdb:
the warning is followed by "No breakpoints, watchpoints, tracepoints, or
catchpoints" -- the breakpoint is silently not set
Also names the licence-tier trap: save_stored_choices persists the six group
choices and the trust-store path, and NOT --enable-gpl/--enable-nonfree, so a
bare rebuild after a nonfree build resolves a different recipe set. Verified by
reading the heredoc rather than assumed.
Links to BUILDING.md for per-distribution static-build setup rather than
restating it, per the GH-96 carve-out.
Refs #99
Claude-Session: https://claude.ai/code/session_019T1bLfDhuHJpNNhn8CHVLJ
Home: name the in-tree reference authoritative, and stop pointing at a moving branch
The page already said the reference lives in the repository. It did not say the
checkout is the authoritative copy, and every link pointed at blob/develop --
which always shows the tip, so a reader on a tagged release was sent to a
different document than the one beside the mediaforge.sh that will parse their
flags. That gave away the version-matching this split exists to preserve.
States why rather than asserting it: a wiki is a separate repository, so it is
not tagged, not present on clone, not reviewed by any pull request, and not
readable by an offline gate -- while two in-tree tests do grep the docs on every
push (tests/debug-levels.sh:929 for flag coverage, tests/ccache.sh:45 for a
behavioural default). Names FFmpeg's own arrangement as the precedent.
Refs #96
Claude-Session: https://claude.ai/code/session_019T1bLfDhuHJpNNhn8CHVLJ
Add the first wiki pages: worked examples, choices, split DWARF
Covers what the repository deliberately does not carry: goal-shaped
sequences, the reasoning behind a default, and the retention contract that
--debug creates.
The flag reference stays in Documentation/usage.md, which the
every-flag-is-documented gate checks on every push. These pages link to it
rather than restating it, so there is no second copy free to drift.
Refs #96
Claude-Session: https://claude.ai/code/session_019T1bLfDhuHJpNNhn8CHVLJ