abuild 使用说明

1. 简介

abuild 是一款面向 Linux C/C++ 开发的 VS Code 扩展，用于完成工程创建、编译、运行、调试、打包和智能提示配置。

适用场景：

C 工程与 C++ 工程
可执行文件、静态库、动态库构建
本机编译与交叉编译
基于 clangd 的智能提示
基于 gdb / gdbserver 的调试

当前支持矩阵：

Linux 本机：支持
Windows + VS Code Remote WSL：支持
VS Code Remote SSH 到 Linux：支持
Windows 原生 PowerShell / CMD：暂不支持

2. 使用条件

使用前建议具备以下环境：

Linux
VS Code
clangd
VS Code clangd 插件
make
bash
tar
C/C++ 编译器
调试场景下可用的 gdb 或交叉 gdb
建议安装 bear
abuild-yk 可选

建议关闭 VS Code C/C++ 插件的 intelliSenseEngine，避免与 clangd 冲突。

VS Code 扩展建议如下：

建议安装 llvm-vs-code-extensions.vscode-clangd 用于代码补全、跳转、诊断，与 abuild 生成的 .clangd 配置配合使用
建议安装 xaver.clang-format 用于匹配工程默认写入的 C/C++ formatter 配置
调试必需安装 ms-vscode.cpptools LDebug / RDebug 使用的 cppdbg 由该扩展提供，且需要安装在当前 Linux 或 WSL 宿主中

bear 用于辅助生成编译数据库信息，缺失时不会阻塞构建，但可能导致：

构建命令执行异常
compile_commands.json 不完整
智能提示、跳转、诊断不准确

安装示例：

sudo apt install bear

3. 安装与启用

安装方式：

在 VS Code 扩展市场中搜索 abuild
或使用 .vsix 离线安装

安装后，使用命令面板输入 abuild 可查看相关命令。

3.1 Windows + WSL 使用

在 Windows 上，请使用 VS Code 的 Remote - WSL 打开工程，并将 abuild 安装到 WSL: <发行版> 侧。

最小前置条件：

已安装 WSL
已安装 VS Code Remote - WSL
WSL 内可用 bash、make、gcc、g++、gdb、tar
建议安装 bear
abuild-yk 可选；如果安装在 WSL 环境并加入 PATH，环境检查会一并显示其状态

可用命令面板执行 ABuild: 检查环境，确认当前运行时和依赖状态。

环境检查当前会检查：

运行时是否位于 Linux 或 Remote WSL
命令行依赖：bash、make、gcc、g++、gdb、tar
可选命令：clangd、bear、abuild-yk
当前宿主中的 VS Code 扩展：clangd 扩展、Clang-Format 扩展、Microsoft C/C++ 扩展
用户编译器配置文件 ~/.local/share/abuild/compilersitem.json
当前选中的 C/C++/gdb 编译器配置是否能在 PATH 中解析

如果只使用当前 VS Code 扩展完成创建工程、构建、运行、调试、打包，abuild-yk 不是必需项。如需使用 abuild-yk 命令行工具，再单独安装即可。

3.2 Remote SSH 到 Linux 使用

如果通过 VS Code Remote - SSH 连接到 Linux 主机，abuild 仍会运行在远端 Linux 工作区主机中。

建议远端 Linux 主机满足以下条件：

bash
make
gcc
g++
gdb
tar
建议安装 clangd
建议安装 bear

同时建议将以下 VS Code 扩展安装到远端 SSH 宿主：

llvm-vs-code-extensions.vscode-clangd
xaver.clang-format
ms-vscode.cpptools

4. 快速使用

4.1 新建工程

使用 VS Code 打开一个空目录
按 Ctrl+Shift+P
输入 abuild
执行创建 C 工程或创建 C++ 工程命令

创建后通常会生成：

.abuild/abuild.json
.abuild/interface.json
.clangd
.vscode/settings.json
main.c 或 main.cpp
version.h

其中 .vscode/settings.json 默认会补充以下推荐配置：

