[vcpkg_check_linkage] Clarify ONLY_DYNAMIC_LIBRARY failures and supports expressions.

vcpkg/maintainers/functions/vcpkg_check_linkage.md

@@ -1,7 +1,7 @@
 ---
 title: vcpkg_check_linkage
 description: Assert the available library and CRT linkage options for the port.
-ms.date: 01/30/2024
+ms.date: 12/05/2024
 ---
 # vcpkg_check_linkage
 
@@ -22,11 +22,14 @@ vcpkg_check_linkage(
 
 Indicates that this port can only be built with static library linkage.
 
-If the user requested a dynamic build, `ONLY_STATIC_LIBRARY` will result in a note being printed, not a fatal error.
+If the user requested a dynamic build, `ONLY_STATIC_LIBRARY` will result in a note being printed,
+not a fatal error.
 
 ### ONLY_DYNAMIC_LIBRARY
 
-Indicates that this port can only be built with dynamic/shared library linkage.
+Indicates that this port can only be built with dynamic/shared library linkage. When using this
+option, port authors should add `!(static & static-crt)` to the `"supports"` expression in the
+port's `vcpkg.json` to warn consumers it will fail early.
 
 ### ONLY_STATIC_CRT
 
@@ -38,7 +41,33 @@ Indicates that this port can only be built with dynamic/shared CRT linkage.
 
 ## Notes
 
-This command will either alter the settings for `VCPKG_LIBRARY_LINKAGE` or fail, depending on what was requested by the user versus what the library supports.
+If the triplet requests a setting of `VCPKG_LIBRARY_LINAKGE` different than the port supports,
+and changing `VCPKG_LIBRARY_LINKAGE` to that the port supports is cosidered safe,
+`vcpkg_check_linkage` changes `VCPKG_LIBRARY_LINKAGE` to that the port supports and emits a warning.
+This means that the port may produce something that the user does not expect, but the alternative
+would be to just fail.
+
+If `vcpkg_check_linkage` would change `VCPKG_LIBRARY_LINKAGE` to `dynamic` while the triplet
+requests `VCPKG_CRT_LINKAGE` of `static`, the change is not considered safe and
+`vcpkg_check_linkage` fails. Building a dynamic library with a static CRT creates conditions many
+developers find surprising, and for which most ports are unprepared.
+
+For example, on Windows, each DLL will get its own copy of the CRT, meaning such DLLs cannot share
+standard library components over the DLL boundary. On non-Windows, different .sos or .dylibs may
+cause mutually incompatible symbols from different CRT versions to be concurrently loaded.
+
+If you are consuming a port and it fails in `vcpkg_check_linkage`, consider choosing a triplet that
+sets `VCPKG_CRT_LINKAGE` to `dynamic`. If you really know what you're doing, understand the
+potential problems a static CRT with a dynamic library can cause, and are confident that the port
+safely handles that configuration, author a custom triplet which explicitly sets
+`VCPKG_LIBRARY_LINKAGE` to `dynamic` and `VCPKG_CRT_LINKAGE` to static. For example:
+
+```cmake
+if("${PORT}" STREQUAL "the-name-of-the-port-you-want-to-control")
+    set(VCPKG_LIBRARY_LINKAGE dynamic)
+    set(VCPKG_CRT_LINKAGE static)
+endif()
+```
 
 ## Examples