Merge #1681: doc: Recommend clang-cl when building on Windows

7379124 ci: Add more tests for clang-cl (Hennadii Stepanov)
7379a5b doc: Recommend clang-cl when building on Windows (Hennadii Stepanov)

Pull request description:

  There are several reasons to prefer clang-cl over MSVC, such as improved [security](#1164) and performance.

  Below are the benchmark results for the master branch @ 201b2b8:
  - using [MSVC](https://github.com/bitcoin-core/secp256k1/actions/runs/15439981265/job/43455271726):
  ```
  Benchmark                     ,    Min(us)    ,    Avg(us)    ,    Max(us)

  ecdsa_verify                  ,    66.0       ,    71.0       ,   113.0
  ecdsa_sign                    ,    37.0       ,    37.1       ,    37.5
  ec_keygen                     ,    28.5       ,    28.9       ,    29.0
  ecdh                          ,    66.0       ,    66.2       ,    67.0
  ecdsa_recover                 ,    67.0       ,    74.9       ,   123.0
  schnorrsig_sign               ,    30.0       ,    30.3       ,    30.5
  schnorrsig_verify             ,    66.5       ,    70.6       ,   104.0
  ellswift_encode               ,    17.5       ,    17.9       ,    18.0
  ellswift_decode               ,    14.5       ,    15.3       ,    19.0
  ellswift_keygen               ,    55.0       ,    56.4       ,    63.5
  ellswift_ecdh                 ,    72.5       ,    73.5       ,    79.5
  ```

  - using [clang-cl](https://github.com/bitcoin-core/secp256k1/actions/runs/15439981265/job/43455271749):
  ```
  Benchmark                     ,    Min(us)    ,    Avg(us)    ,    Max(us)

  ecdsa_verify                  ,    41.0       ,    47.5       ,   100.0
  ecdsa_sign                    ,    27.0       ,    27.2       ,    27.5
  ec_keygen                     ,    19.0       ,    19.3       ,    19.5
  ecdh                          ,    42.0       ,    42.4       ,    43.0
  ecdsa_recover                 ,    41.5       ,    45.7       ,    80.0
  schnorrsig_sign               ,    20.0       ,    20.5       ,    20.5
  schnorrsig_verify             ,    41.5       ,    45.5       ,    77.5
  ellswift_encode               ,    13.0       ,    13.0       ,    13.0
  ellswift_decode               ,    10.0       ,    10.4       ,    10.5
  ellswift_keygen               ,    38.5       ,    39.1       ,    41.5
  ellswift_ecdh                 ,    47.0       ,    48.5       ,    59.0
  ```

  On my local machine, the "Release" build configuration:
  - using MSVC:
  ```
  > .\build-msvc\bin\Release\bench.exe
  Benchmark                     ,    Min(us)    ,    Avg(us)    ,    Max(us)

  ecdsa_verify                  ,    81.2       ,    90.6       ,   102.0
  ecdsa_sign                    ,    46.5       ,    48.6       ,    52.9
  ec_keygen                     ,    31.6       ,    34.8       ,    36.2
  ecdh                          ,    73.0       ,    76.4       ,    79.5
  schnorrsig_sign               ,    32.1       ,    34.4       ,    35.8
  schnorrsig_verify             ,    74.6       ,    76.2       ,    79.8
  ellswift_encode               ,    33.4       ,    34.0       ,    34.8
  ellswift_decode               ,    14.9       ,    15.5       ,    17.1
  ellswift_keygen               ,    64.5       ,    65.6       ,    67.1
  ellswift_ecdh                 ,    78.3       ,    80.7       ,    90.1
  ```

  - using clang-cl:
  ```
  > .\build-clangcl\bin\Release\bench.exe
  Benchmark                     ,    Min(us)    ,    Avg(us)    ,    Max(us)

  ecdsa_verify                  ,    40.3       ,    40.6       ,    40.9
  ecdsa_sign                    ,    30.6       ,    30.9       ,    31.3
  ec_keygen                     ,    21.2       ,    21.3       ,    21.5
  ecdh                          ,    41.5       ,    42.4       ,    44.8
  schnorrsig_sign               ,    22.5       ,    22.7       ,    22.8
  schnorrsig_verify             ,    41.2       ,    41.4       ,    41.7
  ellswift_encode               ,    20.3       ,    20.6       ,    20.8
  ellswift_decode               ,     8.50      ,     8.64      ,     8.76
  ellswift_keygen               ,    41.7       ,    42.0       ,    42.4
  ellswift_ecdh                 ,    45.1       ,    45.5       ,    46.3
  ```

ACKs for top commit:
  real-or-random:
    utACK 7379124

Tree-SHA512: b0a4219cf24208e875a9757a490376af021dd3771911a670d80bb4979713bf1bbdbe206b8e121a3c4d1913c58f4b4593047410aa8104eff19aa3d3f359fd94af

Author: real-or-random

.github/workflows/ci.yml

@@ -631,8 +631,16 @@ jobs:
             cpp_flags: '/DSECP256K1_MSVC_MULH_TEST_OVERRIDE'
           - job_name: 'x86 (MSVC): Windows (VS 2022)'
             cmake_options: '-A Win32'
-          - job_name: 'x64 (MSVC): Windows (clang-cl)'
-            cmake_options: '-T ClangCL'
+          - job_name: 'x64 (clang-cl): Windows (VS 2022, shared)'
+            cmake_options: '-T ClangCL -DBUILD_SHARED_LIBS=ON'
+            symbol_check: 'true'
+          - job_name: 'x64 (clang-cl): Windows (VS 2022, static)'
+            cmake_options: '-T ClangCL -DBUILD_SHARED_LIBS=OFF'
+          - job_name: 'x64 (clang-cl): Windows (VS 2022, int128_struct)'
+            cmake_options: '-T ClangCL -DSECP256K1_TEST_OVERRIDE_WIDE_MULTIPLY=int128_struct'
+          - job_name: 'x64 (clang-cl): Windows (VS 2022, int128_struct with __(u)mulh)'
+            cmake_options: '-T ClangCL -DSECP256K1_TEST_OVERRIDE_WIDE_MULTIPLY=int128_struct'
+            cpp_flags: '/DSECP256K1_MSVC_MULH_TEST_OVERRIDE'
 
     steps:
       - name: Checkout

README.md

@@ -135,13 +135,11 @@ To cross compile for Android with [NDK](https://developer.android.com/ndk/guides
 
 ### Building on Windows
 
-To build on Windows with Visual Studio, a proper [generator](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators) must be specified for a new build tree.
-
-The following example assumes using of Visual Studio 2022 and CMake v3.21+.
+The following example assumes Visual Studio 2022. Using clang-cl is recommended.
 
 In "Developer Command Prompt for VS 2022":
 
-    >cmake -G "Visual Studio 17 2022" -A x64 -B build
+    >cmake -B build -T ClangCL
     >cmake --build build --config RelWithDebInfo
 
 Usage examples