search.exclude
"[cpp]".editor.defaultFormatter = "xaver.clang-format"
"[c]".editor.defaultFormatter = "xaver.clang-format"
"C_Cpp.intelliSenseEngine" = "disabled"

如果当前宿主未安装 xaver.clang-format 扩展，环境检查会提示该项缺失，但不会阻塞构建或运行。

4.2 接管已有工程

对于已有源码目录，直接在该目录执行创建工程命令即可。abuild 会补齐管理文件，并接管构建与调试流程。

5. 界面与操作入口

状态栏常用入口：

compiler-xxx：选择编译器
Debug / Release：选择构建类型
Executable file / Static library / Dynamic library：选择输出类型
Build：编译
Run：运行
LDebug：本地调试
RDebug：远程调试
clean：清理当前输出

命令面板常用入口：

创建工程
编辑编译器配置
打包当前工程
传送可执行文件
重启语言服务器

6. 编译器配置

abuild 使用用户侧编译器配置。典型流程如下：

打开命令面板
执行编译器配置编辑命令
增加或修改编译器条目
保存后，在状态栏选择当前工程所使用的编译器

示例：

{
  "name": "GCC ARM",
  "compilers": {
    "c": "arm-buildroot-linux-gnueabihf-gcc",
    "cplus": "arm-buildroot-linux-gnueabihf-g++",
    "gdb": "arm-buildroot-linux-gnueabihf-gdb"
  }
}

使用建议：

本机开发可直接使用系统 gcc/g++
交叉编译时，应确保工具链目录已加入 PATH
切换编译器后，建议刷新智能提示

7. 构建说明

abuild 根据工程配置自动收集源码目录、头文件目录、宏和编译参数，并生成 .clangd。

构建特点：

自动扫描工程目录
支持 Debug / Release
支持三类输出：可执行文件、静态库、动态库
使用 shadow build，输出与源码目录分离

为避免大型工程在链接阶段生成超长命令行，abuild 在构建时会生成辅助文件：

.abuild/.cache/source_dirs.list
.abuild/.cache/include_dirs.list
.abuild/.cache/<outDir>.objects.rsp
.abuild/.cache/<outDir>.archive.mri

其中：

可执行文件与动态库使用 objects.rsp
静态库使用 archive.mri

这些文件由 abuild 自动生成和使用，用户通常不需要手工编辑。

关于工程内 ./include 目录，当前采用保守策略：

