Skip to content

Fix stale gershwin-build references and broken build commands - #2

Open
greenm01 wants to merge 1 commit into
gershwin-desktop:mainfrom
greenm01:docs-fix-gershwin-developer
Open

greenm01 wants to merge 1 commit into
gershwin-desktop:mainfrom
greenm01:docs-fix-gershwin-developer

Conversation

@greenm01

@greenm01 greenm01 commented Sep 6, 2026 •

Copy link
Copy Markdown

The build repository was renamed gershwin-build → gershwin-developer. The old URL still redirects, so the nine references across five pages look fine — but two of them hand the reader commands that fail.

building.md and rpi.md both say:

cd gershwin-build
./bootstrap.sh

The scripts live in Library/Scripts/, so that's an immediate "No such file or directory" — on the first command a new contributor types. Both now follow the README's actual flow: clone to /Developer, run the scripts from Library/Scripts/, build with make install.

building.md also contradicted itself, cloning into ./gershwin-build under Quick start and then using /Developer under Per-component builds.

linux.md presented one repository as two different tools — use gershwin-build, then in the very next paragraph clone gershwin-developer for "manual development setup". Now a single instruction.

Also, while in these files

  • Document the checkout.sh environment variables. SKIP_REPOS, BRANCH and PINNED are all in the README but appear nowhere on the docs site. SKIP_REPOS is the one you want when hacking on a single component.
  • Correct the Linux distribution list. It named four; Library/OSSupport/ has package lists for seven — Debian, Devuan, Ubuntu, Arch, Artix, Manjaro and Void.
  • Note that bootstrap.sh and make install run as root. The building.md quick start omitted this while linux.md used sudo.
  • Add the eau-theme build target, missing from the table.
  • Point the Live ISO section at targets/ and ADDING-A-FLAVOR.md instead of an unqualified "see gershwin-desktop/".
  • Replace the vague init-system line with what LoginWindow actually installs a service for, since it installs none on runit.

Verified

  • No gershwin-build references remain.
  • Every path, make target and environment variable named here exists in gershwin-developer at main — checked against a local checkout, not from memory.
  • The seven distributions claimed match Library/OSSupport/ exactly.
  • sphinx-build -b html succeeds on this branch, and the warning set is byte-identical to main — 65 both before and after, none introduced. The one new cross-reference, a relative link from linux.md to building.md, resolves.

One thing I noticed but did not change

Three pages are missing from the toctree in index.md and so are not published at all: developer/linux.md, developer/boot.md and user/feedback.md. The toctree sets glob: true but lists entries explicitly, with no developer/* pattern to catch them.

Sphinx says so itself, on main as well as here:

developer/linux.md: WARNING: document isn't included in any toctree [toc.not_included]

So linux.md — the page with the worst contradiction — isn't on the site. Fixing that changes site navigation, which felt like a different call from a text correction, so I left it out. Happy to add developer/linux here, or open a separate issue for all three, whichever you prefer.

https://claude.ai/code/session_01B3i2SyxJHZ2nBTLAEKGGLx

The build repository was renamed gershwin-build -> gershwin-developer. The old
URL still redirects, so the nine references across five pages looked fine while
two of them handed the reader commands that fail.

building.md and rpi.md both said:

    cd gershwin-build
    ./bootstrap.sh

The scripts live in Library/Scripts/, so that is an immediate "No such file or
directory" -- the first thing a new contributor types. Both now use the flow
from the gershwin-developer README: clone to /Developer, run the scripts from
Library/Scripts/, and build with make install. building.md also contradicted
itself, cloning into ./gershwin-build in Quick start and then using /Developer
under Per-component builds.

linux.md presented one repository as two different tools, telling the reader to
use gershwin-build and then, in the next paragraph, to clone gershwin-developer
for "manual development setup". Collapsed to a single instruction.

Also, while in these files:

* Document the three checkout.sh environment variables. SKIP_REPOS, BRANCH and
  PINNED are all in the README but appear nowhere on the docs site, and
  SKIP_REPOS is what you want when hacking on a single component.
* Correct the Linux distribution list, which named four; there are package
  lists in Library/OSSupport/ for seven (Debian, Devuan, Ubuntu, Arch, Artix,
  Manjaro and Void).
* Note that bootstrap.sh and make install run as root, which the building.md
  quick start omitted while linux.md used sudo.
* Add the eau-theme build target, which the table was missing.
* Point the Live ISO section at the targets/ directory and ADDING-A-FLAVOR.md
  rather than an unqualified "see gershwin-desktop/".
* Replace the vague init-system line with what LoginWindow actually installs a
  service for, since it installs none on runit.

Verified: no gershwin-build references remain; every path, make target and
environment variable named here exists in gershwin-developer at main.

Claude-Session: https://claude.ai/code/session_01B3i2SyxJHZ2nBTLAEKGGLx

This branch has not been deployed

No deployments
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.

1 participant