Vcpkg

vcpkg is Microsoft's C++ package manager. It ships as source code that you build. It includes several tools such as:

• CMake - Because the other build tools that Microsoft ships (nmake, MSBuild) just aren't good enough.
• 7Zip (7za)
• bash
• git
• MinGW
• nuget

What It Does

vcpkg performs three basic tasks:

1. Download source code
2. Compile source code into libraries/executables
3. Copy files to well known folders

Prerequisites

• A command line git client.
• PowerShell

Getting vcpkg

Here's how to put a C++ library project into a package. These steps are derived from this article.

1. Create a folder

   mkdir MyProject
   

2. Go into that folder

   cd MyProject
   

3. Get the vcpkg source code

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

4. Go into the vcpkg folder

   cd vcpkg
   

5. Start Powershell

   powershell
   

6. Compile vcpkg

   .\bootstrap-vcpkg.bat
   

7. As of this writing, 2019-10-24, vcpkg defaults to 32-bit builds. To get it to use 64-bit you must set a global environment variable to something called a "triplet" which is a long string with two fields in it.

   VCPKG_DEFAULT_TRIPLET=x64-windows
   

8. Integrate vcpkg with your build system

   .\vcpkg integrate install
   

   You can uninstall the integration by:

   .\vcpkg integrate remove
   

9. vcpkg is now ready to use. To get and compile a package, you use the install command.

   .\vcpkg install curl
   

Recommended Environment Variables

• VCPKG_DEFAULT_TRIPLET=x64-windows
• VCPKG_PLATFORM_TOOLSET=v142
• VCPKG_TARGET_ARCHITECTURE=x64

How it Works

The vcpkg package manager gets the package information for packages it knows how to get from a folder named ports The package name is the name of a folder in ports That named folder will contain at least a CONTROL file and a portfile.cmake. When you "install" a package, the compilation result will be written to a sub-folder named packages with the name of the package, an underscore and the triplet (the two-field string).

vcpkg uses CMake as the primary build tool that can spawn other build tools to build your code.

Sample

vcpkg install wfc

vcpkg will then:

1. Read a file named ports/wfc/portfile.cmake
2. Download the source code to a folder named buildtrees/wfc/src
3. It will then build the source code
4. It will copy the compiled results from step 2 to a folder named packages/wfc_x64-windows

If you want to delete an installed package:

vcpkg remove wfc

Adding a New Package

Make a folder in the ports folder with the name of your new package (wfc). Go into that folder to do your work. You must create two files, CONTROL and portfile.cmake

CONTROL

This file gives you a description of the package (aka library).

Source: wfc
Version: 77
Description: Win32 Foundation Classes is a C++ library to help with Win32 programming.

portfile.cmake

This file is basically a build script, in yet another build-script language. This one is in CMake.

include(vcpkg_common_functions)

if (NOT VCPKG_TARGET_IS_WINDOWS)
    message(FATAL_ERROR "\n${PORT} does not support your system, only Windows for now. Please open a ticket issue on github.com/microsoft/vcpkg if necessary\n")
endif()

vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO SammyB428/WFC
    REF dd41bd5e3f2ed8daa9d87adde938b156317bc3b9
    SHA512 d02c7cde8cfed24db5ca52e46e15f866d1dcec3f42013d059ad60fc98bedeec3409b8dad768ad53918a4f152ee07442dcbe9234aa2e625daba4038f1ef24efc9
    HEAD_REF master
)

vcpkg_install_msbuild(
    SOURCE_PATH ${SOURCE_PATH}
    PROJECT_SUBPATH lib/WFC.sln
    INCLUDES_SUBPATH INCLUDE
    LICENSE_SUBPATH LICENSE
    REMOVE_ROOT_INCLUDES
    USE_VCPKG_INTEGRATION
    PLATFORM x64
    RELEASE_CONFIGURATION "STL Unicode Release"
    DEBUG_CONFIGURATION "STL Unicode Debug"
)

The really important fields are:

vcpkg_from_github

This is a CMake function defined in vcpkg\scripts\cmake\vcpkg_from_github.cmake which will clone a GitHub project so it can be built locally.

REPO

This field holds the github repository name (SammyB428/WFC) to retrieve.

REF

This is either the release name of the repository to get OR the hash of the commit to retrieve. In our example, we are retrieving a specific commit dd41bd5e3f2ed8daa9d87adde938b156317bc3b9

SHA512

This is the SHA-512 of the ZIP file downloaded from github.

The get the correct SHA-512 value for the SHA512 line, just set it to "1" then run:

vcpkg install wfc

This will generate an error message with the desired hash in it.

C:\Users\Sam\Documents\vcpkg\vcpkg>vcpkg.exe install wfc
The following packages will be built and installed:
    wfc[core]:x86-windows
Starting package 1/1: wfc:x86-windows
Building package wfc[core]:x86-windows...
-- Using cached C:/Users/Sam/Documents/vcpkg/vcpkg/downloads/SammyB428-WFC-dd41bd5e3f2ed8daa9d87adde938b156317bc3b9.tar.gz
CMake Error at scripts/cmake/vcpkg_download_distfile.cmake:99 (message):


 File does not have expected hash:

          File path: [ C:/Users/Sam/Documents/vcpkg/vcpkg/downloads/SammyB428-WFC-dd41bd5e3f2ed8daa9d87adde938b156317bc3b9.tar.gz ]
      Expected hash: [ 1 ]
        Actual hash: [ d02c7cde8cfed24db5ca52e46e15f866d1dcec3f42013d059ad60fc98bedeec3409b8dad768ad53918a4f152ee07442dcbe9234aa2e625daba4038f1ef24efc9 ]

  Please delete the file and retry if this file should be downloaded again.

Copy the value from the Actual hash: field of the error message to the SHA512 field.

vcpkg_install_msbuild

This is a CMake function defined in vcpkg\scripts\cmake\vcpkg_install_msbuild.cmake which will build then install an MSBuild-based project.

PROJECT_SUBPATH

The relative path from the root of the unzipped file where your solution file resides.

PLATFORM

The platform identifier that matches the platform identifier in your vcxproj file.

RELEASE_CONFIGURATION

The name of the configuration in your vcxproj file that will produce the "Release" build.

DEBUG_CONFIGURATION

The name of the configuration in your vcxproj file that will produce the "Debug" build.