Jacob Mini-Tutorial and FAQ
Jacob Mini-Tutorial
Just bring me to the FAQ.
The purpose of this mini-tutorial is to get new Jacob users started
and to demonstrate it's basic features.
Introduction with Example Project
After starting Jacob for the first time it opens an empty project named
'tutorial'. There are already two Java source files inside the jacob/tutorial
directory which we want to insert into our project. Both files belong to
the package 'jacob.tutorial'.
Therefore use Jacob's menu at 'Edit->Add
Package...', type in 'jacob.tutorial', and press 'OK'.
Now, this package should be listed in the top list window. Clicking
on this String should reveal the names
of two classes in the middle list window ('Main' and 'World').
If you properly set up Jacob then clicking on one of these two class
names should load the appropriate source code into Emacs. In the
bottom window you see the string "<parse>". Click on it and Jacob will
parse the current source file and display the methods of the current class.
In this case there exists only one method. Of course, now you can use this/these
method(s) for navigation too. The height of each list window can be changed.
Simply click on a bar between two lists and move it up or down. When the
project gets saved, the list window heights will be stored for each project
individually.
It's time to save your project file ('File->Save') and create a makefile
('File->Create Makefile').
Your project file is stored at .../jacob/tutorial/tutorial.proj
and the makefile is likewise stored in the same directory.
You can take a look at this makefile with 'Edit->Makefile'. Now go
back to one of the source files inside Emacs and start the compile process
with the elisp function compile, which in fact starts make.
This should compile both java source files.
BTW this is the elisp code I use to compile.
(defun my-compile ()
(interactive)
(if (string= major-mode "java-mode")
(progn
(compile "make all")
)
)
)
(global-set-key [f10] 'my-compile)
Next you want to start and test this application from inside Emacs. First
Jacob must know which of your project classes is the one with the public
static void main(String[]); routine. This can be specified at the Project
Settings Dialog ('Edit->Project Settings...'). Press Select News
and select 'Main'. Now recreate the makefile ('File->Create Makefile').
When looking again at the produced makefile, there is a new section run:.
To execute the hello world
java application you must start make with the run parameter.
To do this from inside Emacs I have the following elisp function bound
to a key:
(defun my-run ()
(interactive)
(if (string= major-mode "java-mode")
(progn
(shell-command "make run &")
)
)
)
(global-set-key [f9] 'my-run)
Now hit this key and you should see the 'hello, world' output.
Navigate to Method Callees
After you compiled your project you have another option to navigate through
your project sources. (Make also sure you parsed both example class files,
Main
and World, before proceeding.) Now select method Main.main(..)
as a starting point. A click with the right mouse button invokes a window
titled "Method Callees". It is still empty. Click on the "<parse>"-button
inside and a list with each method invoked inside Main.main(..)
will be created.

We use this window now to jump from method to method until we get out
of the project's scope. Click now on jacob.tutorial.World.World().
Emacs jumps to that method and also selects it in Jacob. Press again the
"<parse>"-button and select java.lang.Object.Object(). Oh, bad
luck, in Object.java is no constructor defined :=(. Anyway, I believe you
can surf much longer through your own source files :-).
A New Project
For example, you want to have a project named test with source files
in a package named test either.
Then, goto c:\java_apps
do
mkdir test
use Jacob "File->Open..." and goto c:\java_apps\test
and fill in the name test.proj and press ok. Now the
project test.proj is opened into Jacob. (The project file itself
will be created for the first time when you save this project once.) But
it's still empty.
So first set the project's classpath under "Edit->ProjectSettings..."
and then "change classpath". Change the classpath to c:\java_apps;c:\jdk1.1.5\lib\classes.zip,
press ok everywhere in this dialog and goto "Edit->Add Package..."
and type in simply "test" and press ok.
It says then: "warning: empty package" but that doesn't matter.
Now you need some java classes. Either copy some into the test
directory and make sure they contain the package test; statement,
create new source files from scratch yourself, or use the "Edit->New Class..."
Class Wizard to create a class template file. If you use the class wizard,
the new class is automatically included into your project. in the former
case, you must include them with "Edit->Add Classes...". Then, jacob scans
the test directory and will find every .java file and includes it into
the test.proj project. Now would be an appropriate time to save
your project data.
Ok, lets recall the steps to create a new project:
1. open a new project which then is still empty
2. set the classpath for this project all right
3. add a package to the project
4. fill the package with source files
5. save your project data ("File->Save")
---
More to come ...
Jacob FAQ
1) Installation
2) Usage
1) Installation
1.1) ...java.lang.NoClassDefFoundError: com/sun/java/swing/JList
After invoking Jacob in the command line the following error occurs:
java -classpath ..;D:\jdk1.1.3\lib\classes.zip;D:\swing-0.5.1\swing.jar
jacob.Main
...java.lang.NoClassDefFoundError: com/sun/java/swing/JList
at jacob.Controller.<init>(Controller.java:318)
at jacob.Main.main(Main.java:17)
-
Ans:
-
There is a possibility that the classpath is not set correctly, so the
swing.jar archive can't be found. But more likely it is, that during the
download the swing.jar archive got broken. This does regularly happen when
using Netscape for downloading bigger files. You can test if this happened
with an unzipper, for example 'jar tf', 'unzip -t' or 'winzip'. Just try
to list the content of the swing.jar file. If that is not possible and
results in an error message, you know it got corrupted.
1.2) All class files have lower case names on Unix and
the JVM can't handle them.
It appears that a number of Jacob classes are in .class files that do not
match the case of the classes they contain ie.
jacob.Main is in /jacob/main.class
The java VM complains that it cannot find this file. If I mv jacob/main.class
to jacob/Main.class, this class loads fine, but the VM then fails to find
additional classes. Obviously I do not want to go through all .class files
and change them.
-
Ans:
-
This is either because you use an old unzip version (your unzip version
should be something around 5.30), or in some shell configuration file (etc/profiles)
might be an alias defined for unzip like "alias unzip='unzip -L'" which
changes the normal unzip behaviour to extracts all files with lower case
letters by default. You might also try the -U option for upper case letters.
1.3) How do I report bugs or other problems?
- Ans:
-
Of course just send me a note.
Any feedback will be very much appreciated. I try my best to make Jacob
as bugfree as I can, but your help will be needed too. I know you don't
have the source code to debug Jacob yourself; but in case you get hit by
a serious bug like a crash with a runtime exception or so, you could execute
Jacob with the command line option '-debug'. That creates a lot
of additional output (don't hesitate to send it all). Maybe that will help
me to locate the bug.
If you want to get a new feature into Jacob, feel free to go into details
describing it. Otherwise I might not get the idea. :-)
1.4) I am new to Emacs. How can I configure it suitable
to Java programming?
- Ans:
- Well, if you are completely new to Emacs first go read the Info documentation
for it (Ctrl-H I). That will keep you busy for a while ;-). Then
to setup Emacs for Java I recommend checking one of the two web sites below
which solely focus on this topic.
 
