Platform-Specific Notes

This page covers platform-specific considerations when building Zeal on different operating systems.

Windows

Building Zeal on Windows requires careful dependency management. Using vcpkg is the recommended approach.

Prerequisites

Install Visual Studio

Install Visual Studio 2017 or newer with C++ development tools:

Desktop development with C++
Windows 10 SDK

Install Qt

Download and install Qt from qt.io:

Qt 5.15.2+ or Qt 6.2.0+
Include Qt WebEngine component
Add Qt’s bin directory to PATH

Install vcpkg

git clone https://github.com/microsoft/vcpkg.git C:\vcpkg
cd C:\vcpkg
.\bootstrap-vcpkg.bat

Set the environment variable:

$env:VCPKG_ROOT="C:\vcpkg"

Install Ninja (Optional)

winget install Ninja-build.Ninja

Or use Visual Studio’s bundled Ninja from Developer Command Prompt.

Building with vcpkg

The recommended build method on Windows uses the vcpkg preset:

cmake --preset ninja-multi-vcpkg
cmake --build build/ninja-multi-vcpkg --config Debug

The vcpkg preset automatically installs dependencies listed in vcpkg.json during the configure step.

Windows-Specific Options

When building on Windows, several platform-specific features are enabled:

Automatic dependency deployment: X_VCPKG_APPLOCAL_DEPS_INSTALL=ON copies DLLs to the build directory
Version information: Embedded in the executable via versioninfo.rc
WiX installer: Available for non-portable builds

Creating Windows Packages

cmake --build build/ninja-multi-vcpkg-release --config RelWithDebInfo --target package

WiX installer generation is only available for non-portable builds. Portable builds generate ZIP archives only.

Troubleshooting Windows

Qt Not Found

cmake --preset ninja-multi-vcpkg -DCMAKE_PREFIX_PATH="C:\Qt\6.5.0\msvc2019_64"

vcpkg Errors

If vcpkg integration fails:

# Manually specify toolchain file
cmake -B build -DCMAKE_TOOLCHAIN_FILE="C:\vcpkg\scripts\buildsystems\vcpkg.cmake"

OpenSSL DLLs Missing

Qt WebEngine requires OpenSSL DLLs at runtime:

vcpkg install openssl
# DLLs are automatically copied with X_VCPKG_APPLOCAL_DEPS_INSTALL

Linux

Linux builds vary by distribution but generally follow a similar pattern. X11 support is required for global shortcuts.

Ubuntu/Debian

Install build dependencies

sudo apt update
sudo apt install build-essential cmake ninja-build extra-cmake-modules

Install Qt

Qt 6 (recommended)

sudo apt install qt6-base-dev qt6-webengine-dev

Qt 5

sudo apt install qtbase5-dev qtwebengine5-dev libqt5x11extras5-dev

Install libraries

sudo apt install libarchive-dev libsqlite3-dev libssl-dev

Install X11 dependencies

sudo apt install libx11-dev libxcb-keysyms1-dev

Fedora/RHEL

Install development tools

sudo dnf groupinstall "Development Tools"
sudo dnf install cmake ninja-build extra-cmake-modules

Install Qt

Qt 6

sudo dnf install qt6-qtbase-devel qt6-qtwebengine-devel

Qt 5

sudo dnf install qt5-qtbase-devel qt5-qtwebengine-devel qt5-qtx11extras-devel

Install libraries

sudo dnf install libarchive-devel sqlite-devel openssl-devel

Install X11 dependencies

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

Arch Linux

sudo pacman -S base-devel cmake ninja extra-cmake-modules \
               qt6-base qt6-webengine \
               libarchive sqlite openssl \
               libx11 xcb-util-keysyms

Building on Linux

Standard CMake workflow:

cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build

Installing on Linux

cmake --build build --target install

# Or with DESTDIR for packaging
DESTDIR=/tmp/zeal-install cmake --build build --target install

Default installation paths (GNUInstallDirs):

Binary: /usr/local/bin/zeal
Icons: /usr/local/share/icons/
Desktop file: /usr/local/share/applications/

Wayland Support

Global keyboard shortcuts require X11. On Wayland, shortcuts will not work unless XWayland is used with X11 libraries available.

If X11 libraries are not found during configuration, Zeal builds with a no-op implementation:

-- X11 not found, global shortcuts will be disabled

Troubleshooting Linux

Qt WebEngine Missing

Qt WebEngine is a separate package on many distributions:

# Debian/Ubuntu
sudo apt install qtwebengine5-dev  # Qt 5
sudo apt install qt6-webengine-dev # Qt 6

# Fedora
sudo dnf install qt5-qtwebengine-devel  # Qt 5
sudo dnf install qt6-qtwebengine-devel  # Qt 6

X11 Headers Not Found

# Debian/Ubuntu
sudo apt install libx11-dev

# Fedora
sudo dnf install libX11-devel

