1. CMake 在 VST 3 插件工程里到底管什么:一次“找不到源文件”的排查开场
SDK 自带示例能编过,换成自己的 processor.cpp 和 controller.cpp,configure 阶段直接报找不到源文件——这类问题很少是代码写错,八成是代码开发工具链里的 CMake 配置没把路径基准搞对。VST 3 插件在 VST 3 SDK 里的构建入口只有顶层那份 CMakeLists.txt,插件工厂入口、bundle 结构、Info.plist 都由 SDK 的 CMake 函数代劳。这篇写的是从 SDK 目录到可加载 .vst3 的一条完整操作路径:命令怎么敲、参数怎么设、路径为什么必须绝对、构建成功后怎么确认产物。适合已经能写 C++ 但被构建脚本卡住的音频插件开发者。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 从 SDK 目录到第一个 .vst3:CMake 两阶段构建的完整链路
2.1 为什么构建入口只能是 SDK 顶层那份 CMakeLists.txt
VST 3 插件的产物形态在每个平台上并不一样:有的平台产出的是一个包目录,里面除了二进制还有描述文件和插件工厂的入口信息;有的平台就是另一种目录层级。如果手写工程文件,等于要同时维护多套彼此独立的构建配置,加一个源文件要在每套配置里各改一遍,任何一处漏改都会在某个平台上翻车。
SDK 的做法是把这些平台差异收敛成 CMake 函数调用。smtg_add_vst3plugin 这类函数负责按平台生成 bundle 结构、Info.plist 和插件工厂入口,你只需要告诉它插件名和源文件列表。这也解释了为什么构建入口必须是 SDK 顶层那份 CMakeLists.txt:函数定义在 SDK 的 CMake 模块里,只有先进入 SDK 的 CMake 上下文,这些函数才存在。
所以不要把 SDK 当成一个可以 add_subdirectory 引入的外部依赖,反过来在自己工程里另起一个 project()。正确姿势是站在 SDK 根目录,把插件源码目录通过参数指进去,让 SDK 的顶层脚本去 include 它。这个方向搞反了,后面所有参数都会对不上。
再往下要分清 CMake 的两个阶段。configure 阶段展开所有 CMakeLists.txt、加载 SDK 模块、校验参数、生成构建文件;build 阶段才真正调编译器。报错出现在哪个阶段,排查方向完全不同:configure 阶段的报错基本是路径、参数、目录结构问题;build 阶段的报错才是源码和链接问题。很多人一看到红字就去翻 C++ 代码,其实错误发生在前一个阶段。
2.2 一条命令完成 configure:逐参数拆开看
配置阶段用一条命令就能完成,但每个参数都别当成咒语背,要知道它改了什么。
bash复制# 在 SDK 根目录执行:-S . 指向顶层 CMakeLists.txt,-B build 把生成物收进独立目录
cmake -S . -B build -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DSMTG_MYPLUGINS_SRC_PATH=$(pwd)/my-plugins \
-DSMTG_ADD_VSTGUI=ON
-S . 指定源码目录,这里的 . 是 SDK 根目录,也就是顶层 CMakeLists.txt 所在位置。-B build 指定构建目录,所有生成的构建文件、中间对象、最终产物都落在这个目录下,不污染源码树;换一套参数重新配置时,删掉这个目录就能从干净状态重来,这是排错时最省事的动作。
-G Ninja 选生成器。Ninja 的增量构建快,而且它是单配置生成器——构建类型在 configure 阶段就通过 CMAKE_BUILD_TYPE 定死了,build 阶段不需要再指定。这一点很关键,后面第 4 章会讲到为什么“改了参数只重新 build”是个典型陷阱。
-DCMAKE_BUILD_TYPE=Release 决定优化级别和调试信息。调试插件逻辑时用 Debug 方便单步,但要验证音频线程里的真实表现、验证产物能不能被宿主正常加载,必须用 Release 再走一遍,两者的行为差异在实时线程里会被放大。
-DSMTG_MYPLUGINS_SRC_PATH=$(pwd)/my-plugins 告诉 SDK 你的插件代码放在哪个目录。这里用 $(pwd) 展开成绝对路径不是洁癖,是必须——原因在第 3 章展开。
-DSMTG_ADD_VSTGUI=ON 把 VSTGUI 支持编进来。只要你的编辑器界面用了这套控件,这个开关就必须打开;纯参数、无自定义界面的插件可以不开,能省下一截编译时间。
参数之间没有先后依赖,但建议按“目录 → 生成器 → 构建类型 → 插件路径 → 功能开关”的顺序写,出问题时一眼能扫出哪一项可疑。
2.3 build 阶段与产物确认
configure 成功只说明构建系统生成好了,还没编译一行代码。接着执行构建:
bash复制# Ninja 是单配置生成器,构建类型已在 configure 阶段确定,这里不需要 --config
cmake --build build
用 cmake --build 而不是直接敲 ninja,好处是换生成器时命令不用改。如果你的环境用的是多配置生成器,才需要在后面补 --config Release;用 Ninja 时加了反而多余。
构建成功后,产物不是在 build 根目录下随便躺着一个动态库,而是按平台规则生成的一个 .vst3 bundle。这个 bundle 是一个整体:里面有二进制,有描述文件,有插件工厂的入口信息。判断构建是否真的成功,不要只看“编译通过”四个字,要去 build 目录下确认这个 bundle 完整生成了,而不是只有一个中间对象文件。
提示:第一次构建建议完整走一遍 configure + build,不要跳过 configure 直接复用别人的 build 目录。构建目录里缓存了上一次的路径和参数,跨机器拷贝过来大概率对不上。
2.4 先用示例验链路,再换自己的代码
替换代码的顺序比想象中重要。我一般按三步走,每一步只引入一个变量:
第一步,不碰任何自己的代码,直接用 SDK 自带示例跑通 configure + build,确认编译器、生成器、SDK 模块这三样都没问题。这一步失败,说明环境本身有问题,跟你的插件代码无关。
第二步,加上 -DSMTG_MYPLUGINS_SRC_PATH 指向一个只含最小插件的目录,源文件先极简,能编过就行。这一步验证的是外置目录机制有没有接对。
第三步,才把真正的 processor.cpp、controller.cpp 填进去。这一步报错,范围就缩小到源码本身。
跳过前两步直接上自己的代码,一旦失败,你面对的可能是环境、路径、源码三类问题叠在一起,排查成本翻几倍。这套顺序看起来慢,实际是最快的。
3. 把自己的插件挂进 SDK:smtg_add_vst3plugin 与外置源码目录
3.1 smtg_add_vst3plugin 替你做了哪些事
很多人第一次看到这个函数会下意识觉得“不就是把源文件编成库吗”,于是手写 add_library 加一堆 target_link_libraries,最后产物能被编译出来,却加载不了。差别在于函数额外处理了产物形态层面的工作。把两者对照一下:
| 工作项 | 手写 add_library | smtg_add_vst3plugin |
|---|---|---|
| 编译源文件 | 需要自己列 | 传参即可 |
| 按平台生成 bundle 目录结构 | 需要自己写平台分支 | 函数内部处理 |
| 生成 Info.plist 等描述文件 | 需要自己维护模板 | 函数内部生成 |
| 导出插件工厂入口 | 需要自己写导出配置 | 函数内部处理 |
| 安装/拷贝规则 | 需要自己写 install | 跟随 SDK 约定 |
表格里后三行才是关键。插件能不能被宿主识别,靠的不是二进制里有没有你的类,而是 bundle 结构是否合规、工厂入口是否按规范导出。这些样板代码写错一处,编译全绿,加载全黑,属于典型的黑匣子故障。所以结论很直接:只要在 SDK 体系内做插件,就用 smtg_add_vst3plugin,不要自己拼 add_library。
3.2 外置目录的 CMakeLists.txt 怎么写
SDK 允许你把插件代码放在源码树外面,通过 SMTG_MYPLUGINS_SRC_PATH 指过去,不用往 SDK 目录里塞文件。这个外置目录下需要一个 CMakeLists.txt,内容不长:
cmake复制# my-plugins/CMakeLists.txt
cmake_minimum_required(VERSION 3.20)
project(MyPlugins LANGUAGES CXX)
# smtg_add_vst3plugin 是 SDK 提供的函数,负责按平台生成 bundle 结构、
# Info.plist 和插件工厂入口,不用自己写这些样板
smtg_add_vst3plugin(MyPlugin
source/processor.cpp
source/controller.cpp
)
target_include_directories(MyPlugin PRIVATE source)
逐段说明。cmake_minimum_required(VERSION 3.20) 声明最低版本要求,这个版本号要和 SDK 顶层脚本的要求对齐,低于它会在 configure 阶段被拦下。project(MyPlugins LANGUAGES CXX) 起一个逻辑上的工程名,注意这里的名字只是给这组插件归类用,最终产物名由 smtg_add_vst3plugin 的第一个参数决定。
smtg_add_vst3plugin(MyPlugin source/processor.cpp source/controller.cpp) 是核心。第一个参数是插件目标名,也是最终 bundle 的名字;后面跟源文件列表,路径相对于这份 CMakeLists.txt 所在目录。target_include_directories(MyPlugin PRIVATE source) 把 source 目录加进头文件搜索路径,这样 processor.cpp 里 include 同目录的头文件不用写长路径。PRIVATE 表示这个包含路径不向外传递,插件目标本身也不需要被别人链接,用 PRIVATE 是合适的选择。
注意:这份文件的名字必须叫
CMakeLists.txt,不能改成MyPlugins.txt之类。SDK 是按固定文件名去 include 这个目录的,改名之后 configure 阶段不会报“文件名错”,而是表现为你的插件根本没被加进构建,产物里找不到它。
3.3 SMTG_MYPLUGINS_SRC_PATH 的解析基准
这个参数是整条链路里最容易翻车的一处,值得单独拎出来说。它是相对构建目录解析的,不是相对你当前敲命令的目录,也不是相对 SDK 根目录。
也就是说,如果你写成 -DSMTG_MYPLUGINS_SRC_PATH=my-plugins,CMake 会跑去 build/my-plugins 下面找 CMakeLists.txt。那个位置当然什么都没有,于是报出来的错是“找不到源文件”。这个报错极具误导性:你回头检查 source/processor.cpp,文件名没错、路径也没错,怎么看都不像有问题,实际上基准目录从一开始就偏了。
正确写法是用 $(pwd) 展开成绝对路径:
bash复制# 在 SDK 根目录执行,$(pwd) 展开为 SDK 根目录的绝对路径
cmake -S . -B build -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DSMTG_MYPLUGINS_SRC_PATH=$(pwd)/my-plugins \
-DSMTG_ADD_VSTGUI=ON
如果懒得每次敲 $(pwd),也可以在 shell 里先算好一个变量再传进去,效果一样。关键是落到 CMake 手里的值必须是绝对路径。这条是血泪经验,我第一次遇到时在源文件列表上折腾了半小时,最后发现是基准目录变了。
3.4 CMAKE_BUILD_TYPE 与 SMTG_ADD_VSTGUI 的取舍
CMAKE_BUILD_TYPE 在单配置生成器下是一次性定死的。这意味着你改了这个值,必须重新跑一次 configure,只重新 build 是没用的——构建目录里缓存的还是上一次的类型。日常节奏我一般是:调界面和参数逻辑用 Debug,验证音频处理和数据上报用 Release,两套构建目录分开,build-debug 和 build-release,互不干扰。
SMTG_ADD_VSTGUI=ON 的代价是编译时间变长,因为要把整套 GUI 支持编进来。如果你的插件确实有自定义编辑器,这个开关没有商量余地;如果只是做参数自动化、没有任何界面,关掉它能让构建快不少,产物也更小。判断标准很简单:源码里有没有 include VSTGUI 的头、有没有继承对应的编辑类。有就必须开,没有就别开。
这里有个常见的误判:先关着开关编过了,后来加了界面代码,编译报一堆未定义符号,第一反应是“SDK 装坏了”。实际上就是开关没开,重新 configure 带上 -DSMTG_ADD_VSTGUI=ON 就好。参数和源码要对得上,这是构建系统的基本约束。
4. 避坑与排查:CMake 配置 VST 3 插件时的五个翻车点
4.1 路径类:找不到源文件,以及被改名的 CMakeLists.txt
现象:configure 阶段报找不到源文件,但把报错里的路径和实际文件对照,文件名、目录名都没错。
原因:SMTG_MYPLUGINS_SRC_PATH 给的是相对路径,CMake 以构建目录为基准去解析,实际查找位置变成了 build/ 下面,自然找不到。
解决:改成绝对路径,用 $(pwd)/my-plugins 展开。排查这类问题时,先看报错里的完整路径前缀是不是 build/ 开头,是的话基本可以锁定。
现象:外置目录里的文件明明在,插件却没被加进构建,产物里找不到它,configure 也不报错。
原因:目录下的构建脚本被改名了。SDK 按固定文件名去 include,改名之后它认为这个目录没有可用的构建脚本,静默跳过。
解决:文件名保持 CMakeLists.txt。这类静默失败比报错更难查,因为没有任何红字提示,只能靠对比“期望的产物”和“实际的产物”发现。
4.2 开关类:GUI 参数没开,以及改了参数只 build 不 configure
现象:源码里用了 VSTGUI 的控件,编译或链接阶段报一堆未定义符号,看着像 SDK 缺模块。
原因:configure 时没带 -DSMTG_ADD_VSTGUI=ON,GUI 支持根本没被编进来。
解决:补上参数重新 configure。注意是重新 configure,不是重新 build——开关是 configure 阶段读取的,缓存里没有就是没有。
现象:改了 SMTG_MYPLUGINS_SRC_PATH 或 CMAKE_BUILD_TYPE 之后直接 cmake --build build,产物行为和预期不一致,像是参数没生效。
原因:-D 参数只在 configure 阶段写入缓存,build 阶段读的是缓存里的旧值。Ninja 这种单配置生成器尤其明显,构建类型定死之后不会自己变。
解决:任何 -D 参数变更后,完整重跑 configure 再 build。养成“参数变了就重配”的习惯,能省掉大量“为什么没生效”的困惑。
4.3 产物类:构建全绿但宿主扫不到插件
现象:编译链接全部通过,build 目录下也确实有产物,但宿主扫描插件目录之后列表里没有它。
原因:最常见的是产物还留在 build 目录里,没有放到宿主实际扫描的插件目录。其次是手动拷贝时只把里面的二进制文件单独拎出来,丢掉了 bundle 的目录结构——外壳没了,宿主自然认不出来。
解决:整包搬运,保持 bundle 的目录层级完整,别拆开单独拷文件。验证顺序上,先确认产物路径,再确认目标目录,最后才怀疑代码。另外还要确认宿主加载的是不是本次构建的那一份,之前装过旧版本的话很容易加载到旧的,表现出来就是“改了代码没反应”。
排查这类问题有个通用思路:把“构建成功”和“加载成功”当成两件独立的事。构建成功只证明编译链接没问题,加载成功还要额外满足产物结构、放置位置、版本一致三个条件。把这三条逐个排掉,问题基本就定位了。
5. 把配置固化成脚本:一条命令复现构建与三步验证
参数一多,靠手敲迟早会漏。我习惯在 SDK 根目录放一个构建脚本,把那条 configure 命令和 build 命令固定下来,同时在脚本里把路径算成绝对路径,从源头掐掉第 4 章那个相对路径的坑。
bash复制#!/usr/bin/env bash
set -euo pipefail
# 以脚本所在目录(SDK 根目录)为基准,保证任何位置执行都得到绝对路径
SDK_ROOT="$(cd "$(dirname "$0")" && pwd)"
cmake -S "$SDK_ROOT" -B "$SDK_ROOT/build" -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DSMTG_MYPLUGINS_SRC_PATH="$SDK_ROOT/my-plugins" \
-DSMTG_ADD_VSTGUI=ON
cmake --build "$SDK_ROOT/build"
set -euo pipefail 让脚本在任一步失败时立刻退出,避免 build 阶段拿着上一次的缓存继续跑。SDK_ROOT 用 cd 加 pwd 算出来,无论从哪个目录调用脚本,传进 CMake 的都是绝对路径。后面几行就是第 2 章那条命令的原样固化,改参数只需要改这一处。
构建完成之后,按下面三步验证,顺序不要乱:
| 步骤 | 检查位置 | 通过标准 |
|---|---|---|
| 1. 产物完整性 | build 目录下的 .vst3 bundle |
目录结构完整,不只有一个二进制 |
| 2. 放置位置 | 宿主扫描的插件目录 | 与 build 里的是同一份,整包拷贝 |
| 3. 加载验证 | 宿主插件列表 | 能扫到、能实例化、参数能保存 |
三步里任何一步不过,就不要往下走。第 1 步不过说明构建有问题,第 2 步不过说明部署有问题,第 3 步不过才轮到怀疑插件实现。这个顺序能避免在错误的方向上浪费时间。
从那以后我每次新建插件工程,都强制先跑一遍脚本、确认三步验证全过,再开始写业务代码。构建这条链路一旦稳定,后面调音频算法和参数逻辑才谈得上效率。希望帮到你。
