RFR: 8283901: Introduce "make doctor" to diagnose build environment problems

[Erik Joelsson]

On Wed, 30 Mar 2022 01:05:08 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> When a user has problems with their build environment that trips up their builds, the cause is often one of just a few "popular" gotchas. For us working with the build system, we've seen them all before, but for the individual user, it's often the first time, and it can be really frustrating to debug.
> 
> The Doctor will help users detect if any of these well-known problems is present. Not all issues can be tested automatically, but enough of the most common problems *can* actually be checked, which makes this a worthwhile exercise.
> 
> (This was inspired by the macOS Homebrew "brew doctor".) 
> 
> This is an example output:
> 
> $ make doctor
> Building target 'doctor' in configuration 'linux-x86_64-server-release'
> 
> "make doctor" will help you analyze your build environment. It can highlight
> certain well-known problems, but it can never find all possible errors.
> 
> * Verifying that configure has picked up git...
> 
> * Checking for warnings from configure...
>  ---
> WARNING: The result of this configuration has overridden an older
> configuration. You *should* run 'make clean' to make sure you get a
> proper build. Failure to do so might result in strange build problems.
>  ---
> ! Inspect the warnings, fix any problems, and re-run configure
> 
> * Checking for left-over core files...
> 
> * Checking for untracked files with illegal names...
> 
> * If all else fails, try removing the entire build directory and re-creating
> the same configuration using:
>  ---
> configure_command_line=$(make print-configuration)
> make dist-clean
> bash configure $configure_command_line
>  ---
> 
> * The build README (doc/building.md) is a great source of information,
> especially the chapter "Fixing Unexpected Build Failures". Check it out!
> 
> * If you still need assistance please contact build-dev at openjdk.java.net.
> 
> Finished building target 'doctor' in configuration 'linux-x86_64-server-release'

Nice feature!

Did you consider using `.NOTPARALLEL` in Doctor.gmk instead of explicitly declaring prereqs between every target?

-------------

Marked as reviewed by erikj (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/8027