<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="color-scheme" content="dark light">
<meta name="description" content="htoprs — engineering report. A faithful Rust port of htop 3.5.1. Porting methodology, the build-time port-purity gate, coverage against the C spec, and project metadata.">
<title>htoprs — Engineering Report</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Orbitron:wght@400;600;700;900&family=Share+Tech+Mono&display=swap" rel="stylesheet">
<link rel="stylesheet" href="hud-static.css">
<link rel="stylesheet" href="tutorial.css">
<style>
.tutorial-main { max-width: 68rem; }
.stat-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(11rem, 1fr));
gap: 0.5rem;
margin: 1rem 0;
}
.stat-card {
border: 1px solid var(--border);
border-left: 2px solid var(--cyan);
padding: 0.65rem 0.85rem;
background: color-mix(in srgb, var(--bg-card) 92%, transparent);
border-radius: 2px;
}
.stat-val {
font-family: 'Orbitron', sans-serif;
font-size: 20px;
font-weight: 700;
color: var(--accent);
}
.stat-val.cyan { color: var(--cyan); }
.stat-val.green { color: var(--green); }
.stat-label {
font-family: 'Share Tech Mono', monospace;
font-size: 10px;
text-transform: uppercase;
letter-spacing: 1.2px;
color: var(--text-dim);
margin-top: 0.2rem;
}
.arch-table { width: 100%; border-collapse: collapse; margin: 0.6rem 0; font-size: 12.5px; }
.arch-table th {
background: var(--bg-secondary);
color: var(--cyan);
font-family: 'Orbitron', sans-serif;
font-size: 10px;
font-weight: 700;
letter-spacing: 1px;
text-transform: uppercase;
text-align: left;
padding: 6px 10px;
border: 1px solid var(--border);
}
.arch-table td { padding: 6px 10px; border: 1px solid var(--border); color: var(--text-dim); vertical-align: top; }
.arch-table td code { color: var(--accent-light); background: var(--bg); padding: 1px 4px; }
.section-rule { border: 0; border-top: 1px dashed var(--border); margin: 2rem 0 1.5rem; }
</style>
</head>
<body>
<div class="app tutorial-app" id="reportApp">
<div class="crt-scanline" id="crtH" aria-hidden="true"></div>
<div class="crt-scanline-v" id="crtV" aria-hidden="true"></div>
<header class="tutorial-header">
<div class="tutorial-header-inner">
<div>
<h1 class="tutorial-brand">// HTOPRS — ENGINEERING REPORT</h1>
<nav class="tutorial-crumbs" aria-label="Breadcrumb">
<span class="current">Engineering Report</span>
<span class="sep">/</span>
<a href="index.html">Docs</a>
<span class="sep">/</span>
<a href="port_report.html">Port report</a>
<span class="sep">/</span>
<a href="https://github.com/MenkeTechnologies/htoprs" target="_blank" rel="noopener noreferrer">GitHub</a>
<span class="sep">/</span>
<a href="https://github.com/MenkeTechnologies/MenkeTechnologiesMeta" target="_blank" rel="noopener noreferrer">Meta</a>
</nav>
<p style="margin:0.35rem 0 0;font-family:'Share Tech Mono',monospace;font-size:11px;color:var(--text-dim);letter-spacing:0.03em;opacity:0.75;">
Faithful port · htop 3.5.1 is the spec · function-for-function, cited File.c:line · build-time port-purity gate
</p>
</div>
<div class="tutorial-toolbar">
<button type="button" class="btn btn-secondary" id="btnTheme" title="Toggle light/dark">Theme</button>
<button type="button" class="btn btn-secondary active" id="btnCrt" title="CRT scanline overlay">CRT</button>
<button type="button" class="btn btn-secondary active" id="btnNeon" title="Neon border pulse">Neon</button>
<a class="btn btn-secondary" href="index.html">Docs</a>
<a class="btn btn-secondary" href="port_report.html">Port report</a>
</div>
</div>
</header>
<main class="tutorial-main">
<h2 class="tutorial-title"><span class="step-hash">>_</span>EXECUTIVE SUMMARY</h2>
<p class="tutorial-subtitle"><strong>htoprs</strong> is a faithful Rust port of <a href="https://github.com/htop-dev/htop" target="_blank" rel="noopener noreferrer">htop</a> 3.5.1, the interactive process viewer. The upstream C source is the specification — the port is translated function-for-function, never reimplemented from scratch, the same precedent as <a href="https://github.com/MenkeTechnologies/zshrs" target="_blank" rel="noopener noreferrer">zshrs</a>.</p>
<p class="tutorial-subtitle">Fidelity is enforced mechanically: a build-time port-purity gate rejects any free <code>fn</code> under <code>src/ported/</code> whose name has no counterpart in the htop C source. The port now covers <strong>121 of the 131 C files</strong> — <strong>891 of 1093 C functions (81.5%)</strong>, with 31 remaining stubs. On top of the port sits an <strong>htoprs-original extensions layer</strong> (18 modules, exempt from the port-purity gate) providing a named color-theme system, a keyboard-help/theme overlay, and a live monitoring suite (per-PID history rings, threshold alerts, braille CPU graphs, a fuzzy finder, snapshot diffs, and exporters). Live coverage per file is in the <a href="port_report.html">port report</a>.</p>
<div class="stat-grid">
<div class="stat-card"><div class="stat-val">v0.5.0</div><div class="stat-label">Version</div></div>
<div class="stat-card"><div class="stat-val cyan">3.5.1</div><div class="stat-label">htop spec</div></div>
<div class="stat-card"><div class="stat-val cyan">131</div><div class="stat-label">C source files</div></div>
<div class="stat-card"><div class="stat-val">1093</div><div class="stat-label">C fns defined</div></div>
<div class="stat-card"><div class="stat-val green">891</div><div class="stat-label">Fns ported</div></div>
<div class="stat-card"><div class="stat-val green">81.5%</div><div class="stat-label">Coverage</div></div>
<div class="stat-card"><div class="stat-val cyan">145</div><div class="stat-label">src .rs files</div></div>
<div class="stat-card"><div class="stat-val">88.9k</div><div class="stat-label">Source lines</div></div>
</div>
<hr class="section-rule">
<h2 class="tutorial-title"><span class="step-hash">~</span>PORTING METHODOLOGY</h2>
<p class="tutorial-subtitle">The C source is the spec. Ports are faithful; the original C is translated function-for-function. The gate keeps the port from drifting into a reimplementation.</p>
<table class="arch-table">
<thead><tr><th>Layer</th><th>Implementation</th></tr></thead>
<tbody>
<tr><td>Spec</td><td>htop <strong>3.5.1</strong> at <code>~/forkedRepos/htop</code> — 131 <code>.c</code> files, platform-split (darwin / linux / freebsd / netbsd / openbsd / dragonflybsd / solaris / pcp)</td></tr>
<tr><td>Port tree</td><td><code>src/ported/<file>.rs</code>, one Rust module per C file; every <code>fn</code> carries a <code>/// Port of</code> citation naming its <code><File>.c:<line></code> origin</td></tr>
<tr><td>Port-purity gate</td><td><code>build.rs</code> (std-only) scans <code>src/ported/</code> on every <code>cargo build</code> / <code>test</code> / <code>check</code>; a free <code>fn</code> whose name is absent from <code>tests/data/htop_c_fn_names.txt</code> and the allowlist fails the build — cannot be bypassed by <code>cargo test --test X</code></td></tr>
<tr><td>C-name snapshot</td><td><code>tests/data/htop_c_fn_names.txt</code>, regenerated by <code>tests/data/extract_c_fn_names.sh</code> (<code>HTOP_C_SOURCE=~/forkedRepos/htop</code>) after pulling upstream htop</td></tr>
<tr><td>Allowlist</td><td><code>tests/data/fake_fn_allowlist.txt</code> — genuine Rust-only architectural helpers only, each justified inline; currently empty</td></tr>
<tr><td>Port report</td><td><code>scripts/gen_port_report.py</code> → <a href="port_report.html">port_report.html</a>, per-file + overall coverage derived from source at run time (nothing hardcoded)</td></tr>
</tbody>
</table>
<hr class="section-rule">
<h2 class="tutorial-title"><span class="step-hash">&</span>PORTED SUBSYSTEMS</h2>
<p>121 of the 131 C files are started (81.5% of functions). The authoritative per-file, per-function breakdown is the <a href="port_report.html">port report</a>, generated from source; this table groups the port by subsystem.</p>
<table class="arch-table">
<thead><tr><th>Subsystem</th><th>Ported layer</th></tr></thead>
<tbody>
<tr><td>Core model</td><td><code>Process</code> / <code>ProcessTable</code> / <code>Table</code> / <code>Row</code> / <code>Machine</code> / <code>Object</code> / <code>Settings</code> — the process model, table build, and settings</td></tr>
<tr><td>Containers & utils</td><td><code>Vector</code>, <code>Hashtable</code>, <code>RichString</code>, <code>XUtils</code> — sort/search, prime-table, attributed strings, string/math helpers</td></tr>
<tr><td>Meters</td><td><code>Meter</code> plus CPU / Memory / Swap / Load / Battery / Network / DiskIO / GPU / ZFS / DateTime / Uptime / Tasks / dynamic meters</td></tr>
<tr><td>UI panels</td><td><code>Panel</code> / <code>ScreenManager</code> / <code>MainPanel</code> / <code>FunctionBar</code> / <code>Header</code> and the setup / columns / colors / display-options / affinity / signals panels</td></tr>
<tr><td>Screens & input</td><td><code>Action</code> key dispatch, <code>IncSet</code>, <code>LineEditor</code>, and the trace / env / info / open-files / process-locks screens</td></tr>
<tr><td>ncurses shim</td><td><code>CRT</code> — the crossterm-backed terminal layer (colors, mouse, key decode)</td></tr>
<tr><td>Platforms</td><td>darwin / linux / freebsd / netbsd / openbsd / dragonflybsd / solaris machine & process-table backends</td></tr>
</tbody>
</table>
<p>The C allocation / memory machinery (the <code>xMalloc</code> family, the raw <code>Object**</code> dynamic array, the open-addressing bucket table), the null-terminated-string helpers, and the varargs formatters have no faithful safe-Rust analog (Rust's <code>Vec</code> / <code>HashMap</code> / <code>String</code> own allocation, bounds, probing, and lifetimes) and are intentionally not ported. The remaining 31 stubs and un-started files are tracked in the <a href="port_report.html">port report</a>.</p>
<hr class="section-rule">
<h2 class="tutorial-title"><span class="step-hash">+</span>HTOPRS-ORIGINAL EXTENSIONS</h2>
<p>Beyond the faithful port, an <code>src/extensions/</code> layer (18 modules, exempt from the port-purity gate) adds capabilities htop lacks. These are htoprs-original, not translations of htop C.</p>
<table class="arch-table">
<thead><tr><th>Area</th><th>Capability</th></tr></thead>
<tbody>
<tr><td>Theming</td><td>31 named color schemes with a live chooser / editor overlay (<code>c</code> / <code>C</code>), recoloring the ncurses UI in 256-color; persisted to <code>~/.config/htoprs/prefs.json</code></td></tr>
<tr><td>Monitoring</td><td>Per-PID CPU/mem history rings, debounced threshold alerts (<code>A</code>), a fuzzy process finder (<code>f</code>), regex filters (<code>r</code>), snapshot diffs (<code>d</code>), and JSON/CSV export (<code>o</code>)</td></tr>
<tr><td>Braille graphs</td><td>A full braille CPU history graph (<code>G</code>) and an inline per-process CPU graph whose height scales with load (<code>v</code>)</td></tr>
<tr><td>Chrome</td><td>A themed help overlay (<code>h</code>/<code>?</code>), a border toggle (<code>B</code>), and a bar-fill-glyph cycler (<code>b</code>)</td></tr>
</tbody>
</table>
<hr class="section-rule">
<h2 class="tutorial-title"><span class="step-hash">$</span>CI GATES</h2>
<table class="arch-table">
<thead><tr><th>Gate</th><th>Command</th></tr></thead>
<tbody>
<tr><td>port-purity</td><td><code>cargo build</code> (build.rs rejects any non-htop <code>fn</code> under <code>src/ported/</code>)</td></tr>
<tr><td>test</td><td><code>cargo test</code> — hand-crafted unit tests pin the C edge behavior</td></tr>
<tr><td>fmt</td><td><code>cargo fmt --all --check</code></td></tr>
</tbody>
</table>
<hr class="section-rule">
<h2 class="tutorial-title"><span class="step-hash">#</span>PROJECT METADATA</h2>
<table class="arch-table">
<thead><tr><th>Item</th><th>Value</th></tr></thead>
<tbody>
<tr><td>Version</td><td>0.5.0</td></tr>
<tr><td>License</td><td>GPL-2.0-or-later (matching htop)</td></tr>
<tr><td>Spec</td><td>htop 3.5.1 — <a href="https://github.com/htop-dev/htop" target="_blank" rel="noopener noreferrer">github.com/htop-dev/htop</a></td></tr>
<tr><td>Precedent</td><td><a href="https://github.com/MenkeTechnologies/zshrs" target="_blank" rel="noopener noreferrer">zshrs</a> — the faithful-port + port-purity-gate pattern</td></tr>
<tr><td>Author</td><td><a href="https://github.com/MenkeTechnologies">MenkeTechnologies</a></td></tr>
<tr><td>Repository</td><td><a href="https://github.com/MenkeTechnologies/htoprs">github.com/MenkeTechnologies/htoprs</a></td></tr>
<tr><td>Meta umbrella</td><td><a href="https://github.com/MenkeTechnologies/MenkeTechnologiesMeta">MenkeTechnologiesMeta</a></td></tr>
</tbody>
</table>
</main>
</div>
<script src="hud-theme.js"></script>
</body>
</html>