6.170 / Spring 2004 / Problem Set Procedure for 6.170

Handout S3

This document explains the procedure for how to do problem sets for 6.170 this semester which is considerably different than how they were done in the past. We are introducing some new tools, so this document explains what they are and how to use them for 6.170.

Basically, the steps for completing a problem set are as follows:

Start early.
Find a computer on which you are going to work and configure your environment. (Also, get comfy because you might be there awhile.)
Checkout the problem set from your CVS repository.
Think, write, code, compile, debug, commit. Repeat as necessary.
Turn in your problem set by doing a final commit to CVS and then run validate6170 to make sure that your problem set was submitted correctly.

The rest of this document explains these steps in greater detail...

Table of Contents:

Step 1: Start Early
Step 2: Find Someplace to Work
Step 3: Checkout the Problem Set from CVS
Step 4: Do the Problem Set
Step 5: Turn in Your Problem Set

Step 1: Start Early

As you know, 6.170 problem sets often take a long time to complete. Even if you cannot start a problem set as soon as it is released, you should read it over right away to try to gauge how much time you will need to complete it. Remember: Everything will take twice as long as you think even if you know that it will take twice as long as you think.
Don't deceive yourself into believing that you can put off your problem sets until the last minute – you know what you signed up for!

Step 2: Find Someplace to Work

If you decide to work in Athena, all you need to do to configure your environment is to run the following from the command line once (although nothing harmful will happen if you run it multiple times):

add 6.170
student-setup.pl

Then you have to logout and log back in for the changes to take effect. Now everything should be set up so that you can start working on your problem set. Be aware that the software that you will be using tends to run faster on the Athena Linux workstations than they do on the Athena Solaris boxes, so you should try to use the Linux machines whenever possible.

Working at Home

But maybe working in Athena isn't for you. Sometimes it smells bad, and now that the 24-hour-coffeeshop is gone, w20 may not have the "resources" you need to keep you going all night. Thus, you can try to setup your own machine for 6.170. The two things that you need to install are Sun's Java 2 Platform, Standard Edition (J2SE), v1.4.2_03 SDK and Eclipse. The installation instructions on each of these respective web sites should be enough to get you up and running. You'll find the link for downloading the SDK about halfway down Sun's page, and you may also want to download the documentation for v1.4.2 while you're there. The documentation is always available online, but you can access it quicker if you have a local copy of it on your machine.

As it is impossible for the 6.170 staff to be able to provide support for every platform, you are on your own if you have problems configuring these tools on your own computer. If you run into trouble, try searching the web for a solution as there is probably someone out there who has had (and solved) the same problem that you have.

Differences Between Using Eclipse on Athena and Using Eclipse at Home

There are two major differences between using Eclipse in Athena and using Eclipse at home:

On Athena, you launch Eclipse by typing runeclipse after you have run student-setup.pl. This script changes to the correct directory and sets an environment variable that Eclipse needs to work correctly with CVS. On your own computer, you should launch Eclipse by running whatever executable you downloaded from eclipse.org.
When you checkout from CVS through Eclipse on Athena, you should never have to enter your Athena password. On your own machine, you must enter your Athena password, in which case Eclipse will store your password in cleartext on your local machine. As this is a security risk, you may not want to use Eclipse on your own machine unless you can configure Kerberos to work with Eclipse so you can use your Kerberos ticket for authorization instead of your Athena password.

Setting up CVS in Your Environment

Setting up CVS in Eclipse Setting up Command Line CVS in Athena

Launch Eclipse using runeclipse if you are on Athena. If you are working on another platfrom, then launch the Eclipse executable that you downloaded.
Select Window >> Open Perspective >> Other... >> CVS Repository Exploring
Right-click in the "CVS Repositories" window, and select New >> Repository Location...
Fill in the fields as follows, and as shown below:
Host: athena.dialup.mit.edu
Repository path: /mit/6.170/students/your username
User: your username
Password: leave this field blank if you are on Athena; otherwise, enter your Athena password
Connection type: ext if you are on Athena; otherwise choose extssh
Click Finish
student-setup.pl should have set up CVS for you. To make sure, check to see that your CVS_RSH environment variable is set to ssh and that your CVSROOT environment variable is set to /mit/6.170/students/username by typing echo $CVS_RSH and echo $CVSROOT to print out the values of those variables.

