Tutorial: Install and use packages with MSBuild in Visual Studio

Article
04/30/2024

This tutorial shows you how to create a C++ "Hello World" program that uses the fmt library with MSBuild, vcpkg and Visual Studio. You'll install dependencies, configure, build, and run a simple application.

Prerequisites:

Visual Studio with C++ development workload
Git
Windows 7 or newer

1 - Set up vcpkg

Clone the repository

The first step is to clone the vcpkg repository from GitHub. The repository contains scripts to acquire the vcpkg executable and a registry of curated open-source libraries maintained by the vcpkg community. To do this, run:
```
git clone https://github.com/microsoft/vcpkg.git
```
The vcpkg curated registry is a set of over 2,000 open-source libraries. These libraries have been validated by vcpkg's continuous integration pipelines to work together. While the vcpkg repository does not contain the source code for these libraries, it holds recipes and metadata to build and install them in your system.
Run the bootstrap script

Now that you have cloned the vcpkg repository, navigate to the vcpkg directory and execute the bootstrap script:
```
cd vcpkg && bootstrap-vcpkg.bat
```
```
cd vcpkg; .\bootstrap-vcpkg.bat
```
```
cd vcpkg && ./bootstrap-vcpkg.sh
```
The bootstrap script performs prerequisite checks and downloads the vcpkg executable.

That's it! vcpkg is set up and ready to use.

Integrate with Visual Studio MSBuild

The next step is to set the user-wide instance of vcpkg so that MSBuild will be able to find it:

.\vcpkg.exe integrate install

This outputs:

All MSBuild C++ projects can now #include any installed libraries. Linking will be handled automatically. Installing new libraries will make them instantly available.

2 - Set up the Visual Studio project

Create the Visual Studio project
- Create a new project in Visual Studio using the "Console Application" template
Screenshot of the Visual Studio UI for showing how to create a new C++ Windows console application in Visual Studio
- Name your project "helloworld"
- Check the box for "Place solution and project in the same directory."
- Click the "Create" button
Screenshot of Visual Studio UI for naming your MSBuild C++ project and clicking the "create" button.
Configure the VCPKG_ROOT environment variable.
Open the built-in Developer PowerShell window in Visual Studio.

Screenshot of Visual Studio UI for the built-in PowerShell developer window

Run the following commands:
```
$env:VCPKG_ROOT = "C:\path\to\vcpkg"
$env:PATH = "$env:VCPKG_ROOT;$env:PATH"
```
Screenshot of Visual Studio UI for the built-in PowerShell developer window showing how to set up VCPKG_ROOT and and add it to PATH.

Note

Setting environment variables in this manner only affects the current terminal session. To make these changes permanent across all sessions, set them through the Windows System Environment Variables panel.
Open the Developer command prompt in Visual Studio.

Screenshot of Visual Studio UI for developer command prompt.

Run the following commands:
```
set VCPKG_ROOT="C:\path\to\vcpkg"
set PATH=%VCPKG_ROOT%;%PATH%
```
Screenshot of Visual Studio developer command prompt showing how to set up VCPKG_ROOT and and add it to PATH.

Note

Setting environment variables in this manner only affects the current terminal session. To make these changes permanent across all sessions, set them through the Windows System Environment Variables panel.
Setting VCPKG_ROOT helps Visual Studio locate your vcpkg instance. Adding it to PATH ensures you can run vcpkg commands directly from the shell.
Generate a manifest file and add dependencies.

Run the following command to create a vcpkg manifest file (vcpkg.json):
```
vcpkg new --application
```
The vcpkg new command adds a vcpkg.json file and a vcpkg-configuration.json file in the project's directory.

Add the fmt package as a dependency:
```
vcpkg add port fmt
```
Your vcpkg.json should now contain:
```
{
    "dependencies": [
        "fmt"
    ]
}
```
This is your manifest file. vcpkg reads the manifest file to learn what dependencies to install and integrates with MSBuild to provide the dependencies required by your project.

The generated vcpkg-configuration.json file introduces a baseline that places minimum version constraints on the project's dependencies. Modifying this file is beyond the scope of this tutorial. While not applicable in this tutorial, it's a good practice to keep the vcpkg-configuration.json file under source control to ensure version consistency across different development environments.

3 - Set up the project files

Modify the helloworld.cpp file.

Replace the content of helloworld.cpp with the following code:

#include <fmt/core.h>

int main()
{
    fmt::print("Hello World!\n");
    return 0;
}

This source file includes the <fmt/core.h> header which is part of the fmt library. The main() function calls fmt::print() to output the "Hello World!" message to the console.

Note

There will be error squiggles in your project when MSBuilds it for the first time. Build the project to acquire vcpkg dependencies to remove them.

4 - Enable manifest mode

Navigate to the Project Properties pages of your project. Under Configuration Properties > vcpkg, set Use vcpkg manifest to Yes. MSBuild checks whether this property is set before installing any dependencies from the vcpkg manifest.

Enable manifest mode in project properties

Other settings, such as triplets, are filled in with default values vcpkg detects from your project and will be useful when configuring your project.

5 - Build and run the project

Build the project.

Press Ctrl+Shift+B to build the project in Visual Studio and acquire the vcpkg dependencies.

If MSBuild detects a vcpkg.json file and manifests are enabled in your project, MSBuild installs the manifest's dependencies as a pre-build step. Dependencies are installed in a vcpkg_installed directory in the project's build output directory. Any headers installed by the library can be directly used, and any libraries installed will be automatically linked.

Note

vcpkg install builds both Debug and Release configurations for a library. To only build release libraries, add VCPKG_RELEASE_ONLY to your triplet.

Run the application.

Finally, run the executable:

Screenshot of Visual Studio UI for running the executable.

You should see the output:

Screenshot of the program outputs - "Hello World!"

Next steps

To learn more about vcpkg.json and vcpkg MSBuild integration, see our reference documentation:

Share via