Vcpkg: Using multiple enlistments

Vcpkg allows you to acquire and build 3rd 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:

clip_image002

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

clip_image004

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 8th, 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.

clip_image006

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

clip_image008

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

clip_image010

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:

clip_image012

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

clip_image014

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.