installing jgrasp etc.txt

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

Installing jGRASP

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

Important Notes

This is jGRASP version 1.8.3. 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.