installing jgrasp etc.txt

The documentation folder contains general documentation. It includes an alternative version of Chapt

-h - display a help message. 

-l line_number    - select line_number for the filename argument. 

-g language    - force a language for the filename argument. language can be C, +, J, A, V, O for C, C++, Java, Ada, VHDL, and Objective-C. 

-d directory    - alternate settings directory. See "Command line arguments for jGRASP itself" below. 

-a JGRASP_JAVA    - specify the java command used to start jGRASP. This can also be set in a JGRASP_JAVA environment variable. If not specified, "java" will be called on UNIX/Linux, and on Windows the registry and PATH will be searched for "java.exe" as explained in Running on Windows. If a JRE is bundled with jGRASP, that VM will be used if no other is found. 

-j JGRASP_HOME    - specify the root of the jGRASP installation. This can also be set in a JGRASP_HOME environment variable. The "jgrasp" shell script attempts to "locate itself", so this should not be necessary under normal circumstances. This should never be necessary on Windows. 

-cp JGRASP_CLASSPATH    - specify a classpath to be used for jGRASP. This can also be set in a JGRASP_CLASSPATH environment variable. The "jgrasp.jar" file will always be prepended to this path. Under normal circumstances using this argument should not be necessary. 

-Jjvm_arg   - pass jvm_arg to the JVM running jGRASP. For example,  -J-Xmx90m  will make the maximum size of the memory allocation pool for jGRASP 90 megs. 


--------------------------------------------------------------------------------

Command Line Arguments for jGRASP Itself.

-d directory - use directory as the settings directory instead of USER_HOME/.grasp_settings. directory must be a full path name. By using this, you can run two jGRASP sessions concurrently and they will  not interfere with each other, or you can keep different settings for different users on the same system. 

-h - print a help message. 

-v - print the version number. 


--------------------------------------------------------------------------------

Using Help

This help is best viewed in a browser that supports frames, or from jGRASP. 

If you are using frames or jGRASP, the frame on the left side can be one of: 

Contents - links to major subjects. 
Index - alphabetized list of links to subject headings. 
Search (jGRASP only) - a search of the help text. 
At the top of each of these pages is a link to the other two. Clicking on any other links will change the page in the frame on the right side. 

The search page searches for sections containing all words entered in the "Search" field. 


--------------------------------------------------------------------------------

Control Structure Diagram (CSD)

The Control Structure Diagram, or CSD, is an algorithmic level diagram intended to improve the comprehensibility of source code by clearly depicting control constructs, control paths, and the overall structure of each program unit. The CSD is an alternative to flow charts and other graphical representations of algorithms. The major goal behind its creation was that it be an intuitive and compact graphical notation that was easy to use manually and relatively straightforward to automate. 

A primary purpose of jGRASP is to provide for automatic generation of the CSD for source code written in Java, C, C++, Objective-C, Ada, and VHDL (support for additional languages is planned). 


--------------------------------------------------------------------------------

Interface Terminology

These terms are used throughout this documentation. 

Control Panel - the top level jGRASP window. 

CSD Window - the source code editing windows. 

Virtual Desktop or Desktop - the optional desktop window that contains CSD windows. 

Tab Page or Page - one page of a tabbed window. 

Menu Accelerator - a function key or control-key combination that performs the same function as a menu item. 

Context Menu - a menu that pops-up over a specific interface item. In most environments, a right mouse click over the item triggers such a menu. 

Swing - also called JFC, the Java gui class library that jGRASP uses. 

Complier Environment - a group of settings that specify how jGRASP will interface with a particular compiler. 


--------------------------------------------------------------------------------

Known Bugs

Check the known bugs list at  http://www.jgrasp.org  for an updated list of known bugs, if you are not already there. Check the future plans page for a list of future features. Here is the bug-fix history. 


--------------------------------------------------------------------------------

Our Known Bugs

In the Java debugger and workbench, elements with replaced generic type are displayed with the replaced type (when known), but for "invoke method" and other operations, they are treated according to the actual run-time type. Also, generic type parameters supplied when creating an instance are not thoroughly checked for validity, and arguments for "invoke method" or "create instance" are not checked for compile-time validity with respect to generic replacements or generic type parameter bounds. These problems don't limit the use of the debugger or workbench in any way, and they will be fixed in a future release. 

