Installation

This guide covers installing ZAP C++ on various platforms.

System Requirements

C++20 compatible compiler (GCC 10+, Clang 12+, MSVC 2019+)
CMake 3.16 or later
pkg-config (optional, for system integration)

Package Managers

macOS (Homebrew)

# Install from tap
brew tap zap-protocol/tap
brew install zap-cpp

Ubuntu/Debian (apt)

# Add ZAP repository
curl -fsSL https://pkg.zap-protocol.org/gpg | sudo gpg --dearmor -o /usr/share/keyrings/zap.gpg
echo "deb [signed-by=/usr/share/keyrings/zap.gpg] https://pkg.zap-protocol.org/apt stable main" | \
  sudo tee /etc/apt/sources.list.d/zap.list
 
# Install
sudo apt update
sudo apt install zap-cpp-dev

Arch Linux (AUR)

# Install from AUR
yay -S zap-cpp

vcpkg

// vcpkg.json
{
  "dependencies": ["zap-cpp"]
}

Or install directly:

vcpkg install zap-cpp

Conan

# conanfile.txt
[requires]
zap-cpp/1.0.0

Or install directly:

conan install zap-cpp/1.0.0@

Building from Source

The recommended way to install ZAP C++ from source:

# Clone the repository
git clone https://github.com/zap-protocol/zap-cpp.git
cd zap-cpp
 
# Create build directory
mkdir build && cd build
 
# Configure with CMake
cmake .. -DCMAKE_BUILD_TYPE=Release
 
# Build
cmake --build . -j$(nproc)
 
# Install (may require sudo)
cmake --install .

CMake Options

Option	Default	Description
`BUILD_TESTING`	ON	Build test suite
`BUILD_SHARED_LIBS`	OFF	Build shared libraries
`ZAP_LITE`	OFF	Build lite version (no RPC, reflection)
`WITH_OPENSSL`	ON	Enable TLS support via OpenSSL
`WITH_ZLIB`	ON	Enable compression support

Example: Minimal Build

cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_TESTING=OFF \
  -DZAP_LITE=ON

Docker

A Docker image with ZAP C++ pre-installed is available:

# Pull the image
docker pull ghcr.io/zap-protocol/zap-cpp:latest
 
# Run with your project mounted
docker run -it -v $(pwd):/workspace ghcr.io/zap-protocol/zap-cpp:latest
 
# Inside container
cd /workspace
zap compile -oc++ schema.zap

Verifying Installation

After installation, verify that the tools are available:

# Check compiler version
zap --version
 
# Generate a unique ID for testing
zap id
 
# Compile a test schema
echo "@0x85150b117366d14b; struct Test { value @0 :Int32; }" > test.zap
zap compile -oc++ test.zap
 
# Verify generated files
ls test.zap.h test.zap.c++

CMake Integration

Finding the Package

cmake_minimum_required(VERSION 3.16)
project(myproject CXX)
 
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
# Find ZAP C++ (ZAP)
find_package(Zap REQUIRED)
 
add_executable(myapp src/main.cpp)
target_link_libraries(myapp PRIVATE Zap::zap)

Compiling Schema Files

find_package(Zap REQUIRED)
 
# Generate C++ from schema
zap_generate_cpp(ZAP_SRCS ZAP_HDRS
  schemas/message.zap
  schemas/protocol.zap
)
 
add_executable(myapp
  src/main.cpp
  ${ZAP_SRCS}
)
 
target_include_directories(myapp PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
target_link_libraries(myapp PRIVATE Zap::zap)

FetchContent Integration

Include ZAP C++ directly in your project:

include(FetchContent)
 
FetchContent_Declare(
  zap
  GIT_REPOSITORY https://github.com/zap-protocol/zap-cpp.git
  GIT_TAG        v1.0.0
)
 
FetchContent_MakeAvailable(zap)
 
add_executable(myapp src/main.cpp)
target_link_libraries(myapp PRIVATE Zap::zap)

Troubleshooting

CMake cannot find zap

If CMake cannot find the installed library:

# Set the prefix path
cmake .. -DCMAKE_PREFIX_PATH=/usr/local
 
# Or use pkg-config
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH

Linker errors with shared libraries

Update the library path:

# Linux
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
sudo ldconfig
 
# macOS
export DYLD_LIBRARY_PATH=/usr/local/lib:$DYLD_LIBRARY_PATH

Compiler version issues

Ensure you have a C++20 compatible compiler:

# Check GCC version
g++ --version  # Should be 10+
 
# Check Clang version
clang++ --version  # Should be 12+
 
# Specify compiler for CMake
cmake .. -DCMAKE_CXX_COMPILER=g++-12

Next Steps

Learn the Schema Language
Understand Serialization

Installation

On this page