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

[Farwaykorse]

Describe the bug
Vcpkg does not provide the right usage hint for <pkg_name>Config.cmake files installed into a path ending in cmake.
E.g. /share/Microsoft.GSL/cmake/Microsoft.GSLConfig.cmake, used in Microsoft/GSL/CMakeLists.txt.

Without the work-around added in the portfile for #10831 vcpkg install ms-gsl returns the following usage hint:

The package ms-gsl:x86-windows provides CMake targets:

    find_package(cmake CONFIG REQUIRED)
    target_link_libraries(main PRIVATE Microsoft.GSL::GSL)

Note the cmake in find_package, this should be Microsoft.GSL.

The current implementation shows a package name taken from the wrong folder.

Proposed solution
An update of the algorithm used to determine the package name.
There might be more valid paths that are not matched. (See the table below.)

Describe alternatives you've considered
Fixes, such as added to #10831, moving the files to a recognised path, are easy to forget and hard to maintain.
And they should not be necessary for projects using a valid path.

Additional context

The tables below show the directories searched. Each entry is meant for installation trees following Windows (W), UNIX (U), or Apple (A) conventions:

<prefix>/                                                       (W)
<prefix>/(cmake|CMake)/                                         (W)
<prefix>/<name>*/                                               (W)
<prefix>/<name>*/(cmake|CMake)/                                 (W)
<prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/                 (U)
<prefix>/(lib/<arch>|lib*|share)/<name>*/                       (U)
<prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/         (U)
<prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/         (W/U)
<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/               (W/U)
<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U)

Source: CMake documentation - find_package Search Procedure

---

[Neumann-A]

returns the following usage hint:

probably a bug in the usage printing which does not correctly search for a *Config.cmake and takes every allowed path into account. It is probably better to derive the find_package name from the config name instead of the path

[JackBoosY]

should be a vcpkg bug.

[roddypratt]

Seeing this with the mdns library too.

[cmake] mdns provides CMake targets:
[cmake] 
[cmake]     # this is heuristically generated, and may not be correct
[cmake]     find_package(cmake CONFIG REQUIRED)
[cmake]     target_link_libraries(main PRIVATE mdns::mdns)

[dg0yt]

This belongs to the #20190 gallery...

[JackBoosY]

cc @Cheney-W

[dg0yt]

With microsoft/vcpkg-tool#849, vcpkg-tool will print usage heuristics only for config located directly in share/<Pkg>. For mdns, the output changes to header-only.

-mdns provides CMake targets:
-
-    # this is heuristically generated, and may not be correct
-    find_package(cmake CONFIG REQUIRED)
-    target_link_libraries(main PRIVATE mdns::mdns)
+mdns is header-only and can be used from CMake via:
+
+    find_path(MDNS_INCLUDE_DIRS "mdns.h")
+    target_include_directories(main PRIVATE ${MDNS_INCLUDE_DIRS})

This is not plainly wrong as with the current tool, but still not what is desired.
However, instead of considering alternative location in the usage heuristics, I would rather suggest to add a check which suggests to call vcpkg_cmake_config_fixup. At least for libraries, this is needed anyways, no matter where the location is stored.

[JonLiu1993]

Duplicate of #20190