xcb-util-keysyms Missing

# Debian/Ubuntu
sudo apt install libxcb-keysyms1-dev

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

macOS

Building on macOS is straightforward with Homebrew.

Prerequisites

Install Xcode Command Line Tools

xcode-select --install

Install Homebrew

If not already installed:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install dependencies

brew install cmake ninja qt@6 libarchive sqlite

Or for Qt 5:

brew install cmake ninja qt@5 libarchive sqlite

Building on macOS

Zeal automatically searches Homebrew paths for libarchive.

export CMAKE_PREFIX_PATH="$(brew --prefix qt@6)"
cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build

macOS App Bundle

The build produces a macOS application bundle:

Bundle location: build/Zeal.app
Binary: build/Zeal.app/Contents/MacOS/Zeal
Icon: Embedded in Zeal.app/Contents/Resources/zeal.icns

Running on macOS

# From terminal
open build/Zeal.app

# Or directly
./build/Zeal.app/Contents/MacOS/Zeal

macOS-Specific Features

Carbon framework: Used for global keyboard shortcuts
Retina support: Automatic high-DPI rendering
macOS bundle properties: Set in CMakeLists.txt

Troubleshooting macOS

Qt Not Found

Ensure CMAKE_PREFIX_PATH points to Qt:

export CMAKE_PREFIX_PATH="$(brew --prefix qt@6)"

# Or specify directly
cmake -B build -DCMAKE_PREFIX_PATH="$(brew --prefix qt@6)"

libarchive Issues

CMake checks these paths automatically:

/opt/homebrew/opt/libarchive (Apple Silicon)
/usr/local/opt/libarchive (Intel)

If not found, specify manually:

cmake -B build \
  -DLibArchive_INCLUDE_DIRS="$(brew --prefix libarchive)/include" \
  -DLibArchive_LIBRARIES="$(brew --prefix libarchive)/lib/libarchive.dylib"

Code Signing

For distribution, the app bundle needs to be signed:

codesign --deep --force --verify --verbose --sign "-" build/Zeal.app

Cross-Platform Considerations

C++ Standard

Zeal requires C++17:

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

This is configured automatically by CMake.

Qt Version Detection

Zeal automatically detects and prefers Qt 6, but falls back to Qt 5:

find_package(QT NAMES Qt6 COMPONENTS Core)
if(NOT QT_FOUND)
    find_package(QT NAMES Qt5 REQUIRED COMPONENTS Core)
endif()

To force Qt 5:

cmake -B build -DZEAL_USE_QT5=ON

Platform Detection in CMake

Zeal uses standard CMake variables:

WIN32: Windows builds
APPLE: macOS builds
UNIX: Linux and macOS builds
CMAKE_SYSTEM_PROCESSOR: Architecture detection

Global Shortcuts Implementation

Zeal uses different implementations per platform:

Platform	Implementation	Dependencies
Windows	Win32 API	`RegisterHotKey`
macOS	Carbon framework	Carbon.framework
Linux X11	XCB	libX11, xcb-util-keysyms
Linux Wayland	Not supported	Falls back to no-op

Building

Architecture

Contributing

​Windows

​Prerequisites

​Building with vcpkg

​Windows-Specific Options

​Creating Windows Packages

​Troubleshooting Windows

​Qt Not Found

​vcpkg Errors

​OpenSSL DLLs Missing

​Linux

​Ubuntu/Debian

​Fedora/RHEL

​Arch Linux

​Building on Linux

​Installing on Linux

​Wayland Support

​Troubleshooting Linux

​Qt WebEngine Missing

​X11 Headers Not Found

​xcb-util-keysyms Missing

​macOS

​Prerequisites

​Building on macOS

​macOS App Bundle

​Running on macOS

​macOS-Specific Features

​Troubleshooting macOS

​Qt Not Found

​libarchive Issues

​Code Signing

​Cross-Platform Considerations

​C++ Standard

​Qt Version Detection

​Platform Detection in CMake

​Global Shortcuts Implementation

​Next Steps

Building Zeal

Dependencies

Build docs developers (and LLMs) love

Windows

Prerequisites

Building with vcpkg

Windows-Specific Options

Creating Windows Packages

Troubleshooting Windows

Qt Not Found

vcpkg Errors

OpenSSL DLLs Missing

Linux

Ubuntu/Debian

Fedora/RHEL

Arch Linux

Building on Linux

Installing on Linux

Wayland Support

Troubleshooting Linux

Qt WebEngine Missing

X11 Headers Not Found

xcb-util-keysyms Missing

macOS

Prerequisites

Building on macOS

macOS App Bundle

Running on macOS

macOS-Specific Features

Troubleshooting macOS

Qt Not Found

libarchive Issues

Code Signing

Cross-Platform Considerations

C++ Standard

Qt Version Detection

Platform Detection in CMake

Global Shortcuts Implementation

Next Steps