Tutorial: Install and use packages with CMake in Visual Studio Code

Article
02/27/2024

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

Prerequisites

Visual Studio Code
C++ compiler
Windows 7 or newer

This example uses the C++ MSVC compiler in the Visual Studio C++ development workload.

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.

2 - Install Visual Studio Code Extensions

Navigate to the Extension view, and install the C++ Extension. This enables C++ IntelliSense and code navigation.

installing C++ Visual Studio Code Extension

Install the CMake Tools Extension. This enables CMake support in Visual Studio Code.

installing CMake Tools Visual Studio Code Extension

3 - Setup vcpkg

Configure the VCPKG_ROOT environmental variable.

Open a new Terminal in Visual Studio Code: Terminal > New Terminal

Run the following commands:

$env:VCPKG_ROOT="C:\path\to\vcpkg"
$env:PATH="$env:VCPKG_ROOT;$env:PATH"

setting up vcpkg environment variables

set "VCPKG_ROOT=C:\path\to\vcpkg"
set PATH=%VCPKG_ROOT%;%PATH%

VCPKG_ROOT=/c/path/to/vcpkg
PATH=$PATH:$VCPKG_ROOT

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

Create the CMakeLists.txt file with the following content:

cmake_minimum_required(VERSION 3.10)

project(HelloWorld)

find_package(fmt CONFIG REQUIRED)

add_executable(HelloWorld helloworld.cpp)

target_link_libraries(HelloWorld PRIVATE fmt::fmt)

Now, let's break down what each line in the CMakeLists.txt file does:

cmake_minimum_required(VERSION 3.10): Specifies that the minimum version of CMake required to build the project is 3.10. If the version of CMake installed on your system is lower than this, an error will be generated.
project(HelloWorld): Sets the name of the project to "HelloWorld."
find_package(fmt CONFIG REQUIRED): Looks for the fmt library using its CMake configuration file. The REQUIRED keyword ensures that an error is generated if the package is not found.
add_executable(HelloWorld main.cpp): Adds an executable target named "HelloWorld," built from the source file main.cpp.
target_link_libraries(HelloWorld PRIVATE fmt::fmt): Specifies that the HelloWorld executable should link against the fmt library. The PRIVATE keyword indicates that fmt is only needed for building HelloWorld and should not propagate to other dependent projects.

Create the helloworld.cpp file with the following content:

#include <fmt/core.h>

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

In this helloworld.cpp file, the <fmt/core.h> header is included for using the fmt library. The main() function then calls fmt::print() to output the "Hello World!" message to the console.

To allow the CMake project system to recognize C++ libraries provided by vcpkg, you'll need to provide the vcpkg.cmake toolchain file. To automate this, create a CMakePresets.json file in the "helloworld" directory with the following content:

{
  "version": 2,
  "configurePresets": [
    {
      "name": "vcpkg",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

Create CMakeUserPresets.json file in the "helloworld" directory with the following content:

{
  "version": 2,
  "configurePresets": [
    {
      "name": "default",
      "inherits": "vcpkg",
      "environment": {
        "VCPKG_ROOT": "<path to vcpkg>"
      }
    }
  ]
}

This CMakePresets.json file contains a single "vcpkg" preset for CMake and sets the CMAKE_TOOLCHAIN_FILE variable. The CMAKE_TOOLCHAIN_FILE allows the CMake project system to recognize C++ libraries provided by vcpkg. Only CMakePresets.json is meant to be checked into source control while CMakeUserPresets.json is to be used locally.

4 - Build and run the project

Run the CMake: Build command the project by navigating to the Command Palette in View > Command Palette

CMake build command in Visual Studio Code

Select the default CMake preset. This enables the vcpkg toolchain.

Selecting preset in CMake build command in Visual Studio Code

Launch the project

You should see the output:

Hello World!

Next steps

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