A C++ project template based on CMake and vcpkg

• A C++ project template based on CMake and vcpkg
• 1. Description
• 2. Key features:
• 3. GitHub Action workflows
• 4. Rationale
• 5. Setup Guide
  • 5.1 Windows-specific setup guide
    • 5.1.1 Install Build Tools for Visual Studio 2022
    • 5.1.2 Install CMake & Ninja
    • 5.1.3 Open VSCode from Developer terminal for Visual Studio
  • 5.2 Setting up VSCode Extensions
• 6. Build, Debug, and Test
  • 6.1 How to build
  • 6.2 How to debug
  • 6.3 How to run test
• 7. Integrated Development Environment (IDE) Support
• 8. License

1. Description

This repository contains a C++ based project template that leverages vcpkg and CMake's CMakePresets.json to build and test C++ source code.

Supports Linux/macOS/Windows on x64 and arm64 platforms.

vcpkg is driven to use its binary caching feature storing the content in the GitHub Action cache, hence speeding up workflows by reusing previously built packages.

2. Key features:

• CMakePresets.json allows to run the same build either locally on your IDE and on GitHub runners.
• vcpkg greatly helps in pulling and building the needed dependencies (e.g. libraries) which are cached for reuse on GitHub Action cache.

3. GitHub Action workflows

The repository provides also two GitHub workflows to build the project on GitHub runners. Both builds and tests the project using vcpkg and CMake, the only key difference is their implementation:

• hosted-pure-workflow.yml: it is a pure workflow which does not use unneeded GitHub Actions that cannot run locally on your development machine. On the other hand it is directly using the CMake, Ninja, vcpkg and the C++ build tools.
• hosted-ninja-vcpkg_submod.yml: it is a concise workflow based on the custom GitHub Actions get-cmake, run-vcpkg and run-cmake which simplify and shorten the workflow verbosity while adding some goodies like vcpkg binary caching stored on GH's cache and inline error annotations.

4. Rationale

The main idea of this C++ project template is to show how to obtain a perfectly reproducible software development process that can be run anywhere without any difference and no surprises, either locally using your preferred tools/IDE, either remotely on build agents typically used for continuous integration.

5. Setup Guide

5.1 Windows-specific setup guide

If you are developing in Linux or macOS, skip to Section 5.2.

5.1.1 Install Build Tools for Visual Studio 2022

If you have already installed Visual Studio 2022, you can skip this part.

• Go to https://visualstudio.microsoft.com/downloads/
• In All Downloads, open up Tools for Visual Studio and download Build Tools for Visual Studio 2022
• Install the downloaded file

5.1.2 Install CMake & Ninja

• Install CMake (with adding PATH) [Download]
• Install Ninja build tool using winget:
  • winget install Ninja-build.Ninja

5.1.3 Open VSCode from Developer terminal for Visual Studio

Important

To properly build the project, you should always run VSCode from Developer terminal for Visual Studio.
Follow the guide below firmly.

• [IMPORTANT] If you are to build x86 binary,
  • Run launch_devtools_x86.bat
• [IMPORTANT] If you are to build x64 binary,
  • Run launch_devtools_x64.bat
• Run code .

Now you can build and run the project! Keep in mind you should always open the project like this way.

(If you clone this repository and open with plain VSCode, you will see following error after all:

[cmake] CMake Error: CMake was unable to find a build program corresponding to "Ninja Multi-Config".  CMAKE_MAKE_PROGRAM is not set.  You probably need to select a different build tool.
[cmake] CMake Error: CMAKE_C_COMPILER not set, after EnableLanguage
[cmake] CMake Error: CMAKE_CXX_COMPILER not set, after EnableLanguage

In this case, you should remove the builds directory and run the VSCode by launching the launch_devtools_x**.bat mentioned above.

5.2 Setting up VSCode Extensions

Go to extensions tab and install following extensions:

• C/C++
• C/C++ Extension Pack
• CMake
• CMake Langugage Support
• CMake Tools

After you install the above extensions and select in the status bar the CMake preset (e.g. ninja-multi-vcpkg), as show in the following image:

6. Build, Debug, and Test

Before build or debug, click the following button to choose the target:

Then choose the target:

6.1 How to build

• Open the command palette(ctrl+shift+p)
• Run CMake: Build to build all targets
• Run CMake: Build target to build the target currently selected

6.2 How to debug

• Open the command palette(ctrl+shift+p)
• Run CMake: Debug

6.3 How to run test

• Open the command palette(ctrl+shift+p)
• Run CMake: Run Tests

7. Integrated Development Environment (IDE) Support

The major C++ IDEs should already support CMakePresets.json and require no particular configuration.

For example Visual Studio Code with the CMake Tools extension let you to open the root folder of this repository, and select in the status bar the CMake preset (e.g. ninja-multi-vcpkg), as show in the following image:

8. License

All the content in this repository is licensed under the MIT License.

Copyright © 2024 Luca Cappa, Taein Kim