Skip to content

docs: add "Reducing closure size" tutorial (gcc closure leak) - #2552

Open
hamishmack wants to merge 1 commit into
masterfrom
hkm/issue-829-closure-size-docs
Open

docs: add "Reducing closure size" tutorial (gcc closure leak)#2552
hamishmack wants to merge 1 commit into
masterfrom
hkm/issue-829-closure-size-docs

Conversation

@hamishmack

Copy link
Copy Markdown
Collaborator

What

Adds a new tutorial page, Reducing closure size (removing the gcc dependency), under docs/tutorials/, and wires it into the mdBook SUMMARY.md navigation.

The page documents the existing opt-in knobs for trimming the compiler toolchain (most visibly gcc, ~143 MB) out of an executable's runtime closure:

  • nix why-depends for diagnosing what pulls gcc in;
  • per-component dontStrip = false; + dontPatchELF = false; for dynamically linked executables (with a copy-pasteable modules override, scoped to the exes component);
  • remove-references-to / nukeReferences in a postInstall for fully static binaries, where store paths remain baked in as string data;
  • an honest note on why these are opt-in.

Defaults are intentionally unchanged

This PR is documentation only. The defaults (dontStrip = true, dontPatchELF = true in modules/component-options.nix, with builder/comp-builder.nix passing --disable-executable-stripping / --disable-library-stripping accordingly) are deliberately left as-is.

Stripping has historically been reported to occasionally break Haskell binaries (angerman in #336), and hamishmack's follow-up question in the thread — whether that still holds with current GHC/binutils — was never answered. Flipping the default without resolving that would be unsafe, so this documents the safe opt-in path and tells users to test their binaries after enabling it.

Flipping the executable-only default (nixpkgs strips executables by default; the historical breakage was about aggressive stripping of library object files used for further linking) could be a sensible follow-up once maintainers resolve the stripping-safety question.

Verification

  • Verified option names/behaviour against the actual source (modules/component-options.nix, builder/comp-builder.nix).
  • Built the docs with mdBook: the new page renders and appears in the nav. (The pre-existing book.toml multilingual field is rejected by current mdBook and the only build warnings come from the pre-existing dev/coverage.md; both are unrelated to this change.)

Closes #829.

Document the existing opt-in knobs for trimming the toolchain (notably
gcc) out of an executable's runtime closure: per-component
dontStrip/dontPatchELF for dynamically linked exes, and
remove-references-to/nukeReferences for fully static binaries, plus
nix why-depends for diagnosis.

Defaults are intentionally left unchanged: stripping has historically
been reported to occasionally break Haskell binaries and that concern
is unresolved in the thread, so the page documents the safe opt-in
path and tells users to test.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Full GCC is included in the Nix closure of built artifacts

1 participant