mirror of
https://github.com/azaion/admin.git
synced 2026-04-22 22:06:33 +00:00
Oleksandr Bezdieniezhnykh
79 lines
4.5 KiB
Markdown
79 lines
4.5 KiB
Markdown
# Hardware-Dependency & Execution Environment Assessment (BLOCKING)
|
||
|
||
Runs between Phase 3 and Phase 4.
|
||
|
||
Docker is the **preferred** test execution environment (reproducibility, isolation, CI parity). However, hardware-dependent projects may require local execution to exercise the real code paths. This assessment determines the right execution strategy by scanning both documentation and source code.
|
||
|
||
## Step 1 — Documentation scan
|
||
|
||
Check the following files for mentions of hardware-specific requirements:
|
||
|
||
| File | Look for |
|
||
|------|----------|
|
||
| `_docs/00_problem/restrictions.md` | Platform requirements, hardware constraints, OS-specific features |
|
||
| `_docs/01_solution/solution.md` | Engine selection logic, platform-dependent paths, hardware acceleration |
|
||
| `_docs/02_document/architecture.md` | Component diagrams showing hardware layers, engine adapters |
|
||
| `_docs/02_document/components/*/description.md` | Per-component hardware mentions |
|
||
| `TESTS_OUTPUT_DIR/environment.md` | Existing environment decisions |
|
||
|
||
## Step 2 — Code scan
|
||
|
||
Search the project source for indicators of hardware dependence. The project is **hardware-dependent** if ANY of the following are found:
|
||
|
||
| Category | Code indicators (imports, APIs, config) |
|
||
|----------|-----------------------------------------|
|
||
| GPU / CUDA | `import pycuda`, `import tensorrt`, `import pynvml`, `torch.cuda`, `nvidia-smi`, `CUDA_VISIBLE_DEVICES`, `runtime: nvidia` |
|
||
| Apple Neural Engine / CoreML | `import coremltools`, `CoreML`, `MLModel`, `ComputeUnit`, `MPS`, `sys.platform == "darwin"`, `platform.machine() == "arm64"` |
|
||
| OpenCL / Vulkan | `import pyopencl`, `clCreateContext`, vulkan headers |
|
||
| TPU / FPGA | `import tensorflow.distribute.TPUStrategy`, FPGA bitstream loaders |
|
||
| Sensors / Cameras | `import cv2.VideoCapture(0)` (device index), serial port access, GPIO, V4L2 |
|
||
| OS-specific services | Kernel modules (`modprobe`), host-level drivers, platform-gated code (`sys.platform` branches selecting different backends) |
|
||
|
||
Also check dependency files (`requirements.txt`, `setup.py`, `pyproject.toml`, `Cargo.toml`, `*.csproj`) for hardware-specific packages.
|
||
|
||
## Step 3 — Classify the project
|
||
|
||
Based on Steps 1–2, classify the project:
|
||
|
||
- **Not hardware-dependent**: no indicators found → use Docker (preferred default), skip to Step 5 "Record the decision"
|
||
- **Hardware-dependent**: one or more indicators found → proceed to Step 4
|
||
|
||
## Step 4 — Present execution environment choice
|
||
|
||
Present the findings and ask the user using Choose format:
|
||
|
||
```
|
||
══════════════════════════════════════
|
||
DECISION REQUIRED: Test execution environment
|
||
══════════════════════════════════════
|
||
Hardware dependencies detected:
|
||
- [list each indicator found, with file:line]
|
||
══════════════════════════════════════
|
||
Running in Docker means these hardware code paths
|
||
are NOT exercised — Docker uses a Linux VM where
|
||
[specific hardware, e.g. CoreML / CUDA] is unavailable.
|
||
The system would fall back to [fallback engine/path].
|
||
══════════════════════════════════════
|
||
A) Local execution only (tests the real hardware path)
|
||
B) Docker execution only (tests the fallback path)
|
||
C) Both local and Docker (tests both paths, requires
|
||
two test runs — recommended for CI with heterogeneous
|
||
runners)
|
||
══════════════════════════════════════
|
||
Recommendation: [A, B, or C] — [reason]
|
||
══════════════════════════════════════
|
||
```
|
||
|
||
## Step 5 — Record the decision
|
||
|
||
Write or update a **"Test Execution"** section in `TESTS_OUTPUT_DIR/environment.md` with:
|
||
|
||
1. **Decision**: local / docker / both
|
||
2. **Hardware dependencies found**: list with file references
|
||
3. **Execution instructions** per chosen mode:
|
||
- **Local mode**: prerequisites (OS, SDK, hardware), how to start services, how to run the test runner, environment variables
|
||
- **Docker mode**: docker-compose profile/command, required images, how results are collected
|
||
- **Both mode**: instructions for each, plus guidance on which CI runner type runs which mode
|
||
|
||
The decision is consumed by Phase 4 to choose between local `scripts/run-tests.sh` and `docker-compose.test.yml`.
|