Installing jGRASP


Important Notes

This is jGRASP version 1.7.0. Check http://www.jgrasp.org for the latest version of jGRASP.

jGRASP is written in Java. Java 1.3 or higher must be installed on your machine in order to run jGRASP. The full JDK (j2sdk) 1.3 or higher (not the JRE) from Sun is required in order to use the integrated Java debugger and workbench.

jGRASP does not include any compilers. The JRE bundled version and all other versions of jGRASP do not include a Java compiler. In order to compile programs you must have a compiler installed.



Which JVM to Use

If you have downloaded a JRE bundled version of jGRASP, this is not a concern. Otherwise, Sun JDK (j2sdk) 1.4 is suggested. When jGRASP starts, you may get a message telling you that jGRASP has known problems or minor problems, or has not been tested on your system.



Installing from the Self-Extracting exe on Windows

Before running the installation file, you should close all applications. If a file from a previous installation is in use, the installer may give you a "Can not copy file" or "File in use" message. This would happen, for example, if you had the readme.txt file open in MS Word. If this happens, iconify the installer, close the file or the application that is using the file, pop the installer back up, and click "Retry" on the error dialog. If the installer will not run, you will have to install manually.

On Windows NT, if you have Administrator access, the start menu items and desktop shortcut will be installed for all users.



Manual Installation on Windows

Unzip the distribution file in the directory where you wish to install jGRASP. This will create a jgrasp directory containing all the files. Add a shortcut or start menu item to jgrasp\bin\jgrasp.exe.



Installing on Mac OS X

Unzip and untar the .tar.gz file, if this did not happen automatically when you downloaded. You can use Stuffit Expander or from a terminal, "gunzip jgrasp*.tar.gz" then "tar xf jgrasp*.tar". Then double click on the .pkg file. A root password is required to install. The first time you run jGRASP, the CSD font will be installed on your system, and a soft link to the jgrasp startup script (for command line execution) will be created in /usr/bin or your $HOME/bin directory.



Manual installation on Mac OS X

Unzip the distribution file in the directory where you wish to install jGRASP (you can use Stuffit Expander to do this). This will create a jgrasp directory containing all the files. You can then click on "jgrasp/bin/osx/j" to run jGRASP. The first time you run, the CSD font will be installed on your system, and a soft link to the jgrasp startup script (for command line execution) will be created in /usr/bin or your $HOME/bin directory.

If you want to create a "normal" OS X application, copy the "jgrasp/bin/osx/j.app" directory to the target location, then move the original "jgrasp" directory (the whole thing) into the copied "j.app/Contents/Resources" directory. If you don't want two versions of jGRASP to show up on the OS X "Start With" menu, delete the "jgrasp/bin/osx/j.app/Contents/Resources/jgrasp/bin/osx" directory.



Installing on x86 Linux, SPARC Solaris, and NetBSD/i386

Unzip the distribution file in the directory where you wish to install jGRASP. This will create a jgrasp directory containing all the files. You may want to add the "bin" subdirectory of this directory to your execution path or create a soft link to .../jgrasp/bin/jgrasp from a directory on the executable path.



Installing on Other Systems

Unzip the distribution file in the directory where you wish to install jGRASP. All the functions of jGRASP will work except for the compile and run functions.

If you are on a Unix system other than Linux, Solaris, or NetBSD/i386, you can build startup and "wedge" programs in order to use the startup shell and compile and run functions of jGRASP (C compiler and knowledge of how to use it is necessary).

The source for a startup client-server shell can be found at  jgrasp/src/linux_exec.c . The executable should be   jgrasp/bin/sys_jgrasp . For the best chance of success, compile with default optimization.

The source for the wedge can be found at  jgrasp/src/linux_run.c . The executable must be  jgrasp/jbin/sys_run . For the best chance of success, compile with default optimization.

Please contact us if you succeed in doing this. We can incorporate your executables in a future release of jGRASP.

If you are on a system other than Windows or a UNIX variant and have a good knowledge of system programming on your system, you can build a wedge based on the UNIX wedge sources found in  jgrasp/src . The executable must be jgrasp/jbin/sys_run.



Network Administration

jGRASP supports common settings for all users on a network. The common settings directory can be specified at installation time if using the self-extracting exe on Windows. Otherwise, in the "data" directory of the installation, create a file called "admin". Specify the directory to be used for administrator settings in this file. This should be the only contents of the file, and not be followed by a line feed or carriage return. Use a full path to specify the directory. This directory must be accessible and readable by all users, and writable only for administrators. You should select a location outside the jGRASP distribution, so that you can continue to use the settings after upgrading.

When an administrator (anyone with write access in the common settings directory) runs jGRASP, menu items that allow you to change administrator settings will appear on the control panel settings menu. Also, when copying or creating compiler environments, you will have the choice of creating them for all users or just the current user.



Running jGRASP

jGRASP requires a Java 1.3 or better virtual machine and system classes to run. You can get the latest JDK from Sun Microsystems.

