gh-130090: Support PGO for clang-cl

Misc/NEWS.d/next/Build/2025-02-13-19-21-41.gh-issue-130090.3ngJaV.rst

@@ -1,2 +1,2 @@
 Building with ``PlatformToolset=ClangCL`` on Windows now supports PGO
-(profile guided optimization). Patch by Chris Eibl.
+(profile guided optimization). Patch by Chris Eibl with invaluable support from Steve Dover.

PCbuild/pyproject-clangcl.props

@@ -39,6 +39,8 @@
   <ItemDefinitionGroup>
     <ClCompile>
       <AdditionalOptions>-Wno-deprecated-non-prototype -Wno-unused-label -Wno-pointer-sign -Wno-incompatible-pointer-types-discards-qualifiers -Wno-unused-function %(AdditionalOptions)</AdditionalOptions>
+      <AdditionalOptions Condition="'$(Platform)' == 'Win32'">-m32 %(AdditionalOptions)</AdditionalOptions>
+      <AdditionalOptions Condition="'$(Platform)' == 'x64'">-m64 %(AdditionalOptions)</AdditionalOptions>
       <AdditionalOptions Condition="$(Configuration) != 'Debug'">-flto %(AdditionalOptions)</AdditionalOptions>
       <AdditionalOptions Condition="$(SupportPGO) and $(Configuration) == 'PGInstrument'">-fprofile-instr-generate=$(_CLANG_PROFILE_PATH)$(TargetName)_%m.profraw %(AdditionalOptions)</AdditionalOptions>
       <AdditionalOptions Condition="$(SupportPGO) and $(Configuration) == 'PGUpdate'">-fprofile-instr-use=$(OutDir)instrumented\profdata.profdata -Wno-profile-instr-unprofiled %(AdditionalOptions)</AdditionalOptions>

PCbuild/readme.txt

@@ -61,29 +61,32 @@ You can use the IDE to switch to clang-cl for local development,
 but because this alters the *.vcxproj files, the recommended way is
 to use build.bat:
 
-build.bat "/p:PlatformToolset=ClangCL" "/p:PreferredToolArchitecture=x64"
+build.bat "/p:PlatformToolset=ClangCL"
 
 All other build.bat options continue to work as with MSVC, so this
-will create a 64bit release binary. PreferredToolArchitecture is needed,
-because msbuild by default selects the 32bit architecture of the toolset,
-which uses -m32 as the default target architecture.
+will create a 64bit release binary.
 
 You can also use a specific version of clang-cl downloaded from
 https://github.com/llvm/llvm-project/releases, e.g.
 clang+llvm-18.1.8-x86_64-pc-windows-msvc.tar.xz.
 Given you have extracted that to <my-clang-dir>, you can use it like so
 build.bat --pgo "/p:PlatformToolset=ClangCL" "/p:LLVMInstallDir=<my-clang-dir> "/p:LLVMToolsVersion=18"
 
-Here, PreferredToolArchitecture is not needed, because this is a 64bit
-platform toolset, but LLVMToolsVersion has to be set accordingly.
-Setting the major version is enough, although you can be specific
-and use 18.1.8 in the above example, too.
+Setting LLVMToolsVersion to the major version is enough, although you
+can be specific and use 18.1.8 in the above example, too.
 
-Even --pgo works out of the box. However, if you want to run the PGO task
+Use the --pgo option to build with PGO (Profile Guided Optimization).
+
+However, if you want to run the PGO task
 on a different host than the build host, you must pass
 "/p:CLANG_PROFILE_PATH=<relative-path-to-instrumented-dir-on-remote-host>"
 in the PGInstrument step to make sure the profile data is generated
 into the instrumented directory when running the PGO task.
+E.g., if you place the instrumented binaries into the folder
+"workdir/instrumented" and then run the PGO task using "workdir"
+as the current working directory, the usage is
+"/p:CLANG_PROFILE_PATH=workdir/instrumented"
+
 Like in the MSVC case, after fetching (or manually copying) the instrumented
 folder back into your build tree, you can continue with the PGUpdate
 step with no further parameters.