diff --git a/command.MD b/command.MD index dad5e70..c879b12 100644 --- a/command.MD +++ b/command.MD @@ -1,239 +1,125 @@ -# PDF Engine β€” Developer Command Reference +# πŸ› οΈ PDF Engine β€” Developer Command Cheat Sheet + +This document serves as the single source of truth for commands across our developer roles. --- -## ⚠️ Windows β€” Activate MSVC Before Anything Else +## πŸ—ΊοΈ Developer Matrix & Focus Areas -Run this once per terminal session before any `cmake` command: - -**Option A β€” Open a new PowerShell with MSVC loaded** - -```powershell -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** - -```powershell -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.` +| Role | Focus Area | Code Paths | Primary Responsibilities | +| :--- | :--- | :--- | :--- | +| **Dev 1 β€” Parser & SDK** | Core PDF parser, C++ wrappers, and FastAPI integration | `engine/src/parser/`
`gateway/` | PDFium abstraction layers, Rule R2 compliance, Python bindings, FastAPI gateway | +| **Dev 2 β€” Graphics & Render** | Frontend React viewer and browser WebAssembly layers | `frontend/`
`wasm/` | Rendering facade, Emscripten build pipeline, annotation tools, React UI components | +| **Dev 3 β€” Fonts & Text** | Text shaping, font embedding, and subsetting | `engine/src/fonts/`
`engine/src/text/` | FreeType & HarfBuzz wrappers, font subsetting, text extraction layers | --- -## One-Time Setup (new machine only) +## ⚑ Quick Reference Command Matrix -```powershell -pwsh scripts/bootstrap.ps1 -``` - -```sh -./scripts/bootstrap.sh -``` +| Task / Goal | Dev 1: Parser & SDK | Dev 2: Graphics & Render | Dev 3: Fonts & Text | +| :--- | :--- | :--- | :--- | +| **1. One-Time Setup** | `powershell scripts/bootstrap.ps1`
*(Setup Python env in `gateway/`)* | `powershell scripts/bootstrap.ps1`
*(Setup Node in `frontend/`)* | `powershell scripts/bootstrap.ps1`
*(Setup Python env in `gateway/`)* | +| **2. Build C++ Engine** | `powershell scripts/build_cpp.ps1` | `powershell scripts/build_wasm.ps1` *(WASM)* | `powershell scripts/build_cpp.ps1` | +| **3. Run Unit Tests** | `powershell scripts/test_cpp.ps1` | `node wasm/pdfengine.test.mjs` | `powershell scripts/test_cpp.ps1 -R "Font\|Text"` | +| **4. Run Gateway/UI Tests**| `powershell scripts/test_gateway.ps1` | β€” | `powershell scripts/test_gateway.ps1` | +| **5. Start Local Server** | `powershell scripts/start_gateway.ps1` | `cd frontend; npm run dev` | β€” | +| **6. Aggregator/CI Check** | `powershell scripts/test_phase0.ps1` | `powershell scripts/test_phase0.ps1` | `powershell scripts/test_phase0.ps1` | --- -## Component 1 β€” C++ Engine +## πŸ› οΈ Setup & Execution Workflows -### Configure - -Run on first setup, after adding `.cpp` files, or after changing `CMakeLists.txt`. - -```powershell -cmake --preset windows-debug -``` - -### Build - -Run after changing any C++ source file. - -```powershell -cmake --build --preset windows-debug -``` - -### Test - -```powershell -ctest --preset windows-debug -``` - -Expected output: `100% tests passed` - -### Fresh / Clean Rebuild - -Use when you see cache errors or strange Ninja errors. - -```powershell -cmake --preset windows-debug --fresh -cmake --build --preset windows-debug -``` - -### Rule R2 Boundary Check - -Verifies no raw `FPDF_*` calls exist outside `engine/src/parser/`. - -```powershell -pwsh scripts/check_pdfium_boundary.ps1 -``` - ---- - -## Component 2 β€” Gateway (FastAPI / Python) +### πŸ’» Dev 1 β€” Parser & SDK Workflow +#### A. Setup Python Gateway ```powershell +powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1 cd gateway -python -m pip install -e ".[dev]" -python -m ruff check . -python -m ruff format --check . -python -m pytest +python -m venv .venv +.venv\Scripts\Activate.ps1 +pip install -e ".[dev]" +cd .. +``` + +#### B. Build & Local Verification +```powershell +powershell -ExecutionPolicy Bypass -File scripts/build_cpp.ps1 +powershell -ExecutionPolicy Bypass -File scripts/test_cpp.ps1 +powershell -ExecutionPolicy Bypass -File scripts/check_pdfium_boundary.ps1 +``` + +#### C. Gateway Integration & Dev Loop +```powershell +powershell -ExecutionPolicy Bypass -File scripts/test_gateway.ps1 +powershell -ExecutionPolicy Bypass -File scripts/start_gateway.ps1 ``` --- -## Component 3 β€” Frontend (React / TypeScript) +### βš›οΈ Dev 2 β€” Graphics & Render Workflow +#### A. Setup Frontend UI ```powershell +powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1 cd frontend npm install +cd .. +``` + +#### B. WASM Engine Compilation +```powershell +powershell -ExecutionPolicy Bypass -File scripts/build_wasm.ps1 +``` + +#### C. Frontend Execution & Production Build +To launch the Vite web server for visual UI prototyping: +```powershell +cd frontend npm run dev +``` + +To compile production bundles: +```powershell +cd frontend npm run build -npm run lint ``` --- -## Component 4 β€” WASM (Emscripten) - -Activate Emscripten first (one-time install): - -```powershell -Get-Content wasm/emsdk.pinned -./emsdk install -./emsdk activate -./emsdk_env.ps1 -``` - -Build and test: - -```powershell -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): - -```powershell -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): - -```powershell -pip install clang-format==22.1.5 -``` - -Check formatting: - -```powershell -Get-ChildItem -Recurse engine -Include *.cpp,*.cc,*.h,*.hpp | - ForEach-Object { clang-format --dry-run --Werror $_.FullName } -``` - -Auto-format in place: - -```powershell -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. - -```powershell -pwsh scripts/test_phase0.ps1 -Preset windows-debug -pwsh scripts/test_phase0.ps1 -Preset windows-debug -SkipWasm -``` - -```sh -./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 - powershell -ExecutionPolicy Bypass -File scripts/build_cpp.ps1 - ``` -* **Run C++ Core Unit Tests**: - ```powershell - powershell -ExecutionPolicy Bypass -File scripts/test_cpp.ps1 - ``` -* **Run Gateway pytest Integration Tests**: - ```powershell - powershell -ExecutionPolicy Bypass -File scripts/test_gateway.ps1 - ``` -* **Start the Local FastAPI Dev Server**: - ```powershell - powershell -ExecutionPolicy Bypass -File scripts/start_gateway.ps1 - ``` - ---- - -## Quick Reference - - -```powershell -cmake --preset windows-debug -cmake --build --preset windows-debug -ctest --preset windows-debug -``` +### πŸ”€ Dev 3 β€” Fonts & Text Workflow +#### A. Setup Environment ```powershell +powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1 cd gateway -python -m pip install -e ".[dev]" -python -m pytest +python -m venv .venv +.venv\Scripts\Activate.ps1 +pip install -e ".[dev]" +cd .. ``` +#### B. Development & Test Loop ```powershell -cd frontend -npm install -npm run dev +powershell -ExecutionPolicy Bypass -File scripts/build_cpp.ps1 +powershell -ExecutionPolicy Bypass -File scripts/test_cpp.ps1 -R "Font|Text" +powershell -ExecutionPolicy Bypass -File scripts/test_gateway.ps1 ``` +--- + +## 🏁 Environment Verification (Aggregator Check) +Before pushing any branches, all developers should run the full suite verification: ```powershell -cmake --preset wasm -cmake --build --preset wasm -node wasm/hello.test.mjs +powershell -ExecutionPolicy Bypass -File scripts/test_phase0.ps1 -Preset win-local-pdfium ``` -```powershell -pwsh scripts/check_pdfium_boundary.ps1 -``` +--- + +## πŸ”§ Developer Utilities +Below is a list of other helper scripts in the repository: +* **Populate Test Corpus**: + ```powershell + powershell -ExecutionPolicy Bypass -File scripts/copy_test_corpus.ps1 + ``` + *(Copies standard testing PDFs from local PDFium source/checkout directories to the workspace `corpus/` folder).* + diff --git a/scripts/build_wasm.ps1 b/scripts/build_wasm.ps1 new file mode 100644 index 0000000..fa174ff --- /dev/null +++ b/scripts/build_wasm.ps1 @@ -0,0 +1,80 @@ +#requires -Version 5.1 +# Build C++ Engine to WebAssembly (WASM) and deploy to Frontend public folder. + +$ErrorActionPreference = 'Stop' + +$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path +$ProjectRoot = (Resolve-Path (Join-Path $ScriptDir "..")).Path + +# --- Resolve EMSDK --- +$emsdk = $env:EMSDK +if (-not $emsdk) { + $candidates = @( + "C:\Users\$env:USERNAME\emsdk", + "C:\emsdk", + "C:\src\emsdk", + "C:\Users\furqa\emsdk" + ) + foreach ($cand in $candidates) { + if (Test-Path $cand) { + $emsdk = $cand + break + } + } + + if (-not $emsdk) { + Write-Error "EMSDK environment variable was not set and could not be found at standard locations. Please set the EMSDK environment variable." + exit 1 + } + $env:EMSDK = $emsdk + Write-Host "EMSDK defaulted to: $emsdk" -ForegroundColor Yellow +} + +# Load EMSDK environment variables in PowerShell context +$envScript = Join-Path $emsdk "emsdk_env.ps1" +if (-not (Test-Path $envScript)) { + Write-Error "Could not find emsdk_env.ps1 at $emsdk" + exit 1 +} + +Write-Host "Loading Emscripten environment variables..." -ForegroundColor Cyan +. $envScript + +# Configure WASM preset +Write-Host "Configuring CMake WASM preset..." -ForegroundColor Cyan +cmake --preset wasm +if ($LASTEXITCODE -ne 0) { + Write-Error "CMake configuration failed." + exit $LASTEXITCODE +} + +# Build WASM preset +Write-Host "Building WASM targets..." -ForegroundColor Cyan +cmake --build --preset wasm +if ($LASTEXITCODE -ne 0) { + Write-Error "WASM build failed." + exit $LASTEXITCODE +} + +# Run WASM smoke tests +Write-Host "Running WASM smoke tests..." -ForegroundColor Cyan +node wasm/pdfengine.test.mjs +if ($LASTEXITCODE -ne 0) { + Write-Error "WASM smoke tests failed." + exit $LASTEXITCODE +} + +# Copy built targets to frontend public folder +$WasmBinDir = Join-Path $ProjectRoot "out\build\wasm\bin" +$FrontendPublic = Join-Path $ProjectRoot "frontend\public" + +if (-not (Test-Path $FrontendPublic)) { + Write-Warning "Frontend public folder not found at $FrontendPublic. Skipping copy." +} else { + Write-Host "Copying WASM build artifacts to frontend public folder..." -ForegroundColor Cyan + Copy-Item -Path (Join-Path $WasmBinDir "pdfengine.mjs") -Destination (Join-Path $FrontendPublic "pdfengine.mjs") -Force + Copy-Item -Path (Join-Path $WasmBinDir "pdfengine.wasm") -Destination (Join-Path $FrontendPublic "pdfengine.wasm") -Force + Write-Host "Successfully copied WASM files to $FrontendPublic" -ForegroundColor Green +} + +Write-Host "Success! WASM built and deployed." -ForegroundColor Green diff --git a/scripts/test_cpp.ps1 b/scripts/test_cpp.ps1 index 7187912..f9dd3c4 100644 --- a/scripts/test_cpp.ps1 +++ b/scripts/test_cpp.ps1 @@ -11,5 +11,5 @@ if (Test-Path $vcvars) { } Write-Host "Running C++ core unit tests..." -ForegroundColor Cyan -ctest --preset win-local-pdfium +ctest --preset win-local-pdfium $args exit $LASTEXITCODE diff --git a/scripts/test_gateway.ps1 b/scripts/test_gateway.ps1 index 2bd5926..1598f1f 100644 --- a/scripts/test_gateway.ps1 +++ b/scripts/test_gateway.ps1 @@ -4,7 +4,7 @@ $gatewayDir = Join-Path (Split-Path -Parent $scriptDir) "gateway" Write-Host "Running FastAPI Gateway integration tests..." -ForegroundColor Cyan Push-Location $gatewayDir try { - & .venv\Scripts\pytest + & .venv\Scripts\pytest $args } finally { Pop-Location }