Managing assignment workspaces with a .csroom file

Without setup, a student opening a project sees a flat list of files, clicks Run on whichever one is open, and gets whatever that file does on its own. A .csroom file in the project folder tells the workspace which file to start in, how to build and run the project, which environment variables to set, and which folders to keep out of view. It applies to every file under that folder.

The file is plain text in TOML format. It works the same in your own projects, in an imported lesson, and in an assignment a teacher hands out.

Create it

Make a file named .csroom at the top of the project folder. The explorer hides files whose names start with a dot, so turn on Show hidden files (the eye icon above the file tree) to see it, or create it from the terminal:

nano .csroom

The smallest useful file is one line:

entrypoint = "main.py"

That names the project's main file. It opens first, and Run runs it from any file in the project. Every key is optional.

Keys

entrypoint

The project's main file, relative to the project folder. It opens first when someone opens the assignment from the class page. When run is not set, Run runs this file the way it would run it on its own.

entrypoint = "src/main.py"

run

What Run does, when running the entrypoint on its own isn't enough: extra arguments, a module, several commands. Write it as a shell command line, or as a list of arguments to avoid quoting rules:

run = "python3 main.py --verbose"

run = ["python3", "main.py", "--verbose"]

Anything you could type at the prompt works, including several commands joined with && or ;. The command runs from the project folder, so relative paths work.

build

A command that runs before run, for languages with a compile step. If it fails, run does not start.

build = "javac *.java"
run = "java Main"

hidden

Files and folders to keep out of the file explorer, usually build output and caches. They still exist, the terminal still sees them, and Show hidden files shows them.

hidden = ["bin", "obj", "*.class", "src/generated"]

A name without a slash, like bin or *.class, matches at any depth. A path with a slash, like src/generated, is relative to the project folder. Hiding a folder hides everything inside it.

env

Environment variables set before build and run.

run = "python3 main.py"

[env]
NAME = "Ada"
DEBUG = "1"

Values must be strings, so write "1", not 1. Names use letters, digits and underscores, and can't start with a digit.

A complete example

A Java project with sources in src, compiled into a hidden out folder, and a variable the program reads:

entrypoint = "src/Main.java"
build = "javac -d out src/*.java"
run = "java -cp out Main"
hidden = ["out"]

[env]
GREETING = "Hello"

Run types one line into the terminal that changes into the project folder, exports the variables, builds, and runs. Your shell stays in the folder it was in.

For teachers

Put the .csroom in the assignment folder, next to the starter files. Students receive it with the rest of the assignment. When they open the assignment, they land in the file you chose, Run does what you set, and the explorer leaves out what you hid. Students can edit their own copy. When you open a student's workspace, Run follows the student's copy.

A .csroom never affects a grade. The test command, hidden tests and reference solution live in Test settings, which students never see; see Writing assignment tests. hidden only tidies the explorer. To keep a file away from students, use File visibility in Test settings, which moves the file out of the folder students receive.

If a project you imported came with a .replit file, its run, entrypoint and hidden keys mean the same thing here. Copy them into a .csroom and drop the rest.

What Run does, with and without the file

Without a .csroom, Run works per file. It runs whichever file is open, using that file's language: python3 for hello.py, node for hello.js.

Setting run or entrypoint in a .csroom above the open file makes Run work per project, the way Replit's Run button did:

.csroom says	Run on hello.js runs
nothing above this file	node hello.js
entrypoint = "main.py"	python3 main.py
run = "python3 main.py --verbose"	python3 main.py --verbose
only hidden or [env]	node hello.js, with the variables set

Once a project has an entrypoint or a run command, Run does the same thing from every file in it, a README included. To run one file on its own, type its command in the terminal. The button still reads Run; hover it to see "Run this project (configured in .csroom)".

A .csroom at the top of your workspace applies to every file in the workspace.

Troubleshooting

• A red ".csroom error" label appears beside Run. The file has a mistake, so the whole file is ignored and Run runs the open file instead. Hover the label to read the problem and its line, or click it to open the .csroom with that line underlined. The label goes away once the file is fixed.
• String errors. A bare " inside a double-quoted string ends the string. Write it as \" (run = "echo \"hi\""), wrap the whole value in single quotes (run = 'echo "hi"'), or leave out inner quotes the command doesn't need (run = "mvn exec:java -Dexec.mainClass=app.Main").
• A [run.env] section is rejected. TOML doesn't allow run = "..." followed by [run.env]. Use a top-level [env] section, as in the examples above.
• There is no Run button on some files. Neither run nor entrypoint is set, and the open file's language has no default command. Set one of them.
• A change doesn't take effect. The file is re-read when the workspace reports a file change, shortly after you stop typing in it, when you click Run with the .csroom itself open, and when you switch files.
• The file isn't in the explorer. Turn on Show hidden files above the file tree.