Clarify Linux build tools installation instructions

[p-linnane]

On Linux, brew doctor and the missing-build-tools errors previously advised users to "Install Clang or run brew install gcc". That guidance is misleading here: a Homebrew-installed gcc does not provide the system /usr/bin/cc toolchain that bootstrap and post-install steps rely on (for example, brew postinstall gcc shells out to /usr/bin/cc -print-file-name=crti.o when building against the system glibc, which fails until a system compiler is installed). This overrides the Linux DevelopmentTools.installation_instructions to point at the system C compiler and the standard development tools, with a link to the requirements docs.

CompilerSelectionError still recommends brew install gcc via a Linux custom_installation_instructions override, mirroring the existing macOS split: the system toolchain for "no developer tools installed", and brew install gcc when a formula fails with every available compiler.

The Requirements section of the Linux docs now notes that Homebrew expects a working system C compiler and that its own gcc does not replace it for bootstrap and post-install steps.

This follows https://github.com/orgs/Homebrew/discussions/6940 and supersedes #22921.

Note: check_for_installed_developer_tools only fires when no compiler is detected at all, so it does not trigger for the specific case in the discussion where a Homebrew gcc is present but /usr/bin/cc is absent. This PR improves the guidance and documentation rather than adding a new detector for that case.

---

• Have you followed our Contributing guidelines?
• Have you checked for other open Pull Requests for the same change?
• Have you explained what your changes do? Performance claims (e.g. "this is faster") must include Hyperfine benchmarks.
• Have you explained why you'd like these changes included, not just what they do?
• For bug fixes, have you given step-by-step brew commands to reproduce the bug?
• Have you written new tests (excluding integration tests)? Here's an example.
• Have you successfully run brew lgtm (style, typechecking and tests) locally?

---

• AI was used to generate or assist with generating this PR.

Claude Code drafted the code, tests and docs from my design and iterated on my review; I reviewed every change and verified locally with brew typecheck, brew style and brew lgtm (the Linux-only specs run in CI).

---

[Copilot]

Pull request overview

This PR clarifies Linux-facing guidance around missing build tools by distinguishing between the required system C toolchain and Homebrew’s optional gcc formula, aligning brew doctor/diagnostic output and docs with the actual bootstrap/post-install expectations on Linux.

Changes:

• Override Linux DevelopmentTools.installation_instructions to direct users to install system development tools and link to the Linux requirements docs.
• Override Linux DevelopmentTools.custom_installation_instructions to keep CompilerSelectionError guidance pointing to brew install gcc.
• Update Linux documentation and add/adjust specs to cover the new messaging.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
Library/Homebrew/test/os/linux/diagnostic_spec.rb	Adds Linux-specific specs asserting the new developer-tools messaging and custom_installation_instructions content.
Library/Homebrew/test/diagnostic_checks_spec.rb	Adds a unit spec ensuring diagnostics use DevelopmentTools.installation_instructions.
Library/Homebrew/extend/os/linux/development_tools.rb	Implements Linux overrides for installation guidance (system toolchain vs. brew install gcc).
docs/Homebrew-on-Linux.md	Updates review date and documents that Homebrew requires a working system C compiler on Linux.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[MikeMcQuaid]

Thanks!