This comprehensive guide covers how to obtain, build, and configure Vanilla.PDF for all supported platforms and use cases.

Installation Methods

Install with vcpkg (Recommended)

The fastest way to get started is using vcpkg:

vcpkg install vanillapdf

After installation point CMake at your vcpkg instance:

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake
cmake --build build

Benefits include fastest builds with pre-compiled binaries, feature control via vcpkg install vanillapdf[openssl,jpeg,jpeg2000], and shared binary cache across projects.

FetchContent Integration (Alternative)

For users who prefer not to introduce external tools into their build chain, use CMake's FetchContent mechanism:

cmake_minimum_required(VERSION 3.20)
project(MyApp)
 
include(FetchContent)
FetchContent_Declare(
    vanillapdf
    GIT_REPOSITORY https://github.com/vanillapdf/vanillapdf.git
    GIT_TAG        main  # or "v2.1.0" for specific release
)
FetchContent_MakeAvailable(vanillapdf)
 
# Link to your target
target_link_libraries(myapp PRIVATE vanillapdf::vanillapdf)

Note: When using FetchContent, you are responsible for managing VanillaPDF's dependencies. Install them via system package managers (apt-get install libssl-dev libjpeg-turbo8-dev on Linux, brew install openssl libjpeg-turbo on macOS) or other packaging systems like Conan.

A complete working example with cross-platform testing is available in the FetchContent integration example with automated CI validation.

Build Requirements

CMake (minimum version 3.20) Download from https://cmake.org/download/

Supported Compilers:

Windows: Visual Studio 2022 (MSVC 17.x) or Visual Studio 2026 (MSVC 18.x)
Linux: GCC 8.1+ or Clang 10+ (x64, ARM64, ARM)
macOS: AppleClang 15+ (Xcode 15)
Android: NDK toolchain (arm64-v8a, armeabi-v7a, x86, x86_64)

Build from Source

Clone and Setup

Clone the repository and initialize the bundled vcpkg submodule:

git clone https://github.com/vanillapdf/vanillapdf.git
cd vanillapdf
# fetch submodules for bundled vcpkg
git submodule sync --recursive
git submodule update --init --recursive

Available Build Presets

List the available build presets:

cmake --list-presets

Available configure presets:
 
  "windows-x86-msvc-17-static"
  "windows-x64-msvc-17-static"
  "windows-x86-msvc-17"
  "windows-x64-msvc-17"
  "windows-x86-msvc-17-static-md"
  "windows-x64-msvc-17-static-md"
  "windows-x86-msvc-18-static"
  "windows-x64-msvc-18-static"
  "windows-x86-msvc-18"
  "windows-x64-msvc-18"
  "windows-x86-msvc-18-static-md"
  "windows-x64-msvc-18-static-md"
  "default"
  "linux-x64-gcc"
  "linux-arm64-gcc"
  "linux-x64-clang"
  "linux-arm64-clang"
  "linux-x64-musl"
  "linux-arm64-musl"
  "linux-arm-musl"
  "macos-x64"
  "macos-arm64"
  "android-arm64"
  "android-armv7"
  "android-x86"
  "android-x86_64"

Common presets include:

windows-x64-msvc-17 / windows-x86-msvc-17 - Windows with Visual Studio 2022 (dynamic CRT)
windows-x64-msvc-17-static / windows-x86-msvc-17-static - Windows with Visual Studio 2022 (static CRT)
windows-x64-msvc-17-static-md / windows-x86-msvc-17-static-md - Windows with Visual Studio 2022 (static libs, dynamic CRT)
windows-x64-msvc-18 / windows-x86-msvc-18 - Windows with Visual Studio 2026 (dynamic CRT)
windows-x64-msvc-18-static / windows-x86-msvc-18-static - Windows with Visual Studio 2026 (static CRT)
windows-x64-msvc-18-static-md / windows-x86-msvc-18-static-md - Windows with Visual Studio 2026 (static libs, dynamic CRT)
linux-x64-gcc / linux-arm64-gcc - Linux with GCC
linux-x64-clang / linux-arm64-clang - Linux with Clang
macos-x64 / macos-arm64 - macOS builds

