1. 概述

MXMACA® Clangd是支持MXMACA C/C++语言的编辑器辅助工具集，包括支持语言服务协议（LSP）的Clangd工具（以下称为Clangd工具）和编辑器插件（以下称为Clangd插件）。目前支持VSCode编辑器，提供了VSCode插件。

在编辑器中编写、阅读MXMACA C/C++代码时，MXMACA Clangd可以提供文件识别、代码补全、跳转、诊断等多种功能，具有功能全面、识别准确、响应速度快等优点，帮助使用者快速、高效地开发、浏览MXMACA C/C++工程。

1.1. 工作流程

如下图所示，在安装了VSCode插件和MXMACA的环境中，用户通过VSCode执行某个功能，Clangd插件发送对应的消息到Clangd工具，Clangd工具处理后，将处理结果再通过消息返回给Clangd插件，经由VSCode显示给用户。

_images/image4.png

图 1.1 MXMACA Clangd工作流程

1.2. 关键特性

MXMACA Clangd支持以下特性：

  • 支持MXMACA C/C++工程，支持自动识别 .maca 后缀的文件为MXMACA C/C++语言，并设置对应图标

  • 兼容C/C++语言，支持MXMACA C/C++和C/C++混合工程

  • 支持MXMACA C/C++语言关键字、MXMACA头文件和API的识别、跳转

  • 支持语言服务协议规定的大部分特性，支持了一些协议以外的扩展特性

  • 与官方C/C++ Extension插件相比，整体上功能更多，响应速度更快

1.3. 支持平台

1.3.1. Clangd工具

Clangd工具支持的CPU架构和操作系统同MXMACA SDK，具体参见《曦云® 系列通用计算GPU用户指南》中 “系统支持范围” 章节。

备注

Clangd工具支持情况不涉及编辑器。

1.3.2. Clangd插件

编辑器：目前支持Visual Studio Code。

备注

Clangd插件支持情况不涉及架构和OS，使用的是支持的编辑器即可。

2. MXMACA Clangd 安装

2.1. 准备文件

下载并安装2.27.0及以后版本的MXMACA SDK包。

Clangd工具已安装于 /opt/maca/mxgpu_llvm/bin/clangd 。Clangd插件安装文件位于 /opt/maca/mxgpu_llvm/extensions/packages/MXMACA-clangd-0.2.0.vsix 。

2.2. 安装Clangd插件

采用VSCode插件离线安装方法，将Clangd插件安装到VSCode。

  1. 在VSCode主界面选择 View -> Extensions 。

  2. 点击 Views and More Actions 图标 image5 ，选择 Install from VSIX ，找到 MXMACA-clangd-0.2.0.vsix 文件进行安装。部分环境中安装耗时可能较久，耐心等待即可。

_images/image6.png

图 2.1 安装Clangd插件

2.3. 禁用VSCode官方C/C++插件（若有）

Clangd和官方C/C++插件会有冲突，若已安装C/C++插件，如C/C++ Extension Pack，需禁用。

  1. 点击插件右侧配置按钮 image7 。

_images/image8.png

图 2.2 点击配置按钮

  1. 根据需要选择 Disable 或 Disable (Workspace) ，在全局或当前工程禁用插件。

_images/image9.png

图 2.3 选择禁用插件

  1. 点击插件的 Reload Required 或直接重启VSCode使得禁用生效，即插件变灰色。

_images/image10.png

图 2.4 禁用生效

3. MXMACA Clangd使用

打开工程目录或文件即可使用。正常情况下，能够识别 .maca 文件，代码高亮显示，无编译报错波浪线提示，如图 3.1 所示。具体功能详见 4 特性列表。

_images/image11.png

图 3.1 .maca文件示例

体验完整功能需要提供准确的编译命令，比如准确的变量跳转、头文件包含、预编译宏分支选择等。 用户需要提供一个含有每个文件编译命令的 compile_commands.json 的文件，供Clangd获取编译命令。 该文件通常可以自动生成，详见 3.1 为工程生成compile_commands.json文件 。

