Programming projects for this course are graded with https://www.gradescope.com using a standard Ubuntu base environment. Graded work must meet the course submission requirements.

A student has three choices for their development environment:

1. "Pull" the course Docker image at https://hub.docker.com/r/khellmanatmines/sim-student, and do their development and testing on a virtual machine.

   docker pull khellmanatmines/sim-student

   Then you will need to install the language toolchain of your choice, if your project will use Java and Scala:

   docker run -it khellmanatmines/sim-student /bin/bash
   vmID# /usr/local/install-scripts/install-java.sh
   ...
   vmID# /usr/local/install-scripts/install-scala.sh
   ...

   You can install whatever you like on your docker vm, but the Gradescope grading machines will use only the /usr/local/install-*.sh scripts to setup your build environment.

   Look in /usr/local/install-scripts for the available languages you can use to complete your project. If you don't find a language you'd like to use, let me know, I'll likely add it!.

   Once you have your toolchains installed, exit the virtual machine and commit your image for future project work.

   $ docker commit vmID simgrading
   sha256:6ee998 blah blah blah
   $ docker image list
   REPOSITORY          TAG         IMAGE ID            CREATED             SIZE
   simgrading          latest      6ee998a8a914        16 seconds ago      1.8GB

   If you forget the vmID or need to jump back into an exited container, use

   $ docker ps --all
   ...
   $ docker start -ai vmID

   to resume the session. The ps --all command will list all your interned machines, the first column CONTAINER ID should be used in the docker start command as the vmID.

   Now you can complete all your course projects as the blaster user on the virtual machine.

   $ docker run -it simgrading runuser -l blaster
   blaster@vmID $ echo $SIMGRADING
   /SIMGRADING
   blaster@vmID $ /SIMGRADING/Random 423 | head -n 3 >test.dat
   blaster@vmID:~$ cat test.dat
   0.53229350689799
   0.91892032278702
   0.11796685447916

2. Students can use their own Linux environment with the course's grading scripts and utils installed within it.

   1. Download SIMGRADING.tar.bz2 to your Linux box

   2. Unravel the tarball somewhere...

      somewhere$ tar xjf ~/Downloads/SIMGRADING.tar.bz2

      (Your path for somewhere is whereever you'd like it to be.)

   3. Set SIMGRADING in your environment --- you should really do this in your login rc file: .bashrc most likely!

      export SIMGRADING="/your/path/to/somewhere/SIMGRADING"

   4. And make sure the binaries work

      $ /your/path/to/somewhere//SIMGRADING/Random 423 | head -n 3 
      0.53229350689799
      0.91892032278702
      0.11796685447916

      All the binaries should be built with static linking to avoid shared library dependencies. If you find one that causes problems, please let the instructor know ASAP.

3. Lastly, you could simply develop your code on a non-Linux box, and package it up appropriately in a ZIP for submission. But you won't be able to easily run the project's "grader script" so your test-debug-edit cycle through gradescope is going to be painful. I do not recommend this approach, but if you choose to develop this way you will most certainly want the downloads from the trace files page.

Hints for developing in a docker image

Viewing PDFs

The grader.sh scripts for projects produce PDFs of SIM results. It is important to inspect these to make sure your submission is working as it should. However, if you don't have a setup where you can simply "file browse" to the directory in the docker image and view the PDFs in your preferred GUI, this can be a bit klunky to do over and over and over during development and testing.

I'm sure there are only a bazillion ways to do this on your favorite OS. Google knows of course... Here is my "terminal-centric" solution.

After running grader.sh, in another terminal on your machine use

$ docker exec vmID runuser -u blaster -- /bin/sh -c '( cd && cd path/to/my/sim && tar cf - _*.pdf)' | tar xf -

which will dump all the grader.sh script PDFs in your current directory (you could of course use zip instead, choose your weapon of choice). If you use an auto-refreshing PDF viewer (like gv(1)) you can now open the PDF plot of interest and it will reload whenever the PDF transfer occurs. Good stuff.

If you don't like having to "up-arrow" and re-issuing the docker exec command all the time, consider:

$ while sleep 4 ; do docker exec ...<your transfer command> ; done

Using the Docker container with VSCode on MacOS

(Many thanks to NatalieR, Fall 25 for these insights).

• Run one time

  • docker run --platform linux/amd64 -it --name simdev \
      -v /Users/USERNAME/Desktop/CSCI423/Project1:/workspace khellmanatmines/sim-student \
      runuser -l blaster -c "cd /workspace && bash -l"

    Where /Users/USERNAME/Desktop/Project1:/workspace is specific to your own Mac setup, simdev is the name of the container being created, and /workspace on the container should probably pre-exist and be owned by the blaster user.

    I suspect /workspace is a VSCode-ism.

• You can reconnect to the container with

  • docker start -ai simdev