mirror of
https://github.com/RevLayDust/RLD-UVR-Opt.git
synced 2026-11-20 13:07:58 +09:00
130 lines
6.0 KiB
Markdown
130 lines
6.0 KiB
Markdown
# Installer Architecture & Development
|
|
|
|
This guide documents the architecture, lifecycle phases, and testing practices for the **RLD UVR-Opt** PowerShell installer pipeline located in [install/](../../install/).
|
|
|
|
---
|
|
|
|
## 1. Five-Phase Pipeline Architecture
|
|
|
|
The installer replaces monolithic batch files with a deterministic, modular pipeline implemented in **Windows PowerShell 5.1**:
|
|
|
|
```text
|
|
[Input Flags / Prompts]
|
|
│
|
|
▼
|
|
Phase 1: Detect (lib/Detect.ps1) - Read-only hardware & package inspection
|
|
│
|
|
▼
|
|
Phase 2: Plan (lib/Plan.ps1) - Pure action mapping (Keep, Install, Replace, Remove)
|
|
│
|
|
▼
|
|
Phase 3: Verify (lib/Verify.ps1) - Read-only gate; checks invariants & -DryRun
|
|
│
|
|
▼
|
|
Phase 4: Install (lib/Install.ps1) - Safe mutation with snapshot rollback & uv execution
|
|
│
|
|
▼
|
|
Phase 5: Validate (lib/Validate.ps1) - Live runtime validation with in-memory ONNX model
|
|
│
|
|
▼
|
|
Post: Record (lib/Record.ps1) - Atomic persistence to install_record.json
|
|
```
|
|
|
|
### Module Responsibilities:
|
|
|
|
| File | Phase | Responsibility |
|
|
| :--- | :--- | :--- |
|
|
| [**`Config.ps1`**](../../install/lib/Config.ps1) | Config | **Single Source of Truth**: Package pins (PyTorch, ONNX Runtime, plugins), URLs, driver threshold ($\ge 570$), CC threshold ($\ge 8.0$), and disk space ($5\text{ GB}$). |
|
|
| [**`Common.ps1`**](../../install/lib/Common.ps1) | Common | Shared logging (`Write-InstallerLog`), deadlock-free native process runner (`Invoke-Native`), file I/O, and interactive prompts. |
|
|
| [**`Detect.ps1`**](../../install/lib/Detect.ps1) | Phase 1 | Inspects OS bitness, GPU controllers via CIM, `nvidia-smi`, Python venv, and `.dist-info` package state (without importing torch). |
|
|
| [**`Plan.ps1`**](../../install/lib/Plan.ps1) | Phase 2 | Pure function `New-InstallPlan`: maps current state to desired target profile (A, B, C) and marks destructive operations. |
|
|
| [**`Verify.ps1`**](../../install/lib/Verify.ps1) | Phase 3 | Verifies plan invariants: architecture suitability, minimum driver version, disk space, and active process locks. Handles `-DryRun`. |
|
|
| [**`Install.ps1`**](../../install/lib/Install.ps1) | Phase 4 | Captures rollback snapshot, cleans variant conflicts, installs wheels and filtered requirements via Astral `uv`. |
|
|
| [**`Validate.ps1`**](../../install/lib/Validate.ps1) | Phase 5 | Deep runtime check inside venv: verifies GPU tensor allocation and creates live ONNX Runtime sessions using embedded IR 8 test models. |
|
|
| [**`Record.ps1`**](../../install/lib/Record.ps1) | Record | Atomically writes [install_record.json](../../install/install_record.json) while delegating base schema to `install_record.py write`. |
|
|
|
|
---
|
|
|
|
## 2. Running Non-Destructive Dry Runs
|
|
|
|
Contributors can simulate any installation or migration scenario on their local machine without touching the filesystem or installing packages:
|
|
|
|
```powershell
|
|
# Simulate Option A (CUDA)
|
|
powershell -NoProfile -ExecutionPolicy Bypass -File .\install\Install-UVR.ps1 -Mode A -DryRun
|
|
|
|
# Simulate Option B (TensorRT-RTX)
|
|
powershell -NoProfile -ExecutionPolicy Bypass -File .\install\Install-UVR.ps1 -Mode B -DryRun
|
|
|
|
# Simulate Option C (CPU)
|
|
powershell -NoProfile -ExecutionPolicy Bypass -File .\install\Install-UVR.ps1 -Mode C -DryRun
|
|
```
|
|
|
|
A `-DryRun` prints the generated plan table and verification status, then exits with code 0 without performing changes.
|
|
|
|
---
|
|
|
|
## 3. Single Source of Truth Rule
|
|
|
|
All version pins, index URLs, and hardware thresholds **must reside exclusively** in [install/lib/Config.ps1](../../install/lib/Config.ps1). Never hardcode package versions or driver versions inside `Detect.ps1`, `Plan.ps1`, or `Install.ps1`.
|
|
|
|
### Example: Adding or Updating a Dependency Pin
|
|
To bump PyTorch or ONNX Runtime, update the `Get-InstallerConfig` hashtable in [install/lib/Config.ps1](../../install/lib/Config.ps1):
|
|
|
|
```powershell
|
|
Torch = [PSCustomObject]@{
|
|
Version = '2.11.0'
|
|
CudaIndexUrl = 'https://download.pytorch.org/whl/cu128'
|
|
CpuIndexUrl = 'https://download.pytorch.org/whl/cpu'
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Writing Pester Tests for Installer Scenarios
|
|
|
|
Installer logic is thoroughly covered by Pester test fixtures located in [install/tests/](../../install/tests/).
|
|
|
|
### Adding a New Planning Scenario
|
|
To test plan generation for a new package state, add an `It` block to [install/tests/Plan.Tests.ps1](../../install/tests/Plan.Tests.ps1) using `New-TestFacts`:
|
|
|
|
```powershell
|
|
It 'Scenario: Venv with custom package condition' {
|
|
$facts = New-TestFacts -TorchVariant 'CUDA' -TorchVersion '2.11.0' -HasOrtGpu $true
|
|
$plan = New-InstallPlan -Facts $facts -Choice 'B'
|
|
|
|
$plan.Profile | Should Be 'B'
|
|
$plan.Actions | Where-Object { $_.Component -eq 'TRT-RTX-Plugin' } | Should Not BeNullOrEmpty
|
|
}
|
|
```
|
|
|
|
### Adding a New Verification Gate
|
|
To test a hardware gate or safety block, add an `It` block to [install/tests/Verify.Tests.ps1](../../install/tests/Verify.Tests.ps1):
|
|
|
|
```powershell
|
|
It 'Scenario: System with insufficient memory' {
|
|
$facts = New-TestFacts -FreeDiskSpaceBytes (2GB) # Less than 5GB required
|
|
$plan = New-InstallPlan -Facts $facts -Choice 'A'
|
|
$verdict = Test-InstallPlan -Facts $facts -Choice 'A' -Plan $plan
|
|
|
|
$verdict.Status | Should Be 'Blocked'
|
|
}
|
|
```
|
|
|
|
Execute the test suite to verify:
|
|
```powershell
|
|
powershell -NoProfile -ExecutionPolicy Bypass -Command "Invoke-Pester -Path ./install/tests"
|
|
```
|
|
|
|
---
|
|
|
|
## 5. The `install_record.py` Contract
|
|
|
|
To maintain full backward compatibility with legacy tooling and the GUI:
|
|
1. `install_record.py inspect-stack`:
|
|
- Prints `TORCH_VARIANT|TORCH_VERSION|ORT_VARIANT|ORT_VERSION` used by external inspectors.
|
|
2. `install_record.py write`:
|
|
- Writes the base schema fields (`schema_version`, `timestamp_utc`, `selected_option`, `install_mode`).
|
|
3. **Additive Extensions**:
|
|
- [install/lib/Record.ps1](../../install/lib/Record.ps1) injects additional telemetry fields (`effective_option`, `detected`, `validation`) atomically without breaking base consumers.
|