240 lines
4.5 KiB
Markdown
240 lines
4.5 KiB
Markdown
# PDF Engine — Developer Command Reference
|
|
|
|
---
|
|
|
|
## ⚠️ 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**
|
|
|
|
```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.`
|
|
|
|
---
|
|
|
|
## One-Time Setup (new machine only)
|
|
|
|
```powershell
|
|
pwsh scripts/bootstrap.ps1
|
|
```
|
|
|
|
```sh
|
|
./scripts/bootstrap.sh
|
|
```
|
|
|
|
---
|
|
|
|
## 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)
|
|
|
|
```powershell
|
|
cd gateway
|
|
python -m pip install -e ".[dev]"
|
|
python -m ruff check .
|
|
python -m ruff format --check .
|
|
python -m pytest
|
|
```
|
|
|
|
---
|
|
|
|
## Component 3 — Frontend (React / TypeScript)
|
|
|
|
```powershell
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
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
|
|
```
|