[vcpkg-tool] vcpkg install <pkg> gives wrong usage information

[dg0yt]

Bad User Experience

The auto-generated usage information is wrong for many non-trivial ports.

Earlier reports

• vcpkg install: Usage hint for CMake find_package, incomplete support for possible paths #10881

Known problem ports

• azure-iot-sdk-c (lists 4 out of 10 targets in one line, too much)
• grpc (references a modules target, Install grpc error : Could not find a package configuration file provided by "modules"  #17177)
• hdf5 (listing all targets, which is too much)
• iir1(config in wrong dir, [iir1] find_package failed #23940)
• itk (promoting bad practice, see below, include ITK #22641)
• jsoncpp (3 targets in one line, [vcpkg-tool] vcpkg install <pkg> gives wrong usage information #20190 (comment))
• libpng (reporting different targets for static vs. dynamic instead of CMake Find module, [libpng] Add file usage.txt to describe the usage of port libpng #23379)
• openimageio (references a Module target, [openimageio] OpenImageIO Cmake rules are broken and the package is unusable #21234)
• openxr-loader (config in wrong dir, [openxr-loader] Fix package name and enable arm #23928)
• qhull (listing all targets, which is too much)
• qt5-base (listing targets which are private implementation details, and duplicate targets, cf. [qt5-base] build failure #14907 (comment))
• realsense2 (lists four targets, [vcpkg-tool] vcpkg install <pkg> gives wrong usage information #20190 (comment))
• shapelib (no config file to match the proposed package name, [shapelib] Unable to find shp-config.cmake when including in build #16041, [vcpkg-tool] vcpkg install <pkg> gives wrong usage information #20190 (comment))

Patched by usage file

• arrow (references an arrow_bundled_dependencies library which doesn't exist in absence of vendored dependencies, Arrow link error after installing on Ubuntu #20459)
• c-ares (lists c-ares::cares c-ares::cares_shared c-ares::cares_static)
• drogon(picks targets from conditional find_dependency helpers, [vcpkg-tool] vcpkg install <pkg> gives wrong usage information #20190 (comment))
• libiconv (see below, from [osg] build failure #14994; [iconv] How to use with vcpkg? vcpkg install iconv then "Could not find a package configuration file" #22539)
• mailio (reports a cmake package, [mailio] hint message after installing mailio is incorrect #23798)
• vtk (original output cf. [VTK] CMake usage printed by vcpkg is wrong #19035)

Other resolved

• effolkronium-random (config in wrong dir, [effolkronium-random] Properly handle package_name #20795)
• sentry-native (config in wrong dir, [sentry-native] Update to 0.4.17 #24309 (review))

Misguided patching in vcpkg

• libgeotiff 1.6.1 ([libgeotiff] Fix packagename via find_package #15750 diverging from upstream)

Promoting Bad Practice

All targets are listed in the same target_link_libraries line. But normally, canonical usage is to use only a single desired target and let it pull in its transitive usage requirements.

Some package do export targets not as public interface, but as an implementation detail hidden behind interface variables. By automatic reporting of targes, vcpkg distracts user from applying canonical usage, contributors from researching, documenting and testing canonical usage, and team members to base there support answers on canonical usage.

Example: User experience for libiconv

but when i run the command vcpkg install libiconv, it always tell me

ubuntu@o-01:~/vcpkg$ vcpkg install libiconv
Computing installation plan...
The following packages are already installed:
    libiconv[core]:x64-linux -> 1.16#11
Package libiconv:x64-linux is already installed
Restored 0 packages from /home/ubuntu/.cache/vcpkg/archives in 1.052 us. Use --debug to see more details.

Total elapsed time: 37.06 us

The package libiconv provides CMake targets:

    find_package(iconv CONFIG REQUIRED)
    target_link_libraries(main PRIVATE Iconv::Charset)

please fix the issue.

Originally posted by @ssrlive in #14994 (comment)

[dg0yt]

The CONFIG keyword and the package name (actually Iconv) and the target name (actually Iconv::Iconv) are wrong. It should be:

find_package(Iconv REQUIRED)
target_link_libraries(main PRIVATE Iconv::Iconv)

Generally, given a share/<pkg>/vcpkg-cmake-wrapper.cmake, the tool heuristics would need to look for a Find<pkg>.cmake (case insensitively), and suggest find_package(<pkg-with-rectified-case> REQUIRED) if such a module is found.

[dg0yt]

In addition, Iconv::Charset is an internal helper of the wrapper, not a public feature.

[dg0yt]

I see this as a general vcpkg bug now. Usage information must be reviewed and verified, or omitted.
Maybe something for "discussion".

[dg0yt]

Is there sufficient evidence now to request a response from the vcpkg team?

[dg0yt]

CC @ras0219-msft @strega-nil-ms

[strega-nil-ms]

This is fair enough; I'll bring it up in the new year at the PR meeting.

[dg0yt]

The following packages will be built and installed:
    drogon[core,mysql,orm]:x64-linux -> 1.7.4
....
The package drogon provides CMake targets:

    find_package(Drogon CONFIG REQUIRED)
    # Note: 6 target(s) were omitted.
    target_link_libraries(main PRIVATE pg_lib UUID_lib coz::coz MySQL_lib)

The Drogon config clearly provides target Drogon::Drogon. None of the other targets should be linked manually. They seem to come from Find modules installed but only conditionally used via find_dependency(...). Maybe a hint how to improve the heuristic.

[dg0yt]

This is a friendly reminder. Actually I'm increasingly unhappy with how this vcpkg feature promotes bad practice.

[dg0yt]

Added qt5-base.

[dg0yt]

Added azure-iot-sdk-c

[dg0yt]

Added qhull.

Do I need to make a PR which disables the tool feature?

[dg0yt]

Added libpng.

Ping @vicroms @strega-nil-ms.

[dg0yt]

shapelib bonus fact:
#22633 added a patch file to fix the config, but didn't add it to the portfile.
Not detected in review.
Not detected in automated checks.
And IMO the patch is invalid because it makes assumptions about the desired package name. It must be unofficial until fixed upstream.

[dg0yt]

LOL while working on #24720:

Elapsed time to handle osgearth:x64-linux: 16.23 min

Total elapsed time: 16.28 min

osgearth is header-only and can be used from CMake via:

    find_path(OSGEARTH_INCLUDE_DIRS "osgEarth/AGG.h")
    target_include_directories(main PRIVATE ${OSGEARTH_INCLUDE_DIRS})

(Libs went to /lib64 by error. Headers don't have a .h suffix except for the one listed.)

Where is the # this is heuristically generated, and may not be correct?

[dg0yt]

The tool also creates invalid suggestions by copying things literally, e.g.
target_link_libraries(main PRIVATE <name> alpaka alpaka::alpaka) (#26812 (comment)), or
target_link_libraries(main PRIVATE # foobar), or
target_link_libraries(main PRIVATE " cmrc-base cmrc::base) (#27109 (comment))

[FabienPean]

I stumbled upon this problem recently with ports Simbody, Blas, Lapack, and header-only Boost libraries.

Just to clarify @strega-nil-ms since I couldn't find a guideline on the topic:

• From this thread, I understand that the current recommended way is to add a usage file in the port folder ?
• If so, is there any specific template or format to follow for getting quick approval of the PR ?

Listing all the targets provided by a port in the usage file would be best to me, unless there is an easy way to list the installed targets provided by the port. I remember getting quite a few times # note: X additional targets are not displayed. forcing me to dig the corresponding share/<lib> folder.

[dg0yt]

• From this thread, I understand that the current recommended way is to add a usage file in the port folder ?

Yes.

• If so, is there any specific template or format to follow for getting quick approval of the PR ?

Look at a similar port, or start with the tool's ouput. But use your brain, and upstream documentation.

I remember getting quite a few times # note: X additional targets are not displayed. forcing me to dig the corresponding share/ folder.

Quite often, there are only a few relevant targets, and the others are used implicitly.

[JoseSanchez7]

Hello @dg0yt. In regard to the azure-iot-sdk-c, what exactly are you referring to? An explicit example in the code base would be helpful.

[dg0yt]

@JoseSanchez7 Without looking at the current state:

azure-iot-sdk-c (lists 4 out of 10 targets in one line, too much)

vcpkg detects many targets and print some 4 of them. This is not a good path to indicate usage. In general,

• most targets are for a particular purpose. They shouldn't be used when they aren't needed.
• some targets are for shared code.They shouldn't be used directly, but are included as transitive usage requirements.

The proper fix is to add a usage file to the port, connecting targets to purposes. Simple example: ports/geos/usage.
Or just the most common case, and a pointer to upstream documentation. (Unfortunately, many upstream are particular in this aspect of documentation.)

[JoseSanchez7]

Hello @dg0yt, our team (Azure C SDK) spoke yesterday morning about your request regarding changes to how our cmake works with vcpkg and decided that it's not something we will be changing at this moment.

[dg0yt]

@JoseSanchez7 I didn't want to indicate a need for changes to "how your cmake works". I see a need to better document downstream CMake usage. The heuristics in vcpkg tool is very limited. It is unlikely that a random pick of 4 targets out of 10 is what the users needs.

[dg0yt]

@BillyONeal Not sure if it was case the before the last tool release, but now the heuristics picks misleading information (CONFIG, targets) from the wrappers:

tiff provides CMake targets:

    # this is heuristically generated, and may not be correct
    find_package(tiff CONFIG REQUIRED)
    target_link_libraries(main PRIVATE ZSTD::ZSTD)

[dg0yt]

@BillyONeal Ignore my last comment. I bootstrapped on the old version. The new version no longer outputs misleading information for tiff.
(Now we should probably looka at my next proposal: Check if there is an official find module when we find wrapper.)

[github-actions]

This is an automated message. Per our repo policy, stale issues get closed if there has been no activity in the past 180 days. The issue will be automatically closed in 14 days. If you wish to keep this issue open, please add a new comment.

[Cheney-W]

Stay active