Skip to main content
This guide will walk you through building Zeal from source code using CMake.

​
Prerequisites

Before building Zeal, make sure you have all the required dependencies installed for your platform.

​
Basic Build

Zeal uses CMake as its build system. The simplest way to build Zeal is:
1

Configure the build

Run CMake to configure the build system:
cmake -B build
This creates a build directory with the generated build files.
2

Build the project

Compile Zeal using:
cmake --build build
The compiled binary will be available in the build directory.

​
Using CMake Presets

Zeal provides CMake presets for common build configurations. Presets simplify the build process by providing pre-configured settings.

​
Available Presets

cmake --preset ninja-multi
cmake --build build/ninja-multi --config Debug
The presets use the Ninja Multi-Config generator for faster builds. Make sure you have Ninja installed.

​
Preset Configurations

  • ninja-multi: Basic multi-configuration build
  • ninja-multi-portable: Portable build with ZEAL_PORTABLE_BUILD=ON
  • ninja-multi-vcpkg: Windows build using vcpkg for dependencies
  • ninja-multi-vcpkg-test: Build with testing enabled

​
Build Options

Zeal supports several CMake options to customize the build:
OptionDefaultDescription
BUILD_TESTINGONBuild the testing suite
ZEAL_PORTABLE_BUILDOFFBuild portable version
ZEAL_RELEASE_BUILDOFFMark as a tagged release build
ZEAL_USE_QT5OFFForce use of Qt 5 (auto-detected by default)

​
Examples

cmake -B build -DBUILD_TESTING=OFF
cmake --build build

​
Build Types

CMake supports multiple build types:
  • Debug: No optimization, includes debug symbols
  • Release: Full optimization, no debug symbols
  • RelWithDebInfo: Optimized with debug symbols (recommended)
  • MinSizeRel: Optimized for size
cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build
When using multi-config generators like Ninja Multi-Config, specify the configuration during build:
cmake --build build --config RelWithDebInfo

​
Running Tests

If BUILD_TESTING is enabled, you can run the test suite: 
cmake --preset ninja-multi-vcpkg-test
cmake --build build/ninja-multi-vcpkg-test --config Debug
ctest --test-dir build/ninja-multi-vcpkg-test -C Debug

​
Building Packages

Zeal uses CPack for creating distributable packages: 
cmake --build build --target package

​
Troubleshooting

​
Qt Version Issues

Zeal requires Qt 5.15.2 or Qt 6.2.0+. If CMake can’t find Qt: 
cmake -B build -DCMAKE_PREFIX_PATH=/path/to/qt
Qt WebEngine Widgets is required. Make sure it’s installed as part of your Qt distribution.

​
vcpkg Dependencies

On Windows, using vcpkg is recommended for managing dependencies: 
set VCPKG_ROOT=C:\path\to\vcpkg
cmake --preset ninja-multi-vcpkg

​
libarchive Not Found

If libarchive isn’t found (common on macOS with Homebrew): 
cmake -B build -DLibArchive_INCLUDE_DIRS=/opt/homebrew/opt/libarchive/include \
               -DLibArchive_LIBRARIES=/opt/homebrew/opt/libarchive/lib/libarchive.dylib

​
Missing X11 Dependencies (Linux)

On Linux, you may need X11 development packages: 
# Debian/Ubuntu
sudo apt install libx11-dev libxcb-keysyms1-dev

# Fedora
sudo dnf install libX11-devel xcb-util-keysyms-devel

​
Compiler Warnings as Errors

CMake 3.24+ enables CMAKE_COMPILE_WARNING_AS_ERROR by default. This helps catch potential issues early.
If you encounter warnings that block the build, fix them or temporarily disable this for testing: 
cmake -B build -DCMAKE_COMPILE_WARNING_AS_ERROR=OFF

​
Next Steps

Dependencies

Learn about all required and optional dependencies

Platform Notes

Platform-specific build instructions and requirements

Build docs developers (and LLMs) love

Get started for freeTalk to us