Incorrect documentation when using manifest mode with CMake

[wardw]

Firstly, a note that is only a minor issue relating to the documentation not reflecting what appears to be current practice. Nevertheless, I thought perhaps worthwhile to raise the issue, particularity as this may impact many people's first experience when using Vcpkg under manifest mode with CMake.

The current tutorial on manifest mode explains that for a CMake build the approach is not to run vcpkg install to build and install the dependencies but rather "skip ahead to the next step: Build the project" which installs the dependencies as part of your project's build. This contradicts the documentation on introducing manifest mode

Manifest mode is engaged by running the vcpkg install command while there's a manifest file (vcpkg.json) in the working directory.

which at least here, is not the case. Continuing the tutorial, I then observe that the install root for vcpkg_installed is placed in the current build directory and not in the same directory that contains the manifest file. This likewise contradicts the documentation

Packages installed in manifest mode will not be installed in the global installed directory as they do in classic mode. Instead, each manifest gets its own installation directory named vcpkg_installed; the vcpkg_installed directory is created in the same directory that contains the manifest file.

A consequence is that there is no longer a one-to-one correspondence between your project's manifest file and a unique vcpkg_installed root, since you may have many build directories (debug, release) that each now contain their own vcpkg_installed root. For example, you may now have

project/
    build/
        debug/
            vcpkg_installed
        release/
            vcpkg_installed
    ..
    vcpkg.json

This matters because all subsequent documentation assumes such a one-to-one correspondence. This is confirmed in Installation directory layout conventions that explains

In manifest mode, each manifest file has a corresponding vcpkg_installed directory.

which from my understanding is simply not the expected behaviour?

All subsequent documentation then needs some degree of reinterpretation by the reader. For example, the suggestion to run

vcpkg list

from the directory containing your manifest file can't possibly work - to which install would this refer?

Instead, the approach appears to be something like

vcpkg list --x-install-root build/debug/vcpkg_installed

which works but requires somewhat disregarding the documentation and leaves me wondering if this is in fact correct practice or if I have misunderstood the basic setup of how to use Vcpkg under manifest mode with CMake.

Just finally, some related use-cases using manifest mode with CMake also seem a little light on details, for example when using custom triplets. If there were an opportunity to update the docs, that might also be worth a look.

[dg0yt]

Inconsistencies in the documentation are a real problem, and sometimes even show in recommendations given to users here. So your report is useful. But I would like to shift the perspective away from "CMake integration is doing it wrong".

Command line mode is nice if you cannot use buildsystem integration, if you want to issue specific commands, or if you want to pre-fill the artifact cache.

But CMake's capability to have multiple binary dirs and configurations for one source dir makes the single installed tree maintained by the command line a very poor match. Even for the same triplet, installed packages and features can vary, with manifest feature selection via CMake variables. This cannot be reasonably mapped to a single installed tree.

[wardw]

It wasn't my intention to suggest issues with the CMake integration itself, and as it happens (as a long-time CMake user) I'm quite grateful that Vcpkg works well with multiple build trees. At least from my perspective, finding that vcpkg_installed is placed per build-tree and not as the documentation suggests is a welcome surprise (!).

In fact, in my view this greatly enhances the value of using package manager for dependency management as you can really take advantage of how this automation scales to having multiple triplet combinations (and as you point out, manifest feature variations, too), all locally separated in parallel build-tress. That combinatorial nature scales poorly when building dependencies manually.

Rather, the emphasis should have been that the documentation doesn't appear to be in sync with such practice. Of course, there's always a chance I had completely misunderstood as the documentation does heavily lean into the single-install-tree approach, almost everywhere (?) outside that first tutorial. Hence why I thought this worthy of an issue to clarify best practice. Appreciating how a tool is expected to be used can be very valuable.

I should also have said in my first post, thanks for a great tool!

[WangWeiLin-MV]

Thank you for your thorough investigation, detailed analysis, and suggested enhancements. I will update the documents promptly after testing and verifying. If you have any questions, please feel free to let me know. Your contribution is greatly appreciated.

[WangWeiLin-MV]

There are two ways to use packages in manifest mode.

When using manifest mode, given C:/vcpkg/, given vcpkg.json, using default triplet x64-windows, taking the build tool CMake and the generator Visual Studio 17 2022 as an example:

• For integrated usage

cmake -B build_dir -D CMAKE_TOOLCHAIN_FILE="C:/vcpkg/scripts/buildsystems/vcpkg.cmake"
# packages in ./build_dir/vcpkg_installed
cmake --build build_dir

• For non-integrated usage

vcpkg install
cmake -B build_dir -D CMAKE_PREFIX_PATH="vcpkg_installed/x64-windows"
# packages in ./vcpkg_installed
cmake --build build_dir

---

Issues related to the documents of vcpkg now need to be reported at https://github.com/microsoft/vcpkg-docs. I have moved it for you, the new issue is microsoft/vcpkg-docs#349.

[dg0yt]

• For non-integrated usage

vcpkg install
cmake -B build_dir -D CMAKE_PREFIX_PATH="vcpkg_installed/x64-windows"
# packages in ./vcpkg_installed
cmake --build build_dir

This is nearly unusable, because it doesn't use any vcpkg-cmake-wrapper.cmake.