-
JDE is a collection of elisp packages
for Emacs suited for Java programming. If you don't have yet configured
Emacs yourself for that purpose, you should take a look at it.
-
On Anders Lindgren's
Emacs page you can find a java-mode package
 
Just for the completeness sake and because sometimes people ask me for
my own personal .emacs file (I used it on
NTEmacs, does not work on XEmacs), here it is together with a Java font
lock elisp file (java-f-lck.el), which
is a modified version of Mitch Chapman's java-f-lck.el file. But
be warned, it's all hacked, undocumented, and sometimes preferences are
hard coded (like 3 spaces default indentation for tab stops) etc.
2) Usage
2.1) How do I create a new project?
-
Ans:
-
See mini-tutorial A New Project.
2.2) How do I add Java source files that do not belong
to a package?
-
Ans:
-
Use the virtual package '.' instead. Jacob can have one "no name" package.
When adding a Package with the name "." (just a single dot), it includes
all .java files from the first directory of the project's classpath. So,
make sure your classpath is set the way you need it. If you want to add
the file C:\java_apps\test\Test.java, make sure C:\java_apps\test
is the first element in the project's classpath, add the new package '.'
and you are done.
2.3) How can one common copy of Jacob be used by different
users, so that each user can invoke Jacob with its own personal '.ini'
file?
-
Ans:
-
By default Jacob loads the "jacob.ini" file located in jacob's "main" directory.
You can start Jacob with:
-
-inifile /absolutepath/personal.ini
-
Either use it in the batch file or in the command line.
-
You can also use one project from different machines/locations. You just
need to update the project each time you change your location and set a
different classpath once on each location. Ok, but this is another issue.
2.4) When parsing Java files for methods, Jacob seems
to show only a portion of the method signature, such as "nt,String)" instead
of "func(int,String)".
-
Ans:
-
This problem arises when your source code is located physically at a different
place than the logical structure suggests. If you have a class foo.Bar,
make sure, that:
-
-
a) your source file is located in the right directory, that is
-
.../foo/Bar.java
-
and
-
b) your source code contains the statement:
-
package foo;
-
-
The reason for this is, Jacob parses the source code, and uses also the
package/directory structure to get the method information AND to present
it (in this case package information gets cut off so only the method signature
gets presented in the the method window). If the logical and physical package
structure is not the same, the result is the observed.
-
-
As a result, always make sure your source files are in located at the place
you would expect just by just having package and class names. Yes, this
means you can't use the -d flag for javac together with Jacob.
Back to Jacob's main page
Chr.
Clemens Lahme, email to: Clemens.Lahme@gmd.de