On Windows, if documentation is viewed "outside of jGRASP", operations that should display javadoc documentation for fields or methods will only display the corresponding file (won't scroll to the field or method) for documentation on the local file system (Java library documentation on the web will work correctly). The built-in HTML viewer does not have this problem. This should be fixed in the next release. 

On Windows NT, a 16 bit process that is run with the %CY flag (console mode) can not be killed until the virtual DOS machine initializes and starts the process (which can take several seconds). An attempt to kill such a process will fail, but the process can be killed by closing the console, which will initially be iconified. This problem is not fatal and will rarely be encountered. It will not be fixed. 


--------------------------------------------------------------------------------

Bugs Caused by Java, Swing, or Window Manager Problems

These are difficult or impossible to work around. The eventual "fix" for them is (or will be) to get a newer version of the JDK. Many of them apply only to old versions of the JDK. 

File chooser details view does not resize rows when the font size is changed under some JDKs (all file choosers). 

On JDK 1.3.1 or earlier, when renaming a file or directory in a file chooser, tabbing out, clicking back in, and hitting enter will not rename and will cause a harmless stack dump. 

Changing the look-and-feel to Windows using keyboard menu navigation on JDK 1.3.1 or lower will cause a harmless stack dump with
"at sun.awt.windows.WInputMethod.dispatchEvent(WInputMethod.java: ..."
at the top. 

When using the integrated Java debugger, jGRASP and the target process will sometimes lock up. This is most likely due to bugs in the JDK, and happens much less frequently with newer versions of the JDK. The target JVM will sometimes crash as well, and jGRASP may need to be restarted in order for it to work again. 

On some JDK versions, the Help window will sometimes not come up, and a stack dump will be generated, the first time help is used. If this happens, help will not work until you shut down jGRASP and restart it. 

Performance is bad and there is much unnecessary repainting with the Mac Look-And-Feel. 

The help browser is not suitable for browsing the web. HTML display in Swing is limited and very buggy. The jGRASP help pages are constructed so as to work within the limitations and work around the bugs. This is somewhat better with newer versions of Java. 

On some UNIX/Linux VMs, running jGRASP through the single-instance shell will cause the JVM to crash at shutdown. This seems to be harmless. 

Windows installation may randomly fail. If it does, try it again. 

Click in the wrong place - when clicking in an unselected CSD window in the virtual desktop, the click position will be offset by the size of the border and menu. This can cause the cursor to move to an unintended location, the wrong text to be selected,  the scrollbar to be activated (and probably stuck down), a toolbar or menu item to be accidentally selected, and similar strange effects. This is fixed in JDK 1.3 final. 

Memory leaks - due to Swing bugs, there are some small memory leaks. These have been minimized as much as was possible. Opening and closing a CSD window on the virtual desktop will leak up to 1K or so on some systems. This should not be a problem unless you run jGRASP for weeks without restarting (like I do). There may be larger memory leaks that we are unaware of. 


--------------------------------------------------------------------------------

Future Features / Missing Features

Check the future plans page at  http://www.jgrasp.org  for an updated list of planned future features, if you are not already there. 

Current Development 

Advanced data structure display for the Java debugger and workbench - interface-based views, structural views. Ability for users to develop their own data structure views. 

More flexible compiler environments. Ability to run multiple commands for one "compile" or "run" item, add items to menus other than "Compile" and "Run", specify icons and have items appear on the toolbar. 

Forward development features for the UML diagram (drawing, creating shell classes). 

Future 

Ability to "undo" past CSD generation. 

Navigation (for Java first). 

More features for the integrated Java debugger: hex and octal display for values and array indices; a dynamically updated monitor display window, listing owning thread and waiting threads by monitor; automatic deadlock detection; byte code display; display of current watchpoints to make removing them easier; ability to set breakpoints without access to source code; repeated, animation-like stepping; counted stepping (eg: step in 42 steps); ability to disable/enable garbage collection for objects; assistance for memory leak (lost reference) detection; exception breakpoints; listing of all loaded classes with their fields and methods; show classpath, version, and other information for target VM; tracing variable changes; dumping of thread, stack, and variables to message window for easy cut-and-paste. 

A debugger connection and interface for languages other than Java. 

Unicode support - this will require considerable work, so it will not be done soon.