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

Article
09/25/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

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 - Create a project folder

Note

If you're running this tutorial in Windows and using MSVC as your compiler you need to start the Visual Studio Code instance from a Developer Command Prompt for VS or Developer PowerShell for VS. This ensures that the compiler path and other environment variables are correctly set up.

Create a folder to hold the project files in a location of your choice. For this tutorial, we create a folder named "helloworld". Then open the folder using Visual Studio Code.

mkdir helloworld
code helloworld

3 - 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

4 - Set up environment variables

Configure the VCPKG_ROOT environmental variable.

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

Run the following commands:

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.

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

setting up vcpkg environment variables

Note

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

Note

Setting environment variables using the export command only affects the current shell session. To make this change permanent across sessions, add the export command to your shell's profile script (e.g., ~/.bashrc or ~/.zshrc).

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

Setting VCPKG_ROOT helps Visual Studio Code 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) in the root of the helloworld folder:

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.

5 - Set up the project files

Create the CMakeLists.txt file

Create a new file named CMakeLists.txt in the root of the project folder 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)

Let's break down what each line in the CMakeLists.txt file:

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 helloworld.cpp): Adds an executable target named "HelloWorld," built from the source file helloworld.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.

6 - 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

Run the program:

./build/HelloWorld.exe

./build/HelloWorld

You should see the output:

Hello World!

Next steps

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

Share via

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

Prerequisites

1 - Set up vcpkg

2 - Create a project folder

3 - Install Visual Studio Code Extensions

4 - Set up environment variables

5 - Set up the project files

6 - Build and run the project

Next steps

Additional resources