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 ()
       (if (string= major-mode "java-mode")
                  (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 ()
       (if (string= major-mode "java-mode")
                  (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.

Then, goto c:\java_apps, do mkdir test, use Jacob "File->Open...", goto c:\java_apps\test, 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.) This creates an empty project.

The project name may be arbitrarily chosen; it does not have to be the same as the directory name within which it is created or the package name. However, it must end with the .proj extension.

Next, set the project's classpath under "Edit->ProjectSettings..." and then select "change classpath". Change the classpath to c:\java_apps;c:\jdk1.1.5\lib\classes.zip, press ok everywhere in this dialog, goto "Edit->Add Package...", type in simply "test" and press ok. It then says "warning: empty package". This is OK.

Note that the classpath should point to the directory containing the package directory tree, i.e. if the package name you choose is myprog.bells.whistle the  source files for the package must be created in or copied to the directory myprog\bells\whistle . The classpath should be set to the directory that contains the myprog subdirectory, i.e. if the myprog directory is in c:\java_apps the classpath should be set to c:\java_apps .

 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, empty project in the directory which will contain your source files.
2. set the classpath for this project
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)

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.

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?

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?

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.
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.

1.5) How can I use Gnu Emacs instead of XEmacs on Unix?

First make sure gnuserv is installed and working together with Gnu Emacs. Then either just make sure Gnu Emacs is up and running together with the gnuserv server before you start Jacob and everything should be fine.

You can also add 'Editor=emacs' in the [Init] section in your initialization file. Then Gnu Emacs starts together with Jacob if Emacs isn't running yet.

You might also think about specifying the 'GnuclientPath' entry in the initialization file in case you have also installed XEmacs with its own gnuserv package on your system.

1.6) Gnu Emacs does not come with gnuserv by default. Any help?

I had big problems getting gnuserv to work for Gnu Emacs. With the help of Max Renkin I finally managed to get it going.

Go download it from: ftp://ftp.wellfleet.com/netman/psmith/emacs/gnuserv-2.1alpha.tar.gz

Then I downloaded and compiled the newest Emacs source files from http://www.emacs.org/. Unfortunately it's a 14 mb pig.

Now goto the gnuserv source directory and edit the Makefile entry 'Includes' to let it point to the Emacs source directory. Afterwards edit gnuserv.h and make sure


is set and not


Now you are ready to compile the gnuserv package. In case you also have XEmacs installed on your system, make sure the gnuserv package from XEmacs is not in your PATH or set the 'GnuclientPath' entry in your Jacob initialization file so Jacob uses the right gnudoit/gnuclient binary.

Just as with XEmacs, you need to insert into your .emacs file the following elisp code:

(require 'gnuserv)
;; If you want you can specify the gnuserv binary so you
;; don't use the XEmacs gnuserv binary by accident.
;; (setq server-program "/usr/local/gnuserv-2.1alpha/gnuserv")
(setq gnuserv-frame (selected-frame))

Before proceeding with Jacob, you might want to first test manually if gnuclient is working (like with: 'gnuclient ~/.emacs').

Thanks also to Jochen Bedersdorfer who provided me with feedback and was able to get gnuserv working through recompiling gnuserv.el from the XEmacs sources and also using gnuserv from XEmacs. Thought it didn't work out for me this way.

1.7) How can I use jEdit for editing?

If you haven't done so already go download jEdit from:


In your Jacob startup script make sure the jedit.jar file is part of its CLASSPATH. Then start Jacob with option '-jedit' and jEdit will be started before Jacob gets started itself.

Only file loading and method jumping is supported right now. Other Jacob features like 'Edit->Add Import Statemen...' aren't yet supported together with jEdit.

1.8) How can I use environment variables in my project settings?

You can specify a property file that contains key value pairs of environment variables and their values. Jacob reads this file and you can use all the variables that are specified in this file in the Properties Settings dialog.

Thanks to Paddy Ramanathan for providing the base class for this feature.

For example, on Unix you can easily create a file with all your environment variables and values like this without specifying anything by hand:

set > /some_path/environment.properties

Now edit your batch file or shell script which you use to start Jacob and add the option


to the java command. This is what I have in my shell script:

set > $HOME/src/java/jacob/env.properties
$JAVA_HOME/bin/java  -DSYS_ENV=$HOME/src/java/jacob/env.properties  -classpath $CLASSPATH jacob.Main -inifile $HOME/src/java/jacob/jacob$HOSTNAME.ini $*

Now in the Project Settings dialog you can use environment variables for example to specify your project classpath. The format is the Makefile format for environment variables with a dollar sign and brackets around the variable name like:


1.9) Jacob starts with a dialog indicating that gnudoit does not work. What went wrong?

1) Did you start XEmacs (or GNU/NT Emacs) together with gnuserv? For this you must add

   (require 'gnuserv)
   (setq gnuserv-frame (selected-frame))

to your .emacs (_emacs) file so that the gnuserv process is running together with Emacs. Only then can gnudoit or gnuclient load files into Emacs from an external process. Best to manually test with gnuclient testfile.txt from the command line if gnuclient works before going forward to use it from Jacob.
2) Of course the gnuserv package has to be installed together with Emacs. XEmacs normally comes bundled with gnuserv, but other Emacs implementations need a separate download and installation.

3) If this is the case and Jacob has still problems invoking gnudoit successfully then Jacob just can't locate the gnudoit executable. Make sure the directory where gnudoit (and gnuclient) is located in is added to your PATH environment.
4) Alternatively you can set this in Jacob under 'File->Preferences...' after Jacob has started up. Maybe you will have to restart Jacob afterwards.

1.10) An AccessControlException appears on the command console with the message to relax the security policy. What does this mean?

If you see the following message:
AccessControlException: please relax your security policy for your jdk
in order to let the application run with its full functionality.
You should grand more permissions in file $JAVA_HOME/jre/lib/security/java.policy.
E.g. put
'grant {
    permission java.security.AllPermission;
in that file (backup the original content).
If you don't want to do anything like this the application should still
work with most of its functionality.
Then you probably are using e.g. jdk 1.3 with the default security settings which are pretty strict. Jacob on the other hand plays around with standard output and error streams which Java does not allow by default. If you apply the changes mentioned above then Java will not complain any more. But if Jacob can not change standard output it effects only the Java console feature, so the user should not worry to much about the whole warning.

Jdk 1.1 is not effected at all by this security issue.

2) Usage

2.1) How do I create a new project?

See mini-tutorial A New Project.

2.2) How do I add Java source files that do not belong to a package?

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?

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)".

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
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 Lee, email to: clemens@kclee.com