Step 3: Checkout the Problem Set from CVS

This semester, you will manage versions of your code with a program called CVS which stands for Concurrent Versions System. This system keeps track of previous versions of your code so that you have a backup copy that you can revert back to, if necessary. More importantly, CVS enables multiple developers to work on a codebase at the same time by synchronizing different versions of files checked in by multiple developers. Although you will be the only person working on the code for your problem sets, you may want to switch back and forth between working in Athena and at home, so you can still take advantage of CVS's support for synchronizing multiple copies of code. Further, it is good practice to start using CVS now so that you'll be familiar with it by the time you start working on your team final project. More importantly, you will encounter CVS (or some other type of versioning-control software) in industry and elsewhere, so it is an important tool to learn how to use.

So how does it work? On Athena, we have created an individual CVS repository for you that has the code you need to get started for each problem set. Each problem set is its own module in CVS which you must checkout to your local machine. When you create a new file for the problem set, you must add it to CVS. Every time you make a change to a file worth that is worth recording, you commit that file to CVS. If someone else makes a change to the repository, you must update your local copy to get the other person's changes. CVS will try to merge the copy in the repository with your local copy, but if it can't, then it will notify you that there is a conflict which you must address.

You will begin each problem set by checking out a module from your CVS repository. This repository has been set up for you by the 6.170 staff. You can checkout your problem set from CVS by doing the following in your respective development environment (below, N is the number of the problem set that you are checking out from CVS):

How to Checkout in Eclipse How to Checkout from the
Command Line in Athena

Launch Eclipse using runeclipse if you are on Athena. If you are working on another platfrom, then launch the Eclipse executable that you downloaded.
Select Window >> Open Perspective >> Other... >> CVS Repository Exploring
Expand the CVS Repository directory structure, in the CVS Repositories Perspective Window. Expand HEAD, so that "psN" is visible.
Right-click "psN," and select Check Out As Project

cd ~/6.170/workspace/
cvs checkout psN

psN is the name of the module that you are checking out from CVS. Checking out will create the directory ~/6.170/workspace/psN/ which will have the contents of your problem set. (The workspace/ directory is used by Eclipse, so we create it now in either case so you have the ability to migrate from Emacs to Eclipse later on.)

Step 4: Do the Problem Set

Step 4 has a number of subtasks:

Creating a new file
Adding a file to the CVS repository
Editing and compiling code
Running unit tests
Committing changes to CVS
Updating your local copy of the CVS repository
Resolving CVS conflicts

Creating a New File

Every problem set will require you to create new java source files in addition to the ones we give you. You may also have to create new textfiles that answer questions asked on problem sets. These textfiles should be created in the doc/ directory.

Creating a New Java File

Regardless of whether you are creating a new Java class or a new Java interface, the file should have the same name (and capitalization) of the class or interface and end with a .java extension.

How to Create a Java Source File in Eclipse How to Create a Java Source File in Emacs

Select File >> New >> Class or Interface, depending on which type of file you are creating.
Fill out the fields of the dialog that comes up that are pertinent the new file that you are creating, especially Package, Name, and Source Folder whose value should be psN/src.
When the fields are filled out correctly, the Finish button will become enabled. Click it.

Use C-x C-f to bring up the "Find File" buffer in the bottom pane.
Type the fully-delimited path name of the file that you would like to create and press ENTER.

Creating a New Non-Java File

Relevant textfiles, screen shots, and diagrams should also be created in your psN directory.

How to Create a New Non-Java File in Eclipse How to Create a New Non-Java File in Emacs

Select File >> New >> File
In the dialog that appears, select the folder that should contain the file from the dialog, enter the name of the new file, and press the Finish button.

