RFR: 8352645: Add tool support to check order of includes

[Doug Simon]

This PR adds `test/hotspot/jtreg/sources/SortIncludes.java`, a tool to check that blocks of include statements in C++ files are sorted and that there's at least one blank line between user and sys includes (as per the [style guide](https://github.com/openjdk/jdk/blob/master/doc/hotspot-style.md#source-files)).

By virtue of using `SortedSet`, the tool also removes duplicate includes (e.g. `"compiler/compilerDirectives.hpp"` on line [37](https://github.com/openjdk/jdk/blob/059f190f4b0c7836b89ca2070400529e8d33790b/src/hotspot/share/c1/c1_Compilation.cpp#L37) and line [41](https://github.com/openjdk/jdk/blob/059f190f4b0c7836b89ca2070400529e8d33790b/src/hotspot/share/c1/c1_Compilation.cpp#L41)). Sorting uses lowercased strings so that `_` sorts before letters, preserving the prevailing convention in the code base. I've also updated the style guide to clarify this sort-order.

The tool does nothing about re-ordering blocks of conditional includes vs unconditional includes. I briefly looked into that but it gets very complicated, very quickly. That kind of re-ordering will have to continue to be done manually for now.

I have used the tool to fix the ordering of a subset of HotSpot sources and added a test to keep them sorted. That test can be expanded over time to keep includes sorted in other HotSpot directories.

When `TestIncludesAreSorted.java` fails, it tries to provide actionable advice. For example:

java.lang.RuntimeException: The unsorted includes listed below should be fixable by running:

    java /Users/dnsimon/dev/jdk-jdk/open/test/hotspot/jtreg/sources/SortIncludes.java --update /Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/c1 /Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/ci /Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/compiler /Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/jvmci

	at TestIncludesAreSorted.main(TestIncludesAreSorted.java:80)
	at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:104)
	at java.base/java.lang.reflect.Method.invoke(Method.java:565)
	at com.sun.javatest.regtest.agent.MainActionHelper$AgentVMRunnable.run(MainActionHelper.java:335)
	at java.base/java.lang.Thread.run(Thread.java:1447)
Caused by: java.lang.RuntimeException: 36 files with unsorted headers found:

/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/c1/c1_Compilation.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/c1/c1_Runtime1.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/c1/c1_Optimizer.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/c1/c1_Compilation.hpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/c1/c1_FrameMap.hpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/c1/c1_RangeCheckElimination.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/c1/c1_InstructionPrinter.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/ci/bcEscapeAnalyzer.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/ci/ciInstance.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/ci/ciEnv.hpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/ci/ciUtilities.inline.hpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/ci/ciMethod.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/ci/ciUtilities.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/ci/ciEnv.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/ci/ciCallSite.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/ci/bcEscapeAnalyzer.hpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/ci/ciReplay.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/ci/ciInstanceKlass.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/compiler/compilationMemoryStatistic.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/compiler/compilationFailureInfo.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/compiler/compilationPolicy.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/compiler/directivesParser.hpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/compiler/compileBroker.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/compiler/directivesParser.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/compiler/compilerDirectives.hpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/compiler/methodMatcher.hpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/compiler/compilationMemoryStatistic.hpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/compiler/compileTask.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/compiler/disassembler.hpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/compiler/oopMap.inline.hpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/jvmci/jvmciRuntime.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/jvmci/jvmci.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/jvmci/jvmciCompiler.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/jvmci/jvmci.hpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/jvmci/jvmciEnv.cpp
/Users/dnsimon/dev/jdk-jdk/open/src/hotspot/share/jvmci/jvmciJavaClasses.cpp

Note that non-space characters after the closing " or > of an include statement
can be used to prevent re-ordering of the include. For example:

#include "e.hpp"
#include "d.hpp"
#include "c.hpp" // do not reorder
#include "b.hpp"
#include "a.hpp"

will be reformatted as:

#include "d.hpp"
#include "e.hpp"
#include "c.hpp" // do not reorder
#include "a.hpp"
#include "b.hpp"


	at SortIncludes.main(SortIncludes.java:190)
	at TestIncludesAreSorted.main(TestIncludesAreSorted.java:75)
	... 4 more

JavaTest Message: Test threw exception: java.lang.RuntimeException


This PR includes a [commit](https://github.com/openjdk/jdk/pull/24247/commits/a76d4f98c7e6074b4745c1c1791fe605e352d79f) with ordering suppression comments for some files I discovered needed it while playing around in #24180 .

This PR replaces #24180.

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

Commit messages:
 - sort includes in subset of HotSpot sources and added a test to keep them sorted
 - added tool to sort includes
 - do not reorder certain includes

Changes: https://git.openjdk.org/jdk/pull/24247/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=24247&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8352645
  Stats: 396 lines in 53 files changed: 335 ins; 54 del; 7 mod
  Patch: https://git.openjdk.org/jdk/pull/24247.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24247/head:pull/24247

PR: https://git.openjdk.org/jdk/pull/24247