中文 | English
一个面向 C/C++ 的功能齐全且轻量的 Neovim 插件:支持一键编译、运行与调试当前文件,兼容 Windows、Linux、macOS,适配 betterTerm 与内置终端;构建与运行全程异步,不阻塞 Neovim 主线程。
- ⚡️ 零配置即可 Build/Run/Debug,支持单文件与多文件,输出名有记忆。
- 🧰 Make & CMake 选择器 自带预览与“跳转到目标定义”。
- 🪟 Windows 友好:PowerShell 引号处理、MSVC
cl支持、路径兼容性细节完善。 - 🔭 Telescope 优先的体验:增强版 Quickfix 右侧展示信息与源码上下文。
- 🧠 全程异步不阻塞:不会卡住 Neovim;文件变更触发智能失效与缓存更新。
安装(lazy.nvim):
{
"AuroBreeze/quick-c",
ft = { "c", "cpp" },
config = function()
require("quick-c").setup()
end,
}使用:
<leader>cqb→ 构建当前文件<leader>cqr→ 运行最近构建<leader>cqR→ 构建并运行<leader>cqD→ 调试(codelldb + nvim-dap)<leader>cqS→ 使用 Telescope 多选源文件
可选:使用命令
:QuickCBuild·:QuickCRun·:QuickCBR·:QuickCDebug
| 能力 | Quick-c | compiler.nvim | cmake-tools.nvim | overseer.nvim |
|---|---|---|---|---|
| 范围 | 面向 C/C++ 的构建/运行/调试,含 Make/CMake 辅助 | 多语言编译/运行辅助 | 面向 C/C++ 的 CMake 项目集成 | 通用任务运行器/调度器 |
| 单文件构建/运行 | 内置、异步、输出名有记忆 | 内置(多语言) | 非单文件场景优先 | 通过任务实现(需手动配置) |
| 多文件构建 | 内置(Telescope 多选或命令行传参) | 受语言配置限制 | 交由 CMake 项目处理 | 通过任务实现(需手动配置) |
| Make 目标选择器 | 内置 Telescope 选择器 + 预览 + 跳转到定义 | 非主要关注点 | 非主要关注点 | 可通过自定义任务实现 |
| CMake 目标/构建 | 内置目标选择、配置(-S/-B)、视图 both/quickfix/terminal | — | 核心功能 | 可实现(需自定义任务) |
| Quickfix 增强 | 增强版 Telescope quickfix(消息 + 代码上下文) | 随编译器输出而异 | 聚焦 CMake 输出;quickfix 非核心 | 依赖任务输出解析 |
| Windows 细节 | PowerShell 引号、MSVC cl、路径兼容细节完善 |
取决于个人配置 | 支持 CMake/VS 环境;单文件运行非核心 | 取决于用户命令实现 |
| 单插件工作流 | 单入口覆盖单/多文件、Make、CMake、调试 | 偏单文件 | 偏项目(CMake) | 元运行器;常与构建插件配合 |
- 🚀 一键构建/运行(异步):
QuickCBuild、QuickCRun、QuickCBR(构建并运行) - 🐞 调试集成:
QuickCDebug使用nvim-dap与codelldb - 🌐 跨平台:自动选择可用编译器(gcc/clang/cl)与合适运行方式(PowerShell/终端)
- 📁 灵活输出位置:默认将可执行文件输出到源码所在目录;可通过配置修改
- 🔌 终端兼容:优先将命令发送到
betterTerm(如已安装),否则使用 Neovim 内置终端 - 🔧 Make 集成:自动发现 Makefile、列出目标、
.PHONY优先、参数输入与记忆 - 🏗️ CMake 集成:自动搜索 CMakeLists、
cmake -S/-B配置、cmake --build构建、目标列表(基于--target help)- 视图模式:
both(默认,流式输出+quickfix)/quickfix/terminal - 输出面板:
cmake.output.{open,height}控制
- 视图模式:
- 🔭 Telescope 增强:内置 Makefile 预览、源文件多选、快捷切换 .PHONY
- 🧪 Quickfix 增强预览:
cqf打开时右侧显示错误详情与源码上下文 - 📦 多文件构建:支持一次构建/运行多个源文件
- 🧠 LSP 集成:一键为当前文件目录生成或使用指定
compile_commands.json供 clangd 等 LSP 使用
- Neovim 0.8+
- 至少一种 C/C++ 编译器(按平台自动探测):
- Windows:
gcc/g++(MinGW)或cl(MSVC)或clang/clang++ - Unix:
gcc/g++或clang/clang++
- Windows:
- 可选:
betterTerm(若安装则优先使用)- 调试:
nvim-dap与codelldb - Make 选择器:
nvim-telescope/telescope.nvim与nvim-lua/plenary.nvim
使用 lazy.nvim(三重懒加载:按文件类型/按快捷键/按命令 任一触发即加载):
{
"AuroBreeze/quick-c",
lazy = true,
event = "VeryLazy",
-- 1) 文件类型触发(打开 C/C++ 文件时加载)
ft = { "c", "cpp" },
-- 2) 快捷键触发(首次按键时加载,映射由插件在 setup 时注入)
keys = {
{ "<leader>cqb", desc = "Quick-c: Build" },
{ "<leader>cqr", desc = "Quick-c: Run" },
{ "<leader>cqR", desc = "Quick-c: Build & Run" },
{ "<leader>cqD", desc = "Quick-c: Debug" },
{ "<leader>cqM", desc = "Quick-c: Make targets (Telescope)" },
{ "<leader>cqS", desc = "Quick-c: Select sources (Telescope)" }, -- 使用tab进行多选
{ "<leader>cqf", desc = "Quick-c: Open quickfix (Telescope)" },
{ "<leader>cqL", desc = "Quick-c: Build logs (Telescope)" },
{ "<leader>cqC", desc = "Quick-c: CMake targets (Telescope)" },
{ "<leader>cqB", desc = "Quick-c: CMake build" },
{ "<leader>cqc", desc = "Quick-c: CMake configure" },
{ "<leader>cqx", desc = "Quick-c: Stop current task" },
{ "<leader>cqt", desc = "Quick-c: Retry last task" },
},
-- 3) 命令触发(调用命令时加载,等同“命令提前加载”)
cmd = {
"QuickCBuild", "QuickCRun", "QuickCBR", "QuickCDebug",
"QuickCMake", "QuickCMakeRun", "QuickCMakeCmd",
"QuickCCMake", "QuickCCMakeRun", "QuickCCMakeConfigure",
"QuickCCompileDB", "QuickCCompileDBGen", "QuickCCompileDBUse",
"QuickCQuickfix", "QuickCCheck",
},
config = function()
require("quick-c").setup()
end,
}使用 packer.nvim:
use({
"AuroBreeze/quick-c",
config = function()
require("quick-c").setup()
end,
})插件会通过 plugin/quick-c.lua 在加载时自动调用 require('quick-c').setup(),你也可以在自己的配置中传入自定义项覆盖默认行为。
打开任意 *.c 或 *.cpp 文件:
- 构建当前文件:
:QuickCBuild或<leader>cqb - 运行可执行文件:
:QuickCRun或<leader>cqr - 构建并运行:
:QuickCBR或<leader>cqR - 调试运行:
:QuickCDebug或<leader>cqD
多文件项目(传入多个源文件路径):
- C:
:QuickCBuild main.c util.c - C++:
:QuickCBR src/main.cpp src/foo.cpp - 运行基于多文件编译生成的可执行文件:
:QuickCRun src/main.cpp src/foo.cpp
使用 Telescope 选择多文件(推荐):
- 按
<leader>cqS打开源文件选择器。 - 在列表中按
Tab多选(Shift+Tab 往回,多选不移动可用 Ctrl+Space)。 - 回车后选择操作:Build / Run / Build & Run。
说明:源文件列表显示为相对当前工作目录的路径,内部会使用绝对路径进行构建与运行。
默认输出名为当前文件名(Windows 会追加 .exe);如需自定义输出名,构建时可在提示中输入。
输出名与缓存:
- 多文件构建:总是弹出“Output name”输入框;若你对“同一源集合”输入过名称,将自动带出为默认值。
- 单文件构建:直接使用默认名(同文件名)。
| 分类 | 命令 | 说明 | 默认键位 |
|---|---|---|---|
| Build/Run/Debug | QuickCBuild |
构建当前/所选源文件 | <leader>cqb |
QuickCRun |
运行最近构建的可执行文件 | <leader>cqr |
|
QuickCBR |
构建并运行 | <leader>cqR |
|
QuickCDebug |
使用 codelldb 调试最近构建的程序 | <leader>cqD |
|
| Make | QuickCMake |
选择目录与目标并执行 | <leader>cqM |
QuickCMakeRun [target] |
直接执行指定目标 | — | |
QuickCMakeCmd |
自定义完整 make 命令并发送到终端 | — | |
| CMake | QuickCCMake |
打开 CMake 目标选择器 | <leader>cqC |
QuickCCMakeRun [target] |
构建默认或指定目标 | <leader>cqB |
|
QuickCCMakeConfigure |
执行 cmake 配置(-S/-B) | <leader>cqc |
|
| Sources | — | Telescope 源文件选择器 | <leader>cqS |
| Diagnostics | QuickCQuickfix |
打开 quickfix(优先 Telescope) | <leader>cqf |
| Tasks | QuickCStop |
取消当前内部构建任务 | <leader>cqx |
QuickCRetry |
重试最近一个内部构建任务 | <leader>cqt |
|
| Config | QuickCCompileDB |
应用编译数据库(生成到当前文件目录) | — |
QuickCCompileDBGen |
生成 compile_commands.json | — | |
QuickCCompileDBUse |
使用外部 compile_commands.json | — | |
QuickCCheck |
检查配置并输出报告 | — | |
QuickCHealth |
环境健康检查 | — | |
QuickCReload |
重新加载配置 | — | |
QuickCConfig |
打印生效配置与项目路径 | — | |
| Compile DB | QuickCCompileDB |
按 compile_commands.mode 执行(generate/use/cmake) | — |
QuickCCompileDBGenProject |
扫描 :pwd 全项目生成 compile_commands.json | — | |
QuickCCompileDBGenDir [dir] |
对指定目录生成 compile_commands.json | — | |
QuickCCompileDBGenSources |
从源文件选择器(Telescope)多选后生成 | — | |
QuickCCompileDBGenCMake |
使用 CMake 导出并复制到 outdir | — |
注:
- 当
make.enabled = false时,不创建 Make 相关命令/键位。 - 当
cmake.enabled = false时,不创建 CMake 相关命令/键位。 - 当
telescope_enhance = false时,Quickfix 优先使用原生命令,且不提供内置 Telescope 选择器。
- 若希望以 cmake-tools 为主的 CMake 交互界面:
- 将
cmake.enabled = false - 可选:
telescope_enhance = false(保持 quickfix 原生,避免 Telescope 选择器)
- 将
- 若希望以 overseer 作为任务运行器,同时保留 quick-c 的单/多文件 Build/Run:
- 将
make.enabled = false(使用 overseer 任务来执行 make) - quick-c 的单/多文件 Build/Run/Debug 仍可独立使用。
- 将
- 键位会遵循这些开关;被关闭的功能不会注入默认映射。
Quick-c 支持多级配置,优先级从高到低为:
- 项目级配置(
.quick-c.json) - 覆盖全局配置 - 用户配置(
setup()参数) - 用户自定义配置 - 默认配置 - 插件内置默认值
在项目根目录创建 .quick-c.json 文件,可以为特定项目定制配置,覆盖全局配置。当插件检测到项目配置文件时,会自动加载并应用配置。
配置文件查找规则:
- 仅在当前工作目录(
:pwd,项目根)查找 - 文件名固定为
.quick-c.json - 如切换目录(
DirChanged),会自动重新载入(含 400ms 防抖)
配置格式:
- 使用 JSON 格式
- 配置结构与 Lua 配置相同
- 支持所有配置选项
配置生效时机:
- 插件初始化时自动检测并加载
- 切换不同项目(
:cd改变:pwd)时自动应用(400ms 防抖) - 使用命令
:QuickCReload手动重载 - 使用命令
:QuickCConfig查看“生效配置”和检测到的项目配置路径
具体指导:GUIDE
补充说明:
make.prefer_force = true时:- 解析阶段若
prefer不可执行,仅提示 Warning,并尝试用可用的 make 探测目标; - 运行阶段仍按你的
prefer构造命令并发送到终端(可配合QuickCMakeCmd全自定义)。
- 解析阶段若
- 解析阶段回退策略:
-qp无结果时使用-pn再试。
最小示例(仅常用项):
require("quick-c").setup({
-- 可选模块:与其他插件(cmake-tools/overseer)共存时,可关闭以避免重叠
telescope_enhance = true, -- 设为 false 关闭内置 Telescope 增强(选择器/quickfix 预览)
make = { enabled = true }, -- 设为 false 不注入 Make 相关命令/键位
cmake = { enabled = true }, -- 设为 false 不注入 CMake 相关命令/键位(目标/构建/配置)
outdir = "source", -- 或自定义路径,如 vim.fn.stdpath("data") .. "/quick-c-bin"
toolchain = {
windows = { c = { "gcc", "cl" }, cpp = { "g++", "cl" } },
unix = { c = { "gcc", "clang" }, cpp = { "g++", "clang++" } },
},
-- 构建超时(毫秒):例如 2 分钟
build = { timeout_ms = 120000 },
compile = { -- 只有当你想使用自定义的工具时才会有效,且仅当 prefer_force = true 时有效
prefer = { c = nil, cpp = nil }, -- 就像 c = i686-gcc-elf
prefer_force = false,
},
make = {
prefer = { "make", "mingw32-make" },
cache = { ttl = 10 },
-- 当为 true 时,发送 make 命令时不附带 `-C <cwd>`,在当前终端目录执行
no_dash_C = false,
telescope = { choose_terminal = "auto" },
},
diagnostics = {
quickfix = { open = "warning", jump = "warning", use_telescope = true },
},
-- 输出目录 outdir:"source" 表示写到源文件目录;否则为自定义目录(相对 :pwd 或绝对路径)
-- 例:outdir = "source" | "build" | "build/bin" | "C:/tmp/bin"
-- 强制选择编译器:可用于交叉编译器或固定工具链名
compile = {
prefer = { c = "arm-none-eabi-gcc", cpp = "arm-none-eabi-g++" },
prefer_force = false, -- 设为 true 将不检查可执行性,直接调用
},
-- 调试可执行文件搜索(当默认路径不存在时)
debug = {
search = {
dirs = { "./build/bin", "./out" }, -- 优先搜索目录,不存在则回退到 up/down 策略
up = 2, -- 限制在 :pwd 内向上搜索层数
down = 2, -- 向下搜索层数
ignore_dirs = { ".git", "node_modules", ".cache" },
},
concurrency = 8, -- 并行扫描并发数
},
keymaps = {
enabled = true,
build = "<leader>cqb",
run = "<leader>cqr",
build_and_run = "<leader>cqR",
debug = "<leader>cqD",
},
})更多配置请参考 Default_configuration。
- CMake 目标/构建发送到终端的行为由
cmake.telescope.choose_terminal控制,语义与make.telescope.choose_terminal一致:auto:已打开终端时弹选择器,否则使用默认策略(betterTerm 优先,失败回退内置)always:总是弹出选择器never:总是使用默认策略
自定义示例:指定固定输出目录,并优先使用 clang/clang++:
require("quick-c").setup({
outdir = vim.fn.stdpath("data") .. "/quick-c-bin",
toolchain = {
windows = { c = { "clang", "gcc", "cl" }, cpp = { "clang++", "g++", "cl" } },
unix = { c = { "clang", "gcc" }, cpp = { "clang++", "g++" } },
},
make = {
-- 在 Windows 优先尝试 make,不存在时退回到 mingw32-make
prefer = { 'make', 'mingw32-make' },
cache = { ttl = 15 },
},
})- 构建时会解析 gcc/clang/MSVC 输出为 quickfix 项,支持错误与警告。
- 满足触发条件时自动打开列表并跳转到第一条;默认仅有错误时打开/跳转。
- 如已安装 Telescope,默认使用“增强版 Quickfix 选择器”,右侧显示该条目的错误详情与源码上下文;不可用时回退
:Telescope quickfix,再回退:copen。
提示:若当前缓冲是“未命名且已修改”,为避免保存提示,自动跳转(cc)将被跳过,此时请在 quickfix 中手动选择条目即可。
配置示例:
require('quick-c').setup({
diagnostics = {
quickfix = {
enabled = true,
open = 'warning', -- always | error | warning | never
jump = 'warning', -- always | error | warning | never
use_telescope = true,
},
},
})- gcc/g++
- clang/clang++
- MSVC cl
默认快捷键(普通模式):
<leader>cqb→ 构建<leader>cqr→ 运行<leader>cqR→ 构建并运行<leader>cqD→ 调试<leader>cqM→ 打开 Make 目标选择器(Telescope)<leader>cqS→ 打开源文件选择器(Telescope)<leader>cqf→ 打开 quickfix 列表(Telescope)<leader>cqx→ 取消当前内部任务(仅单/多文件构建)<leader>cqt→ 重试最近内部任务(仅单/多文件构建)
提示:
- 以上键位均可通过
setup({ keymaps = { ... } })自定义或禁用。 - 插件设置键位时使用
unique=true,不会覆盖你已有的映射;如键位已被占用会跳过注入。 - QuickCStop/QuickCRetry 仅作用于插件内部“单/多文件构建”任务队列;对 Make/CMake 流程不生效。
- CMake 导出:
compile_commands.mode = 'cmake',或执行:QuickCCompileDBGenCMake- 自动追加
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON,从cmake.build_dir复制到compile_commands.outdir
- 非 CMake 项目:
- 扫描项目:
:QuickCCompileDBGenProject - 指定目录:
:QuickCCompileDBGenDir [dir] - 多选源文件:
:QuickCCompileDBGenSources(需 Telescope) - 单/多文件基础:
compile_commands.mode = 'generate'时,:QuickCCompileDB也可生成
- 扫描项目:
outdir 可选:'source'(单文件目录,多文件/项目时优先写项目根以便 clangd 查找)、'cwd'、相对/绝对路径。
- 目录选择器与目标选择器均内置 Make/CMake 预览,Windows 路径兼容更好。
- 目标选择器阶段,预览固定显示当前目录的
Makefile或项目根的CMakeLists.txt,不随光标移动刷新(避免卡顿)。 - 预览增强:
- 跳转到定义:选中目标后,预览自动跳转至该目标在
Makefile/CMakeLists.txt中的定义附近。 - 软换行:预览窗口启用 wrap/linebreak/breakindent,长行可读性更好。
- 跳转到定义:选中目标后,预览自动跳转至该目标在
- 对大文件自动截断,受以下配置项控制:
make.telescope.preview:是否启用预览。make.telescope.max_preview_bytes:超过该字节数则改为按行读取并截断。make.telescope.max_preview_lines:截断时最多显示的行数。make.telescope.set_filetype:是否设置预览 buffer 的filetype=make。- CMake 预览默认也开启跳转与换行;如需更细配置,可按同样思路扩展
cmake.telescope。
- 选择 make 目标后,可将命令发送到已打开的内置终端,或使用默认策略(betterTerm 优先,失败回退内置)。
- 通过
make.telescope.choose_terminal控制行为:'auto':存在已打开终端时弹选择器,否则直接默认策略。'always':总是弹出选择器。'never':总是使用默认策略。
- 若未设置
make.cwd,插件会在“当前文件所在目录”为起点:- 向上查找至多
search.up层(默认 2 层) - 在每一层向下递归至多
search.down层(默认 3 层) - 找到包含
Makefile/makefile/GNUmakefile的首个目录作为工作目录 - 会跳过
ignore_dirs名单中的目录(默认:.git、node_modules、.cache) - 增强:对被忽略目录进行“第一层探测”(不递归),若该目录根下存在 Makefile,则也纳入候选
- 向上查找至多
多结果时,Telescope 列表显示相对于 :pwd 的相对路径,便于识别(如 ./build、./sub/dir)。
内部已模块化重构,但对外 API 不变:
-
模块划分
-
lua/quick-c/init.lua装配、命令与键位注入 -
lua/quick-c/config.lua默认配置 -
lua/quick-c/util.lua工具函数(平台/路径/消息) -
lua/quick-c/terminal.lua终端封装(betterTerm/内置) -
lua/quick-c/make_search.lua异步 Makefile 搜索与目录选择 -
lua/quick-c/make.lua选择 make/解析目标/在 cwd 执行 -
lua/quick-c/telescope.luaTelescope 交互(目录与目标、自定义参数) -
lua/quick-c/build.lua构建/运行/调试 -
lua/quick-c/cc.lua生成或使用指定的compile_commands.json -
lua/quick-c/keys.lua键位注入
-
-
行为保持不变:
- 键位可配置/禁用;多 Makefile 时目录先选后执行;选择后自动关闭选择器并在终端执行;全程异步不阻塞。
- 如在 PowerShell 下运行,会自动使用
& 'path\to\exe'语法;cmd/其它 shell 下会使用"path\to\exe" - 使用 MSVC
cl编译时,请确保已在“开发者命令提示符”或已正确设置 VS 环境变量的终端中启动 Neovim
- 需要安装并配置
nvim-dap与codelldb :QuickCDebug会以codelldb方案启动,program指向最近一次构建输出
- 可执行文件写到哪里了?
- 由
outdir决定:"source"表示写到源文件所在目录;否则写到你配置的目录(相对:pwd或绝对路径)。 - 示例:
outdir = "build/bin"时,a.c将生成./build/bin/a.exe(Windows)或./build/bin/a.out(Unix)。 - 若
QuickCRun/QuickCDebug找不到 exe:请确认outdir设置与期望一致,或在debug.search.dirs中加入你的产物目录(如./build/bin)。
- 由
- 找不到编译器:请确认
gcc/g++、clang/clang++或cl在PATH中 - 构建失败但无输出:查看 Neovim
:messages或终端面板中的编译器警告/错误 - 终端无法发送命令:如安装了
betterTerm但发送失败,插件会自动回退到内置终端 - 无法运行可执行文件:请先
:QuickCBuild;或检查输出目录与文件后缀(Windows 需要.exe) - 未解析到 make 目标:确认项目存在
Makefile,以及make -qp在该目录下可运行;Windows 可改用mingw32-make
欢迎贡献代码与文档!请先阅读:
参见 Release.md