The 2019.06 update of vcpkg, a tool that helps you manage C and C++ libraries on Windows, Linux, and MacOS, is now available. This is the first time we’ve created a vcpkg release on our GitHub repository. This update is designed to bring you a summary of the new functionality and improvements made to vcpkg over about a month’s time. The 2019.06 update covers the month of June.

This release includes many new ports and triplet updates including overlay options, improvements for port contributors, and new documentation. For a full list of this release’s improvements, check out our release notes on GitHub.

Ports

There has been a substantial growth in vcpkg contributions over the past few months, with over 1,000 packages now available in the catalog. You can view the libraries available by either searching for a library name in the GitHub repo ports folder or using the vcpkg search command.

We added 44 new ports in the month of June. Some notable additions include: bdwgc, cJSON, greatest, immer, json-c, and zydis. These ports have 1K+ stars on their respective GitHub repos. You can view a full list of new ports in the [new ports section of our release notes]().

In addition to new ports, we updated 291 existing ports. A notable update to the release includes port ‘Homepages’.

Port Homepages

As part of our infrastructure work, you can now view the ‘Homepage’ for a port. This allows you to easily view a port’s official homepage via a link to the website. Let’s take the Abseil port for example. If you navigate to <vcpkg root>/ports/abseil/CONTROL, you will find the line “Homepage: https://github.com/abseil/abseil-cpp” which links to the official Abseil page.

Overlay Ports

The vcpkg command line interface allows you to easily search, install, and maintain your libraries. We added an –-overlay-ports option to allow you to override ports with alternate versions and create private ports.

Let’s look at an example where you are using OpenCV for your computer vision project. You would like to use vcpkg to acquire OpenCV and other packages. Your team is specifically using version 3.0 of OpenCV, but vcpkg offers version 3.4.3. Even though that version of OpenCV is not available in vcpkg, you can create a private port.

Let’s say you go ahead and create a private GitHub repo and check in the ports you want to preserve including OpenCV 3.0 and its specific dependent libraries that also may not be available in current vcpkg. You can then provide your team with the link to clone your private repo.

Locally, you create a custom ports directory and commit your changes:

~/vcpkg$ mkdir vcpkg-custom-ports
~/vcpkg$ cd vcpkg-custom-ports
~/vcpkg/vcpkg-custom-ports$ git init
~/vcpkg/vcpkg-custom-ports$ cp -r %VCPKG_ROOT%/ports/opencv .
~/vcpkg/vcpkg-custom-ports$ git add .
~/vcpkg/vcpkg-custom-ports$ git commit -m "[opencv] Add OpenCV 3.0 port"
~/vcpkg/vcpkg-custom-ports$ git remote add origin https://github.com/<My GitHub username>/vcpkg-custom-ports.git
~/vcpkg/vcpkg-custom-ports$ git push -u origin master

Now, you and your team can use version 3.0 of OpenCV for your projects with vcpkg using the following:

~/vcpkg/vcpkg-custom-ports$ git clone https://github.com/<My GitHub username>/vcpkg-custom-ports.git
~/vcpkg/vcpkg-custom-ports$ ./vcpkg update --overlay-ports=./vcpkg-custom-ports
~/vcpkg/vcpkg-custom-ports$ ./vcpkg upgrade --no-dry-run --overlay-ports=./vcpkg-custom-ports

Note that you may need to update vcpkg to use the most up-to-date command line options. You can update vcpkg on Windows via .\bootstrap-vcpkg.bat or on macOS /Linux via ./bootstrap-vcpkg.sh.

This allows you to upgrade your packages and preserve the older version of OpenCV that your project requires.

As shown in the example above, you can use --overlay-ports with the vcpkg install, vcpkg update, vcpkg upgrade, vcpkg export, and vcpkg depend-info commands. Learn more in our overlay-ports documentation.

Note that while overlay ports can help with overriding port versions and creating private ports, this is part of our ongoing work to improve the usability of vcpkg when it comes to versioning. Stay tuned for a future post on best practices for versioning with vcpkg!

Triplets