MXMACA相关头文件需要从MXMACA安装路径中获取，Clangd依次从编译命令的 -maca-path 选项、环境变量 MACA_PATH、Clangd所在目录、 /opt/maca 中获取MXMACA安装路径。

3.1. 为工程生成compile_commands.json文件

基于cmake的工程

  • 方式1：在cmake命令中添加 -DCMAKE_EXPORT_COMPILE_COMMANDS=1

  • 方式2：在 CMakeLists.txt 文件中添加 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

在构建根目录下将生成 compile_commands.json ，Clangd会自动搜索到该文件。

基于make的工程

使用bear工具，根据版本不同，命令为 bear make 或 bear -- make 。

其他构建工程，或使用其他工具生成该文件，可参考 工程构建相关文档 。

Clangd工具自动搜索文件目录和其下的 build 目录，以及递归搜索父目录和其下的 build 目录。如果上述目录中没有这个文件，可以软链接或手动拷贝过去。

3.2. 独立文件或简单工程

Clangd支持没有 compile_commands.json 文件的情况，此时Clangd默认其编译命令为 mxcc <file> 。对单个文件或包含关系比较简单的工程，此时也能有相对完整的功能体验。

如果需要在默认命令上添加一些编译选项，可以使用 compile_flags.txt 配置文件，参考 compile_flags.txt相关文档 。

4. 特性列表

4.1. .maca文件识别

识别 .maca 后缀为MXMACA语言，图标为 image12 ，VSCode状态栏显示为 MXMACA C++ ，如图 4.1 所示。

_images/image13.png

图 4.1 .maca文件识别

4.2. 错误和告警诊断

  • 编写代码时，实时显示编译报错和告警信息。

_images/image14.png

图 4.2 实时显示编译报错和告警信息

  • 自动修复

    提示正确代码，点击后可自动修复。如图 4.3 所示，点击 image15 图标后，可以选择修正错误的函数名。

_images/image16.png

图 4.3 代码自动修复

  • clang-tidy检查

    集成了clang-tidy，可在编程规范、错误等方面提供更充分的检查。具体使用方式参考 Clang-Tidy相关文档 。

4.3. 代码补全

  • 编写代码时，给出可能的全称候选列表，供快速输入

_images/image17.png

图 4.4 提供全称候选列表

  • 命名空间和头文件自动插入

    编写代码时，可以自动插入命名空间或头文件。对于插入命名空间，键入变量或函数时，在候选列表中可以看到带有完整命名空间的变量或函数。对于插入头文件，键入足够信息后回车确认，即可将头文件插入顶部。

    例如图 4.5 所示，键入 std::string 后，回车确认，可以按字母顺序自动插入其所属的C++标准库头文件 <string> 到文件顶部。头文件插入成功后如图 4.6 所示。

_images/image18.png

图 4.5 插入头文件

_images/image19.png

图 4.6 头文件插入成功

  • 函数参数提示

    编写代码时，给出调用函数的入参信息。

_images/image20.png

图 4.7 函数参数提示

4.4. 跳转

查找到定义、声明、引用等，包括MXMACA安装包中的头文件，以及MXMACA的各类API、宏、类型的声明或定义。如图 4.8 所示，在感兴趣的变量、函数上单击右键打开菜单，可选择对应的条目。

_images/image21.png

图 4.8 跳转

4.5. 工程导航

  • 文件大纲

    OUTLINE 栏目显示文件大纲，便于浏览并跳转到本文件的所有符号。如图 4.9 所示，在 EXPLORER 窗口打开 Outline ，即可看到该栏目。

_images/image22.png

图 4.9 OUTLINE栏目显示

  • 搜索符号

    Ctrl+P打开搜索栏，如图 4.10 所示，输入 @ 搜索本文件，或输入 # 搜索本工程的符号。

_images/image23.png

