Saving and Restoring Project Settings
Welcome to the JDE User's Guide. This guide explains how to use the JDE to develop Java applications and applets. The guide assumes that you are familiar with Emacs and JavaSoft's Java development tools.
The Java Development Environment (JDE) is an Emacs Lisp package that interfaces Emacs to third-party Java application development tools, such as those provided by JavaSoft's Java Development Kit (JDK). The result is an integrated development environment (IDE) comparable in power to many commercial Java IDEs. Features include:
The JDE requires:
The JDE distribution includes the following files:
See the Emacs JDE Home Page for instructions on downloading and installing the most recent version of the JDE>
Please send bug reports and enhancement suggestions to Paul Kinnucan at paulk@mathworks.com.
To edit a Java source file, load it into an Emacs buffer. Loading a Java source file into a buffer causes the buffer to enter into java-mode, a variant of the standard Emacs cc-mode for editing source files written in C and related languages. Java mode offers all the specialized source file editing commands of cc-mode plus functions for compiling, running, and debugging Java source files. You can invoke the commands by selecting them from the JDE menu that java-mode displays on the Emacs menu bar or by typing the commands in the Emacs minibuffer (see the figure below).
The jde-compile command (JDE->Compile, C-c C-v C-c) compiles the Java source file in the current buffer, using javac, the Java compiler provided by the JDK, or another compiler that you specify (see Specifying a Compiler). The compile command displays the output of the compiler in a separate compilation buffer. If a compilation buffer does not exist, the compile command creates the buffer; otherwise, it reuses the existing compile output buffer. The compilation buffer operates in compilation-mode, a standard Emacs buffer mode. This mode greatly simplify locating compilation errors in the Java source code. For example, to find the line that cause a compilation error, simply click the error message in the compilation buffer.
The JDE allows you to set javac compile options, such as, -depend or -verbose. To set compilation options, type M-x jde-set-compile-options or select JDE->Compile Options from the Emacs menubar. The JDE displays a prompt in the minibuffer. Enter the desired compile options as you would on the command line. For example,
-depend -debug
The JDE uses the specified command options whenever you compile a Java source file. To clear the current options, press return at the prompt.
Note. You can use jde-set-compile-options (JDE->Compile Options) to set the javac -classpath option. However, any path that you set in this way applies only to compilations. If you want the class path to apply to invocations of the java interpreter and debugger as well, use the jde-set-classpath command (see Setting the Classpath).
The JDE lets you set the -classpath options of the Java compiler, interpreter, and debugger to a common path. To set the -classpath option for all three tools, enter
M-x jde-set-classpath
at the command line. The JDE displays a prompt in the minibuffer. Enter the class path, using the appropriate separator character (colon for Unix platforms, semicolon for Windows). For example,
.;d:jdk1.1.3/lib/classes.zip
Note. Enclose the class path in quotation marks if you are using a Unix shell on a Windows platform to prevent the shell from interpreting the semicolons as statement separators.
The JDE uses javac, the compiler provided with the JDK, by default to compile the current buffer. You can specify another compiler, using the jde-set-compiler command. The compiler that you specify applies only to the current buffer.
The JDE allows you to run a Java application as an Emacs subprocess. You can run multiple applications concurrently, but only one instance of each application at a time. The JDE displays each application's standard and error output in an Emacs common interface (comint) buffer. You can interact with applications that accept command line input via the comint buffer. When interacting with an application, you can use any of comint-mode's extensive set of command-line history commands to speed interaction. To run an application, enter
M-x jde-run
or select Java->Run App on the Emacs menubar or type C-c C-v C-r.
The JDE uses the virtual machine specified by the variable jde-run-java-vm to run Java applications on Unix platforms. The default value of this variable is java, the name of the virtual machine provided by JavaSoft's JDK. On Windows platforms, the JDE uses the virtual machine specified by the variable jde-run-java-vm-w. The default value of this variable is javaw, a version of java that hides the DOS window associated with a Java process on Windows hosts. You can specify another Java virtual machine by setting the value of jde-run-java-vm (jde-run-java-vm-w on Windows platforms) appropriately.
The JDE determines the class to be run first by checking the value of the Lisp variable jde-run-application-class. If that variable is non-nil, the JDE runs the class specified by the variable. If the variable is nil, the JDE runs the class corresponding to the Java source file in the current buffer. If the source file specifies a package name, the JDE prepends the package name to the class name.
The command jde-run-set-app sets jde-run-application-class. Use it to specify your application's main class (the class with a public static main(String[] args) method). Don't forget to qualify the class name if the main class is a member of a package.
By default, the JDE uses the JavaSoft JDK interpreter (java for Unix platforms, javaw for Windows platforms) to run applications. You can specify another interpreter by entering
M-x jde-run-set-vm
for Unix plattforms or
M-x jde-run-set-vm-w
for Windows platforms.
To specify run options supported by the Java interpreter, enter
M-x jde-run-set-args
and enter the options as you would on the command line, e.g.,
-verbose -mx24m
Note: Do not enter a -classpath option if you specified the classpath via the jdesetclasspath command. The jdesetclasspath command sets the -classpath option for both compiling and running applications.
Use the jde-run-set-app-args command to specify command-line arguments to pass to the application.
The JDE lets you run an applet as a subprocess of the current Emacs session. To run an applet, enter
M-x jde-run-applet
or select Java->Run Applet from the Emacs menu bar or type C-c C-v C-a. If you type the command jde-run-applet, the JDE prompts you to enter the name of the document that contains the applet. It opens the specified document in appletviewer, the applet viewer suppled with the JDK. You can specify another viewer via the jde-run-set-applet-viewer command. If you select Java->Run Applet, the JDE assumes by default that you want to view a document called index.html and that that document is located in the current directory. You can specify another document via the jde-run-set-applet-doc command. The JDE opens the specified document in the current viewer.
To debug an application:
By default the JDE uses jdb, the debugger supplied with the JDK, to run applications in debug mode. You can specify another debugger, using the jde-db-debugger command. You can specify either an executable debugger or a debugger class. If you specify a debugger class, the JDE runs the debugger as a Java application.
Use the commands jde-db-set-args and jde-db-set-app-args to specify arguments to pass to the debugger and the application being debugged, respectively. The arguments that you specify apply only to the current Java buffer.
The jde-db command (JDE->Debug, C-c C-v C-d) starts the debugger and opens a debugger interaction window.
First set a breakpoint at the line where you want to begin stepping through your program (see Setting Breakpoints). You can set other breakpoints at this point as well. Then, at the debugger prompt (>), type the run command. The debugger runs your program, stopping at the initial breakpoint. The JDE splits the Emacs window into two frames. One shows the debugger interaction buffer. The other frame displays the source file containing the line at which your program has stopped. An arrow (=>) points to the current line. The menu bar of the source buffer displays a menu (Jdb) of debug commands.
At this point, you can step through your code by entering commands in either the Java source buffer or the jdb interaction buffer.
The debugger executes the current line and stops at the next line. If the next line is in another source file, the debugger opens the source file in the source buffer (replacing the existing file) and positions the display at the new stopping point. At this point, you can enter a debugger command to display the value of a variable, set or clear a breakpoint, or perform some other operation.
Note. A blank source buffer indicates that the debugger cannot find the source file into which you have stepped. You should check your source path setting (see Specifying Source Code Paths) to ensure that it includes all source files in the execution path of your program.
You can set breakpoints in your program from either of two places: the debugger interaction buffer or the source buffer created by the debugger. When setting breakpoints from the source code buffer, you can set breakpoints only in classes whose source is displayed in the buffer. If you want to set breakpoints at other points in your program, you must set them from the debugger interaction buffer.
Since the debugger does not create a source code buffer until it has reached the first breakpoint, you must set the first breakpoint from the debugger buffer. Thereafter, you can use the source buffer to set breakpoints whose source is displayed in the buffer.
The stop in command sets a breakpoint in a specified function. For example,
> stop in myapp.Main.main
sets a breakpoint in the main method of myapp.Main class. The stop at command sets a breakpoint at a particular line. For example,
> stop at myapp.Main:20
sets a breakpoint at line 20 of myapp.Main class. Use the clear command to clear a breakpoint from a specified line. For example,
> clear myapp.Main:20
clears the breakpoint set at line 20 of myapp.Main.
To set a breakpoint on any executable line in the source file buffer, click on the line and select Jdb->Set Breakpoint (C-x SPC). To clear a breakpoint from a line in the current buffer, click on the line and select Jdb->Remove Breakpoint (C-x C-a C-d).
Type M-x jde-db-set-source-paths to specify the source paths of files you might visit while debugging your app. The JDE displays a prompt in the minibuffer. Enter the source paths separated by colons (on Unix systems) or semicolons (on Win32 systems) and press enter.
You must specify the paths of the top-level directories of any source code that you might visit while debugging your application. The source code directory structure must mirror your app's package structure. For example, suppose that your application includes a set of classes packaged in the myapp directory. Then, the source for those classes must be reside in a directory named myapp and you must specify the path of myapp's parent directory.
Tip: If you want to step through the JDK source code, select the source code install option when you install the JDK and the use jde-db-set-source-paths to specify the directory containing the source code. You need specify only the path of the top-level directory. The JDE will use the JDK's package structure to find the source code in the subdirectories.
Tip: Specify source paths in your prj.el file (see Saving Project Settings) to avoid having to set them every time you start a session. For example, entering
(jde-db-set-source-paths "c:/jdk/src/;c:/java_projects/")
in your prj.el file tells the JDE to look for source files in the specified directories when stepping through your applications.
The debugger lets you display the value of any local variable currently in scope. To display a variable from the debugger buffer, enter print x at the debugger prompt where x is the name of the variable whose value you want to display. The debugger displays the value of the variable in the debugger buffer. To display a local, in-scope variable whose source is displayed in the debugger source buffer, put the point on the variable and select Jdb->Print Expression or type C-x C-a C-p. To display all variables in scope, enter locals at the debugger command prompt in the debugger buffer.
When the debugger displays a user-defined object, it prints the value returned by the object's toString() method. By default, the toString() method returns the object's id. You can override the toString() method to return a more informative result, such as the values of the object's fields.
You can store the settings for a project in an Emacs Lisp source file named prj.el located in the directory hierarchy that contains the file. When you open a Java source file, the JDE searches for a project file, starting in the current directory and working upwards. The JDE loads the first project file that it finds.
For example, here is a typical project file:
;; prj.el ;; Class path setting (setenv "CLASSPATH" ".;c:/prj1/src;c:/prj1/classes;c:/jdk/lib/classes.zip") ;; Compile options (jde-set-compile-options "-d \"c:/prj1/classes\" -debug") ;; Application's main class (jde-run-set-app "foo.main") ;; Source paths (jde-db-set-source-paths "c:/prj1/src;c:/jdk/src")
The jde-browse-jdk-doc command (JDE->Browse JDK Doc, C-c C-v C-n) opens the JDK documentation in a browser. By default, this command displays the JDK documentation page at JavaSoft's web site. To display a different copy, set the variable jde-jdk-doc-url to the url of the index page of the copy you want to be displayed.
You can use Emacs' etags facility or the speedbar to browse your Java source code.
To use the speedbar, select Speedbar from the JDE menu. The speedbar opens in a separate window, showing a tree-structure list of the Java source files in the current directory.
Click on the + button in front of any file. The node for the file expands, showing the methods, class and instance variables, and classes defined in that file as children of the file node.
Click on any method, variable, or class name to see its definition.
To use the etags facility, you must first construct a TAGS file that indexes every symbol in your source code. The JDE package contains two shell scripts that you can use to tag your source code, one for csh shells and the other for bash. The bash version is called jtags; the csh version, jtags.csh.
To tag your source code, first copy the appropriate shell script to a directory in your Emacs path. Then start a shell (M-x shell). Change to the top-level directory containing your source code and then enter jtags. The jtags script tags every .java file in the current directory and in all descendants of the current directory, storing the result in a file called TAGS in the top-level directory.
To find the definition of a symbol, put your cursor anywhere in the symbol and enter M-x .. Emacs responds by locating and opening (if necessary) the file containing the definition and positioning the point at the definition. (The first time you type M-x ., Emacs prompts you to load the TAGS file.)
The JDE defines a major mode, named jde-mode, for editing Java source files. This mode derives from the standard Emacs Java source editing mode java-mode. In particular, it inherits all the functions and customization variables defined by java-mode and adds its own customization variables. When you load a Java source file, Emacs runs a JDE mode initialization function called jde-mode. The jde-mode function in turn calls the Java mode intialization function, java-mode. The last thing that jde-mode does before returning is to call a JDE mode function, if it exists.. You can customize the JDE by defining a JDE mode hook function in your .emacs file. The following is an example of how to do this:
(defun my-jde-mode-hook ()
(message "my-jde-mode-hook function executed"))
(add-hook 'jde-mode-hooks 'my-jde-mode-hook)
The preceding example defines a JDE mode hook function named my-jde-mode-hook and adds it to the list of JDE mode hook functions, using the Emacs Lisp function add-hook. Now, whenever you open a Java source file, jde-mode invokes the function my-jde-mode-hook. Of course, the hook function defined in this example is trivial. A real-world example might do something more useful, such as setting a custom indentation style.