Purpose

This tutorial is made for existing projects that use vcpkg to manage their C++ dependencies.

Sometimes, it becomes necessary to modify some elements of a C++ library that your project depends on. Modifications can include:

• Changing compilation flags
• Changing installation strategies
• Changing source code
• Changing static data

This tutorial demonstrates how to apply these changes to a dependency installed with vcpkg in a way that'scheap,shareable, andpermanent.

The full process can be completed in 15 minutes.

Project Structure

We'll use a mock project structure, like so:

project/ |-- include/ |-- src/ |-- vcpkg/ |-- CMakeLists.txt |-- README.md

In this example, we'd likely set up the vcpkg CLI utility, like so:

# pwd: at project rootchmod +x ./vcpkg/bootstrap-vcpkg.sh./vcpkg/bootstrap-vcpkg.sh

Step (1 of 4): Create a Local Registry

The first change we'll make to the project structure is making a directory to hold our vcpkg portfiles.

APort is a small, cheap collection of metadata files which instruct vcpkg on how to download, configure, build, and install your dependencies.

To customize our dependency, we're going to copy its portfiles and place them in our own custom registry.

First, let's create a directory to hold our vcpkg portfiles:

# pwd: at project rootmkdirregistry

Call it whatever you'd like. This tutorial refers to it as alocal registry.

Step (2 of 4): Copy the Port Files

This tutorial will use the fake "foobaz" package as an example.

# pwd: at project root./vcpkg/vcpkginstallfoobaz

We're going to copy thefoobaz portfiles into ourlocal registry in order to apply our modifications in the future.

# pwd: at project rootcp-r ./vcpkg/ports/foobaz ./registry/foobaz

Take a look inside./registry/foobaz and you'll probably see three files:

project/ |-- registry/ |    |-- foobaz/ |    |    |-- build_fixes.patch |    |    |-- portfile.cmake |    |    |-- vcpkg.json

Let's examine each of them.

• build_fixes.patch is agit diff that vcpkg applies to your dependency's source tree before compiling and installing it.
• portfile.cmake is acmake script that tells vcpkg where to find your dependency's source tree, plus some other stuff.
• vcpkg.json is ametadata file that's conceptually similar to a package.json file from the Node.js universe.

It's recommended to keepvcpkg.json the same.

This tutorial is going to demonstrate how to generate a newbuild_fixes.patch file, and it will contain the modifications you want to apply to the source code, build configuration, etc.

Please note thatportfile.cmake is run in CMake's script mode, so wecannot use this to change build parameters for our dependency. Those must be modified from within thebuild_fixes.patch instead.

Step (3 of 4): Generating a Patch File

Awesome, it's time to make some changes!

First, clone the dependency's source tree, so we can make our changes. This is a temporary folder that won't be checked into your git project. I'm cloning inside ofregistry/foobaz for convenience, but you may put it anywhere you'd like.

# pwd: at project/registry/foobazgit clone https://github.com/username/foobaz.gitsource

Next, we're going to apply the existingbuild_fixes.patch file on top of the source tree. This puts our dependency's source into the state that vcpkg uses by default when you install it.

# pwd: at project/registry/foobaz/sourcegit apply ../build_fixes.patch

Now, it's time to make your changes! You can modify theCMakeLists.txt to adjust build configuration, comment out source files, introduce new code, whatever the hell you want.

After applying your modifications, create a newgit diff file. This overwrites the existingbuild_fixes.patch with the changes you've just made (plus whatever was already there).

# pwd: at project/registry/foobaz/sourcegit diff> ../build_fixes.patch

Remove the source tree when you're done.

# pwd: at project/registry/foobazrm-rfsource

Finale (4 of 4): Use your Modified Dependency

It is necessary to removefoobaz from vcpkg so that we can re-install our modified version.

# pwd: at project/./vcpkg/vcpkg remove foobaz

From now on, to make vcpkg download your modified dependency, the CLI tool must be invoked like so:

# pwd: at project/./vcpkg/vcpkginstallfoobaz--overlay-ports=registry/foobaz

Check it out!You're done! 🎈

Find me ongithub