Platform-Specific Builds

Building on Windows

Choose a preset matching your toolchain:

cmake --preset windows-x64-msvc-17
cmake --build --preset windows-x64-msvc-17
ctest --preset windows-x64-msvc-17

Windows Build Notes:**

Uses Visual Studio 2022 (msvc-17) or Visual Studio 2026 (msvc-18) generator
CRT linking depends on preset: -static variants use static CRT (VANILLAPDF_USE_STATIC_CRT=ON)
Uses optimized vcpkg triplets (e.g., x64-windows-static-md for static libs + dynamic CRT)

Building on Linux

cmake --preset linux-x64-gcc
cmake --build --preset linux-x64-gcc
ctest --preset linux-x64-gcc

For external dependencies** (optional, faster builds):

sudo apt-get install libssl-dev libjpeg-turbo8-dev zlib1g-dev libopenjp2-7-dev
cmake --preset linux-x64-gcc -DVANILLAPDF_EXTERNAL_OPENSSL=ON \
  -DVANILLAPDF_EXTERNAL_JPEG=ON -DVANILLAPDF_EXTERNAL_OPENJPEG=ON \
  -DVANILLAPDF_EXTERNAL_ZLIB=ON

Building on macOS

cmake --preset macos-arm64
cmake --build --preset macos-arm64
ctest --preset macos-arm64

For external dependencies** (optional, faster builds):

brew install openssl@3 jpeg-turbo zlib openjpeg
cmake --preset macos-arm64 -DVANILLAPDF_EXTERNAL_OPENSSL=ON \
  -DVANILLAPDF_EXTERNAL_JPEG=ON -DVANILLAPDF_EXTERNAL_OPENJPEG=ON \
  -DVANILLAPDF_EXTERNAL_ZLIB=ON

Dependency Management

Vanilla.PDF uses vcpkg for automatic dependency management. Dependencies are handled automatically - no manual installation required.

Automatic Dependencies:**

OpenSSL (encryption and digital signatures)
libjpeg-turbo (JPEG image support)
OpenJPEG (JPEG2000 support)
zlib (compression)
spdlog (logging)
nlohmann-json (configuration)

Using your own vcpkg instance

You may manage vcpkg yourself and install the required packages manually:

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg install openssl libjpeg-turbo

Configure Vanilla.PDF with the vcpkg toolchain:

cmake -S . -B build/vcpkg \
  -DCMAKE_TOOLCHAIN_FILE=</path/to/vcpkg>/scripts/buildsystems/vcpkg.cmake
cmake --build build/vcpkg

Using system dependencies

