Platform-Specific Notes

Platform-specific build requirements and instructions for Windows, Linux, and macOS

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

1. Install Visual Studio

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

   • Desktop development with C++
   • Windows 10 SDK
2. 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
3. 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"
   
4. 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:

Debug Build

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

ZIP Package

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

1. Install build dependencies

   sudo apt update
   sudo apt install build-essential cmake ninja-build extra-cmake-modules
   
2. 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
   
3. Install libraries

   sudo apt install libarchive-dev libsqlite3-dev libssl-dev
   
4. Install X11 dependencies

   sudo apt install libx11-dev libxcb-keysyms1-dev
   

Fedora/RHEL

1. Install development tools

   sudo dnf groupinstall "Development Tools"
   sudo dnf install cmake ninja-build extra-cmake-modules
   
2. 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
   
3. Install libraries

   sudo dnf install libarchive-devel sqlite-devel openssl-devel
   
4. 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:

Basic Build

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

1. Install Xcode Command Line Tools

   xcode-select --install
   
2. Install Homebrew

   If not already installed:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   
3. 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.

Qt 6 (Homebrew)

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

Next Steps

Building Zeal

General build instructions and options

Dependencies

Complete list of required dependencies