Merge branch 'master' into 8347938

Makefile

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2012, 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
@@ -24,8 +24,9 @@
 #
 
 ###
-### This file is just a very small wrapper needed to run the real make/Init.gmk.
-### It also performs some sanity checks on make.
+### This file is just a very small wrapper which will include make/PreInit.gmk,
+### where the real work is done. This wrapper also performs some sanity checks
+### on make that must be done before we can include another file.
 ###
 
 # The shell code below will be executed on /usr/bin/make on Solaris, but not in GNU Make.
@@ -60,5 +61,5 @@ else
 endif
 topdir := $(strip $(patsubst %/, %, $(dir $(makefile_path))))
 
-# ... and then we can include the real makefile
-include $(topdir)/make/Init.gmk
+# ... and then we can include the real makefile to bootstrap the build
+include $(topdir)/make/PreInit.gmk

doc/hotspot-style.html

@@ -217,10 +217,10 @@ <h3 id="source-files">Source Files</h3>
 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>All .cpp files include precompiled.hpp as the first include
-line.</p></li>
-<li><p>precompiled.hpp is just a build time optimization, so don't rely
-on it to resolve include problems.</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
+don't rely on it to resolve include problems.</p></li>
 <li><p>Keep the include lines alphabetically sorted.</p></li>
 <li><p>Put conditional inclusions (<code>#if ...</code>) at the end of
 the include list.</p></li>

doc/hotspot-style.md

@@ -150,10 +150,10 @@ the first include line. 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.
 
-* All .cpp files include precompiled.hpp as the first include line.
-
-* precompiled.hpp is just a build time optimization, so don't rely on
-it to resolve include problems.
+* 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
+don't rely on it to resolve include problems.
 
 * Keep the include lines alphabetically sorted.