You will probably need about 48 Megs of memory to run jGRASP, but this depends on the virtual machine, jit compiler, and which other applications you run concurrently.



Running on Windows

The bin\jgrasp.exe file will start jGRASP in single-instance mode. Running jGRASP a second time will pop up the currently running instance. If you chose to associate file extensions with jGRASP during installation, clicking on an associated file will pop up the file in the currently running instance. A Windows application titled "jGRASP Control Shell", which initially runs minimized, displays the jGRASP output (including stack dumps if there is a crash) and allows the user to kill jGRASP if it locks up. It will first try a "soft kill", and if jGRASP does not exit within a few seconds, a "hard kill" will be issued.

"bin\jgrasp.exe" will search for a java.exe to run jGRASP in the following manner:

1) get from "-a" command line parameter if present

2) get from JGRASP_JAVA environment variable if present

3) check the registry for the current version of the Sun JDK if it is 1.3, 1.4, or 1.5 then the current version of the IBM JDK if it is 1.3, 1.4, or 1.5.

4) check the PATH for javac.exe - if found look for java.exe in the same place (avoids finding JRE before JDK)

5) check the PATH for java.exe.

6) check for the JRE bundled with jGRASP

The method used to find java.exe and the java command used to start jGRASP will be displayed in the "jGRASP Control Shell" window.



Running on Mac OS X

Double clicking on the "jGRASP" file, or on "jgrasp/bin/osx/j" if jGRASP was manually installed, will start jGRASP in single-instance mode. Running jGRASP a second time will pop up the currently running instance. Clicking on an associated file will pop up the file in the currently running instance. An application titled "jGRASP Control Shell", which initially runs minimized, displays the jGRASP output (including stack dumps if there is a crash) and the command used to start jGRASP, and allows the user to kill jGRASP if it locks up. It will first try a "soft kill", and if jGRASP does not exit within a few seconds, a "hard kill" will be issued.

The first time you run jGRASP it will create a soft link to a startup shell in /usr/bin or $HOME/bin. Then in a terminal shell you can run "jgrasp" and open files in an already running jGRASP with "jgrasp filename".



Running on Linux, Solaris, NetBSD/i386, and Other UNIX Systems

Similar single-instance mode executables exist for x86 Linux, SPARC Solaris, and NetBSD/i386. These can all be accessed through the bin/jgrasp shell script, which will also pass the location of the jGRASP installation to the correct executable so you don't have to. You can run the executables directly (they are in subdirectories of "bin" with obvious names) if you specify the location of the jGRASP installation through a JGRASP_HOME environment variable or "-j path" at the command line. A window titled "jGRASP exec", which initially runs minimized, allows the user to kill jGRASP if it locks up. It will first try a "soft kill", and if jGRASP does not exit within a few seconds, a "hard kill" will be issued.

On other UNIX systems, bin/jgrasp should run jGRASP directly, without a single-instance shell. See Installing on Other Systems for information on compiling the native parts of jGRASP.

For the "java" startup script, if the location of java is not specified through a "-a" command line parameter or JGRASP_JAVA environment variable, then "java" must be on the path.



Requirements for the Integrated Debugger

For both the Windows and UNIX/Linux startup programs, to use the integrated Java debugger, "java.exe" or "java" must be in the JDK directory structure (in /bin, where tools.jar is in /lib), unless the "-cp" command line argument or JGRASP_CLASSPATH environment variable is used.

On Mac OS X, the integrated debugger will be available by default.



Command Line Arguments for the Single Instance Executables and Shells

A filename can be given as the last argument. The leading dash for flags can also be a forward slash on Windows.

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

-e JGRASP_EXTENSIONS    - specify a path for jGRASP elements and user extensions that should persist between versions and may be supplied in optional packages. For now, the classes/system and classes/user subdirectories will be added to the classpath when any system Java compiler environment is used. This is just a convenient way to make library packages available to your Java programs. This can also be set in a JGRASP_EXTENSIONS environment variable. In Windows, a default location is chosen during installation, and will be retrieved from the registry. Otherwise, the default is the "extensions" directory in the jGRASP distribution.

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

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

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.



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 shut-down. 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 indeces; 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.

Command line functionality for batch formatting and printing like UNIX GRASP has.

Add more compiler setups.

Have a project realize that it has been moved, and copy previous file settings.

Add an editor for user defined templates.



Reporting Bugs / Requesting Features

If you are having a problem with a compile or run command, make sure the command works from the DOS command prompt or UNIX/Linux command line before contacting us.

If you are having a problem with a compile or run command, clear the Compile Messages or Run I/O window, turn on "Verbose Messages" under the "Settings" menu, execute the compile or run command, and copy and send us ALL of the output. This will make it much easier for us to determine the nature of the problem.

Check the known bugs or future plans page at  http://www.jgrasp.org  before reporting a bug or requesting a feature.

The preferred way to send a bug report or request a feature is using the "Report a Bug" menu under "Help". Using this will send us system information (OS, Java version, etc.) that may be essential in helping us to track down the bug or understand your request.