图 4.10 搜索本文件或本工程

  • 显示当前函数的调用关系

    如图 4.11 所示，在函数上右键打开菜单，选择 Show Call Hierarchy ，左侧窗口中会出现调用链。

_images/image24.png

图 4.11 显示函数调用链

4.6. 悬停

鼠标悬停时显示符号更多的信息，如图 4.12 所示。

_images/image25.png

图 4.12 悬停显示

4.7. 代码规范化

集成了clang-format，可以对代码格式进行规范化处理。如图 4.13 所示，选中一部分代码后，在右键菜单选择 Format Selection ，可以将第25行自动修复为缩进2格，修复后如图 4.14 所示。也可以选择 Format Document ，对整个文件进行处理。

clang-format的使用详情可参考 ClangFormat相关文档 。

_images/image26.png

图 4.13 选择代码规范化

_images/image27.png

图 4.14 代码修复成功

4.8. 代码重构

  • 重命名符号

    在任一需修改处选择 Rename Symbol ，输入新符号名，所有引用的地方都会自动修改。

    1. 在任一 h_A 变量处打开右键菜单，点击 Rename Symbol 。

      _images/image28.png

      图 4.15 选择重命名符号

    2. 在文本框中输入新名称 hostA 。

      _images/image29.png

      图 4.16 输入新变量名称

    3. 回车确认后，所有的 h_A 都修改为 hostA 。

      _images/image30.png

      图 4.17 重命名成功

  • 更多重构方式

    支持抽取表达式为变量、抽取多行语句为函数、展开宏或auto类型。如图 4.18 所示，选中对应内容后，在右键菜单选择 Refactor… ，根据提示进行后续操作。

    _images/image31.png

    图 4.18 抽取

    • 抽取表达式为变量：

      _images/image32.png

      图 4.19 选择抽取表达式为变量

      _images/image33.png

      图 4.20 抽取为变量成功

    • 抽取语句为函数：

      _images/image34.png

      图 4.21 选择抽取语句为函数

      _images/image35.png

      图 4.22 抽取为函数成功

    • 展开宏：

      _images/image36.png

      图 4.23 展开宏

      _images/image37.png

      图 4.24 展开宏成功

4.9. 关键字高亮

除了常规的C/C++语言外，也支持MXMACA C/C++语言关键字、宏等高亮。

4.10. 源文件与头文件切换

支持在源文件和头文件之间快速切换。如图 4.25 所示，在源文件任意位置点击右键，在菜单中选择 Switch Between Source/Header ：

_images/image38.png

图 4.25 源文件与头文件切换

4.11. 显示AST

支持显示某段代码的抽象语法树信息，辅助开发者编写、理解代码。如图 4.26 所示，选中一段代码后，在右键菜单选择 Show AST ，左侧显示抽象语法树如图 4.27 所示。

_images/image39.png

图 4.26 选择显示AST

_images/image40.png

图 4.27 显示抽象语法树

4.12. 显示MXMACA预处理后文件

支持显示device侧预处理后文件。如图 4.28 所示，在右键菜单选择 Show MXMACA Preprocessor Output ，在新的编辑窗口生成预处理后文件，同时右下角会弹出编译命令，如图 4.29 所示，供开发者核对。

_images/image41.png

图 4.28 显示MXMACA预处理后文件

_images/image42.png

图 4.29 预处理后文件窗口

5. 进阶配置

5.1. 配置Clangd工具路径

如果需要用其他MXMACA目录下的Clangd，可以在Clangd插件中设置对应路径。如图 5.1 所示，点击Clangd插件配置按钮 image43 ，并选择 Extension Settings ，根据需要，选择 User 、 Remote 或 Workspace 页面，配置 Clangd: Path 为所需的Clangd路径。

_images/image44.png

图 5.1 配置Clangd工具路径

5.2. 重启Clangd工具

修改了Clangd插件的设置后，需要重启Clangd工具才能生效。按Ctrl + Shift + P，输入 clangd: Restart language server ，并执行，稍等即可生效。