docs: simplify developer command reference guide
This commit is contained in:
Furqan-14
+61
-213
@@ -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 <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
|
||||
```
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user