You can also email bug reports and feature requests to graspATengDOTauburnDOTedu. Be sure to include the version number, and for bug reports, the system you are using, and the stack dump if any.



About jGRASP

jGRASP version 1.7.0.

Built on June 1, 2004.

Copyright 1999-2004 Auburn University

Project Director:
   James H. Cross II, Ph.D.
   Computer Science and Software Engineering
   107 Dunstan Hall
   Auburn University, Alabama 36849
   graspATengDOTauburnDOTedu

Chief Programmer:
   Larry A. Barowski

Empirical Evaluation:
   Dr. Dean Hendrix

Wireless Software:
   Dr. David Umphress



Acknowledgements:

The development of jGRASP has been supported by a research grant from the National Science Foundation.

The development of previous versions of GRASP was supported by research grants from NASA Marshall Space Flight Center, the Department of Defense Advanced Research Projects Agency (ARPA), and the Defense Information Systems Agency (DISA).

 

Free code used in jGRASP (thanks to all who provided it):

The click-to-error regular expression matching, regular expression find-and-replace, and multi-file search use OROMatcher. See the ORO License.

The console connection mode for Windows NT is based on portions of Gordon Chaffee's very well structured and well documented port of "expect" to Windows NT. See the Expect License.

The Windows installation was created with Freeman Installer.

Many of the toolbar icons were created and copyrighted by Dean S. Jones.



jGRASPTM License

Software License for jGRASP Version 1.7.0

Copyright 1999-2004 Auburn University

Section 1. License Grant.

Auburn University grants to you a non-exclusive and non-transferable license to use jGRASP and the associated documentation provided in jgrasp/help, collectively "jGRASP". jGRASP may be installed for use on a single computer or on a local area network. The "wedge" source code provided in the jgrasp/src directory is free of license restrictions. It may be used or modified for any purpose. jGRASP is a Trademark of Auburn University.

Section 2. Restrictions

Distribution of jGRASP is not permitted without written permission (see Supplements), except that it may be distributed internally within a single organization. Distribution of components of jGRASP separately from the whole is not permitted, except that the complete associated documentation provided in jgrasp/help may be distributed separately. Reverse engineering of jGRASP is not permitted. Any use of image files, icons, or executable components of jGRASP separately from the whole is prohibited.

Section 3. Disclaimer of Warranty

jGRASP is licensed "as is". There are no express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Auburn University makes no warranty with respect to the accuracy or completeness of information obtained through the use of this program. Auburn University does not warrant that jGRASP will meet all of your requirements or that its operation will be uninterrupted or error free or that any defect within jGRASP will be corrected. No oral or written information, representation, or advice given by Auburn University or an authorized representative of Auburn University shall create a warranty. Auburn University and its agents shall in no event be held liable to the user for any damages, including direct, indirect, incidental, or consequential damages, lost profits, lost savings, or other such damages arising out of the installation, use, improper use, or inability to use jGRASP, even if Auburn University has been advised of the possibility of such damages, or any claim by any other person or entity related thereto.

Supplements

Distribution for Educational Purposes - Publishers may distribute the jGRASP software and the jGRASP Handbook (Tutorials and Reference) on CDs that accompany their textbooks provided that (1) the title "jGRASP(TM) 1.7.0 copyright 1999-2004 Auburn University" is included on each CD label, (2) descriptions of the CD indicate that jGRASP is included on the CD, and (3) a list of the textbooks that include jGRASP is provided to Auburn University (crossATengDOTauburnDOTedu). Permission to distribute jGRASP for educational purposes covers all CDs created prior to December 31, 2004 for inclusion in textbooks. While it is anticipated that distribution of jGRASP for educational purposes will remain royalty free, this supplement of the jGRASP license will be re-evaluated on an annual basis.

For additional information, contact James H. Cross II, Computer Science and Software Engineering, 107 Dunstan Hall, Auburn University, AL 36849 (334-844-6315, crossATengDOTauburnDOTedu).



ORO License

The Apache Software License, Version 1.1

Copyright (c) 2000 The Apache Software Foundation. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.

4. The names "Apache" and "Apache Software Foundation", "Jakarta-Oro" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org.

5. Products derived from this software may not be called "Apache" or "Jakarta-Oro", nor may "Apache" or "Jakarta-Oro" appear in their name, without prior written permission of the Apache Software Foundation.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation. For more information on the Apache Software Foundation, please see <http://www.apache.org/>.

Portions of this software are based upon software originally written by Daniel F. Savarese. We appreciate his contributions.



Expect License

Copyright (c) 1997 Mitel Corporation

Permission is hereby granted without license or royalty fees to use, copy, modify, and distribute this software and its documentation for any purposes, provided that the copyright notice set forth above and in the following two paragraphs appear in all copies of this software.

IN NO EVENT SHALL MITEL CORPORATION BE LIABLE TO ANY PART FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF MITEL CORPORATION HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MITEL CORPORATION SPECIFICALLY DISCLAIMS ANY CONDITIONS, REPRESENTATIONS OR WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND MITEL CORPORATION HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.