Merge pull request 'Own Pages site (manual, quality dashboard, benchmarks); remove internal notes' (#20) from repo-cleanup into main
This commit is contained in:
@@ -1,35 +0,0 @@
|
||||
name: public-benchmark-pages
|
||||
|
||||
on:
|
||||
workflow_run:
|
||||
workflows: [build-test-release]
|
||||
types: [completed]
|
||||
workflow_dispatch:
|
||||
|
||||
concurrency:
|
||||
group: alkane-toolkit-public-benchmark-pages
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
publish:
|
||||
runs-on: alkane-verify
|
||||
container:
|
||||
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:4929b2979851f1f12fb8f92ef74236ae4c2ea735a41ead94a16af416a4f0a1a5
|
||||
permissions:
|
||||
contents: read
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Install SSH client
|
||||
run: bash ci/ensure-build-deps.sh ssh
|
||||
- name: Render measured benchmark history
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
|
||||
run: python3 ci/bench_history.py render
|
||||
- name: Publish public benchmark page
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
|
||||
BENCH_PAGES_DEPLOY_KEY: ${{ secrets.BENCH_PAGES_DEPLOY_KEY }}
|
||||
run: python3 ci/publish-bench-pages.py toolkit
|
||||
- name: Clean generated page
|
||||
if: always()
|
||||
run: python3 ci/cleanup-generated.py
|
||||
@@ -0,0 +1,47 @@
|
||||
name: pages
|
||||
|
||||
# The project site, https://blueflare.gitea.bluefla.re/alkane-toolkit/ :
|
||||
# overview, user manual (docs/manual), code-quality dashboard (from the
|
||||
# quality record main CI publishes with the badges) and benchmark history.
|
||||
# Rebuilt after every main build-test-release run and published to this
|
||||
# repository's gh-pages branch.
|
||||
on:
|
||||
workflow_run:
|
||||
workflows: [build-test-release]
|
||||
types: [completed]
|
||||
workflow_dispatch:
|
||||
|
||||
concurrency:
|
||||
group: alkane-toolkit-pages
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
publish:
|
||||
runs-on: alkane-verify
|
||||
container:
|
||||
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:4929b2979851f1f12fb8f92ef74236ae4c2ea735a41ead94a16af416a4f0a1a5
|
||||
permissions:
|
||||
contents: write
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Install page tools
|
||||
run: bash ci/ensure-build-deps.sh pages
|
||||
- name: Render measured benchmark history
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
|
||||
run: python3 ci/bench_history.py render
|
||||
- name: Fetch measured quality record
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
|
||||
run: python3 ci/fetch-quality.py quality.json
|
||||
- name: Build site
|
||||
run: |
|
||||
python3 ci/build-pages.py --out site --quality quality.json \
|
||||
--bench bench-site/index.html --sha "$GITHUB_SHA"
|
||||
- name: Publish site
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
|
||||
run: python3 ci/publish-pages.py site
|
||||
- name: Clean generated site
|
||||
if: always()
|
||||
run: python3 ci/cleanup-generated.py
|
||||
@@ -271,8 +271,10 @@ jobs:
|
||||
set -euo pipefail
|
||||
rustup component add llvm-tools-preview >/dev/null 2>&1 || true
|
||||
[ "$(cargo llvm-cov --version)" = 'cargo-llvm-cov 0.8.7' ]
|
||||
PCT=$(bash ci/coverage.sh --summary-only \
|
||||
| awk '/^TOTAL/{gsub(/%/,"",$10); print $10}')
|
||||
# Keep the whole table: gen-badges turns it into the per-crate and
|
||||
# per-file breakdown on the Pages quality dashboard.
|
||||
bash ci/coverage.sh --summary-only | tee coverage-summary.txt
|
||||
PCT=$(awk '/^TOTAL/{gsub(/%/,"",$10); print $10}' coverage-summary.txt)
|
||||
[ -n "$PCT" ] || { echo "coverage report produced no TOTAL line" >&2; exit 1; }
|
||||
echo "pct=${PCT}" >> "$GITHUB_OUTPUT"
|
||||
echo "line coverage (tests + self-test): ${PCT}%"
|
||||
@@ -300,7 +302,8 @@ jobs:
|
||||
python3 ci/gen-badges.py --tests "$PASS" \
|
||||
--coverage "${{ steps.cov.outputs.pct }}" \
|
||||
--bench-coverage "${{ steps.benchcov.outputs.pct }}" \
|
||||
--bench-delta "$BENCH_DELTA" --clippy clean
|
||||
--bench-delta "$BENCH_DELTA" --clippy clean \
|
||||
--coverage-summary coverage-summary.txt
|
||||
|
||||
- name: Publish measured badges
|
||||
env:
|
||||
|
||||
@@ -2,3 +2,8 @@
|
||||
**/target
|
||||
.claude/
|
||||
__pycache__/
|
||||
# Internal working notes live outside this public repository.
|
||||
/AGENTS.md
|
||||
/HANDOFF.md
|
||||
/CLAUDE.md
|
||||
code-review-report*.md
|
||||
|
||||
@@ -1,17 +1,18 @@
|
||||
# Alkane Toolkit
|
||||
|
||||
[](https://gitea.bluefla.re/blueflare/alkane-toolkit/actions)
|
||||

|
||||

|
||||

|
||||

|
||||

|
||||

|
||||

|
||||

|
||||
[](https://blueflare.gitea.bluefla.re/alkane-toolkit/quality/)
|
||||
[](https://blueflare.gitea.bluefla.re/alkane-toolkit/quality/#coverage)
|
||||
[](https://blueflare.gitea.bluefla.re/alkane-toolkit/bench/)
|
||||
[](https://blueflare.gitea.bluefla.re/alkane-toolkit/quality/)
|
||||
[](https://blueflare.gitea.bluefla.re/alkane-toolkit/quality/#coverage)
|
||||
[](https://blueflare.gitea.bluefla.re/alkane-toolkit/quality/)
|
||||
[](https://blueflare.gitea.bluefla.re/alkane-toolkit/quality/)
|
||||
[](LICENSE)
|
||||
|
||||
The code quality grade reports GUI Clippy and first-party Rust formatting checks
|
||||
from the last successful main build. Test coverage has a separate badge.
|
||||
The badges link to the [project site](https://blueflare.gitea.bluefla.re/alkane-toolkit/): the [manual](https://blueflare.gitea.bluefla.re/alkane-toolkit/manual/),
|
||||
the [code-quality dashboard](https://blueflare.gitea.bluefla.re/alkane-toolkit/quality/) (how the grade is set, coverage by
|
||||
crate and file) and the [benchmark history](https://blueflare.gitea.bluefla.re/alkane-toolkit/bench/).
|
||||
|
||||
Desktop miner discovery and monitoring. The Rust GUI uses wxWidgets through
|
||||
a patched [wx-rs bridge](thirdparty/wx-rs). In-app image flashing is disabled
|
||||
@@ -42,8 +43,7 @@ macOS is not built.
|
||||
aftermarket firmware to stock.
|
||||
|
||||
Discovery is read-only. Control and restore actions change miners. Check the
|
||||
selected devices before applying them. See the [implementation plan](docs/IMPLEMENTATION-PLAN.md)
|
||||
and [firmware matrix](docs/aftermarket-parity-roadmap.md) for planned coverage.
|
||||
selected devices before applying them.
|
||||
|
||||
## Development
|
||||
|
||||
@@ -55,8 +55,8 @@ WX_RS_WXCONFIG="$HOME/.cache/wx-3.3.3-linux/bin/wx-config" \
|
||||
|
||||
Keep build output off the source share. `main` runs full CI and publishes
|
||||
qualifying releases; `next` builds `-rc` candidates. Badges measure host
|
||||
code, not installation support. See the public
|
||||
[benchmark history](https://blueflare.gitea.bluefla.re/alkane-benchmarks/toolkit/).
|
||||
code, not installation support. See the
|
||||
[benchmark history](https://blueflare.gitea.bluefla.re/alkane-toolkit/bench/).
|
||||
|
||||
## Firmware safety
|
||||
|
||||
|
||||
Executable
+293
@@ -0,0 +1,293 @@
|
||||
#!/usr/bin/env python3
|
||||
# SPDX-License-Identifier: MIT
|
||||
"""Build the Alkane Toolkit Pages site (served from this repo's gh-pages).
|
||||
|
||||
build-pages.py --out site [--manual docs/manual] [--quality quality.json]
|
||||
[--bench bench-site/index.html] [--sha SHA]
|
||||
|
||||
Pages:
|
||||
/ overview and downloads
|
||||
/manual/ the user manual, one page per docs/manual/NN-name.md chapter
|
||||
/quality/ code-quality dashboard from the measured quality.json that main
|
||||
CI publishes next to the badges (ci/gen-badges.py)
|
||||
/bench/ the measured benchmark history (ci/bench_history.py render)
|
||||
|
||||
Every value taken from CI data is HTML-escaped; the manual is Markdown written
|
||||
in this repository.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import html
|
||||
import json
|
||||
import re
|
||||
import shutil
|
||||
from pathlib import Path
|
||||
|
||||
import markdown
|
||||
|
||||
REPO = "https://gitea.bluefla.re/blueflare/alkane-toolkit"
|
||||
RELEASES = REPO + "/releases"
|
||||
SECTIONS = (("", "Overview"), ("manual/", "Manual"), ("quality/", "Code quality"),
|
||||
("bench/", "Benchmarks"))
|
||||
|
||||
CSS = """
|
||||
:root { --bg:#ffffff; --fg:#1f2328; --muted:#59636e; --line:#d1d9e0; --card:#f6f8fa;
|
||||
--accent:#d9822b; --link:#0969da; --good:#1a7f37; --warn:#9a6700; --bad:#cf222e; }
|
||||
@media (prefers-color-scheme: dark) { :root { --bg:#0d1117; --fg:#e6edf3; --muted:#9198a1;
|
||||
--line:#30363d; --card:#151b23; --link:#4493f8; --good:#3fb950; --warn:#d29922; --bad:#f85149; } }
|
||||
* { box-sizing: border-box; }
|
||||
body { margin:0; background:var(--bg); color:var(--fg);
|
||||
font:16px/1.55 system-ui,-apple-system,"Segoe UI",Roboto,Ubuntu,sans-serif; }
|
||||
a { color:var(--link); text-decoration:none; } a:hover { text-decoration:underline; }
|
||||
header { border-bottom:1px solid var(--line); }
|
||||
header .bar, main { max-width:1040px; margin:0 auto; padding:0 16px; }
|
||||
header .bar { display:flex; align-items:center; gap:24px; height:56px; flex-wrap:wrap; }
|
||||
header .brand { font-weight:700; color:var(--fg); display:flex; gap:8px; align-items:center; }
|
||||
header .brand i { width:20px; height:20px; border-radius:5px; background:var(--accent); display:inline-block; }
|
||||
header nav { display:flex; gap:18px; flex-wrap:wrap; }
|
||||
header nav a { color:var(--muted); } header nav a.on { color:var(--fg); font-weight:600; }
|
||||
main { padding:28px 16px 64px; }
|
||||
h1 { font-size:1.9rem; margin:.2em 0 .4em; } h2 { margin-top:1.8em; border-bottom:1px solid var(--line); padding-bottom:.25em; }
|
||||
code { background:var(--card); border:1px solid var(--line); border-radius:5px; padding:.1em .35em; font-size:.92em; }
|
||||
pre { background:var(--card); border:1px solid var(--line); border-radius:8px; padding:12px; overflow:auto; }
|
||||
pre code { border:0; padding:0; }
|
||||
table { border-collapse:collapse; width:100%; margin:1em 0; display:block; overflow-x:auto; }
|
||||
th, td { border:1px solid var(--line); padding:6px 10px; text-align:left; vertical-align:top; }
|
||||
th { background:var(--card); }
|
||||
td.num, th.num { text-align:right; font-variant-numeric:tabular-nums; white-space:nowrap; }
|
||||
.cards { display:grid; grid-template-columns:repeat(auto-fill,minmax(180px,1fr)); gap:12px; margin:1.2em 0; }
|
||||
.card { background:var(--card); border:1px solid var(--line); border-radius:10px; padding:14px; }
|
||||
.card b { display:block; font-size:1.6rem; } .card span { color:var(--muted); font-size:.9rem; }
|
||||
.good { color:var(--good); } .warn { color:var(--warn); } .bad { color:var(--bad); }
|
||||
.bar-cell { min-width:120px; } .meter { height:8px; background:var(--line); border-radius:4px; overflow:hidden; }
|
||||
.meter i { display:block; height:100%; }
|
||||
.layout { display:grid; grid-template-columns:220px 1fr; gap:32px; }
|
||||
.layout aside ol { padding-left:1.2em; margin:0; } .layout aside li { margin:.3em 0; }
|
||||
.layout aside a.on { font-weight:600; color:var(--fg); }
|
||||
@media (max-width:760px) { .layout { grid-template-columns:1fr; } }
|
||||
.buttons a { display:inline-block; margin:4px 8px 4px 0; padding:8px 14px; border-radius:8px;
|
||||
border:1px solid var(--line); background:var(--card); color:var(--fg); }
|
||||
.buttons a.primary { background:var(--accent); border-color:var(--accent); color:#fff; }
|
||||
footer { color:var(--muted); font-size:.85rem; margin-top:48px; }
|
||||
"""
|
||||
|
||||
|
||||
def page(title: str, body: str, depth: int, current: str, sha: str) -> str:
|
||||
up = "../" * depth
|
||||
nav = "".join(
|
||||
f'<a href="{up}{path}"{" class=on" if path == current else ""}>{label}</a>'
|
||||
for path, label in SECTIONS)
|
||||
built = f"Built from {html.escape(sha[:10])}. " if sha else ""
|
||||
return f"""<!doctype html>
|
||||
<html lang="en"><head><meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>{html.escape(title)} - Alkane Toolkit</title>
|
||||
<link rel="stylesheet" href="{up}style.css"></head>
|
||||
<body><header><div class="bar"><a class="brand" href="{up}"><i></i>Alkane Toolkit</a>
|
||||
<nav>{nav}<a href="{RELEASES}">Downloads</a><a href="{REPO}">Source</a></nav></div></header>
|
||||
<main>{body}
|
||||
<footer>{built}Alkane Toolkit is MIT licensed.</footer></main></body></html>
|
||||
"""
|
||||
|
||||
|
||||
def write(out: Path, rel: str, text: str) -> None:
|
||||
path = out / rel
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(text, encoding="utf-8")
|
||||
|
||||
|
||||
# ---- manual -----------------------------------------------------------------
|
||||
|
||||
def chapters(manual: Path) -> list[tuple[str, str, str]]:
|
||||
"""(slug, title, markdown) for docs/manual/NN-slug.md, in file-name order."""
|
||||
out = []
|
||||
for path in sorted(manual.glob("[0-9][0-9]-*.md")):
|
||||
text = path.read_text(encoding="utf-8")
|
||||
m = re.search(r"^# (.+)$", text, re.M)
|
||||
title = m.group(1).strip() if m else path.stem
|
||||
out.append((path.stem[3:], title, text))
|
||||
return out
|
||||
|
||||
|
||||
def build_manual(out: Path, manual: Path, sha: str) -> None:
|
||||
items = chapters(manual)
|
||||
if not items:
|
||||
raise SystemExit(f"no manual chapters in {manual}")
|
||||
|
||||
def toc(current: str) -> str:
|
||||
links = "".join(
|
||||
f'<li><a href="{slug}.html"{" class=on" if slug == current else ""}>'
|
||||
f"{html.escape(title)}</a></li>" for slug, title, _ in items)
|
||||
return f"<aside><ol>{links}</ol></aside>"
|
||||
|
||||
for slug, title, text in items:
|
||||
# Chapters link to each other as NN-name.md in the repo; on the site
|
||||
# they are name.html.
|
||||
text = re.sub(r"\]\((?:\./)?[0-9][0-9]-([a-z0-9-]+)\.md(#[^)]*)?\)", r"](\1.html\2)", text)
|
||||
body_html = markdown.markdown(text, extensions=["tables", "fenced_code", "toc"])
|
||||
write(out, f"manual/{slug}.html",
|
||||
page(title, f'<div class="layout">{toc(slug)}<article>{body_html}</article></div>',
|
||||
1, "manual/", sha))
|
||||
first = items[0][0]
|
||||
listing = "".join(f'<li><a href="{s}.html">{html.escape(t)}</a></li>' for s, t, _ in items)
|
||||
write(out, "manual/index.html",
|
||||
page("Manual", f"<h1>Manual</h1><p>Start with "
|
||||
f'<a href="{first}.html">{html.escape(items[0][1])}</a>.</p><ol>{listing}</ol>',
|
||||
1, "manual/", sha))
|
||||
|
||||
|
||||
# ---- quality dashboard ---------------------------------------------------------
|
||||
|
||||
def pct_class(pct: float | None) -> str:
|
||||
if pct is None:
|
||||
return ""
|
||||
return "good" if pct >= 80 else "warn" if pct >= 40 else "bad"
|
||||
|
||||
|
||||
def meter(pct: float) -> str:
|
||||
colour = {"good": "var(--good)", "warn": "var(--warn)", "bad": "var(--bad)"}[pct_class(pct)]
|
||||
return f'<div class="meter"><i style="width:{max(0.0, min(pct, 100.0)):.1f}%;background:{colour}"></i></div>'
|
||||
|
||||
|
||||
def build_quality(out: Path, quality: dict | None, sha: str) -> None:
|
||||
e = html.escape
|
||||
if not quality:
|
||||
write(out, "quality/index.html", page(
|
||||
"Code quality", "<h1>Code quality</h1><p>No measurement has been published yet; "
|
||||
"the next main build will fill this page.</p>", 1, "quality/", sha))
|
||||
return
|
||||
grade = str(quality.get("grade", "pending"))
|
||||
cov = quality.get("coverage_pct")
|
||||
bench_cov = quality.get("bench_coverage_pct")
|
||||
delta = quality.get("bench_delta_pct")
|
||||
|
||||
def card(value: str, label: str, cls: str = "") -> str:
|
||||
return f'<div class="card"><b class="{cls}">{value}</b><span>{label}</span></div>'
|
||||
|
||||
cards = "".join([
|
||||
card(e(grade), "Quality grade", {"A": "good", "B": "good", "C": "warn"}.get(grade, "bad")),
|
||||
card(e(str(quality.get("tests_passed", "-"))), "Tests passing", "good"),
|
||||
card(f"{cov:.1f}%" if cov is not None else "-", "Line coverage", pct_class(cov)),
|
||||
card(f"{bench_cov:.1f}%" if bench_cov is not None else "-", "Benchmark coverage", pct_class(bench_cov)),
|
||||
card(e(str(quality.get("clippy") or "-")), "Clippy (warnings are errors)",
|
||||
"good" if quality.get("clippy") == "clean" else "bad"),
|
||||
card(e(str(quality.get("rustfmt") or "-")), "rustfmt", "good" if quality.get("rustfmt") == "clean" else ""),
|
||||
card(f"{quality.get('loc', 0):,}", "Lines of Rust"),
|
||||
card(e(str(quality.get("dependencies", "-"))), "Crates in Cargo.lock"),
|
||||
card((f"{'+' if delta > 0 else ''}{delta:.1f}%" if delta is not None else "-"),
|
||||
"Benchmarks vs previous" + (" (same inputs)" if quality.get("bench_same_inputs") else ""),
|
||||
"" if delta is None else "good" if delta >= 2 else "" if delta > -2 else "warn"),
|
||||
])
|
||||
bands = ", ".join(f"{e(str(letter))} at {floor:.0f}% or more"
|
||||
for floor, letter in quality.get("grade_bands", []))
|
||||
grade_rule = (f"<p>The grade is F if Clippy or rustfmt fails on main. Otherwise it is the "
|
||||
f"line-coverage band: {bands}, and F below that. The coverage badge uses the "
|
||||
f"same bands for its colour, so the two never disagree.</p>")
|
||||
|
||||
crates = quality.get("coverage_by_crate", {})
|
||||
loc = quality.get("loc_by_crate", {})
|
||||
rows = []
|
||||
for name in sorted(set(crates) | set(loc)):
|
||||
c = crates.get(name)
|
||||
if c and c["lines"]:
|
||||
pct = 100.0 * (c["lines"] - c["missed"]) / c["lines"]
|
||||
cov_cells = (f'<td class="num {pct_class(pct)}">{pct:.1f}%</td>'
|
||||
f'<td class="bar-cell">{meter(pct)}</td>'
|
||||
f'<td class="num">{c["lines"] - c["missed"]:,} / {c["lines"]:,}</td>')
|
||||
else:
|
||||
cov_cells = '<td class="num">-</td><td></td><td class="num">-</td>'
|
||||
rows.append(f"<tr><td>{e(name)}</td>{cov_cells}<td class='num'>{loc.get(name, 0):,}</td></tr>")
|
||||
crate_table = ("<table><tr><th>Crate</th><th class=num>Line coverage</th><th></th>"
|
||||
"<th class=num>Covered lines</th><th class=num>Lines of Rust</th></tr>"
|
||||
+ "".join(rows) + "</table>")
|
||||
|
||||
files = sorted(quality.get("coverage_by_file", []),
|
||||
key=lambda r: (r["lines"] - r["missed"]) / r["lines"] if r["lines"] else 1)
|
||||
file_rows = "".join(
|
||||
f"<tr><td><code>{e(r['file'])}</code></td>"
|
||||
f"<td class='num {pct_class(100.0 * (r['lines'] - r['missed']) / r['lines'])}'>"
|
||||
f"{100.0 * (r['lines'] - r['missed']) / r['lines']:.1f}%</td>"
|
||||
f"<td class='num'>{r['missed']:,}</td><td class='num'>{r['lines']:,}</td></tr>"
|
||||
for r in files if r["lines"])
|
||||
file_table = ("<table><tr><th>File (least covered first)</th><th class=num>Coverage</th>"
|
||||
"<th class=num>Uncovered lines</th><th class=num>Lines</th></tr>"
|
||||
+ file_rows + "</table>") if file_rows else ""
|
||||
|
||||
measured = str(quality.get("sha", ""))[:10]
|
||||
of_build = f" (this page: <code>{e(measured)}</code>)" if measured else ""
|
||||
body = f"""<h1>Code quality</h1>
|
||||
<p>Measured by main CI on every build{of_build}:
|
||||
unit tests, line coverage (unit tests plus the headless UI self-test), Clippy with
|
||||
warnings as errors, and rustfmt. Windows builds run the same tests under Wine and
|
||||
on real Windows 11.</p>
|
||||
<div class="cards">{cards}</div>
|
||||
<h2 id="grade">How the grade is set</h2>{grade_rule}
|
||||
<h2 id="coverage">Coverage by crate</h2>{crate_table}
|
||||
<h2 id="files">Coverage by file</h2>{file_table}
|
||||
<p>The dependency count is every package in <code>Cargo.lock</code>, direct and
|
||||
transitive. Lines of Rust count every <code>.rs</code> line under <code>crates/</code>,
|
||||
tests included.</p>"""
|
||||
write(out, "quality/index.html", page("Code quality", body, 1, "quality/", sha))
|
||||
|
||||
|
||||
# ---- benchmarks + overview -------------------------------------------------------
|
||||
|
||||
def build_bench(out: Path, bench: Path | None, sha: str) -> None:
|
||||
if bench is None or not bench.is_file():
|
||||
write(out, "bench/index.html", page(
|
||||
"Benchmarks", "<h1>Benchmarks</h1><p>No benchmark history yet.</p>", 1, "bench/", sha))
|
||||
return
|
||||
rendered = bench.read_text(encoding="utf-8")
|
||||
# The history renderer emits a complete document; keep its body (and its
|
||||
# own styles) under the site's header.
|
||||
styles = "".join(re.findall(r"<style[^>]*>.*?</style>", rendered, re.S | re.I))
|
||||
m = re.search(r"<body[^>]*>(.*)</body>", rendered, re.S | re.I)
|
||||
inner = m.group(1) if m else rendered
|
||||
text = page("Benchmarks", inner, 1, "bench/", sha)
|
||||
write(out, "bench/index.html", text.replace("</head>", styles + "</head>", 1))
|
||||
|
||||
|
||||
def build_index(out: Path, quality: dict | None, sha: str) -> None:
|
||||
grade = html.escape(str((quality or {}).get("grade", "pending")))
|
||||
body = f"""<h1>Alkane Toolkit</h1>
|
||||
<p>Desktop discovery and monitoring for ASIC miners on your network: find every
|
||||
miner in your IP ranges, see hashrate, power, temperatures, fans and hashboard
|
||||
health at a glance, and run the controls each firmware supports.</p>
|
||||
<div class="buttons"><a class="primary" href="{RELEASES}">Download for Windows or Linux</a>
|
||||
<a href="manual/">Read the manual</a><a href="quality/">Code quality: {grade}</a>
|
||||
<a href="bench/">Benchmarks</a></div>
|
||||
<h2>Platforms</h2>
|
||||
<ul><li><b>Windows 10 and 11</b> (x86_64): one signed, self-contained <code>alkane-toolkit.exe</code>.</li>
|
||||
<li><b>Linux</b> (x86_64, GTK 3): one binary.</li></ul>
|
||||
<p>Every release is built, tested and signed by CI from the public source.</p>"""
|
||||
write(out, "index.html", page("Overview", body, 0, "", sha))
|
||||
|
||||
|
||||
def main() -> None:
|
||||
ap = argparse.ArgumentParser(description=__doc__,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
ap.add_argument("--out", required=True)
|
||||
ap.add_argument("--manual", default="docs/manual")
|
||||
ap.add_argument("--quality", default=None)
|
||||
ap.add_argument("--bench", default=None)
|
||||
ap.add_argument("--sha", default="")
|
||||
args = ap.parse_args()
|
||||
out = Path(args.out)
|
||||
if out.exists():
|
||||
shutil.rmtree(out)
|
||||
out.mkdir(parents=True)
|
||||
quality = None
|
||||
if args.quality and Path(args.quality).is_file():
|
||||
quality = json.loads(Path(args.quality).read_text())
|
||||
if not isinstance(quality, dict) or quality.get("schema") != 1:
|
||||
raise SystemExit("unsupported quality.json")
|
||||
(out / "style.css").write_text(CSS.strip() + "\n", encoding="utf-8")
|
||||
build_index(out, quality, args.sha)
|
||||
build_manual(out, Path(args.manual), args.sha)
|
||||
build_quality(out, quality, args.sha)
|
||||
build_bench(out, Path(args.bench) if args.bench else None, args.sha)
|
||||
print(f"built {sum(1 for _ in out.rglob('*.html'))} pages in {out}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -32,12 +32,12 @@ def main() -> int:
|
||||
print(f"{path.name}: {name} has a different runner image", file=sys.stderr)
|
||||
return 1
|
||||
pages = yaml.load(
|
||||
(ROOT / ".gitea/workflows/bench-pages.yml").read_text(),
|
||||
(ROOT / ".gitea/workflows/pages.yml").read_text(),
|
||||
Loader=yaml.BaseLoader,
|
||||
)
|
||||
if (pages["on"]["workflow_run"]["workflows"] != ["build-test-release"]
|
||||
or pages["jobs"]["publish"].get("runs-on") != "alkane-verify"):
|
||||
print("Benchmark Pages must follow main CI on the trusted verifier", file=sys.stderr)
|
||||
print("Pages must follow main CI on the trusted verifier", file=sys.stderr)
|
||||
return 1
|
||||
release = yaml.load(
|
||||
(ROOT / ".gitea/workflows/release.yml").read_text(),
|
||||
@@ -46,7 +46,7 @@ def main() -> int:
|
||||
if release["jobs"]["release"].get("runs-on") != "alkane-ci":
|
||||
print("Main release must use the dedicated Alkane build pool", file=sys.stderr)
|
||||
return 1
|
||||
if any("ci/publish-bench-pages.py" in step.get("run", "")
|
||||
if any("ci/publish-pages.py" in step.get("run", "")
|
||||
for step in release["jobs"]["release"]["steps"]):
|
||||
print("Main release must not publish Pages from GARM", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
@@ -9,9 +9,9 @@ import sys
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
DIRECTORIES = ("target", "dist", "coverage", "bench-site")
|
||||
FILES = ("bench-current.txt",)
|
||||
BADGE_FILES = ("bench-baseline.json", "bench-context.json")
|
||||
DIRECTORIES = ("target", "dist", "coverage", "bench-site", "site")
|
||||
FILES = ("bench-current.txt", "coverage-summary.txt", "quality.json")
|
||||
BADGE_FILES = ("bench-baseline.json", "bench-context.json", "quality.json")
|
||||
|
||||
|
||||
def cleanup() -> None:
|
||||
|
||||
@@ -46,7 +46,7 @@ vendor/*|thirdparty/asic-rs/*)
|
||||
# resources, embedded assets). ui.rs/fixtures.rs/bin
|
||||
# match the UI arm above first, so they still bump Z, not Y.
|
||||
backend=true ;;
|
||||
*) : ;; # docs, HANDOFF, README, thirdparty/wxwidgets tree: no bump
|
||||
*) : ;; # docs, README, thirdparty/wxwidgets tree: no bump
|
||||
esac
|
||||
done <<< "$changed"
|
||||
|
||||
|
||||
@@ -3,11 +3,12 @@
|
||||
# Use the preinstalled CI image or install missing packages on older runners.
|
||||
set -euo pipefail
|
||||
|
||||
mode="${1:?usage: ensure-build-deps.sh base|ui|all|ssh|windows}"
|
||||
mode="${1:?usage: ensure-build-deps.sh base|ui|all|ssh|windows|pages}"
|
||||
case "$mode" in
|
||||
base) packages=(libssl-dev pkg-config ca-certificates) ;;
|
||||
ui) packages=(xvfb xauth dbus-x11 fonts-dejavu-core) ;;
|
||||
ssh) packages=(openssh-client) ;;
|
||||
pages) packages=(python3-markdown) ;;
|
||||
all) packages=(libssl-dev pkg-config ca-certificates openssh-client
|
||||
xvfb xauth dbus-x11 fonts-dejavu-core) ;;
|
||||
# Windows cross build (mingw-w64, posix threads) + Wine for its tests.
|
||||
|
||||
Executable
+41
@@ -0,0 +1,41 @@
|
||||
#!/usr/bin/env python3
|
||||
# SPDX-License-Identifier: MIT
|
||||
"""Download the measured quality record (badges/quality.json on ci-badges).
|
||||
|
||||
fetch-quality.py OUT.json
|
||||
|
||||
Writes nothing (and exits 0) when main CI has not published one yet, so the
|
||||
Pages build shows a "not measured yet" dashboard instead of failing.
|
||||
"""
|
||||
|
||||
import base64
|
||||
import json
|
||||
import os
|
||||
from pathlib import Path
|
||||
import sys
|
||||
from urllib.error import HTTPError
|
||||
from urllib.request import Request, urlopen
|
||||
|
||||
|
||||
def main() -> None:
|
||||
out = Path(sys.argv[1])
|
||||
api = os.environ["GITHUB_API_URL"].rstrip("/")
|
||||
repo = os.environ["GITHUB_REPOSITORY"]
|
||||
url = f"{api}/repos/{repo}/contents/badges/quality.json?ref=ci-badges"
|
||||
request = Request(url, headers={"Authorization": f"token {os.environ['GITEA_TOKEN']}"})
|
||||
try:
|
||||
with urlopen(request, timeout=20) as response:
|
||||
content = base64.b64decode(json.load(response)["content"])
|
||||
except HTTPError as error:
|
||||
if error.code == 404:
|
||||
print("No quality record published yet")
|
||||
return
|
||||
raise
|
||||
if not isinstance(json.loads(content), dict):
|
||||
sys.exit("invalid quality record")
|
||||
out.write_bytes(content)
|
||||
print(f"Fetched quality record ({len(content)} bytes)")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
+97
-8
@@ -135,10 +135,66 @@ def cov_color(pct: float) -> str:
|
||||
return "red"
|
||||
|
||||
|
||||
def quality_grade(clippy: str | None) -> str:
|
||||
if clippy is None:
|
||||
# Code-quality grade (shown on the badge and explained on the Pages quality
|
||||
# dashboard). Lint failures fail the grade outright; otherwise the grade is the
|
||||
# measured line-coverage band, using the same bands as the coverage badge
|
||||
# colour, so the two badges can never disagree.
|
||||
GRADE_BANDS = ((80.0, "A"), (60.0, "B"), (40.0, "C"), (20.0, "D"))
|
||||
GRADE_COLORS = {"A": "brightgreen", "B": "yellowgreen", "C": "yellow",
|
||||
"D": "orange", "F": "red", "pending": "lightgrey"}
|
||||
|
||||
|
||||
def quality_grade(clippy: str | None, coverage: float | None = None) -> str:
|
||||
if clippy is None or (clippy == "clean" and coverage is None):
|
||||
return "pending"
|
||||
return "A" if clippy == "clean" else "F"
|
||||
if clippy != "clean":
|
||||
return "F"
|
||||
for floor, grade in GRADE_BANDS:
|
||||
if coverage >= floor:
|
||||
return grade
|
||||
return "F"
|
||||
|
||||
|
||||
def coverage_by_file(summary_path: str | None, root: str) -> list[dict]:
|
||||
"""Per-file line coverage from a `cargo llvm-cov --summary-only` table.
|
||||
|
||||
Columns: Filename, Regions, Missed Regions, Cover, Functions, Missed
|
||||
Functions, Executed, Lines, Missed Lines, Cover, ...
|
||||
"""
|
||||
if not summary_path:
|
||||
return []
|
||||
rows = []
|
||||
root_abs = os.path.abspath(root).rstrip("/") + "/"
|
||||
for line in Path(summary_path).read_text(errors="replace").splitlines():
|
||||
cols = line.split()
|
||||
if len(cols) < 10 or cols[0] in ("Filename", "TOTAL") or not cols[0].endswith(".rs"):
|
||||
continue
|
||||
try:
|
||||
lines, missed = int(cols[7]), int(cols[8])
|
||||
except ValueError:
|
||||
continue
|
||||
name = cols[0][len(root_abs):] if cols[0].startswith(root_abs) else cols[0]
|
||||
rows.append({"file": name, "lines": lines, "missed": missed})
|
||||
return rows
|
||||
|
||||
|
||||
def crate_of(path: str) -> str:
|
||||
parts = Path(path).parts
|
||||
if "crates" in parts and parts.index("crates") + 1 < len(parts):
|
||||
return parts[parts.index("crates") + 1]
|
||||
if "wx-rs-0.2.0-patched" in parts:
|
||||
return "wx-rs (bridge)"
|
||||
return "other"
|
||||
|
||||
|
||||
def loc_by_crate(root: str) -> dict[str, int]:
|
||||
out: dict[str, int] = {}
|
||||
crates = Path(root) / "crates"
|
||||
for path in sorted(crates.glob("*/**/*.rs")):
|
||||
crate = path.relative_to(crates).parts[0]
|
||||
with open(path, encoding="utf-8", errors="ignore") as fh:
|
||||
out[crate] = out.get(crate, 0) + sum(1 for _ in fh)
|
||||
return out
|
||||
|
||||
|
||||
def human(n: int) -> str:
|
||||
@@ -169,6 +225,9 @@ def main() -> int:
|
||||
# percentage string, or "NEW" when there is no baseline.
|
||||
ap.add_argument("--bench-delta", default=None)
|
||||
ap.add_argument("--clippy", choices=("clean", "failed"))
|
||||
# The full `cargo llvm-cov --summary-only` table, for the per-crate and
|
||||
# per-file breakdown in quality.json (the Pages quality dashboard).
|
||||
ap.add_argument("--coverage-summary", default=None)
|
||||
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):
|
||||
@@ -189,11 +248,9 @@ 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)
|
||||
write("quality", "code quality", grade,
|
||||
{"A": "brightgreen", "B": "yellowgreen", "C": "yellow",
|
||||
"D": "orange", "F": "red", "pending": "lightgrey"}[grade],
|
||||
f"code quality: {grade} (GUI Clippy and first-party rustfmt)")
|
||||
grade = quality_grade(args.clippy, args.coverage)
|
||||
write("quality", "code quality", grade, GRADE_COLORS[grade],
|
||||
f"code quality: {grade} (Clippy, rustfmt and line coverage)")
|
||||
if args.tests is not None:
|
||||
write("tests", "tests", f"{args.tests} passing", "brightgreen")
|
||||
if args.coverage is not None:
|
||||
@@ -228,6 +285,38 @@ def main() -> int:
|
||||
write("bench", "bench", "baseline set", "blue")
|
||||
elif args.bench is not None:
|
||||
write("bench", "bench", args.bench, "blue")
|
||||
|
||||
# Everything above, plus the per-crate breakdowns, for the Pages quality
|
||||
# dashboard (ci/build-pages.py).
|
||||
files = coverage_by_file(args.coverage_summary, args.root)
|
||||
crates: dict[str, dict] = {}
|
||||
for row in files:
|
||||
c = crates.setdefault(crate_of(row["file"]), {"lines": 0, "missed": 0})
|
||||
c["lines"] += row["lines"]
|
||||
c["missed"] += row["missed"]
|
||||
quality = {
|
||||
"schema": 1,
|
||||
"sha": os.environ.get("GITHUB_SHA", ""),
|
||||
"grade": grade,
|
||||
"grade_bands": [[floor, letter] for floor, letter in GRADE_BANDS],
|
||||
"clippy": args.clippy,
|
||||
"rustfmt": "clean" if args.clippy is not None else None,
|
||||
"tests_passed": args.tests,
|
||||
"coverage_pct": args.coverage,
|
||||
"bench_coverage_pct": args.bench_coverage,
|
||||
"bench_delta_pct": delta,
|
||||
"bench_same_inputs": same_inputs,
|
||||
"loc": loc,
|
||||
"loc_by_crate": loc_by_crate(args.root),
|
||||
"dependencies": deps,
|
||||
"license": lic,
|
||||
"coverage_by_crate": crates,
|
||||
"coverage_by_file": files,
|
||||
}
|
||||
path = os.path.join(args.root, args.out, "quality.json")
|
||||
with open(path, "w", encoding="utf-8") as fh:
|
||||
json.dump(quality, fh, indent=1, sort_keys=True)
|
||||
print(f"wrote {path}")
|
||||
return 0
|
||||
|
||||
|
||||
|
||||
@@ -1,121 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
# SPDX-License-Identifier: MIT
|
||||
"""Publish a measured benchmark page to the public, data-only Pages repo."""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
from pathlib import Path
|
||||
import shlex
|
||||
import subprocess
|
||||
import tempfile
|
||||
from urllib.request import Request, urlopen
|
||||
|
||||
PAGES_REPO = "ssh://git@gitea.bluefla.re:2222/blueflare/alkane-benchmarks.git"
|
||||
GUARD_REPO = "https://gitea.bluefla.re/blueflare/alkane-benchmarks.git"
|
||||
GUARD_COMMIT = "ea160545c49bc419a245692deda8dd7db7a611eb"
|
||||
PAGES_HOST = "gitea.bluefla.re"
|
||||
PAGES_HOST_FINGERPRINT = "SHA256:lqB5cmC9E5HNeg/lkzdOwQ++I8A70Wx7lnNs6liN24g"
|
||||
PAGES_HOST_KEY = "[gitea.bluefla.re]:2222 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIO1II6NkmRW+QAd+Wj+7qbNrA8Oo+/N/WRog4hELskn/"
|
||||
|
||||
|
||||
def run(*args: str, env: dict[str, str] | None = None,
|
||||
cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
|
||||
return subprocess.run(args, env=env, cwd=cwd, text=True,
|
||||
capture_output=True, check=True)
|
||||
|
||||
|
||||
def current_main_sha() -> str:
|
||||
api = os.environ["GITHUB_API_URL"].rstrip("/")
|
||||
repo = os.environ["GITHUB_REPOSITORY"]
|
||||
token = os.environ["GITEA_TOKEN"]
|
||||
request = Request(f"{api}/repos/{repo}/branches/main",
|
||||
headers={"Authorization": f"token {token}"})
|
||||
with urlopen(request, timeout=20) as response:
|
||||
branch = json.load(response)
|
||||
return branch["commit"]["id"]
|
||||
|
||||
|
||||
def publish(site: str) -> None:
|
||||
if os.environ.get("GITHUB_REF") != "refs/heads/main":
|
||||
raise ValueError("benchmark Pages publication requires main")
|
||||
sha = os.environ["GITHUB_SHA"]
|
||||
if current_main_sha() != sha:
|
||||
print("Skipping benchmark page from a superseded main commit")
|
||||
return
|
||||
page = Path("bench-site/index.html").read_bytes()
|
||||
if not page.startswith(b"<!doctype html>") or len(page) > 1_048_576:
|
||||
raise ValueError("invalid benchmark page")
|
||||
with tempfile.TemporaryDirectory(prefix="alkane-pages-") as directory:
|
||||
temporary = Path(directory)
|
||||
guard_checkout = temporary / "guard"
|
||||
run("git", "clone", "--quiet", "--single-branch", "--branch", "next",
|
||||
GUARD_REPO, str(guard_checkout))
|
||||
guard_source = run("git", "show", f"{GUARD_COMMIT}:ci/validate_site.py",
|
||||
cwd=guard_checkout).stdout
|
||||
guard_script = temporary / "validate_site.py"
|
||||
guard_script.write_text(guard_source)
|
||||
run("python3", str(guard_script), "--page", site,
|
||||
str(Path("bench-site/index.html").resolve()))
|
||||
key = os.environ["BENCH_PAGES_DEPLOY_KEY"]
|
||||
if not key.startswith("-----BEGIN OPENSSH PRIVATE KEY-----"):
|
||||
raise ValueError("missing benchmark Pages deploy key")
|
||||
key_path = temporary / "deploy_key"
|
||||
key_path.write_text(key.rstrip("\n") + "\n")
|
||||
key_path.chmod(0o600)
|
||||
known_hosts = temporary / "known_hosts"
|
||||
known_hosts.write_text(PAGES_HOST_KEY + "\n")
|
||||
fingerprint = run("ssh-keygen", "-lf", str(known_hosts)).stdout.split()[1]
|
||||
if fingerprint != PAGES_HOST_FINGERPRINT:
|
||||
raise ValueError("benchmark Pages SSH host key changed")
|
||||
git_env = os.environ.copy()
|
||||
ssh_command = (f"ssh -i {shlex.quote(str(key_path))} -o IdentitiesOnly=yes "
|
||||
f"-o UserKnownHostsFile={shlex.quote(str(known_hosts))} "
|
||||
"-o StrictHostKeyChecking=yes -o ConnectTimeout=10")
|
||||
git_env["GIT_SSH_COMMAND"] = ssh_command
|
||||
git_env["GIT_TERMINAL_PROMPT"] = "0"
|
||||
checkout = temporary / "site"
|
||||
run("git", "clone", "--quiet", "--single-branch", "--branch", "gh-pages",
|
||||
PAGES_REPO, str(checkout), env=git_env)
|
||||
run("git", "config", "user.name", "Alkane CI", cwd=checkout)
|
||||
run("git", "config", "user.email", "ci@bluefla.re", cwd=checkout)
|
||||
for attempt in range(3):
|
||||
if current_main_sha() != sha:
|
||||
print("Skipping benchmark page from a superseded main commit")
|
||||
return
|
||||
run("git", "fetch", "--quiet", "origin", "gh-pages", env=git_env,
|
||||
cwd=checkout)
|
||||
run("git", "checkout", "-q", "-B", "bench-publish", "origin/gh-pages",
|
||||
cwd=checkout)
|
||||
destination = checkout / site / "index.html"
|
||||
destination.parent.mkdir(exist_ok=True)
|
||||
destination.write_bytes(page)
|
||||
run("git", "add", f"{site}/index.html", cwd=checkout)
|
||||
changed = subprocess.run(("git", "diff", "--cached", "--quiet"),
|
||||
cwd=checkout, check=False)
|
||||
if changed.returncode == 0:
|
||||
print(f"{site} benchmark page is already current")
|
||||
return
|
||||
if changed.returncode != 1:
|
||||
raise RuntimeError("cannot compare benchmark page")
|
||||
run("git", "commit", "-q", "-m",
|
||||
f"Update {site} benchmarks for {sha[:10]} [skip ci]", cwd=checkout)
|
||||
pushed = subprocess.run(("git", "push", "--quiet", "origin",
|
||||
"HEAD:gh-pages"), env=git_env, cwd=checkout,
|
||||
text=True, capture_output=True, check=False)
|
||||
if pushed.returncode == 0:
|
||||
print(f"Published {site} benchmark page for {sha[:10]}")
|
||||
return
|
||||
if attempt == 2:
|
||||
raise RuntimeError(f"benchmark Pages push failed: {pushed.stderr.strip()}")
|
||||
raise RuntimeError("benchmark Pages publication did not complete")
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("site", choices=("sdk", "os", "toolkit"))
|
||||
publish(parser.parse_args().site)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -2,6 +2,7 @@
|
||||
# SPDX-License-Identifier: MIT
|
||||
"""Publish measured toolkit badges to the private Gitea badge branch."""
|
||||
|
||||
import json
|
||||
import os
|
||||
from pathlib import Path
|
||||
|
||||
@@ -22,7 +23,14 @@ def main() -> None:
|
||||
raise ValueError(f"invalid {name} SVG")
|
||||
publish_file(api, repo, f"badges/{name}.svg", data, token,
|
||||
f"Update measured {name} badge")
|
||||
print(f"Published {len(NAMES)} measured badge SVGs")
|
||||
# The full measurement record behind the badges, read by the Pages
|
||||
# quality dashboard (ci/build-pages.py).
|
||||
data = (ROOT / "badges" / "quality.json").read_bytes()
|
||||
if not isinstance(json.loads(data), dict):
|
||||
raise ValueError("invalid quality.json")
|
||||
publish_file(api, repo, "badges/quality.json", data, token,
|
||||
"Update measured quality record", max_bytes=262_144)
|
||||
print(f"Published {len(NAMES)} measured badge SVGs and quality.json")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
Executable
+79
@@ -0,0 +1,79 @@
|
||||
#!/usr/bin/env python3
|
||||
# SPDX-License-Identifier: MIT
|
||||
"""Publish the built Pages site to this repository's gh-pages branch.
|
||||
|
||||
publish-pages.py SITE_DIR
|
||||
|
||||
Served at https://blueflare.gitea.bluefla.re/alkane-toolkit/ by the Pages
|
||||
server, which serves the gh-pages branch of public repositories. Each publish
|
||||
is one orphan commit (force-pushed), so the branch never accumulates history.
|
||||
Only main may publish, and a run for a superseded main commit skips.
|
||||
"""
|
||||
|
||||
import json
|
||||
import os
|
||||
from pathlib import Path
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
from urllib.request import Request, urlopen
|
||||
|
||||
BRANCH = "gh-pages"
|
||||
MAX_BYTES = 20 * 1024 * 1024
|
||||
|
||||
|
||||
def current_main_sha(api: str, repo: str, token: str) -> str:
|
||||
request = Request(f"{api}/repos/{repo}/branches/main",
|
||||
headers={"Authorization": f"token {token}"})
|
||||
with urlopen(request, timeout=20) as response:
|
||||
return json.load(response)["commit"]["id"]
|
||||
|
||||
|
||||
def git(*args: str, cwd: Path, env: dict | None = None) -> None:
|
||||
subprocess.run(("git", *args), cwd=cwd, env=env, check=True)
|
||||
|
||||
|
||||
def main() -> None:
|
||||
if len(sys.argv) != 2:
|
||||
sys.exit(__doc__)
|
||||
site = Path(sys.argv[1])
|
||||
if not (site / "index.html").is_file():
|
||||
sys.exit(f"{site} has no index.html")
|
||||
size = sum(p.stat().st_size for p in site.rglob("*") if p.is_file())
|
||||
if size > MAX_BYTES:
|
||||
sys.exit(f"site is {size} bytes, over the {MAX_BYTES} byte limit")
|
||||
for path in site.rglob("*"):
|
||||
if path.is_file() and path.suffix not in {".html", ".css", ".svg", ".png", ".json"}:
|
||||
sys.exit(f"unexpected file type on the site: {path}")
|
||||
|
||||
api = os.environ["GITHUB_API_URL"].rstrip("/")
|
||||
repo = os.environ["GITHUB_REPOSITORY"]
|
||||
sha = os.environ["GITHUB_SHA"]
|
||||
token = os.environ["GITEA_TOKEN"]
|
||||
if os.environ.get("GITHUB_REF") != "refs/heads/main":
|
||||
sys.exit("Pages publication requires main")
|
||||
if current_main_sha(api, repo, token) != sha:
|
||||
print("Skipping Pages for a superseded main commit")
|
||||
return
|
||||
|
||||
server = api.removesuffix("/api/v1")
|
||||
with tempfile.TemporaryDirectory(prefix="alkane-pages-") as directory:
|
||||
work = Path(directory)
|
||||
shutil.copytree(site, work, dirs_exist_ok=True)
|
||||
env = dict(os.environ, GIT_TERMINAL_PROMPT="0")
|
||||
git("init", "-q", "-b", BRANCH, cwd=work)
|
||||
git("-c", "user.name=Alkane CI", "-c", "user.email=ci@noreply.gitea.bluefla.re",
|
||||
"add", "-A", cwd=work)
|
||||
git("-c", "user.name=Alkane CI", "-c", "user.email=ci@noreply.gitea.bluefla.re",
|
||||
"commit", "-q", "-m", f"Publish site for {sha[:10]} [skip ci]", cwd=work)
|
||||
# The token is read from the environment by the credential helper at
|
||||
# push time; it never appears on a command line or in the remote URL.
|
||||
helper = '!f() { echo username=alkane-ci; echo "password=$GITEA_TOKEN"; }; f'
|
||||
git("-c", f"credential.helper={helper}", "push", "-q", "--force",
|
||||
f"{server}/{repo}.git", f"HEAD:refs/heads/{BRANCH}", cwd=work, env=env)
|
||||
print(f"Published Pages for {sha[:10]} to {BRANCH}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
+30
-10
@@ -5,6 +5,7 @@
|
||||
import importlib.util
|
||||
import re
|
||||
from pathlib import Path
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
|
||||
@@ -50,16 +51,35 @@ class BenchBadgeTests(unittest.TestCase):
|
||||
self.assertEqual(gen_badges.bench_color(30.0), "brightgreen")
|
||||
self.assertEqual(gen_badges.bench_color(-55.5555556), "orange")
|
||||
|
||||
def test_quality_grade_is_only_the_clippy_result(self):
|
||||
self.assertEqual(gen_badges.quality_grade("clean"), "A")
|
||||
self.assertEqual(gen_badges.quality_grade("failed"), "F")
|
||||
self.assertEqual(gen_badges.quality_grade(None), "pending")
|
||||
svg = gen_badges.badge_svg(
|
||||
"code quality", "A", "brightgreen",
|
||||
"code quality: A (GUI Clippy and first-party rustfmt)",
|
||||
)
|
||||
self.assertIn('aria-label="code quality: A (GUI Clippy and first-party rustfmt)"', svg)
|
||||
self.assertIn('>A</text>', svg)
|
||||
def test_quality_grade_follows_lint_and_coverage(self):
|
||||
# A lint failure fails the grade; otherwise it is the coverage band,
|
||||
# with the same floors as the coverage badge colour.
|
||||
self.assertEqual(gen_badges.quality_grade("failed", 95.0), "F")
|
||||
self.assertEqual(gen_badges.quality_grade("clean", 85.0), "A")
|
||||
self.assertEqual(gen_badges.quality_grade("clean", 65.6), "B")
|
||||
self.assertEqual(gen_badges.quality_grade("clean", 48.0), "C")
|
||||
self.assertEqual(gen_badges.quality_grade("clean", 25.0), "D")
|
||||
self.assertEqual(gen_badges.quality_grade("clean", 5.0), "F")
|
||||
self.assertEqual(gen_badges.quality_grade("clean"), "pending")
|
||||
self.assertEqual(gen_badges.quality_grade(None, 90.0), "pending")
|
||||
for pct in (85.0, 65.6, 48.0, 25.0):
|
||||
grade = gen_badges.quality_grade("clean", pct)
|
||||
self.assertEqual(gen_badges.GRADE_COLORS[grade], gen_badges.cov_color(pct))
|
||||
|
||||
def test_coverage_table_is_split_by_crate(self):
|
||||
with tempfile.TemporaryDirectory(prefix="alkane-cov-") as directory:
|
||||
summary = Path(directory) / "summary.txt"
|
||||
summary.write_text(
|
||||
"Filename Regions Missed Regions Cover Functions Missed Functions "
|
||||
"Executed Lines Missed Lines Cover\n"
|
||||
"crates/alkane-gui/src/ui.rs 10 5 50.00% 4 2 50.00% 100 60 40.00%\n"
|
||||
"crates/alkane-core/src/platform.rs 4 0 100.00% 2 0 100.00% 50 5 90.00%\n"
|
||||
"TOTAL 14 5 64.29% 6 2 66.67% 150 65 56.67%\n")
|
||||
rows = gen_badges.coverage_by_file(str(summary), directory)
|
||||
self.assertEqual([r["file"] for r in rows],
|
||||
["crates/alkane-gui/src/ui.rs", "crates/alkane-core/src/platform.rs"])
|
||||
self.assertEqual(rows[0]["missed"], 60)
|
||||
self.assertEqual(gen_badges.crate_of(rows[1]["file"]), "alkane-core")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
//! Bench-fleet fixtures: the expected hardware output of the 9 boards on
|
||||
//! 10.255.1.0/24 (see ../../../HANDOFF.md section 7 and the parent project's
|
||||
//! [removed]). These are the reference values the workflow tests compare
|
||||
//! Fixture fleet: the expected hardware output of nine representative miners
|
||||
//! (one per control-board family / firmware). These are the reference values
|
||||
//! the workflow tests compare
|
||||
//! the application's actual output against, and the rows the offline
|
||||
//! `ALKANE_FAKE_SCAN` demo mode renders. Only miners that respond become rows,
|
||||
//! so there is no synthetic "offline" fixture.
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
# Getting started
|
||||
|
||||
Alkane Toolkit finds the ASIC miners on your network and shows them in one
|
||||
table: model, firmware, hashrate, power, temperatures, fans and the health of
|
||||
every hashboard. From the same table you can run the controls each miner's
|
||||
firmware supports, such as pausing, restarting or changing pools.
|
||||
|
||||
## Download
|
||||
|
||||
Get the latest release from the
|
||||
[downloads page](https://gitea.bluefla.re/blueflare/alkane-toolkit/releases).
|
||||
|
||||
| Platform | File | Notes |
|
||||
|---|---|---|
|
||||
| Windows 10 and 11 (x86_64) | `alkane-toolkit-vX.Y.Z-windows-x86_64.zip` | One signed `alkane-toolkit.exe`; nothing to install |
|
||||
| Linux (x86_64) | `alkane-toolkit-vX.Y.Z-linux-x86_64.tar.gz` | One binary; needs GTK 3 (`sudo apt install libgtk-3-0`) |
|
||||
|
||||
### Windows
|
||||
|
||||
1. Download the zip, right-click it, choose **Properties**, tick **Unblock** if
|
||||
it is shown, then extract it.
|
||||
2. Run `alkane-toolkit.exe`. Windows shows *BlueFlare Energy Solutions Inc.* as
|
||||
the verified publisher. To check the signature yourself, right-click the exe,
|
||||
choose **Properties** and open **Digital Signatures**.
|
||||
|
||||
### Linux
|
||||
|
||||
```sh
|
||||
tar xzf alkane-toolkit-vX.Y.Z-linux-x86_64.tar.gz
|
||||
./alkane-toolkit-vX.Y.Z-linux-x86_64/alkane-toolkit
|
||||
```
|
||||
|
||||
## First run
|
||||
|
||||
The toolkit starts a scan as soon as it opens. Set your own ranges first with
|
||||
**Scan ranges** (see [Scanning](02-scanning.md)); until you do, it scans a
|
||||
built-in default range.
|
||||
|
||||
To look around without touching any miner, start it in demo mode. It shows a
|
||||
built-in sample fleet and simulates every action:
|
||||
|
||||
| Platform | Command |
|
||||
|---|---|
|
||||
| Windows (Command Prompt) | `set ALKANE_FAKE_SCAN=1 && alkane-toolkit.exe` |
|
||||
| Linux | `ALKANE_FAKE_SCAN=1 ./alkane-toolkit` |
|
||||
|
||||
## Where settings are kept
|
||||
|
||||
| Platform | Folder |
|
||||
|---|---|
|
||||
| Windows | `%APPDATA%\alkane-toolkit` |
|
||||
| Linux | `~/.config/alkane-toolkit` |
|
||||
|
||||
See [Settings and credentials](06-settings.md) for the files in that folder.
|
||||
Deleting the folder resets the toolkit to its defaults.
|
||||
@@ -0,0 +1,51 @@
|
||||
# Scanning
|
||||
|
||||
Discovery is read-only: a scan asks each address what it is and records what
|
||||
it reports. It never changes a miner.
|
||||
|
||||
## Scan ranges
|
||||
|
||||
Click **Scan ranges** to edit the addresses to scan. Put one entry per line;
|
||||
blank lines and lines starting with `#` are ignored.
|
||||
|
||||
| Form | Example | Scans |
|
||||
|---|---|---|
|
||||
| Single address | `192.168.1.50` | that address |
|
||||
| CIDR block | `192.168.1.0/24` | the whole block |
|
||||
| Full range | `192.168.1.10-192.168.2.40` | every address between the two, inclusive |
|
||||
| Short range | `192.168.1.10-90` | `.10` to `.90` within the same /24 |
|
||||
| Per-octet ranges | `10.1-4.0-1.1-255` | every combination (10.1.0.1 ... 10.4.1.255) |
|
||||
|
||||
Commas or spaces between several entries on one line are not accepted; use one
|
||||
line each. Duplicates are removed automatically. One line, and all lines
|
||||
together, may cover at most 1,000,000 addresses.
|
||||
|
||||
**Apply** saves the ranges and starts a scan. A mistake keeps the dialog open
|
||||
and the status bar explains it, for example `invalid range: bad octet range`.
|
||||
|
||||
The same dialog has three numbers:
|
||||
|
||||
| Field | Meaning | Default |
|
||||
|---|---|---|
|
||||
| Rescan (s) | seconds between automatic rescans; `0` turns auto-rescan off | 300 |
|
||||
| Timeout (s) | how long to wait for one miner (scans, refreshes, actions and log fetches) | 10 |
|
||||
| Concurrency | how many addresses are probed at once (8 to 256); higher is faster but slow miners may report fewer values | 128 |
|
||||
|
||||
When the ranges change, miners outside the new ranges leave the table at the
|
||||
next scan.
|
||||
|
||||
## Running, pausing and stopping
|
||||
|
||||
The three buttons next to **Scan ranges** control scanning:
|
||||
|
||||
- **Play** (green) turns auto-rescan on and starts a scan now if none is running.
|
||||
- **Pause** (amber) turns auto-rescan off and lets the current scan finish.
|
||||
- **Stop** (red) turns auto-rescan off and cancels the current scan.
|
||||
|
||||
While a scan runs, a progress bar spans the top of the table and the status bar
|
||||
shows progress such as `1935/4590 - scanning 192.168.1.86 (92 found)`. Afterwards
|
||||
it shows the count and the time to the next scan, for example
|
||||
`245 miners - next scan in 4m 12s`.
|
||||
|
||||
Actions that change miners wait for the scan to finish; see
|
||||
[Actions](05-actions.md).
|
||||
@@ -0,0 +1,80 @@
|
||||
# The table and header
|
||||
|
||||
## Summary cards
|
||||
|
||||
The cards at the top count the miners **currently shown** (after any filter).
|
||||
Each miner is in exactly one status: slow, paused, hashing or not hashing.
|
||||
|
||||
| Card | Counts | Click |
|
||||
|---|---|---|
|
||||
| Total | rows in the view | - |
|
||||
| Hashing (green rabbit) | mining at 80% of expected hashrate or more | show only these; click again to clear |
|
||||
| Slow (amber turtle) | mining below 80% of expected hashrate | show only these |
|
||||
| Not hashing (red glass) | answering but not mining | show only these |
|
||||
| Paused (blue otter) | stopped on purpose (paused, stopped, suspended) | show only these |
|
||||
| SHA-256 Hashrate | total hashrate, per algorithm | switch algorithm when the fleet runs more than one |
|
||||
| Est. power | total reported power draw | - |
|
||||
|
||||
On a narrow window the hashrate and power cards are hidden.
|
||||
|
||||
## Columns
|
||||
|
||||
IP is always the first column. The default view shows Model, Health,
|
||||
Hashrate, Power, Chip temp, Firmware, CPU, Access and Light. More than seventy
|
||||
other columns are available, grouped as Identity, Firmware and board, Health
|
||||
and status, Performance, Temperature, Cooling, Hardware and Pools.
|
||||
|
||||
- **Columns** opens a checklist: tick to show, drag to reorder, or sort the list
|
||||
alphabetically or by category. *Hide columns with no scanned values* hides
|
||||
columns that are empty for every miner (it resets when the app restarts).
|
||||
- Drag a column header to move it.
|
||||
- Right-click a header to sort by it, auto-size one or all columns, hide it, or
|
||||
open the column chooser.
|
||||
|
||||
Some values worth knowing:
|
||||
|
||||
| Column | Shows |
|
||||
|---|---|
|
||||
| Hashrate | actual/expected, for example `95.0T/96.0T`; the actual part is red at 50% of expected or less, amber around 75%, green at 100% |
|
||||
| Chip temp | hottest chip on each hashboard, for example `77 / 64 / 74`; blue when cool, red at 90 C and above |
|
||||
| Firmware | the firmware family, coloured (Braiins purple, LuxOS gold, VNish green, ePIC light blue, Hiveon orange, Bixbit pink); stock firmware uses the normal text colour |
|
||||
| Pool account / Worker | the pool user split at the first dot |
|
||||
| Board HR / V / freq | per-hashboard hashrate, voltage and frequency |
|
||||
|
||||
A blank cell means the miner did not report that value.
|
||||
|
||||
## Sorting
|
||||
|
||||
Click a header to sort ascending, again for descending, again to clear.
|
||||
|
||||
- **Hashrate** also sorts by *relative* hashrate (actual as a share of
|
||||
expected), shown as `%^` and `%v` in the header.
|
||||
- **Health** sorts by overall health, then by power (`Pwr`), fans (`Fan`) and
|
||||
hashboards (`Brd`). Ascending puts the most broken miners first.
|
||||
|
||||
## Selecting miners
|
||||
|
||||
Click a row to select it; Ctrl-click and Shift-click add to the selection, and
|
||||
you can drag across rows to select a block. The selection follows miners by IP,
|
||||
so it survives rescans. Double-click a row (or press Enter) to open the miner's
|
||||
web page in your browser. Right-click the selection for [actions](05-actions.md).
|
||||
|
||||
## Filters and presets
|
||||
|
||||
**Filter** keeps only the rows that match. Pick a column, then:
|
||||
|
||||
- for numbers: between, =, !=, >, >=, < or <= (blank cells never match);
|
||||
- for text: *is any of* (tick values; `(blank)` matches empty cells), contains,
|
||||
does not contain, begins with, ends with or equals (case does not matter).
|
||||
|
||||
Filters on different columns must all match. **Reset** clears them. Clicking a
|
||||
status card is a quick filter of its own.
|
||||
|
||||
**Presets** saves and loads whole views: column order and visibility, sort and
|
||||
filters. *Default* is built in and cannot be deleted; saving under an existing
|
||||
name replaces it.
|
||||
|
||||
## Zoom and theme
|
||||
|
||||
The slider in the bottom-right corner zooms the table: text, icons and column
|
||||
widths scale together. The window follows the system light or dark theme.
|
||||
@@ -0,0 +1,54 @@
|
||||
# Health, access and light
|
||||
|
||||
## The Health column
|
||||
|
||||
Each miner gets a row of icons, always in the same order, so problems line up
|
||||
across the table:
|
||||
|
||||
1. **Bolt**: the power supply
|
||||
2. **Brain**: the control board
|
||||
3. **Fan**: one icon per fan
|
||||
4. **Chip**: one icon per hashboard
|
||||
|
||||
Hover over any icon to see its details: PSU voltage and current, the fan speed,
|
||||
or a hashboard's actual and expected hashrate, frequency and voltage, and any
|
||||
fault message with its code.
|
||||
|
||||
| Colour | Meaning |
|
||||
|---|---|
|
||||
| Green | healthy |
|
||||
| Amber | working but below par (a slow board, a fan well below the others, a PSU fault while still mining) |
|
||||
| Red | detected but down (a faulted board, a stopped fan, a PSU that is not delivering) |
|
||||
| Grey | expected but not detected or not reachable |
|
||||
| Blue | the miner is paused, so its boards and stopped fans are idle on purpose |
|
||||
|
||||
How each part is judged:
|
||||
|
||||
- **Power** is green when the miner draws power, its PSU fan turns or it is
|
||||
mining; a reported PSU fault makes it amber (still mining) or red.
|
||||
- **Control board** is red for a control-board fault and amber for a
|
||||
miner-wide warning such as a high ambient temperature.
|
||||
- **Fans** are red at 0 rpm and amber below half the speed of the fastest fan.
|
||||
- **Hashboards** follow the status the miner reports for each board. When the
|
||||
firmware names the failing boards, only those turn red. A board the miner
|
||||
cannot see is grey.
|
||||
|
||||
While an action runs on a miner, its Health cell shows progress such as
|
||||
`restarting...` or `refreshing...`.
|
||||
|
||||
## Access
|
||||
|
||||
The padlock shows whether the toolkit can change the miner:
|
||||
|
||||
- **green, open**: changes are possible with the saved credentials;
|
||||
- **red, closed**: view only;
|
||||
- **blank**: not known yet.
|
||||
|
||||
After a scan the padlock is an estimate from what the firmware offers. Use
|
||||
**Check access (auth)** in the right-click menu for a real, read-only login
|
||||
test.
|
||||
|
||||
## Light
|
||||
|
||||
A flashing green-over-red dot means the miner's locate light is on. Turn it on
|
||||
or off with **Flash lights** / **Stop flashing lights**.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Actions
|
||||
|
||||
Right-click one or more selected miners for the actions menu. With several
|
||||
miners selected, labels show the count, for example *Restart (12)*. An action
|
||||
appears only when **every** selected miner's firmware supports it, so the menu
|
||||
changes with the selection.
|
||||
|
||||
| Action | What it does | Changes the miner |
|
||||
|---|---|---|
|
||||
| Open in browser | opens each miner's web page | no |
|
||||
| Refresh | re-reads just these miners | no |
|
||||
| Check access (auth) | tests whether the saved login is accepted | no |
|
||||
| View log (API)... | shows the first selected miner's log (WhatsMiner: its active fault codes) | no |
|
||||
| Restore to stock firmware... | removes aftermarket firmware; see [Restore to stock](07-restore.md) | yes, reboots |
|
||||
| Flash lights / Stop flashing lights | locate light on or off | yes, harmless |
|
||||
| Pause mining / Resume mining | stop or start hashing | yes |
|
||||
| Set tuning %... | tuning level, 0 to 100 | yes |
|
||||
| Set power target... | power target in watts; the prompt shows the current value and the allowed range | yes |
|
||||
| Set hashrate target... | hashrate target in TH/s, for firmware that tunes by hashrate | yes |
|
||||
| Set profile... | pick a firmware profile or preset (only profiles every selected miner has are listed) | yes |
|
||||
| Restart | reboot | yes |
|
||||
| Configure pools... | set up to three pools | yes |
|
||||
| Set timezone... | IANA time zone, for example `America/Edmonton` | yes |
|
||||
| Change password... | new web/API password | yes |
|
||||
| Factory reset... | wipes pools, tuning and network settings and reboots; the miner may come back on a new DHCP address | yes, destructive |
|
||||
|
||||
## Safety
|
||||
|
||||
- Pause, Resume, Restart and Factory reset ask for confirmation. Value prompts
|
||||
(tuning, targets, timezone, password) apply when you confirm the value.
|
||||
- Actions that change miners do not start while a scan is running, including an
|
||||
automatic rescan. Wait for it to finish or press **Pause**. Scans in turn wait
|
||||
for running actions.
|
||||
- Each changed miner is re-read automatically when the action finishes. Results
|
||||
and failures appear in the bottom-right corner of the status bar and in
|
||||
**Settings > Logs**.
|
||||
- If **Change password** succeeds on every selected miner, the saved global
|
||||
login is updated to the new password. If only some succeed, the saved login
|
||||
is left alone and the log says so.
|
||||
|
||||
## Configuring pools
|
||||
|
||||
The pool dialog has three rows: Address, Account, Worker and Password. A row is
|
||||
used only when it has an address and an account. A blank password becomes `x`.
|
||||
The miner's username becomes `account.worker`.
|
||||
|
||||
Each field has a **+** menu with common pool addresses and the values you saved
|
||||
before (**Add new...** edits that list). Worker names can use placeholders that
|
||||
are filled in per miner:
|
||||
|
||||
| Placeholder | Becomes |
|
||||
|---|---|
|
||||
| `{ip1}` to `{ip4}` | one octet of the miner's IP |
|
||||
| `{serial}`, `{mac}` | serial number; MAC without colons |
|
||||
| `{hostname}` | the miner's hostname |
|
||||
| `{brand}`, `{model}`, `{submodel}` | make and model |
|
||||
| `{firmware}`, `{cpu}`, `{cb}` | firmware family, control-board CPU and board |
|
||||
| `{nameplate-hr}` | the model's rated hashrate |
|
||||
|
||||
For example, `rack3-{ip3}-{ip4}` gives `rack3-1-50` for `10.0.1.50`.
|
||||
@@ -0,0 +1,69 @@
|
||||
# Settings and credentials
|
||||
|
||||
**Settings** opens a menu with Credentials, Language and Logs.
|
||||
|
||||
## Credentials
|
||||
|
||||
Miners need a login for anything beyond basic discovery: for some details, and
|
||||
for every action. The Credentials dialog has two parts:
|
||||
|
||||
- **All firmwares** at the top: one username and password tried on every miner.
|
||||
The saved password is never shown; leave the field blank to keep it. Blank
|
||||
username and password clear it.
|
||||
- **One row per firmware**, pre-filled with that firmware's factory default.
|
||||
Change a row to override the login for that firmware only.
|
||||
|
||||
The toolkit tries, in order, the firmware's own row, then the global login,
|
||||
then the firmware's built-in default.
|
||||
|
||||
| Firmware | Factory default (user / password) |
|
||||
|---|---|
|
||||
| AntMiner Stock | root / root |
|
||||
| WhatsMiner Stock | admin / admin |
|
||||
| Braiins | root / root |
|
||||
| VNish | (none) / admin |
|
||||
| LuxOS | root / root |
|
||||
| UMC OS | (none) / letmein |
|
||||
| Marathon | root / root |
|
||||
| VolcMiner Stock | root / ltc@dog |
|
||||
| Elphapex Stock | root / root |
|
||||
| FutureBit Stock | futurebit / futurebit123 |
|
||||
| SealMiner Stock | seal / seal |
|
||||
| Auradine Stock | admin / admin |
|
||||
|
||||
**Reset to defaults** clears every override and the global login at once.
|
||||
|
||||
Logins are stored as plain text in the settings folder, readable only by your
|
||||
user account (Linux file mode 0600; on Windows, your profile folder's
|
||||
permissions).
|
||||
|
||||
### SSH login
|
||||
|
||||
Restoring Braiins to stock runs a command over SSH, using the system `ssh`
|
||||
client (built into Windows 10/11). There is no dialog for this login yet:
|
||||
create `ssh-credentials.txt` in the settings folder with the username on the
|
||||
first line and the password on the second.
|
||||
|
||||
## Language
|
||||
|
||||
English, Chinese, Russian, French, Spanish and Portuguese. The toolbar, cards
|
||||
and column headers switch immediately; menus and dialogs not yet translated
|
||||
stay in English.
|
||||
|
||||
## Logs
|
||||
|
||||
An activity log of scans, actions, errors and exports, newest last, kept for
|
||||
the current session (the last 2000 lines). Times are shown in UTC.
|
||||
|
||||
## Files in the settings folder
|
||||
|
||||
| File | Holds |
|
||||
|---|---|
|
||||
| `scan-ranges.txt` | scan ranges, one per line |
|
||||
| `auto-rescan-secs.txt`, `scan-timeout-secs.txt`, `scan-concurrency.txt` | the three scan numbers |
|
||||
| `scan-credentials.txt` | global login |
|
||||
| `firmware-credentials.txt` | per-firmware logins |
|
||||
| `ssh-credentials.txt` | SSH login (created by hand) |
|
||||
| `presets.json` | saved views |
|
||||
| `language.txt` | UI language |
|
||||
| `pool-addresses.txt`, `pool-accounts.txt`, `pool-workers.txt`, `pool-passwords.txt` | saved pool values |
|
||||
@@ -0,0 +1,18 @@
|
||||
# Restore to stock firmware
|
||||
|
||||
**Restore to stock firmware...** removes aftermarket firmware and returns the
|
||||
miner to the manufacturer's firmware it keeps on board. Nothing is uploaded.
|
||||
The miner reboots, and some firmwares come back on a new address.
|
||||
|
||||
It is offered when the selection includes a supported firmware, and asks for
|
||||
confirmation with the list of miners first.
|
||||
|
||||
| Firmware | How it is removed | Login used |
|
||||
|---|---|---|
|
||||
| VNish (and builds based on it) | web API: unlock, then remove firmware; reboots in seconds | the VNish row in Credentials, else `admin` |
|
||||
| LuxOS | miner API: log on, then uninstall | none |
|
||||
| Braiins OS | SSH: runs the firmware's own `uninstall.sh` | `ssh-credentials.txt` (see [Settings](06-settings.md)) |
|
||||
|
||||
Miners are restored one at a time. A dropped connection after the command is
|
||||
sent counts as success, because that is the reboot. A refused login counts as
|
||||
a failure and leaves the miner unchanged.
|
||||
@@ -0,0 +1,14 @@
|
||||
# Export
|
||||
|
||||
**Export** saves the scan as a CSV file for spreadsheets or other tools.
|
||||
|
||||
1. Choose the fields to include (all are ticked by default; **All** and
|
||||
**None** help).
|
||||
2. Pick where to save. The suggested name is `alkane-export-YYYYMMDD-HHMMSS.csv`.
|
||||
|
||||
The export contains **every scanned miner**, not just the rows the current
|
||||
filter shows. Per-board temperatures, fan speeds, board status and pools
|
||||
become numbered columns (`board_temp_1_c`, `fan_2_rpm`, `pool_1_url`, ...).
|
||||
|
||||
Values that start with `=`, `+`, `-` or `@` are prefixed with `'` so a
|
||||
spreadsheet treats them as text, not formulas.
|
||||
@@ -0,0 +1,32 @@
|
||||
# Command line and environment
|
||||
|
||||
## Environment variables
|
||||
|
||||
| Variable | Effect |
|
||||
|---|---|
|
||||
| `ALKANE_FAKE_SCAN=1` | demo mode: a built-in sample fleet, no network traffic, simulated actions |
|
||||
| `ALKANE_APPEARANCE=light` or `dark` | force the light or dark theme |
|
||||
| `ALKANE_SELFTEST=1` | run the built-in UI self-test on the sample fleet and exit (prints `SELFTEST PASS` or `FAIL`) |
|
||||
| `ALKANE_ACCESS_PROBE="<ip> <make>"` | print whether the saved login can change that miner, then exit |
|
||||
| `ALKANE_LOG_SCAN="<ip> <brand>"` | fetch that miner's log through its API, print the size, then exit |
|
||||
|
||||
On Windows these one-shot modes print to the Command Prompt they are started
|
||||
from.
|
||||
|
||||
## miner_probe
|
||||
|
||||
`miner_probe` is a command-line companion for scripting and diagnosis. These
|
||||
commands only read:
|
||||
|
||||
| Command | Prints |
|
||||
|---|---|
|
||||
| `miner_probe scan <cidr> [<cidr>...]` | discovered miners and their telemetry, as tab-separated values |
|
||||
| `miner_probe hashrate <cidr>...` | raw hashrate and algorithm |
|
||||
| `miner_probe msgs <ip>` | fault messages and per-board data |
|
||||
| `miner_probe tune <ip>` | tuning support and limits |
|
||||
| `miner_probe presets <ip>` | available firmware profiles |
|
||||
| `miner_probe timezone <ip>` | the current time zone |
|
||||
|
||||
Its other commands change miners. It uses the global login from the settings
|
||||
folder, or `ALKANE_PROBE_USER` and `ALKANE_PROBE_PASS`, and
|
||||
`ALKANE_PROBE_CONCURRENCY` (default 128).
|
||||
@@ -0,0 +1,28 @@
|
||||
# Troubleshooting
|
||||
|
||||
**Windows says "Windows protected your PC".** SmartScreen warns about new
|
||||
downloads until a certificate has built up reputation. The publisher shown
|
||||
should be *BlueFlare Energy Solutions Inc.*; click **More info**, then **Run
|
||||
anyway**. If no publisher is shown, do not run the file and download it again
|
||||
from the releases page.
|
||||
|
||||
**A miner is missing.** Check that its address is inside the scan ranges and
|
||||
that it answers on its web page from this computer. On busy or slow networks,
|
||||
raise **Timeout** or lower **Concurrency** in the Scan ranges dialog.
|
||||
|
||||
**An action is missing from the right-click menu.** Actions appear only when
|
||||
every selected miner supports them. Select fewer miners, or only miners with
|
||||
the same firmware.
|
||||
|
||||
**An action does nothing and the status says a scan is in progress.** Changes
|
||||
wait for scans. Press **Pause**, let the scan finish, then try again.
|
||||
|
||||
**Check access says locked.** The saved login is not accepted. Set the right
|
||||
password in **Settings > Credentials**, either for all firmwares or for that
|
||||
firmware's row.
|
||||
|
||||
**Values are blank.** The firmware did not report them, or it needs a login to
|
||||
report them. Try **Check access** and the Credentials dialog.
|
||||
|
||||
**The window is too small or too large.** It opens at most as large as your
|
||||
screen's work area. Use the zoom slider in the status bar to scale the table.
|
||||
+1
-2
@@ -99,8 +99,7 @@ AZURE_SIGNING_TOKEN=$(az account get-access-token --resource https://codesigning
|
||||
## Native Windows runner
|
||||
|
||||
`windows-native.yml` runs on the self-hosted runner `win11-test-vm`
|
||||
(label `alkane-windows`, host mode) inside the Windows 11 test VM
|
||||
(a local test VM). It downloads the
|
||||
(label `alkane-windows`, host mode) inside a Windows 11 test VM. It downloads the
|
||||
`alkane-toolkit-windows-tests` artifact of the triggering main run, runs every
|
||||
test executable and the UI self-test natively, and never blocks a release:
|
||||
while the VM is off, the job waits for the runner.
|
||||
|
||||
Reference in New Issue
Block a user