athena% mkdir ~/6.170
athena% fs sa ~/6.170 system:6.170 readYou should then create subdirectories ~/6.170/ps0, ~/6.170/ps1, 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. For example, all of your files regarding the first problem set should be under ~/6.170/ps0.
Failure to put your code online in the proper place will interfere with the operation of our auto-tester, 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.
These lines will take effect the 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 6.170 add -f java_v1.3.0
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.
Before using javac, you should add the following lines in your .environment file. These lines will set your CLASSPATH environment variable to include the 6.170-provided class libraries as well as your own generated classes. You will not be able to access the 6.170-provided classes if you do not set your CLASSPATH properly.
if ($?CLASSPATH) then
setenv CLASSPATH ${CLASSPATH}:.:/mit/$USER/6.170:/mit/6.170/class
else
setenv CLASSPATH .:/mit/$USER/6.170:/mit/6.170/class
endif
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.
Once you have compiled your source code into class files, you can execute it with the Java interpreter java. The command
java options classsname
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.
(defun my-java-mode-hook () ;; use two spaces for indentation (setq c-basic-offset 2) ;; make return also do indentation; make newline not do indentation (local-set-key "\15" 'newline-and-indent) (local-set-key "\12" 'newline)) (add-hook 'java-mode-hook 'my-java-mode-hook)
Meta-x font-lock-modeTo automatically color every .java file you edit in Emacs, add the following line to the .emacs file in your home directory:
(add-hook 'java-mode-hook '(lambda () (font-lock-mode 1)))
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 just pass a few argument to javadoc when you run it on the command line. If you would normally generate specifications by typing
then to make use of the Six170Doclet you would supply the additional parameters -docletpath and -doclet, like so:athena% javadoc -d spec-directory \ -sourcepath /mit/$USER/6.170/ ps1 ps2 ps3
athena% javadoc -d spec-directory \ -docletpath /mit/6.170/class -doclet Six170Doclet \ -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>
You can look at the .java files in directories /mit/6.170/handouts/ps1-spec, /mit/6.170/handouts/ps2-spec, and /mit/6.170/handouts/ps3-spec for examples of specifications written for Six170Doclet.
Report any weird behavior or complaints about Six170Doclet to pnkfelix at MIT (not to 6.170-staff@mit.edu).
To write to one of these instances, type:
zwrite -i INSTANCE-NAME
To unsubscribe, type
zctl delete message INSTANCE-NAME \*
To unsubscribe for the current login session only, substitute "unsub" for "delete" in the above line.
The 6.170 instance is intended strictly for questions and answers directly related to problem sets and Java. If you want to start a debate on the aesthetic virtues of Java, for instance, write to 6.170.d instead. 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.
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 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, it is recommended that you
read the man page, by typing at the athena prompt:
athena% man tail
athena% add acro athena% distill file.pswhich produces file.pdf.
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 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.
The most widely used (free) revision control package is the Concurrent Version Control (CVS). CVS is available on Athena in the gnu locker. If you are working on athena, you probably want to add this line to your ~/.environment file.
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/. For Macs, download MacCVS from http://www.maccvs.org/.add gnu
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.
cvs -d /mit/6.170/groups/se99/.cvs init mkdir /mit/6.170/groups/se99/.cvs/gbThis only need to be done once per group, not once per person.
cvs -d /mit/6.170/groups/se99/.cvs co gb
cvs -d :ext:USERNAME@athena.dialup.mit.edu:/mit/6.170/groups/se99/.cvs co gb
Each person in a group must run this command. You may choose to put your gb directory in your personal athena directory, or in a personal subdirectory of your groups/se99 directory. (The former prevents the possibility of accidentally modifying one another's files. The latter provides more disk space and permits examination of one antoher's files.)
You will do all your editing in this private subdirectory of your own. You have control over all files. Other users have their own version of the files, which they can edit simultaneously. The repository containing the master version, which no one edits directly.
To update your code from the repository, merging in any changes made to the repository since you last updated from it, do
cvs updateAlternately, from Emacs do M-x cvs-update RET, which uses the pcl-cvs Emacs package.
You might wish to update from others' changes even if you're not ready to commit your own changes because
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 (yours and the one from the repository), in this format:
<<<<<<< filename YOUR VERSION ======= REPOSITORY VERSION >>>>>>> versionnumYou resolve the conflict by editing the file, removing the markers and leaving whichever version of the code you prefer (or merging them by hand).
To commit your changes -- that is, to replace whatever is in the repository with your versions -- do
cvs commit(Emacs's pcl-cvs package provides convenient ways to access all cvs commands, including this one.) You are not allowed to commit until you have updated to the most recent version.
To add a new file to the repository, run two cvs commands:
cvs add FILENAME cvs commit FILENAME
To see what has changed, do (optional filename arg says just diff that file):
cvs diff
You may wish to create a ~/.cvsrc file containing the following two lines:
diff -u update -d -PSee the manual for more information about ~/.cvsrc files.