Vcpkg provides many triplets (target environments) by default. This past month, we focused on increasing the number of ports available on Linux and creating port improvements for Linux and the Windows Subsystem for Linux (WSL). We now have 823 ports available for Linux and we updated over 150 ports for Linux and WSL.

Here is a current list of ports per triplet:

Don’t see a triplet you’d like? You can easily add your own triplets. Details on adding triplets can be found in our documentation.

Overlay Triplets

As part of our vcpkg command line updates, we also added an --overlay-triplets option. This option is especially helpful if you have custom triplet needs. You can use the option, similar to --overlay-ports, to override triplets with custom specifications and create custom triplets.

For example, a subset of Linux users require fully dynamic libraries, whereas the x64-linux triplet only builds static libraries. A custom triplet file based on the x64-linux triplet can be created to build dynamic libraries. To solve this problem:

First, create a folder to contain your custom triplets:

~/vcpkg$ mkdir ../custom-triplets

Then, create the custom triplet file:

~/vcpkg$ cp ./triplets/x64-linux.cmake ../custom-triplets/x64-linux-dynamic.cmake

And modify the custom-triplets/x64-linux-dynamic.cmake file to:

set(VCPKG_TARGET_ARCHITECTURE x64) 
set(VCPKG_CRT_LINKAGE dynamic) 
set(VCPKG_LIBRARY_LINKAGE dynamic) 
set(VCPKG_CMAKE_SYSTEM_NAME Linux)

* Note the change of VCPKG_LIBRARY_LINKAGE from static to dynamic.

Finally, use your custom triplet by passing the --overlay-triplets option:

~/vcpkg$ vcpkg install opencv:x64-linux-dynamic --overlay-triplets=../custom-triplets

Improvements for Port Contributors

We also made improvements to the vcpkg infrastructure including a public CI system, check features, and a ‘Homepage’ field for ports.

CI System

We now have public CI tests through Azure DevOps pipelines which are run for all PRs to the vcpkg GitHub repo. The CI system allows contributors to get direct, automatic access to failure logs for PRs on Linux, Windows, and Mac within minutes. For example:

The checks will still include badges to indicate pass/fail as shown by the ‘x’ or ‘check mark’.

And if a check fails, you can now drill into the details:

Going further into Azure DevOps, you can get more information in the Summary tab such as downloading a zip file of all the failure logs along with a quick description of relevant changes:

We hope the new CI system will improve your experience submitting PRs to vcpkg!

Check Features

Vcpkg_check_features is a new portfile function that checks if one or more features are a part of a package installation. In vcpkg we use features to enable optional capabilities offered by libraries. A user requests vcpkg to install. For example:

~/vcpkg$ vcpkg install opencv[cuda]

The install command enables the optional CUDA support for OpenCV.

Vcpkg_check_featuressimplifies the portfile creation process for vcpkg contributors by shortening the syntax needed in the CMake portfile script. Previously, you needed to specify which features are included in the port:

if(<feature> IN_LIST FEATURES)
   set(<var> ON)else()&nbsp;&nbsp; 
   set(<var> OFF)
endif()

Now, you can simply write the following:

vcpkg_check_features(<feature> <output_variable>)

Learn more about using vcpkg_check_features in your portfiles in the vcpkg_check_features documentation.

‘Homepage’ Field for Ports

We also added an optional ‘Homepage’ field to CONTROL. This means that CONTROL files may now contain a ‘Homepage’ field which links to the port’s official website. The Homepage field is designed to help you more easily find the origin/location of the ports you are using.

Documentation

We also updated our documentation to reflect these new changes. Check out the following new docs for more information on some of the updates outlined in this post in addition to a couple other areas:

• Maintainer Guidelines and Policies
• Ports Overlay
• vcpkg_check_features
• vcpkg_execute_build_process

Thank you

Thank you to everyone who created vcpkg! We now have 639 total contributors. This release, we’d like to thank the following 24 contributors who made code changes in June:

Tell Us What You Think

Install vcpkg, give it a try, and let us know what you think. If you run into any issues, or have any suggestions, please report them on the Issues section of our GitHub repository.

We can be reached via the comments below or via email (vcpkg@microsoft.com). You can also find our team – and me – on Twitter @VisualC and @tara_msft.