[StevenLi-phoenix]

Created by Claude Opus-5-5: the code, tests and this description were written entirely by Claude Opus-5-5.

Fixes #2287

Problem

On macOS, a Ruby build can fail with unclear compiler or linker errors when a non-default Xcode is the active developer directory, for example /Applications/Xcode-15.0.1.app/Contents/Developer or /Applications/Xcode 16.app/.... Reported symptoms include ffi.h warnings followed by make: *** [build-ext] Error 2, and Undefined symbols ... "_coroutine_transfer". The same build succeeds after sudo xcode-select --reset (or after selecting the Command Line Tools). Nothing in the BUILD FAILED report points to this, so affected users have to find the fix on their own. This also came up in discussion #2305.

Change

As suggested in #2287 (comment), build_failed now checks xcode-select -p on macOS. If the active developer directory is neither /Library/Developer/CommandLineTools nor /Applications/Xcode.app/Contents/Developer, the report names the selected directory and shows how to restore the default. Those are the standard locations that xcode-select --reset falls back to.

Output from a failing build with xcode-select -p stubbed to print a non-default Xcode (temporary paths shortened):

BUILD FAILED (macOS 27.0.1 on arm64 using ruby-build 20261013-3-g0629e79)

The active developer directory is /Applications/Xcode-15.0.1.app/Contents/Developer
A non-default Xcode might have caused this failure. To restore the default, run:

  sudo xcode-select --reset

You can inspect the build directory at $TMPDIR/ruby-build.20261022001004.34549.favkq6
See the full build log at $TMPDIR/ruby-build.20261022001004.34549.log

DEVELOPER_DIR overrides the system-wide selection, so xcode-select --reset does nothing while it is set. In that case the hint suggests unset DEVELOPER_DIR instead.

Nothing changes on other platforms, or on macOS when the default developer directory is active or xcode-select -p fails or prints nothing.

Testing

Three new tests in test/build.bats stub uname as Darwin, stub xcode-select -p, and make make fail. They cover a non-default Xcode, a set DEVELOPER_DIR, and the two default locations, where no hint is printed. All three fail on master and pass with this change. script/test passes on macOS with bats-core v1.10.0, with and without DEVELOPER_DIR exported. I haven't run the suite on Linux, but the new tests rely only on stubs.