From 814730eae76d7b60a6082dc6f9e30618b7d8524b Mon Sep 17 00:00:00 2001
From: Doug Simon <dnsimon@openjdk.org>
Date: Wed, 2 Apr 2025 22:30:13 +0000
Subject: [PATCH] 8352645: Add tool support to check order of includes

Reviewed-by: stefank, kbarrett
---
 doc/hotspot-style.html                        |  43 ++--
 doc/hotspot-style.md                          |   5 +-
 src/hotspot/cpu/aarch64/immediate_aarch64.cpp |   4 +-
 .../windows/systemMemoryBarrier_windows.cpp   |   2 +-
 src/hotspot/share/adlc/archDesc.cpp           |   2 +-
 src/hotspot/share/c1/c1_CFGPrinter.cpp        |   4 +-
 src/hotspot/share/c1/c1_CodeStubs.hpp         |   2 +-
 src/hotspot/share/c1/c1_Compilation.cpp       |   5 +-
 src/hotspot/share/c1/c1_FrameMap.hpp          |   2 +-
 src/hotspot/share/c1/c1_GraphBuilder.cpp      |   2 +-
 src/hotspot/share/c1/c1_GraphBuilder.hpp      |   2 +-
 src/hotspot/share/c1/c1_IR.cpp                |   2 +-
 src/hotspot/share/c1/c1_Instruction.cpp       |   2 +-
 .../share/c1/c1_InstructionPrinter.cpp        |   2 +-
 .../share/c1/c1_InstructionPrinter.hpp        |   2 +-
 src/hotspot/share/c1/c1_LinearScan.cpp        |   2 +-
 src/hotspot/share/c1/c1_LinearScan.hpp        |   2 +-
 src/hotspot/share/c1/c1_Optimizer.cpp         |   2 +-
 src/hotspot/share/c1/c1_Optimizer.hpp         |   2 +-
 .../share/c1/c1_RangeCheckElimination.cpp     |   4 +-
 src/hotspot/share/c1/c1_Runtime1.cpp          |   2 +-
 src/hotspot/share/c1/c1_ValueStack.cpp        |   2 +-
 src/hotspot/share/ci/bcEscapeAnalyzer.cpp     |   2 +-
 src/hotspot/share/ci/bcEscapeAnalyzer.hpp     |   2 +-
 src/hotspot/share/ci/ciCallSite.cpp           |   2 +-
 src/hotspot/share/ci/ciEnv.cpp                |   2 +-
 src/hotspot/share/ci/ciEnv.hpp                |   2 +-
 src/hotspot/share/ci/ciInstance.cpp           |   2 +-
 src/hotspot/share/ci/ciInstanceKlass.cpp      |   2 +-
 src/hotspot/share/ci/ciMethod.cpp             |   2 +-
 src/hotspot/share/ci/ciReplay.cpp             |   2 +-
 src/hotspot/share/ci/ciUtilities.cpp          |   2 +-
 .../share/compiler/compilationFailureInfo.cpp |   4 +-
 .../share/compiler/compilationPolicy.cpp      |   2 +-
 src/hotspot/share/compiler/compileBroker.cpp  |   4 +-
 src/hotspot/share/compiler/compileBroker.hpp  |   2 +-
 src/hotspot/share/compiler/compileTask.cpp    |   4 +-
 .../compiler/compilerDefinitions.inline.hpp   |   1 +
 .../share/compiler/compilerDirectives.hpp     |   2 +-
 src/hotspot/share/compiler/compilerThread.cpp |   2 +-
 .../share/compiler/directivesParser.cpp       |   1 +
 .../share/compiler/directivesParser.hpp       |   2 +-
 src/hotspot/share/compiler/disassembler.hpp   |   3 +-
 src/hotspot/share/compiler/methodMatcher.hpp  |   2 +-
 src/hotspot/share/compiler/oopMap.inline.hpp  |   1 +
 src/hotspot/share/jvmci/jvmci.cpp             |   4 +-
 src/hotspot/share/jvmci/jvmciCompiler.cpp     |   4 +-
 src/hotspot/share/jvmci/jvmciEnv.cpp          |   2 +-
 src/hotspot/share/jvmci/jvmciJavaClasses.cpp  |   2 +-
 src/hotspot/share/jvmci/jvmciRuntime.cpp      |   2 +-
 test/hotspot/jtreg/TEST.groups                |   5 +-
 test/hotspot/jtreg/sources/SortIncludes.java  | 235 ++++++++++++++++++
 .../jtreg/sources/TestIncludesAreSorted.java  | 109 ++++++++
 53 files changed, 431 insertions(+), 79 deletions(-)
 create mode 100644 test/hotspot/jtreg/sources/SortIncludes.java
 create mode 100644 test/hotspot/jtreg/sources/TestIncludesAreSorted.java

diff --git a/doc/hotspot-style.html b/doc/hotspot-style.html
index 72e5ce66e19..7e7f4de3629 100644
--- a/doc/hotspot-style.html
+++ b/doc/hotspot-style.html
@@ -207,27 +207,34 @@ the simple "getter".</p></li>
 <ul>
 <li><p>All source files must have a globally unique basename. The build
 system depends on this uniqueness.</p></li>
