athena% mkdir ~/6.170
athena% fs sa ~/6.170 system:6.170 readYou should then create subdirectories ~/6.170/ps1, ~/6.170/ps2, etc., for the problem sets. 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.
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.
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. Alternately, see the staff list for email information, or ask for help on the 6.170 zephyr instance.)
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:
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.add -f java_v1.4.0_01 add 6.170
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 BOOTCLASSPATH /mit/java_v1.4.0_01/jre/lib/rt.jar
Explanations:
If you have a .path file, be sure that it puts $athena_path first, n order to get the proper version of the Java tools.
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 the Java documentation page at MIT (http://web.mit.edu/java/www/home.html).
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 javac, 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
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.javac [options] file1.java file2.java ...
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.Testto 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.
(load "/mit/6.170/etc/emacs/6170.el")This causes the following changes:
(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.
The Six170Doclet extends Javadoc 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.
| Indicates that name is a abstract specification field of type T for the class, adding text as a comment if present | |
| Same as specfield, except that this also adds the property "derived" to the output information | |
| @endspec | Signals to Javadoc 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 : integerwe 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 |
To use Six170Doclet with javadoc, you use the same syntax as you would with the original javadoc tool, except that you invoke javadoc6170 instead of javadoc. Thus, if you would normally generate specifications by typing
then to make use of the Six170Doclet you would type:athena% javadoc -d spec-directory -sourcepath /mit/$USER/6.170/ ps1 ps2 ps3
athena% javadoc6170 -d spec-directory -sourcepath /mit/$USER/6.170/ ps1 ps2 ps3
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 Javadoc 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
then <x> and <y> will be interpreted as HTML tags in the output (and won't be displayed by a browser).@effects Adds <x> and <y>
Report any weird behavior or complaints about Six170Doclet to 6.170-tas@mit.edu.
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.)
To subscribe, type
zctl add message 6.170 \*
To write to the instance, type:
zwrite -i 6.170
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.
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
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.
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.
The 6.170 zlog is stored in the zlog locker on athena. To access it, first type at the athena prompt:
athena% add zlogThe 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
athena% add outland athena% xwrits typetime=5 breaktime=0.50 +beep +clock +idle +mouse maxhands=5 +multiply +noiconify +lock &
You can also put the xwrits command in your .startup.X file.
athena% add acro athena% distill file.pswhich 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.
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 2000 and Visio v.5 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.
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 ssen at MIT (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.
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 Javadoc 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:
Each user will have their own working copy somewhere. We suggest that you create a set of /mit/6.170/groups/seNNM/username directories.
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 from http://www.wincvs.org/ or a non-graphical version from http://www.cvshome.org/; Also see Jeremy Nimmer's hints about getting CVS to work on Windows machines. For Macs, download MacCVS from http://www.maccvs.org/.
Please note that we only officially support use of CVS on Athena.
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/repository 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.)
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:
cvs -d /mit/6.170/groups/seNNM/repository checkout gb
setenv CVS_RSH ssh cvs -d :ext:USERNAME@athena.dialup.mit.edu:/mit/6.170/groups/seNNM/repository checkout gb
Finally, create a ~/.cvsrc file containing the following two lines:
diff -u update -d -PSee the manual for more information about ~/.cvsrc 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.)
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.
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.
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.
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
Alternately, you can use the pcl-cvs package to run CVS commands and browse the output. The primary command is
M-x cvs-update RETwhich 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 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!
Some tips on avoiding common problems while using CVS:
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."
Additional information is available from CVS Home (see especially CVS for new users and the CVS manual). The CVS manual is available is a variety of formats.