Strip /share/runtime/docs from io.elementary.Sdk (~600MB)? #254

Problem

io.elementary.Sdk bakes ~600MB of documentation (man pages, gtk-doc HTML, info pages, ri Ruby docs, cmake docs, help files) directly into every install, where the upstream org.gnome.Sdk it's built from, leaves that content out.

I compared an actual local install of io.elementary.Sdk//8 (2.6GB installed) against the plain org.gnome.Sdk//46 it's built on (2.0GB installed — runtime-version in io.elementary.Sdk.json.in is 46 for branch 8). All the toolchain directories are essentially identical in size between the two (lib 891M vs 892M, bin 291M vs 293M, libexec 324M vs 325M, include 114M vs 114M) — the entire ~620MB gap is concentrated in one path:

$ du -h --max-depth=1 <io.elementary.Sdk checkout>/files/share/runtime
600M    .../files/share/runtime
599M    .../files/share/runtime/docs
392M    .../files/share/runtime/docs/doc
72M     .../files/share/runtime/docs/man
56M     .../files/share/runtime/docs/ri
38M     .../files/share/runtime/docs/info
31M     .../files/share/runtime/docs/gtk-doc
9.7M    .../files/share/runtime/docs/cmake-3.29
2.3M    .../files/share/runtime/docs/help

You can see the difference yourself by comparing the SDK's:

flatpak remote-add --user --if-not-exists appcenter https://flatpak.elementary.io/repo.flatpakrepo
flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

flatpak install --user --noninteractive appcenter io.elementary.Sdk//8
flatpak install --user --noninteractive flathub org.gnome.Sdk//46   # matches branch 8's runtime-version

du -h --max-depth=1 ~/.local/share/flatpak/runtime/io.elementary.Sdk/x86_64/8/active/files/share/runtime
du -h --max-depth=1 ~/.local/share/flatpak/runtime/org.gnome.Sdk/x86_64/46/active/files/share/runtime

share/runtime/docs and share/runtime/locale are flatpak's extension mount points — normally empty directories that only get populated when a consumer explicitly installs the corresponding .Docs/.Locale/.Debug extension. On the plain org.gnome.Sdk//46 checkout, share/runtime is indeed empty (24KB, just placeholder dirs). On io.elementary.Sdk//8 it's 599MB of real files, permanently included — and there's no io.elementary.Sdk.Docs extension published on the appcenter remote to opt out into instead (flatpak remote-info appcenter io.elementary.Sdk.Docs//8 → Can't find ref), so there's no way for a consumer to avoid downloading/extracting it.

Notably, io.elementary.Sdk.json.in already declares /share/runtime/docs under cleanup-platform:

"cleanup-platform": [
    "/share/runtime/docs",
    "/include",
    ...
]

This isn't a bug — cleanup-platform is doing exactly what it's documented and implemented to do. Per flatpak-builder's own source (builder-manifest.c, comment above builder_manifest_prepare_platform): for a build-runtime: true manifest, flatpak-builder does one combined build, then derives the platform output by layering those changes on top of a base "except any new files mentioned by cleanup-platform". The Sdk export is the full, unfiltered build — cleanup-platform was only ever going to trim the derived io.elementary.Platform output (consistent with what we measured: io.elementary.Platform//8 is only ~38MB larger than plain org.gnome.Platform//46, vs. the Sdk's ~620MB gap). There's no equivalent cleanup field in this manifest for the Sdk build's own output at all.

This matters for CI: for a project doing a plain meson/ninja/valac build via flatpak-builder (no devhelp/man/info ever invoked), this 599MB, which is not needed, is pulled on every pull — and per #253, extraction time (not just download bandwidth) scales with file count, and a docs tree like this is typically tens of thousands of small files.

Proposal

• Add a top-level cleanup array to io.elementary.Sdk.json.in, alongside the existing cleanup-platform:

  "cleanup": [
      "/share/runtime/docs"
  ]

  This is a different field from cleanup-platform and applies earlier in the build: per builder_manifest_cleanup(), cleanup is applied directly to the Sdk build's own file tree as its own step, before builder_manifest_prepare_platform() derives the Platform output from it (the comment there — "layer on top all the changes from the sdk build" — implies the Sdk build is already finalized/cleaned by that point). So cleanup and cleanup-platform are sequential, not alternatives; listing /share/runtime/docs in both is harmless (Platform derivation would just find it already gone).
• If the content is wanted for some consumers (e.g. interactively browsing docs in flatpak run --devel), publishing it as a proper opt-in extension would let CI/build-only consumers skip it while keeping it available for anyone who wants it. This was actually attempted before, in add io.elementary.Sdk.Docs extension #25 (2021) — an add-extensions block for io.elementary.Sdk.Docs:

  "add-extensions": {
      "io.elementary.Sdk.Docs" : {
          "directory": "share/runtime/docs",
          "bundle": true,
          "autodelete": true,
          "no-autodownload": true
      }
  }

  That PR stalled and was closed for inactivity in 2023, not rejected on technical grounds — but it also bundled in unrelated changes (new graphviz/vala modules, enabling granite's own -Ddocumentation=true), which likely didn't help it get reviewed. Worth trying again as its own focused PR if the plain cleanup fix above isn't preferred.

Prior Art (Optional)

• add io.elementary.Sdk.Docs extension #25 (2021, closed 2023 for inactivity): tried the add-extensions/io.elementary.Sdk.Docs approach above. Notably, the author's own comment on that PR — "/share/runtime/docs are in the platform-cleanup, is that right? ... Yes, it seems to be working, no idea why." — is the same uncertainty this issue resolves: cleanup-platform only ever applied to the derived Platform output, never the Sdk's own.
• Companion to Use zstd compression? #253 (layer compression). Related size-awareness work in this repo: Dockerfile: Rebase on Flathub actions image #234 (rebasing the base image to cut bloat), Make sure not to use apt in the workflows that use flatpak-platform docker images #236 (fallout from that).