Note: If you have added a file to your psN directory through another program and you do not see it in your filetree in Eclipse, try right-clicking on the folder where you expect to see the file and choose Refresh.
For Emacs, the instructions for creating a new non-Java file are identical to the instructions for creating a new Java file above:

Use C-x C-f to bring up the "Find File" buffer in the bottom pane.
Type the fully-delimited path name of the file that you would like to create and press ENTER.

Adding a File to the CVS Repository

When you create a new file for your problem set, you must add it to your CVS repository.

Which files should be added to CVS?

For 6.170, you should expect to add the following files to CVS:

Java source files
Text files that answer questions asked by the problem set
Image files that depict diagrams of your design
Any file that the problem set dictates should be added to CVS

Which files should NOT be added to CVS?

By comparision, the following files should NEVER be added to CVS:

Generated .class files
Files generated by javadoc
Any file that is generated by some script of yours

These files should not be added to CVS because they should be cleanly generated by whoever checks out the module from CVS.

You may have noticed that CVS acknowledges when you have a file that has not been added to the repository. To tell CVS to ignore these files, you should add (and commit) a file named .cvsignore that has a list of files in the same directory that should be ignored by CVS. For example, in Problem Set 0, the file src/ps0/.cvsignore contains the line *.class so that CVS will ignore all .class files in that directory. Note that this does not recurse down the directory tree, so src/ps0/optional/ has its own (identical) .cvsignore file.

How Do I Add a File to CVS?

How to Add a File to the Repository in Eclipse How to Add a File to the Repository in Emacs

Open the Java Perspective by selecting Window >> Open Perspective >> Java.
Right-click on the file that you wish to add to the repository.
Select Team >> Add to Version Control

Eclipse should automatically detect which type of file (text/ASCII or binary) that you are adding.

When adding a file, you must indicate to CVS whether it is a text/ASCII file (such as a .java file) or a binary file (such as a .jpg image) when invoking the cvs add filename command. If you're already in your ~/6.170/workspace/ps0/ directory, you can add a text/ASCII file as follows:

cvs add src/ps0/RandomHello.java

But if the file is binary, then you need to use a -kb flag:

cvs add -kb doc/screenshot.jpg

Editing and Compiling Code

Traditionally, programmers switch back and forth between editing code and compiling it. However, Eclipse users perform these two tasks concurrently, as Eclipse takes advantage of partial recompilation and compiles code every time that you save it.

Editing Java Code in Eclipse Editing Java Code in Emacs

Double-click your file in Eclipse's filetree to open it, and edit the text in the window that opens with the contents of your file. If you prefer to use Emacs key bindings while editing code, do:
Window >> Preferences>> Workbench >> Keys and set Active Configuration to Emacs

Use C-x C-f to bring up the "Find File" buffer in the bottom pane.
Type the fully-delimited path name of the file that you would like to edit and press ENTER.
Edit the text in the buffer to edit your code.
If you are not familiar with Emacs, then you may want to visit the "Using Emacs to Edit Java Code" section on our tools page.

When you compile Java code, .class files are generated from your .java files. In 6.270, we generate the .class files in the same directory as the .java files. If one or more of your files does not compile, you will receive an error message from the compiler and no .class files will be generated for the .java file that does not compile.

Compiling Java Code in Eclipse Compiling Java Code from the Command Line
Compile your file by saving it. If your file is saved and Eclipse says that it does not compile but you believe that it should, make sure that all of the files on which your file depends are saved and compiled. If that does not work, try refreshing your project or using Project >> Rebuild Project to force Eclipse to recognize the latest version of everything. From the command line, you should use javac <options> <source files> to compile a group of Java files. Often you want to compile all of the files in a number of packages, so you must be sure to include the directory for each package that you would like to compile. For example, to compile all of the files in problem set 0, run the following from the ps0 directory that you checked out:

