vcpkg 2023.10.19 Release: Export for Manifests, Documentation Improvements, and More…

Augustin Popa

The 2023.10.19 release of the vcpkg package manager is available. This blog post summarizes changes from August 10^th, 2023 to October 19^th, 2023 for the Microsoft/vcpkg, Microsoft/vcpkg-tool, and Microsoft/vcpkg-docs GitHub repos.

Some stats for this period:

• 53 new ports were added to the open-source registry. If you are unfamiliar with the term ‘port’, they are packages that are built from source and are typically C/C++ libraries.
• 729 updates were made to existing ports. As always, we validate each change to a port by building all other ports that depend on or are depended by the library that is being updated for our nine main triplets.
• There are now 2,318 total libraries available in the vcpkg public registry.
• 34 contributors submitted PRs, issues, or participated in discussions in the main repo.
• The main vcpkg repo has over 5,700 forks and 19,900 stars on GitHub.

Key changes

Notable changes for this release are summarized below.

vcpkg export now supports manifest mode

The vcpkg export command can be used to export built packages from the installed directory to a standalone SDK. A variety of formats are supported, including NuGet, a zip, or a raw directory. The SDK contains all prebuilt binaries for the selected packages, their transitive dependencies, and integration files such as CMake toolchain or MSBuild props/targets. This command is useful for developers who want to export their dependencies to a portable format for their end users to consume, when those end users do not have vcpkg.

Now, this command is supported for manifest-based (vcpkg.json) projects. Summary of changes:

• vcpkg export in manifest mode exports everything in the vcpkg_installed directory
• In manifest mode, the export command emits an error and fails when port:triplet arguments are provided, as they are not allowed in manifest mode.
• Added a guard to exit with an error message when the installed directory is empty. Previously, it just failed silently.
• Made --output-dir mandatory in manifest mode.

Documentation for vcpkg export in manifest mode

PR: Microsoft/vcpkg-tool#1136

Implemented default triplet changes announced earlier this year

In a previous blog post, we announced that we would be changing the default behavior for commands that accept a triplet as an option but are not provided one. This change is now live. The default triplet assumed is no longer always x86-windows but will instead use a triplet inferred from your CPU architecture and operating system.

PR: Microsoft/vcpkg-tool#1180

Improvements to vcpkg help

The documentation provided when running vcpkg help or vcpkg help <command> has been updated. This should make it easier to explore vcpkg without having to go to the documentation on Microsoft Learn and also improves the autocompletion (Tab) experience for the tool. Below are some screenshots of the new experience.

Before (left) and after (right) when running vcpkg help (or not providing any commands to vcpkg):

Summary of changes:

• We now show a more complete list of available commands and options.
• Available commands now organized by category and sorted alphabetically.
• Added a link to our online vcpkg documentation.
• Cleaned up some of the wording.

Before (left) and after (right) when running vcpkg help install:

Summary of changes:

• Added synopsis describing what the command does.
• In some cases, added additional examples for different usage scenarios.
• Added a link to our online vcpkg documentation
• Cleaned up some of the wording.

With the autocompletion improvements, vcpkg is able to autocomplete commands like: x-set autocompleting to x-set-installed.

PR: Microsoft/vcpkg-tool#1169

Introduced –x-cmake-debug and –x-cmake-configure-debug options

Thanks to a community contribution, two new experimental common command options have been added to vcpkg: --x-cmake-debug and --x-cmake-configure-debug. These options help facilitate CMake debugging for upstream build systems’ CMakeLists.txt.

–x-cmake-debug

Usage:

--x-cmake-debug=<debugger-pipe>[;semicolon;port;list]

Enables CMake’s –debugger while running directly-invoked CMake scripts like triplet files (for example: x64-windows.cmake) or portfile.cmake files.

The <debugger-pipe> value is passed as –debugger-pipe on the CMake command line.

For more information, see documentation for x-cmake-debug.

–x-cmake-configure-debug

Usage:

--x-cmake-configure-debug=<debugger-pipe>[;semicolon;port;list]

Enables CMake’s –debugger within upstream build systems’ CMakeLists.txt, such as within vcpkg_cmake_configure.

The <debugger-pipe> value is passed as –debugger-pipe on the CMake command line.

Although all ports should be calling CMake inside of the portfile to obtain compile flags from the CMake toolchain, this command is mainly useful for ports actually using CMake as their build system.

For more information, see documentation for x-cmake-configure-debug.

PR: Microsoft/vcpkg-tool#1173 (thanks @Neumann-A!)

Command: “vcpkg cache” removed

The vcpkg cache command has been removed as it was rendered obsolete by the binary caching feature and our data indicated very few users were interacting with it.

PR: Microsoft/vcpkg-tool#1174

Documentation changes

This release includes the most significant documentation changes ever for vcpkg. We have been listening to your feedback and actively developing new articles and improvements to our existing articles at https://learn.microsoft.com/vcpkg.

Below is a summary of notable documentation changes:

• The landing page at https://learn.microsoft.com/vcpkg has been updated with new links and several new categories have been added.
• The table of contents has been re-organized for better navigation. Don’t forget the site has a search experience too via the search box.
• There is a new “Get started” node for new users with a variety of new articles depending on your scenario. This addresses feedback that the documentation was hard to follow and that it introduced concepts that were confusing to understand too early. List of new getting started content:
  • vcpkg overview
  • Install and use packages with CMake
  • Install and use packages with CMake in Visual Studio
  • Install and use packages with MSBuild in Visual Studio
  • Package a library with vcpkg
  • Contribute an open-source library to vcpkg
