doc: Recommend clang-cl when building on Windows

[hebasto]

There are several reasons to prefer clang-cl over MSVC, such as improved security and performance.

Below are the benchmark results for the master branch @ 201b2b8:

• using MSVC:

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:

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

[fanquake]

Are benchmarks all that should be considered? From what I can see there's there's only a single clang-cl CI job in this repo; if we're going to change the recommended way to build the library, then we should also replace the majority of the MSVC jobs, with clang-cl, to reflect that preference?

It would also be interesting to elaborate on why the performance of MSVC is so much worse than Clang.

[hebasto]

It would also be interesting to elaborate on why the performance of MSVC is so much worse than Clang.

Several factors may contribute to the performance gap:

1. Different optimization strategies.
2. Differences in inlining heuristics.
3. A number of other compiler‑level details.

However, I haven't compared the generated assembly code.

[hebasto]

It would also be interesting to elaborate on why the performance of MSVC is so much worse than Clang.

Another factor is that clang-cl uses native 128-bit integer types, whereas MSVC relies on int128_struct.

[hebasto]

Although clang-cl supports inline assembly, as indicated by the configure summary:

secp256k1 configure summary
===========================
<snip>
Optional features:
  assembly ............................ x86_64

I observed no benchmark difference between -DSECP256K1_ASM=x86_64 and -DSECP256K1_ASM=OFF.

[hebasto]

From what I can see there's there's only a single clang-cl CI job in this repo; if we're going to change the recommended way to build the library, then we should also replace the majority of the MSVC jobs, with clang-cl, to reflect that preference?

Fair enough. More clang-cl CI tasks have been added.

[real-or-random]

Naming: Shouldn't this be: x64 (clang-cl): Windows (VS 2022, shared) then? It's not a MSVC build.

(We could rework the naming of the jobs in general, it's not very consistent, and it's also not very helpful because the long names are truncated too early in the sidebar on https://github.com/bitcoin-core/secp256k1/pull/1681/checks, but that's a separate issue.)

[hebasto]

Thanks! Renamed.

[real-or-random]

if we're going to change the recommended way to build the library,

I doubt that MSVC was ever supposed to be a recommendation. (I wouldn't recommend MSVC to anyone...) It's just an example, and it's the default compiler in VS as far as I understand.

then we should also replace the majority of the MSVC jobs, with clang-cl, to reflect that preference?

But sure, I can't hurt to test more in clang-cl. Though we have a good clang coverage already, just not on Windows. But since we hardly use the C stdlib or syscalls, that's still a good coverage.

[real-or-random]

Suggested change

	Using clang-cl is recommended, as it tends to produce better-performing binaries compared to MSVC.
	Using clang-cl is recommended.

There are more reasons to prefer clang, e.g., the (forgotten) #1164 or just the fact its output more testing (though mostly on Linux). But it's difficult to explain in one or two sentences, and I think it's ok not to explain it here.

edit: I also suggest dropping the empty line after this sentence, but somehow the GitHub suggestion feature doesn't understand this.

[hebasto]

Thanks! Updated, including dropping the empty line.

[real-or-random]

Concept ACK

[real-or-random]

@sipa What do you think?

[sipa]

Concept ACK

[sipa]

This looks outdated now.

[hebasto]

Thanks! Adjusted.

[real-or-random]

ACK mod nit

[real-or-random]

nit:

I think this is more grammatical:

Suggested change

	The following example assumes using of Visual Studio 2022.
	The following example assumes using Visual Studio 2022.

But I'd just simplify to:

Suggested change

	The following example assumes using of Visual Studio 2022.
	The following example assumes Visual Studio 2022.

[hebasto]

Thanks! Picked the correct wording you suggested.

Additionally, I dropped the mention of 'a proper generator must be specified', as the default generator now works just fine.

[real-or-random]

utACK 7379124