Settings


 
 

General Info for Settings

There are three levels of CSD window and print settings in jGRASP: workspace, project, and file. Workspace settings apply to all files. Project settings apply to all files when the associated project is selected (there is a default project if none has been selected). File settings apply to a specific file. Each workspace setting can be overridden by a project setting, and each project setting by a file setting. In order to change the setting at any level (override the setting at the next level down), the "Use Default" checkbox must be checked. If it is not checked, the current default setting is displayed, and is not editable. Note that this default setting is not a fixed value, but the value of the corresponding setting at the next level down (which can be changed), or for workspace settings, the system default value (which could change with a new release of jGRASP - but won't unless absolutely necessary).

In most cases, you will want personalized settings to apply to all CSD windows, in which case you should edit the workspace settings. If you use a variety of compiling environments for different projects, you would most likely edit compiler settings at the project level. Since the settings of the current project apply to all files, a single file can be used in different projects without conflict. File level settings would most commonly be used to override the default language for the file, and to add any file-specific compiler flags. Some settings, such as the CSD colors and font, can only be set at the workspace level.


 
 

CSD Window Settings Dialog

This dialog is used to set most properties not related to printing. The CSD Text and Font pages are available only for workspace settings.

Compiler Page

Language specific settings page on the CSD window settings dialog.
 

Language Combo Box

The "Language" combo box specifies the language for which settings are being viewed or edited, and for file level settings, the language of that file.


 
 

Environment page

"Compiler Environments" specify the compile and run commands (Make, Compile, Compile and Link, Semantic Check, Run, Debug, and for Java, Run Applet and Debug Applet), working directories, error formats, and environment variables.

System compiler environments, supplied with jGRASP, can be viewed or copied, but not edited or removed. Note that system compiler environments for Java that are have "prefer JDK compiler" in the name will attempt to use the same version of Java that jGRASP is running under to compile and run programs.

Local compiler environments, created by the administrator, can be edited or removed only by an administrator. These have names beginning with "local:".

User compiler environments, created by the user, can be edited or removed by the user. These have names beginning with "user:".

To use a compiler environment, select it in the list, then hit the "Use" button on the environment page (to the right of the list). This will immediately activate the environment, there is no need to click "Apply" or "OK" on the settings dialog.

Use - use the selected environment (immediately applied).

New - create a new environment using a compiler environment dialog.

Copy - copy the selected environment using a compiler environment dialog. It must be saved under a new name.

View - for system environments, view the environment using a compiler environment dialog.

Edit - for user created environments, edit the selected environment using a compiler environment dialog.

Remove - remove a user created environment.

Select - select the current environment from the list, or if it is not available, display a warning.


 
 

Flags/Args/Main Page

Main File - specifies the file used to substitute command variables beginning with  MAIN_  or  main_  . This is intended to be the file containing the executable module for languages such as Java or Ada. If no main file is used, "main" variables will be substituted with the current file (useful for single file projects). The %<PROJECT_PATH> and %<SEP> (or %/ or %\) variables can be used in the path.

FLAGS or ARGS - for each command, this will replace any %<FLAGS> or %<ARGS> variables. This is intended to be used for passing flags to a compiler or arguments to an executable.

FLAGS2 or ARGS2 - for each command, this will replace any <FLAGS2> or <ARGS2> variables. This can be used when multiple sets of flags are needed. In the Java compiler environments supplied with jGRASP, these are the arguments sent to the jvm during a "run", while "FLAGS or ARGS" are the arguments sent to the application.


 

HTML Page

This specifies the contents of the temporary HTML file used for "Run as Applet" in Java. %<PATH>, %<FILE>, %<BASE>, %<file>, %<base>, %<PACKAGE>, and %<PACKAGE_PATH> variables may be used here.


 
 

Extensions Page

Allows the default extensions for each language to be set. For a file that has not been opened in jGRASP before, these extensions determine which icon will be shown in the file browser page or in a file dialog, and which language will first be used when the file is opened (once opened, the language associated with a file is remembered). Extensions must be listed without a preceding dot and separated by whitespace. If the same extension is set for more than one language, an "unknown" icon will be shown, and the user will be prompted to select one of the appropriate languages before opening the file.


 
 

Variables

Variables are expressed as %variable_name or %<variable_name>. Variables longer than one character that were added after version 1.4.3 must be expressed as %<variable_name>, and are marked as [new] below.

%<JGRASP_PATHS> [new] - paths set in workspace and project "PATH" tabs. Workspace level paths are appended to project level paths. In the system compiler environments, this variable is always prepended to the PATH.

%<JGRASP_CLASSPATHS> [new] - classpaths set in workspace and project "PATH" tabs. Workspace level classpaths are appended to project level classpaths. In the system compiler environments for Java, this variable is always prepended to the CLASSPATH.

%<FLAGS> - flags or arguments.

%<ARGS> - same as %<FLAGS>.

%<FILE> - full path to file.

%<file> - filename.

%<BASE> - full path to file without extension.

%<base> - filename without extension.

%<PATH> - full path to directory containing file.

%<EQ> - equals sign.

%<PLUS> - plus sign.

%<SEP> or %\ or %/ - name separator character ( \  on Windows  /  on UNIX).

%<PATH_SEP> or %; or %: - path separator character ( ;  on Windows  :  on UNIX).

%A - "a.exe" on Windows systems, otherwise "a.out".

%<PROJECT_PATH> - path to the directory containing the current project, or the empty string if the current project is the default project.

%<JAVA_BIN_DIR> - path to the directory containing the java executable that was used to start jGRASP.

%<DOC_DEST> [new] - documentation destination directory.

%<TRANSPORT> - JDK jdpa (debug interface) transport appropriate to current OS. This is dt_shmem if available, dt_socket if dt_shmem is not available, and the first transport found otherwise.

%<CLASSIC_OPT> - "-classic" on systems where the latest JDK ships with a classic VM, otherwise the empty string.

%<PACKAGE> - (Java) full package name.

%<CLASS> - (Java) full package/class name.

%<class> - (Java) class name.

%<PACKAGE_PATH> - (Java) path to package root.

%<HTML_FILE> - (Java) full path to temporary html file.

%<html_file> - (Java) temporary html file name.

%<EXTENSION_PATH> - path to jGRASP extensions directory. This was set during installation on Windows, by a JGRASP_EXTENSIONS environment variable, or -e flag at startup.

%D - begins and ends a part of the command that is only used when compiler debug mode is on.

%N - begins and ends a part of the command that is only used when compiler debug mode is off.

%I - begins and ends a part of the command that is only used when a file-level command is executed.

%K - begins and ends a part of the command that is only used when a project-level command is executed. Currently this is only used for project documentation in Java.

%<EY> - turn on input echo. This is the default mode unless debug connect mode (%<CX>) is selected and active (system is Windows NT/2000/XP and I/O is not is DOS window). In this mode, input in the Run I/O window remains visible after it is entered.

%<EN> - turn off input echo. In this mode, input in the Run I/O window disappears after it is entered. This is useful if the target process will echo input, or if the input should not be seen in the output stream.

%<CP> - turn on pipe connection mode for a command (Windows only). This is the default mode (but the Cygwin compiler environments use <%CY>). In this mode, input and output to the target process will be through pipes. Many Windows programs will buffer output in this mode (Java programs will not).

%<CD> - turn on DOS window mode for a command (Windows only). If on, the target process will always run in a DOS window.

%<CY> - use Cygwin wedge for a command (Windows/Cygwin only). If on, the target process will be called from a Cygwin-aware native wedge program. This should eliminate output buffering problems for Cygwin applications. This wedge can not be used for non-Cygwin executables, or if you have an old version of Cygwin. For old versions of Cygwin, you will likely get an error message stating that "Cygwin1.dll" is missing, in which case you need to use a different connection mode. You might have the same problem with a new version of Cygwin if your PATH is messed up (possibly because you have multiple versions of Cygwin installed), or because the Cygwin mounts are messed up.

%<CC> - turn on console connection mode for a command (Windows only). If on, input to the target process will be through a console, while output is through pipes. This can eliminate I/O buffering problems seen when input is through a pipe. It does fix buffering problems on executables compiled with some old versions of Cygwin gcc and g++. On VC++, Borland bcc, and new Cygwin compiled executables, it makes buffering worse (block buffered instead of line buffered output). It will cause some jvms to crash.

%<CX> - turn on debug connection mode for a command (Windows NT/2000/XP only). This mode has not been thoroughly tested; it may have problems. If on, the target will run as a debug process in Windows NT/2000/XP, and console functions will be intercepted to collect output. This will make the run I/O window behave more like a console. An actual console which echoes I/O will pop up, initially iconified. This window can be used to enter escape sequences, etc. This mode will not work for processes that move the cursor around in the console. This changes the default echo mode to off, as most processes will echo input to the console. Input color will change to text color in the Run I/O window when it is replaced by the echo.

%<ND> - "Run in MSDOS Window" setting will be ignored on Windows. This is used for the integrated Java debugger, which currently must use the Run I/O window for I/O.

%<V1> - variable specified in environment.

%<V2> - variable specified in environment.

A %<FLAGS>, %<ARGS>, %<FLAGS2>, or %<ARGS2> variable must be surrounded by whitespace; the others need not be. To put a percent symbol in a command, use %%. To put a double quote in a quoted string, use %'.

 Variables that are related to files, paths, and classes may be prepended by  MAIN_  or  main_  . In that case, the main file will be used in the substitution, or if a main file was not specified, the current file will be used.


 
 

CSD Page

CSD generation settings.

Show Unit Symbols - if on, package/method/function symbols are shown.

Show Boxes - if on, boxes are drawn around major code structure headings (packages, methods, functions, etc.).

Force Newlines - if on, each statement is forced to a new line.

Auto Indent - if on, hitting return will insert whitespace even with the CSD, space and tab indentation of the previous line.

Show Data Syms. - if on, data and type symbols are shown.

Intra-Stmt. Align - if on, parenthesis and assignment symbols are aligned.

Indent Braces - if on, curly braced in C, C++, and Java are indented to match the enclosed block.

Soft Tab - if on, spaces are used instead of tabs, for the tab key, block indent, and auto indent.

Tab Size - width of a tab in characters. For variable-width fonts, the width of a "W" is used.


 
 

Colors Page (workspace settings only)

Colors for lexical types, CSD and background color, and message and I/O window colors. Click the "Use Default" checkbox off and click on the color square to change the color.


 
 

Font Page (workspace settings only)

Font Properties - font attributes (bold and/or italic) for lexical types in the CSD and message windows. Note that on some systems and with some fonts, bold and italic fonts will not align with the plain font and/or each other.

CSD Font - font to use in CSD and message windows.

Antialias - if on, CSD and message window fonts are antialiased. Antialiasing generally improves the appearance of text at higher resolutions (or large font sizes), but at low resolutions it may make text harder to read.

Encoding - encoding to use when displaying characters in CSD windows. You can use this to view code or text that is in an encoding other than the system default. You can type in encodings that are not on the drop-down list. jGRASP only supports 8 bit characters at this time, and encodings must be one-to-one (more than one text character can not map to one display character, and one display character can not map to multiple display characters). Encodings that do not fit this model will not be allowed, and do not appear on the drop-down list. The ASCII encoding is automatically converted to a raw encoding (in ASCII, characters 128-255 map to the unknown character, and would be lost when copying, etc. if we really used an ASCII encoding).

CSD Font Size - base size of the CSD window font.

Message Font Size - base size of the message and I/O window font.

Font Scale - scale factor for all fonts (CSD, menus, labels etc.) in jGRASP. This is quite useful for presentations.


 
 

Font Size Page (project and file settings)

CSD Font Size - base size of the CSD window font. Using different font sizes in different windows may consume a lot of memory.


 
 

Sources Page (Workspace and Project Settings Only)

Allows the search path for jGRASP to be specified. This path will be used for click-to-error in the jGRASP message windows as well as for finding classes shown in the call stack of the integrated debugger for Java. These are used when the message or call stack reference contains a relative path name or a Java class name. They are searched in order. If this is not set, only the working directory for the command that produced the message will be searched. If this is set, and one of the paths is "working directory", the working directory will be searched at that point. In most cases you will need to include "working directory" as one of the paths, probably the first.

Paths are entered one per line, and must be absolute.

This can be used, for example, to get click-to-error to work for JDK classes in Java stack dumps, if you have the JDK sources. In that case, the root of the JDK source tree (the directory containing the java, javax, etc. directories) should be on one line, and "working directory" on another. If you have Java sources and classes in separate directories, or use a make file in one directory with sources in another, you should specify the source directory or directories and not "working directory".


 
 

PATH Page (Workspace and Project Settings Only)

Allows you to add to the system PATH and CLASSPATH for compile and run commands. The project settings will take precedence over those at the workspace level. The compiler environments delivered with jGRASP will prepend these paths to the system PATH and CLASSPATH before compiling or running.

Paths are entered one per line. Appropriate separators will be added automatically.


 
 

Compiler Environment Dialog

This dialog allows a compiler environment to be created, edited, or viewed. These environments specify compile and run commands, working directories, and error formats.


 
 

Commands Page

This page specifies settings for Compile, Compile and Link, Check, Run, Debug, and (for Java) Run as Applet and Debug as Applet commands. For each command a working directory and error format can be specified. If a compile command is empty, that command will not appear on the "Compiler" menu of the CSD window, and the icon will not appear on the toolbar. If a run command is empty, that command will not appear on the "Run" menu of the CSD window, and the icon will not appear on the toolbar.

A variety of execution-time variables may be applied to commands and directories. Also, two static variables, %<V1> and %<V2>, can be specified at the bottom of the page.

Environment variables can also be modified.

Whitespace separates arguments in commands. Use double quotes to specify an argument containing whitespace. Use  %'  (percent-single quote) to include a double quote in a quoted argument. Any variable can also be used in a quoted argument, and %% (percent-percent) must be used to include a percent symbol.


 

"Command" specifies the command. All variables may be used.

"Directory" specifies the working directory for the command. If left blank, the directory containing the file will be used. %<PATH>, %<base>, and for Java, %<PACKAGE_PATH> variables may be used here.

"Error Format" specifies the error format for the command. The format string begins with a list of target flags, followed by a dash. The rest of the string is a Perl5 regular expression. See the perlre man page for a description of this format.

The target flags are:

f    = filename
c    = class
u    = unqualified file name (used in combination with class)
1    = start line
2    = start column
3    = end line
4    = end column

For click-to-error to work, the numbers of target flags must be equal to the number of matching groups in the regular expression. If a filename or class (possibly in combination with an unqualified file name) is matched and the corresponding file exists, a click will open the file. If the start line is matched, that line will be highlighted. If the start and end lines and columns are matched, that piece of text will be matched. If a filename and class are matched, the filename will be tried first. If the same target type matches multiple times, the last match is used. Unmatched groups are ignored, so you can use or'ed expressions and repeated target flags to match multiple possible formats. No error message is reported if the format is bad, or the number of target flags does not match the number of groups. On the control panel "Tools" menu, there is a testing tool for pattern matches.

As an example,   "f1-(\S(?:\s*\S)*):(\d+):.*"   will match the file and line number of a GNU-style error message. The regular expression reads as:  a matching group containing (a non-whitespace character followed by any number of non-matching groups consisting of any number of whitespace characters followed by one non-whitespace character); followed by a colon; followed by a matching group consisting of one or more digits; followed by a colon; followed by anything. In other words, "filename:line_number:other_text", where filename must begin and end with non-whitespace characters and be at least one character long, and line_number consists of one or more digits.

"Environment" allows environment variables to be changed and special jGRASP variables to be set. Variables are set one-per-line, using the following format:

Replace: VAR=VALUE
Prepend: VAR+=VALUE
Append: VAR=+VALUE
Set Special: SPECIAL_VAR==VALUE

For now, the only special variables are NOT_FOUND_MESSAGE, which specifies the message to display when the compiler is not found, and ADD_APPLETVIEWER_CLASSPATH, which adds -J-cp -J_CLASSPATH_ (where _CLASSPATH_ is the run-time CLASSPATH) as the first and second command line arguments.

Remember to add a path separator when prepending or appending to a path, like "PATH+=C:\newpath;" on Windows or "PATH+=/usr/local/newpath:" on UNIX/Linux, or "PATH+=/usr/local/newpath%<PATH_SEP>" (%; and %: are equivalent to %<PATH_SEP>) for either.

All variables may be used, so you'll need to escape "%" with "%%". All whitespace is significant, so don't leave space before the end-of-line or within the command unless you mean it to be there. For example, "VAR = VALUE" will set "VAR " (VAR followed by a space) to " VALUE" (VALUE preceded by a space).

You can have a plus sign at the beginning of a value by using the %<PLUS> or %+ variable. For example "VAR=%+val" will set "VAR" to "+val". In most environments, equals signs can not appear in environment variable names, but for completeness, you can use %<EQ> or %= to include an equals sign (this will most likely produce unexpected results).

By default, settings apply to all commands. You can change the commands they apply to using "-Command", "+Command", and "Command". For example "-Run" will make the following settings not apply to the run command, "+Run" will make the following settings apply to run, and "Run" will make the following settings apply only to Run. These commands can be grouped on a line, separated by whitespace. Use the exact labels in the dialog for command names, but for Run Applet and Debug Applet, use "Run_Applet" and "Debug_Applet" (replace space with an underscore). To turn all commands on or off, use "+All" and "-All".

For example: add C:\mypath to the path but not for run or debug, set DEBUG_TEST to 1 for compile only.

-Run -Debug
PATH+=C:\mypath;
Compile
DEBUG_TEST=1

 

Parse Page (C and C++ only)

CSD parsing options for C and C++. These apply only to CSD generation, not to compiling.

Include Path - search path for include files. The directory containing the file is always searched (last).

Include Files - all, none, or only local include files may be parsed. Local includes are defined as those include by #include "filename" rather than #include <filename>. Include file parsing is necessary for CSD generation if the include files contain unstructured macros (macros that when used, do not look like legal C or C++ code) or partial code structures. Parsing include files can make CSD generation slow, so it should be turned off if unnecessary.

Expand Macros - if true, macros are expanded during CSD generation. This may be necessary for unstructured macros, and for others, part of the CSD structure for the substitution result may be shown if this is on.

Allow GNU Extensions - if true, the GNU __attribute__ keyword is handled. It will not be colored.

Use Alternate Tokens - the C++ language allows alternate tokens such as "<%" for "{".

Allow C++ Comments - allow // comments in C. This can not be done by default because of things like:
   x //* this is x divided by 3 in ANSI C
   */ 3  .


 
 

Macros Page (C and C++ only)

Specifies macros that are pre-defined for CSD generation of C and C++. By default, _GRASP_IGNORE is defined: by using #ifndef _GRASP_IGNORE, blocks of code that can't or shouldn't be involved in CSD generation can be ignored.


 
 

Print Settings Dialog

This dialog is used to set properties related to printing. The OK, Apply, Reset, and Cancel buttons operate in the same way as those of the CSD window settings dialog. The "Units" combo box changes the displayed units for items in this dialog.


 

Common Print Settings Page

These settings apply to both CSD and UML printing.

Standard Paper Sizes - choosing an item from this pulldown list will set the paper width and height.

Paper Width / Height - these are ignored for native Windows CSD printing, and can be set in the Windows print dialog (if allowed) in that case.

Horizontal / Vertical DPI - the horizontal and vertical resolution of the target device or printer. If this is not known, choose a high density (the default is 300x300dpi). If the resolution set here does not match the resolution of the target device or printer, the alignment of the printout may be off very slightly for all types of printing. The error can be 1 pixel per character, which at high resolutions is not noticeable. For Java printing, the resolution is also used to build the CSD characters, so the CSD may look chunky or asymmetrical if the resolutions are not correct.


 
 

CSD/Messages Print Settings Page

Color - if on, printing will be in color.

Page Numbers - if on, the page number is printed on each page.

Filename Header - if on, the filename is printed at the top of each page.

Break Pages on Form Feed - if on, form feed characters (hex code 0C) will cause page breaks in the printing. If off, these characters will be printed in the text font.

Landscape - if on, printing will be in landscape mode. This is ignored for native Windows printing, and can be set in the Windows print dialog in that case.

Book Format - if on, left and right margins will alternate. This is useful if the printouts will be bound.

Left Page First - if on and book format is on, the first page printed will have reversed margins.

Left / Right / Top / Bottom Margin - page margins.

Gutter - spacing between columns if more than one column is used.

Line Spacing - the CSD will stretch when line spacing is increased. At an aspect ratio of 3 or above, the CSD will loose its symmetrical appearance.

Columns - allows multiple columns of text per page.

Font Size - the size of the printed font.

Header - text for a header: to be printed at the top of each page.

Font - the printed font. Note that Courier is always used for PostScript printing (Print To File (PostScript)  and  Native Print (UNIX/Linux)) regardless of this setting.


 
 

UML Print Settings Page

Margin - the same margin is used on all four sides.

Multi-page Overlap - for multiple-page printouts, the pages must be overlapped by this amount to align them properly. This makes it easier to assemble multiple-page printouts.

Landscape - if on, printing will be in landscape mode.

Maximum printed width, height - if the printed image exceeds this size, the user will have the option to scale to this size.

Horizontal and vertical image alignment - alignment within the printed page or pages.


 
 

Command Print Settings Page (Unix / Linux only)

Allows the printing command to be changed.