htoprs 0.3.0

A faithful Rust port of htop — the interactive process viewer
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

<!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>XUtils.c</code></h2>
        <p>htop's string and math utility layer. The pure string/math functions port faithfully; the C allocation wrappers, null-terminated helpers, varargs formatters, and <code>String_freeArray</code> have no faithful safe-Rust analog (Rust owns its allocation, bounds, and lifetimes) and are intentionally not ported.</p>
        <table class="example-tbl">
          <tbody>
            <tr><td><code>String_cat</code></td><td>concatenation</td></tr>
            <tr><td><code>String_trim</code></td><td>trims leading/trailing space, tab, newline (only those three)</td></tr>
            <tr><td><code>String_split</code></td><td>splits on a separator; interior empties kept, trailing empty dropped</td></tr>
            <tr><td><code>String_splitFirst</code></td><td>splits on the first separator only</td></tr>
            <tr><td><code>String_contains_i</code></td><td>case-insensitive substring; pipe-separated multi-needle mode</td></tr>
            <tr><td><code>compareRealNumbers</code></td><td>NaN-aware ordering (NaN sorts first)</td></tr>
            <tr><td><code>sumPositiveValues</code></td><td>sum of strictly-positive values, NaN skipped</td></tr>
            <tr><td><code>countDigits</code></td><td>digit count in a given base, with overflow guard</td></tr>
            <tr><td><code>countTrailingZeros</code></td><td>mod-37 lowest-set-bit table</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>