The compiler.find_library() logic when using the static argument doesn't match the documentation (and it breaks finding Windows system libraries)

[DDoS]

Describe the bug
The meson doc states for compiler.find_library()'s static argument:

If true, the search is limited to static libraries only. Setting this value to false (the default) will search for both shared and static libraries.

This is incorrect: when static is explicitly false, only shared libraries are considered. The logic is:

prefer_static = self.environment.coredata.get_option(OptionKey('prefer_static'))
if kwargs['static'] is True:
    libtype = mesonlib.LibType.STATIC
elif kwargs['static'] is False:
    libtype = mesonlib.LibType.SHARED
elif prefer_static:
    libtype = mesonlib.LibType.PREFER_STATIC
else:
    libtype = mesonlib.LibType.PREFER_SHARED

The correct documentation is that when the keyword is not specified, the prefer_static option is used, and both library types are considered. When the keyword is used then only static or shared is considered.

The problem doesn't end at the doc though. Finding Windows system libraries requires PREFER_SHARED, because when using an MSVC compiler get_library_dirs always returns empty. Thus the only way to find a library is through the linker test, but it's only used with PREFER_SHARED, because the test can't guarantee that it won't find a static library. This means that when using prefer_static=true, _find_library_real is a no-op and it's impossible to find a Windows system library!

Either compiler.find_library() needs to be updated to do what the doc says it does, or it needs to be modified to allow "prefer" behaviour even if the static argument is explicitly used (maybe with an opt-in flag).

To Reproduce
Copied from issue #13887:

project('test', 'c', 'cpp')
cc = meson.get_compiler('c')
x = cc.find_library('ws2_32', static: false)

configured with -Dprefer_static=true

Expected behavior
_find_library_real should be called with libtype is LibType.PREFER_SHARED and ws2_32.dll should be found.

system parameters

• Is this a cross build or just a plain native build (for the same computer)? Native
• what operating system (e.g. MacOS Catalina, Windows 10, CentOS 8.0, Ubuntu 18.04, etc.): Windows 11
• what Python version are you using e.g. 3.8.0: 3.9.13
• what meson --version: 1.6.1
• what ninja --version if it's a Ninja build: 1.12.1