上一篇讲的是 Zekit 是什么。这一篇只干一件事:把源码变成你工程里的一个
.lib。全程以 Windows 为主,Linux 是同一套逻辑,只换个预设名。跟着做完,你手上会有一个能编、能链接、能跑中文的工程。
视频版:【C++ 桌面 GUI Zekit:单静态库,内置 D3D12 / Vulkan / OpenGL 渲染后端】P2 环境搭建与构建
一、整套流程其实只有三步
| 步骤 | 做什么 | 大概耗时 |
|---|---|---|
| 1 | git clone 拉源码 | 几秒 |
| 2 | 两条 cmake 编出 Zekit.lib | 几分钟(首次) |
| 3 | 自己工程的属性页里填三处 | 两分钟 |
看起来步骤不少,但这三件事只需要做一次。之后每一集都是在这个工程里加代码,不会再碰构建配置。
先说一个必须提前知道的事,能省你半小时:
⚠️ Releases 里没有编好的库。 官方 Releases 放的是使用文档和控件画廊,
.lib必须自己编——就是你上面第 2 步那两条命令。
二、第一步:把源码拉下来
在任意一个空目录里:
git clone https://github.com/Z-ze489/Zekit.git
仓库不大,一千三百多个文件、八个多兆,几秒钟就完:
Cloning into 'Zekit'...
Receiving objects: 100% (1941/1941), 8.45 MiB
Updating files: 100% (1349/1349), done.
拉完之后先认清三个位置,后面所有路径都从这里长出来:
| 位置 | 是什么 | 你要不要看 |
|---|---|---|
Zekit/include/ | 公开头文件 | 用库只看这里 |
Zekit/(再往里一层) | 库内实现和私有头 | 想看实现时才进来 |
CMakePresets.json | 编译入口,预设全写好了 | 不用改,直接用 |
这两个 Zekit 目录很容易搞混,因为名字一样。记住一条:你工程里要填的是带 include 的那一层。 后面第五节的第一个坑,就是填错了这一层。
三、第二步:编出 Zekit.lib
预设都写好了,你不需要自己拼任何 CMake 参数。装的是 Visual Studio 2026,就用 windows-msvc 这一套:
cmake --preset windows-msvc
cmake --build --preset windows-msvc-release
一句配置,一句编译。跑完你会看到:
-- Build files have been written to: build/msvc
Zekit.lib -> x64/Release/Zekit.lib
注意产物在哪。 它没有进 build/ 目录,而是在仓库根的 x64/Release/ 下面。
这一点必须记住,因为第 4 步要填的就是这个路径。MSVC 预设把输出目录交给了 VS 那套默认布局,所以你在仓库根看到 x64,而不是 CMake 惯常的 build/Release。第一次找 lib 找不到的人,几乎都是在这里翻 build/。
顺带一个一致性提醒。 这一集编的是 Release 版。第 4 步属性页切到"所有配置",是为了让 Debug 和 Release 都能编过;但真要跑起来时,工程配置也切到 Release 会省事得多——拿 Debug 的运行时去配 Release 的静态库,容易撞上运行库不一致的警告(
LNK4098那类)。第一次接入,别把变量放在配置组合上。
不想敲命令:用 VS 打开
配置那一步跑完,build/msvc/ 里会生成一个 Zekit.slnx。双击用 VS 打开,选 Release,生成解决方案,结果完全一样。
方案里会有六个目标,不用管它们,你要的只有 zekit 这一个。
VS 2022 / Linux
还在用 Visual Studio 2022,就把预设名换掉,后面照样是 release:
cmake --preset windows-vs2022
cmake --build --preset windows-vs2022-release
Linux 上是同一套逻辑,预设换成 linux-release:
cmake --preset linux-release
cmake --build --preset linux-release
产物是一个静态库 .a。应用层代码一个字都不用改。
预设对照:
| 环境 | 配置 | 编译 |
|---|---|---|
| VS 2026 / MSVC | windows-msvc | windows-msvc-release |
| VS 2022 | windows-vs2022 | windows-vs2022-release |
| Linux | linux-release | linux-release |
两套 Windows 预设编的是同一份源码,源文件清单只有一处声明(cmake/ZekitSources.cmake),所以你不用为了换编译器去改任何东西。
四、第三步:接进你自己的 VS 工程
1. 新建项目
VS 里新建项目,模板选控制台应用,语言 C++、平台 Windows,直接下一步。
这一集我们只验证"能不能编过、能不能链接上",所以空项目就够,不需要任何界面代码。
2. 选中"项目",不是"解决方案"
建好之后先认清位置。解决方案资源管理器里,要选中的是项目名那一行,不是上面那行解决方案。
选中项目 → 右键 → 属性。
这一步选错了,后面填的路径对整份解决方案都不生效——而且它不会报错,只会莫名其妙地链接不上。这是本集最隐蔽的一个坑。
3. 填三处
打开属性页后,先把左上角配置切到「所有配置」,平台确认是 x64,然后填这三处:
① C/C++ → 常规 → 附加包含目录
D:\Demo\Zekit\Zekit\include
填到 include 这一级,不是仓库根,也不要指到某个具体头文件上——头文件是按目录去找的。
② 链接器 → 输入 → 附加依赖项
D:\Demo\Zekit\x64\Release\Zekit.lib
写完整路径最省事。路径里带 x64 和 Release,两边都不能少。
文件名打错一个字母,或者指到了 Debug 目录,编译能过,链接一定失败——因为编译阶段只找头文件,根本没碰 lib。
③ C/C++ → 命令行 → 其他选项
/utf-8
最后这一步,也是绝对不能漏的一步。
不写这一条,源码里的中文会按系统本地代码页去解释:轻则字符串乱码,重则直接编译不过。凡是界面里出现"锟斤拷"的,八成就是漏了这行。
4. 先编一个空 main 验证
#include <Zekit.h>
int main() {
return 0;
}
能过,说明三处都对。过不去,就看错误码——报错的位置,就是没配对的地方。
五、四种报错,四个原因
我把这一集里最容易撞上的错都列成表,撞上了直接对号入座:
| 报错 / 现象 | 真正的原因 | 怎么修 |
|---|---|---|
LNK2019 无法解析的外部符号 | lib 路径不对,或平台不是 x64 | 检查附加依赖项,以及配置页上的平台是否 x64 |
中文乱码 / C4819 警告 | /utf-8 没加,或加到了别的配置 | C/C++ → 命令行 → 其他选项 |
fatal error C1083 找不到头文件 | 包含目录指到了仓库根,少了 include | 补上 Zekit\include 这一层 |
| 能编过但链接失败,lib 路径看着没错 | 属性页开在了"解决方案"上,不是"项目" | 重新选中项目行 → 属性 |
LNK2019 和 C1083 这两个,占了新手第一次接入失败的绝大多数。它们的区别很好记:头文件的问题在编译期炸,lib 的问题在链接期炸。
六、想要文档和示例程序
库没有现成可下的,都得自己编。但如果只是想先看看、先读文档,Releases 上的 v1.0.0 有你要的东西:
| 内容 | 是什么 |
|---|---|
Zekit-windows-x64.zip | Windows 包(Linux 是 .tar.gz) |
ZekitGuide | 离线文档阅读器,2,749 页全编在里面 |
ZekitDemo | 控件画廊,静态链接,不装 VC 运行库也能跑 |
ZekitDemo 值得单独说一句:它是静态链接的,拿到一台没装任何运行库的干净机器上也能双击就跑。想知道这个库做出来的界面长什么样,看它比看文档快。
七、GitHub 进不去的时候
国内访问 GitHub 不顺,仓库在 Gitee 上有镜像,Releases 也同步了一份,版本号一样是 v1.0.0:
git clone https://gitee.com/z-ze489/Zekit.git
文档包去 Gitee 的 Releases 下:
后面编译、配置的步骤一个字都不用改。
八、这一篇的清单
到这里环境就通了。四句话复盘:
clone之后,两行cmake拿到Zekit.lib- Release 产物在
x64/Release/,不在build/里 - 工程里填三处:包含目录、附加依赖项、
/utf-8 - 包里不提供 lib:只想先看文档,就下
ZekitGuide
下一篇开始写代码:创建第一个窗口。你会看到上一集说的"十几行就能跑起来",在你自己那个工程里真正跑起来是什么样子。
有问题欢迎提 issue,或者直接在评论区说。