• New tutorials:
  • Tutorial: Install a locally modified dependency
  • Tutorial: Set up a vcpkg asset cache
  • Tutorial: Install a specific version of the Boost libraries using registry baselines
  • Tutorial: Install a dependency from a Git-based registry
  • Tutorial: Install a specific version of a package
  • Tutorial: Authenticate vcpkg Git-based registries in GitHub Actions
  • Tutorial: Publish packages to a private vcpkg registry using Git
  • Tutorial: Install a dependency from the command line
• New concept articles:
  • Asset caching with vcpkg
  • Build system integration
  • Manifest mode
  • Overlay ports
  • Ports
  • Registries concepts
  • Triplets
• New reference articles:
  • Installation directory layout
  • vcpkg add
  • vcpkg x-add-version
  • vcpkg create
  • vcpkg contact
  • vcpkg format-manifest
  • vcpkg hash
  • vcpkg help
  • vcpkg new
  • vcpkg owns
• Binary caching content split into multiple articles with added details:
  • What is binary caching?
  • Default local vcpkg binary cache
  • Tutorial: Set up a vcpkg binary cache using filesystem directories
  • Tutorial: Set up a vcpkg binary cache using a NuGet feed
  • Tutorial: Set up a vcpkg binary cache using GitHub Actions Cache
  • Tutorial: Set up a vcpkg binary cache using GitHub Packages in a GitHub Actions workflow
• New common command options:
  • Common command options#x-cmake-debug
  • Common command options#x-cmake-configure-debug
• A new “Troubleshooting” category has been added to the table of contents, featuring its first article: Troubleshoot binary caching issues. Our team received many questions about how to identify and fix these types of issues. This article is intended to guide the reader toward solving these problems.
• Many articles have new pivots based on the command line/operating system you are using. You can select your preferred environment to view the examples in the article in that format for a simple copy + paste experience.
• Rewritten Tutorial: Install a dependency from a manifest file.
• Various updates to existing articles on the Registries feature.
• Triplets article split into Triplets concepts and Triplets reference.
• Added manifest mode instructions for vcpkg export.
• Various small text edits, URL fixes, and other minor changes.
• Added background information on how CMake toolchain leads to dependency acquisition in vcpkg in CMake projects (thanks for the contribution, @ihnorton!).
• New article for vcpkg_msbuild_install and various other updates to documentation on building vcpkg ports with MSBuild (thanks for the contribution, @Neumann_A!).

Bug fixes

• Fixed vcpkg edit trying to look in the registry set for autocompletion as this isn’t relevant to its purpose. (PR: Microsoft/vcpkg-tool#1158)
• Commands such as vcpkg activate now exit with an exit code of 1 rather than 0 if the command method throws an exception (PR: Microsoft/vcpkg-tool#1195, thanks @mcgordonite!)

Total ports available for tested triplets

While vcpkg supports a much larger variety of target platforms and architectures, the list above is validated exhaustively to ensure updated ports don’t break other ports in the catalog.

Thank you to our contributors

vcpkg couldn’t be where it is today without contributions from our open-source community. Thank you for your continued support! The following people contributed to the vcpkg, vcpkg-tool, or vcpkg-docs repos in this release:

• jiayuehua (124 commits)
• autoantwort (94 commits)
• Neumann-A (40 commits)
• dg0yt (31 commits)
• xiaozhuai (30 commits)
• chausner (11 commits)
• talregev (10 commits)
• RT2Code (8 commits)
• Thomas1664 (8 commits)
• cbrl (6 commits)
• alagoutte (6 commits)
• Osyotr (6 commits)
• Pospelove (5 commits)
• AenBleidd (5 commits)
• Honeybunch (4 commits)
• yurybura (4 commits)
• RealTimeChris (4 commits)
• BurningEnlightenment (4 commits)
• quyykk (3 commits)
• SchaichAlonso (3 commits)
• mcgordonite (2 commits)
• horenmar (2 commits)
• coryan (2 commits)
• Ryan-rsm-McKenzie (1 commit)
• eao197 (1 commit)
• m-kuhn (1 commit)
• Sibras (1 commit)
• myd7349 (1 commit)
• daschuer (1 commit)
• luncliff (1 commit)
• traversaro (1 commit)
• lazyhamster (1 commit)
• JackBoosY (1 commit)
• amirmasoudabdol (1 commit)
• ihnorton (1 commit)
• retifrav (1 commit)

Is your company looking for a better C/C++ dependency management experience?

We are partnering with companies to help them get started with vcpkg and overcome any initial hurdles. We have also been making product and documentation changes based on feedback we receive from these partnerships. If you are interested in trying out vcpkg or just have some thoughts to share with us, feel free to reach out at vcpkg@microsoft.com.

Learn more

You can find the full 2023.10.19 release notes on GitHub for the main repo. Recent updates to the vcpkg tool can be viewed on the vcpkg-tool Releases page. To contribute to documentation, visit the vcpkg-docs repo. If you’re new to vcpkg or curious about how a package manager can make your life easier as a C/C++ developer, check out the vcpkg website – vcpkg.io.

If you would like to contribute to vcpkg and its library catalog, or want to give us feedback on anything, check out our GitHub repo. Please report bugs or request updates to ports in our issue tracker or join more general discussion in our discussion forum.

Augustin Popa Senior Product Manager, Microsoft C++ Team

Follow