<!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 is at an early stage — <code>XUtils.c</code>'s string/math utility layer is the first file landed.</p>
<div class="stat-grid">
<div class="stat-card"><div class="stat-val">v0.1.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">16</div><div class="stat-label">Fns ported</div></div>
<div class="stat-card"><div class="stat-val green">1.46%</div><div class="stat-label">Coverage</div></div>
<div class="stat-card"><div class="stat-val cyan">7</div><div class="stat-label">src .rs files</div></div>
<div class="stat-card"><div class="stat-val">797</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 FILES</h2>
<p>The pure-logic layers are ported first. The live per-function breakdown and coverage are in the <a href="port_report.html">port report</a>, derived from source at generation time; this table is the file-level summary.</p>
<table class="arch-table">
<thead><tr><th>C file</th><th>Ported layer</th></tr></thead>
<tbody>
<tr><td><code>XUtils.c</code></td><td>string / math utilities — <code>String_cat</code> / <code>_trim</code> / <code>_split</code> / <code>_splitFirst</code> / <code>_contains_i</code>, <code>compareRealNumbers</code>, <code>sumPositiveValues</code>, <code>countDigits</code>, <code>countTrailingZeros</code></td></tr>
<tr><td><code>Vector.c</code></td><td>container sort / search core — <code>swap</code>, <code>partition</code>, <code>quickSort</code>, <code>insertionSort</code>, <code>Vector_indexOf</code> (generics over a slice with a C-<code>int</code> comparator)</td></tr>
<tr><td><code>Hashtable.c</code></td><td>prime-table math — <code>nextPrime</code></td></tr>
<tr><td><code>Meter.c</code></td><td>value formatting — <code>Meter_humanUnit</code></td></tr>
</tbody>
</table>
<p>The C allocation / memory machinery (the <code>xMalloc</code> family and <code>String_freeArray</code>; the <code>Object**</code> dynamic array — <code>Vector_new</code> / <code>_insert</code> / <code>_resizeIfNecessary</code> …; the open-addressing bucket table — <code>Hashtable_new</code> / <code>_put</code> / <code>_get</code> …), 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.</p>
<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.1.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>