3. Integrate vcpkg with MSBuild / Visual Studio

Free, Unlimited Access

Comprehensive course covering advanced concepts, and how to use them on large-scale projects.

Professional C++





<Excerpt>


When working with C++, we’re not restricted to just working with the standard library.  There is a huge and diverse ecosystem of other libraries we can use, covering a large range of uses.


Rather than reinventing the wheel in every project, we can import libraries created by other developers that can meet our needs.


In upcoming lessons, we’re going to begin relying more and more on these external libraries.


However, manually downloading and managing packages is a cumbersome process.  A range of options have been created that help us manage our dependencies more effectively.


The most popular options are currently [vcpkg](https://vcpkg.io/en/) and [Conan](https://conan.io/).


For this course, we’ll use vcpkg, and in this lesson, we’ll walk through the installation process and some common issues that can occur in Windows. but feel free to use any option


</Excerpt>


<Ad />


## Installing vcpkg


We need to compile vcpkg from the source code, but a simple script is provided that will do this for us with a single command.


A common installation and setup for vcpkg involves four steps:

- Downloading the Source Code
- Building the Source Code
- Integrating vcpkg with MSBuild
- Setting our default target

We walk through these four steps below.


<Aside>


### Installing vcpkg in Visual Studio


Recent versions of Visual Studio allow vcpkg to be installed as an individual component, alongside Visual Studio.  This approach can cause issues, so we should use the manual installation process instead.


The version of vcpkg that is integrated with Visual Studio only supports “manifest mode”, which is a more complex form of dependency management.  We cover manifest mode in a later chapter when we introduce build automation.


</Aside>


### 1. Download from GitHub


A zip containing the source code we need is available from the [releases page on GitHub](https://github.com/microsoft/vcpkg/releases/).


We should download the source code from the Assets section of the latest release:


<Img file=”vcpkg-install-1.jpg” width=”890” height=”359” alt=”Screenshot of the GitHub releases page for vcpkg” blurHash=”L0S6Pk0000000000.40000^m?wMb” />


Once acquired, we should unzip this folder to a location on our hard drive.  We will be accessing it frequently, so ensure it is in a location we’ll easily be able to find later.


<Aside>


### Downloading vcpkg with git


Git users can quickly clone the latest code, rather than downloading a zip file:


```c++
//<ti>
git clone https://github.com/Microsoft/vcpkg.git
```


</Aside>


### 2. Run bootstrap-vcpkg.bat


To compile vcpkg and generate the executable file, we can run the `bootstrap-vcpkg.bat` in the folder where we unzipped everything.


Once complete, the script should have created an executable file - vcpkg.exe - in the same directory.


### 3. Integrate vcpkg with MSBuild / Visual Studio


To easily use the packages we download, we need to integrate vcpkg with our C++ build tools.  By default, this is MSBuild on Windows.


vcpkg also has a script for this, as part of the executable we generated in the previous step


vcpkg.exe is a command line tool.  To use it, we need to execute it from a terminal, which allows us to pass additional arguments.


On Windows, we can open a Power Shell terminal window in our vcpkg directory using _Shift + Right Click > Open PowerShell Window here_


From PowerShell, we can run the following command to integrate vcpkg with MSBuild:


```c++
//<ti>
.\vcpkg integrate install
```


This should generate a success message, indicating C++ projects can now #include installed libraries.


If this script generates an error stating vcpkg is not recognized, we need to ensure we ran the bootstrap-vcpkg.bat file from step 2, and that we’re opening our PowerShell window in the same location as the vcpkg.exe file that was generated.


### 4. Set Default Triplet


There are many possible environments we can build C++ applications for.  For example, these can include PCs running Windows, phones running iOS, smartwatches, etc.  A triplet is a simple string that specifies what the target environment is.  For example, `x64-windows` specifies our target is 64-bit Windows devices.


When we download a package through vcpkg, we need to specify which target we want.  We can do that every time we install a package, but it’s usually easier to specify a default.


We do that by creating a `VCPKG_DEFAULT_TRIPLET` as an environment variable.


We can do that through _Control Panel > System Properties > Advanced > Environment Variables_, and click “New” within the User Variables section.


<Img file=”vcpkg-install-2.jpg” width=”663” height=”175” alt=”Screenshot showing an environment variable being set in Windows” blurHash=”L5RfkB9FD%xu~qWBayay4n-;xuRj” />


Alternatively, we can run this PowerShell command:


```c++
//<ti>
[System.Environment]::SetEnvironmentVariable(
  'VCPKG_DEFAULT_TRIPLET','x64-windows', 'User'
)
```


<Ad />


## Installing Packages with vcpkg


We can install packages through vcpkg by using the `vcpkg install` command, followed by the names of the packages we want to install.


<NotCourse id={6}>
For example, let's install _**spdlog**_, a popular third-party library for logging.  As before, open a PowerShell terminal in our vcpkg installation directory, and run this command:


```c++
//<ti>
.\vcpkg install spdlog
```


If successful, we should now be able to immediately #include this library in our Visual Studio projects:


```c++
#include <spdlog/spdlog.h>

int main() {
  spdlog::info("hello world");
  spdlog::error("oh no!");
}
```


```c++
//<o>
[2023-06-21 14:12:33.945] [info] hello world
[2023-06-21 14:12:33.946] [error] oh no!
```


</NotCourse>
<OnlyCourse id={6}>
Let's now install the SDL libraries with vcpkg. As before, let’s open a PowerShell terminal in our vcpkg installation directory, and run this command:


```c++
//<ti>
.\vcpkg install sdl2 sdl2-image sdl2-ttf
```


If successful, we should now be able to immediately `#include` this library in our Visual Studio projects, and ensure they compile successfully:


```c++
#define SDL_MAIN_HANDLED
#include <SDL2/SDL.h>
#include <SDL2/SDL_image.h>
#include <SDL2/SDL_ttf.h>

int main(){
  SDL_Init(SDL_INIT_VIDEO);
  IMG_Init(IMG_INIT_PNG);
  TTF_Init();
}
```


</OnlyCourse>


## Troubleshooting


If the `#include` directive isn’t working following the above steps, the problem is likely to be one of two possibilities:


### 1. The `integrate` script didn’t run


Ensure step 2 from the installation instructions above is completed successfully.


### 2. Target/Triplet Mismatch


We need to ensure the platform we’re building for in Visual Studio matches the target of the package we downloaded.  We can see our Visual Studio target (eg x64) from the dropdown near the _Run_ button, or _Build Menu > Configuration Manager_


<Img file=”vcpkg-install-3.jpg” width=”717” height=”459” alt=”Screenshot showing the configuration manager in Visual Studio” blurHash=”L2RW0bIURjt7~qD%t7RP9FM{WBRj” />


In the above example, we’re building for x64, or the `x64-windows` triplet.


We can see what vcpkg packages we have downloaded by running `.\vcpkg.exe list` from the vcpkg directory.  For example, if our Visual Studio build configuration is targeting x64, we should ensure that the list includes the `x64-windows` version of our package:


```c++
//<ti>
.\vcpkg.exe list
```


If it’s missing, we can specify the desired triplet as an additional argument to the `vcpkg install` command:


<NotCourse id={6}>


```c++
//<ti>
.\vcpkg install spdlog --triplet x64-windows
```


</NotCourse>


<OnlyCourse id={6}>


```c++
//<ti>
.\vcpkg install sdl2 --triplet x64-windows
```


</OnlyCourse>


Alternatively, we can set the default triplet by following step 4 of the installation instructions above.  The default triplet will be used when we do not explicitly specify one as part of the `install` command.


## Summary


In this lesson, we've navigated through the steps of installing vcpkg on Windows, allowing us to manage external C++ libraries.  The key takeaways include:

- Package managers and their role in simplifying library management.
- An introduction to vcpkg, a C++ package manager created and maintained by Microsoft.
- Installing and integrating vcpkg with MSBuild and Visual Studio.
- Understood how to set a default target environment using triplets to tailor library installations for specific platforms.
- Explored the process of installing packages with vcpkg and troubleshooting common issues.

<FAQ>


```javascript
//<m>
{
  slug: 'using-vcpkg-with-non-msvc-compilers',
  title: 'Using vcpkg with Non-MSVC Compilers',
  question: 'Can I use vcpkg with other compilers like MinGW or Clang on Windows?',
}
```


Yes, vcpkg supports integration with various compilers on Windows, including MinGW and Clang. To use vcpkg with a non-MSVC compiler, you need to set the appropriate triplet when installing packages.


For example, to install a package for MinGW-w64, you can use the `x64-mingw-static` triplet:


```c++
//<ti>
.\vcpkg install spdlog --triplet x64-mingw-static
```


Make sure to configure your build system or IDE to use the correct compiler and include paths for the installed packages.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'updating-vcpkg-and-packages',
  title: 'Updating vcpkg and Installed Packages',
  question: 'How can I update vcpkg and the installed packages to the latest versions?',
}
```


To update vcpkg itself and the installed packages, you can follow these steps:

1. Open a PowerShell terminal in your vcpkg directory.
2. Update vcpkg by running the following command:

```c++
//<ti>
.\vcpkg update
```


This will fetch the latest changes from the vcpkg repository.


To update your installed packages, run:


```c++
//<ti>
.\vcpkg upgrade
```


vcpkg will check for available updates and upgrade the packages to their latest versions.


It's recommended to regularly update vcpkg and your packages to benefit from bug fixes, performance improvements, and new features.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'using-vcpkg-with-cmake',
  title: 'Using vcpkg with CMake Projects',
  question: 'How can I integrate vcpkg with my CMake projects on Windows?',
}
```


Integrating vcpkg with CMake projects on Windows is straightforward. Here's how you can do it:


**Step 1**: Make sure you have installed and integrated vcpkg with your build system as described in the lesson.


**Step 2**: In your CMake project, add the following lines to your `CMakeLists.txt` file before the `project()` command:


```text
//<cmake>
cmake_minimum_required(VERSION 3.0)

set(CMAKE_TOOLCHAIN_FILE "{vcpkg_root}/scripts/buildsystems/vcpkg.cmake")
```


Replace `{vcpkg_root}` with the actual path to your vcpkg installation directory.


**Step 3**: Use `find_package()` to locate the libraries you want to use in your project. For example:


```text
//<cmake>
find_package(spdlog CONFIG REQUIRED)
```


**Step 4**: Link the libraries to your target using `target_link_libraries()`:


```text
//<cmake>
target_link_libraries(your_target PRIVATE spdlog::spdlog)
```


**Step 5**: Configure and build your project using CMake as usual.


By setting the `CMAKE_TOOLCHAIN_FILE` variable and using `find_package()`, CMake will automatically locate the installed vcpkg packages and make them available for linking in your project.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'vcpkg-installation-directory',
  title: 'Choosing the vcpkg Installation Directory',
  question: 'Does the location where I install vcpkg matter? Are there any best practices?',
}
```


The location where you install vcpkg is flexible, but there are a few considerations to keep in mind:

1. Accessibility: Choose a location that is easily accessible and convenient for you to navigate to. You'll need to frequently access the vcpkg directory to install packages and run commands.
2. Permissions: Ensure that you have the necessary permissions to read, write, and execute files in the vcpkg directory. Avoid installing vcpkg in system directories that require elevated privileges.
3. Path length: On Windows, there is a maximum path length limit. If you encounter issues related to long paths, consider installing vcpkg in a directory with a shorter path.
4. Consistency: If you work on multiple projects or collaborate with others, it can be beneficial to have a consistent location for vcpkg across different environments. This makes it easier to share project configurations and setup instructions.

A common convention is to install vcpkg in a directory like `C:\vcpkg` or `C:\Tools\vcpkg`. You can also install it in a subdirectory of your project if you prefer to keep it self-contained.


Remember to update any necessary environment variables or configuration files if you move the vcpkg installation directory.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'vcpkg-and-version-control',
  title: 'Managing vcpkg with Version Control Systems',
  question: 'Should I include the vcpkg directory in my version control system?',
}
```


When it comes to managing vcpkg with version control systems like Git, there are a few approaches you can consider:

1. Exclude vcpkg directory: You can choose to exclude the entire vcpkg directory from version control by adding it to your `.gitignore` file (or equivalent for other version control systems). This keeps your repository clean and avoids tracking the vcpkg source code and installed packages.
2. Include vcpkg as a submodule: If you want to include vcpkg in your repository but keep it as a separate entity, you can add it as a Git submodule. This allows you to specify a specific version of vcpkg and keeps it separate from your main project files.
3. Include specific files: If you have custom triplets, ports, or configuration files within the vcpkg directory that you want to track, you can selectively include those files in your version control system while excluding the rest of the vcpkg directory.

The choice depends on your project's requirements and collaboration needs. If you have multiple developers working on the project, it's generally recommended to exclude the vcpkg directory from version control and provide clear instructions on how to install and set up vcpkg independently.


By excluding vcpkg, you can avoid potential conflicts and ensure that each developer has control over their own vcpkg installation and package versions.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'using-vcpkg-with-continuous-integration',
  title: 'Using vcpkg with Continuous Integration Systems',
  question: 'How can I use vcpkg in a continuous integration (CI) environment?',
}
```


Using vcpkg in a continuous integration (CI) environment allows you to automate the installation of dependencies and ensure consistent builds across different machines. Here's a general approach to using vcpkg in a CI setup:

1. Install vcpkg: In your CI configuration file (e.g., `.travis.yml`, `appveyor.yml`, or `azure-pipelines.yml`), add a step to clone or download the vcpkg repository.
2. Bootstrap vcpkg: Run the `bootstrap-vcpkg` script to build vcpkg itself.
3. Install dependencies: Use the `vcpkg install` command to install the required packages for your project. You can specify the packages in a configuration file or directly in the CI script.
4. Integrate vcpkg: Run `vcpkg integrate install` to set up the necessary environment variables and integrate vcpkg with your build system.
5. Build your project: Proceed with building your project using the appropriate build commands or scripts.

Here's an example of how you can set up vcpkg in an Azure Pipelines configuration file:


```yaml
steps:
- task: Git@2
  displayName: 'Clone vcpkg'
  inputs:
    repository: 'https://github.com/Microsoft/vcpkg.git'
    path: 'vcpkg'

