Rustrace

Rustrace is the editor you will use for every programming assignment in this course. It runs in your terminal, opens an assignment package, and lets you edit, compile, run, and test your Rust code. While you work, it records how your program came together, so that the teaching team can see your work as a process rather than as a finished file. It has no AI features, and it accepts only text that you type or that you copied inside the editor itself.

You do not need to learn much to use it. This page covers everything an assignment requires; press F1 (which corresponds to Fn + F1 on a Mac) inside Rustrace for the full list of shortcuts.

Rustrace is open source (under the MIT license) and developed by the course instructor for use in this course. You are welcome to submit PRs; if you submit a PR, though coding agents can be used to write your code, you should write the PR description by yourself. Do not submit issues in the Rustrace repository; instead, let the instructor know about any issues you have in the dedicated course discussion forum.

Before You Install

You will need the following prerequisites before you install Rustrace:

• A Mac with Apple Silicon, or a Linux machine on x86-64. On Windows, install WSL 2 and keep your assignments inside the WSL filesystem, not on a mounted Windows drive.

• Rust’s toolchain manager, rustup. If you do not have it yet, run:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

• Your system’s native build tools: on macOS, run xcode-select --install; on Debian or Ubuntu, install build-essential and pkg-config.

• A terminal window of at least 80 columns by 24 rows. Ghostty, kitty, WezTerm, and iTerm2 are recommended because they deliver the Command-key shortcuts to Rustrace. The built in macOS Terminal.app also works, but use the Ctrl shortcuts there. The instructor personally uses Ghostty on his Mac for development. Running Rustrace within a terminal multiplexer may work, but it has not been tested.

Installing Rustrace

Run this one command:

curl -fsSL https://raw.githubusercontent.com/baochunli/rustrace/main/scripts/install.sh | sh

The installer checks that rustup is present, installs Rust 1.98.1 if it is missing, and then builds Rustrace from source. Building takes a few minutes; this is normal. The binary is placed in ~/.cargo/bin, which is already on your path if you use Rust. Open a new terminal window and confirm the installation:

rustrace --version

If you use Ghostty, it keeps some Command-key shortcuts for itself. Run the following command once and add the line it prints to your Ghostty configuration file, then reload Ghostty:

rustrace doctor --write-ghostty-keys

Starting an Assignment

Each assignment page gives you a package file, for example lab1.rta. Save it in a normal local folder, not in a cloud-synced folder such as iCloud Drive, Dropbox, or OneDrive. First, let Rustrace check that your machine is ready:

rustrace doctor lab1.rta

Every line should say OK; anything else comes with a one-line fix. Then open the assignment:

rustrace work lab1.rta

Rustrace creates a working directory named lab1.work next to the package, unpacks the starter code into it, places the public test cases in a test-cases directory beside it, and opens the editor. To stop, press Ctrl-Q. To continue later, run the same rustrace work lab1.rta command again; it resumes exactly where you left off.

Editing

The screen shows a file list on the left, your open files on the right, and an output pane below. The bottom row always reads F1 keybinds · F7 menu · F9 console, which is all you need to remember.

• Files. The file list is mouse-driven: click a file to open it, and right-click to create, rename, or delete a file. New files go under src/.
• Saving. Press Ctrl-S to save all files; this also runs cargo check for you. Rustrace autosaves as you type anyway, so you cannot lose work by forgetting to save.
• Errors and warnings. After a check, lines with compiler errors are tinted red and lines with warnings are tinted yellow, and the details appear in the output pane. Press Alt-Up or Alt-Down (Option-Up or Option-Down on a Mac) to jump between them, or click a tinted line.
• The usual shortcuts. Ctrl-Z and Ctrl-Y undo and redo; Ctrl-F finds and replaces; Ctrl-/ comments a line out and back in; Tab and Shift-Tab indent and outdent a selection. The mouse works everywhere: click, drag to select, scroll, and drag the divider between the panes. To select everything, right-click in the editor and choose Select all.
• Copy and paste. Ctrl-C, Ctrl-X, and Ctrl-V copy, cut, and paste text within Rustrace, including between files. Pasting text from outside Rustrace is blocked: the attempt is recorded, though the rejected text itself is never stored. If you need something from elsewhere, type it.

On a Mac, the Command-key versions of these shortcuts also work in the recommended terminals; the Ctrl versions always work.

Building and Running

Press F7 (Fn + F7 on Macs) to open the command menu. Its entries are Check, Run, Clippy, Format, Doc, Update dependencies, Update Rustrace, Automatic checks, Console, Test cases, Keybinds, and Quit. Use the arrow keys and Enter, or click. The result appears in the output pane; while a command runs, the editor is read-only and Esc cancels it.

Press F9 (Fn + F9 on Macs) for the console, which accepts these Cargo commands, one per line:

cargo build
cargo check
cargo test
cargo run
cargo clippy
cargo doc
cargo add NAME
cargo remove NAME

When you run your program with cargo run, the console prompt becomes the program’s standard input: type a line and press Enter to send it. Esc stops the program and closes the console. The console is not a shell: it accepts only the commands above, and it never uses pipes, quotes, or other programs.

Test Cases

Press F4, or choose Test cases from the menu, to see the public test cases that came with the assignment. Press Enter on a case to run your program with that input and compare its output with the expected output. The result is PASS, FAIL with the number of the first line that differs, or ERROR if the program did not run to completion. Choose Run all to run every case in turn; press R to refresh the list after a change in the test-cases directory; press Esc to close.

If you prefer the console, cargo run < 33.in runs the case named 33 the same way, and cargo run < 33.in > 33.actual saves the output beside it for you to inspect. All of these test runs are recorded with your work.

Submitting

When you are done, quit Rustrace and create your submission from the terminal, using the student identifier stated on the assignment page:

rustrace submit lab1.work --student-id YOUR_ID

This finalizes your work and writes a ZIP file named after your identifier and the assignment, next to the working directory. Upload that .zip archive to Quercus; the .zip archive is your submission, and Rustrace does not upload anything by itself. If you would like to see exactly what the archive contains, run rustrace privacy lab1.work first.

A finalized working directory cannot be reopened. If you need to change your work after submitting, and the deadline allows it, run rustrace revise lab1.work lab1-v2.work lab1.rta to continue in a new working directory, then submit again with rustrace submit lab1-v2.work --student-id YOUR_ID --output YOUR_ID-lab1-v2.zip. The new .zip archive contains the complete history, so only the latest one needs to be uploaded.

Keeping Rustrace Up to Date

Once a day, when you start an assignment, Rustrace asks GitHub for the latest release number. That single request is the only network traffic Rustrace itself ever makes; no assignment content or identity is sent. When a newer version exists, the menu shows Update Rustrace with a NEW badge. Quit Rustrace and run:

rustrace update

This rebuilds Rustrace from source, which again takes a few minutes. You can turn the daily check off with the Automatic checks entry in the menu, and check by hand at any time with rustrace update --check.

Rules

If something goes wrong, rustrace doctor lab1.rta is the first thing to run, and its output is the first thing to include when you ask for help on the course discussion forum.