From 876c13c089fa6287d1f7b5c19312faef308613cb Mon Sep 17 00:00:00 2001 From: Furqan-14 Date: Tue, 26 May 2026 16:21:51 +0530 Subject: [PATCH] docs: simplify developer command reference guide --- command.MD | 274 ++++++++++++----------------------------------------- 1 file changed, 61 insertions(+), 213 deletions(-) diff --git a/command.MD b/command.MD index dad5e70..2202774 100644 --- a/command.MD +++ b/command.MD @@ -1,239 +1,87 @@ -# PDF Engine — Developer Command Reference +# Developer Command Reference + +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. --- -## ⚠️ 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** +## 🛠️ Dev 1 — C++ Core Engine Developer +Use these when writing C++ code (`engine/`), modifying PDFium layers, or changing binding structures. +### 1. Build C++ Engine & Python Bindings +Run this after changing C++ source code to update the local binaries and the Python extension: ```powershell -cmd /c '"C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\VC\Auxiliary\Build\vcvars64.bat" && 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 ``` -**Option B — Load MSVC into your current PowerShell window** - +### 3. Check PDFium API Boundary +Verifies no raw `FPDF_*` calls exist outside the `engine/src/parser/` abstraction layer (Rule R2): ```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.` - ---- - -## One-Time Setup (new machine only) - -```powershell -pwsh scripts/bootstrap.ps1 -``` - -```sh -./scripts/bootstrap.sh +powershell -ExecutionPolicy Bypass -File scripts/check_pdfium_boundary.ps1 ``` --- -## Component 1 — C++ Engine - -### 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 3 — Backend API Developer (Python / FastAPI) +Use these when writing FastAPI routes, managing Python services, or testing endpoint integrations. +### 1. Environment Setup (One-Time) +Run this once to create the virtual environment and install dependencies: ```powershell 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 .. +``` + +### 2. Start Dev Server +Launches the FastAPI gateway locally on port `8000` (reloads automatically on file save): +```powershell +powershell -ExecutionPolicy Bypass -File scripts/start_gateway.ps1 +``` + +### 3. Run Gateway Integration Tests +Runs all pytest integration tests checking route responses and document modifications: +```powershell +powershell -ExecutionPolicy Bypass -File scripts/test_gateway.ps1 ``` --- -## Component 3 — Frontend (React / TypeScript) +## ⚛️ Dev 2 — Frontend Developer (React / WASM) +Use these when building the React UI, annotation toolbar, and client-side WASM engine components. +### 1. Project Setup (One-Time) +Run once to install Node dependencies: ```powershell 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: +```powershell +powershell -ExecutionPolicy Bypass -File scripts/build_wasm.ps1 +``` + +### 3. Start Frontend Dev Server +Launches the local Vite web server: +```powershell +cd frontend npm run dev +``` + +### 4. Build for Production +Validates TypeScript and generates static build files for deployment: +```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 -``` - -```powershell -cd gateway -python -m pip install -e ".[dev]" -python -m pytest -``` - -```powershell -cd frontend -npm install -npm run dev -``` - -```powershell -cmake --preset wasm -cmake --build --preset wasm -node wasm/hello.test.mjs -``` - -```powershell -pwsh scripts/check_pdfium_boundary.ps1 ```