pdf/command.MD

# 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
```