CARDIAC › rust-cardiac
Custom Rust backend targeting the 1968 Bell Labs CARDIAC cardboard computer.
Generates code compatible with most CARDIAC emulators on the web, with special emphasis on
heartburn, the fastest emulator available today. Build and debug your code in
vscode or other tools, then flick a switch and generate CARDIAC opcodes. See the
Language Reference for a full description of supported language features.
Quick start
Installing and setting up
You'll need rustup. After that it's four commands from nothing to a program
running on CARDIAC:
cargo install cargo-cardiac
cargo cardiac setup
cargo cardiac new countdown
cd countdown
cargo cardiac run
The first time, setup downloads the compiler's driver and the Rust nightly it runs on. That's about
550 MB, so go get a coffee. Skip setup and the first build does it for you anyway.
If you use vscode for Rust development, consult the vscode guide.
rust-cardiac on crates.io
All you need to do to get going is install cargo-cardiac. Here are the packages it drags in:
| Crate | What it is |
| cargo-cardiac | The tool you install. It adds
cargo cardiac to cargo, to build, run and debug your program on CARDIAC. |
cardiac | The crate your program uses,
home of inp(), out() and the other built-ins. cargo cardiac new adds it for
you. |
| heartburn | The runtime underneath. cargo
cardiac run runs your decks on it, about a billion CARDIAC instructions a second. |
The target is called cardiac-unknown-none. It's named like a real Rust target, but rustc has never
heard of it, so you'll never type --target. Plain cargo build still builds for your own
machine, and cargo cardiac build builds for CARDIAC. Options and
switches lists every command and option, and the build settings.
Debugging with Cardigan
rust-cardiac emits a listing and a map alongside each deck, and they integrate with Cardigan,
so you can debug the CARDIAC assembly your program became directly in the simulator. In the listing every cell is
named after the Rust variable it holds and every instruction is marked with the Rust it came from. Run cargo
cardiac view and it builds the program and opens it in Cardigan, ready to step through. Here's the countdown
that cargo cardiac new gives you:
use cardiac::*;
fn main() {
let mut n = inp();
while n >= 0 {
out(n);
n -= 1;
}
}
cargo cardiac build --emit deck,listing,map
Start at 03.
03 011 main_bb0 INP n inp()
04 111 main_bb1 CLA n
05 310 TAC main_bb4
06 511 OUT n out(...)
07 700 SUB 00 n = n - 1
08 611 STO n
09 804 JMP main_bb1 goto
10 900 main_bb4 HRS 00 return from main
11 000 n DATA 000
Nine cells, which is about what you'd write by hand. If you'd rather stay in the terminal, cargo cardiac
debug does the same thing in ekg. And because every program also builds as ordinary Rust, you can step
through the Rust itself in vscode: using rust-cardiac with vscode shows how.
Platform strengths and limitations
CARDIAC is better at arithmetic than you'd expect from a cardboard computer. Integer math works well as long as
your numbers fit in the three digits a card holds, and rustc does the whole front end, so you get real Rust type
checking and real Rust error messages before anything goes near CARDIAC.
Strings are another story. CARDIAC only prints numbers and has no heap, so println! and
String were never going to happen, and neither were floats. Memory is the other wall, since a program
gets 96 cells. That one turns out to be softer than it looks. A program can come in phases, each loading over the
last while the data stays put, the way you'd swap decks on a real CARDIAC.
Programming with overlays explains how.
The cardiac adapter layer
The cardiac crate bridges the two worlds. On CARDIAC, inp() reads a card and
out() outputs a value. Under cargo run, the same calls read standard input and print a
line. The crate also has a few built-ins for things only CARDIAC needs.
| Built-in | On CARDIAC | With cargo run |
inp() | Reads the next card. | Reads the next number from standard input. |
out(v) | Outputs a value. | Prints v on a line of its own. |
overlay() | Ends a phase, so the next deck loads over this one. See
Programming with overlays. | Does nothing. |
load_resource("NAME") | Fills an array from a file when the program loads, instead of
reading it in card by card. See Load tables
with the program, not with INP. | Reads resources/NAME when the program runs. |
assume(cond) | Promises cond holds, so the compiler can drop checks it
couldn't prove. | assert!(cond). |
Flag | A bool kept as -1 or 0, so testing it is a single TAC. See
Keep a flag as 0 and -1, not 1 and 0. | A
plain i16. |
The reference guide has the rest of the built-ins, along with every piece of
Rust we've tried, what it costs on CARDIAC, and what to write instead when the build says no.
Sample Rust code
Hello world is a problem when your machine only prints numbers, so on CARDIAC, hello world counts down:
use cardiac::*;
fn main() {
for n in (0..=10).rev() {
out(n);
}
}
cargo run --bin hello # compile to native machine code
cargo cardiac run --bin hello # the same numbers, on CARDIAC
The examples folder has plenty
more, from FizzBuzz to Nim from the original manual. Every one prints the same thing natively and on CARDIAC, and
every one fits in 96 cells.
Real Rust projects
If you think you found a bug
Email bug@strangequery.com. Send the program, the input you gave it,
what it printed and what you expected, and the version from cargo cardiac --version. The best
"expected" is what the same program prints with cargo run.
Everything else
- The sourcerust-cardiac on GitHub, with the full README
- cargo-cardiacwhat you install, on crates.io
- The
cardiac cratewhat your program uses: inp(), out() and the other built-ins, on docs.rs
- The rust-cardiac reference guidewhat Rust works, what it costs on CARDIAC, and what is refused
- Options and switchesevery cargo-cardiac command, option and file
- Using rust-cardiac with vscoderun it natively and on CARDIAC, and debug both
- heartburnthe emulator underneath, and burn, carc and ekg on their own
- Cardiganthe CARDIAC IDE in your browser: open a deck and step through it
- The CARDIAC archivelore, tools, programming, tips and tricks, and samples