This is jGRASP version 2.0.6. Check https://www.jgrasp.org for the latest version of jGRASP.
jGRASP is written in Java. Java 1.6 (JDK 6) or higher must be installed on your machine in order to run jGRASP. The full JDK 1.5 or higher (not just the JRE) is required in order to use the integrated Java debugger and workbench.
jGRASP does not include any compilers. In order to compile programs you must have a compiler installed.
Which JVM to Use
The latest Oracle JDK is suggested. If you are using a very new version of Java or a non-Oracle version, you may get a startup 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, if you have Administrator access, the start menu items and desktop shortcut will be installed for all users.
For a silent install, use the /Q flag. This will install in the standard location with a desktop shortcut and start menu items, but no new file associations. You can use "/D=install_directory" to specify an alternate install location. Note that there will be no test to ensure that jGRASP is not running when this flag is used. If jGRASP is running while it is upgraded, it is likely to crash.
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. On 64 bit systems, add a shortcut or start menu item to jgrasp\bin\jgrasp64.exe; on 32 bit systems, add a shortcut or start menu item to jgrasp\bin\jgrasp.exe.
Installing on macOS
Double click on the .pkg file if it did not run automatically after downloading. A root password is required to install.
Manual installation on macOS
Unzip the distribution file in the directory where you wish to install jGRASP. This will create a jgrasp directory containing all the files. You can then click on "jgrasp/bin/osx/jcs" to run jGRASP.
If you want to create a "normal" macOS application, copy the "jgrasp/bin/osx/jcs.app" directory to the target location, then move the original "jgrasp" directory (the whole thing) into the copied "jcs.app/Contents/Resources" directory. If you don't want two versions of jGRASP to show up on the macOS Start With menu, delete the "jgrasp/bin/osx/jcs.app/Contents/Resources/jgrasp/bin/osx" directory.
Installing on x86 Linux
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.
The bin/create_linux_launcher.sh script will create a desktop launcher for jGRASP on most Linux systems.
Note that java must be on your system path in order to run jGRASP.
Installing on Other Systems
Unzip the distribution file in the directory where you wish to install jGRASP.
If you are on a UNIX system other than Linux with LSB or macOS, the first time you attempt to compile or run a program jGRASP will attempt to build the native "wedge" and startup shell programs. This may fail due to file permission issues or for other reasons, in which case jGRASP will use a less capable pure Java wedge. To build the native parts from the command line, cd to the jGRASP "src" directory. Run ./configure and if successful run ./Make.sh .
Please contact us if this fails for some reason other than a C compiler not being installed or your system not being a UNIX variant.
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/internal_bin/sys_run . If this is not done, the pure Java wedge will be used. This may cause block output buffering when you run programs from jGRASP (this is not generally a problem if you are running Java programs).
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.
Linux Multi-click Interval Fix
Due to Oracle bug 5076635, the multi-click interval time on many Linux systems is set to 200ms regardless of the desktop setting. This means that you have to double-click very fast or it will register as two single clicks. This bug affects all Java applications. The following paragraphs describe a procedure that will usually solve this problem.
Look for a file in your home directory named .Xdefaults or .Xresources. If one of those exists, open it up in jGRASP; otherwise, open a new file using File > New > Plain Text.
Add the following line to the file:
Half a second (500ms) is a reasonable multi-click interval for most people, but you can use a different value if you like.
Save the file. If it is a new file, save it in your home directory as ".Xdefaults".
Shut down jGRASP and log out or run the following at the command line:
(or .Xresources if that is the file you edited).
Log back in and/or restart jGRASP. If the problem is not fixed after creating a new .Xdefaults file, try again using .Xresources.
jGRASP requires a Java 1.6 (JDK 6) or better virtual machine and system classes to run. You can get the latest JDK from Oracle.
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" is available from the Windows system tray. This displays the jGRASP output (including stack dumps if there is a crash) and allows you 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" or "bin\jgrasp64.exe" will search for a java.exe to run jGRASP in the following manner:
1) get from previously set jGRASP startup settings.
2) get from "-a" command line parameter if present
3) get from JGRASP_JAVA environment variable if present
4) check the registry for the current version of Java in this order: highest Oracle JDK under which jGRASP has been tested, highest Oracle JDK under which jGRASP has not been tested, highest Oracle JRE under which jGRASP has been tested, highest Oracle JRE under which jGRASP has not been tested, highest IBM JDK under which jGRASP has been tested, highest IBM JDK under which jGRASP has not been tested, highest IBM JRE under which jGRASP has been tested, highest IBM JRE under which jGRASP has not been tested.
5) check the PATH for javac.exe - if found look for java.exe in the same place (avoids finding JRE before JDK)
6) check the PATH for java.exe.
The method used to find java.exe and the java command used to start jGRASP will be displayed in the jGRASP Control Shell window.
If jGRASP will not run normally, please report the problem. As a last resort, you should be able to run the "jgrasp.jar" file manually from the command prompt. Some minor features, such as deleted files being moved to the Windows recycle bin, will be missing. If "java.exe" is not on your system PATH, you'll need the full path to Java. For example, with jGRASP installed in the default location, you would do:
cd C:\Program Files (x86)\jGRASP
"C:\Program Files\Java\jdk1.8.0_31\bin\java" -jar jgrasp.jar
Running on macOS
Double clicking on the "jGRASP" app file, or on "jgrasp/bin/osx/jcs.app" 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 you 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.
jGRASP will select Apple Java 6 over Oracle Java 7 if both 6 and 7 are present and Java 8 or higher is not. Oracle Java 7 tends to have slow display performance and poor support for retina (uneven font sizes, etc.) compared to Apple Java 6. This is much improved on newer versions of Oracle Java 8.
If jGRASP will not run normally, please report the problem. As a last resort, you should be able to run the "jgrasp.jar" file manually from a terminal window. Some minor features, such as opening files by double clicking in Finder, will be missing. For example, with jGRASP installed in the default location, you would do:
java -jar jgrasp.jar
Running on Linux and Other UNIX Systems
Similar single-instance mode executables exist for x86 Linux. These can 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. A window titled "jGRASP exec", which initially runs minimized, allows you 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 Apple Java, 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.
-nosplash - do not show the splash screen at startup.
-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, P for C, C++, Java, Ada, VHDL, Objective-C, and Python.
-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 and through jGRASP startup settings on Windows and macOS. 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.
-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-Xmx2048m will make the maximum size of the memory allocation pool for jGRASP 2 Gigs.
Installing and Running jGRASP in Portable Mode
jGRASP can be run in portable mode from a USB drive or other portable drive. In this mode, all opened files and projects, project files, etc. are stored in a drive-relative and OS-neutral format, so that the jGRASP desktop, projects, etc. can be used regardless of the Windows drive letter or Linux/Unix/Mac mount directory for the drive, and regardless of the OS on which the drive is installed. jGRASP startup settings will also be stored on the portable drive. The Java installation used to run jGRASP may be on the portable drive or on the local system(s).
Installing Portable jGRASP
To install jGRASP for portable use, download the .zip installation file and unzip anywhere on a portable drive. Settings will be stored in a ".grasp_settings" directory in the same directory that contains the jGRASP root directory "jgrasp". Startup settings will be stored in a "jGRASP_ss" file also in that same directory. These settings will not be lost when upgrading.
If desired, Java may be installed on the portable drive by copying files from a Java installation on the desired OS. Settings > jGRASP Startup Settings (while running in portable mode) can be used to select that Java executable for use by jGRASP (by default it will run under the current system's "java"), or on Windows by running bin\winconfig_portable.bat before running jGRASP.
Running in Portable Mode
The bin\jgrasp_portable.bat file will start jGRASP in portable mode on 64 bit Windows systems, while bin\jgrasp_portable32.bat must be used on 32 bit Windows systems. On other operating systems, jGRASP can be started in portable mode by running "jgrasp -p drive_root" from the "jgrasp/bin" directory, where drive_root is the current mount point for the portable drive.
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 two set of setting on the same system and user account.
-h - print a help message.
-v - print the version number.
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, VHDL, and Python.
These terms are used throughout this documentation.
Control Panel - the top level jGRASP window.
CSD Window - the source code editing windows. Also referred to as "editing window".
Virtual Desktop or Desktop - a desktop window that may contain code editing windows, CPG windows, etc.
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.
Compiler Environment - a group of settings that specify how jGRASP will interface with a particular compiler.
Check the known bugs list at https://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
Output in interactions is not shown until all processing is complete. Input in interactions will appear above the interactions text that caused it to be requested, and will not be correctly ordered with output. This will be fixed in the next release.
Interactions is not Java 8 compatible.
Interactions is missing some Java language features: static import, uninitialized variables (interactions locals are now initialized as if they were fields), generics.
Interactions does not allow the minimum long and integer constants to be used.
In the Java debugger and workbench, if a field exists in an implemented interface of the declared type of an object, and a field with the same name exists in the superclass but is "not inherited" according to JLS terminology (is declared private or is inaccessible from the child), the field declared in the interface will be shown as "not visible" (it will have a red bar through it), although it should be visible (jGRASP definition of "visible" is "available without casting"). This is due to Oracle bug 6655791, but we may work around it in a future jGRASP release.
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 as 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.
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).
Performance is bad and there is much unnecessary repainting with the Mac Look-And-Feel and Nimbus Look-And-Feel.
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.
Memory leaks - due to Swing bugs, there are some small memory leaks. These have been minimized as much as was possible. This should not be a problem unless you run jGRASP for weeks without restarting. There may be larger memory leaks that we are unaware of.
Future Features / Missing Features
Check the future plans page at https://www.jgrasp.org for an updated list of planned future features, if you are not already there.
The current focus is the jGRASP Plugin for IntelliJ, which brings the jGRASP viewers and canvas to IntelliJ IDEA and Android Studio, for Java and Kotlin.
Code completion for Java.
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).
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, 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.
Command line functionality for batch formatting and printing.
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 https://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.
jGRASP version 2.0.6.
Built on January 10, 2020.
Copyright 1999-2020 Auburn University
Computer Science and Software Engineering
3101 Shelby Center
Auburn University, Alabama 36849-5347
Chief Software Engineer:
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 Windows installation was created with Nullsoft Installer.
Software License for jGRASP Version 2.0.6
Copyright 1999-2020 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 one or more computers 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. The plugin source code provided in the jgrasp/extensions directory, with the exception of the Web-CAT tool plugin sources, may be used or modified for any purpose, but when linked with the jGRASP jar file, the results may only be used as jGRASP plugins. See the Web-CAT source files for license information specific to that plugin. Source code for our slightly modified version of the Eclipse Web-CAT submission plugin is available upon request. 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.Section 4. Third Party Software Bundled Software:
Software that is bundled with jGRASP, if present, is not subject to this license. This software will be within a directory named "bundled" in the jGRASP installation. All such software is independently usable. Check the individual project websites for license details. Bundled software may include:
File putbi8a.pfb, Utopia Font (used under the TeX Users Group sublicense):
Copyright 1989, 1991 Adobe Systems Incorporated. All rights reserved.
Utopia is either a registered trademark or trademark of Adobe Systems Incorporated in the United States and/or other countries. Used under license.
ADOBE MAKES NO REPRESENTATIONS ABOUT THE SUITABILITY OF THE SOFTWARE FOR ANY PURPOSE. IT IS PROVIDED "AS-IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. ADOBE DISCLAIMS ALL WARRANTIES WITH REGARD TO THE SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL ADOBE BE LIABLE TO YOU OR ANY OTHER PARTY FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER WHETHER IN AN ACTION OF CONTRACT NEGLIGENCE, STRICT LIABILITY OR ANY OTHER ACTION ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. ADOBE WILL NOT PROVIDE ANY TRAINING OR OTHER SUPPORT FOR THE SOFTWARE.
See file "utopia_license.txt" in the "data" directory for the full license.File OpenSans-Semibold.ttf, Open Sans Font:
Digitized data copyright © 2010-2011, Google Corporation.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Distribution for Educational Purposes - Publishers may distribute the jGRASP software and the jGRASP Handbook (Tutorials and Reference) on media that accompany their textbooks provided that (1) the title "jGRASP(TM) 2.0.6 copyright 1999-2020 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 media finalized prior to January 31, 2022 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, 3101 Shelby Center, Auburn University, AL 36849-5347 (334-844-6315, crossATengDOTauburnDOTedu).