- script: .\vcpkg\bootstrap-vcpkg.bat
  displayName: 'Bootstrap vcpkg'

- script: .\vcpkg\vcpkg install spdlog
  displayName: 'Install dependencies'

- script: .\vcpkg\vcpkg integrate install
  displayName: 'Integrate vcpkg'

- script: msbuild your_project.sln
  displayName: 'Build the project'
```


Adjust the steps and commands based on your specific CI system and project requirements.


By incorporating vcpkg into your CI pipeline, you can ensure that the necessary dependencies are installed and the project builds successfully in the CI environment.


</FAQ>



An introduction to C++ package managers, and a step-by-step guide to installing vcpkg on Windows and Visual Studio.

Using vcpkg with Non-MSVC Compilers

Updating vcpkg and Installed Packages

Using vcpkg with CMake Projects

Choosing the vcpkg Installation Directory

Managing vcpkg with Version Control Systems

Using vcpkg with Continuous Integration Systems

Moved lesson to a later chapter and updated content

microsoft/vcpkg: C++ Library Manager for Windows, Linux, and MacOS

Get Started with Vcpkg

Vcpkg README

Microsoft Vcpkg Docs

Manifest Mode in Vcpkg

Microsoft Vcpkg Tool: Components of Vcpkg's Binary

A detailed guide for setting up vcpkg (C++ package manager) on Windows and integrating it with MSBuild / Visual Studio Projects

Updating vcpkg and Installed Packages

How can I update vcpkg and the installed packages to the latest versions?

Installing vcpkg on Windows

Can I use vcpkg with other compilers like MinGW or Clang on Windows?

How can I integrate vcpkg with my CMake projects on Windows?

Does the location where I install vcpkg matter? Are there any best practices?

Should I include the vcpkg directory in my version control system?

How can I use vcpkg in a continuous integration (CI) environment?

Installing vcpkg on Windows

Professional C++

This course includes:

Professional C++