8264425: Update building.md on non-English locales on Windows

Reviewed-by: naoto, erikj

doc/building.html

@@ -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

doc/building.md

@@ -191,7 +191,8 @@ on different platforms.
 ### Windows
 
 Windows XP is not a supported platform, but all newer Windows should be able to
-build the JDK.
+build the JDK. (Note: The Windows 32-bit x86 port is deprecated and may be
+removed in a future release.)
 
 On Windows, it is important that you pay attention to the instructions in the
 [Special Considerations](#special-considerations).
@@ -209,8 +210,32 @@ rule also applies to input to the build system, e.g. in arguments to
 `--with-msvcr-dll=c:\msvcr100.dll`. For details on this conversion, see the
 section on [Fixpath](#fixpath).
 
-Note: The Windows 32-bit x86 port is deprecated and may be removed in a future
-release.
+#### Locale Requirements
+
+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
+`LC_*` 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.
+
+The **recommended** and **supported** way of building the JDK on Windows is to
+set both the system locale and the user locale to **US English**. The system
+setting can be changed by going to the Control Panel, choosing "Regional
+Settings" -> "Administrative" and then pressing on the "Change System Locale"
+button.
+
+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.
+
+It is also imperative to install the US English language pack in Visual Studio.
+For details, see [Microsoft Visual Studio](#microsoft-visual-studio).
 
 #### Cygwin
 
@@ -436,6 +461,32 @@ setting `--with-toolchain-version`, e.g. `--with-toolchain-version=2022`.
 If you have Visual Studio installed but `configure` fails to detect it, it may
 be because of [spaces in path](#spaces-in-path).
 
+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.
+
+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:
+
+* Click on "Visual Studio Installer" in Start menu.
+* Click "Modify".
+* Select the tab "Language packs".
+* Choose "English".
+* Click "Modify".
+
+or you can run it on the command line. For this to work, you need to start
+`cmd.exe` using "Run as Administrator". Then execute the following line: (note
+that the " characters are essential)
+
+```
+"C:\Program Files (x86)\Microsoft Visual Studio\Installer\vs_installer.exe" modify --channelId VisualStudio.16.Release --productId Microsoft.VisualStudio.Product.BuildTools --addProductLang en-us -p
+```
+
+`VisualStudio.16.Release` represent VS 2019, so adjust the version number
+accordingly. If you have not installed the `BuildTools`, but e.g.
+`Professional`, adjust the product ID accordingly.
+
 ### IBM XL C/C++
 
 Please consult the AIX section of the [Supported Build Platforms](