Debug builds: price the split by turning it off
The page argued the split is worth having and measured it only as an
inline-vs-split object comparison. Turning it off is the clearer demonstration:
lame built four ways with the exact flags each level composes gives 1.72x for
--debug=full against a normal build, and 11.01x for the same build with
-gsplit-dwarf removed.
Also records the two results that read backwards: full is the SMALLEST of the
three levels, because -O0 emits smaller code than -O2 and past the split the -O
choice moves the archive more than the debug info does.
Corroborates Documentation/usage.md, which carried ~3x for full until GH-97.
Refs #97
Claude-Session: https://claude.ai/code/session_019T1bLfDhuHJpNNhn8CHVLJ
6f7fed3
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
069629f
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
caaec2d
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
063a8af