Handout S2: Tools
Table of Contents:
Also see the documentation for the Daikon invariant detector.
Directories
You must create a directory named 6.170 in your home directory on Athena and give read access specifically to the 6.170 staff. This will allow the 6.170 staff to see and test your code on Athena, without granting access to your code to all Athena users. (It is a violation of the collaboration policy to permit anyone besides the 6.170 and yourself read-access to your ~/6.170 directory, or any other location where you keep 6.170 code.) The name of the group for 6.170 staff is system:6.170.
athena% mkdir ~/6.170
athena% fs sa ~/6.170 system:6.170 read
You should then create subdirectories ~/6.170/ex1, ~/6.170/ex2, etc., for the exercises. All of these subdirectories will automatically inherit the right set of permissions from the parent directory if these steps are performed in the proper order.
Failure to put your code online in the proper place will prevent us from collecting your problem sets, annoy your TA, and lower your grade.
Even if you use your own PC for coding 6.170 problem sets, your code still must also work on Athena, and you must place your source code and other files on Athena for testing and grading purposes.
When you start your final project, you will be given a group locker. You may then set the appropriate permission on it to allow your group members access your files. You will get more information on this later.
Top
Using Java™
Sun Microsystems' Java™ Development Kit (JDK) is available on Athena, and may be used for coding 6.170 problem set solutions. Before using Java™ on Athena, you will need to perform some basic setup steps.
Initial Setup
You will need to attach the 6.170 and Java™ lockers, as well as set the CLASSPATH environment variable. We provide a script which will edit your dotfiles for you, but you may also decide to make the changes by hand.
Top
Using the Helper Script
Type the following commands at your athena% prompt:
add 6.170
student-setup.pl
If you see the message "6.170 setup complete", you are done. You must logout and login again for the changes to take effect. If you see an error message, contact the course staff for assistance. (The best way to get help is to visit an LA during office hours or ask for help on the 6.170 zephyr instance.)
Top
Manual Setup
This section describes the necessary steps for your initial setup. This section may be skipped if you have used the helper script mentioned above, but is useful if you would like to make the edits yourself, or would like to know exactly what changes are made.
You need to attach the "6.170" and "Java" lockers. The 6.170 locker contains copies of handouts, code libraries that you will use when completing your problem sets, and source code for some libraries. The "java" locker contains the Java™ compiler javac and the Java™ interpreter java.
To attach these lockers automatically when you log in to Athena, add the following lines to your .environment file:
add 6.170 add -f java_v1.3.0
These lines will take effect the next time you log in to Athena. To make them take effect in the current session, you may also type the same lines at the Athena prompt. Once these lockers are attached, you may access the 6.170 locker through the /mit/6.170 directory.
Before using Java™, you will also need to set your CLASSPATH environment variable. Add the following lines to your .environment file:
setenv CLASSPATHLIB `perl -e 'print join(":", @ARGV);' /mit/6.170/lib/*.jar` setenv CLASSPATH /mit/${USER}/6.170:${CLASSPATHLIB} setenv RTJAR /mit/java_v1.3.0/jre/lib/rt.jar
Explanations:
-
- CLASSPATH: The variable used by Java™ when searching for classes to compile or execute. We define this to include all 6.170 code you write (the /mit/$USER/6.170 part) as well as compiled code which the staff provides (${CLASSPATHLIB}).
- CLASSPATHLIB: Includes the 6.170-provided class libraries. Not used directly by Java™, but useful to have available in your environment. (If you are typing the line in by hand, note that the outer quotes are backticks, the next-inner quotes are single-quotes, and the inner quotes are double-quotes.)
- RTJAR: Includes the standard Java™ classes, such as java.lang.Object. You will not normally use this variable, but may need it if you use the jikes compiler, an alternative to javac.
Be sure to make these edits correctly. You will not be able to access the 6.170-provided classes if you do not set your CLASSPATH properly.
Top
Writing and Compiling Code
To write code in Java™, you start by writing a Java™ source file. Java source filenames usually have a ".java" extension. Source files are just text files, which you may create and edit with Emacs or your favorite text editor.
You must compile your source code before running it. The Javac compiler is used to transform Java™ programs into bytecode form, contained in a class file. Class files are recognized by their .class extension. The bytecode in class files can then be executed by the Java™ interpreter.
Extensive on-line documentation for javac, Java™, and other tools in the JDK can be found through Sun's Java page (http://www.sun.com/java)
A Java™ program consists of one or more packages, each of which defines a group of related abstractions. Each package consists of one or more classes. Each class is produced from a source file that implements the abstractions.
Using Java™c, one or more source files can be compiled into class files for execution by the interpreter. At least one of the resulting classes must define a method named "main", which serves as the starting point for execution of the program. Once all of the source files have been compiled the program can be run using java, the Java™ interpreter. Running the following line
javac [options] file1.Java file2.Java...
will generate class files file1.class, file2.class, etc., for each specified source file. Type "man javac" at the Athena prompt for more information on javac options. You should almost always use the -g option, which will provide improved debugging output.
Once you have compiled your source code into class files, you can execute it with the Java™ interpreter java. The command
java options classname
will execute the class indicated by classname. This class must exist in your current CLASSPATH, or you will need to use the -classpath option to specify a different CLASSPATH. The class that you execute must also contain the "main" method discussed above. If you wish to run a class that is not in the default package, you must specify the complete class name; for instance, use
java ps1.Test
to run the main method of the Test class in the ps1 package. For a complete description of all of Java's options type java -help at the Athena prompt.
Top
Useful Java™ Sites
Top
Using Emacs to edit Java™ code
The 6.170 staff has prepared a set of customizations for Emacs to make Java™ code easier to edit. To use these customizations, add the following line to your .emacs file (or create a .emacs file in your home directory containing the following line, if you don't already have one):
(load "/mit/6.170/etc/emacs/6170.el")
This causes the following changes:
- Pressing RET (return) not only inserts a newline but also sets up default indentation for the next line. C-j only inserts a newline.
- Pressing C-c C-c saves and compiles the current program. If there's not a makefile in the current directory, the default command run for Java™ files is javac -g *.java.
- Pressing C-h f (mnemonic: "help for function") runs jdk-lookup, which displays JDK documentation for a Java™ package, class, method, or field.
- Pressing C-c C-r comments out the selected region, and pressing C-u C-c C-r uncomments the region. (You can select a region in Emacs by moving to one end, pressing C-SPC, and moving to the other end, or by clicking at one end and dragging to the other end.)
- Middle-clicking on a Java™ stack backtrace takes you to the code for the clicked-upon frame.
- The default indentation is reduced to 2 spaces per indent.
- In all modes, not just when editing Java™ files, syntax highlighting ("font locking", in Emacs terminology) is enabled.
If you want some, but not all of these, customizations, add the line
(setq make-6170-changes nil)
to your .emacs file before loading the file. This will define all of the functions but make none of the customizations. Feel free to look at the 6170.el file and copy out the bits you find useful.
Top
Using Java™doc and Six170Doclet to generate specs
Sun's Java™ Development Kit includes Javadoc, a tool that produces specifications from source code annotated with special comments. The comments may include "tags", which are introduced by an at-sign (@).
The Six170Doclet extends Java™doc to recognize additional 6.170 tags, as well as all the tags accepted by the Sun Standard Doclet. (The Six170Doclet actually works as a preprocessor, producing a new input file which can be read directly by the Sun Standard Doclet.) These additional tags declare specification fields for classes and requires, modifies, and effects clauses for methods.
In addition to adding new tags, Six170Doclet automatically infers missing method summaries and has a few other features that make specifications easier for people to write and read even when looking at the code itself.
- Some extended tags belong in the overview for a class; they are used to formally define what a given Abstract Data Type represents.
| @specfield name : T // text |
Indicates that name is a abstract specification field of type T for the class, adding text as a comment if present |
| @derivedfield name : T // text |
Same as specfield, except that this also adds the property "derived" to the output information |
| @endspec |
Signals to Java™doc that there are no more abstract fields to document in the spec |
Derived fields can be viewed as functions on preexisting state; thus if a class had a specfield
@specfield n : integer
we could define a derived field
@derivedfield pos : boolean // pos = true iff n > 0
Derived fields are not allowed to hold any information that could not be already calculated from the already existing state in the object. Thus, you use specfields to introduce new state variables and derived fields to introduce functions on those state variables.
Derived fields are not strictly needed in specifications, but they may reduce complexity and redundancy.
| @requires X |
Declares X to be a precondition for the procedure |
| @modifies Y |
Declares that everything outside of Y will not be modified by the procedure (as long as X holds) |
| @effects Z |
Declares that if X holds at the start of the method, then Z will hold at the end of the method |
After running javadoc, you should check the output. You may find that you need to add line breaks (<br>) or paragraph breaks (<p>) for readability. Also, if you omit certain tags (such as @endspec), subsequent text may fail to appear in the output. Finally, since much of the text of Java™doc comments is inserted in a HTML document, you must be careful with text that can be interpreted as HTML markup. For instance, if you write
@effects Adds <x> and <y>
then <x> and <y> will be interpreted as HTML tags in the output (and won't be displayed by a browser).
Top
Zephyr Instance
You may want to subscribe to various zephyr instances pertaining to this class. These instances can be a useful resource, for instance as a supplement to visiting an LA during lab hours. The main instance is called 6.170. This zephyr instance allows you to get in touch with fellow classmates and any lab assistants that are on duty. (Lab assistants give priority to students who visit them in person during lab hours, which is a better way to interact with them in any event. However, they will attempt to monitor the instance and also provide help via that mechanism, time permitting.)
Top
Mechanics
To subscribe, type
zctl add message 6.170 \*
To write to the instance, type:
zwrite -i 6.170
To unsubscribe, type
zctl delete message 6.170 \*
To unsubscribe for the current login session only, substitute "unsub" for "delete" in the above line:
zctl unsub message 6.170 \*
For more information on zctl, type "man zctl" at the Athena prompt or check out the Inessential Zephyr document available on-line.
Top
Guidelines
The 6.170 instance is intended strictly for questions and answers directly related to problem sets and Java™. The TAs and LAs will generally subscribe to the 6.170 instance as long as the signal-to-noise ratio remains high. We will occasionally answer questions on the instances, especially if we see a "not-quite-correct" answer or general confusion. However, if you have a question for a TA, e-mail your TA instead. Also, questions on the instance are not guaranteed to receive a response from a staff member; to be sure of attention, visit an LA or TA during lab/office hours.
Certain questions are not appropriate for the zephyr instance. These include
-
"Here is my solution. Is it appropriate? Is it adequate?"
(This breaks the no-collaboration policy by broadcasting your solution. It is a violation of the collaboration policy to zephyr more than 5 lines of code to the instance.)
-
"What does function foo in the JDK API do? What arguments does it take?"
This question is evidence of laziness. You should look in the JDK API documentation instead.
-
"Is an LA or TA online?"
First, this question is irrelevant; being online is not the same as being on duty. Second, even if an LA is on duty, the LA may be helping other students (particularly those who visit the LA in person).
You should either visit an LA or a TA, or you you should just ask your question on the instance and hope it gets an answer.
If you want to talk about 6.170-related topics which are not specific questions or answers, you should use the 6.170.d instance. For example, if want to start a debate on the aesthetic virtues of Java™, wish to chat about the wonderful writing style of the problem set authors, or have to express frustration about the bug you've been hunting for two hours, the 6.170.d instance should be used instead of the 6.170 instance.
The mechanics of the 6.170.d instance are the same as 6.170, except you add a .d onto the obvious place in the examples above.
Top
Zephyr Log
Since the 6.170 zephyr instance is often high traffic, the constant stream of zephyrs can be distracting. Also, some students spend time OFFLINE (!), and thus can't benefit from the discussions taking place on the instance in real time.
The 6.170 zlog is a solution to these two problems. It logs every message sent on the 6.170 zephyr instance. This way, you can unsubscribe from the instance and read the conversations that others are having on the instance separately, on your own time and at your own pace. You can also review conversations that took place while you were logged off. It is often very useful to skim the log before starting the problem set, just to check if there are any common problems with the Java™ runtime that other students are encountering and prepare to handle them yourself.
Top
How to use the zlog
The 6.170 zlog is stored in the zlog locker on athena. To access it, first type at the athena prompt:
athena% add zlog
The 6.170 zlog is in the file /mit/zlog/6.170
The zlog is a text file like any other. Therefore, you could try opening it in your favorite text browser. However, it can grow very large, which makes navigating the messages difficult.
Thus, it is recommended that you try the tail command as an alternate way of reading the zlog. The tail command is similar to the cat and head commands in Unix, except that instead of starting at the beginning of a file and printing the successive lines, it starts at some point near the end of a file and then prints the remainder of the file to the terminal. This way you don't have to scroll through pages of zephyrs you saw the last time you were logged in; you just see the last few ones that were sent.
You can tell tail to start at an arbitrary offset from the end or the beginning of the file; the default action of
athena% tail /mit/zlog/6.170
is to print the last ten lines of the zlog. To have it start further back, pass the -number option to tail, where number is the number of lines to offset the starting point from the end of the file. So,
athena% tail -50 /mit/zlog/6.170
outputs the last 50 lines of the log.
You can even have tail wait and print out new zephyrs as they come in, if you prefer not to mix the 6.170 instance conversations with your personal zephyr conversations. To do this, use the -f option, as in:
athena% tail -f /mit/zlog/6.170
For more information on tail, read the man page, by typing at the athena prompt:
athena% man tail
Top
Creating PDFs
You may submit diagrams (or other non-code homework) electronically in PDF form. You can convert PostScript to PDF by running Adobe Acrobat Distiller, as follows:
athena% add acro
athena% distill file.ps
which produces file.pdf.
Please note that distill is only available for the Sun platforms. If this is a problem, you may choose to run it on a dialup server, or may also use the ps2pdf utility in the gnu locker.
Top
Visio®
Visio® 2000 is available for download as a zip file. Note: you must be have an MIT IP address to download this file. It is also quite large (224 MB). A limited number of CD versions are available for those to whom this presents a problem. Visio® is a program for drawing diagrams that you can use for object models and module dependency diagrams. For more information about it, refer to the Visio® 2000 website.
When installing Visio® 2000 on a Windows 2000 machine, refer to Microsoft Support if you receive an error message of "Visio2000: Error Message: The Procedure Entry Point GBL Could Not Be Located in the Dynamic Link Library Vislib32.dll."
6.170 Visio® stencils for Visio® v.5 (ZIP) are available as zip files. Use these in your OMs and MDDs. After downloading and unzipping, the 6170 directory should be placed in the Solutions subdirectory of your Visio® installation.
If you are working on Athena or do not have a Windows machine, you can use Dia® in place of Visio®.
Top
Dia®
If you do not have a Microsoft Windows machine (and therefore cannot run Visio®), there is an alternative diagram drawing program, named "dia".
If you have added the 6.170 locker and are on a Sun or Linux machine, then you should be able to run it by running
athena% dia &
Dia® can export its diagrams as encapsulated postscript files, which you can then convert to pdf. Or you can print out the diagrams from Dia® itself.
If you have problems running dia, email pnkfelix@mit.edu (not 6.170-staff).
If you have problems using Dia®, see the below links:
Tutorial for Dia
Dia® homepage
6.170 is not officially supporting Dia® (don't ask your TA about how to use it; chances are they do not know), but it is an alternative to Visio®.
Top
CVS
CVS (Concurrent Version System) allows multiple users to edit the same files independently, working on their own copies. There is a "repository" where the master files are kept. Each user "checks out" a working copy. They then edit that copy, "check in" or "commit" their changes back into the repository, and "update" to incorporate others' changes into their working copy. CVS also keeps track of previous versions of your files, so you can compare versions or revert to a previous version if a changed introduces a bug.
CVS repositories contain text-based files such as source files (.Java™), Makefiles, and some documentation. Repositories should not contain compiled files (.class) or generated text files, such as Java™doc documentation. Your CVS repository should only contain files which cannot be regenerated from the other files in the repository.
Here is a typical list of steps in CVS usage:
- "Update" your checked out files.
- Add/edit a file.
- "Update" again to see if the files have changed in the repository since you started editing. If they have, the changes will be merged into your working copy automatically.
- If there is a "merge conflict", where two changes conflict with each other, manually decide which change to keep.
- "Commit", aka "Check in", the file.
Each user will have their own working copy somewhere. We suggest that you create a set of /mit/6.170/groups/seNNM/username directories.
Top
Setup
Installation
If you are working on athena, add this line to your ~/.environment file:
add gnu
If you work at home on a Linux machine, it probably has CVS installed already. For Windows machines, download WinCVS or a non-graphical version; Also see MIT IS CVS documentation. For Macs, download MacCVS.
Please note that we only officially support use of CVS on Athena.
Per-group setup
There are 2 steps to setting up CVS. First, the repository is created and a module is added to it; then, each user checks that module out.
A "module" is a group of files in CVS. You will likely just need one module for 6.170; let's call it gb. Run the following commands once per group:
setenv CVSROOT /mit/6.170/groups/seNNM/.cvs
cvs init
cd /mit/6.170/groups/seNNM
mkdir $USER; cd $USER
mkdir gb; cd gb
cvs import -m "Start" gb seNNM start
cd ..
(The -m flag denotes a log message; more on these later. The seNNM and start parameters are arbitrary, but must be there for the cvs import command.)
Per-user setup
After the repository has been created, each user should check out the gb module into their own working directory. First, create your working directory and switch to it:
cd /mit/6.170/groups/seNNM
mkdir -p $USER; cd $USER
Then, check out the gb module:
- Local checkout (from Athena):
cvs -d /mit/6.170/groups/seNNM/.cvs checkout gb
- Remote checkout (from non-Athena computer):
setenv CVS_RSH ssh
cvs -d :ext:USERNAME@athena.dialup.mit.edu:/mit/6.170/groups/seNNM/.cvs checkout gb
Finally, create a ~/.cvsrc file containing the following two lines:
diff -u update -d -P
See the manual for more information about ~/.cvsrc files.
Top
Basic Usage
Updating your files
To update your working copy with the latest revision from the repository (but retaining any changes you have made in your local copy), use:
cvs update
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.
(cvs update displays the status of any files in your working directory that have changed or are different from the repository with a one-letter flag: "U" means it has been replaced with the latest copy from the repository. "M" means your working copy is different from the repository's latest version, and that merging is successful. "C" means that there are merge conflicts.)
Committing, adding, and removing files
To commit a file you've edited to the repository, use:
cvs commit -m "a log message" filename
If you omit the filename, CVS will commit all files in the current directory. The message is a log message that allows you to keep track of changes without reading through the code. These are incredibly useful, and you should always enter a descriptive log message; you should not enter something like, "Fixed some bugs." If you omit the -m flag, CVS will prompt you for a log message.
To add a file to the repository, use:
cvs add filename
To remove a file from the repository:
rm filename
cvs rm filename
cvs commit -m "Removing the file for such and such reason"
These commands only mark the file for addition or deletion. After running cvs add or cvs rm, you'll still need to use cvs commit to actually notify the repository of the change.
To move or rename a file or a directory in CVS, you must remove it from one location and add it to another.
Adding and removing subdirectories
You can add a subdirectory with:
mkdir dirname
cvs add dirname
cvs adding a subdirectory happens immediately, without the need to commit.
You cannot remove a subdirectory with CVS. (cvs rm cannot be used on a directory.) The best you can do is to rm and cvs rm everything in that directory, then run cvs update -P to get rid of any empty subdirectories in your working directory.
Tracking changes
To see the change log, which is a list of the messages used when checking in changes,
cvs log filename
To see differences between the working copy and the repository's latest copy:
cvs diff [filename]
Omit filename to see differences for all files. Use the -r1.xx flag to compare with a particular revision, and use two -r flags to compare two versions with each other.
Top
Tips and techniques
CVS in Emacs
Emacs has built-in-support for CVS. There are two ways you can invoke CVS commands from within Emacs: either from within a buffer that is visiting a file, or from a buffer that lists all modified files and permits you to perform operations on them.
CVS commands to perform actions from a file-visiting buffer are prefixed by C-x v (mnemonic: version control). The three most useful commands are
C-x v =: vc-diff- Show differences between your working copy and the repository version, like cvs diff.
C-x v =: vc-next-action- In most circumstances, this commits changes you have made, like cvs commit. You will enter a log message into a special buffer, then type C-c C-c to actually commit the file.
C-x v C-h: show VC bindings- List all the commands starting with C-x v.
Alternately, you can use the pcl-cvs package to run CVS commands and browse the output. The primary command is
M-x cvs-update RET
which runs cvs update and puts the results in a *cvs* buffer for you to browse. You can then operate on each line with commands such as the following:
=: cvs-mode-diff- Show differences between your working copy and the repository version, like cvs diff.
f: cvs-mode-find-file- "Find" (edit) the file, using Emacs.
c: cvs-mode-commit- Commit your changes, like cvs commit. You will enter a log message into a special buffer, then type C-c C-c to actually commit the file.
g: cvs-update- Re-run cvs update and update the current (*cvs*) buffer with the new results
r: cvs-mode-remove- Delete the file and run cvs remove on it. You still need to commit that change.
m: cvs-mode-mark- Mark a file for later operation. This permits you to operate on multiple files at once, for instance to commit them simultaneously with the same log message. Most cvs-mode (commit, remove, etc.) operate on all marked files, or on the file under the Emacs cursor ("point") if no files are marked.
u: cvs-mode-unmark- Unmark the file at point.
h: cvs-mode-help- Give (very brief) help on commands
Top
Minimizing merge conflicts
CVS is no replacement for management! Coordination of work is important, even if you're working separately. You should minimize working on the same file at the same time if possible. If you do work on the same file, work on different portions. Modularizing code into multiple files often makes parallelizing work more efficient. You should always pass major design decisions by your teammates before implementing them, particularly if they involve interfaces that will affect their code.
When should you commit? If you commit too often without sufficient testing, you may introduce bugs into the repository that will affect your groupmates' work. However, if you commit too rarely, your groupmates will be using outdated code, which may cause wasted effort and merge conflicts later.
There is no hard and fast rule, but one good rule of thumb is to make sure everything at least compiles before you check in. There's nothing more annoying than having your code cease to compile after checking out someone else's changes.
Another good rule of thumb (though this one is far more malleable) is that you should minimize leaving something uncommitted when you quit for the day. A lot can happen while you're not coding, and it's generally better to get your change in working order and commit it before you leave. Since the previous rule (of never checking in non-working code) is more important, this can be hard to accomplish if you're making big changes. Thus, it's often good to tackle one feature at a time, so you can finish each piece quickly and keep the repository up-to-date.
Coordinating your efforts with your groupmates is, of course, the true key to minimizing merging hassles. Again, CVS is no replacement for management!
Top
Pitfalls
Some tips on avoiding common problems while using CVS:
-
Do not edit the repository manually. It wasn't designed for human use.
-
Try not to make many drastic changes at once. This will minimize merge conflicts. This is good coding practice in general.
-
Always cvs update before editing a file. It's easy to forget this. If you do, you may end up editing an outdated version, which can cause nasty merge conflicts.
-
In case another group member didn't check in their changes and isn't available, you may want to check in their changes for them. You can do this by simply cding to their working directory and doing a cvs commit from there. This should only be done as a last resort. And before you do so, you should use cvs diff to find out exactly what changes they've made, and whether you really want to check them in.
- Watch out for tabbing. Emacs's auto-tabbing can be a different width for different people, and other text editors also vary in the way they treat tabbing, both in terms of width and in terms of whether tabs are true tabs, spaces, or both. All text editors that your groupmates use must use the same tabbing convention. This is because CVS compares on a line-by-line basis, so tabbing differences can often cause nasty merge conflicts. This is just a specific case of "You should agree on a code formatting convention."
Top
More information
There's a lot more that CVS can do that isn't mentioned in this quick start guide. Please read the documentation for more help.
To read the CVS manual on athena, use the command info cvs. Alternately, from Emacs, do M-x info RET m cvs RET, where M-x is pressing x while holding down the meta key or the alt key, RET is the return key, and you do not need to type any of the spaces. See, in particular, the sections "Starting a new project" and "Overview/A sample session". Additionally, if one or more of your group members wants to work from home, you will want to read the section on "Repository/Remote repositories."
Top