使用Visual Studio Code编译Apollo项目

严正声明：本文系作者davidhopper原创，未经许可，不得转载。
说明：本文已过时，请参阅我另一篇博客。
Apollo项目非常不错，但每次修改完代码都需要在命令行中编译，这让人很不爽。我有点追求完美，必须想办法让Apollo项目能在IDE中编辑、构建。
Visual Studio Code（以下简称VSCode）是微软第一款支持Linux的轻量级代码编辑器，其功能介于编辑器与IDE之间，但更倾向于一个编辑器。优点是运行速度快，占用内存少，使用方法与Visual Stuio类似。缺点在于，与Visual Studio、QT等IDE相比，功能还不够强大。我个人认为，Windows中最强大的C++ IDE为Visual Studio，Linux中最强大的C++ IDE为QT。因Apollo项目无法使用上述两种IDE，退而求次选用VSCode。我写了一个脚本文件，能直接在VSCode中编译Apollo项目，具体描述如下：

一、创建脚本文件：dev_build.sh

使用VSCode或其他文本编辑工具，在Apollo项目的根目录创建脚本文件：dev_build.sh（与apollo.sh文件放置于同一目录），该文件内容为：

#!/usr/bin/env bash

current_docker=$(docker ps | grep 'apolloauto/apollo')
if [ -z "${current_docker}" ]
then 
    # start the docker firstly. 
    # echo ${current_docker} 
    bash docker/scripts/dev_start.sh
fi

xhost +local:root 1>/dev/null 2>&1
docker exec \
    -u $USER \
    -it apollo_dev \
    /bin/bash apollo.sh $1
xhost -local:root 1>/dev/null 2>&1

二、配置编译任务文件“tasks.json”

打开VSCode，执行菜单命令“任务->配置默认生成任务”，在弹出的小窗中，点击“使用模板创建tasks.json->Others 运行任意外部命令的示例”，之后会在隐藏的“.vscode”文件夹中生成任务文件“tasks.json”，将该文件修改为：

{
    "version": "2.0.0",
    "tasks": [       
        {
            "label": "build the apollo project",
            "type": "shell",
            // 根据不同需求，将build选项替换为其他选项，该选项与apollo.sh要求相同
            "command": "bash dev_build.sh build", 
            "group": {
                "kind": "build",
                // 默认生成任务，即按“Ctrl+Shift+B”快捷键会自动运行的任务
                "isDefault": true 
            }, 
            // 以下指定出错信息输出格式
            "problemMatcher": {
                "owner": "cc",
                "fileLocation": [
                    "relative",
                    "${workspaceFolder}"
                ],
                "pattern": {
                    "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
                    "file": 1,
                    "line": 2,
                    "column": 3,
                    "severity": 4,
                    "message": 5
                }
            }
        }
    ]
}

将上述配置内容保存，按快捷键“Ctrl+Shift+B”（与Visual Studio和QT的快捷键一致）编译工程，若之前没有启动过Docker文件，则编译时会启动Docker，需要在底部终端窗口输入超级用户密码。命令执行完毕，若在底部终端窗口出现如下信息，则表示编译成功：

注意：VSCode可能出现的一个Bug
修改配置文件后，VSCode有时不会执行新的配置文件，这时需重新打开VSCode，让新配置文件生效。
说明：
因为Apollo项目各模块紧密相联，不太适合于在IDE中单步调试；此外，若需调试，还需修改编译选项，让各模块的可执行文件（或共享库文件）带有调试信息。基于上述考虑，暂不配置调试任务文件。

三、GitHub仓库Apollo项目源代码的更新说明

