pdf/third_party/pdfium

PDFium — built from source

PDFium is the parser + base-rendering core of the engine (Rule R1). It is not a vcpkg package; Google ships it only as source built with their own toolchain (depot_tools + GN + Ninja). The timeline flags this as "the single biggest Day-1 risk — budget a full day for depot_tools quirks."

What the build scripts do

build_pdfium.ps1 (Windows) and build_pdfium.sh (Linux/macOS) automate:

1. Read the pinned revision from pdfium.pinned (refuses to run if it is still the placeholder — Rule: never track rolling HEAD).
2. Clone depot_tools under the build root and run its Windows bootstrap (fetches bundled git + python via CIPD).
3. gclient config + gclient sync the PDFium tree into <build root>/checkout/.
4. Check out the exact pinned commit and re-sync its DEPS.
5. Write args.gn for a static, standalone, monolithic, embed-friendly build:
   • is_component_build = false — one static lib, not many DLLs
   • pdf_is_standalone = true
   • pdf_enable_v8 = false, pdf_enable_xfa = false — no JS / XFA in v1
   • pdf_use_skia = false — we drive Skia ourselves later
   • use_custom_libcxx = false — link the system C++ runtime so PDFium is ABI-compatible with the rest of the engine (critical for embedding)
   • pdf_use_partition_alloc = false
6. gn gen + ninja -C out/Release pdfium.
7. Copy public/*.h → install/include/ and the static lib → install/lib/.

cmake/pdfium.cmake then turns install/ into the pdfium::pdfium imported target. Build the engine with -DPDFENGINE_WITH_PDFIUM=ON to link it.

The build root — paths with spaces

depot_tools, GN and Ninja do not support a space anywhere in their own path. By default the scripts build under this directory (third_party/pdfium/), which is fine when the repo lives on a space-free path.

If the repo path contains a space (e.g. OneDrive\...\PDF Editor\...), the scripts hard-error and you must point the build root somewhere space-free:

# Windows
$env:PDFIUM_BUILD_ROOT = 'C:\pdfium-build'
pwsh third_party\pdfium\build_pdfium.ps1

# Linux / macOS
PDFIUM_BUILD_ROOT=/tmp/pdfium-build ./third_party/pdfium/build_pdfium.sh

depot_tools/ and checkout/ then live under the build root; the finished install/ is always written into third_party/pdfium/install/ (git-ignored) so cmake/pdfium.cmake finds it in the same place regardless.

Pinning the revision

pdfium.pinned holds the pinned commit SHA. It is currently pinned to a specific main-branch commit. To re-pin (a deliberate, scheduled action — the risk register calls for quarterly rebases):

1. Pick a commit from https://pdfium.googlesource.com/pdfium/+log/main (or the tip of a recent chromium/NNNN release branch).
2. Update PDFIUM_COMMIT= in pdfium.pinned and commit it.
3. Re-run the build script.

Usage

Prerequisites: Git, Python 3, and a C++ toolchain (Windows: Visual Studio 2022+ with the "Desktop development with C++" workload).

# Windows — set PDFIUM_BUILD_ROOT first if the repo path has a space (see above)
pwsh third_party\pdfium\build_pdfium.ps1

# Linux / macOS
./third_party/pdfium/build_pdfium.sh

Expect the first run to take a long time — the gclient sync alone pulls several GB, and the compile is lengthy. depot_tools/, checkout/, and install/ are all git-ignored.

Troubleshooting

• 'C:\...\PDF' is not recognized / GN or Ninja path errors — a space in the build-root path. Set PDFIUM_BUILD_ROOT to a space-free location.
• gclient sync aborts with "uncommitted changes" — git's core.autocrlf rewrote a dependency checkout. The scripts already inject core.autocrlf=false per-process; if you bypass them, set it yourself.
• depot_tools git/python not found — depot_tools was not bootstrapped. The scripts run bootstrap\win_tools.bat; do not set DEPOT_TOOLS_UPDATE=0, which suppresses that bootstrap.