从 clone 到跑通:C++ 桌面 GUI 库编成 .lib 接进 VS 工程,附四种报错对照

0 阅读7分钟

上一篇讲的是 Zekit 是什么。这一篇只干一件事:把源码变成你工程里的一个 .lib。

全程以 Windows 为主,Linux 是同一套逻辑,只换个预设名。跟着做完,你手上会有一个能编、能链接、能跑中文的工程。

视频版:【C++ 桌面 GUI Zekit:单静态库,内置 D3D12 / Vulkan / OpenGL 渲染后端】P2 环境搭建与构建

源码:GitHub | Gitee


一、整套流程其实只有三步

步骤做什么大概耗时
1git 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 / MSVCwindows-msvcwindows-msvc-release
VS 2022windows-vs2022windows-vs2022-release
Linuxlinux-releaselinux-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 有你要的东西:

github.com/Z-ze489/Zek…

内容是什么
Zekit-windows-x64.zipWindows 包(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 下:

gitee.com/z-ze489/Zek…

后面编译、配置的步骤一个字都不用改。


八、这一篇的清单

到这里环境就通了。四句话复盘:

  1. clone 之后,两行 cmake 拿到 Zekit.lib
  2. Release 产物在 x64/Release/,不在 build/ 里
  3. 工程里填三处:包含目录、附加依赖项、/utf-8
  4. 包里不提供 lib:只想先看文档,就下 ZekitGuide

下一篇开始写代码:创建第一个窗口。你会看到上一集说的"十几行就能跑起来",在你自己那个工程里真正跑起来是什么样子。

有问题欢迎提 issue,或者直接在评论区说。