Merge branch 'dev' of https://gitea.maskantech.in/gitea_admin/pdf into azeem
This commit is contained in:
azeeee05
+85
-199
@@ -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/`<br>`gateway/` | PDFium abstraction layers, Rule R2 compliance, Python bindings, FastAPI gateway |
|
||||
| **Dev 2 — Graphics & Render** | Frontend React viewer and browser WebAssembly layers | `frontend/`<br>`wasm/` | Rendering facade, Emscripten build pipeline, annotation tools, React UI components |
|
||||
| **Dev 3 — Fonts & Text** | Text shaping, font embedding, and subsetting | `engine/src/fonts/`<br>`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`<br>*(Setup Python env in `gateway/`)* | `powershell scripts/bootstrap.ps1`<br>*(Setup Node in `frontend/`)* | `powershell scripts/bootstrap.ps1`<br>*(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 <version>
|
||||
./emsdk activate <version>
|
||||
./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).*
|
||||
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user