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/. Deleting a file asks you to type its name, such as src/main.rs, to confirm, and there is no keyboard shortcut for it; Ctrl-W does nothing.
• 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. Line numbers appear beside your code; Ctrl-L hides or shows them, and Rustrace remembers your choice. 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 or Ctrl-C cancels it. Run instead opens the console and runs cargo run there, so your program can read what you type; in earlier versions, Run closes your program’s input, so a program that reads input (such as Lab 1) stops with an error, and you should use cargo run in the console instead.

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. Ctrl-C stops the program and keeps the console open; Esc stops it and closes the console. Both work even if your program is stuck in a loop. Long lines wrap, and PgUp, PgDn, or the mouse wheel scroll back through earlier output, such as a long list of compiler errors; drag the divider above the console to make it taller. The console is not a shell: it accepts only the commands above, and it never uses pipes, quotes, or other programs.

cargo run -- ARGS passes command-line arguments to your program: each space-separated word after -- becomes one argument, exactly as typed, so cargo run -- -n Utility tests/grep.md passes -n, Utility, and tests/grep.md. Because there is no shell, every character the console accepts is passed literally: cargo run -- a*b $HOME passes a*b and $HOME unchanged. Quoting and pipes are not supported: an argument may not contain ', ", or a backtick, nor |, &, ;, <, or >. Because there is no quoting, an argument cannot contain a space, and a backslash does not escape one: cargo run -- a\ b passes the two arguments a\ and b. You can still add < input.txt or > output.txt after the arguments.

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. Each case may run for at most 10 seconds, so a program stuck in a loop reports ERROR instead of hanging. Choose Run all to run every case in turn, and press Esc or Ctrl-C to stop a run; press R to refresh the list after a change in the test-case 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.

An assignment can have test cases that run your program with command-line arguments and with files for it to read. Such an assignment keeps its cases in its own directory named after it, such as lab2.test-cases next to lab2.work, so they never mix with another assignment’s cases, and the files the cases read are in its files directory, lab2.test-cases/files. Your program runs in that directory, both from the picker and from the console, so it opens those files by the same names that the arguments use. A case may have no input file; your program then runs with its standard input closed.

When you select one of these cases, the picker also shows its arguments, each between « and » so that spaces are visible, its input file and size or no input (stdin closed), the directory it runs in with the files there, and its last result. Do not edit, add, or remove the files in lab2.test-cases/files: the expected output was written for them, and a case run with changed files won’t match the package’s case, and it is reported to your instructor. The picker says changed from the package before you run if they differ; to restore them, remove the files you changed or added, then quit and run rustrace work lab2.rta again.

To run such a case in the console, type cargo run -- followed by the arguments the picker shows, without the « and » marks, and add < NAME.in if the case has an input file; for example, the Lab 2 case whose arguments are «-n», «Utility», and «tests/grep.md» runs as cargo run -- -n Utility tests/grep.md. An argument that contains a space cannot be typed in the console. An argument that the picker shows with an escape such as \u{a0}, which stands for an invisible or unusual character, cannot be typed that way either: the console does not read escapes, so typing \u{a0} passes those six characters; run such a case from the picker instead. Without <, the console prompt becomes your program’s input rather than closing it.

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.

If submit stops without creating the archive, for example because of a mistyped identifier, nothing is lost: fix the cause it names and run the same command again. rustrace status lab1.work shows how much more a submission can hold.

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.

If Rustrace or Your Terminal Closes Unexpectedly

Your work is safe. Run the same rustrace work lab1.rta command again and Rustrace resumes where you left off, recording that the interrupted command was stopped. If Rustrace was killed while your program was still running, it may tell you that a program is still using the workspace; stop it (for example with pkill -f target/debug, or in Activity Monitor) and run the command again.

If Rustrace reports an unfinished command when you start it, stop any program that your last command may have left running and run the same rustrace work lab1.rta command again. If the message repeats, ask on the course discussion forum.

Code Changed Outside Rustrace

If a file in your working directory changes outside Rustrace, for example because you edited it in another editor or copied a backup into it, Rustrace does not accept the change. It keeps the outside version, puts back the code it recorded, and tells you: The outside version is kept: run rustrace set-aside to view it. Nothing is deleted. To see what was set aside, quit Rustrace and run:

rustrace set-aside lab1.work

This lists each set-aside version with a number, the time it was captured, and how each of its files compares with your current code. Then rustrace set-aside lab1.work --show 1 prints the code of version 1; add --file src/main.rs to print a single file. These commands only read: Rustrace cannot put set-aside code back into your work. To use that code, type it in Rustrace, and let the teaching team know if you had to re-enter a large amount of code this way.

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.