| Add a README b66da6b nandithebull 7h ago | 1 | # rustnim |
| 2 | |
| 3 | A Rust → Nim transpiler. It parses Rust with `syn` and emits Nim source that |
| 4 | behaves the same way — same stdout, same exit status — when both are built and |
| 5 | run. |
| 6 | |
| 7 | The rule the whole thing is organised around: **never approximate a semantic |
| 8 | you cannot represent.** If a construct doesn't map, `rustnim` says so and exits |
| 9 | non-zero. It never writes a file it can't stand behind. |
| 10 | |
| 11 | That rule comes from a real failure. We tried an existing transpiler that |
| 12 | advertises Rust support on the `base16ct` crate; it emitted an empty file and |
| 13 | exited 0. The write-up is in [`findings/`](findings/). |
| 14 | |
| 15 | ## Build and run |
| 16 | |
| 17 | ```bash |
| 18 | cargo build --release |
| 19 | ./target/release/rustnim input.rs -o out.nim |
| 20 | nim c out.nim |
| 21 | ``` |
| 22 | |
| 23 | Several inputs are concatenated into one Nim module, in the order given — Nim |
| 24 | has no per-file `mod`, so items are flattened and names must not collide: |
| 25 | |
| 26 | ```bash |
| 27 | rustnim src/lib.rs src/error.rs --cfg feature=alloc -o crate.nim |
| 28 | ``` |
| 29 | |
| 30 | ## What works |
| 31 | |
| 32 | Functions and `impl` methods, structs, enums (C-like and data-carrying), |
| 33 | `Option`/`Result` with `?`, `let`/`let mut`, the integer and float operators at |
| 34 | exact widths, `as` casts, `if`/`while`/`loop`/`for`, `match` including binding |
| 35 | patterns, `Vec`/slices/arrays, type aliases, function-typed parameters |
| 36 | (`impl Fn(A) -> B`), multi-file input, `#[cfg]`, and `println!`/`format!` with |
| 37 | `{}`, `{:?}`, `{:x}`, `{:b}`, positional and inline-named arguments, and |
| 38 | zero/space padding. |
| 39 | |
| Correct the README where trait impls and iterators are listed as rejected 428f374 nandithebull 6h ago | 40 | Also: the formatting trait impls (`Display`, `Debug`, `LowerHex`, `UpperHex`, |
| 41 | `Binary`, `Octal`) and `From`; and slice iterators — `iter`, `iter_mut`, |
| 42 | `enumerate`, `zip`, `chunks_exact`, `chunks_exact_mut`, `windows` — resolved |
| 43 | into a single index loop where each binding is an lvalue into the original |
| 44 | container, so `*d = v` through `iter_mut()` reaches the caller's slice. |
| 45 | Borrowed slices are views, not copies, including as return types. |
| 46 | |
| 47 | Rejected with a reason, rather than guessed at: `i128`/`u128`, generics, |
| 48 | closures, `unsafe`, trait impls other than the ones above, iterator adaptors |
| 49 | with no index-loop equivalent (`map`, `filter`, `take_while`), float→int casts, |
| 50 | and any standard-library method that isn't mapped. |
| 51 | |
| 52 | ## base16ct |
| 53 | |
| 54 | `tests/cases/026-base16ct-crate/` transpiles base16ct 1.0.0's `error.rs` and |
| 55 | `mixed.rs` byte-for-byte as published on crates.io, plus `lib.rs`'s |
| 56 | `decoded_len`, `encoded_len` and `decode_inner` verbatim. Its decoder output is |
| 57 | byte-identical to rustc's — lower, upper and mixed hex, both error variants, |
| 58 | and the `Display` strings. That is the crate the transpiler in |
| 59 | [`findings/`](findings/) emitted an empty file for. |
| 60 | |
| 61 | The rest of the crate needs closures, `unsafe`, and struct fields of view type; |
| 62 | [`DESIGN.md`](DESIGN.md) says which file needs which. |
| Add a README b66da6b nandithebull 7h ago | 63 | |
| 64 | ## Tests |
| 65 | |
| 66 | ```bash |
| 67 | cargo test |
| 68 | ``` |
| 69 | |
| 70 | The tests are differential, with rustc as the oracle. Each case in |
| 71 | `tests/cases/` is compiled by rustc and run, transpiled and compiled by Nim and |
| 72 | run, and the two stdouts and exit statuses must match. Building anything less |
| 73 | than that — checking the Nim output "looks right", say — is how you end up |
| 74 | shipping the bug in `findings/`. `rustnim` exiting 0 with a missing or empty |
| 75 | output file is a hard failure, and so is an empty corpus. |
| 76 | |
| 77 | rustc is invoked without `-O` so debug-profile overflow checks are on, which is |
| 78 | the matching pair for `nim c`'s defaults. |
| 79 | |
| 80 | Nim is found at `.nim-toolchain/bin/nim` in the repo root or any parent, or via |
| 81 | `RUSTNIM_NIM`. Run a single case with: |
| 82 | |
| 83 | ```bash |
| 84 | RUSTNIM_CASE=005 cargo test --test differential -- --nocapture |
| 85 | ``` |
| 86 | |
| 87 | ## Layout |
| 88 | |
| 89 | | file | role | |
| 90 | |---|---| |
| 91 | | `src/ty.rs` | Rust type → Nim type, exact widths, explicit rejections | |
| 92 | | `src/lower.rs` | items, statements, expressions → Nim | |
| 93 | | `src/fmt.rs` | `println!`/`format!` format strings | |
| 94 | | `src/prelude.nim` | `Option`/`Result`, panic, `Display`/`Debug` runtime | |
| 95 | | `tests/differential.rs` | the runner above | |
| 96 | |
| 97 | [`DESIGN.md`](DESIGN.md) has the reasoning: how each construct is mapped, what |
| 98 | was settled by running both compilers rather than by reading docs, and what's |
| 99 | still open. |