Merge branch 'master' into fg8320379

doc/building.html

@@ -49,7 +49,7 @@ <h1 class="title">Building the JDK</h1>
 <li><a href="#building-on-aarch64" id="toc-building-on-aarch64">Building
 on aarch64</a></li>
 <li><a href="#building-on-32-bit-arm"
-id="toc-building-on-32-bit-arm">Building on 32-bit arm</a></li>
+id="toc-building-on-32-bit-arm">Building on 32-bit ARM</a></li>
 </ul></li>
 <li><a href="#operating-system-requirements"
 id="toc-operating-system-requirements">Operating System Requirements</a>
@@ -74,7 +74,7 @@ <h1 class="title">Building the JDK</h1>
 JDK Requirements</a>
 <ul>
 <li><a href="#getting-jdk-binaries"
-id="toc-getting-jdk-binaries">Getting JDK binaries</a></li>
+id="toc-getting-jdk-binaries">Getting JDK Binaries</a></li>
 </ul></li>
 <li><a href="#external-library-requirements"
 id="toc-external-library-requirements">External Library Requirements</a>
@@ -116,7 +116,7 @@ <h1 class="title">Building the JDK</h1>
 <li><a href="#macos-1" id="toc-macos-1">macOS</a></li>
 </ul></li>
 <li><a href="#cross-compiling"
-id="toc-cross-compiling">Cross-compiling</a>
+id="toc-cross-compiling">Cross-Compiling</a>
 <ul>
 <li><a href="#specifying-the-target-platform"
 id="toc-specifying-the-target-platform">Specifying the Target
@@ -130,11 +130,11 @@ <h1 class="title">Building the JDK</h1>
 <li><a href="#verifying-the-build"
 id="toc-verifying-the-build">Verifying the Build</a></li>
 <li><a href="#cross-compiling-the-easy-way"
-id="toc-cross-compiling-the-easy-way">Cross compiling the easy
-way</a></li>
+id="toc-cross-compiling-the-easy-way">Cross-Compiling the Easy
+Way</a></li>
 <li><a href="#considerations-for-specific-targets"
-id="toc-considerations-for-specific-targets">Considerations for specific
-targets</a></li>
+id="toc-considerations-for-specific-targets">Considerations for Specific
+Targets</a></li>
 </ul></li>
 <li><a href="#build-performance" id="toc-build-performance">Build
 Performance</a>
@@ -146,9 +146,9 @@ <h1 class="title">Building the JDK</h1>
 <li><a href="#precompiled-headers"
 id="toc-precompiled-headers">Precompiled Headers</a></li>
 <li><a href="#icecc-icecream" id="toc-icecc-icecream">Icecc /
-icecream</a></li>
+Icecream</a></li>
 <li><a href="#using-the-javac-server"
-id="toc-using-the-javac-server">Using the javac server</a></li>
+id="toc-using-the-javac-server">Using the javac Server</a></li>
 <li><a href="#building-the-right-target"
 id="toc-building-the-right-target">Building the Right Target</a></li>
 </ul></li>
@@ -202,7 +202,7 @@ <h1 class="title">Building the JDK</h1>
 <li><a href="#contributing-to-the-jdk"
 id="toc-contributing-to-the-jdk">Contributing to the JDK</a></li>
 <li><a href="#editing-this-document"
