Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
d54bd6473f | ||
|
|
a5b07d22ae | ||
|
|
3d17326460 |
@@ -167,7 +167,7 @@ jobs:
|
||||
python3 ci/gen-badges.py --tests "$PASS" \
|
||||
--coverage "${{ steps.cov.outputs.pct }}" \
|
||||
--bench-coverage "${{ steps.benchcov.outputs.pct }}" \
|
||||
--bench-delta "$BENCH_DELTA"
|
||||
--bench-delta "$BENCH_DELTA" --clippy clean
|
||||
|
||||
- name: Publish measured badges
|
||||
env:
|
||||
|
||||
Generated
+1
@@ -75,6 +75,7 @@ dependencies = [
|
||||
"alkane-artifacts",
|
||||
"alkane-core",
|
||||
"sha2",
|
||||
"tempfile",
|
||||
"thiserror",
|
||||
]
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# alkane-toolkit
|
||||
# Alkane Toolkit
|
||||
|
||||
[](https://gitea.bluefla.re/blueflare/alkane-toolkit/actions)
|
||||

|
||||
@@ -10,118 +10,61 @@
|
||||

|
||||

|
||||
|
||||
The CI badge shows the last completed attempt for this branch while newer
|
||||
runs are queued. Badge SVGs are stored in a private, machine-maintained branch.
|
||||
The code-quality letter requires warnings-denied Clippy and measured test plus
|
||||
UI self-test line coverage: A at 90%, B at 80%, C at 70%, D at 60%, and F
|
||||
below 60%. A missing coverage measurement displays pending.
|
||||
The benchmark delta compares an earlier commit only when its CPU class
|
||||
matches the current dedicated runner; otherwise it establishes a new
|
||||
baseline. Main CI runs microbenchmarks serially to avoid test contention.
|
||||
Desktop fleet discovery and monitoring for ASIC miners. The Rust GUI uses
|
||||
wxWidgets through a patched [wx-rs bridge](thirdparty/wx-rs). Firmware
|
||||
installation is under development.
|
||||
|
||||
A cross-platform desktop toolkit for discovering, monitoring, and re-flashing
|
||||
ASIC miners. It scans a fleet over the network, shows live health and hashrate
|
||||
in a sortable table. The install path is under development for **stock** and
|
||||
**alkaneOS** firmware on boards running stock, VNish/AnthillOS, Braiins OS+,
|
||||
LuxOS, ePIC, HiveOn, BixBit, WardenOS).
|
||||
|
||||
The core and UI are pure Rust; the native window is wxWidgets driven through a
|
||||
vendored, patched [wx-rs](thirdparty/wx-rs) bridge, so there is no Electron,
|
||||
no web view, and a single self-contained binary per platform.
|
||||
|
||||
## What it does
|
||||
|
||||
- **Discover** a fleet by CIDR or IP range and identify each miner's make,
|
||||
model, control board, and firmware (via a vendored [asic-rs](vendor/asic-rs)).
|
||||
- **Monitor** hashrate vs. expected, per-board health, chip temperatures, fans,
|
||||
PSU state, and pool workers, with an Excel-style filter and drag-reorderable
|
||||
columns.
|
||||
- **Operate** miners from a right-click menu: flash the locate light, pause /
|
||||
resume, restart, set a power or hashrate target, select a firmware profile
|
||||
(LuxOS/VNish presets), configure pools, set the timezone, and change the
|
||||
password -- each action offered only when every selected miner supports it.
|
||||
- **Install firmware**: push stock or aftermarket images, or revert an
|
||||
aftermarket miner to stock, behind a typed confirmation.
|
||||
|
||||
Discovery and telemetry are read-only and safe to run against any fleet; every
|
||||
mutating action is capability-gated and, where destructive, confirmed.
|
||||
|
||||
## Build and run (Debian/Ubuntu)
|
||||
## Run locally
|
||||
|
||||
```sh
|
||||
scripts/build-wx-linux.sh # once: builds the vendored wxWidgets 3.3.3 into ~/.cache
|
||||
scripts/build-gui-linux.sh # cargo build --release -p alkane-gui
|
||||
~/.cache/alkane-tk-target/release/alkane-toolkit
|
||||
scripts/build-wx-linux.sh
|
||||
scripts/build-gui-linux.sh
|
||||
ALKANE_FAKE_SCAN=1 ~/.cache/alkane-tk-target/release/alkane-toolkit
|
||||
```
|
||||
|
||||
Runtime needs GTK 3: `sudo apt install libgtk-3-0`. To explore the UI with no
|
||||
hardware, run the offline demo fleet:
|
||||
The first command builds wxWidgets 3.3.3 once. Linux runtime needs GTK 3
|
||||
(`libgtk-3-0` on Debian/Ubuntu). The fake scan uses offline fixtures and
|
||||
does not contact hardware. Windows and macOS use their respective
|
||||
`scripts/build-gui-*.sh` scripts and platform toolchains.
|
||||
|
||||
```sh
|
||||
ALKANE_FAKE_SCAN=1 alkane-toolkit
|
||||
```
|
||||
## Current scope
|
||||
|
||||
Windows and macOS share all GUI code; only the C++ bridge and wx build differ
|
||||
(`scripts/build-gui-windows.sh` needs an msys2 toolchain, `-macos.sh` needs a
|
||||
Mac).
|
||||
- Discover miners by CIDR or IP range with vendored
|
||||
[asic-rs](vendor/asic-rs), and show model, firmware, health, hashrate,
|
||||
temperatures, fans, PSU, and pool workers.
|
||||
- Filter, sort, and reorder columns in the desktop table.
|
||||
- Probe discovery, telemetry, presets, and write actions with the
|
||||
`miner_probe` CLI. Run it without arguments for the verb list.
|
||||
|
||||
## Command-line probe
|
||||
|
||||
`miner_probe` is a headless companion for hardware checks that should not go
|
||||
through the window event loop -- discovery, telemetry, and each write action:
|
||||
|
||||
```sh
|
||||
miner_probe scan 10.0.0.0/24 # discover + telemetry (TSV)
|
||||
miner_probe presets 10.0.0.5 # list a firmware's selectable profiles
|
||||
miner_probe setpreset 10.0.0.5 540MHz
|
||||
```
|
||||
|
||||
Run `miner_probe` with no arguments for the full verb list.
|
||||
The installer and some operator actions remain roadmap items; see the
|
||||
[implementation plan](docs/IMPLEMENTATION-PLAN.md) and
|
||||
[firmware parity matrix](docs/aftermarket-parity-roadmap.md). A listed
|
||||
firmware or board is not an install claim. Discovery is read-only.
|
||||
|
||||
## Development
|
||||
|
||||
```sh
|
||||
export WX_RS_WXCONFIG="$HOME/.cache/wx-3.3.3-linux/bin/wx-config"
|
||||
export CARGO_TARGET_DIR="$HOME/.cache/alkane-tk-target" # keep the target tree off the source share
|
||||
|
||||
cargo test -p alkane-gui # unit tests
|
||||
cargo test -p alkane-gui --release -- --ignored bench_ # microbenchmarks
|
||||
cargo clippy -p alkane-gui --no-deps --bins -- -D warnings # lint gate
|
||||
xvfb-run -a env ALKANE_SELFTEST=1 \
|
||||
"$CARGO_TARGET_DIR/release/alkane-toolkit" # headless UI self-test
|
||||
ci/coverage.sh --summary-only # coverage (tests + self-test)
|
||||
export CARGO_TARGET_DIR="$HOME/.cache/alkane-tk-target"
|
||||
cargo test -p alkane-gui --offline
|
||||
cargo clippy -p alkane-gui --no-deps --bins -- -D warnings
|
||||
scripts/ui-selftest.sh
|
||||
ci/coverage.sh --summary-only
|
||||
```
|
||||
|
||||
CI mirrors these: `verify.yml` runs lint, tests, benchmarks, the self-test, and
|
||||
a dependency audit on development branches. `release.yml` runs the full gate
|
||||
on every `main` push and cuts an `X.Y.Z` release when the change warrants it.
|
||||
`next.yml` builds release candidates with little testing and publishes `-rc`
|
||||
releases. Dependencies are vendored under `vendor/`, so builds never touch the
|
||||
network.
|
||||
Keep build output off the source share. `main` runs the full CI gate and
|
||||
publishes qualifying releases; `next` builds `-rc` candidates. Badges
|
||||
report host tests and benchmarks, not installation support. Benchmark
|
||||
comparisons require the same CPU class. The code quality letter reports the
|
||||
Clippy gate; the separate coverage badge reports exercised lines.
|
||||
|
||||
## Architecture
|
||||
## Firmware safety
|
||||
|
||||
- `crates/alkane-gui` -- the application: scan engine, data model, wxWidgets UI,
|
||||
and the `miner_probe` CLI (the other `crates/alkane-*` are early scaffolding).
|
||||
- `vendor/asic-rs` -- the miner-discovery and control library, vendored and
|
||||
extended through numbered patches under `thirdparty/asic-rs/patches`.
|
||||
- `thirdparty/wx-rs` -- the patched wxWidgets bridge (see `docs/adr/0002`,
|
||||
`0003`).
|
||||
|
||||
See [`docs/IMPLEMENTATION-PLAN.md`](docs/IMPLEMENTATION-PLAN.md) for the roadmap
|
||||
and [`docs/aftermarket-parity-roadmap.md`](docs/aftermarket-parity-roadmap.md)
|
||||
for the firmware config/scan parity work.
|
||||
|
||||
## Firmware safety rules
|
||||
|
||||
Encoded in code, from alkane-sdk `docs/install-methods.md`:
|
||||
|
||||
1. Never write the bootloader or secure region.
|
||||
2. Verify on a channel the installer does not control.
|
||||
3. Reboot is root-only; a dropped SSH connection can still be success.
|
||||
4. A packer is per board; never reuse one across boards.
|
||||
5. Boot-switch handling is an explicit, verified step.
|
||||
The [SDK install rules](https://gitea.bluefla.re/blueflare/alkane-sdk/src/branch/main/docs/install-methods.md) require
|
||||
serial and recovery checks for risky writes. Installation must never write
|
||||
the bootloader or secure region, must verify over an independent channel,
|
||||
and must use the packer and boot-switch procedure for the exact board.
|
||||
|
||||
## License
|
||||
|
||||
Licensed under the [MIT license](LICENSE).
|
||||
[MIT](LICENSE). Vendored dependencies keep their own terms.
|
||||
|
||||
+13
-12
@@ -2,10 +2,11 @@
|
||||
# Measure line coverage from BOTH the unit tests AND the headless UI self-test.
|
||||
#
|
||||
# The self-test (ALKANE_SELFTEST=1) builds the real wxWidgets table, renders every
|
||||
# fixture through the real widgets, and checks each cell against the model -- it
|
||||
# exercises most of ui.rs. Because it runs as a separate binary invocation, a plain
|
||||
# `cargo llvm-cov` (which only runs the #[test]s) never counts it, so ui.rs shows
|
||||
# ~4% even though it is integration-tested. This combines both runs' coverage.
|
||||
# fixture through the real widgets, and checks each cell against the model.
|
||||
# It covers the fixture-rendering path, while interactive event handlers need
|
||||
# separate tests. Because it runs as a separate binary invocation, a plain
|
||||
# `cargo llvm-cov` (which only runs the #[test]s) never counts it. This
|
||||
# combines both runs' coverage.
|
||||
#
|
||||
# Usage: ci/coverage.sh [extra `cargo llvm-cov report` args, e.g. --summary-only]
|
||||
set -euo pipefail
|
||||
@@ -16,8 +17,12 @@ export WX_RS_WXCONFIG="${WX_RS_WXCONFIG:-$HOME/.cache/wx-3.3.3-linux/bin/wx-conf
|
||||
# default; override with CARGO_LLVM_COV_FLAGS if you need something else.
|
||||
read -ra CARGO_FLAGS <<<"${CARGO_LLVM_COV_FLAGS:---offline}"
|
||||
|
||||
# A display for the self-test's real widgets.
|
||||
need_xvfb() { command -v xvfb-run >/dev/null 2>&1; }
|
||||
# A display is required for the self-test; skipping it would publish an
|
||||
# incomplete coverage number as if the measured test set had run.
|
||||
if ! command -v xvfb-run >/dev/null 2>&1; then
|
||||
echo "coverage.sh: xvfb-run is required for the UI self-test" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
cargo llvm-cov clean --workspace
|
||||
|
||||
@@ -27,12 +32,8 @@ cargo llvm-cov --no-report "${CARGO_FLAGS[@]}" \
|
||||
-p alkane-artifacts -p alkane-flash -p alkane-cli
|
||||
|
||||
# 2. Headless UI self-test, under the same instrumentation, its coverage appended.
|
||||
if need_xvfb; then
|
||||
xvfb-run -a env GDK_BACKEND=x11 ALKANE_SELFTEST=1 \
|
||||
cargo llvm-cov run --no-report "${CARGO_FLAGS[@]}" --bin alkane-toolkit
|
||||
else
|
||||
echo "coverage.sh: xvfb-run not found; skipping the self-test run (unit tests only)" >&2
|
||||
fi
|
||||
xvfb-run -a env GDK_BACKEND=x11 ALKANE_SELFTEST=1 \
|
||||
cargo llvm-cov run --no-report "${CARGO_FLAGS[@]}" --bin alkane-toolkit
|
||||
|
||||
# 3. Merged report, our source only (vendored asic-rs + the patched wx-rs bridge
|
||||
# are out of scope).
|
||||
|
||||
+5
-10
@@ -131,15 +131,10 @@ def cov_color(pct: float) -> str:
|
||||
return "red"
|
||||
|
||||
|
||||
def quality_grade(clippy: str, coverage: float | None) -> str:
|
||||
if clippy != "clean":
|
||||
return "F"
|
||||
if coverage is None:
|
||||
def quality_grade(clippy: str | None) -> str:
|
||||
if clippy is None:
|
||||
return "pending"
|
||||
for minimum, grade in ((90, "A"), (80, "B"), (70, "C"), (60, "D")):
|
||||
if coverage >= minimum:
|
||||
return grade
|
||||
return "F"
|
||||
return "A" if clippy == "clean" else "F"
|
||||
|
||||
|
||||
def human(n: int) -> str:
|
||||
@@ -170,7 +165,7 @@ def main() -> int:
|
||||
# percentage string (e.g. "-3.2"), or "NEW"/"" when there is no baseline yet
|
||||
# (round 19 #1). Takes precedence over --bench for the bench badge.
|
||||
ap.add_argument("--bench-delta", default=None)
|
||||
ap.add_argument("--clippy", default="clean")
|
||||
ap.add_argument("--clippy", choices=("clean", "failed"))
|
||||
args = ap.parse_args()
|
||||
for value in (args.coverage, args.bench_coverage):
|
||||
if value is not None and (not math.isfinite(value) or not 0 <= value <= 100):
|
||||
@@ -191,7 +186,7 @@ def main() -> int:
|
||||
write("loc", "lines of code", human(loc), loc_color(loc))
|
||||
write("license", "license", lic, "blue")
|
||||
write("dependencies", "dependencies", str(deps), "blue")
|
||||
grade = quality_grade(args.clippy, args.coverage)
|
||||
grade = quality_grade(args.clippy)
|
||||
write("quality", "code quality", grade,
|
||||
{"A": "brightgreen", "B": "yellowgreen", "C": "yellow",
|
||||
"D": "orange", "F": "red", "pending": "lightgrey"}[grade])
|
||||
|
||||
@@ -9,3 +9,4 @@ alkane-core = { path = "../alkane-core" }
|
||||
alkane-artifacts = { path = "../alkane-artifacts" }
|
||||
sha2.workspace = true
|
||||
thiserror.workspace = true
|
||||
tempfile = "3"
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
use alkane_artifacts::VerifiedArtifact;
|
||||
use sha2::{Digest, Sha256};
|
||||
use std::io::{Read, Seek, SeekFrom};
|
||||
use std::io::{Read, Seek, SeekFrom, Write};
|
||||
use thiserror::Error;
|
||||
|
||||
pub struct PartitionSpec {
|
||||
@@ -90,6 +90,34 @@ fn digest_bytes(hex: &str) -> Result<[u8; 32], FlashError> {
|
||||
Ok(result)
|
||||
}
|
||||
|
||||
fn stage_verified_artifact(
|
||||
artifact: &mut VerifiedArtifact,
|
||||
size: u64,
|
||||
expected: [u8; 32],
|
||||
) -> Result<std::fs::File, FlashError> {
|
||||
let mut staged = tempfile::tempfile().map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
|
||||
artifact
|
||||
.reader()
|
||||
.seek(SeekFrom::Start(0))
|
||||
.map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
|
||||
let mut source = DigestReader {
|
||||
inner: artifact.reader(),
|
||||
remaining: size,
|
||||
digest: Sha256::new(),
|
||||
};
|
||||
std::io::copy(&mut source, &mut staged).map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
|
||||
if source.remaining != 0 || <[u8; 32]>::from(source.digest.finalize()) != expected {
|
||||
return Err(FlashError::ArtifactChanged);
|
||||
}
|
||||
staged
|
||||
.flush()
|
||||
.map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
|
||||
staged
|
||||
.seek(SeekFrom::Start(0))
|
||||
.map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
|
||||
Ok(staged)
|
||||
}
|
||||
|
||||
struct DigestReader<'a> {
|
||||
inner: &'a mut dyn Read,
|
||||
remaining: u64,
|
||||
@@ -145,6 +173,10 @@ pub fn write_verified<W: Writer, R: IndependentReadback>(
|
||||
artifact
|
||||
.revalidate()
|
||||
.map_err(|_| FlashError::ArtifactChanged)?;
|
||||
let expected = digest_bytes(&artifact.record().sha256)?;
|
||||
// The source path may change while backup or transport I/O runs. Copy and
|
||||
// verify it before any device write; the anonymous file is removed on drop.
|
||||
let mut staged = stage_verified_artifact(artifact, size, expected)?;
|
||||
let backup = writer
|
||||
.backup(partition)
|
||||
.map_err(|e| FlashError::Write(e.to_string()))?;
|
||||
@@ -154,13 +186,8 @@ pub fn write_verified<W: Writer, R: IndependentReadback>(
|
||||
{
|
||||
return Err(FlashError::BackupIncomplete);
|
||||
}
|
||||
let expected = digest_bytes(&artifact.record().sha256)?;
|
||||
artifact
|
||||
.reader()
|
||||
.seek(SeekFrom::Start(0))
|
||||
.map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
|
||||
let mut stream = DigestReader {
|
||||
inner: artifact.reader(),
|
||||
inner: &mut staged,
|
||||
remaining: size,
|
||||
digest: Sha256::new(),
|
||||
};
|
||||
@@ -203,6 +230,7 @@ mod tests {
|
||||
max_read: Option<u64>,
|
||||
writes: usize,
|
||||
contents: Vec<u8>,
|
||||
mutate_source_on_write: Option<PathBuf>,
|
||||
}
|
||||
|
||||
impl Writer for MockWriter {
|
||||
@@ -231,6 +259,9 @@ mod tests {
|
||||
_: u64,
|
||||
) -> Result<(), Self::Error> {
|
||||
self.writes += 1;
|
||||
if let Some(path) = &self.mutate_source_on_write {
|
||||
std::fs::write(path, b"PK\x03\x04changed").map_err(|_| "mutation failed")?;
|
||||
}
|
||||
if let Some(limit) = self.max_read {
|
||||
image
|
||||
.take(limit)
|
||||
@@ -285,6 +316,7 @@ mod tests {
|
||||
max_read: None,
|
||||
writes: 0,
|
||||
contents: Vec::new(),
|
||||
mutate_source_on_write: None,
|
||||
}
|
||||
}
|
||||
|
||||
@@ -395,4 +427,20 @@ mod tests {
|
||||
assert_eq!(writer.writes, 1);
|
||||
std::fs::remove_file(path).unwrap();
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn writes_verified_snapshot_when_source_changes_during_transport() {
|
||||
let (path, mut image) = artifact("mutated-during-write");
|
||||
let mut writer = writer();
|
||||
writer.mutate_source_on_write = Some(path.clone());
|
||||
let mut readback = MockReadback {
|
||||
channel: "serial",
|
||||
digest: digest_bytes(SHA).unwrap(),
|
||||
};
|
||||
let receipt = write_verified(&partition(), &mut image, &mut writer, &mut readback).unwrap();
|
||||
assert_eq!(receipt.image_sha256, digest_bytes(SHA).unwrap());
|
||||
assert_eq!(writer.contents, IMAGE);
|
||||
assert_eq!(std::fs::read(&path).unwrap(), b"PK\x03\x04changed");
|
||||
std::fs::remove_file(path).unwrap();
|
||||
}
|
||||
}
|
||||
|
||||
+6
-6
@@ -1,10 +1,10 @@
|
||||
# UI Spec — primary view
|
||||
# Primary view
|
||||
|
||||
Source: operator description, 2026-09-15. Status: ACCEPTED (v1 scope).
|
||||
|
||||
## Header (above the table)
|
||||
## Header
|
||||
|
||||
- **KPI block, top left — 6 KPIs:**
|
||||
- **KPI block, top left: 6 KPIs:**
|
||||
1. Total miners
|
||||
2. Hashing
|
||||
3. Slow
|
||||
@@ -31,7 +31,7 @@ Source: operator description, 2026-09-15. Status: ACCEPTED (v1 scope).
|
||||
4. Cooling (fan)
|
||||
5. Firmware
|
||||
6. Pool worker account name
|
||||
7. …then the remaining statistics in registry order.
|
||||
7. Remaining statistics in registry order.
|
||||
|
||||
## Data sources
|
||||
|
||||
@@ -45,10 +45,10 @@ Source: operator description, 2026-09-15. Status: ACCEPTED (v1 scope).
|
||||
ships with the board registry; missing band = excluded from Slow, counted
|
||||
in Hashing).
|
||||
|
||||
## Implementation notes
|
||||
## Implementation
|
||||
|
||||
- wxWidgets: the view is a `wxDataViewListCtrl`/`wxDataViewCtrl` (virtual
|
||||
list — thousands of rows without materializing cells), checkbox column +
|
||||
list for thousands of rows without materializing cells), checkbox column +
|
||||
IP column fixed via attribute/serializer, drag reorder via `wxReorderable`
|
||||
column events, sort via column header click events mapped to the model.
|
||||
- Filter panel: per-column distinct-value checklist with text search,
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# ADR 0001: Recipes as data, interpreted by one engine
|
||||
# ADR 0001: Recipe engine
|
||||
|
||||
Status: ACCEPTED
|
||||
Date: 2026-09-14
|
||||
|
||||
@@ -1,41 +1,27 @@
|
||||
# ADR 0002: GUI bindings — wxWidgets shell in C++ + Rust core, spike to revisit
|
||||
# ADR 0002: GUI bindings
|
||||
|
||||
Status: RESOLVED 2026-09-15 - the operator chose Option B (pure Rust via
|
||||
wx-rs) with vendoring (ADR-0003). wx-rs 0.2.0 was extended via the patch
|
||||
queue: Linux/GTK3 wx-config build path plus the widget bridge (panel,
|
||||
sizers, static text, button, text ctrl, checkbox, checklistbox, dialog,
|
||||
data view list ctrl, timer). The app ships this way; no C++ shell.
|
||||
Date: 2026-09-14
|
||||
Resolved: 2026-09-15
|
||||
|
||||
## Context
|
||||
|
||||
The toolkit must present a native cross-platform GUI (wxWidgets chosen).
|
||||
Rust bindings to wxWidgets checked on crates.io 2026-09-14:
|
||||
|
||||
- `wxRust` 0.0.1-alpha — unmaintained since 2022.
|
||||
- `wx-rs` 0.2.0 (2023, self-contained) — ~6k downloads, no 1.0.
|
||||
|
||||
Betting the GUI on alpha bindings risks weeks of binding-gap debugging
|
||||
(paste-heavy widgets, worker threads + event loops, GTK/WinCocoa quirks).
|
||||
The toolkit needs a native wxWidgets GUI. At the time of evaluation,
|
||||
`wxRust` 0.0.1-alpha had seen no maintenance since 2022, and `wx-rs`
|
||||
0.2.0 lacked widgets needed for the Toolkit.
|
||||
|
||||
## Decision
|
||||
|
||||
Default: **thin C++17 wxWidgets shell (`gui/`) + Rust core exposed over a
|
||||
small stable C ABI** (cdylib from `alkane-core`, header generated with
|
||||
cbindgen). The shell holds frames, lists, the install wizard, and event
|
||||
glue only — no business logic, no safety logic. All invariants, engines,
|
||||
and tests live in Rust where they are testable headlessly.
|
||||
The operator chose a Rust GUI through a vendored, patched `wx-rs` 0.2.0.
|
||||
The patch queue adds the Linux/GTK3 build path and bindings for panels,
|
||||
sizers, controls, dialogs, data views, timers, and event dispatch. The
|
||||
application uses this bridge; it has no separate C++ shell.
|
||||
|
||||
Gate: M0 runs a time-boxed `wx-rs` spike (window + list/tree + wizard flow
|
||||
+ worker-thread progress + cancel on Linux and Windows). If the spike is
|
||||
solid, flip to pure Rust; either way the decision is recorded before M3.
|
||||
The original proposal was a small C++17 wxWidgets shell calling a Rust
|
||||
core through a C ABI. The `wx-rs` spike met the GUI need, so that proposal
|
||||
was not adopted.
|
||||
|
||||
## Consequences
|
||||
|
||||
- The repo builds two things: a Rust workspace and a small C++ app linked
|
||||
against the core cdylib. CMake in `gui/`.
|
||||
- Core API surface stays small and event-oriented (discover, identify,
|
||||
plan, execute, cancel, progress events, log tail) — good FFI hygiene and
|
||||
a natural match for the CLI too (D4).
|
||||
- If wx-rs wins the spike, the C ABI is kept as an integration boundary for
|
||||
scripted/HIL use anyway.
|
||||
- Keep business logic and safety checks in testable Rust code.
|
||||
- Carry wx-rs changes as numbered patches under `thirdparty/wx-rs/patches`.
|
||||
- Recheck the bridge on Linux, Windows, and macOS packaging changes.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# ADR 0003: Vendoring policy — pristine upstream archives + patch queue
|
||||
# ADR 0003: Vendoring
|
||||
|
||||
Status: ACCEPTED
|
||||
Date: 2026-09-15
|
||||
@@ -42,7 +42,7 @@ thirdparty/
|
||||
|
||||
Rules:
|
||||
|
||||
1. Never edit a vendored pristine tree in place — every local change is a
|
||||
1. Never edit a vendored pristine tree in place. Every local change is a
|
||||
patch in `patches/`, applied by the build in numeric order. This makes
|
||||
an upstream update: replace pristine archive, `git apply` surviving
|
||||
patches, rebase the rest.
|
||||
|
||||
Reference in New Issue
Block a user