Clearify `vcpkg_check_linkage` vs `supports`

[SunBlack]

Type of issue

Missing information

Description

While updating some ports, I came across vcpkg_check_linkage in the portfile.cmake file. At first, I assumed that it had been replaced by supports in vcpkg.json. However, the documentation for vcpkg_check_linkage makes it sound as if supports is only an addition. I think it would be good if both documentations clearly stated when to use which one.

Page URL

https://learn.microsoft.com/en-us/vcpkg/reference/vcpkg-json#supports

Content source URL

https://github.com/MicrosoftDocs/vcpkg-docs/blob/main/vcpkg/reference/vcpkg-json.md

Document Version Independent Id

c9908f8f-fc4a-6ba6-65a0-c4f16fc1621d

Platform Id

0820403e-fc79-ac36-0384-23406cf90ddb

Article author

@vicroms

Metadata

• ID: c9908f8f-fc4a-6ba6-65a0-c4f16fc1621d
• PlatformId: 0820403e-fc79-ac36-0384-23406cf90ddb
• Service: vcpkg

[dg0yt]

Could you be more specific?

What should be understood first: Both locations serve different purposes.

• Manifest properties are evaluated early, when making an installation plan. They change what is included in the installation plan.
• Portfile commands are evaluated when actually building a package from source. They can change how the build of a particular artifact is done.

[SunBlack]

From what I understand: If something is only built statically, for example, I enter that in the supports clause so that vcpkg knows right away when building the build plan that it won't work. vcpkg_check_linkage, on the other hand, only becomes operational when the port is actually to be built.

So, if you have a port that has, for example: supports: "static" in vcpkg.json and vcpkg_check_linkage(ONLY_STATIC_LIBRARY) in the portfile: Under what circumstances does the extra check trigger? And if there is a way to bypass the build plan: Why can't it pull this information for the warning from the supports clause?

[dg0yt]

If something is only built statically, for example, I enter that in the supports clause so that vcpkg knows right away when building the build plan that it won't work.

No. The static lib (with dynamic CRT linkage) can exist and be quite useful in a dynamic universe.
So you leave supports unrestricted and use vcpkg_check_linkage(ONLY_STATIC_LIBRARY) instead. The portfile function will check the triplet's linkage values and change library linkage for this port only to static if this is a reasonable thing to do.

As a special case, you will find libraries which lack dllexport declarations. Then the pattern becomes conditional:

if(VCPKG_TARGET_IS_WINDOWS)
    vcpkg_check_linkage(ONLY_STATIC_LIBRARY)
endif()

---

OTOH there are ports which provide only dynamic libs. They might work reasonably in a static universe with dynamic CRT linkage. So in this case you will find a combination of "supports": "!(static & staticcrt)" and vcpkg_check_linkage(ONLY_DYNAMIC_LIBRARY). Here, the actual library linkage will be changed to dynamic for this port only if this is a reasonable thing to do.

---

Last, there are other combinations which are too rare and specific to need general support. Users might inject build customizations via per-port customziation of linkage options in triplet files. This is not considered when creating the installation plan.

And that's why supports should prefer to prefer to express the exlusion of specific known impossible targets (e.g. !windows | mingw), not the exclusive list of known possible targets (e.g. linux | osx).