If dependencies are managed externally (e.g., by system packages, Conan, or a parent project's vcpkg), disable internal vcpkg entirely:

cmake -B build -DVANILLAPDF_INTERNAL_VCPKG=OFF

cmake --build build

Alternatively, if you want to use internal vcpkg but override specific libraries to come from your package manager, enable the matching VANILLAPDF_EXTERNAL_* options:

cmake -B build \
  -DVANILLAPDF_EXTERNAL_OPENSSL=ON \
  -DVANILLAPDF_EXTERNAL_JPEG=ON
cmake --build build

Options exist for OpenSSL, libjpeg-turbo, openjpeg, zlib, spdlog, nlohmann-json, GTest and Google Benchmark. When VANILLAPDF_EXTERNAL_* options are set, the corresponding packages will not be installed by vcpkg and CMake will search for them on your system instead.

Build Configuration

Feature Enable/Disable Options

-DVANILLAPDF_ENABLE_ENCRYPTION=ON/OFF - PDF encryption/decryption support (default: ON)
-DVANILLAPDF_ENABLE_JPEG=ON/OFF - JPEG image support (default: ON)
-DVANILLAPDF_ENABLE_JPEG2000=ON/OFF - JPEG2000 support (default: ON)

Build Configuration Options

-DVANILLAPDF_INTERNAL_VCPKG=ON/OFF - Enable internal vcpkg dependency management (default: ON)
-DVANILLAPDF_ENABLE_PACKAGING=ON/OFF - Enable packaging features like CPack (auto-detected)
-DVANILLAPDF_ENABLE_TESTS=ON/OFF - Build and run test scenarios (default: ON)
-DVANILLAPDF_ENABLE_BENCHMARK=ON/OFF - Include benchmarking project (default: ON)
-DVANILLAPDF_USE_STATIC_CRT=ON/OFF - Use static MSVC runtime (/MT) instead of dynamic (/MD) (default: OFF)
-DBUILD_SHARED_LIBS=ON/OFF - Build vanillapdf as a shared library (default: ON)

Development Options

-DVANILLAPDF_ENABLE_COVERAGE=ON - Enable code coverage instrumentation (GCC/Clang only)
-DVANILLAPDF_FORCE_32_BIT=ON - Force 32-bit output binary regardless of architecture
-DVANILLAPDF_ENABLE_STACK_SANITIZER=ON - Enable address sanitizer for memory safety testing

External Dependency Options

-DVANILLAPDF_EXTERNAL_OPENSSL=ON/OFF - Use system OpenSSL instead of vcpkg (default: OFF)
-DVANILLAPDF_EXTERNAL_JPEG=ON/OFF - Use system libjpeg instead of vcpkg (default: OFF)
-DVANILLAPDF_EXTERNAL_OPENJPEG=ON/OFF - Use system OpenJPEG instead of vcpkg (default: OFF)
-DVANILLAPDF_EXTERNAL_ZLIB=ON/OFF - Use system zlib instead of vcpkg (default: OFF)
-DVANILLAPDF_EXTERNAL_SPDLOG=ON/OFF - Use system spdlog instead of vcpkg (default: OFF)
-DVANILLAPDF_EXTERNAL_NLOHMANN_JSON=ON/OFF - Use system nlohmann-json instead of vcpkg (default: OFF)

Running Tests

After building, run the test suite:

ctest --preset <your-preset> --output-on-failure

Test Categories:**

Unit tests: Core functionality validation
Integration tests: End-to-end scenarios
Benchmarks: Performance testing

Troubleshooting

Common Issues:**

vcpkg bootstrap fails:*

git submodule sync --recursive

git submodule update --init --recursive

Build configuration fails:*

rm -rf build/

cmake --preset <your-preset>

Platform-specific dependency issues:*

Linux: Install system packages: sudo apt-get install libssl-dev libjpeg-turbo8-dev zlib1g-dev libopenjp2-7-dev
macOS: Install via Homebrew: brew install openssl@3 jpeg-turbo zlib openjpeg
Windows: Use vcpkg presets or ensure Visual Studio 2022 or 2026 is properly installed

OpenSSL and FIPS Configuration

Vanilla.PDF is compatible with FIPS-enabled and policy-restricted OpenSSL configurations commonly found on RHEL-based distributions (Rocky Linux, Fedora, AlmaLinux, RHEL). The library uses OpenSSL's PKCS#7 padding for AES encryption and loads the OpenSSL legacy provider at startup to support the full range of PDF encryption standards.

Crypto Policy Configuration

The PDF specification requires algorithms that some OpenSSL crypto policies consider legacy: MD5 for encryption key derivation, RC4 for older encrypted documents, and SHA-1 for some digital signatures. On RHEL-based distributions, the DEFAULT crypto policy may restrict these algorithms.

If encrypted PDF operations fail with crypto errors, enable the legacy algorithms via the system crypto policy:

sudo update-crypto-policies --set LEGACY

Weak Algorithm Control

For digital signature verification, the SignatureVerificationSettingsHandle API provides fine-grained control over whether weak algorithms (MD5, SHA-1, RSA < 2048 bits) are accepted, without requiring system-wide policy changes:

SignatureVerificationSettings_SetAllowWeakAlgorithmsFlag(settings, VANILLAPDF_RV_TRUE);

VANILLAPDF_RV_TRUE

const boolean_type VANILLAPDF_RV_TRUE

Represents the boolean true value.

Building packages

Instructions for creating Debian or Homebrew packages are provided in the packaging guide.

Table of Contents