Installing jGRASP

 

Important Notes

This is jGRASP version 1.3.6 Beta. Check http://www.eng.auburn.edu/grasp/ for the latest version of jGRASP.

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

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, the following JDKs/JREs are supported: Sun Windows 1.2 - 1.3 (1.3 suggested), Sun Solaris 1.2.1 - 1.2.2, Blackdown Linux 1.2.0, Sun Linux 1.3. You may have major or minor problems running on other JVMs.

To use the integrated Java debugger, JDK 1.3 from Sun is needed (and you should develop under 1.3 also).


 
 

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. If you want to use native Windows printing or view files "printed as RTF", you need to install the font  jgrasp\src\csd9.ttf ("Java" printing does not require a font). You can do this by running  jgrasp\jbin\installfont.exe  from the  jgrasp\bin  directory, or by using  Start / Settings / Control Panel / Fonts / File / Install New Font.


 
 

Installing on x86 Linux, SPARC Solaris

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 or Solaris, you can build a "wedge" program in order to use the compile and run functions of jGRASP (C compiler and knowledge of how to use it is necessary). The source can be found at  jgrasp/src/linux_run.c . The executable must be  jgrasp/jbin/sys_run .  The source for a client-server shell can be found at  jgrasp/src/linux_exec.c . That executable can have any name, it is only used externally.

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

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 Windows exec", 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 PATH for javac.exe - if found look for java.exe in the same place (avoids finding JRE before JDK)

4) check the PATH for java.exe - if it is found in the system directory, Windows directory, or any subdirectory of those, check the registry for the actual distribution location of a Sun JDK installation.

5) check for the JRE bundled with jGRASP

6) look in C:\jdk1.2.2\bin then C:\jre1.3\bin

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

 


Similar single-instance mode executables exist for x86 Linux and SPARC Solaris. These can both 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.

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.


 

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. In other words, "java.exe" can't be the redirecting startup program on Windows, or any kind of startup shell on UNIX/Linux.


 

Command line arguments to the single-instance executables / 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 for C, C++, Java, Ada, and VHDL.

-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 PATH, then standard JDK locations will be searched for "java.exe". 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 retreived 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.

In a browser, the search page requires Java 1.1 or better. You will need a Java 1.1 or better plugin, and must have it enabled, to use the search.

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. The CSD is a natural extension to architectural diagrams, such as data flow diagrams, structure charts, module diagrams, and class diagrams.

A primary purpose of jGRASP is to provide for automatic generation of the CSD for source code written in Java, C, 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.

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.eng.auburn.edu/grasp/  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.

Back up your work - this is a Beta release, and has not been thoroughly tested. Save and back up your work frequently.


 

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). If this happens, the process can be killed by closing the console, which will initially be iconified.

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 the HotSpot vm and newer versions of the jDK. Note that on a dual processor NT or Win 2000 system this may happen frequently, making the integrated debugger effectively unusable.

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.

Modified warning will sometimes appear when saving a file that has not been modified outside of jGRASP. The modification time and jGRASP save time will differ by about one second. This has only been seen on a dual processor system running Linux, and we are not sure if this is a problem with Linux, the JDK, or jGRASP. If you experience this on other systems, let us know.

The "Left Align" CSD setting does not work correctly. The code is not shifted before a save or compile, among other problems.

Windows native printing - CSD and text fonts will sometimes not be the same size (note: improved from "usually" to "sometimes"). The CSD font is not as symmetrical and "perfectly rendered" as it is on the screen or with JVM printing.


 
 

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.

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.

Using the integrated debugger on a dual-processor NT system will always or frequently cause jGRASP and the target process to lock up.

Using the integrated debugger may occasionally cause jGRASP and the target process to lock up.

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.

