#acl All:read


<<LaTeXMathSetup()>>

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

A student has three choices for their development environment:

 1. <<Anchor(dockerimage)>>"Pull" the course Docker image at https://hub.docker.com/r/khellmanatmines/sim-student, and do their development and testing on a virtual machine.
 {{{#!plain
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:
 {{{#!plain
docker run -it khellmanatmines/sim-student /bin/bash
vmID# /usr/local/install-scripts/install-java.sh
...
vmID# /usr/local/install-scripts/install-scala.sh
...
 }}}
 {{{#!wiki important
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.
 }}}
 {{{#!wiki tip
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.
 {{{#!plain
$ 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 `exit`ed 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
 }}}
 1. <<Anchor(linuxhost)>>Students can use their own Linux environment with the course's grading scripts and utils installed within it.
   a. Download <<DjHR(SIMGRADING.tar.bz2)>> to your Linux box
   a. Unravel the tarball somewhere...
   {{{#!plain
somewhere$ tar xjf ~/Downloads/SIMGRADING.tar.bz2
   }}}
   ('''Your path''' for `somewhere` is whereever you'd like it to be.)
   a. 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"
   }}}
   a.  And make sure the binaries work
   {{{#!plain
$ /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.
 1. <<Anchor(nonlinux)>>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 [[Assignments/TraceFiles|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
{{{#!plain
$ 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:
{{{#!plain
$ 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
   {{{#!plain
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 
   {{{#!plain
docker start -ai simdev
   }}}