Vcpkg: Using multiple enlistments to handle multiple versions of a library

EricMittelette

Vcpkg allows you to acquire and build 3^rd party libraries on Windows. Once cloned, the vcpkg directory (enlistment) provides a stable set of libraries that are all compatible and based on the latest published version of these libraries. Occasionally, you may need different versions of the same library. By design, you can’t have two different versions of the same library in the same enlistment; instead, you need to create and work with multiple enlistments.

Creating multiple enlistments

1) Clone the git repository

To create multiple enlistments, just reclone the GitHub repo on a different location on your machine:

git clone https://github.com/Microsoft/vcpkg.git

By default, the master branch of vcpkg presents the latest version of libraries. If you need an older version, browse the file history of the library to see if the version you are looking for is available. The control file should display the version history.

2) Find a specific version

For example, imagine you want to use OpenCV, but not the 3.3.0.4, but instead the 3.2.0 version:

Once you have identified the version, use the <> button to navigate the repo at this point in time.

3) Clone the repo for a specific label/hash

You’re now ready to clone the repo for OpenCV version 3.2.0 from February 8^th, 2017. Note: it is important that all the libraries you are going to use came from the same label/hash. By cloning the entire repo from that label/hash the dependents libraries will be compatible with the version of the lib you selected.

Click on the commit hash, and then copy the “complete” commit hash:

This is the one to use for your new enlistment, via the git checkout command:

4) build vcpkg for a specific label/hash

Don’t forget to build vcpkg via the bootstrap file running:

bootstrap-vcpkg.bat

You’re now ready to build OpenCV 3.2.0 with the dependencies corresponding to this version.

Using multiple enlistments

Now you’re ready to use your new/specific version of your libraries. To switch between enlistments for your project, we provide two approaches:

· Reference the enlistment via the integrate project command

· Use the Export command to package the libraries in a NuGet Package (or in a raw or zip format)

a) Run the vcpkg integrate project command:

As mentioned in the comment, go to your project and add a reference to this NuGet Package. The NuGet Package contains only a “link” to your new enlistment. Your project is now linked with the libraries present in the second enlistment.

b) Run vcpkg export <mylibs> –nuget

Once again, the command specifies how to use the NuGet generated package. In this second case, the NuGet Package contains the binary of the library, the .lib, the .h and the .pdb. Of course, it also contains all the dependencies needed by the library.

We really value your feedback as an essential source of improvement. Please let us know if you have issues with this tool or usage scenario by opening an issue on GitHub or sending us an email at vcpkg@microsoft.com.

EricMittelette Senior Program Manager, VC++ Team

Follow