Jacob Help

 

The documentation about specific features is very rudimentary. If you have any questions, feel free to send me a message and I will take that as an occasion to fill some gaps here. For an educational introduction please see the tutorial (not existent yet). This help is meant as a reference. It describes the Jacob functionality from a menu and dialog point of view.

Table of Contents

Synopsis

Usage: JACOB [-version] [-help] [-noemacs] [-jedit] [-inifile foo.ini] [your_project.proj]
      version:   Prints the version number of the program.
      help:      Prints this help message.
      noemacs:   Use Jacob without Emacs.
      jedit:     Use jEdit editor instead of Emacs.
      inifile:   Starts this application with another ini file than
                 the default one.

File Menu

Create Makefile

This creates a makefile for your project. The new makefile is placed in the same directory as the project file (*.proj). You can take a look at the makefile with 'Edit->Makefile' which loads it into Emacs. There are 4 to 5 sections: all, (run), clean, zip, and cm.

Sometimes to compile a hole project there are some extra things to do except compiling the java classes. For example executing a precompiler or a YACC like parser. Therefore you have the possibility to have your own handwritten makefile that gets executed before Jacob's generated makefile. If there exists a file make_all_first in the same directory then this file will be included at the beginning of the main makefile. Then this file must contain the rule "all_first :".

There are two more special files which are treated similar: make_cm_last and make_zip_last. If used, they must contain the rules "cm_last :" and "zip_last". They are invoked through the command make cm and make zip and executed after the auto-generated "cm :" and "zip :" rules of the standard makefile. If you need different rules for different operating systems, use the "OS" variable which has an appropriate values like "Windows_95" or "Solaris".
 

Update Project...

You can move a project file to another destination and than update the internal path for each package and class automatically. This means also, you can code on one machine, move the code over to a different operating system, change the classpath to the new environment, and adjust the packages and classes automatically to the new settings. But you still have to change the classpath each time manually.

Preferences...

 

Jacob Frame Width:

Specifies the width of the Jacob frame. There is also an undocumented option to set the application frame height to a constant value instead of using the full screen height. Set the field "FrameHeight" by hand in the '.../jacob/jacob.ini' file in the '[Init]' section. If the "FrameHeight" field is empty, the full screen size is used.

View Methods Sorted:

If this option is not set, methods in the method list window are ordered as written in the original source file.

Javadoc @author:

This string is inserted after the @author tag in the documentation header of a new created class/interface using the Class Wizard.

Extra Directories:

This field contains additionally sub directories separated by a ';', that will be created for each new project in the respective project directory. Leave this field blank if you don't want this functionality. The project directory is the directory where the '.proj' file resides.

Edit Menu

Add Package...

Normally this is the way to insert new source code to your project. Specify a package name and Jacob will use the classpath to locate this package and every Java source file which belongs to this directory or its subdirectories.

If a package can't be found you may change the classpath for your project. To do that go to 'Edit->Project Settings...'. Then Jacob should be able to find the desired package.

A project must have at least one package. If you simply want to have classes which don't belong to any package (very common for example for applets) then make clear the first element of the project's classpath points directly to the same directory where the project (*.proj) file is in. Now insert the package named '.' (it consists simply of a dot). This will insert every Java source file in that directory.

New Class...

The class wizard creates the initial source file for a new class/interface and inserts it into the actual project. Entries are separated in the 'import', 'extends', and 'implements' fields with commas. To select more than one item in the tree, use the mouse together with the control key. Then press the update button to move the selections into the choosen field. To make the comma separated
entries in the fields selected in the class tree, just press the appropriate value in the select box again.
 

 
After pressing 'OK' in the former Class dialog, if you extended a class from another, here is the opportunity to select some methods to overwrite and to create some empty method bodies. Note, the methods of implemented interfaces will be created anyway, as well as the constructors of the superclass. Example output can be seen here.

Method Callees

 
Very fast way to trace through your whole project's source code and to follow the program's control flow. Start at the main routine and jump from method invocation to method invocation.