-id="toc-editing-this-document">Editing this document</a></li>
+id="toc-editing-this-document">Editing This Document</a></li>
 </ul>
 </nav>
 <h2 id="tldr-instructions-for-the-impatient">TL;DR (Instructions for the
@@ -341,7 +341,7 @@ <h4 id="branch-protection">Branch Protection</h4>
 build can be run on both machines with and without support for branch
 protection in hardware. Branch Protection is only supported for Linux
 targets.</p>
-<h3 id="building-on-32-bit-arm">Building on 32-bit arm</h3>
+<h3 id="building-on-32-bit-arm">Building on 32-bit ARM</h3>
 <p>This is not recommended. Instead, see the section on <a
 href="#cross-compiling">Cross-compiling</a>.</p>
 <h2 id="operating-system-requirements">Operating System
@@ -390,7 +390,8 @@ <h2 id="operating-system-requirements">Operating System
 to list successes or failures of building on different platforms.</p>
 <h3 id="windows">Windows</h3>
 <p>Windows XP is not a supported platform, but all newer Windows should
-be able to build the JDK.</p>
+be able to build the JDK. (Note: The Windows 32-bit x86 port is
+deprecated and may be removed in a future release.)</p>
 <p>On Windows, it is important that you pay attention to the
 instructions in the <a href="#special-considerations">Special
 Considerations</a>.</p>
@@ -407,8 +408,31 @@ <h3 id="windows">Windows</h3>
 use <code>--with-msvcr-dll=/cygdrive/c/msvcr100.dll</code> rather than
 <code>--with-msvcr-dll=c:\msvcr100.dll</code>. For details on this
 conversion, see the section on <a href="#fixpath">Fixpath</a>.</p>
-<p>Note: The Windows 32-bit x86 port is deprecated and may be removed in
-a future release.</p>
+<h4 id="locale-requirements">Locale Requirements</h4>
+<p>Building and testing the JDK requires a well-defined locale to be
+guaranteed to run correctly. On non-Windows operating systems, this is
+achieved using the <code>LC_*</code> variables, which propagate to all
+child processes of the build. Unfortunately, there is no way to set the
+locale for a specific process like this in Windows. Instead, changes to
+locale can only be made globally, which will affect all applications run
+by the user. Furthermore, Windows makes a difference between user locale
+and system locale, where the latter determines e.g. the file path
+encoding. Both this locale settings affect building and testing the
+JDK.</p>
+<p>The <strong>recommended</strong> and <strong>supported</strong> way
+of building the JDK on Windows is to set both the system locale and the
+user locale to <strong>US English</strong>. The system setting can be
+changed by going to the Control Panel, choosing "Regional Settings"
+-&gt; "Administrative" and then pressing on the "Change System Locale"
+button.</p>
+<p>Since this is annoying for users who prefer another locale, we strive
+to get the building and testing to work on other locales as well. This
+is on a "best effort" level, so beware! You might get odd results in
+both building and testing. If you do, remember that locales other than
+US English are not supported nor recommended.</p>
+<p>It is also imperative to install the US English language pack in
+Visual Studio. For details, see <a
+href="#microsoft-visual-studio">Microsoft Visual Studio</a>.</p>
 <h4 id="cygwin">Cygwin</h4>
 <p>Install <a href="https://www.cygwin.com/">Cygwin</a> as instructed on
 the home page. It is strongly recommended to use the 64-bit version of
@@ -626,6 +650,27 @@ <h3 id="microsoft-visual-studio">Microsoft Visual Studio</h3>
 <p>If you have Visual Studio installed but <code>configure</code> fails
 to detect it, it may be because of <a href="#spaces-in-path">spaces in
 path</a>.</p>
+<p>You must install the US English locale, otherwise the build system
+might not be able to interact properly with the compiler. You can add
+additional language packs when installing Visual Studio.</p>
+<p>If you have already installed Visual Studio without the US English
+language pack, you can modify the installation to add this. You can
+either do this via a GUI like this:</p>
+<ul>
+<li>Click on "Visual Studio Installer" in Start menu.</li>
+<li>Click "Modify".</li>
+<li>Select the tab "Language packs".</li>
+<li>Choose "English".</li>
+<li>Click "Modify".</li>
+</ul>
+<p>or you can run it on the command line. For this to work, you need to
+start <code>cmd.exe</code> using "Run as Administrator". Then execute
+the following line: (note that the " characters are essential)</p>
+<pre><code>&quot;C:\Program Files (x86)\Microsoft Visual Studio\Installer\vs_installer.exe&quot; modify --channelId VisualStudio.16.Release --productId Microsoft.VisualStudio.Product.BuildTools --addProductLang en-us -p</code></pre>
+<p><code>VisualStudio.16.Release</code> represent VS 2019, so adjust the
+version number accordingly. If you have not installed the
+<code>BuildTools</code>, but e.g. <code>Professional</code>, adjust the
+product ID accordingly.</p>
 <h3 id="ibm-xl-cc">IBM XL C/C++</h3>
 <p>Please consult the AIX section of the <a
 href="https://wiki.openjdk.org/display/Build/Supported+Build+Platforms">Supported
@@ -653,7 +698,7 @@ <h2 id="boot-jdk-requirements">Boot JDK Requirements</h2>
 locations on most platforms, this heuristics has a high likelihood to
 fail. If the boot JDK is not automatically detected, or the wrong JDK is
 picked, use <code>--with-boot-jdk</code> to point to the JDK to use.</p>
-<h3 id="getting-jdk-binaries">Getting JDK binaries</h3>
+<h3 id="getting-jdk-binaries">Getting JDK Binaries</h3>
 <p>An overview of common ways to download and install prebuilt JDK
 binaries can be found on https://openjdk.org/install. An alternative is
 to download the <a
@@ -1188,7 +1233,7 @@ <h3 id="macos-1">macOS</h3>
 or the specified identity is valid. If hardened isn't possible, then
 <code>debug</code> signing is chosen if it works. If nothing works, the
 codesign build step is disabled.</p>
-<h2 id="cross-compiling">Cross-compiling</h2>
+<h2 id="cross-compiling">Cross-Compiling</h2>
 <p>Cross-compiling means using one platform (the <em>build</em>
 platform) to generate output that can ran on another platform (the
 <em>target</em> platform).</p>
@@ -1354,7 +1399,7 @@ <h3 id="verifying-the-build">Verifying the Build</h3>
 contain the newly built JDK, for your <em>target</em> system.</p>
 <p>Copy these folders to your <em>target</em> system. Then you can run
 e.g. <code>images/jdk/bin/java -version</code>.</p>
-<h3 id="cross-compiling-the-easy-way">Cross compiling the easy way</h3>
+<h3 id="cross-compiling-the-easy-way">Cross-Compiling the Easy Way</h3>
 <p>Setting up a proper cross-compilation environment can be a lot of
 work. Fortunately there are ways that more or less automate this
 process. Here are two recommended methods, using the "devkits" that can
@@ -1364,7 +1409,7 @@ <h3 id="cross-compiling-the-easy-way">Cross compiling the easy way</h3>
 solution only work for gcc.</p>
 <p>The devkit method is regularly used for testing by Oracle, and the
 debootstrap method is regularly used in GitHub Actions testing.</p>
-<h4 id="using-openjdk-devkits">Using OpenJDK devkits</h4>
+<h4 id="using-openjdk-devkits">Using OpenJDK Devkits</h4>
 <p>The JDK build system provides out-of-the box support for creating and
 using so called devkits. A <code>devkit</code> is basically a collection
 of a cross-compiling toolchain and a sysroot environment which can
@@ -1615,8 +1660,8 @@ <h4 id="using-debian-debootstrap">Using Debian debootstrap</h4>
 </tr>
 </tbody>
 </table>
-<h3 id="considerations-for-specific-targets">Considerations for specific
-targets</h3>
+<h3 id="considerations-for-specific-targets">Considerations for Specific
+Targets</h3>
 <h4 id="building-for-arm32">Building for ARM32</h4>
 <p>A common cross-compilation target is the ARM CPU. When building for
 ARM, it is recommended to set the ABI profile. A number of pre-defined
@@ -1727,15 +1772,15 @@ <h3 id="precompiled-headers">Precompiled Headers</h3>
 circumstances, it can actually slow things down.</p>
 <p>You can experiment by disabling pre-compiled headers using
 <code>--disable-precompiled-headers</code>.</p>
-<h3 id="icecc-icecream">Icecc / icecream</h3>
+<h3 id="icecc-icecream">Icecc / Icecream</h3>
 <p><a href="https://github.com/icecc/icecream">icecc/icecream</a> is a
 simple way to setup a distributed compiler network. If you have multiple
 machines available for building the JDK, you can drastically cut
 individual build times by utilizing it.</p>
 <p>To use, setup an icecc network, and install icecc on the build
 machine. Then run <code>configure</code> using
 <code>--enable-icecc</code>.</p>
-<h3 id="using-the-javac-server">Using the javac server</h3>
+<h3 id="using-the-javac-server">Using the javac Server</h3>
 <p>To speed up compilation of Java code, especially during incremental
 compilations, the javac server is automatically enabled in the
 configuration step by default. To explicitly enable or disable the javac
@@ -2411,7 +2456,7 @@ <h2 id="contributing-to-the-jdk">Contributing to the JDK</h2>
 your contribution.</p>
 <p>The official place to start is the <a
 href="https://openjdk.org/guide/">OpenJDK Developers’ Guide</a>.</p>
-<h2 id="editing-this-document">Editing this document</h2>
+<h2 id="editing-this-document">Editing This Document</h2>
 <p>If you want to contribute changes to this document, edit
 <code>doc/building.md</code> and then run
 <code>make update-build-docs</code> to generate the same changes in