htoprs 0.5.3

A faithful Rust port of htop — the interactive process viewer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

<!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 — a faithful Rust port of htop, the interactive process viewer. The htop 3.5.1 C source is the spec; every function under src/ported/ ports a specific htop C function, cited by File.c:line, enforced by a build-time port-purity gate.">
  <title>htoprs — Documentation</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&amp;family=Share+Tech+Mono&amp;display=swap" rel="stylesheet">
  <link rel="stylesheet" href="hud-static.css">
  <link rel="stylesheet" href="tutorial.css">
  <style>
    .tutorial-main { max-width: 68rem; }
    .docs-build-line {
      margin: 0.35rem 0 0;
      font-family: 'Share Tech Mono', ui-monospace, monospace;
      font-size: 11px;
      color: var(--text-dim);
      letter-spacing: 0.03em;
      max-width: 46rem;
      opacity: 0.75;
    }
    .example-tbl { width: 100%; border-collapse: collapse; margin: 0.6rem 0; font-size: 12.5px; }
    .example-tbl td {
      padding: 6px 10px;
      border: 1px solid var(--border);
      vertical-align: top;
      color: var(--text-dim);
    }
    .example-tbl td:first-child { width: 40%; color: var(--cyan); font-family: 'Share Tech Mono', monospace; }
    .example-tbl td code { color: var(--accent-light); background: var(--bg); padding: 1px 5px; font-size: 12px; }
  </style>
</head>
<body>
  <div class="app tutorial-app" id="docsApp">
    <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 &mdash; A FAITHFUL RUST PORT OF HTOP</h1>
          <nav class="tutorial-crumbs" aria-label="Breadcrumb">
            <span class="current">Docs</span>
            <span class="sep">/</span>
            <a href="report.html">Engineering report</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 class="docs-build-line">faithful port &middot; htop 3.5.1 is the spec &middot; C source at ~/forkedRepos/htop &middot; function-for-function, cited File.c:line &middot; 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="report.html">Report</a>
          <a class="btn btn-secondary" href="port_report.html">Port report</a>
          <a class="btn btn-secondary" href="https://github.com/MenkeTechnologies/htoprs" target="_blank" rel="noopener noreferrer">GitHub</a>
        </div>
      </div>
    </header>

    <main class="tutorial-main">
      <h2 class="tutorial-title"><span class="step-hash">&gt;_</span>HTOPRS</h2>
      <p class="tutorial-subtitle"><strong>The htop C source is the spec.</strong> htoprs is a faithful Rust port of <a href="https://github.com/htop-dev/htop" target="_blank" rel="noopener noreferrer">htop</a>, the interactive process viewer. The upstream C is translated <strong>function-for-function</strong>, never reimplemented from scratch. Every function under <code>src/ported/</code> ports a specific htop C function and cites its origin (<code>&lt;File&gt;.c:&lt;line&gt;</code>) in its doc comment.</p>

      <section class="tutorial-section">
        <h2>Porting methodology</h2>
        <table class="example-tbl">
          <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 / …)</td></tr>
            <tr><td>Port tree</td><td><code>src/ported/&lt;file&gt;.rs</code> &mdash; one Rust module per C file; each <code>fn</code> cites <code>/// Port of</code> its <code>&lt;File&gt;.c:&lt;line&gt;</code> origin</td></tr>
            <tr><td>Port-purity gate</td><td><code>build.rs</code> checks every free <code>fn</code> name under <code>src/ported/</code> against the htop C-function snapshot; a name with no C counterpart 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> after pulling upstream htop</td></tr>
            <tr><td>Allowlist</td><td><code>tests/data/fake_fn_allowlist.txt</code> &mdash; genuine Rust-only architectural helpers only, each justified</td></tr>
            <tr><td>Port report</td><td><code>scripts/gen_port_report.py</code> &rarr; <a href="port_report.html">port_report.html</a>, per-file + overall coverage derived from source at run time</td></tr>
          </tbody>
        </table>
      </section>

      <section class="tutorial-section">
        <h2>Ported so far &mdash; <code>891 / 1093</code> C functions (81.5%)</h2>
        <p>121 of htop's 131 C files are started; 31 stubs remain. The authoritative per-file, per-function breakdown is the <a href="port_report.html">port report</a>, generated from source. By subsystem:</p>
        <table class="example-tbl">
          <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></td></tr>
            <tr><td>Containers &amp; utils</td><td><code>Vector</code>, <code>Hashtable</code>, <code>RichString</code>, <code>XUtils</code></td></tr>
            <tr><td>Meters</td><td><code>Meter</code> + CPU / Memory / Swap / Load / Battery / Network / DiskIO / GPU / ZFS / dynamic</td></tr>
            <tr><td>UI panels</td><td><code>Panel</code> / <code>ScreenManager</code> / <code>MainPanel</code> / <code>FunctionBar</code> / <code>Header</code> + setup panels</td></tr>
            <tr><td>Screens &amp; input</td><td><code>Action</code>, <code>IncSet</code>, <code>LineEditor</code>, trace / env / open-files / process-locks screens</td></tr>
            <tr><td>ncurses shim</td><td><code>CRT</code> &mdash; crossterm-backed colors, mouse, key decode</td></tr>
            <tr><td>Platforms</td><td>darwin / linux / freebsd / netbsd / openbsd / dragonflybsd / solaris</td></tr>
          </tbody>
        </table>
      </section>

      <section class="tutorial-section">
        <h2>htoprs-original extensions</h2>
        <p>On top of the faithful port, an <code>src/extensions/</code> layer (18 modules, exempt from the port-purity gate) adds capabilities htop lacks &mdash; htoprs-original, not translations of htop C.</p>
        <table class="example-tbl">
          <tbody>
            <tr><td>Theming</td><td>31 named color schemes, live chooser / editor overlay (<code>c</code> / <code>C</code>), 256-color UI recolor, persisted to prefs</td></tr>
            <tr><td>Monitoring</td><td>Per-PID history rings, threshold alerts (<code>A</code>), fuzzy finder (<code>f</code>), regex filters (<code>r</code>), snapshot diffs (<code>d</code>), JSON/CSV export (<code>o</code>)</td></tr>
            <tr><td>Braille graphs</td><td>Full 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>Themed help overlay (<code>h</code>/<code>?</code>), border toggle (<code>B</code>), bar-fill-glyph cycler (<code>b</code>)</td></tr>
          </tbody>
        </table>
      </section>

      <section class="tutorial-section">
        <h2>Build &amp; test</h2>
<pre>cargo build          # runs the port-purity gate
cargo test           # hand-crafted unit tests pin the C edge behavior
python3 scripts/gen_port_report.py   # regenerate docs/port_report.html</pre>
        <p>The snapshot is regenerated with <code>HTOP_C_SOURCE=~/forkedRepos/htop tests/data/extract_c_fn_names.sh</code> after pulling new upstream htop commits.</p>
      </section>

      <section class="tutorial-section">
        <h2>The MenkeTechnologies stack</h2>
        <p>htoprs follows the same faithful-port precedent as <a href="https://github.com/MenkeTechnologies/zshrs" target="_blank" rel="noopener noreferrer">zshrs</a> (the first compiled Unix shell, a 1:1 port of zsh's C). Browse the rest via the <a href="https://github.com/MenkeTechnologies/MenkeTechnologiesMeta" target="_blank" rel="noopener noreferrer">MenkeTechnologiesMeta</a> umbrella repo.</p>
      </section>

    </main>
  </div>
  <script src="hud-theme.js"></script>
</body>
</html>