./include 本身会加入搜索路径
不自动递归展开 ./include/**

8. `abuild.json` 配置说明

8.1 示例

{
  "projectName": "template_Bin",
  "projectVersion": {
    "major": "0",
    "minor": "0",
    "patch": "1"
  },
  "globalMacro": [
    { "MACRO_NAME": "1" },
    { "ENABLE_XX": "1" }
  ],
  "staticLibraryPath": ["", ""],
  "autoInclude": true,
  "includePath": ["./include"],
  "extraIncludePath": [
    { "path": "/opt/sdk/include", "recursive": false },
    { "path": "../vendor", "recursive": true }
  ],
  "libPath": ["/home/libraryPath1"],
  "libName": ["crypt"],
  "debugFlags": "-pthread -g -O0 -fPIC -Wall -Wextra -pedantic",
  "releaseFlags": "-pthread -O3 -fPIC -DNDEBUG",
  "cplusDebugFlags": "-pthread -g -O0 -fPIC -Wall -Wextra -pedantic -std=c++11",
  "cplusReleaseFlags": "-pthread -O3 -fPIC -DNDEBUG -std=c++11",
  "linkerFlags": "-pthread",
  "packPath": ["configs"],
  "packLibIgnoreHeaderFiles": ["", ""],
  "sharePath": "",
  "executionArgs": ["args1", "args2"],
  "stopAtEntry": true,
  "environmentVariable": [
    { "name": "config", "value": "Debug" }
  ],
  "debuggerServerAddress": "192.168.7.6:1234"
}

8.2 主要字段

projectName

工程名称
可执行文件输出时通常也是产物名

projectVersion

版本号配置
用于生成 version.h

globalMacro

全局宏定义
有值宏生成 -DKEY=VALUE
无值宏生成 -DKEY

autoInclude

true：自动扫描工程内头文件目录
false：只使用 includePath 中手工指定的工程内目录

includePath

extraIncludePath

额外 include 目录配置
适用于 SDK、第三方库、公共头文件目录
无论 autoInclude 是 true 还是 false，该配置始终生效

单项格式：

{
  "path": "../vendor",
  "recursive": true
}

字段说明：

path：目录路径，支持相对路径或绝对路径
recursive：
- false：仅加入当前目录
- true：加入当前目录及全部子目录

生效规则：

autoInclude=true：自动扫描结果 + extraIncludePath
autoInclude=false：includePath + extraIncludePath
extraIncludePath 同时作用于构建和 .clangd
旧版 abuild.json 缺少该字段时按空数组处理，不报错

libPath

libName

链接库名称，会转换为 -lxxx

debugFlags / releaseFlags

C 编译参数

cplusDebugFlags / cplusReleaseFlags

C++ 编译参数

linkerFlags

链接参数

packPath

packLibIgnoreHeaderFiles

打包库时忽略的头文件名

sharePath

executionArgs

运行参数

stopAtEntry

调试时是否在入口停止

environmentVariable

运行或调试时注入的环境变量

debuggerServerAddress

远程调试地址

9. `interface.json` 说明

interface.json 由插件自动维护，通常不需要手工修改。

示例：

{
  "compilerVersion": {
    "name": "GCC ARM",
    "compilers": {
      "c": "arm-buildroot-linux-gnueabihf-gcc",
      "cplus": "arm-buildroot-linux-gnueabihf-g++",
      "gdb": "arm-buildroot-linux-gnueabihf-gdb"
    }
  },
  "buildVariant": "Release",
  "outputType": "Executable file"
}

10. `adebug.json` 说明

adebug.json 位于工程目录下的 .abuild/adebug.json，用于补充本地调试和远程调试时传给 cppdbg / gdb 的附加配置。

默认会生成如下结构：

{
  "setupCommands": [
    {
      "description": "Enable pretty-printing for gdb",
      "text": "-enable-pretty-printing",
      "ignoreFailures": true
    },
    {
      "description": "Set the follow fork mode to parent",
      "text": "-gdb-set follow-fork-mode parent",
      "ignoreFailures": true
    },
    {
      "description": "Set the detach exec fork to off",
      "text": "-gdb-set detach-on-fork off",
      "ignoreFailures": true
    }
  ],
  "sourceFileMap": {},
  "additionalSOLibSearchPath": ""
}

常用字段说明：

setupCommands

传递给 GDB 的附加初始化命令
适合放置 pretty-printing、fork 行为、符号加载策略等调试命令

additionalSOLibSearchPath

告诉 GDB 到哪些目录查找 .so 动态库文件本身
常用于依赖库不在系统默认搜索路径的场景

示例：

{
  "additionalSOLibSearchPath": "${workspaceFolder}/build/deps:${env:LD_LIBRARY_PATH}"
}

sourceFileMap

用于把调试信息中的源码路径映射到当前工作区实际路径
常用于交叉编译、容器构建、远端构建、目录迁移等场景

示例：

{
  "sourceFileMap": {
    "/workspace/libs/libfoo/src": "${workspaceFolder}/deps/libfoo/src",
    "/workspace/libs/libbar/include": "${workspaceFolder}/deps/libbar/include",
    "/home/yk/GIT/rcfRepository/code/others/rcfprogram/TheSimplestrcf": "/home/yk/GIT/rcfRepository/code/others/rcfprogram/TheSimplestrcf1"
  }
}

使用建议：

additionalSOLibSearchPath 解决“库文件找不到”的问题
sourceFileMap 解决“源码路径对不上、断点落不到源码”的问题
两者经常需要配合使用：先让 GDB 找到 .so，再让调试信息中的源码路径正确映射

说明：

adebug.json 中的字段会直接合并到 abuild 生成的调试配置中
LDebug 和 RDebug 都会读取该文件
如果文件不存在，abuild 会使用内置默认调试配置

11. 功能使用说明

11.1 编译

点击 Build 后，abuild 会：

收集源码目录和头文件目录
生成或更新 .clangd
按当前构建类型和输出类型执行 make
在输出面板中汇总错误、警告和耗时

11.2 运行

点击 Run 后，运行当前构建变体对应的产物，并应用 executionArgs 与环境变量配置。

11.3 清理

点击 clean 后，清理当前构建变体对应的输出目录。

11.4 打包

打包命令根据当前输出类型采用不同策略：

可执行文件：打包产物和 packPath
静态库 / 动态库：打包库文件、头文件和 packPath

11.5 本地调试

点击 LDebug 可启动本地调试，支持断点、单步执行、变量观察和调用栈查看。

11.6 远程调试

远程调试依赖目标机侧 gdbserver。典型流程：

在目标机启动 gdbserver
在 abuild.json 中设置 debuggerServerAddress
如有需要，将产物传送到 sharePath
点击 RDebug

11.7 传送可执行文件

传送功能主要用于远程调试或部署前准备。通常先在 abuild.json 中设置 sharePath，完成构建后再执行传送命令。

12. 智能提示与 VS Code 配置

建议使用 clangd 作为主语言服务，并避免与微软 C/C++ 插件的 IntelliSense 同时工作。

若智能提示异常，优先检查：

.clangd 是否已生成或更新
bear 是否已安装
编译器是否可执行
abuild.json 中宏与 include 路径是否正确
是否需要手动重启 clangd

13. 插件设置项

13.1 智能提示刷新设置

支持以下设置项：

编译后是否自动刷新智能提示
切换编译类型后是否自动刷新智能提示
切换编译器后是否自动刷新智能提示

当前默认值：

编译后自动刷新：关闭
切换编译类型后自动刷新：开启
切换编译器后自动刷新：开启

13.2 `MakeJobs` 并行设置

MakeJobs 用于控制 make -jN 中的并行任务数。

生效规则：

MakeJobs >= 1：使用设置值
MakeJobs = 0：自动检测 CPU 核心数

建议：

常规开发机保持默认值 0
资源受限设备可设置为较小值
大工程不要盲目设置过大，避免系统负载过高

14. 使用建议

工程内目录优先使用 autoInclude
工程外目录使用 extraIncludePath
仅在确有需要时使用递归 include
交叉编译时先确认工具链 PATH
老工程接入时，优先先跑通编译，再校准智能提示和调试

15. 常见问题

15.1 构建失败

优先检查：

当前编译器是否正确
编译器是否已加入 PATH
libPath、libName、staticLibraryPath 是否正确
includePath、extraIncludePath 是否正确

15.2 智能提示不准

优先检查：

.clangd 是否更新
bear 是否已安装
是否已经成功构建过一次
是否切换过编译器但未刷新智能提示

15.3 远程调试失败

优先检查：

debuggerServerAddress 是否正确
目标机 gdbserver 是否启动
主机与目标机网络是否互通
目标程序是否已传送到运行目录

abuild

杨康

abuild 使用说明

1. 简介

2. 使用条件

3. 安装与启用

3.1 Windows + WSL 使用

3.2 Remote SSH 到 Linux 使用

4. 快速使用

4.1 新建工程

4.2 接管已有工程

5. 界面与操作入口

6. 编译器配置

7. 构建说明

8. abuild.json 配置说明

8.1 示例

8.2 主要字段

9. interface.json 说明

10. adebug.json 说明

11. 功能使用说明

11.1 编译

11.2 运行

11.3 清理

11.4 打包

11.5 本地调试

11.6 远程调试

11.7 传送可执行文件

12. 智能提示与 VS Code 配置

13. 插件设置项

13.1 智能提示刷新设置

13.2 MakeJobs 并行设置

14. 使用建议

15. 常见问题

15.1 构建失败

15.2 智能提示不准

15.3 远程调试失败

8. `abuild.json` 配置说明

9. `interface.json` 说明

10. `adebug.json` 说明

13.2 `MakeJobs` 并行设置