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 › 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

CommandWhat it does
cargo cardiac new NAMEMakes 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 setupFetches 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 buildCompiles the package's programs for CARDIAC.
cargo cardiac runBuilds the program and runs it on burn.
cargo cardiac viewBuilds 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 FILEAssembles 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 --versionShows which cargo-cardiac this is.

Building a package

OptionMeaning
--manifest-path PATHBuilds the package at PATH instead of the one here.
-p NAMEBuilds the workspace member NAME.
--bin NAMEBuilds only the program NAME. You can give it more than once. run and view need it when a package has more than one program.
--releaseUses the release profile.
--profile NAMEUses the profile NAME from the workspace's Cargo.toml.
--emit LISTChooses 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.

SettingValueWhy
opt-level2The compiler works from rustc's optimized MIR. At opt-level 0 its own passes are off too, and few programs fit.
incrementalfalseThe CARDIAC driver can't build incrementally.
debugfalseDebug info changes the MIR, and with it the listing.
overflow-checksfalseThe checks rarely fit in 96 cells. The voxel example is 87 cells without them and 134 with.
debug-assertionsfalseThe 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) {}.

OptionMeaning
-C opt-level=Nrustc'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|offThe default is on at opt-level 0 and off above it.
-C debug-assertions=on|offTurns debug_assert! on or off.
--auto-overlayLets the compiler split the program into phases. See Phases.
--edition YEARThe 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.

KindFileContents
deckNAME.cqbThe program as a deck that any CARDIAC following the 1968 manual can load.
listingNAME.cqThe 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.
mapNAME.mapThe panic map: where the program's checks are and what each one checks. run and Cardigan use it to say why a program panicked.
asmNAME.asmThe 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

OptionMeaning
-q, --quietShows errors only.
-v, --verboseAlso shows where the cells go, function by function.
--message-format=jsonWrites 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 optionMeaning
-x COMMANDRuns COMMAND first. You can give any number of them.
--batchRuns the -x commands and exits.
--profileRuns to the end and reports instruction counts and the hottest cells.
--limit=NStops after N instructions. The default is 1,000,000,000.
--start-at=NNStarts a listing at cell NN.
carc optionMeaning
-o FILEWrites the deck to FILE. - means standard output.
--start-at=NNStarts 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.