85 lines
4.3 KiB
Markdown
85 lines
4.3 KiB
Markdown
|
# PDF Engine
|
||
|
|
|
||
|
|
Cross-platform, high-performance, license-safe PDF rendering and editing SDK.
|
||
|
|
A single C++ core (PDFium + Skia + FreeType + HarfBuzz) drives native desktop,
|
||
|
|
server-side, and browser (WASM) rendering, with a FastAPI gateway and a
|
||
|
|
React + TypeScript viewer on top.
|
||
|
|
|
||
|
|
> **Status:** Phase 0 — Infrastructure. The stack must compile clean on
|
||
|
|
> Linux, macOS, and Windows before any feature work begins. See
|
||
|
|
> [`docs/phase0.md`](docs/phase0.md).
|
||
|
|
|
||
|
|
## Repository layout
|
||
|
|
|
||
|
|
| Path | Purpose |
|
||
|
|
|------------------|----------------------------------------------------------------------|
|
||
|
|
| `engine/` | C++23 PDF SDK core. The only code that links PDFium/Skia/FreeType. |
|
||
|
|
| `engine/src/parser/` | **Only** place raw `FPDF_*` PDFium APIs may be used (Rule R2). |
|
||
|
|
| `bindings/` | Language bindings — C ABI (.NET/ctypes) and pybind11 (Python). |
|
||
|
|
| `gateway/` | FastAPI service: auth, metadata, storage, job queue. *(placeholder)* |
|
||
|
|
| `frontend/` | React + TypeScript layered PDF viewer. *(placeholder)* |
|
||
|
|
| `wasm/` | Emscripten build of the engine for in-browser rendering. *(placeholder)* |
|
||
|
|
| `third_party/` | Vendored dependencies built from source (PDFium via depot_tools/GN). |
|
||
|
|
| `cmake/` | Reusable CMake modules (`pdfium.cmake`, warnings, sanitizers). |
|
||
|
|
| `corpus/` | Test PDF corpus for rendering/regression gates. |
|
||
|
|
| `scripts/` | Bootstrap, lint, and developer tooling. |
|
||
|
|
| `docs/` | Engineering docs and phase plans. |
|
||
|
|
|
||
|
|
## Prerequisites
|
||
|
|
|
||
|
|
- **CMake** >= 3.25 and **Ninja**
|
||
|
|
- A **C++23** compiler: MSVC 19.36+ (VS 2022 17.6+ **or** VS 2026 / Build
|
||
|
|
Tools 2026 — IDE not required), GCC 13+, or Clang 16+
|
||
|
|
- **vcpkg** (set `VCPKG_ROOT`; `scripts/bootstrap` can install it). On
|
||
|
|
Windows, `setx VCPKG_ROOT ...` does not affect already-open shells —
|
||
|
|
set `$env:VCPKG_ROOT` in that shell or open a new terminal.
|
||
|
|
- **clang-format 22.1.5** (CI is pinned to this exact version) —
|
||
|
|
`pip install clang-format==22.1.5` on Windows
|
||
|
|
- **Python 3.11+** and **Node 20+** (for gateway/frontend, later phases)
|
||
|
|
- For building PDFium from source: **depot_tools** (handled by
|
||
|
|
`third_party/pdfium/build_pdfium.*` — do **not** add it to your
|
||
|
|
persistent `PATH`; its `ninja.bat` shadows real Ninja and breaks the
|
||
|
|
engine build, see [`docs/phase0.md`](docs/phase0.md))
|
||
|
|
|
||
|
|
## Quick start
|
||
|
|
|
||
|
|
```sh
|
||
|
|
# 1. One-time setup: checks tools, installs vcpkg, pins the dependency baseline.
|
||
|
|
# Windows: pwsh scripts/bootstrap.ps1
|
||
|
|
# Unix: ./scripts/bootstrap.sh
|
||
|
|
|
||
|
|
# 2. Build PDFium from source (slow, one-time — see third_party/pdfium/README.md).
|
||
|
|
# Windows: pwsh third_party/pdfium/build_pdfium.ps1
|
||
|
|
# Unix: ./third_party/pdfium/build_pdfium.sh
|
||
|
|
|
||
|
|
# 3. Configure + build + test via CMake presets.
|
||
|
|
cmake --preset windows-debug # or linux-debug / macos-debug
|
||
|
|
cmake --build --preset windows-debug
|
||
|
|
ctest --preset windows-debug
|
||
|
|
```
|
||
|
|
|
||
|
|
> **Windows + PDFium:** the engine-linked-against-PDFium build is
|
||
|
|
> RelWithDebInfo + static CRT (not the Debug preset). Drop the
|
||
|
|
> `win-local-pdfium` preset into a local `CMakeUserPresets.json` and use
|
||
|
|
> that — see [`docs/phase0.md`](docs/phase0.md#windows--pdfium) for the
|
||
|
|
> exact JSON and the reason (CRT alignment).
|
||
|
|
|
||
|
|
> **OneDrive note:** this checkout lives in a OneDrive-synced folder whose
|
||
|
|
> path also contains a space. On **Windows** this is not optional — put
|
||
|
|
> your build directory outside OneDrive on a space-free path
|
||
|
|
> (e.g. `C:\Users\<you>\pdfeng-build\...`), or vcpkg/meson and depot_tools
|
||
|
|
> will fail. On Linux/macOS it is just a sync nuisance — exclude `out/`
|
||
|
|
> and `vcpkg/` from sync, or pause sync while building. See
|
||
|
|
> [`docs/phase0.md`](docs/phase0.md#onedrive-warning) for details.
|
||
|
|
|
||
|
|
## Engineering rules (non-negotiable)
|
||
|
|
|
||
|
|
- **R1** PDFium stays the parser core — no custom parser.
|
||
|
|
- **R2** Only `engine/src/parser/` may call raw `FPDF_*` APIs. CI enforces this.
|
||
|
|
- **R3** No custom graphics interpreter in Phase 1/2 — use PDFium's renderer.
|
||
|
|
- **R4** Saving is incremental (append-only xref) by default.
|
||
|
|
- **R5** WASM never blocks shipping — server-side render is the fallback.
|
||
|
|
|
||
|
|
Dependency versions are **pinned** (vcpkg baseline + a pinned PDFium ref).
|
||
|
|
Never track rolling `HEAD`.
|