[C++] 使用 VSCode 调试 CMake 项目

1. 背景

VSCode 官方文档 中介绍了，如何使用 C/C++ 插件 对单独的一个 .cpp 文件进行调试。
现汇总如下，

（1）VSCode 安装 C/C++ 插件
（2）确保 clang 已安装

$ clang --version
Apple LLVM version 8.1.0 (clang-802.0.42)
Target: x86_64-apple-darwin16.4.0
Thread model: posix
InstalledDir: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin

（3）创建项目文件夹，并用 VSCode 打开，目录结构如下

├── .vscode           # VSCode 配置文件夹
│   ├── launch.json     ## 调试配置
│   └── tasks.json      ## 调试前置任务（编译）
└── main.cpp    #源文件

（4）文件内容（根据官方文档内容，进行简化）
main.cpp

#include 
#include 

using namespace std;

int main()
{
    string hello = "hello world";
    cout << hello << endl;
}

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "clang++ - Build and debug active file",
      "type": "cppdbg",
      "request": "launch",
      "program": "${fileDirname}/${fileBasenameNoExtension}",
      "cwd": "${workspaceFolder}",
      "MIMode": "lldb",
      "preLaunchTask": "clang++ build active file"
    }
  ]
}

.vscode/tasks.json

{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "shell",
      "label": "clang++ build active file",
      "command": "/usr/bin/clang++",
      "args": [
        "-std=c++11",
        "-stdlib=libc++",
        "-g",
        "${file}",
        "-o",
        "${fileDirname}/${fileBasenameNoExtension}"
      ],
      "options": {
        "cwd": "${workspaceFolder}"
      }
    }
  ]
}

（5）使用 VSCode 在 main.cpp 中 按 F5 进行调试

2. CMake 项目

有很多 C++ 项目是使用 CMake 进行构建的，
用户首先会调用 cmake 生成 Makefile 文件，然后再调用 make 执行构建。

2.1 make

GNU Make is a tool which controls the generation of executables and other non-source files of a program from the program's source files.

GNU Make 可用于从源码生成 可执行文件 或 其他文件。

Make gets its knowledge of how to build your program from a file called the makefile, which lists each of the non-source files and how to compute it from other files.

make 会读取 Makefile 文件，其中记录了 待生成文件 如何从源码生成。

2.2 cmake

CMake is used to control the software compilation process using simple platform and compiler independent configuration files, and generate native makefiles and workspaces that can be used in the compiler environment of your choice.

CMake 的配置文件是跨平台的，
在特定的平台下，cmake 会生成相应的 Makefile 文件。

2.3 示例

一个典型的 CMake 项目的目录结构如下，

├── CMakeLists.txt    # cmake 配置文件
├── bin/              # 产物目录
├── build/            # 构建目录：cmake 会生成 Makefile 文件到这里
├── include           # 头文件目录
│   └── head.h
└── src               # 源文件目录
    └── main.cpp

（1）文件内容
CMakeLists.txt

cmake_minimum_required(VERSION 2.8)  # 依赖 cmake 的最低版本
project(hello)                       # 项目名称

set(CMAKE_CXX_COMPILER "/usr/bin/clang++")  # 编译器
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11 -stdlib=libc++ -g")  # 编译参数
set(EXECUTABLE_OUTPUT_PATH "${PROJECT_SOURCE_DIR}/bin")  #产物目录

aux_source_directory(src DIR_SRCS)  # 源文件目录
include_directories("${PROJECT_SOURCE_DIR}/include")  #头文件目录

add_executable(main ${DIR_SRCS})  # 将哪些源文件 构建成 什么名字的可执行文件

include/head.h

#pragma once
#include 
#include 

src/main.cpp

#include "head.h"

using namespace std;

int main()
{
    string hello = "hello world";
    cout << hello << endl;
}

（2）cmake 生成 Makefile
在 build/ 目录中执行 cmake，

$ cd build
$ cmake ../
-- The C compiler identification is AppleClang 8.1.0.8020042
-- The CXX compiler identification is AppleClang 8.1.0.8020042
-- Check for working C compiler: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/cc
-- Check for working C compiler: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/c++
-- Check for working CXX compiler: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done
-- Generating done
-- Build files have been written to: /Users/.../build

cmake 后的文件结构如下，

├── CMakeLists.txt
├── bin
├── build
│   ├── CMakeCache.txt
│   ├── CMakeFiles/  # 目录
│   ├── Makefile     # make 要用的 Makefile 文件
│   └── cmake_install.cmake
├── include
│   └── head.h
└── src
    └── main.cpp

（3）make 生成可执行文件
同样是在项目下的 build/ 目录中，执行 make（与 Makefile 同级），

$ cd build
$ make
Scanning dependencies of target main
[ 50%] Building CXX object CMakeFiles/main.dir/src/main.cpp.o
[100%] Linking CXX executable ../bin/main
[100%] Built target main

（4）执行

$ cd bin
$ ./main
hello world

3. 使用 VSCode 调试 CMake 项目

3.1 前置条件

前置条件与调试 C++ 文件相同。
（1）VSCode 安装 C/C++ 插件
（2）确保 clang 已安装

$ clang --version
Apple LLVM version 8.1.0 (clang-802.0.42)
Target: x86_64-apple-darwin16.4.0
Thread model: posix
InstalledDir: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin

3.2 目录结构

新增 VSCode 配置文件夹 .vscode/，其他文件与上一节保持不变

├── .vscode  # 新增 VSCode 配置文件夹
│   ├── launch.json
│   └── tasks.json
├── CMakeLists.txt
├── bin
├── build
├── include
│   └── head.h
└── src
    └── main.cpp

3.2 VSCode 配置

（1）.vscode/tasks.json

{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "shell",
      "label": "let's make",   // 任务名
      "command": "make",       // 命令行调用
      "options": {
        "cwd": "${workspaceFolder}/build"  // 在 build/ 目录中执行
      },
      "dependsOn": "let's cmake"           // 依赖哪个任务的执行结果
    },
    {
      "type": "shell",
      "label": "let's cmake",  // 任务名
      "command": "cmake",      // 命令行调用
      "args": [                // 命令行参数
        "../"
      ],
      "options": {
        "cwd": "${workspaceFolder}/build"  // 在 build/ 目录中执行
      },
    },
  ]
}

（2）.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "let's debug",          // debug 文件名
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/bin/main",  // 构建后的可执行文件
      "cwd": "${workspaceFolder}",
      "preLaunchTask": "let's make",  // 执行调试的前置任务名
      "MIMode": "lldb",               // 必填（与哪个 debugger 通信）
    }
  ]
}

3.3 源文件

为了示例的完整性，这里再重复贴一下 src/main.cpp 和 include/head.h

src/main.cpp

#include "head.h"

using namespace std;

int main()
{
    string hello = "hello world";
    cout << hello << endl;
}

include/head.h

#pragma once
#include 
#include 

3.4 执行调试

使用 VSCode 打开项目，在任何文件中执行按 F5 启动调试

---

参考

GNU Make Manual
CMake Tutorial
VSCode: Using Clang in Visual Studio Code