SQ in silver chrome letters, a lab's gear stacked against the S: a rack, two oscilloscopes, pizza boxes and a six-pack. Strange Query Lab

CARDIAC › rust-cardiac

rust-cardiac

Compile Rust to CARDIAC

cargo install cargo-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:

CrateWhat it is
cargo-cardiacThe tool you install. It adds cargo cardiac to cargo, to build, run and debug your program on CARDIAC.
cardiacThe crate your program uses, home of inp(), out() and the other built-ins. cargo cardiac new adds it for you.
heartburnThe 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-inOn CARDIACWith 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).
FlagA 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