fix: updated build scripts
This commit is contained in:
Furqan-14
+79
-41
@@ -1,39 +1,39 @@
|
||||
# Developer Command Reference
|
||||
# 🛠️ PDF Engine — Developer Command Cheat Sheet
|
||||
|
||||
This guide lists the exact commands each developer needs for their day-to-day workflow. All compiler environments, presets, and path configs are handled automatically under the hood by the scripts.
|
||||
This document serves as the single source of truth for commands across our developer roles.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Dev 1 — C++ Core Engine Developer
|
||||
Use these when writing C++ code (`engine/`), modifying PDFium layers, or changing binding structures.
|
||||
## 🗺️ Developer Matrix & Focus Areas
|
||||
|
||||
### 1. Build C++ Engine & Python Bindings
|
||||
Run this after changing C++ source code to update the local binaries and the Python extension:
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File scripts/build_cpp.ps1
|
||||
```
|
||||
*(On first execution, this will automatically generate your local `CMakeUserPresets.json` file).*
|
||||
|
||||
### 2. Run C++ Unit Tests
|
||||
Runs all C++ document, rendering, and lifecycle unit tests:
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File scripts/test_cpp.ps1
|
||||
```
|
||||
|
||||
### 3. Check PDFium API Boundary
|
||||
Verifies no raw `FPDF_*` calls exist outside the `engine/src/parser/` abstraction layer (Rule R2):
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File scripts/check_pdfium_boundary.ps1
|
||||
```
|
||||
| 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 |
|
||||
|
||||
---
|
||||
|
||||
## 🐍 Dev 3 — Backend API Developer (Python / FastAPI)
|
||||
Use these when writing FastAPI routes, managing Python services, or testing endpoint integrations.
|
||||
## ⚡ Quick Reference Command Matrix
|
||||
|
||||
### 1. Environment Setup (One-Time)
|
||||
Run this once to create the virtual environment and install dependencies:
|
||||
| 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` |
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Setup & Execution Workflows
|
||||
|
||||
### 💻 Dev 1 — Parser & SDK Workflow
|
||||
|
||||
#### A. Setup Python Gateway
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1
|
||||
cd gateway
|
||||
python -m venv .venv
|
||||
.venv\Scripts\Activate.ps1
|
||||
@@ -41,47 +41,85 @@ pip install -e ".[dev]"
|
||||
cd ..
|
||||
```
|
||||
|
||||
### 2. Start Dev Server
|
||||
Launches the FastAPI gateway locally on port `8000` (reloads automatically on file save):
|
||||
#### B. Build & Local Verification
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File scripts/start_gateway.ps1
|
||||
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
|
||||
```
|
||||
|
||||
### 3. Run Gateway Integration Tests
|
||||
Runs all pytest integration tests checking route responses and document modifications:
|
||||
#### C. Gateway Integration & Dev Loop
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File scripts/test_gateway.ps1
|
||||
powershell -ExecutionPolicy Bypass -File scripts/start_gateway.ps1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚛️ Dev 2 — Frontend Developer (React / WASM)
|
||||
Use these when building the React UI, annotation toolbar, and client-side WASM engine components.
|
||||
### ⚛️ Dev 2 — Graphics & Render Workflow
|
||||
|
||||
### 1. Project Setup (One-Time)
|
||||
Run once to install Node dependencies:
|
||||
#### A. Setup Frontend UI
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1
|
||||
cd frontend
|
||||
npm install
|
||||
cd ..
|
||||
```
|
||||
|
||||
### 2. Build WebAssembly Module
|
||||
Compiles the C++ engine to WebAssembly, runs smoke tests, and deploys `.wasm` and `.mjs` assets directly to `frontend/public/` for local loading:
|
||||
#### B. WASM Engine Compilation
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File scripts/build_wasm.ps1
|
||||
```
|
||||
|
||||
### 3. Start Frontend Dev Server
|
||||
Launches the local Vite web server:
|
||||
#### C. Frontend Execution & Production Build
|
||||
To launch the Vite web server for visual UI prototyping:
|
||||
```powershell
|
||||
cd frontend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### 4. Build for Production
|
||||
Validates TypeScript and generates static build files for deployment:
|
||||
To compile production bundles:
|
||||
```powershell
|
||||
cd frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 🔤 Dev 3 — Fonts & Text Workflow
|
||||
|
||||
#### A. Setup Environment
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1
|
||||
cd gateway
|
||||
python -m venv .venv
|
||||
.venv\Scripts\Activate.ps1
|
||||
pip install -e ".[dev]"
|
||||
cd ..
|
||||
```
|
||||
|
||||
#### B. Development & Test Loop
|
||||
```powershell
|
||||
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
|
||||
powershell -ExecutionPolicy Bypass -File scripts/test_phase0.ps1 -Preset win-local-pdfium
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 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