8352645: Add tool support to check order of includes

Reviewed-by: stefank, kbarrett

Author: Doug Simon

doc/hotspot-style.html

@@ -207,27 +207,34 @@ <h3 id="source-files">Source Files</h3>
 <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

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

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"

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() {

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;

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"
 

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"

src/hotspot/share/c1/c1_Compilation.cpp

@@ -25,20 +25,19 @@
 #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"
 #include "c1/c1_ValueStack.hpp"
 #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"

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;

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"