Usage: select a method in the methods window (in this example it was 'jacob.Controller.Controller(String[],String)', then invoke this frame via menu or better with right mouse button. Hit the '<parse>' button and each method that is used inside the selected method gets shown. Now select the one for which you want to see the source code definition. The editor will show the definition of that method. Additionally this method gets selected in the browser, so you can again hit the '<parse>' button to jump iteratively from method to method.

Project Settings...

See also 'How can I use environment variables in my project settings?' in the Jacob FAQ.

Classpath:

The default classpath is the classpath Jacob was started with. To allow Jacob to find new packages and class source files to be included into a project, for each project a separate classpath can be specified.
Jacob stores for each project different classpaths dependent on the system architecture hardware, OS, and user home directory. After moving a project onto a new system the classpath must be once more set. Then Jacob stores for each environment and project separate paths and chooses the appropriate the next time.

Start Parameter:

This value is used for the Makefile in the 'run:' section as a parameter for the application. For example:

...
run : all
        $(JAVA) -classpath $(CLASSPATH) jacob.Main jacob.proj
...

Project Tag:

This string together with the current release number is used as a tag for the configuration management tool RCS. You must also select a Main Class. In the source of this class the RCS keyword 'Header' must occur. For each source file an entry like the following is then created in the 'cm:' section of the Makefile:

   ci -l -nJE43 h:\eigen\src\java\jacob\Main.java

Tools Menu

 
The 'Tools' menu's purpose is to offer a way to invoke other Java applications out of Jacob. As an example and in the hope someone will find it useful (and because most of its code is used by Jacob anyway) I included a Lines of Code counter for Java source code named JavaNCSS. You can take a look what JavaNCSS (local) has to offer at its own dedicated page.

If you want to invoke your own or your favorite application out of Jacob, take a look at the source files in the jacob/tool directory and use them as examples (or nag me and I will write more documentation or give you personal assistance [or i will even write it for you/us]). Also look in the jacob/jacob.ini at the 'Tools' section to get an idea how to put a new entry in the Tools menu and how to specify which class will be invoked. Don't forget to start Jacob with an extended classpath if necessary.

Javancss All...

Javancss Selected...

The difference to 'Javancss All...' is just that the user can count only part of a project, for example all code of one package or one class. Sometimes counting a big project can take some time. If a class is selected in the class window, JavaNCSS counts only the class, if no class but a package is selected, the whole package gets counted. If you are interested only in some data of a single method, count the whole class.

Timelog...

 
Timelog is a separate program i wrote. As you can see its purpose is to record your personal development time (or for whatever you spend your time on which you want to track). You can get additional information about it on its own web page. The advantage of starting Timelog out of Jacob is that Timelog does immediately load the time data for the current project. Timelog looks in the subdirectory 'psp' for the project's time data. This directory must exist, otherwise Timelog can't create a new log file.

To install Timelog for use out of Jacob, download it and make sure its in Jacob's classpath. Then edit your initialization file (normally jacob/jacob.ini) and remove the semicolon from the line ";Timelog...=jacob.tool.TimelogWrapper" in the Tools section. Also add or insert "|Timelog..." in the line where all tools are listed.

JavaDump

JavaDump is the work of Matt T. Yourst. Thankfully he released it with a very liberal copyright so it can be distributed together with Jacob. Because Jacob will rely in future versions on JavaDump's JCF class library for new functionality, JavaDump is also included in Jacob and you don't need to download and install it separately.

"The JavaDump utility, built with the JCF class file manipulation package, produces an HTML report from the structures in a class file".

The only thing I changed about JavaDump is, while originally its output was in HTML format, for Jacob it is in ASCII. That way, the output can be viewed in Emacs. Loading the output into HtmlViewer would have been too slow.

JavaP

Since JavaP is part of Sun's JDK you don't need to do anything to get or install this tool (if you don't use Sun's JDK this might be another case). Invoking JavaP out of Jacob disassembles the currently selected class, writes its output in the class name with suffix ".javap" and loads this file into Emacs. This together with JavaDump is kewl for learning Java byte code stuff. I am sure somewhere out there exists a disassembler with output in Jasmin syntax. That might be another candidate for a wrapper class.

List Archive...

 
You need to have 'unzip' reachable through your system's path environment variable. Than you can select an archive that's listed in your current project's classpath and then the content of the selected jar or zip file can be viewed from inside Emacs. OK, its not the killer functionality everyone was looking for, but I once found it convenient to have it and since its small its not much bloat. BTW, you can remove entries from the Tools menu manually in the initialization file.

Class Dependencies

Starts with your main class and creates a list with all classes that get invoked statically. You can use this to manually check if you missed distributing a .class file that your project does need. Does not help in case a class gets dynamically loaded.

Make sure you have set your project main class in 'Edit->Project Settings...', invoke this tool, and wait until it has analyzed all class files. Then it will load a file with all class names into the editor.

Jikes Debugger

This tool lets you invoke IBM's Jikes Debugger with the appropriate classpath and sourcepath as well as the relevant main class with your project paramaters. It is much more convenient then starting JD from hand each time or writing a batch file for each project.

Jikes Debugger is the property of IBM and is therefore not distributed together with Jacob. You can download it for free from IBM's alphaworks site. If you didn't take a look at it yet, it is very much worth to give it a try. It's not that fast and user friendly (but it's not so bad either), but it is very stable and didn't stall even on very big projects. I still try to avoid a debugger as much as I can, but from time to time it is very helpful.

To use Jikes Debugger together with Jacob make sure when you startup Jacob, that he jd.zip archive is in Jacob's classpath.

Be aware of the fact that using JD this way, Jacob and JD both run in the same virtual machine. If you close and restart JD several times, memory leaks each time. I was not able to close down JD and to also garbage collect all memory Jikes Debugger had used. If you are concerned with this, use the memory frame ('Help->Memory...') to keep an eye on Jacob's memory consumption and restart Jacob if necessary.

Licensor...

The Licensor is a tool which lets you select a license and it then goes through all Java source files of your current project and puts a license header comment at the top. It gives you a list of the files that were changed (or unchanged) afterwards.

Right now there are only licenses for the GPL and MPL. If you regularly work on projects that use a different license, be it open source or not, you can add easily add more licenses to Jacob. Put into the $JACOB_HOME/license directory one file named <license_name>.txt containing the whole text of the license and a second file named <license_name>-header.txt containing just the header file which will be used to be put at the top of each source file.Then in your Jacob initialization file add <license_name> to the Licenses key in the [Licenses] section. Next time you restart Jacob the new license will be known as well.

The header file can have some special tags in it all starting with a '@' character:

@name
@author
@email
@software
@url
@year

These tags will then be exchanged with their real project values when the header gets applied to the source code. E.g. these are the values I have specified for the Jacob project itself via the "File->Preferences..." and "Edit->Project Settings..." dialogs.

@name: Jacob
@author: Chr. Clemens Lee
@email: clemens@kclee.com
@software: Jacob - The Java Commando Base
@url: http://www.kclee.com/clemens/jacob/
@year: 2001

 
Back to Jacob's main page

Chr. Clemens Lee, email to: clemens@hehe.com