Harmonia-Mode User's Guide Printer-Friendly Version

	Manual Contents Introduction Features Movement Search Filtered Views Reference Customization Commands Java Notes Crash Recovery and Bug Reporting

Harmonia-Mode in CS164

Cool and Java can be tricky to learn. Until recently, there have been no editing aids (e.g. an Emacs mode) to help you write your Cool programs. The editing facilities in Emacs for Java are generally limited to indentation and syntax highlighting. Using research technology from Prof. Susan L. Graham's Harmonia project, this situation has been remedied. It's an extension to XEmacs, called Harmonia-mode.

Harmonia-mode will analyze your Cool or Java programs as you're editing them and gives you syntax highlighting, proper indentation, and most importantly, will highlight syntax and semantics errors as you type:

Harmonia-mode is research technology, and may crash on you (though, it has been engineered to recover from any type of crash and preserve your work). Its use in this class is completely optional. We encourage you to try it out. If you like it (or don't) tell us in your README. Feel free to email the Harmonia group as well, at harmonia-feedback@sequoia.cs.berkeley.edu.

Setting it Up

Harmonia-mode is installed on Solaris/x86 and Solaris/SPARC instructional machines. You can run it on your own Linux computer by downloading it from here.

Then,

1. If you are using a cs164-xx account (i.e. not a named account), go to step 2.
   
   Otherwise, you must add a line to your ~/.cshrc file:
   1. If you are on a Solaris SPARC computer:
      set path = ( /home/ff/cs164/bin/arch/sun4u $path )
   2. If you are on a Solaris x86 computer:
      set path = ( /home/ff/cs164/bin/arch/i86pc $path )
   Then log out of your account, and back in. The cs164 class accounts already have this modified path.
2. Type xemacs to run our modified version of XEmacs.
   (Note that xemacs is not the same as emacs! Harmonia-mode doesn't work with regular emacs, so make sure that you run xemacs.)
3. Load a Cool file (ending in ".cl") or a Java file (ending in ".java") and start editing! You should see "Harmonia-Cool" or "Harmonia-Java" at the bottom of your window.

If you decide to stop using Harmonia-mode for Cool, you can switch to the fundamental XEmacs editing mode by typing M-x fundamental-mode. For a more permanent solution, type M-x customize-group RETURN harmonia-cool-mode RETURN, toggle the "Harmonia-Cool-Mode Enabled" option, and save your changes. To get the same effect for Java, type M-x customize-group RETURN harmonia-java-mode RETURN, toggle the "Harmonia-Java-Mode Enabled" option, and save your changes.

Additional Setup for Harmonia-mode for Java

Harmonia-mode for Java caches its semantic analysis results (name resolution and type checking) in your home directory, in a new subdirectory called ~/.harmonia_java_cache. This cache speeds analysis immensely, and only requires around 1-2 KB of data per analyzed Java class.You may override the choice of directory for this cache using the "Customize Harmonia-Java" menu item in the "Harmonia-Java" menu.

What it will do

Harmonia-mode will be continually reanalyzing your Cool and Java programs, using the same three phases of analyses that you implement in your CS164 projects. You can see the current state of Harmonia-mode's analyses on the XEmacs modeline:

Modeline Visual	Completed Analyses
	None
	Lexical
	Lexical, Syntax
	Lexical, Syntax, Semantics

Using the results of these analyses, Harmonia-mode will supply you with syntax highlighting, indentation, error-detection, and a few other features. Note that these features won't always work properly until your program is free of syntax errors! Harmonia-mode remembers the structure of your program as you edit it, but if you type a new method declaration from scratch, it won't know how to indent it properly until you type the last semicolon.

Just like a Cool or Java compiler, Harmonia-mode will not be able to run semantic analysis unless the syntax analysis ran without finding errors.

Speed Issues

1. Run Harmonia-mode on an unloaded machine with a fast CPU and at least 50 MB of free RAM.
2. Don't run Harmonia-mode on quasar.cs or pulsar.cs. These computers are using really slow 167 MHz UltraSparc I CPUs and Harmonia-mode goes too slow to be usable.

Crash Recovery and Bug Reporting

Harmonia-mode has been engineered to recover from crashes in order to preserve your work, and to help us with debugging. If it crashes, it will ask for permission to file a bug report:

Harmonia-mode will then restart itself on your buffer, and allow you to edit your program again. For more information, see the Crash Recovery and Bug Reporting page.

Please report the problems you find! Harmonia-mode is currently in active development, and we will be updating the CS164 installation as we fix bugs and add features.

Other Features?

If you'd like to browse the documentation on some of Harmonia-mode's other features, read through the rest of the sections on this web site. Note, however, that the version of Harmonia-mode installed on the instructional machines only supports the Cool and Java languages, even though the documentation may mention support for other languages (like C++).

Next Section: Structural Movement