Skip to content

Latest commit

 

History

History
191 lines (133 loc) · 8.54 KB

get-started-vs.md

File metadata and controls

191 lines (133 loc) · 8.54 KB
Raw
title description zone_pivot_group_filename zone_pivot_groups author ms.author ms.topic ms.date
Install and use packages with CMake in Visual Studio
Tutorial guides the user through the process of installing and using packages with CMake and Visual Studio.
zone-pivot-groups.json
shell-selections
JavierMatosD
javiermat
tutorial
01/10/2024

Tutorial: Install and use packages with CMake in Visual Studio

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

Prerequisites

1 - Set up vcpkg

[!INCLUDE setup-vcpkg]

2 - Set up the Visual Studio project

  1. Create the Visual Studio project

    • Create a new project in Visual Studio using the "CMake Project" template :::image type="complex" source="../resources/get_started/visual-studio-create-project.png" alt-text="create a new CMake project"::: Screenshot of the Visual Studio UI for showing how to create a new CMake project in Visual Studio :::image-end:::
    • Name your project "helloworld"
    • Check the box for "Place solution and project in the same directory."
    • Click the "Create" button :::image type="complex" source="../resources/get_started/visual-studio-name-project.png" alt-text="naming your CMake project"::: Screenshot of Visual Studio UI for naming your CMake project and clicking the "create" button. :::image-end:::

  2. Configure the VCPKG_ROOT environment variable.

    ::: zone pivot="shell-powershell" Open the built-in Developer PowerShell window in Visual Studio.

    :::image type="complex" source="../resources/get_started/visual-studio-developer-powershell.png" alt-text="opening built-in developer powershell"::: Screenshot of Visual Studio UI for the built-in PowerShell developer window :::image-end:::

    Run the following commands:

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

    :::image type="complex" source="../resources/get_started/visual-studio-environment-variable-setup-powershell.png" alt-text="setting up your environment variables"::: 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. :::image-end:::

    [!INCLUDE env-vars]

    ::: zone-end ::: zone pivot="shell-cmd" Open the Developer command prompt in Visual Studio.

    :::image type="complex" source="../resources/get_started/visual-studio-developer-cmd.png" alt-text="opening Visual Studio developer command prompt."::: Screenshot of Visual Studio UI for developer command prompt. :::image-end:::

    Run the following commands:

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

    :::image type="complex" source="../resources/get_started/visual-studio-environment-variable-setup-cmd.png" alt-text="setting up your environment variables"::: Screenshot of Visual Studio developer command prompt showing how to set up VCPKG_ROOT and and add it to PATH. :::image-end:::

    [!INCLUDE env-vars]

    ::: zone-end

    Setting VCPKG_ROOT helps Visual Studio locate your vcpkg instance. Adding it to PATH ensures you can run vcpkg commands directly from the shell.

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

  1. Modify the helloworld.cpp file.

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

    :::code language="cpp" source="../examples/snippets/get-started/main.cpp":::

    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.

  2. Configure the CMakePresets.json file.

    • Rename the CMakePresets.json file to CMakeUserPresets.json
    • Update its contents as shown below. Replace <VCPKG_ROOT> with the path to your vcpkg directory.
    {
  "version": 2,
  "configurePresets": [
    {
      "name": "default",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "<VCPKG_ROOT>/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}
    • Since this file includes a hardcoded absolute path, it is recommended that you don't keep this file under source control. If you're using Git, add CMakeUserPresets.json to your .gitignore file.

    The CMakeUserPresets.json file contains a single preset named "default", this preset sets the CMAKE_TOOLCHAIN_FILE to use vcpkg's CMake toolchain file. This lets vcpkg provide packages to CMake when you configure and build the project. Read the vcpkg CMake integration documentation to learn more.

  3. Edit the CMakeLists.txt file.

    Replace the contents of the CMakeLists.txt file with the following code:

    :::code language="cmake" source="../examples/snippets/get-started/CMakeLists.txt":::

    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, the build fails.
    • 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.

4 - Build and run the project

  1. Build the project.

    Press Ctrl+Shift+B to build the project in Visual Studio.

  2. Run the application.

    Finally, run the executable: :::image type="complex" source="../resources/get_started/visual-studio-run-project.png" alt-text="Running the executable"::: Screenshot of Visual Studio UI for running the executable. :::image-end:::

    You should see the output: :::image type="complex" source="../resources/get_started/visual-studio-helloworld-output.png" alt-text="Program output"::: Screenshot of the program outputs - "Hello World!" :::image-end:::

Next steps

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