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 IDE is an integrated Java application development environment based on Emacs and JavaSoft's Java Development Kit (JDK). The JDE integrates the Java-specific software development tools provided by the JDK into Emacs' powerful general-purpose software development environment to create a development environment comparable in power to many commercial Java IDEs. Features include:
The IDE integrates several Emacs program development packages
(cc-mode, gud, and compile)
with JavaSoft's JDK.
This package includes the following files:
jde.el, defines a Java major mode
jde-run.el, runs Java applications and applets
jde-db.el, jdb debugger interface
speedbar.el, tree-structured source code browser
jtags, a bash shell script that tags Java source
hierarchies
jtags.csh, a c shell script that tags Java source
heierarchies
The JDE requires:
cc-mode.el (download).
andersl-java-font-lock.el (available from http:\\www.csd.uu.se\~andersl\emacs.shtml
or ftp://ftp.csd.uu.se/pub/users/andersl/emacs\).This
is required for syntax highlighting.
Please send bug reports and enhancement suggestions to Paul Kinnucan at paulk@mathworks.com.
To install this package:
jde.el, jde-db.el, jde-run.el,
and speedbar.el files to a directory in your Emacs
Lisp file load path.
.emacs file:
(load "jde")
(setq jde-web-browser "BROWSER")
(setq jde-doc-dir "JDK DIRECTORY")
(jde-db-set-source-paths "SRCPTH1;SRCPTH2;...)
For example, suppose that Netscape is your browser and is in your shell command path and you have installed the JDK API doc at c:/JDK1.1/docs. Then, you would add
(load "jde")
(setq jde-web-browser "netscape")
(setq jde-doc-dir "c:/jdk1.1/docs/")
(jde-db-set-source-paths "c:/jdk1.1/src/;c:/myjava/src/")
to your .emacs file.
If you are using the bash shell, you should specify this either
by setting the SHELL environment variable or the
elisp variable shell-file-name to bash. For example,
for Win95, enter
set shell=bash
in your autoexec.bat file or
(setq shell-file-name "bash")
in your .emacs file.
If you are using bash on Windows 95 or Windows/NT, you should
also put
(setq shell-command-switch "-c")
in your .emacs file.
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-x 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-x 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-x 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:
jde-db-set-source-paths to specify the paths
of any source code that you expect to visit while debugging your
application (see Specifying Source Code Paths).
If you suspect that a problem is occurring in the Java API, you
should include the API source files in your source path.
-g option
(see Compiling Java Programs).
This causes the compiler to insert information needed by the debugger
into your application's class files.
jde-run-set-app
command (you need only do this once) or by starting the debugger
from the buffer that contains the source file for the main class.
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-x
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.
C-x C-a C-s) or Jdb->Next (C-x
C-a C-n) to step into or step over the current line, respectively.
Select Jdb->Continue (C-x C-a C-r) to continue to the next
breakpoint or to the end of your program, whichever comes first.
step, next,
or cont at the jdb command prompt.
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-x n) opens the JDK documentation
in a browser. To view the JDK doc, choose from the Java menu.
The variable jde-doc-dir specifies the path of the
JDK documentation. The default value of this variable is d:\jdk1.1\docs\.
The variable jde-web-browser specifies the documentation
browser. Its default value is netscape. If necessary,
you should set these variables to the actual path of the JDK documentation
on your system and the browser that you want to use to view the
documentation.
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.)