javac -sourcepath src/ -d src/ src/ps0/*.java src/ps0/optional/*.java
The -sourcepath flag indicates that the root directory for the Java packages to be compiled is src/. The -d flag indicates that the src/ directory is the destination for the .class files. Then src/ps0/*.java and src/ps0/optional/*.java are all of the Java source files that you need to compile.
If you think that this command seems too long or too complicated to type every time you want to compile a number of packages, you may want to consider using Ant.

Ant: A Java-Based Build Tool to Ease the Pains of Compiling

Ant is a tool that helps developers package up common tasks that they perform and wrap them with simplified commands. According to the Ant home page, Ant "is kind of like Make, but without Make's wrinkles." For example, instead of calling the long javac command above, you can call ant compile from the command line. Ant works by looking for a file named build.xml in the directory in which it is called and then looking for an Ant task with the same name as the argument passed to the command line ant command. We will provide a build.xml file with every problem set so that you can use Ant to perform tasks such as compile code or generate Javadoc. Note that you are not required to use Ant for your problem sets, but you may find it helpful to package your common tasks as Ant tasks. The Ant web site is rich with examples, so you will likely be able to find some sample code for your build.xml file to accomplish the task you are trying to encode.

Using Ant in Eclipse Using Ant from the Command Line

While in the Java Perspective, right-click on the build.xml file and choose Run Ant...
In the dialog that pops up, check off the Ant tasks that you would like to run and press the Run button.
For 6.170, the default task that runs when you type ant without an argument is a task called usage that prints out all of the available Ant tasks to the console. Though this is a 6.170 convention, it is a good habit to have a default usage task so that users of your build.xml file do not have to read the XML itself to see what tasks are available. To run a particular task, call ant taskname from the directory containing the build.xml file.

Running Unit Tests

Running the Tests using Eclipse

JUnit is integrated with Eclipse, so you can run the test suite from within the IDE.

First, select the test you want to run from the package explorer, the left pane. Since you want to test Card, you should select CardTest from the ps1 classes.
From the Eclipse menu at the top of the screen, select Run >> Run As >> JUnit Test
The JUnit GUI should pop up in place of the package explorer, momentarily, and run all the tests. You can double-click on failed tests to jump to the code for that test. When you're done inspecting the JUnit results, close the JUnit pane to go back to the package explorer.

Later on, when you have finished all the problems, you might want to run AllTests to run all the tests together.

If you are not working on athena, you might have to explicitly add the junit.jar library using Project >> Properties >> Java Build Path >> Libraries >> Add External JARs and then telling Eclipse where your copy of junit.jar is.

Running the Tests from the Command Line

If you are not using Eclipse, you can invoke JUnit from the command line. To run the Card test suite, type the following command:

athena% java junit.swingui.TestRunner ps1.playingcards.CardTest

For a non-graphical alternative method of running JUnit, use junit.textui.TestRunner instead of junit.swingui.TestRunner.

Committing Changes to CVS

When you make a change to a file that should be saved in the repository, you must commit the change to CVS. For whatever reason, cvs add does not actually add the file to your CVS repository; instead, it indicates that the file should be added to your repository upon your next CVS commit. Thus, you should always commit a file to CVS after adding it because you obviously meant to commit the new file if you decided to add it.

CVS Committing Using Eclipse CVS Comitting from the Command Line

Right-click on the file you would like to commit while in the Java Perspective.
Select Team >> Commit...
Enter a descriptive log message into the comment box and press OK.

You can commit a group of filename(s) to CVS by running: cvs commit -m "a descriptive log message" filename(s)

If you omit the message flag from your commit command, CVS will throw you into an editor where you can enter a message. If you have not set your $EDITOR environment variable to emacs, then this editor will most likely be vi. If you have never used vi before, you probably won't be able to figure out how to exit from it. The simplest thing to do is to type :wq to write-quit, cancel your cvs commit command, and rerun it using the -m flag.
If you omit the filename(s) from your commit command, then CVS will recursively commit everything in the current directory. This should be avoided so that files are not inadvertantly committed to the repository.

When you commit a file to CVS, you should always add a message when you commit so that you can quickly find an old version of a file if you need to revert to it. (You can see a log of your commits by running cvs log filename.) Also, when your repository is shared among a team of developers, your team mates may want to read your messages to get a summary of what you have committed.

When Should I Commit a File to CVS?

First, you should commit a file to CVS immediately after you add it so that you do not forget to do so later. After that, you should commit a file every time that you make an important change to it, so commit often! As a general rule, you should not commit files to CVS that do not compile because your team mates will be upset if you "break the build." Finally, you should also remember to commit all of your code to CVS before the problem set is due as that is how you will be turning in problem sets for this course.

Updating Your Local Copy of the CVS Repository

Normally, you update your local copy of your repository before working on it so that you get others' changes to the code before you start editing it. Although you will be the only person working on the code for your problem set, you should get in the habit of updating your code before you start working and committing when you are done. If you work on your code on multiple machines (such as on an Athena machine and on your own machine), then it is imperative that you commit your changes when you finish working in one place so you can use cvs update to get them when you sit down to work in another.

Running CVS Update from Eclipse Running CVS Update from the Command Line

Right-click on the file or directory you would like to update while in the Java Perspective.
Select Team >> Update
To update your local copy, go to the root of your repository and run:
cvs update
This will display a list of files that get updated. You should pay attention to the character that shows up in front of each file, as it indicates what sort of change was made to the file:

? Indicates that this file has not been added to the repository, so CVS has not edited it. This is an indication that the file should probably either be added to the repository or to a .cvsignore file in that directory

U Indicates that this file has been updated succesfully to match the latest copy in the repository.

M Indicates that your working copy of the file is different from the repository's latest version, but that merging the repository's copy with yours is successful.

C Indicates that there was a conflict when trying to merge your local copy of the file with the one in the repository. See information below about resolving CVS conflicts.

P Indicates that this file has been patched which for all practical purposes is the same as updated.

Resolving CVS Conflicts

CVS will try to merge any changes made since your last cvs update by both yourself and others. If some of your changes conflict with others' changes, cvs update will tell you so, and the source file will be changed to include both versions of any conflicting portions (yours and the one from the repository), in this format:

  <<<<<<< filename
  YOUR VERSION
  =======
  REPOSITORY'S VERSION
  >>>>>>> repository version's revision number

You must resolve the conflict by editing the file, removing the markers, and leaving whichever version of the code you prefer (or merging them by hand). (Searching for "<<<" until you've resolved all the conflicts is generally a good idea.) Once you've resolved any conflicts, you can safely commit the file to the repository.

Note that CVS works on a line-by-line basis. That is, it only knows whether an entire line has been changed, added, or deleted.

Step 5: Turn in Your Problem Set

In order to check that your problem set is ready to be turned in, use the validate6170 script. Log in to athena and run validate6170 ps0 in order to check that ps0 is ready to be turned in. The validate script will check that you have all of the required files and that they compile. It will also run the test cases that were provided with the problem set.

Your problem set is automatically collected from your CVS repository. There is no specific step for handing in a problem set.

How to Create a Java Source File in Eclipse	How to Create a Java Source File in Emacs
Select File >> New >> Class or Interface, depending on which type of file you are creating. Fill out the fields of the dialog that comes up that are pertinent the new file that you are creating, especially Package, Name, and Source Folder whose value should be `psN/src`. When the fields are filled out correctly, the Finish button will become enabled. Click it.	Use C-x C-f to bring up the "Find File" buffer in the bottom pane. Type the fully-delimited path name of the file that you would like to create and press ENTER.

Editing Java Code in Eclipse	Editing Java Code in Emacs
Double-click your file in Eclipse's filetree to open it, and edit the text in the window that opens with the contents of your file. If you prefer to use Emacs key bindings while editing code, do: Window >> Preferences>> Workbench >> Keys and set Active Configuration to Emacs	Use C-x C-f to bring up the "Find File" buffer in the bottom pane. Type the fully-delimited path name of the file that you would like to edit and press ENTER. Edit the text in the buffer to edit your code. If you are not familiar with Emacs, then you may want to visit the "Using Emacs to Edit Java Code" section on our tools page.