Provide helper .cmake file to avoid toolchain chainloads

[seanmiddleditch]

Is your feature request related to a problem? Please describe.

The documentation currently states:

When using vcpkg as a submodule of your project, you can add the following to your CMakeLists.txt before the first project() call, instead of passing CMAKE_TOOLCHAIN_FILE to the cmake invocation.

set(DVCPKG_CHAINLOAD_TOOLCHAIN_FILE CACHE INTERNAL ${CMAKE_TOOLCHAIN_FILE)
set(CMAKE_TOOLCHAIN_FILE ${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake
  CACHE STRING "Vcpkg toolchain file" FORCE)

This is not ideal. Likewise, passing -DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake or modifying build settings.

A CMake project that relies on vcpkg should ideally be self-contained (requiring no external steps or configuration or manual build steps) and also should ideally not co-opt a key CMake ecosystem variable like CMAKE_TOOLCHAIN_FILE.

Proposed solution

A few lines of CMake can do a two-step with cache variables to both enable standard CMAKE_TOOLCHAIN_FILE while injecting vcpkg's own toolchain. Something along the lines of:

set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE CACHE INTERNAL ${CMAKE_TOOLCHAIN_FILE)
set(CMAKE_TOOLCHAIN_FILE ${CMAKE_CURRENT_SOURCE_DIR}/cmake/vcpkg.cmake
  CACHE STRING "toolchain file")

A few additional lines may be added for error checking, path searching to find the right vcpkg.cmake location, etc. It could also automatically acquire vcpkg if not present already (avoiding the grossness of git submodules) with minimal work thanks to the FetchContent module.

I propose wrapping all that up into a function vcpkg_enable(), offering that as a simple vcpkg.cmake file, and documenting that a CMake integration can be achieved by copying that file into its source repo, includeing the file and adding the vcpkg_enable() line before project():

# after copying vcpkg.cmake into <root>/cmake
include(cmake/vcpkg.cmake)
vcpkg_enable()

project(myproject ...etc...)

Describe alternatives you've considered
The alternative is the status quo, which makes vcpkg feel "alien" in a CMake environment despite how minimal the existing integration is (due to the hijacking of the toolchain variable).

Additional context
Being able to add vcpkg to a CMake project in a way that Just Works(tm) for users when they checkout the repo (no need to set new CMake variables or IDE settings or anything) and in a way that continues working with existing CI and cross-compile infrastructure (which will already be using CMAKE_TOOLCHAIN_FILE) is possibly critical to gradual adoption of vcpkg in environments where a single developer does not easily control all the dev environments or CI environments.

[Neumann-A]

find_package(VCPKG) or find_package(vcpkg) whatever casing you like ..... with a findvcpkg.cmake in your CMAKE_MODULE_PATH and you can setup vcpkg however you like it.