vcpkg-tool is the client half of vcpkg, and it is where the build system lives

The split is deliberate: tool here, ports there

The repository description is the whole story in one line, since it contains the components of microsoft/vcpkg's binary. The README spells out the arrangement. This repository contains the contents formerly at the main vcpkg repository in the toolsrc tree, and build support. The main repository, microsoft/vcpkg, is where feature discussion, issue tracking and the edits to which libraries are available live. That division of labour is what makes both repositories workable. A client that can install libraries is one thing, and a catalogue of thousands of port recipes with their own issue threads and patches is a different kind of project, and merging them in one tree made both slower. The tool here is C++, the licence is MIT, and the same README that describes the split also carries the four translated links to the Microsoft Learn overview pages, so the reader who wants the conceptual introduction is sent to the documentation rather than kept here.

The Ubuntu build path is spelled out in full

The contributing prerequisites are the most concrete part of the README, and they are given as two platform specific lists. On Windows, you install Visual Studio and the C++ workload, install Node.JS by downloading a 16.x copy from nodejs.org, and install the Rush tool with:

* `npm install -g @microsoft/rush`

For Ubuntu 22.04, the same set of tools is set up with a script and a package list:

curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt update
sudo apt install nodejs cmake ninja-build gcc build-essential git zip unzip
sudo npm install -g @microsoft/rush

Three things stand out. Node.js is pinned to the 16.x line, which is an old major version for a toolchain and tells you the build scripts are not yet tracking current Node releases. CMake and Ninja are needed because the build is driven by CMakePresets.json rather than a hand written makefile, and Rush is the orchestrator that sits on top of Node for the repository's own multi package build.

Telemetry is on by default, and there are three switches

The README has a section on telemetry, and it is unusually specific about how to refuse it. vcpkg collects usage data in order to help improve the experience, and the data collected by Microsoft is anonymous. Opting out can be done in three ways, which is a good sign, because a single documented switch is often a single switch nobody finds. You can re-run the bootstrap-vcpkg script with -disableMetrics, you can pass --disable-metrics to vcpkg on the command line, or you can set the VCPKG_DISABLE_METRICS environment variable. The environment variable is the one that suits a build farm, where the same setting has to apply across many machines without anyone editing a command line, and the bootstrap option is the one that suits a machine you provision once. The README points at the vcpkg telemetry documentation and at the Microsoft Privacy Statement for the details, and for a tool that installs binaries on developer machines, knowing the default and the exit is worth reading before you install it widely.

MIT for the code, a separate file for the tests

The licence section is short but has a distinction worth noting. The product code in this repository is licensed under the MIT License, in the LICENSE.txt file, and the tests contain third party code as documented in NOTICE.txt. That split is the practical part, because the tests are where code gets copied in, and a NOTICE.txt is how you find out whose it was. The repository also carries a Generate-SpdxLicenseList.ps1 script and a cgmanifest.json, which are the artefacts used to generate the list of licences for the shipped binary, so the licensing story is automated rather than maintained by hand. The trademark clause is the standard one for a Microsoft project: the project may contain trademarks or logos, authorised use is subject to and must follow Microsoft's Trademark and Brand Guidelines, and use of Microsoft trademarks in modified versions must not cause confusion or imply Microsoft sponsorship. Any use of third party trademarks is subject to those third parties' policies.

The tree shows a tool that has grown well past a client

The top level of the repository is a good indication of scope. Alongside the expected src/ and include/ there is vcpkg-artifacts/, which is the artifact and binary acquisition side of the tool, and vcpkg-init/, which is the project initialisation path that creates the manifest and configuration files a new project starts from. There is locales/ for translations, docs/ for documentation, scripts/ for the helper tooling, and cmake/ with the CMakePresets.json that drives the build. Then there are the parts that show the project's engineering maturity: a guardian/ directory, a fuzzing-corpora/ directory, azure-pipelines/ for the continuous integration definitions, a .devcontainer/ directory, a .config/ directory, and both a vcpkg.natvis file for the debugger and a LocProject.json for localisation tooling. The Visual Studio natvis file is a small detail that says a lot, since it means the internal data structures of the client are meant to be inspected in a debugger.

The alternative is a system package manager

For installing C and C++ libraries, the realistic alternative is the package manager of your operating system, whether that is apt, dnf or a similar tool, or a source based manager of a different flavour. The difference in approach is where the binaries and the versions come from. A system package manager hands you prebuilt libraries tied to a distribution release, which is fast and small, but the version is whatever the distributor decided and the set of libraries available is whatever that distribution ships. A manifest based source manager compiles the library in your own tree and pins the version you asked for, which costs build time and disk but gives you the exact version and the exact options. The trade also moves the failure mode. A distribution package that is missing is a packaging request, while a library that fails to build against your toolchain is a porting problem, which is exactly the problem the main vcpkg repository exists to solve.

Editorial conclusion

Adopt this repository if you are working on the vcpkg client itself, or if you need to build a vcpkg binary with a modified toolchain, since it is where the executable and the build support live and where the source has been moved. Do not expect it to be the place to add a library, because the port catalogue and issue tracking stay in the main repository, and do not build it if you only need the client, since the published binaries are what most users want. Before you start, read the telemetry section and decide how you want it configured, since the metrics are on by default, and check the LICENSE.txt and NOTICE.txt split, because the product code and the tests carry different terms.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. microsoft/vcpkg-tool on GitHub
4. README
5. Releases