CS 241 - How to run student environment tools (cs241-binasm, cs241-twoints, etc. ) locally

cs241-run-locally.md

Preface

This is a guide for students taking CS 241 at University of Waterloo who wish to use the provided student environment tools (cs241-binasm, cs241-twoints, cs241-array, etc.) on their local machines. This works best if you are using a Mac or Linux machine. If you find a way to make it work on Windows feel free to fork this and include the proper steps to do so.

After spending some time digging around in the student environment, I figured out a way to run these tools on your local machine, so you don't have to connect to the student environment and copy over your MIPS assembly files to execute them. This also enables you to test your programs without an internet connection.

Most of the tools were written in Java or Scala so they can be run on any computer with a JVM. So all you need is JDK installed on your local machine.

Prerequisites

1. You need to have Java Development Kit installed (Version 8+ recommended)

Instructions

1. Make a directory on your local machine to store these tools.

2. With SCP or some SFTP client, connect to student environment (linux.student.cs.uwaterloo.ca) and navigate to /u/cs241/pub/classes.

3. Copy the cs241 and mips folders to the directory on your local machine you created in Step 1.

   • All you really need in the cs241 folder are: binasm.class file and asm folder.
   • You probably need everything in mips folder.
   • It may ask you whether to skip some files due to lack of permissions, just skip them.
   • Note: These files are only Java .class files, so they do not contain any source code.

4. To assemble the program prog.asm into prog.mips with cs241-binasm on your local machine, navigate to the directory you created in Step 1 and in your terminal execute:

   java cs241.binasm < prog.asm > prog.mips.

   Everything is the same as running on student environment except you run java cs241.binasm instead of cs241-binasm. If you want to use cs241-binasm instead, please refer to the Extension section.

5. To run cs241-twoints, execute:

   java mips.twoints < myfile.mips (from the same directory)

6. To run cs241-array, execute:

   java mips.array < myfile.mips

7. Similar conventions apply if you want to use other tools available, like cs241-noints, cs241-cfgcheck, etc.

Extension

If you want to run these tools on your machine from any path, or want to use the wrapper scripts (i.e. cs241-binasm) instead of invoking Java (i.e. java cs241.binasm) all the time, you have to do some more work.

There may be a way to run these tools with the java command from anywhere by configuring classpaths and stuff, but I'm not too familiar with that

If you're running Linux or Mac, you can copy over the wrapper files in the student environment from /u/cs241/pub/wrappers/. That directory contains all the wrapper scripts used to run the tools on the student environment: cs241-array, cs241-twoints, cs241-wordasm, etc.)

Place them in a directory, and add the path to that directory to your PATH by setting your environment variables appropriately.

Then, modify the following in those wrapper files:

Change the following to the path to JDK:

export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64/

It might still work if you delete the line entirely, if you have already set your JDK path.

Delete this line entirely:

export PATH=/u/cs241/pub/bin.\`/u/cs241/pub/bin/arch\`:$JAVA_HOME/bin:$JAVA_HOME:$

Change the following to the path to the folder you created in Step 1:

export CLASSPATH=.:/u/cs241/pub/classes:$CLASSPATH

Then delete this if block:

if ! [ -r "$COURSEHOME/pub/classes/${CLASSPREFIX}/${CLASSNAME}.class" ]; then
    echo "This program has not been made available yet. Please wait until a future assignment." 1>&2
    echo "If you believe it should be enabled, please contact the ISA." 1>&2
    exit 1
fi

Now you can run cs241-binasm, cs241-twoints, cs241-array in terminal from any directory.

If you are on Windows, unfortunately I do not know how to achieve this, you can probably write a similar wrapper script that does the same thing.

FAQ

1. What about tools like cs241-wlmparse, cs241-wlmscan ? Do they work?

These steps only work if the program was written in a JVM language like Java or Scala. Tools like cs241-wlmparse, cs241-wlmscan use a compiled binary from C++ most likely. You can tell from analyzing the wrapper files. For example, for cs241-wlmparse:

To find out where the wrapper file is located for a command:

$ which cs241-wlmparse

/u/cs241/pub/wrappers/cs241-wlmparse

To output the contents of the wrapper file:

$ cat /u/cs241/pub/wrappers/cs241-wlmparse

#!/bin/sh

COURSEHOME="/u/cs241"
PROGNAME="wlmparse"
PROGPATH="$COURSEHOME/pub/bin.x86_64/$PROGNAME"

if ! [ -x "$PROGPATH" ]; then
echo "This program has not been made available yet. Please wait until a future assignment." 1>&2
echo "If you believe it should be enabled, please contact the ISA." 1>&2
exit 1
fi

${PROGPATH} "$@"

The PROGPATH variable points to the wlmparse file in the .../bin.x86_64/ directory, which kind of implies it is a x86_64 binary file, not a class file. This means that the program can only be run on the same computer architecture on which it was compiled and likely will not run on your own machine.

You can confirm this by doing this, which describes the type of file it is:

$ file /u/cs241/pub/bin.x86_64/wlmparse