6 Editing Daikon source code

The Daikon source code follows the Google Java Style and also Michael Ernst’s coding conventions.

6.1 Eclipse setup

6.1.1 Start up Eclipse

Just run the command eclipse at the command shell.

There is one big catch: take note of where you launch Eclipse and always launch Eclipse from the same location. For example, you might want to alias run-eclipse with cd $HOME; eclipse. For convenience, this is already done for you if you source the daikon-dev.bashrc startup script. There are ways around the launch location inconvenience, such as the -data switch, but the alias trick should be the simplest and least confusing workaround.

It is strongly recommended that you make the following customizations to Eclipse:

Window >> Preferences >> Workbench >> Refresh Workspace on Startup
Window >> Preferences >> Java >> Compiler >> Problems >> Unused imports >> Ignore
Window >> Preferences >> Java >> Compiler >> Style >> Non-static access >> >> Ignore

6.1.2 Work on existing coding projects

6.1.2.1 Import an existing project

Second, import Daikon into Eclipse. To import: start Eclipse, then choose menu item ‘File->Import->ExistingProjectIntoWorkspace’, then enter (the full name of) directory $DAIKONDIR/java for Project Contents.

Those two steps are all there is to it!

(This simple procedure works because there are already .project and .classpath files in $DAIKONDIR/java. To import a project that doesn’t have these files, you would need to create them (for instance, copy them from Daikon’s), or else follow a different procedure to work on your project in Eclipse.)

6.1.2.2 Importing a different existing project

Before working on code in Eclipse, you must import the code into the Eclipse workspace. You also need to set up various compilation settings and specify jars and classes that should be in the compilation classpath. (By default, Eclipse does not use your CLASSPATH environment variable.)

1. Change to the Java perspective by selecting "Java Perspective" in the perspective menu on the far-left tool panel. You should see some of the windows move around to a structure similar to the screenshot below.
2. Select the menu item File->New->Project
3. On the popup window, select Java Project and click Next
4. Call the project ‘Daikon’ or some other appropriate name and click Next.
5. On the next window, create a new folder in the project called src, and answer Yes to the next dialog box asking you to confirm a change in the build directory. Select ‘Ok’ and you should see the new Project as a small folder icon in the package explorer.
6. Select the menu item File->Import
7. On the next popup window, select ‘File System’ and click Next. Browse to the folder containing your source code. Using the standard ‘PAG’ setup, the folder should be $DAIKONDIR/java. The import destination should be Daikon/src. Check the boxes for including Daikon, ‘jtb’, and plume.
8. Finally, add the required jars for Daikon by right-clicking on the project and selecting the Properties menu. Select "Java Build Path", then "Libraries", then "Add External Jars" and add tools.jar and all .jar files in daikon/java/lib/.

Note that if you follow these directions, then the compiled classes do not appear in the directory from which you imported in the previous step. Instead, the compiled classes appear in the Eclipse workspace directory. If you followed the setup instructions above, then the compiled code will be in "$HOME/.eclipse/Daikon/bin", which you should add to your classpath in order to use the updates you make from Eclipse.

6.1.3 Interaction with external tools

Eclipse compiles your project whenever you save. However, it parses frequently during editing and issues most or all of the errors and warnings that the compiler would have. In order to clear a warning/error (in the Task List), you must save the file, however.

If you change files outside Eclipse, you should refresh Eclipse, via right-clicking on the project or via menu item File >> Refresh.

6.1.4 Using the Eclipse debugger

To begin debugging, you can click on the bug icon in the toolbar or select Run->Debug from the menu. You will see the same window as if you selected Run->Run, but when the Java application launches, Eclipse will switch to the Debugging Perspective, which reveals many windows such as the stack trace window, the variable values window, and the step control panel.

Debugging features (window locations given for default setup):

• Breakpoints: You can add breakpoints during editing by double-clicking on the left margin area of the source code. When debugging, the program halts when it reaches a breakpoint.
• Stack Trace: Once the program halts at a breakpoint, the window in the upper-left corner window show the stack trace.
• Step Controls: Once the program halts at a breakpoint, the panels just below the stack trace allow you to step through the code one line at a time (step over), resume execution as normal (resume), step down into a method call (step into), or execute until leaving the current method (Step return).
• Variables: On the top right window, there is a tab pane that displays the values of objects and fields during a breakpoint halt. You can also type in any legal Java expression that could appear at the breakpoint, and the window will display the value of the expression (don’t forget to put a semi-colon at the end of your expression!).

6.1.5 Using Git with Eclipse

This section has yet to be written, although you can just do all the editing, compiling, and running from the Eclipse IDE while doing version control commands from the shell or whatever current system you use.

6.2 Editing daikon.texinfo

The Daikon manual appears in doc/daikon.texinfo. The manual is written using the Texinfo formatting system, which makes it easy to produce HTML, info, or printed (PDF) output.

You can edit the manual using an ordinary text editor. Emacs has a useful Texinfo mode. You can mimic the formatting commands that already appear in the manual, but it’s also a good idea to read the Texinfo documentation.

If you wish to create a new section of the manual, insert two lines like the following:

@node    @Short title
@chapter @Long title

where you select the short and the long titles (which may be the same), and you may replace @chapter by @section, @subsection, or @subsubsection.

Follow the Texinfo conventions for marking up text. In particular:

• Don’t use regular double quotes (") in running text. Instead, use two single back quotes and two regular quotes, “like this”. Emacs will do this substitution for you if you are using its Texinfo mode.
• Often, some other kind of markup is better than quotes:
  • @code is for names of classes, functions, variables, keywords, and other fragments of source code.
  • @var is for meta-syntactic variables, not for referring to variables that appear literally in the source code.
  • @file is for the names of files.
  • @option is for command-line options.
  • @samp is for sample input or output. (Alternatively, you can use @example to set off longer input/output strings.)
  • @command is for command lines.
• Examples shouldn’t include extra spaces on the left for indentation since Texinfo already adds some indentation. Remember that in code examples you need to replace all curly braces with { and } to quote them for Texinfo.
• Don’t mix @example and @smallexample in the same section since it looks funny to have examples in two different sized fonts. If your example is too wide to fit on the page with @example, it’s better to insert some line breaks to make it more readable than to shrink the font.

Once you have edited the manual, run make twice (yes, you must run it twice) in order to generate formatted versions of the manual (daikon.{html,pdf}).