rickub
Sign in Get started
nandi/rustnimpublic⑂ Fork 0
⑂ 4e4d09dcdd22d17ba510de5639fc3a952ac73f6e
Branches
main View all branches → View all tags →
Commits
⬇ Clone ▾
git clone https://git.rickub.com/nandi/rustnim.git
git clone ssh://git@rickub.com/nandi/rustnim.git

Host key fingerprint (ed25519): SHA256:iycHnxEyq0Q7uyVpB7JlznP0G7JrTPXLYRcAU5CSLhc — verify it before your first connect.

README.md · 176 lines · 7.8 KBmarkdown Blame HistoryRaw
Add a README b66da6b nandithebull 8h ago1# rustnim
2
3A Rust → Nim transpiler. It parses Rust with `syn` and emits Nim source that
4behaves the same way — same stdout, same exit status — when both are built and
5run.
6
7The rule the whole thing is organised around: **never approximate a semantic
8you cannot represent.** If a construct doesn't map, `rustnim` says so and exits
9non-zero. It never writes a file it can't stand behind.
10
11That rule comes from a real failure. We tried an existing transpiler that
12advertises Rust support on the `base16ct` crate; it emitted an empty file and
13exited 0. The write-up is in [`findings/`](findings/).
14
15## Build and run
16
17```bash
18cargo build --release
19./target/release/rustnim input.rs -o out.nim
20nim c out.nim
21```
22
23Several inputs are concatenated into one Nim module, in the order given — Nim
24has no per-file `mod`, so items are flattened and names must not collide:
25
26```bash
27rustnim src/lib.rs src/error.rs --cfg feature=alloc -o crate.nim
28```
29
30## What works
31
32Functions and `impl` methods, structs, enums (C-like and data-carrying),
Add generics; transpile the part of cosmic-theme that is reachable ff34e1b nandithebull 6h ago33`Option`/`Result` with `?`, generics, `saturating_*`/`checked_*`,
34`let`/`let mut`, the integer and float operators at
Add a README b66da6b nandithebull 8h ago35exact widths, `as` casts, `if`/`while`/`loop`/`for`, `match` including binding
36patterns, `Vec`/slices/arrays, type aliases, function-typed parameters
37(`impl Fn(A) -> B`), multi-file input, `#[cfg]`, and `println!`/`format!` with
38`{}`, `{:?}`, `{:x}`, `{:b}`, positional and inline-named arguments, and
39zero/space padding.
40
Correct the README where trait impls and iterators are listed as rejected 428f374 nandithebull 8h ago41Also: the formatting trait impls (`Display`, `Debug`, `LowerHex`, `UpperHex`,
42`Binary`, `Octal`) and `From`; and slice iterators — `iter`, `iter_mut`,
43`enumerate`, `zip`, `chunks_exact`, `chunks_exact_mut`, `windows` — resolved
44into a single index loop where each binding is an lvalue into the original
45container, so `*d = v` through `iter_mut()` reaches the caller's slice.
46Borrowed slices are views, not copies, including as return types.
47
Add display.rs and the alloc half: all of base16ct now goes through afb2a6e nandithebull 7h ago48Closures and `unsafe` blocks, `&str` as a borrowed view rather than an owned
49copy, formatting impls whose `fmt` body writes repeatedly, and the
50`assert!`/`assert_eq!`/`debug_assert*` family. Modules: pass the crate root first and each further file after it,
Add closures and unsafe; base16ct's lower.rs and upper.rs go through 0a375d8 nandithebull 8h ago51and items are scoped by module, so `lower::decode` and `mixed::decode` stay
52distinct.
53
Correct the README where trait impls and iterators are listed as rejected 428f374 nandithebull 8h ago54Rejected with a reason, rather than guessed at: `i128`/`u128`, generics,
Add closures and unsafe; base16ct's lower.rs and upper.rs go through 0a375d8 nandithebull 8h ago55`move` closures, trait impls other than the ones above, iterator adaptors with
56no index-loop equivalent (`map`, `filter`, `take_while`), float→int casts, and
57any standard-library method that isn't mapped.
Correct the README where trait impls and iterators are listed as rejected 428f374 nandithebull 8h ago58
59## base16ct
60
Add display.rs and the alloc half: all of base16ct now goes through afb2a6e nandithebull 7h ago61**It goes through.** `tests/cases/026-base16ct-crate/` transpiles every source
62file of base16ct 1.0.0 — `error.rs`, `lower.rs`, `upper.rs`, `mixed.rs`,
63`display.rs` — byte-for-byte as published on crates.io, plus `lib.rs`'s
64`decoded_len`, `encoded_len` and `decode_inner` verbatim, with the `alloc`
65half enabled. Decoding and encoding are byte-identical to rustc's, including
66`encode_str` (a closure over an `unsafe` block returning a borrowed `&str`
67view of the bytes just written) and `HexDisplay`, whose `UpperHex` impl writes
68once per byte into the formatter.
69
70That is the crate the transpiler in [`findings/`](findings/) emitted an empty
71file for, while exiting 0.
Add a README b66da6b nandithebull 8h ago72
Prove byte-identity for base16ct by enumerating whole input domains 99b8376 nandithebull 7h ago73How strong is "byte-identical"? [`PROOF.md`](PROOF.md) answers that precisely:
74exhaustive over every two-byte decode input, every two-byte encode input and
75every single byte through `encode_str`/`HexDisplay`, plus a compositional
76argument for longer inputs and 20,000 pseudorandom cases attacking it.
77`cargo test --test proof` runs it — 151,463 cases, 9.1 MB of output, compared
78byte for byte.
79
Lower the `log` facade, and add explicit enum discriminants 12c0a01 nandithebull 5h ago80## `bitflags!` and `log`
Lower `bitflags!` directly, checked against the real crate af6e50f nandithebull 5h ago81
82`bitflags` is the most-depended-on translatable crate in libcosmic's tree (79
83of 741), and it is 26 `macro_rules!` definitions. Expanding the macro does not
84help — the expansion still calls into the crate's own macro-defined runtime.
85So the macro is lowered directly, and checked against the real crate: the test
86links bitflags for the *oracle only*, and rustnim has to reproduce its
87behaviour without it, byte for byte.
88
Lower the `log` facade, and add explicit enum discriminants 12c0a01 nandithebull 5h ago89`log` (61 dependents) is the same shape — 20 `macro_rules!` — and gets the
90same treatment. rustnim models log's *emitting* side: a transpiled library's
91`info!` calls work and, with no logger installed, do nothing, exactly as in
92Rust. Installing a logger is done from Nim with `rsLogSetLogger`.
93
Lower `extern "C"` blocks to Nim importc; do not transpile libc 7db7991 nandithebull 5h ago94## C interop
95
96An `extern "C"` block lowers to Nim `importc` declarations — both are
97statements about a symbol someone else defines, bound by the same ABI. Raw
98pointers map, and `*const T` becomes a const-qualified C declaration, because
99Nim emits a real prototype where Rust emits none and the C compiler will
100reject a mismatch.
101
102That is the answer to `libc`, which is *not* transpiled: it is 129,594 lines
103of which 54,544 are constants and 7,660 are declarations, against 121 function
104bodies in the whole crate. Nim reaches those symbols natively.
105
Expand `macro_rules!` rather than translating it to a Nim template 04eb29f nandithebull 5h ago106## Macros
107
108A `macro_rules!` is **expanded at the call site**, not translated into a Nim
109`template`. The shape-level correspondence is real — 36% of macros in a
110400-crate sample are a single rule with no repetition, which is exactly a
111template — but a template body is untyped, and this lowering is type-directed
112throughout. Expanding gives ordinary Rust where the types are known.
113
Expand multi-rule and recursive macro_rules d459281 nandithebull 4h ago114Any number of rules, with `$(..)` repetition and recursion — 1,369 of the
1151,833 definitions in that sample, 74%. What remains is token-tree munching
116(420) and nested repetition (44).
Expand `$(..)` repetition in macro_rules 3d4a7d2 nandithebull 4h ago117
118Expansion took the survey from 3 to 18 of 400 crates accepted, of which 12
119produce Nim the Nim compiler accepts. (Accepted, compiles, and
Expand `macro_rules!` rather than translating it to a Nim template 04eb29f nandithebull 5h ago120behaviourally verified are three different bars; only `tests/cases/` clears
121the third.)
122
Transpile a second crate, adler2, to test whether any of this generalises 5fdd5be nandithebull 7h ago123## Does it generalise?
124
125`base16ct` is the crate this was built toward, so a second one was tried.
126`adler2` 2.0.1 — a stateful checksum with operator-overload trait impls and a
127hand-unrolled loop, structurally nothing like `base16ct` — works, and is
128byte-identical across every single byte, every length to 600, and 144
129incremental-write splits. It needed ten new features, and it caught a
130regression that 33 passing cases had not.
131
Add generics; transpile the part of cosmic-theme that is reachable ff34e1b nandithebull 6h ago132`cosmic-theme`'s spacing scale, corner radii and density model also transpile
133byte-identically — the part of it that is not built on `palette`.
134
135A 400-crate survey says something worth knowing: clearing the single most
136common blocker has twice moved the number of fully-working crates by *zero*,
137because each unblocked crate just hits its next one. Blockers are deep, not
138wide, and a frequency ranking of first blockers is not a roadmap.
139[`DESIGN.md`](DESIGN.md) has the tables.
Transpile a second crate, adler2, to test whether any of this generalises 5fdd5be nandithebull 7h ago140
Add a README b66da6b nandithebull 8h ago141## Tests
142
143```bash
144cargo test
145```
146
147The tests are differential, with rustc as the oracle. Each case in
148`tests/cases/` is compiled by rustc and run, transpiled and compiled by Nim and
149run, and the two stdouts and exit statuses must match. Building anything less
150than that — checking the Nim output "looks right", say — is how you end up
151shipping the bug in `findings/`. `rustnim` exiting 0 with a missing or empty
152output file is a hard failure, and so is an empty corpus.
153
154rustc is invoked without `-O` so debug-profile overflow checks are on, which is
155the matching pair for `nim c`'s defaults.
156
157Nim is found at `.nim-toolchain/bin/nim` in the repo root or any parent, or via
158`RUSTNIM_NIM`. Run a single case with:
159
160```bash
161RUSTNIM_CASE=005 cargo test --test differential -- --nocapture
162```
163
164## Layout
165
166| file | role |
167|---|---|
168| `src/ty.rs` | Rust type → Nim type, exact widths, explicit rejections |
169| `src/lower.rs` | items, statements, expressions → Nim |
170| `src/fmt.rs` | `println!`/`format!` format strings |
171| `src/prelude.nim` | `Option`/`Result`, panic, `Display`/`Debug` runtime |
172| `tests/differential.rs` | the runner above |
173
174[`DESIGN.md`](DESIGN.md) has the reasoning: how each construct is mapped, what
175was settled by running both compilers rather than by reading docs, and what's
176still open.