经与Apollo项目专家沟通，确认Apollo项目根目录中已有一个脚本文件：apollo_docker.sh（与apollo.sh文件放置于同一目录）完成我所写脚本文件：dev_build.sh的功能，且前者考虑更为周全，因此可在编译任务文件“tasks.json”中直接使用该文件（具体内容如下）。我总共配置了四个常见的任务：”build the apollo project”（构建Apollo项目）、”run all unit tests for the apollo project”（运行Apollo项目的所有单元测试）、”code style check for the apollo project”（Apollo项目的代码风格检查）、”clean the apollo project”（清理Apollo项目）。其中第一个任务是默认生成任务，可以直接按快捷键“Ctr+Shift+B”调用，其他任务可通过执行菜单命令：任务->运行任务(R)…，在弹出的窗口中，选择对应选项完成。

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build the apollo project",
            "type": "shell",
            // you can change the "build" option to others acording to the "apollo.sh" file
            "command": "bash apollo_docker.sh build",
            "group": {
                "kind": "build",
                "isDefault": true // default building task invoked by "Ctrl+Shift+B"
            },
            // format the error message
            "problemMatcher": {
                "owner": "cc",
                "fileLocation": [
                    "relative",
                    "${workspaceFolder}"
                ],
                "pattern": {
                    "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
                    "file": 1,
                    "line": 2,
                    "column": 3,
                    "severity": 4,
                    "message": 5
                }
            }
        }, 
        {
            "label": "run all unit tests for the apollo project",
            "type": "shell",
            // you can change the "build" option to others acording to the "apollo.sh" file
            "command": "bash apollo_docker.sh test",
            // format the error message
            "problemMatcher": {
                "owner": "cc",
                "fileLocation": [
                    "relative",
                    "${workspaceFolder}"
                ],
                "pattern": {
                    "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
                    "file": 1,
                    "line": 2,
                    "column": 3,
                    "severity": 4,
                    "message": 5
                }
            }
        },
        {
            "label": "code style check for the apollo project",
            "type": "shell",
            // you can change the "build" option to others acording to the "apollo.sh" file
            "command": "bash apollo_docker.sh lint",          
            // format the error message
            "problemMatcher": {
                "owner": "cc",
                "fileLocation": [
                    "relative",
                    "${workspaceFolder}"
                ],
                "pattern": {
                    "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
                    "file": 1,
                    "line": 2,
                    "column": 3,
                    "severity": 4,
                    "message": 5
                }
            }
        },
        {
            "label": "clean the apollo project",
            "type": "shell",
            // you can change the "build" option to others acording to the "apollo.sh" file
            "command": "bash apollo_docker.sh clean",
            // format the error message
            "problemMatcher": {
                "owner": "cc",
                "fileLocation": [
                    "relative",
                    "${workspaceFolder}"
                ],
                "pattern": {
                    "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
                    "file": 1,
                    "line": 2,
                    "column": 3,
                    "severity": 4,
                    "message": 5
                }
            }
        }
    ]
}

四、可能存在的问题

1. 编译时遇到“ERROR: query interrupted”错误

这是由于bazel内部缓存不一致造成的。
解决方法：
按任意键退出编译过程，在VSCode的命令终端窗口（如果未打开，按快捷键“Ctrl + `”开启）执行如下命令进入Docker环境：

bash docker/scripts/dev_into.sh

在Docker环境中输入如下命令，执行bazel的清理缓存任务：

bazel query //...

最后输入exit命令退出Docker环境，按快捷键“Ctrl+Shift+B”，重新执行构建任务。

2. 编译时长时间停留在“Building: no action running”界面

这是由于当前系统中存在多个不同版本的Docker或者是bazel内部缓存不一致造成的。
解决方法：
按快捷键“Ctrl+C”键终止当前构建过程，在VSCode的命令终端窗口（如果未打开，按快捷键“Ctrl + `”开启），使用下述方法中的任意一种，停止当前运行的所有Docker：

# 方法1：停止当前所有的Apollo项目Docker
docker stop $(docker ps -a | grep apollo | awk '{print $1}') >/dev/null 2>&1
# 方法2：停止当前所有的Docker
docker stop $(docker ps -aq) >/dev/null 2>&1

执行VSCode的菜单命令：任务->运行任务(R)…，在弹出的窗口中，选择
“clean the apollo project”（清理Apollo项目）。待清理完毕后，按快捷键“Ctrl+Shift+B”，重新构建Apollo项目。

3. 编译时出现类似“Another command (pid=2466) is running. Waiting for it to complete…”的错误

这是由于在其他命令行终端进行编译或是在之前编译时按下“Ctrl+C”键强行终止但遗留了部分编译进程所引起的。
解决方法：
按快捷键“Ctrl+C”键终止当前构建过程，在VSCode的命令终端窗口（如果未打开，按快捷键“Ctrl + `”开启），使用如下命令终止遗留的编译进程：

# 1.进入Docker
bash docker/scripts/dev_into.sh
# 2.杀死Docker中遗留的编译进程
pkill bazel-real
# 3.查看Docker中当前运行的进程，若仍然存在bazel-real进程，按“q”退出top，再次执行步骤2
top
# 4.退出Docker
exit

按快捷键“Ctrl+Shift+B”，重新执行构建任务。