Tool Setup and Usage Notes for CS453 and CS553


MIPS and SPIM

SPIM is a simulator for MIPS assembly code. The SPIM website is at http://www.cs.wisc.edu/~larus/spim.html. See their link to Appendix A of Hennessey and Patterson for a good introduction to MIPS and SPIM.

spim and xspim are installed on the CS machines (definitely the 32-bit machines, not installed on the 64-bit yet). Download the example float.s file and try both of the following:

    > spim -keepstats float.s
    > xspim float.s

If you would like to install it on your own machine, download the source if you have a unix-based machine or download the executables if you have a PC. To properly compare floating point output and gather instruction statistics, download the version posted at http://www.cs.colostate.edu/~mstrout/spim/keepstats.html. For a unix-based machine, the only tricky thing I ran into was the EXCEPTION_DIR. Make sure to edit the Makefile in both the spim and the xspim directory to set your CPU_DIR and EXCEPTION_DIR. The EXCEPTION_DIR should be set to the full path to a directory that contains the exception.s file, which currently sits in the CPU/ subdirectory in the spim source.


Setting up a Subversion Repository

For more info on subversion, see http://svnbook.red-bean.com/.
  1. FIRST read chapters 2 and 3 in the subversion manual at http://svnbook.red-bean.com/.

  2. Suppose you have a project with just one file to begin with: Main.java.
    class Main
    {  
        public static void main(String args[])
        {
           System.out.println("Hello World!");
        }
    }
         
    Put Main.java into a file hierarchy with the following structure:
         ProjName.svn/
            trunk/
                src/
                    Main.java
            branch/
            tag/
         
  3. Create a subversion repository for your class projects
    // Make sure to replace $HOMEDIR with your own unix home directory.
    // For example, /s/parsons/c/fac/mstrout
    // Replace $MACHINE with a CS unix machine that you use often.
    // Replace $USER with your username.
    
    // creating the repository on a CS unix machine
    // NOTE: Each project will have its own repository.  
    // All the project repositories for CS553 will be in 
    // $HOMEDIR/SVNRepositories/CS553_Projects/.
    % cd $HOMEDIR
    % mkdir SVNRepositories
    % mkdir SVNRepositories/CS553_Projects
    % svnadmin create $HOMEDIR/SVNRepositories/CS553_Projects/ProjName
    
    // importing ProjName into the repository
    % cd ProjName.svn
    % setenv SVN_SSH 'ssh -l $USER'
        // if you are using bash do the following:
        % export SVN_SSH='ssh -l $USER'
    % svn import . svn+ssh://$MACHINE.cs.colostate.edu/$HOMEDIR/SVNRepositories/CS553_Projects/ProjName -m "Initial import"
    $USER@$MACHINE.cs.colostate.edu's password: 
    Adding         trunk
    Adding         trunk/src
    Adding         trunk/src/Main.java
    Adding         tag
    Adding         branch
    
    Committed revision 1.
    
    
    // get a working directory for the project
    % cd ..
    % setenv SVN_SSH 'ssh -l $USER'
        // if you are using bash do the following:
        % export SVN_SSH='ssh -l $USER'
    // for some reason the below command requires your password three times
    // I have seen this on other subversion servers as well
    % svn co svn+ssh://$MACHINE.cs.colostate.edu/$HOMEDIR/SVNRepositories/CS553_Projects/ProjName/trunk ProjName
        
  4. Commands you will need while working:

    svn commit
    When you want to save the changes that you have made
    svn add
    To add a file or a directory
    svn update
    Pull down any changes that have been committed to the repository by your partner.
    svn info
    To check which repository and the revision number this working directory is associated with. This information is most accurate after an svn update.
    svn status
    To obtain file and directory status - added, deleted, merged, ...
    svn diff
    To compare differences between file paths
    svn log
    To display commit messages for repository
    Subversion Quick Reference Card

  5. Using with eclipse
    First create a new eclipse project, then checkout a subversion project into that project's folder, now refresh your eclipse project.

  6. Working with a partner
    Make sure that the permissions on the repository are set so that everyone in your unix group can write to the repository. Assume that your unix group is cs553x. Your group will have a directory at ~cs553/cs553x. Here are the commands you need to perform to set up a repository in your group directory.
    % cd ~cs553/cs553x
    % mkdir SVNRepositories
    % svnadmin create ~cs553/cs553x/SVNRepositories/Project2
    
    // check the permissions, the cs553x, SVNRepositories, and Project2
    // directories should all have group rws permissions
    % ls -al 
    % ls -al SVNRepositories/
    
    // if they don't them change the permissions
    % cd SVNRepositories
    % chmod g+rwxs .
    % find . -type f -print | xargs chmod g+rw
    % find . -type d -print | xargs chmod g+rwxs
    
    

Java

