DEV Community

泽
泽

Posted on

Building a C++ GUI library from source: CMake presets and wiring it into Visual Studio

Zekit is a C++20 desktop GUI toolkit that compiles to a single static library: window, GPU renderer, widget set, layout, text and IME. This post covers the build path — from git clone to a Visual Studio project that compiles and links.

It is the least interesting part of the library and, based on the issues I get, the part where most people get stuck.

What the download gives you (and what it doesn't)

The release assets contain the offline documentation and a prebuilt widget gallery. They do not contain a compiled .lib. You build that yourself — it's two commands, but you have to run them.

Step 1 — clone

git clone https://github.com/Z-ze489/Zekit.git
Enter fullscreen mode Exit fullscreen mode

About 1,349 files and 8.5 MB, so it finishes in seconds. Three locations matter afterwards:

Path What it is Do you need it
Zekit/include/ public headers yes — this is the only one your project needs
Zekit/ (one level deeper) library implementation and private headers only if you want to read the source
CMakePresets.json the build entry point no, the presets are already written

The two Zekit directories are easy to confuse because they share a name. Remember this: your project points at the one containing include.

Step 2 — build with presets

You don't have to assemble CMake flags. With Visual Studio 2026:

cmake --preset windows-msvc
cmake --build --preset windows-msvc-release
Enter fullscreen mode Exit fullscreen mode

One command configures, one builds. Output:

-- Build files have been written to: build/msvc
Zekit.lib  ->  x64/Release/Zekit.lib
Enter fullscreen mode Exit fullscreen mode

Note where the artifact lands. It is not inside build/. It is at x64/Release/ in the repository root, because the MSVC presets use the Visual Studio output layout rather than CMake's usual build/Release. This one detail accounts for a lot of "where is my lib" confusion.

Other presets — same source, same file manifest, nothing for you to change:

Environment Configure Build
VS 2026 / MSVC windows-msvc windows-msvc-release
VS 2022 windows-vs2022 windows-vs2022-release
Linux linux-release linux-release

If you'd rather click than type: after the configure step there is a Zekit.slnx in build/msvc/. Open it, pick Release, build the solution — identical result. The solution has six targets; you only care about zekit.

On Linux the product is a .a. Application code does not change.

Step 3 — a project that links it

Create a console application in Visual Studio (C++ / Windows). An empty project is enough; we're only proving that it compiles and links.

Then two details that decide whether the next 20 minutes go well:

Select the project, not the solution. In Solution Explorer, right-click the project node and open Properties. Settings applied to the solution node silently don't reach the project — and nothing warns you. This is the most invisible failure in the whole setup.

Set Configuration to "All Configurations" and Platform to x64 before editing anything.

Now fill in three places:

1. C/C++ → General → Additional Include Directories

D:\Demo\Zekit\Zekit\include
Enter fullscreen mode Exit fullscreen mode

Point at the include folder itself — not the repository root, and not an individual header. Headers are resolved by directory.

2. Linker → Input → Additional Dependencies

D:\Demo\Zekit\x64\Release\Zekit.lib
Enter fullscreen mode Exit fullscreen mode

A full path is the simplest correct answer. Both x64 and Release must be right: a typo in the filename or a path into Debug will still compile cleanly and then fail at link time, because the compiler never looked at the lib.

3. C/C++ → Command Line → Additional Options

/utf-8
Enter fullscreen mode Exit fullscreen mode

Do not skip this one. Without it, non-ASCII string literals are interpreted in the system's local code page — at best you get garbled text at runtime, at worst the file doesn't compile. Every "my Chinese labels turned into gibberish" report traces back to this line.

Verify with an empty main

#include <Zekit.h>

int main() {
    return 0;
}
Enter fullscreen mode Exit fullscreen mode

Clean build means all three settings are right. If it fails, the error tells you which one isn't:

Error / symptom Actual cause Fix
LNK2019 unresolved external symbol lib path wrong, or platform isn't x64 check Additional Dependencies and the Platform dropdown
Mojibake, or C4819 warning /utf-8 missing or applied to the wrong configuration C/C++ → Command Line → Additional Options
fatal error C1083 cannot open include file include path points at the repo root, missing include append the include level
Compiles, but linking fails and the path looks right properties were opened on the solution, not the project reselect the project node

The distinction worth memorising: header problems explode at compile time, lib problems explode at link time. That single sentence separates the four rows above.

One more: if you build Release but debug a Debug configuration, you can hit run-time-library mismatch warnings (LNK4098 and friends). Pick one configuration for the first integration and stay there.

Documentation

The library has no downloadable build, but the docs are in the releases: an offline reader with 2,749 pages, and a statically linked widget gallery that runs on a machine with no runtime installed. The gallery is the fastest way to see what the library looks like.

If GitHub is slow from where you are, there's a Gitee mirror with the same release version:

Build once, then forget about it — everything after this is application code.

Top comments (0)