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

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)

(defun my-run ()
       (interactive)
       (if (string= major-mode "java-mode")
           (progn
                  (shell-command "make run &")
            )
        )

 )
(global-set-key [f9] 'my-run)

Navigate to Method Callees

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

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

Jacob FAQ

1.1) ...java.lang.NoClassDefFoundError: com/sun/java/swing/JList
1.2) All class files have lower case names on Unix and the JVM can't handle them.
1.3) How to I report bugs or other problems?
1.4) I am new to Emacs. How can I configure it suitable to Java programming?
1.5) How can I use Gnu Emacs instead of XEmacs on Unix?
1.6) Gnu Emacs does not come with gnuserv by default. Any help?
1.7) How can I use jEdit for editing?
1.8) How can I use environment variables in my project settings?
1.9) Jacob starts with a dialog indicating that gnudoit does not work. What went wrong?
1.10) An AccessControlException appears on the command console with the message to relax the security policy. What does this mean?

2.1) How do I create a new project?
2.2) How do I add Java source files that do not belong to a package?
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?
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)".

1) Installation

1.1) ...java.lang.NoClassDefFoundError: com/sun/java/swing/JList

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

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.

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

Ans:

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?

Ans:

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

#define UNIX_DOMAIN_SOCKETS

is set and not

#define INTERNET_DOMAIN_SOCKETS.

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)
(gnuserv-start)
;; 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?

Ans:

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

http://www.gjt.org/~sp/jedit.html

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?

Ans:

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

-DSYS_ENV=/some_path/environment.properties

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:

$(ENVIRONMENT_VARIABLE)