pdf/command.MD

PDF Engine — Developer Command Reference

---

⚠️ Windows — Activate MSVC Before Anything Else

Run this once per terminal session before any cmake command:

Option A — Open a new PowerShell with MSVC loaded

cmd /c '"C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\VC\Auxiliary\Build\vcvars64.bat" && powershell'

Option B — Load MSVC into your current PowerShell window

cmd /c '"C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\VC\Auxiliary\Build\vcvars64.bat" && set' |
  Where-Object { $_ -match '=' } |
  ForEach-Object {
    $name, $value = $_ -split '=', 2
    [System.Environment]::SetEnvironmentVariable($name, $value, 'Process')
  }
$env:VCPKG_ROOT = "C:\Users\furqa\vcpkg"

If you skip this step, cmake will fail with: CMake Error: No CMAKE_CXX_COMPILER could be found.

---

One-Time Setup (new machine only)

pwsh scripts/bootstrap.ps1

./scripts/bootstrap.sh

---

Component 1 — C++ Engine

Configure

Run on first setup, after adding .cpp files, or after changing CMakeLists.txt.

cmake --preset windows-debug

Build

Run after changing any C++ source file.

cmake --build --preset windows-debug

Test

ctest --preset windows-debug

Expected output: 100% tests passed

Fresh / Clean Rebuild

Use when you see cache errors or strange Ninja errors.

cmake --preset windows-debug --fresh
cmake --build --preset windows-debug

Rule R2 Boundary Check

Verifies no raw FPDF_* calls exist outside engine/src/parser/.

pwsh scripts/check_pdfium_boundary.ps1

---

Component 2 — Gateway (FastAPI / Python)

cd gateway
python -m pip install -e ".[dev]"
python -m ruff check .
python -m ruff format --check .
python -m pytest

---

Component 3 — Frontend (React / TypeScript)

cd frontend
npm install
npm run dev
npm run build
npm run lint

---

Component 4 — WASM (Emscripten)

Activate Emscripten first (one-time install):

Get-Content wasm/emsdk.pinned
./emsdk install <version>
./emsdk activate <version>
./emsdk_env.ps1

Build and test:

cmake --preset wasm
cmake --build --preset wasm
node wasm/hello.test.mjs

Expected output:

[wasm-smoke] OK — add(2,3)=5, hello_version()=1, cwrap add(40,2)=42

Browser test (optional):

npx serve .

Open http://localhost:3000/test.html and check the browser console (F12).

---

C++ Code Style (clang-format)

Install once (CI is pinned to 22.1.5):

pip install clang-format==22.1.5

Check formatting:

Get-ChildItem -Recurse engine -Include *.cpp,*.cc,*.h,*.hpp |
  ForEach-Object { clang-format --dry-run --Werror $_.FullName }

Auto-format in place:

Get-ChildItem -Recurse engine -Include *.cpp,*.cc,*.h,*.hpp |
  ForEach-Object { clang-format -i $_.FullName }

---

Run Everything at Once

Runs all components and prints one pass/fail per component.

pwsh scripts/test_phase0.ps1 -Preset windows-debug
pwsh scripts/test_phase0.ps1 -Preset windows-debug -SkipWasm

./scripts/test_phase0.sh
SKIP_WASM=1 ./scripts/test_phase0.sh

---

Automated Convenience Scripts

We have created several PowerShell scripts in the scripts/ directory to automate setting up the MSVC compiler environments, building, running tests, and starting the FastAPI gateway server. You can run these from the project root:

• Build C++ Engine & Python Bindings:

  powershell -ExecutionPolicy Bypass -File scripts/build_cpp.ps1
  

• Run C++ Core Unit Tests:

  powershell -ExecutionPolicy Bypass -File scripts/test_cpp.ps1
  

• Run Gateway pytest Integration Tests:

  powershell -ExecutionPolicy Bypass -File scripts/test_gateway.ps1
  

• Start the Local FastAPI Dev Server:

  powershell -ExecutionPolicy Bypass -File scripts/start_gateway.ps1
  

---

Quick Reference

cmake --preset windows-debug
cmake --build --preset windows-debug
ctest --preset windows-debug

cd gateway
python -m pip install -e ".[dev]"
python -m pytest

cd frontend
npm install
npm run dev

cmake --preset wasm
cmake --build --preset wasm
node wasm/hello.test.mjs

pwsh scripts/check_pdfium_boundary.ps1