(some fantastic Java Notes)
  1. NOTE: On CS machines, for javac you need the following in your path:
        /usr/local/java/bin
    
    Put it BEFORE /usr/local/bin and /usr/bin/.
        % setenv PATH /usr/local/java/bin:$PATH
        // if you are using bash do the following:
        % export PATH=/usr/local/java/bin:$PATH
    

  2. Make sure you can compile and run the Main.java specified above.
        % javac Main.java
        % java Main
        

Creating a jar file for the MiniJava compiler

  1. Create a mainClass.txt file and put the following lines in it (NOTE: you need a blank line after the Main-Class line):
    Main-Class: Main
    
    
  2. Run the jar utility with the following command:
        % jar cmf mainClass.txt lastname-MJC.jar *.class *.java */*.class */*.java */*/*.class */*/*.java */*/*.dat
    
  3. Now you can use the jar file to run your compiler.
        % java -jar lastname-MJC.jar infile.java
    

Using Eclipse

see http://www.eclipse.org/ for more information
  • Build and run the program in Eclipse
    1. Start Eclipse
          % /usr/local/bin/eclipse.sh
          
    2. File -> New -> Project
      1. Set Project Name to ProjName
      2. Select "Create project from existing source" and browse to find the ProjName working directory
      3. For some reason I couldn't set the compiler compliance level when I created the project. Right-click on the project and make the Compiler compliance level 5.0.

    3. Set up the editor to only use spaces and no tabs. This is a pet peeve of mine and of many other folks (just google "tabs versus spaces"). Your code should look the same no matter who is editing it. With tabs that isn't possible.
              - Window->Preferences
              - Find Java->Code Style->Formatter
              - Click on Edit...
              - Under the Indentation tab select "Spaces only" as your Tab policy
          

    SableCC

    SableCC is a lexer and parser generator, see http://sablecc.org/ for more information.

    Graphviz

    Graphviz is a tool for visualizing graphs, see http://www.graphviz.org/ for more information. The Graphviz executable for the Mac is awesome.

    Here is how you create a graphic on the CS department machines:

    1. Create the input file: test.dot
    2. Run dot
          % dot -Tpng -otest.png test.dot
          
    To generate a pdf file:
        % dot -Tps2 -Gsize=64,64 -Gmargin=0 -otest.ps2 test.dot
        % ps2pdf test.ps2 test.pdf
    
    Here are some notes for using dot on a PC, courtesy of Eric Eastman.
    After getting tired of transferring my ".dot" files from my Windows XP
    system where I am doing my Java work for the class, to one of the CS
    department's Linux systems to display them, I finally got the Graphviz
    package to run on my XP system.  Using the "dotty" viewer that comes with
    the Graphviz package I can now display the graphs under XP.
    
    I downloaded Graphviz from:
    
    http://graphviz.org/Download_windows.php
    
    I tried using the self-installing graphviz-2.8.exe file from this site and
    had problems with it, so after de-installing it, I downloaded the
    graphviz-win-2.8.bin.tgz file. This file has to be un-gzip, un-tar, and the
    directories hand installed, but the dot and dotty programs work under XP. 
    
    To display the graph of the file expr2.ast.dot that Michelle sent out last
    week, I used the command:
    
        dotty expr2.ast.dot 
    
    You can create a jpg file of the graph with the command:
    
        dot -Tjpg expr2.ast.dot  > expr2.ast.jpg
    
    
    I also downloaded and installed "Tintfu", a Java based Editor/Viewer for
    ".dot" files which works with the Graphvis package and allows you to edit
    drawings, from:
    
         http://tintfu.sourceforge.net/
    
    It comes as a single "jar" file, so it's easy to install. 
    

    LaTeX

    LaTeX is a type-setting program frequently used for writing Computer Science research papers, see http://www.latex-project.org/ for more information. Download the SampleLatex project, untar it, and then do a "make" inside the SampleLatex directory. See sample.tex for an example latex file.

    Extras

  • It is possible to set up Eclipse so that it runs SableCC automatically but I found this to be quite annoying especially after the context free grammar was stable. Set up Eclipse so that it runs SableCC automatically (thanks Brent!)
        Under Run => External Tools => External Tools...
            - Create a new configuration.
            - Give it a name, maybe "SableCC"
            - On the Main tab:
                - Provide the location of SableCC
                    For me it was "C:\sablecc-3.2\bin\sablecc.bat"
                - For the working directory I used "${project_loc}/src"
                    - Select the .scc file that you want to run (or run the 
                      main in that project and select nothing) before 
                      running this tool.
                - Under arguments I used "*.scc"
            - Under the Refresh tab:
                - Select "Refresh resources upon completion" and "The 
                  project containing the selected resource and 
                  "Recursively inc..."
            - Now you can just click on the green play icon with the red 
              tool box on the toolbar to the right of debug and run icons
    
        Now that I have a tool named "SableCC" I can add it as a builder for 
        a project.
            - Select a project, right click and select properties
            - Under builders you can either import SableCC (or create a new 
              one using a similar process)
            - Select that new builder and move it up so that it runs before 
              the Java Builder
        

    Michelle Strout
    Last modified: October 4, 2007