C/C++ project template for VSCode, using CMake and conan

Introduction

This template provides a small set of .json files in .vscode folder to properly setup VSCode locally while developping C/C++ projects whose build tools are based on CMake (meta build system), Ninja generator, and conan 1.x client (C/C++ package manager). It is designed to:

• allow non-intrusive integration of conan.
• be as generic and with less manual tweaks as possible.

Basically you add your dependencies in conanfile.txt (or conanfile.py), call conan initialize task, and update your CMakeLists files accordingly. Configure/Build & Debugging inside VSCode should work out of the box even when complex dependencies (like SDK and frameworks) are involved.

This template assumes usage of CMake kits of CMake Tools extension, not CMake presets (autodetection by CMake Tools extension is explicitly disabled). Contributions to provide a robust template based on CMakePresets.json files generated by conan (and/or a custom CMakeUserPresets.json) are welcome.

Prerequisites

• A working C/C++ compiler/toolchain (e.g GCC, LLVM, Visual C++)
• conan 2.x client
• CMake >= 3.15
• Ninja
• VSCode with these extensions:
  • C/C++
  • clangd
  • CMake Tools

Workflow

Global Setup

1. Initialize your Kits for CMake Tools extension if not already done.
2. Rename these Kits names or your conan profiles so that they can match. There should exist one conan profile per Kit. Indeed, this setup relies on Kit names to know which conan profile should be called.
3. Add "environmentSetupScript": "${workspaceFolder}/build/${buildKit}/${buildType}/.conan/conanbuild[.sh|.bat]" property in your Kits (.bat for Windows, .sh otherwise).

Project Initialization

1. Select a Kit and build variant through CMake Tools interface.
2. Add your dependencies under [requires] section of conanfile.txt, and your build dependencies under [tool_requires].
3. Launch conan initialize task in VSCode (through Command Palette or an extension like Task Explorer).
4. Select the Kit again.
5. Run CMake reconfiguration.
6. Restart clangd server (in Command Palette).

Configure/Build

You can use CMake Tools extension as usual.

Debug

• In Debugger panel, select C++ MSVC Debug if compiler is MSVC, C++ GNU Debug otherwise.

• Press F5.

⚠️ DO NOT run the debugger through bottom task bar (CMake: Launch the debugger for the selected target).

Run without Debugger (CMake: Launch)

Run without Debugger is not fully supported yet (it won't work if some dependencies handled by conan are shared, or define mandatory runtime environment variables, since CMake Tools extension doesn't provide a way to inject environment variable while running a target without Debugger).

Modifications

The first time you switch to another Kit/Variant, or after any modification in conanfile.txt, don't forget to run conan initialize task again, and then reselect the Kit. It won't be required anymore afterwards unless conanfile.txt has been modified.

Frequently Asked Questions

• Is it a non-intrusive integration of conan?
• Where can I find the proper find_package() names and imported target names of dependencies?
• Do I need to copy shared libs or plugins of dependencies for runtime execution of my executables inside VSCode?
• Can I use ccache to speed up recompilation?

Is it a non-intrusive integration of conan?

Yes, CMakeLists.txt files in your project don't have to know anything about conan. Under the hood, informations of installed libraries are injected through a toolchain file generated by conan initialize task. Just rely on find_package() (or eventually pkg_check_modules()) and imported targets in your CMakeLists like good citizens. Instructions like find_library(), find_program(), find_file() or find_path() should also be able to discover dependencies files. Therefore you can drop conan whenever you want without side effects in your CMakeLists files.

Where can I find the proper find_package() names and imported target names of dependencies?

The most obvious way is to read libraries documentation, since conan generates the same CMake imported targets. Otherwise, one markdown file per dependency is generated by conan in <project_folder>/build/<kit>_<variant>/.conan folder, with all these informations.

Do I need to copy shared libs or plugins of dependencies for runtime execution of my executables inside VSCode?

No, paths of shared libs and modules location in conan cache are automatically injected in the proper environment variables (PATH, LD_LIBRARY_PATH or DYLD_LIBRARY_PATH) before calling the debugger. Therefore, adding an [imports] section in you conanfile is useless. It's worth noting that all the specific runtime environment variables of dependencies (not very common, usually in SDK or Frameworks) are also automatically injected, so that you don't have to worry with these details during development.

Can I use ccache to speed up recompilation?

Yes, you just need to ensure that ccache is installed on your system obviously, check that it supports your platform & compiler, and to edit settings.json:

    "cmake.configureArgs": [
        "-DCMAKE_TOOLCHAIN_FILE=${workspaceFolder}/build/${buildKit}/${buildType}/.conan/conan_toolchain.cmake",
        // here we wrap compiler calls with ccache
        "-DCMAKE_C_COMPILER_LAUNCHER=ccache",
        "-DCMAKE_CXX_COMPILER_LAUNCHER=ccache"
    ]