-<li><p>Keep the include lines within a section alphabetically sorted.</p></li>
-<li><p>Put conditional inclusions (`#if ...`) at the end of the section of HotSpot
-include lines. This also applies to macro-expanded includes of platform
-dependent files.</p></li>
-<li><p>Put system includes in a section after the HotSpot include lines with a blank
-line separating the two sections.</p></li>
+<li><p>Keep the include lines within a section alphabetically sorted by
+their lowercase value. If an include must be out of order for
+correctness, suffix with it a comment such as
+<code>// do not reorder</code>. Source code processing tools can also
+use this hint.</p></li>
+<li><p>Put conditional inclusions (<code>#if ...</code>) at the end of
+the section of HotSpot include lines. This also applies to
+macro-expanded includes of platform dependent files.</p></li>
+<li><p>Put system includes in a section after the HotSpot include lines
+with a blank line separating the two sections.</p></li>
 <li><p>Do not put non-trivial function implementations in .hpp files. If
-the implementation depends on other .hpp files, put it in a .cpp or
-a .inline.hpp file.</p></li>
+the implementation depends on other .hpp files, put it in a .cpp or a
+.inline.hpp file.</p></li>
 <li><p>.inline.hpp files should only be included in .cpp or .inline.hpp
 files.</p></li>
-<li><p>All .inline.hpp files should include their corresponding .hpp file as
-the first include line with a blank line separating it from the rest of the
-include lines. Declarations needed by other files should be put in the .hpp
-file, and not in the .inline.hpp file. This rule exists to resolve problems
-with circular dependencies between .inline.hpp files.</p></li>
-<li><p>Do not include a .hpp file if the corresponding .inline.hpp file is included.</p></li>
-<li><p>Use include guards for .hpp and .inline.hpp files. The name of the defined
-guard should be derived from the full search path of the file relative to the
-hotspot source directory. The guard should be all upper case with all paths
-separators and periods replaced by underscores.</p></li>
+<li><p>All .inline.hpp files should include their corresponding .hpp
+file as the first include line with a blank line separating it from the
+rest of the include lines. Declarations needed by other files should be
+put in the .hpp file, and not in the .inline.hpp file. This rule exists
+to resolve problems with circular dependencies between .inline.hpp
+files.</p></li>
+<li><p>Do not include a .hpp file if the corresponding .inline.hpp file
+is included.</p></li>
+<li><p>Use include guards for .hpp and .inline.hpp files. The name of
+the defined guard should be derived from the full search path of the
+file relative to the hotspot source directory. The guard should be all
+upper case with all paths separators and periods replaced by
+underscores.</p></li>
 <li><p>Some build configurations use precompiled headers to speed up the
 build times. The precompiled headers are included in the precompiled.hpp
 file. Note that precompiled.hpp is just a build time optimization, so
diff --git a/doc/hotspot-style.md b/doc/hotspot-style.md
index d0b1c82a3d7..0a135b2074c 100644
--- a/doc/hotspot-style.md
+++ b/doc/hotspot-style.md
@@ -138,7 +138,10 @@ change should be done with a "setter" accessor matched to the simple
 * All source files must have a globally unique basename. The build
 system depends on this uniqueness.
 
-* Keep the include lines within a section alphabetically sorted.
+* Keep the include lines within a section alphabetically sorted by their
+lowercase value. If an include must be out of order for correctness,
+suffix with it a comment such as `// do not reorder`. Source code
+processing tools can also use this hint.
 
 * Put conditional inclusions (`#if ...`) at the end of the section of HotSpot
 include lines. This also applies to macro-expanded includes of platform
diff --git a/src/hotspot/cpu/aarch64/immediate_aarch64.cpp b/src/hotspot/cpu/aarch64/immediate_aarch64.cpp
index 024d554b98f..710a1f0677d 100644
--- a/src/hotspot/cpu/aarch64/immediate_aarch64.cpp
+++ b/src/hotspot/cpu/aarch64/immediate_aarch64.cpp
@@ -23,8 +23,8 @@
  *
  */
 
-#include <stdlib.h>
-#include <stdint.h>
+#include <stdlib.h> // do not reorder
+#include <stdint.h> // do not reorder
 
 #include "immediate_aarch64.hpp"
 #include "metaprogramming/primitiveConversions.hpp"
diff --git a/src/hotspot/os/windows/systemMemoryBarrier_windows.cpp b/src/hotspot/os/windows/systemMemoryBarrier_windows.cpp
index 03811fcd64b..6156469ff24 100644
--- a/src/hotspot/os/windows/systemMemoryBarrier_windows.cpp
+++ b/src/hotspot/os/windows/systemMemoryBarrier_windows.cpp
@@ -24,7 +24,7 @@
 
 #include "systemMemoryBarrier_windows.hpp"
 
-#include <windows.h>
+#include <windows.h>  // do not reorder
 #include <processthreadsapi.h>
 
 bool WindowsSystemMemoryBarrier::initialize() {
diff --git a/src/hotspot/share/adlc/archDesc.cpp b/src/hotspot/share/adlc/archDesc.cpp
index edb07d2d22c..8a7d0ee40c4 100644
--- a/src/hotspot/share/adlc/archDesc.cpp
+++ b/src/hotspot/share/adlc/archDesc.cpp
@@ -24,7 +24,7 @@
 
 
 // archDesc.cpp - Internal format for architecture definition
-#include <unordered_set>
+#include <unordered_set>  // do not reorder
 #include "adlc.hpp"
 
 static FILE *errfile = stderr;
diff --git a/src/hotspot/share/c1/c1_CFGPrinter.cpp b/src/hotspot/share/c1/c1_CFGPrinter.cpp
index d178b699238..a846507c3f0 100644
--- a/src/hotspot/share/c1/c1_CFGPrinter.cpp
+++ b/src/hotspot/share/c1/c1_CFGPrinter.cpp
@@ -23,10 +23,10 @@
  */
 
 #include "c1/c1_CFGPrinter.hpp"
-#include "c1/c1_IR.hpp"
 #include "c1/c1_InstructionPrinter.hpp"
-#include "c1/c1_LIR.hpp"
+#include "c1/c1_IR.hpp"
 #include "c1/c1_LinearScan.hpp"
+#include "c1/c1_LIR.hpp"
 #include "c1/c1_ValueStack.hpp"
 #include "jvm.h"
 
diff --git a/src/hotspot/share/c1/c1_CodeStubs.hpp b/src/hotspot/share/c1/c1_CodeStubs.hpp
index 9abfa45785b..a885e4c0816 100644
--- a/src/hotspot/share/c1/c1_CodeStubs.hpp
+++ b/src/hotspot/share/c1/c1_CodeStubs.hpp
@@ -26,8 +26,8 @@
 #define SHARE_C1_C1_CODESTUBS_HPP
 
 #include "c1/c1_FrameMap.hpp"
-#include "c1/c1_IR.hpp"
 #include "c1/c1_Instruction.hpp"
+#include "c1/c1_IR.hpp"
 #include "c1/c1_LIR.hpp"
 #include "c1/c1_Runtime1.hpp"
 #include "code/nativeInst.hpp"
diff --git a/src/hotspot/share/c1/c1_Compilation.cpp b/src/hotspot/share/c1/c1_Compilation.cpp
index 98ec1959cc2..53a97ce1042 100644
--- a/src/hotspot/share/c1/c1_Compilation.cpp
+++ b/src/hotspot/share/c1/c1_Compilation.cpp
@@ -25,8 +25,8 @@
 #include "c1/c1_CFGPrinter.hpp"
 #include "c1/c1_Compilation.hpp"
 #include "c1/c1_IR.hpp"
-#include "c1/c1_LIRAssembler.hpp"
 #include "c1/c1_LinearScan.hpp"
+#include "c1/c1_LIRAssembler.hpp"
 #include "c1/c1_MacroAssembler.hpp"
 #include "c1/c1_RangeCheckElimination.hpp"
 #include "c1/c1_ValueMap.hpp"
@@ -34,11 +34,10 @@
 #include "code/debugInfoRec.hpp"
 #include "compiler/compilationFailureInfo.hpp"
 #include "compiler/compilationMemoryStatistic.hpp"
-#include "compiler/compilerDirectives.hpp"
 #include "compiler/compileLog.hpp"
-#include "compiler/compileTask.hpp"
 #include "compiler/compiler_globals.hpp"
 #include "compiler/compilerDirectives.hpp"
+#include "compiler/compileTask.hpp"
 #include "memory/resourceArea.hpp"
 #include "runtime/sharedRuntime.hpp"
 #include "runtime/timerTrace.hpp"
diff --git a/src/hotspot/share/c1/c1_FrameMap.hpp b/src/hotspot/share/c1/c1_FrameMap.hpp
index dab3aa6e734..4e4fde0cb4a 100644
--- a/src/hotspot/share/c1/c1_FrameMap.hpp
+++ b/src/hotspot/share/c1/c1_FrameMap.hpp
@@ -29,10 +29,10 @@
 #include "c1/c1_LIR.hpp"
 #include "code/vmreg.hpp"
 #include "memory/allocation.hpp"
+#include "oops/compressedOops.hpp"
 #include "runtime/frame.hpp"
 #include "utilities/globalDefinitions.hpp"
 #include "utilities/macros.hpp"
-#include "oops/compressedOops.hpp"
 
 class ciMethod;
 class CallingConvention;
diff --git a/src/hotspot/share/c1/c1_GraphBuilder.cpp b/src/hotspot/share/c1/c1_GraphBuilder.cpp
index b2750345a08..201ee695f69 100644
--- a/src/hotspot/share/c1/c1_GraphBuilder.cpp
+++ b/src/hotspot/share/c1/c1_GraphBuilder.cpp
@@ -22,8 +22,8 @@
  *
  */
 
-#include "c1/c1_CFGPrinter.hpp"
 #include "c1/c1_Canonicalizer.hpp"
+#include "c1/c1_CFGPrinter.hpp"
 #include "c1/c1_Compilation.hpp"
 #include "c1/c1_GraphBuilder.hpp"
 #include "c1/c1_InstructionPrinter.hpp"
diff --git a/src/hotspot/share/c1/c1_GraphBuilder.hpp b/src/hotspot/share/c1/c1_GraphBuilder.hpp
index 9b9ee0072ad..6eaeda5adcf 100644
--- a/src/hotspot/share/c1/c1_GraphBuilder.hpp
+++ b/src/hotspot/share/c1/c1_GraphBuilder.hpp
@@ -25,8 +25,8 @@
 #ifndef SHARE_C1_C1_GRAPHBUILDER_HPP
 #define SHARE_C1_C1_GRAPHBUILDER_HPP
 
-#include "c1/c1_IR.hpp"
 #include "c1/c1_Instruction.hpp"
+#include "c1/c1_IR.hpp"
 #include "c1/c1_ValueMap.hpp"
 #include "c1/c1_ValueStack.hpp"
 #include "ci/ciMethodData.hpp"
diff --git a/src/hotspot/share/c1/c1_IR.cpp b/src/hotspot/share/c1/c1_IR.cpp
index 7f006c0b3ff..ae8332116b3 100644
--- a/src/hotspot/share/c1/c1_IR.cpp
+++ b/src/hotspot/share/c1/c1_IR.cpp
@@ -25,8 +25,8 @@
 #include "c1/c1_Compilation.hpp"
 #include "c1/c1_FrameMap.hpp"
 #include "c1/c1_GraphBuilder.hpp"
-#include "c1/c1_IR.hpp"
 #include "c1/c1_InstructionPrinter.hpp"
+#include "c1/c1_IR.hpp"
 #include "c1/c1_Optimizer.hpp"
 #include "compiler/oopMap.hpp"
 #include "memory/resourceArea.hpp"
diff --git a/src/hotspot/share/c1/c1_Instruction.cpp b/src/hotspot/share/c1/c1_Instruction.cpp
index 92affba99b2..3a7edef0088 100644
--- a/src/hotspot/share/c1/c1_Instruction.cpp
+++ b/src/hotspot/share/c1/c1_Instruction.cpp
@@ -22,9 +22,9 @@
  *
  */
 
-#include "c1/c1_IR.hpp"
 #include "c1/c1_Instruction.hpp"
 #include "c1/c1_InstructionPrinter.hpp"
+#include "c1/c1_IR.hpp"
 #include "c1/c1_ValueStack.hpp"
 #include "ci/ciObjArrayKlass.hpp"
 #include "ci/ciTypeArrayKlass.hpp"
diff --git a/src/hotspot/share/c1/c1_InstructionPrinter.cpp b/src/hotspot/share/c1/c1_InstructionPrinter.cpp
index 633c5e575c2..59e24c3e6c5 100644
--- a/src/hotspot/share/c1/c1_InstructionPrinter.cpp
+++ b/src/hotspot/share/c1/c1_InstructionPrinter.cpp
@@ -22,12 +22,12 @@
  *
  */
 
-#include "classfile/vmSymbols.hpp"
 #include "c1/c1_InstructionPrinter.hpp"
 #include "c1/c1_ValueStack.hpp"
 #include "ci/ciArray.hpp"
 #include "ci/ciInstance.hpp"
 #include "ci/ciObject.hpp"
+#include "classfile/vmSymbols.hpp"
 
 
 #ifndef PRODUCT
diff --git a/src/hotspot/share/c1/c1_InstructionPrinter.hpp b/src/hotspot/share/c1/c1_InstructionPrinter.hpp
index 6bc31d3fe55..b7bac561327 100644
--- a/src/hotspot/share/c1/c1_InstructionPrinter.hpp
+++ b/src/hotspot/share/c1/c1_InstructionPrinter.hpp
@@ -25,8 +25,8 @@
 #ifndef SHARE_C1_C1_INSTRUCTIONPRINTER_HPP
 #define SHARE_C1_C1_INSTRUCTIONPRINTER_HPP
 
-#include "c1/c1_IR.hpp"
 #include "c1/c1_Instruction.hpp"
+#include "c1/c1_IR.hpp"
 #include "c1/c1_Runtime1.hpp"
 
 #ifndef PRODUCT
diff --git a/src/hotspot/share/c1/c1_LinearScan.cpp b/src/hotspot/share/c1/c1_LinearScan.cpp
index 57c592f3506..3736284892f 100644
--- a/src/hotspot/share/c1/c1_LinearScan.cpp
+++ b/src/hotspot/share/c1/c1_LinearScan.cpp
@@ -27,8 +27,8 @@
 #include "c1/c1_Compilation.hpp"
 #include "c1/c1_FrameMap.hpp"
 #include "c1/c1_IR.hpp"
-#include "c1/c1_LIRGenerator.hpp"
 #include "c1/c1_LinearScan.hpp"
+#include "c1/c1_LIRGenerator.hpp"
 #include "c1/c1_ValueStack.hpp"
 #include "code/vmreg.inline.hpp"
 #include "runtime/timerTrace.hpp"
diff --git a/src/hotspot/share/c1/c1_LinearScan.hpp b/src/hotspot/share/c1/c1_LinearScan.hpp
index 7a56f3e92f4..36d84a4fad9 100644
--- a/src/hotspot/share/c1/c1_LinearScan.hpp
+++ b/src/hotspot/share/c1/c1_LinearScan.hpp
@@ -26,8 +26,8 @@
 #define SHARE_C1_C1_LINEARSCAN_HPP
 
 #include "c1/c1_FrameMap.hpp"
-#include "c1/c1_IR.hpp"
 #include "c1/c1_Instruction.hpp"
+#include "c1/c1_IR.hpp"
 #include "c1/c1_LIR.hpp"
 #include "c1/c1_LIRGenerator.hpp"
 #include "compiler/oopMap.hpp"
diff --git a/src/hotspot/share/c1/c1_Optimizer.cpp b/src/hotspot/share/c1/c1_Optimizer.cpp
index 721ad1d9ff5..0c18694df78 100644
--- a/src/hotspot/share/c1/c1_Optimizer.cpp
+++ b/src/hotspot/share/c1/c1_Optimizer.cpp
@@ -25,9 +25,9 @@
 #include "c1/c1_Optimizer.hpp"
 #include "c1/c1_ValueSet.hpp"
 #include "c1/c1_ValueStack.hpp"
+#include "compiler/compileLog.hpp"
 #include "memory/resourceArea.hpp"
 #include "utilities/bitMap.inline.hpp"
-#include "compiler/compileLog.hpp"
 
 typedef GrowableArray<ValueSet*> ValueSetList;
 
diff --git a/src/hotspot/share/c1/c1_Optimizer.hpp b/src/hotspot/share/c1/c1_Optimizer.hpp
index 542ee8acbd0..c26b7534bca 100644
--- a/src/hotspot/share/c1/c1_Optimizer.hpp
+++ b/src/hotspot/share/c1/c1_Optimizer.hpp
@@ -25,8 +25,8 @@
 #ifndef SHARE_C1_C1_OPTIMIZER_HPP
 #define SHARE_C1_C1_OPTIMIZER_HPP
 
-#include "c1/c1_IR.hpp"
 #include "c1/c1_Instruction.hpp"
+#include "c1/c1_IR.hpp"
 
 class Optimizer {
  private:
diff --git a/src/hotspot/share/c1/c1_RangeCheckElimination.cpp b/src/hotspot/share/c1/c1_RangeCheckElimination.cpp
index 6320fc15efe..1adf99cce61 100644
--- a/src/hotspot/share/c1/c1_RangeCheckElimination.cpp
+++ b/src/hotspot/share/c1/c1_RangeCheckElimination.cpp
@@ -22,9 +22,9 @@
  *
  */
 
-#include "c1/c1_ValueStack.hpp"
-#include "c1/c1_RangeCheckElimination.hpp"
 #include "c1/c1_IR.hpp"
+#include "c1/c1_RangeCheckElimination.hpp"
+#include "c1/c1_ValueStack.hpp"
 #include "ci/ciMethodData.hpp"
 #include "runtime/deoptimization.hpp"
 #include "utilities/bitMap.inline.hpp"
diff --git a/src/hotspot/share/c1/c1_Runtime1.cpp b/src/hotspot/share/c1/c1_Runtime1.cpp
index bb0fdf00565..d7a9c8d56d4 100644
--- a/src/hotspot/share/c1/c1_Runtime1.cpp
+++ b/src/hotspot/share/c1/c1_Runtime1.cpp
@@ -49,8 +49,8 @@
 #include "memory/resourceArea.hpp"
 #include "memory/universe.hpp"
 #include "oops/access.inline.hpp"
-#include "oops/objArrayOop.inline.hpp"
 #include "oops/objArrayKlass.hpp"
+#include "oops/objArrayOop.inline.hpp"
 #include "oops/oop.inline.hpp"
 #include "prims/jvmtiExport.hpp"
 #include "runtime/atomic.hpp"
diff --git a/src/hotspot/share/c1/c1_ValueStack.cpp b/src/hotspot/share/c1/c1_ValueStack.cpp
index f1ac940bf16..9a09c186541 100644
--- a/src/hotspot/share/c1/c1_ValueStack.cpp
+++ b/src/hotspot/share/c1/c1_ValueStack.cpp
@@ -22,8 +22,8 @@
  *
  */
 
-#include "c1/c1_IR.hpp"
 #include "c1/c1_InstructionPrinter.hpp"
+#include "c1/c1_IR.hpp"
 #include "c1/c1_ValueStack.hpp"
 
 
diff --git a/src/hotspot/share/ci/bcEscapeAnalyzer.cpp b/src/hotspot/share/ci/bcEscapeAnalyzer.cpp
index cf7b839c982..712f7af4139 100644
--- a/src/hotspot/share/ci/bcEscapeAnalyzer.cpp
+++ b/src/hotspot/share/ci/bcEscapeAnalyzer.cpp
@@ -22,12 +22,12 @@
  *
  */
 
-#include "classfile/vmIntrinsics.hpp"
 #include "ci/bcEscapeAnalyzer.hpp"
 #include "ci/ciConstant.hpp"
 #include "ci/ciField.hpp"
 #include "ci/ciMethodBlocks.hpp"
 #include "ci/ciStreams.hpp"
+#include "classfile/vmIntrinsics.hpp"
 #include "compiler/compiler_globals.hpp"
 #include "interpreter/bytecode.hpp"
 #include "oops/oop.inline.hpp"
diff --git a/src/hotspot/share/ci/bcEscapeAnalyzer.hpp b/src/hotspot/share/ci/bcEscapeAnalyzer.hpp
index 925635f4fdc..27fb5cf1323 100644
--- a/src/hotspot/share/ci/bcEscapeAnalyzer.hpp
+++ b/src/hotspot/share/ci/bcEscapeAnalyzer.hpp
@@ -26,9 +26,9 @@
 #define SHARE_CI_BCESCAPEANALYZER_HPP
 
 #ifdef COMPILER2
-#include "ci/ciObject.hpp"
 #include "ci/ciMethod.hpp"
 #include "ci/ciMethodData.hpp"
+#include "ci/ciObject.hpp"
 #include "code/dependencies.hpp"
 #include "libadt/vectset.hpp"
 #include "memory/allocation.hpp"
diff --git a/src/hotspot/share/ci/ciCallSite.cpp b/src/hotspot/share/ci/ciCallSite.cpp
index 3271e4ea7c7..c46758c0512 100644
--- a/src/hotspot/share/ci/ciCallSite.cpp
+++ b/src/hotspot/share/ci/ciCallSite.cpp
@@ -22,9 +22,9 @@
  *
  */
 
-#include "classfile/javaClasses.inline.hpp"
 #include "ci/ciCallSite.hpp"
 #include "ci/ciUtilities.inline.hpp"
+#include "classfile/javaClasses.inline.hpp"
 
 // ciCallSite
 
diff --git a/src/hotspot/share/ci/ciEnv.cpp b/src/hotspot/share/ci/ciEnv.cpp
index 2a88154faf6..3991773d86f 100644
--- a/src/hotspot/share/ci/ciEnv.cpp
+++ b/src/hotspot/share/ci/ciEnv.cpp
@@ -42,8 +42,8 @@
 #include "compiler/compilationLog.hpp"
 #include "compiler/compilationPolicy.hpp"
 #include "compiler/compileBroker.hpp"
-#include "compiler/compilerEvent.hpp"
 #include "compiler/compileLog.hpp"
+#include "compiler/compilerEvent.hpp"
 #include "compiler/compileTask.hpp"
 #include "compiler/disassembler.hpp"
 #include "gc/shared/collectedHeap.inline.hpp"
diff --git a/src/hotspot/share/ci/ciEnv.hpp b/src/hotspot/share/ci/ciEnv.hpp
index 6c66633ee17..a22975c7453 100644
--- a/src/hotspot/share/ci/ciEnv.hpp
+++ b/src/hotspot/share/ci/ciEnv.hpp
@@ -31,9 +31,9 @@
 #include "code/debugInfoRec.hpp"
 #include "code/dependencies.hpp"
 #include "code/exceptionHandlerTable.hpp"
+#include "compiler/cHeapStringHolder.hpp"
 #include "compiler/compiler_globals.hpp"
 #include "compiler/compilerThread.hpp"
-#include "compiler/cHeapStringHolder.hpp"
 #include "oops/methodData.hpp"
 #include "runtime/javaThread.hpp"
 
diff --git a/src/hotspot/share/ci/ciInstance.cpp b/src/hotspot/share/ci/ciInstance.cpp
index edd8f8b0f40..ad456ba6726 100644
--- a/src/hotspot/share/ci/ciInstance.cpp
+++ b/src/hotspot/share/ci/ciInstance.cpp
@@ -22,13 +22,13 @@
  *
  */
 
-#include "classfile/javaClasses.inline.hpp"
 #include "ci/ciConstant.hpp"
 #include "ci/ciField.hpp"
 #include "ci/ciInstance.hpp"
 #include "ci/ciInstanceKlass.hpp"
 #include "ci/ciNullObject.hpp"
 #include "ci/ciUtilities.inline.hpp"
+#include "classfile/javaClasses.inline.hpp"
 #include "classfile/vmClasses.hpp"
 #include "oops/oop.inline.hpp"
 
diff --git a/src/hotspot/share/ci/ciInstanceKlass.cpp b/src/hotspot/share/ci/ciInstanceKlass.cpp
index e8d71b32b68..a24a68f874b 100644
--- a/src/hotspot/share/ci/ciInstanceKlass.cpp
+++ b/src/hotspot/share/ci/ciInstanceKlass.cpp
@@ -31,10 +31,10 @@
 #include "memory/allocation.hpp"
 #include "memory/allocation.inline.hpp"
 #include "memory/resourceArea.hpp"
+#include "oops/fieldStreams.inline.hpp"
 #include "oops/instanceKlass.inline.hpp"
 #include "oops/klass.inline.hpp"
 #include "oops/oop.inline.hpp"
-#include "oops/fieldStreams.inline.hpp"
 #include "runtime/fieldDescriptor.inline.hpp"
 #include "runtime/handles.inline.hpp"
 #include "runtime/jniHandles.inline.hpp"
diff --git a/src/hotspot/share/ci/ciMethod.cpp b/src/hotspot/share/ci/ciMethod.cpp
index 96cb0bb9040..3b2670c3eb0 100644
--- a/src/hotspot/share/ci/ciMethod.cpp
+++ b/src/hotspot/share/ci/ciMethod.cpp
@@ -28,9 +28,9 @@
 #include "ci/ciMethod.hpp"
 #include "ci/ciMethodBlocks.hpp"
 #include "ci/ciMethodData.hpp"
+#include "ci/ciReplay.hpp"
 #include "ci/ciStreams.hpp"
 #include "ci/ciSymbol.hpp"
-#include "ci/ciReplay.hpp"
 #include "ci/ciSymbols.hpp"
 #include "ci/ciUtilities.inline.hpp"
 #include "compiler/abstractCompiler.hpp"
diff --git a/src/hotspot/share/ci/ciReplay.cpp b/src/hotspot/share/ci/ciReplay.cpp
index 669f316463c..d490b75919d 100644
--- a/src/hotspot/share/ci/ciReplay.cpp
+++ b/src/hotspot/share/ci/ciReplay.cpp
@@ -22,10 +22,10 @@
  *
  */
 
+#include "ci/ciKlass.hpp"
 #include "ci/ciMethodData.hpp"
 #include "ci/ciReplay.hpp"
 #include "ci/ciSymbol.hpp"
-#include "ci/ciKlass.hpp"
 #include "ci/ciUtilities.inline.hpp"
 #include "classfile/javaClasses.hpp"
 #include "classfile/symbolTable.hpp"
diff --git a/src/hotspot/share/ci/ciUtilities.cpp b/src/hotspot/share/ci/ciUtilities.cpp
index 203099bcf3f..0c5b4d9824f 100644
--- a/src/hotspot/share/ci/ciUtilities.cpp
+++ b/src/hotspot/share/ci/ciUtilities.cpp
@@ -23,8 +23,8 @@
  */
 
 #include "ci/ciUtilities.hpp"
-#include "gc/shared/cardTableBarrierSet.hpp"
 #include "gc/shared/cardTable.hpp"
+#include "gc/shared/cardTableBarrierSet.hpp"
 #include "gc/shared/collectedHeap.hpp"
 #include "gc/shared/gc_globals.hpp"
 
diff --git a/src/hotspot/share/compiler/compilationFailureInfo.cpp b/src/hotspot/share/compiler/compilationFailureInfo.cpp
index aaa9cb79d12..3940b4849f6 100644
--- a/src/hotspot/share/compiler/compilationFailureInfo.cpp
+++ b/src/hotspot/share/compiler/compilationFailureInfo.cpp
@@ -33,12 +33,12 @@
 #include "compiler/compilationFailureInfo.hpp"
 #include "compiler/compileTask.hpp"
 #ifdef COMPILER2
-#include "opto/node.hpp"
 #include "opto/compile.hpp"
+#include "opto/node.hpp"
 #endif
 #include "runtime/os.hpp"
-#include "utilities/ostream.hpp"
 #include "utilities/nativeCallStack.hpp"
+#include "utilities/ostream.hpp"
 
 int CompilationFailureInfo::current_compile_id_or_0() {
   ciEnv* env = ciEnv::current();
diff --git a/src/hotspot/share/compiler/compilationPolicy.cpp b/src/hotspot/share/compiler/compilationPolicy.cpp
index e9ae528d0a0..fa18b3c8ab4 100644
--- a/src/hotspot/share/compiler/compilationPolicy.cpp
+++ b/src/hotspot/share/compiler/compilationPolicy.cpp
@@ -28,8 +28,8 @@
 #include "compiler/compilerDefinitions.inline.hpp"
 #include "compiler/compilerOracle.hpp"
 #include "memory/resourceArea.hpp"
-#include "oops/methodData.hpp"
 #include "oops/method.inline.hpp"
+#include "oops/methodData.hpp"
 #include "oops/oop.inline.hpp"
 #include "prims/jvmtiExport.hpp"
 #include "runtime/arguments.hpp"
diff --git a/src/hotspot/share/compiler/compileBroker.cpp b/src/hotspot/share/compiler/compileBroker.cpp
index 588a9051b66..168679feb9b 100644
--- a/src/hotspot/share/compiler/compileBroker.cpp
+++ b/src/hotspot/share/compiler/compileBroker.cpp
@@ -39,15 +39,15 @@
 #include "compiler/directivesParser.hpp"
 #include "gc/shared/memAllocator.hpp"
 #include "interpreter/linkResolver.hpp"
-#include "jvm.h"
 #include "jfr/jfrEvents.hpp"
+#include "jvm.h"
 #include "logging/log.hpp"
 #include "logging/logStream.hpp"
 #include "memory/allocation.inline.hpp"
 #include "memory/resourceArea.hpp"
 #include "memory/universe.hpp"
-#include "oops/methodData.hpp"
 #include "oops/method.inline.hpp"
+#include "oops/methodData.hpp"
 #include "oops/oop.inline.hpp"
 #include "prims/jvmtiExport.hpp"
 #include "prims/nativeLookup.hpp"
diff --git a/src/hotspot/share/compiler/compileBroker.hpp b/src/hotspot/share/compiler/compileBroker.hpp
index ac62a20bc6f..77662692f56 100644
--- a/src/hotspot/share/compiler/compileBroker.hpp
+++ b/src/hotspot/share/compiler/compileBroker.hpp
@@ -27,9 +27,9 @@
 
 #include "ci/compilerInterface.hpp"
 #include "compiler/abstractCompiler.hpp"
-#include "compiler/compileTask.hpp"
 #include "compiler/compilerDirectives.hpp"
 #include "compiler/compilerThread.hpp"
+#include "compiler/compileTask.hpp"
 #include "runtime/atomic.hpp"
 #include "runtime/perfDataTypes.hpp"
 #include "utilities/stack.hpp"
diff --git a/src/hotspot/share/compiler/compileTask.cpp b/src/hotspot/share/compiler/compileTask.cpp
index 6668f212b21..87d4a11e528 100644
--- a/src/hotspot/share/compiler/compileTask.cpp
+++ b/src/hotspot/share/compiler/compileTask.cpp
@@ -23,10 +23,10 @@
  */
 
 #include "compiler/compilationPolicy.hpp"
-#include "compiler/compileTask.hpp"
-#include "compiler/compileLog.hpp"
 #include "compiler/compileBroker.hpp"
+#include "compiler/compileLog.hpp"
 #include "compiler/compilerDirectives.hpp"
+#include "compiler/compileTask.hpp"
 #include "logging/log.hpp"
 #include "logging/logStream.hpp"
 #include "memory/resourceArea.hpp"
diff --git a/src/hotspot/share/compiler/compilerDefinitions.inline.hpp b/src/hotspot/share/compiler/compilerDefinitions.inline.hpp
index 45df9b0b8b0..fe17b77535f 100644
--- a/src/hotspot/share/compiler/compilerDefinitions.inline.hpp
+++ b/src/hotspot/share/compiler/compilerDefinitions.inline.hpp
@@ -26,6 +26,7 @@
 #define SHARE_COMPILER_COMPILERDEFINITIONS_INLINE_HPP
 
 #include "compiler/compilerDefinitions.hpp"
+
 #include "compiler/compiler_globals.hpp"
 #include "runtime/arguments.hpp"
 
diff --git a/src/hotspot/share/compiler/compilerDirectives.hpp b/src/hotspot/share/compiler/compilerDirectives.hpp
index 74e3d8b9b38..27c71b1723c 100644
--- a/src/hotspot/share/compiler/compilerDirectives.hpp
+++ b/src/hotspot/share/compiler/compilerDirectives.hpp
@@ -25,8 +25,8 @@
 #ifndef SHARE_COMPILER_COMPILERDIRECTIVES_HPP
 #define SHARE_COMPILER_COMPILERDIRECTIVES_HPP
 
-#include "classfile/vmIntrinsics.hpp"
 #include "ci/ciMethod.hpp"
+#include "classfile/vmIntrinsics.hpp"
 #include "compiler/methodMatcher.hpp"
 #include "opto/phasetype.hpp"
 #include "utilities/bitMap.hpp"
diff --git a/src/hotspot/share/compiler/compilerThread.cpp b/src/hotspot/share/compiler/compilerThread.cpp
index 55dd8383ac4..4034e63bc10 100644
--- a/src/hotspot/share/compiler/compilerThread.cpp
+++ b/src/hotspot/share/compiler/compilerThread.cpp
@@ -23,8 +23,8 @@
  */
 
 #include "compiler/compileBroker.hpp"
-#include "compiler/compileTask.hpp"
 #include "compiler/compilerThread.hpp"
+#include "compiler/compileTask.hpp"
 #include "runtime/javaThread.inline.hpp"
 
 // Create a CompilerThread
diff --git a/src/hotspot/share/compiler/directivesParser.cpp b/src/hotspot/share/compiler/directivesParser.cpp
index 72cc0612c49..a2da7c7e0e4 100644
--- a/src/hotspot/share/compiler/directivesParser.cpp
+++ b/src/hotspot/share/compiler/directivesParser.cpp
@@ -30,6 +30,7 @@
 #include "opto/traceAutoVectorizationTag.hpp"
 #include "opto/traceMergeStoresTag.hpp"
 #include "runtime/os.hpp"
+
 #include <string.h>
 
 void DirectivesParser::push_tmp(CompilerDirectives* dir) {
diff --git a/src/hotspot/share/compiler/directivesParser.hpp b/src/hotspot/share/compiler/directivesParser.hpp
index 3337186ec0e..d4763430eb9 100644
--- a/src/hotspot/share/compiler/directivesParser.hpp
+++ b/src/hotspot/share/compiler/directivesParser.hpp
@@ -25,8 +25,8 @@
 #ifndef SHARE_COMPILER_DIRECTIVESPARSER_HPP
 #define SHARE_COMPILER_DIRECTIVESPARSER_HPP
 
-#include "utilities/json.hpp"
 #include "compiler/compilerDirectives.hpp"
+#include "utilities/json.hpp"
 
 enum FlagType {
   boolFlag,
diff --git a/src/hotspot/share/compiler/disassembler.hpp b/src/hotspot/share/compiler/disassembler.hpp
index f3108b001f5..8e2ea3ce50d 100644
--- a/src/hotspot/share/compiler/disassembler.hpp
+++ b/src/hotspot/share/compiler/disassembler.hpp
@@ -25,13 +25,12 @@
 #ifndef SHARE_COMPILER_DISASSEMBLER_HPP
 #define SHARE_COMPILER_DISASSEMBLER_HPP
 
-#include "utilities/globalDefinitions.hpp"
-
 #include "asm/assembler.hpp"
 #include "code/codeBlob.hpp"
 #include "code/nmethod.hpp"
 #include "compiler/abstractDisassembler.hpp"
 #include "runtime/globals.hpp"
+#include "utilities/globalDefinitions.hpp"
 #include "utilities/macros.hpp"
 
 class decode_env;
diff --git a/src/hotspot/share/compiler/methodMatcher.hpp b/src/hotspot/share/compiler/methodMatcher.hpp
index bb34c81db7b..ba70747ad26 100644
--- a/src/hotspot/share/compiler/methodMatcher.hpp
+++ b/src/hotspot/share/compiler/methodMatcher.hpp
@@ -26,8 +26,8 @@
 #define SHARE_COMPILER_METHODMATCHER_HPP
 
 #include "memory/allocation.hpp"
-#include "runtime/handles.hpp"
 #include "memory/resourceArea.hpp"
+#include "runtime/handles.hpp"
 
 class MethodMatcher : public CHeapObj<mtCompiler> {
  public:
diff --git a/src/hotspot/share/compiler/oopMap.inline.hpp b/src/hotspot/share/compiler/oopMap.inline.hpp
index 44d553be1fd..e64ae506115 100644
--- a/src/hotspot/share/compiler/oopMap.inline.hpp
+++ b/src/hotspot/share/compiler/oopMap.inline.hpp
@@ -31,6 +31,7 @@
 #include "runtime/frame.inline.hpp"
 #include "runtime/globals.hpp"
 #include "utilities/ostream.hpp"
+
 #if INCLUDE_JVMCI
 #include "jvmci/jvmci_globals.hpp"
 #endif
diff --git a/src/hotspot/share/jvmci/jvmci.cpp b/src/hotspot/share/jvmci/jvmci.cpp
index 609617b4a20..15973f4549f 100644
--- a/src/hotspot/share/jvmci/jvmci.cpp
+++ b/src/hotspot/share/jvmci/jvmci.cpp
@@ -23,12 +23,12 @@
 
 #include "classfile/systemDictionary.hpp"
 #include "compiler/abstractCompiler.hpp"
-#include "compiler/compileTask.hpp"
 #include "compiler/compilerThread.hpp"
+#include "compiler/compileTask.hpp"
 #include "gc/shared/collectedHeap.hpp"
 #include "jvmci/jvmci.hpp"
-#include "jvmci/jvmciJavaClasses.hpp"
 #include "jvmci/jvmciEnv.hpp"
+#include "jvmci/jvmciJavaClasses.hpp"
 #include "jvmci/jvmciRuntime.hpp"
 #include "jvmci/metadataHandles.hpp"
 #include "memory/resourceArea.hpp"
diff --git a/src/hotspot/share/jvmci/jvmciCompiler.cpp b/src/hotspot/share/jvmci/jvmciCompiler.cpp
index f3f68a00b4f..38bf9c438e7 100644
--- a/src/hotspot/share/jvmci/jvmciCompiler.cpp
+++ b/src/hotspot/share/jvmci/jvmciCompiler.cpp
@@ -21,11 +21,11 @@
  * questions.
  */
 
+#include "classfile/moduleEntry.hpp"
 #include "classfile/vmClasses.hpp"
+#include "classfile/vmSymbols.hpp"
 #include "compiler/compileBroker.hpp"
 #include "compiler/compilerDefinitions.inline.hpp"
-#include "classfile/moduleEntry.hpp"
-#include "classfile/vmSymbols.hpp"
 #include "jvmci/jvmciEnv.hpp"
 #include "jvmci/jvmciRuntime.hpp"
 #include "oops/objArrayOop.inline.hpp"
diff --git a/src/hotspot/share/jvmci/jvmciEnv.cpp b/src/hotspot/share/jvmci/jvmciEnv.cpp
index 8840863fc20..a23b09c3c1e 100644
--- a/src/hotspot/share/jvmci/jvmciEnv.cpp
+++ b/src/hotspot/share/jvmci/jvmciEnv.cpp
@@ -43,8 +43,8 @@
 #include "runtime/arguments.hpp"
 #include "runtime/deoptimization.hpp"
 #include "runtime/fieldDescriptor.inline.hpp"
-#include "runtime/jniHandles.inline.hpp"
 #include "runtime/javaCalls.hpp"
+#include "runtime/jniHandles.inline.hpp"
 #include "runtime/os.hpp"
 
 JVMCICompileState::JVMCICompileState(CompileTask* task, JVMCICompiler* compiler):
diff --git a/src/hotspot/share/jvmci/jvmciJavaClasses.cpp b/src/hotspot/share/jvmci/jvmciJavaClasses.cpp
index b8d3d4e3b7e..e5c0017129c 100644
--- a/src/hotspot/share/jvmci/jvmciJavaClasses.cpp
+++ b/src/hotspot/share/jvmci/jvmciJavaClasses.cpp
@@ -31,8 +31,8 @@
 #include "memory/resourceArea.hpp"
 #include "oops/instanceKlass.inline.hpp"
 #include "runtime/fieldDescriptor.inline.hpp"
-#include "runtime/jniHandles.inline.hpp"
 #include "runtime/java.hpp"
+#include "runtime/jniHandles.inline.hpp"
 
 // ------------------------------------------------------------------
 
diff --git a/src/hotspot/share/jvmci/jvmciRuntime.cpp b/src/hotspot/share/jvmci/jvmciRuntime.cpp
index 018824a03e9..8e885e5f7f9 100644
--- a/src/hotspot/share/jvmci/jvmciRuntime.cpp
+++ b/src/hotspot/share/jvmci/jvmciRuntime.cpp
@@ -30,8 +30,8 @@
 #include "gc/shared/memAllocator.hpp"
 #include "gc/shared/oopStorage.inline.hpp"
 #include "jvmci/jniAccessMark.inline.hpp"
-#include "jvmci/jvmciCompilerToVM.hpp"
 #include "jvmci/jvmciCodeInstaller.hpp"
+#include "jvmci/jvmciCompilerToVM.hpp"
 #include "jvmci/jvmciRuntime.hpp"
 #include "jvmci/metadataHandles.hpp"
 #include "logging/log.hpp"
diff --git a/test/hotspot/jtreg/TEST.groups b/test/hotspot/jtreg/TEST.groups
index 66c346712b0..5954be18c09 100644
--- a/test/hotspot/jtreg/TEST.groups
+++ b/test/hotspot/jtreg/TEST.groups
@@ -139,6 +139,7 @@ serviceability_ttf_virtual = \
   -serviceability/jvmti/negative
 
 tier1_common = \
+  sources \
   sanity/BasicVMTest.java \
   gtest/GTestWrapper.java \
   gtest/LockStackGtests.java \
@@ -623,16 +624,12 @@ tier1_serviceability = \
   -serviceability/sa/TestJmapCore.java \
   -serviceability/sa/TestJmapCoreMetaspace.java
 
-tier1_sources = \
-   sources
-
 tier1 = \
   :tier1_common \
   :tier1_compiler \
   :tier1_gc \
   :tier1_runtime \
   :tier1_serviceability \
-  :tier1_sources
 
 tier2 = \
   :hotspot_tier2_runtime \
diff --git a/test/hotspot/jtreg/sources/SortIncludes.java b/test/hotspot/jtreg/sources/SortIncludes.java
new file mode 100644
index 00000000000..222ca05d836
--- /dev/null
+++ b/test/hotspot/jtreg/sources/SortIncludes.java
@@ -0,0 +1,235 @@
+
+/*
+ * Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.List;
+import java.util.SortedSet;
+import java.util.TreeSet;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import java.util.stream.Collectors;
+
+/// See [#main].
+public class SortIncludes {
+    private static final String INCLUDE_LINE = "^ *# *include *(<[^>]+>|\"[^\"]+\") *$\\n";
+    private static final String BLANK_LINE = "^$\\n";
+    private static final Pattern INCLUDES_RE = Pattern.compile(
+                    String.format("%s(?:(?:%s)*%s)*", INCLUDE_LINE, BLANK_LINE, INCLUDE_LINE),
+                    Pattern.MULTILINE);
+
+    /// Gets a sorting key for an include which is its substring as of `delim`, lowercased.
+    /// Note that using lowercase will sort `_` before letters.
+    private static Comparator<String> sortKeyForInclude(char delim) {
+        return Comparator.comparing(s -> s.toLowerCase().substring(s.indexOf(delim)));
+    }
+
+    /// Gets the first substring in `s` enclosed by `start` and `end`.
+    private static String extract(String s, char start, char end) {
+        int startIndex = s.indexOf(start);
+        int endIndex = s.indexOf(end, startIndex + 1);
+        if (startIndex == -1 || endIndex == -1) {
+            throw new IllegalArgumentException(s);
+        }
+        return s.substring(startIndex + 1, endIndex);
+    }
+
+    /// Sorts the include statements in `block`.
+    ///
+    /// @param path path of the file containing `block`
+    /// @param block source code chunk containing 1 or more include statements
+    /// @return `block` with the include statements sorted and a blank line between user and
+    /// sys includes
+    private static String sortedIncludes(Path path, String block) {
+        String[] lines = block.split("\\n");
+        SortedSet<String> userIncludes = new TreeSet<>(sortKeyForInclude('"'));
+        SortedSet<String> sysIncludes = new TreeSet<>(sortKeyForInclude('<'));
+
+        // From the style guide:
+        //
+        // All .inline.hpp files should include their corresponding .hpp file
+        // as the first include line with a blank line separating it from the
+        // rest of the include lines. Declarations needed by other files should
+        // be put in the .hpp file, and not in the .inline.hpp file. This rule
+        // exists to resolve problems with circular dependencies between
+        // .inline.hpp files.
+        String pathString = path.toString();
+        boolean isInlineHpp = pathString.endsWith(".inline.hpp");
+        String nonInlineHpp = pathString.replace(".inline.hpp", ".hpp");
+        if (File.separatorChar != '/') {
+            nonInlineHpp = nonInlineHpp.replace(File.separatorChar, '/');
+        }
+
+        List<String> result = new ArrayList<>(lines.length);
+
+        // Partition lines into user include and sys includes and discard blank lines
+        for (String line : lines) {
+            if (line.contains("\"")) {
+                if (isInlineHpp && nonInlineHpp.endsWith(extract(line, '"', '"'))) {
+                    result.add(line);
+                } else {
+                    userIncludes.add(line);
+                }
+            } else if (line.contains("<")) {
+                sysIncludes.add(line);
+            }
+        }
+
+        if (!result.isEmpty() && (!userIncludes.isEmpty() || !sysIncludes.isEmpty())) {
+            // Insert blank line between include of .hpp from .inline.hpp
+            // and the rest of the includes
+            result.add("");
+        }
+        result.addAll(userIncludes);
+        if (!userIncludes.isEmpty() && !sysIncludes.isEmpty()) {
+            // Insert blank line between user and sys includes
+            result.add("");
+        }
+        result.addAll(sysIncludes);
+
+        return String.join("\n", result) + "\n";
+    }
+
+    /// Processes the C++ source file in `path` to sort its include statements.
+    ///
+    /// @param path a path of a C++ source file
+    /// @param update updates the source file if sorting changed its content
+    /// @return `true` if sorting changes were made,`false` otherwise
+    public static boolean sortIncludes(Path path, boolean update) throws IOException {
+        String source = Files.readString(path);
+        Matcher matcher = INCLUDES_RE.matcher(source);
+        StringBuilder buf = new StringBuilder();
+        int end = 0;
+
+        while (matcher.find()) {
+            if (matcher.start() != end) {
+                buf.append(source, end, matcher.start());
+            }
+            buf.append(sortedIncludes(path, matcher.group()));
+            end = matcher.end();
+        }
+
+        if (end == 0) {
+            return false;
+        }
+        buf.append(source.substring(end));
+
+        String newSource = buf.toString();
+        if (!newSource.equals(source)) {
+            if (update) {
+                Files.writeString(path, newSource);
+            }
+            return true;
+        }
+        return false;
+    }
+
+    /// Record of the files processed by [#process(List, boolean)] and those
+    /// that had unsorted includes.
+    public record Result(List<Path> files, List<Path> unsorted) {
+    }
+
+    /// Processes the C++ source files in `paths` to check if their include statements are sorted.
+    /// Include statements with any non-space characters after the closing `"` or `>` will not
+    /// be re-ordered.
+    ///
+    /// @param paths list of directory and file paths
+    /// @param update if `true`, files with unsorted includes are updated to sort the includes
+    /// @return the files that had unsorted include statements.
+    public static Result process(List<Path> paths, boolean update) throws IOException {
+        List<Path> files = new ArrayList<>();
+        for (Path path : paths) {
+            if (Files.isRegularFile(path)) {
+                files.add(path);
+            } else {
+                Files.walk(path).forEach(p -> {
+                    if (Files.isRegularFile(p)) {
+                        String name = p.getFileName().toString();
+                        if (name.endsWith(".cpp") || name.endsWith(".hpp")) {
+                            files.add(p);
+                        }
+                    }
+                });
+            }
+        }
+
+        List<Path> unsorted = new ArrayList<>();
+        for (Path file : files) {
+            if (sortIncludes(file, update)) {
+                unsorted.add(file);
+            }
+        }
+        return new Result(files, unsorted);
+    }
+
+    /// Exception thrown by [#main] if `"--update"` is in `args` and
+    /// files with unsorted includes were seen.
+    public static class UnsortedIncludesException extends Exception {
+        /// Files with unsorted includes.
+        public final List<Path> files;
+
+        public UnsortedIncludesException(List<Path> files) {
+            this.files = files;
+        }
+
+        @Override
+        public String getMessage() {
+            String unsorted = files.stream().map(Path::toString).collect(Collectors.joining(System.lineSeparator()));
+            return String.format("%d files with unsorted headers found:%n%s", files.size(), unsorted);
+        }
+    }
+
+    /// Processes C++ files to check if their include statements are sorted.
+    ///
+    /// @param args `[--update] dir|file...` where `update` means the processed
+    ///        files are updated to sort any unsorted includes and `dir|file` are the
+    ///        roots to scan for the C++ files to be processed
+    /// @throws UnsortedIncludesException if `args` includes `"--update"` and
+    ///         files with unsorted includes were found
+    public static void main(String[] args) throws IOException, UnsortedIncludesException {
+        boolean update = false;
+        List<Path> paths = new ArrayList<>();
+        for (String arg : args) {
+            if (arg.equals("--update")) {
+                update = true;
+            } else {
+                paths.add(Paths.get(arg));
+            }
+        }
+
+        Result result = process(paths, update);
+        if (update) {
+            System.out.printf("Processed %d files, updated %d to sort include statements%n",
+                            result.files.size(),
+                            result.unsorted().size());
+        } else if (!result.unsorted().isEmpty()) {
+            throw new UnsortedIncludesException(result.unsorted);
+        }
+    }
+}
diff --git a/test/hotspot/jtreg/sources/TestIncludesAreSorted.java b/test/hotspot/jtreg/sources/TestIncludesAreSorted.java
new file mode 100644
index 00000000000..34e8d5be5fd
--- /dev/null
+++ b/test/hotspot/jtreg/sources/TestIncludesAreSorted.java
@@ -0,0 +1,109 @@
+/*
+ * Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * @test
+ * @bug 8343802
+ * @summary Tests that HotSpot C++ files have sorted includes
+ * @build SortIncludes
+ * @run main TestIncludesAreSorted
+ */
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.stream.Stream;
+
+public class TestIncludesAreSorted {
+
+    /**
+     * The directories under {@code <jdk>/src/hotspot} to process. This list can be expanded over
+     * time until the point where it's simply "." (i.e. all HotSpot source files are compliant and
+     * can be checked).
+     */
+    private static final String[] HOTSPOT_SOURCES_TO_CHECK = {
+                    "share/c1",
+                    "share/ci",
+                    "share/compiler",
+                    "share/jvmci",
+    };
+
+    /**
+     * Gets the absolute path to {@code <jdk>/src/hotspot} by searching up the file system starting
+     * at {@code dir}.
+     */
+    private static Path getHotSpotSrcDir(Path dir) {
+        while (dir != null) {
+            Path path = dir.resolve("src").resolve("hotspot");
+            if (Files.exists(path)) {
+                return path;
+            }
+            dir = dir.getParent();
+        }
+        throw new RuntimeException("Could not locate the src/hotspot directory by searching up from " + dir);
+    }
+
+    public static void main(String[] ignore) throws IOException {
+        Path testSrcDir = Paths.get(System.getProperty("test.src"));
+        Path root = getHotSpotSrcDir(testSrcDir);
+        String[] args = Stream.of(HOTSPOT_SOURCES_TO_CHECK)//
+                        .map(root::resolve)
+                        .map(Path::toString)
+                        .toArray(String[]::new);
+        try {
+            SortIncludes.main(args);
+        } catch (SortIncludes.UnsortedIncludesException e) {
+            String msg = String.format("""
+                            %s
+
+                            This should be fixable by running:
+
+                                java %s.java --update %s
+
+
+                            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"
+
+                            """,
+                    e.getMessage(),
+                    testSrcDir.resolve(SortIncludes.class.getSimpleName()),
+                    String.join(" ", args));
+            throw new RuntimeException(msg);
+        }
+    }
+}