CARDIAC › rust-cardiac › Options and switches
Options and switches
These are the commands, options and files of cargo-cardiac 0.2.5. The
rust-cardiac language reference guide covers which language features “just
work”, which ones run but should generally be avoided, and which language features are incompatible with CARDIAC.
Commands
| Command | What it does |
cargo cardiac new NAME | Makes a package as cargo new does (it takes cargo new's options), with cardiac as a dependency and a countdown in src/main.rs. |
cargo cardiac setup | Fetches the CARDIAC driver (about 1 MB) and the nightly it runs on, nightly-2026-05-22 (about 550 MB). The first build does this if you haven't. |
cargo cardiac build | Compiles the package's programs for CARDIAC. |
cargo cardiac run | Builds the program and runs it on burn. |
cargo cardiac view | Builds the program and opens it in Cardigan, stopped at the start with its input in the reader. |
cargo cardiac debug FILE [INPUT]... | Debugs or profiles a listing or a deck with heartburn's ekg. |
cargo cardiac asm FILE | Assembles a listing into a deck with heartburn's carc. |
cargo cardiac help [COMMAND | CODE] | Shows the usage, one command's usage, or what a message code means. |
cargo cardiac --version | Shows which cargo-cardiac this is. |
Building a package
| Option | Meaning |
--manifest-path PATH | Builds the package at PATH instead of the one here. |
-p NAME | Builds the workspace member NAME. |
--bin NAME | Builds only the program NAME. You can give it more than once. run and view need it when a package has more than one program. |
--release | Uses the release profile. |
--profile NAME | Uses the profile NAME from the workspace's Cargo.toml. |
--emit LIST | Chooses what to write. See What a build writes. |
Build settings
Cargo's dev profile doesn't suit CARDIAC, so cargo cardiac builds it with five settings of its own.
It only uses one when your Cargo.toml leaves it unset, it never writes them into your files, and each build lists
the ones it used in note RCI0004.
| Setting | Value | Why |
opt-level | 2 | The compiler works from rustc's optimized MIR. At
opt-level 0 its own passes are off too, and few programs fit. |
incremental | false | The CARDIAC driver can't build
incrementally. |
debug | false | Debug info changes the MIR, and with it the
listing. |
overflow-checks | false | The checks rarely fit in 96 cells. The voxel
example is 87 cells without them and 134 with. |
debug-assertions | false | The same reason. |
Set any of them in [profile.dev] to choose your own. cargo run keeps cargo's own
settings, checks included, so an overflow that cargo run panics on goes unchecked on CARDIAC.
Building a single file
cargo cardiac build FILE.rs... builds files without a package. A single file can't use any crate,
including cardiac, so it declares the built-ins it calls as stubs, such as
#[inline(never)] pub fn out(_v: i16) {}.
| Option | Meaning |
-C opt-level=N | rustc's opt-level. The default is 0. cargo-cardiac's own passes are off at 0 and all on from 1 up, and few programs fit at 0. |
-C overflow-checks=on|off | The default is on at opt-level 0 and off above it. |
-C debug-assertions=on|off | Turns debug_assert! on or off. |
--auto-overlay | Lets the compiler split the program into phases. See Phases. |
--edition YEAR | The Rust edition. The default is 2021. |
What a build writes
--emit takes any of these, separated by commas. The default is deck,map. Each file is
written next to the program's source.
| Kind | File | Contents |
deck | NAME.cqb | The program as a deck that any CARDIAC following the 1968 manual can load. |
listing | NAME.cq | The program in Brian Stuart's six columns, with cells named after their variables and each instruction marked with the Rust it came from. cargo cardiac asm assembles it. |
map | NAME.map | The panic map: where the program's checks are and what each one checks. run and Cardigan use it to say why a program panicked. |
asm | NAME.asm | The compiler's own assembly. |
A program in phases gets one file of each kind per phase: NAME.cqb, NAME.2.cqb and so on.
Phases
A program bigger than memory comes in phases. Each phase's code is loaded over the one before, and the data stays.
Programming with overlays shows the technique. By default the program marks where
each phase ends by calling overlay() in main. With auto-overlay on, the compiler cuts
main itself, and calling overlay() is an error. A package turns auto-overlay on in its
Cargo.toml:
[package.metadata.cardiac]
auto-overlay = true
A single file uses --auto-overlay.
Resources
load_resource("NAME") reads the file resources/NAME, which sits beside the package's
Cargo.toml or beside a single file. The file holds numbers, written the same way as the input.
build puts them in the deck, and run fills any slot still empty from a
resources/ folder beside the deck.
Load tables with the program, not with INP
explains why.
Running
run and view take build's options and read the program's input from the numbers after
--, or from standard input:
cargo cardiac run -- 5
echo 5 | cargo cardiac run
run runs each phase's deck in turn. Build messages go to standard error, so standard output carries
only the program's output. A program that panics says why and exits with 101, as cargo run does.
Messages
| Option | Meaning |
-q, --quiet | Shows errors only. |
-v, --verbose | Also shows where the cells go, function by function. |
--message-format=json | Writes the messages to standard error as JSON Lines, with the kind in reason and the code in code, as cargo does. |
Every message has a code: error[RCE....], warning[RCW....] or note[RCI....].
cargo cardiac help CODE explains it, and every code has a page under
the message codes. cargo cardiac help --json gives all of them
as JSON.
Debugging and assembling
debug is ekg and asm is carc, both from heartburn. Each takes
its own options, and cargo cardiac help debug and cargo cardiac help asm list them.
| ekg option | Meaning |
-x COMMAND | Runs COMMAND first. You can give any number of them. |
--batch | Runs the -x commands and exits. |
--profile | Runs to the end and reports instruction counts and the hottest cells. |
--limit=N | Stops after N instructions. The default is 1,000,000,000. |
--start-at=NN | Starts a listing at cell NN. |
| carc option | Meaning |
-o FILE | Writes the deck to FILE. - means standard output. |
--start-at=NN | Starts the program at cell NN. |
Using rust-cardiac with vscode shows debugging the Rust itself.
Update check
At most once a day, build, run and view look up the newest cargo-cardiac in
crates.io's public index and say when one is newer. CARGO_CARDIAC_NO_UPDATE_CHECK=1 turns the check
off. It is also off with -q, with --message-format=json, and when standard error isn't a
terminal.
Versions
The compiler is pinned to rustc 1.97. Its driver is built on nightly-2026-05-22, so a newer Rust needs a new
driver.