Closing a CSD window will cause an exception on Blackdown and Sun Linux JDK 1.2.2. jGRASP will lock up when closed on these systems (you'll have to kill it manually). We will probably not work around the bug that causes these problems unless it is not fixed in the corresponding 1.3 releases. For now, do not use these systems unless you're willing to put up with the problems, and shut down now and then if you're opening and closing a lot of windows, because memory is leaked each time a window is closed.

Font problems on Windows JDK 1.2.2 (not seen on older or newer versions). If you use bold or italic text properties, text in CSD windows will appear normal, bold, or italic at random.

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.

Freeze up - jGRASP may freeze up when starting. If you kill it and start again, it is likely to run (possibly after several tries). Note that after killing jGRASP you will get a warning that there is a currently running instance; choose "Run Anyway" to continue.

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

Caps lock - the caps lock key will not work on some systems. Having caps lock on may also cause menu accelerators not to work.

Display mode - jGRASP may not run with all display modes (color depths) on all systems. It probably won't run on Blackdown Linux with a 24 bit display (this is a problem with all Java apps) - haven't tried or investigated the latest Blackdown version yet.

Bad dialog positions - due to Swing bugs, on some systems dialogs may pop up in strange positions, possibly off-screen. Clicking the menu item that brought up the dialog again will usually move it on-screen.

Problems on JDK 1.2 - using maximized CSD windows on the virtual desktop may lead to a confused layout.

GNOME - If you are using GNOME (the default desktop environment on RedHat 6), you may not be able to run jGRASP because of freeze-up (this is a problem with all Java apps).

olvwm - on older versions of olvwm and possibly other window managers, the title bars may not show the title bar text (this is a problem with all Java apps). Install the latest olvwm to fix this (or bug your sysadmin into installing it).

Solaris JDK 1.2 problems (you should not use 1.2):

Dialog layout is often messed up, with buttons off-screen or extra empty space.

Find and replace does not see the find text most of the time. Sometimes hitting "Enter" will make it work. If you highlight the search text then pop up the dialog, that will work. Since the replace text may not be recognized, "Replace All" is very dangerous.


 
 

Future Features / Missing Features

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

Short Term / Ongoing

More UML features, including printing.

Navigation (for Java first).

More features for the integrated Java debugger: show new and changed values in a different color; 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 change values while debugging; 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.

Add close button to title bar of desktop CSD windows. It is not there now because of a Swing bug.

Switch to heavy menus. This is not done now because of Swing bugs on some systems.

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

A global setting for the help browser.

Ability to save and load named workspaces.

Improve the CSD TrueType font for better looking native Windows printouts and RTF files.

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

When jGRASP starts, you will get a warning if you are using a JVM on which jGRASP has known problems or on which we have not tested jGRASP. If you are using such a system, do not report bugs like freeze-up or layout bugs, which are probably caused by the virtual machine and system classes (you should get a message telling you this when jGRASP starts).

On Windows, check out the jGRASP exec shell. It will be minimized on the task bar. This window displays Java stack dumps from jGRASP.

On UNIX/Linux, run from the command line so you can capture any Java stack dumps.

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.eng.auburn.edu/grasp/  before reporting a bug or requesting a feature. Email bug reports and feature requests to grasp@eng.auburn.edu. 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.3.6 Beta.

Released August 24 2001.

Copyright 1999-2001 Auburn University

Project Director:
   James H. Cross II, Ph.D.
   Computer Science and Software Engineering
   107 Dunstan Hall
   Auburn University, Alabama 36849
   grasp@eng.auburn.edu

Chief Programmer:
   Larry A. Barowski
 

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.

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


 
 

jGRASP License

Software License for jGRASP Version 1.3.6 Beta

Copyright 1999-2001 Auburn University

Section 1. License Grant.

     Auburn University grants to you a non-exclusive license to install and use jGRASP and associated documentation.  jGRASP may be installed for use on a single computer or on a local area network and may be freely distributed to the public at large. Distribution of components of jGRASP separately from the whole is not permitted, except that the complete documentation may be distributed separately.

      The "wedge" source code provided in the jgrasp/src directory is free of license restrictions. It may be used or modified for any purpose.

Section 2. Exclusions

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


 
 

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