SofCheck Inspector™ Console Help
Version 2.1
As of November 2007
Copyright © 2006—2007 SofCheck, Inc. All rights reserved.
The
use and distribution of this material is subject to licensing terms.
Table of Contents
- About SofCheck Inspector Console
- Launching the SofCheck Inspector Console
- Console Project Menu
- Console Run Menu
- Console Help Menu
- Appendix
About SofCheck Inspector Console
This document describes how to use the SofCheck Inspector Console. The Console is an interactive tool that allows the user to create (and save) Inspector project files, interactively launch the SofCheck Inspector, and browse the output of the inspection. For more information about SofCheck Inspector or how to run SofCheck Inspector in batch mode from the command line, see the separate SofCheck Inspector User Guide.
Launching the SofCheck Inspector Console |
Launch the Console by selecting the Start > Programs > SofCheck Inspector > Inspector Console menu item. Alternately, you may execute the RUNCONSOLE.BAT file from the command line. The Inspector Console main window will appear.
The Project drop-down menu lets you create, open, edit and save Inspector project files. The Run drop-down menu lets you launch SofCheck Inspector, monitor its execution, and view its output. The Help drop-down menu lets you view this document and other helpful information.
The Console text area displays diagnostic output from the SofCheck Inspector. The other output of the inspection is written to the file system in the form of HTML files, text files, and the Inspector Database.
Console Project Menu |
New Projects |
Select Project > New… (or press Ctrl+N) to create a new Inspector project. You will be asked to select the Project Type:
If you select Ada Project, you will see the following Project Description dialog:
If you select Java Project or Ada and Java Project, you will see the following Project Description dialog:
Enter a Project Name for your Inspector project. The Project Name should conform to an acceptable directory name to be saved to the native file system. Click on the Create button to the right of the edit box, and the project name will be used to complete the Project Information fields; at this time, the Project Directory and error.txt log file are also created. For example, type "MyInspection1" in the Project Name edit box and click the Create button. The Project Information fields will be completed as in the following dialog:
You may accept the default names for the project files and directories listed in Project Information or select the Customize Project check box to change them. For each entry you may type new values into the edit boxes or click on the Browse buttons to select existing files. For example, you may wish to have multiple projects use the same database, or you may have an alternate message pattern file which you wish to use.
· The Project Directory is the root directory of an Inspector project. By default, the directory is created in the shared documents workspace on the file system (derived from the environment variable %SOFCHECK_PROJECTS%) when you click the Create button. (When you click the Save button, a project file with the name projectname.prj is also created in the Project Directory.)
· The Output Directory is the directory where Inspector generates its output. It is created when an inspection is run for the first time.
· The Database Directory is the directory where Inspector stores a history of inspection messages for a particular project (or set of projects) so it may compare the current inspection to a previous one, and also show trends across multiple inspections. The Database Directory and its contents are created when an inspection is run for the first time.
· The Message Pattern File is used to characterize and filter the inspection messages. The Inspector comes with a default message pattern file.
Selecting Files to Inspect
For an Ada Project, click the Source Files Select… button to select one or more source files to be inspected. You will be able to browse a source tree and select source directories or source files. It is important that the files chosen are in a compilable state.
The Inspector analysis engine processes JVM “.class” files,
which, for
For a Java project, click the Source Files Select… button to select one or more source files that correspond to the class files being inspected. You will be able to browse a source tree and select source directories, source files, and archives. For Java, it is the class files that determine the scope of the inspection. As such, selecting source files is optional, but is recommended so that the Inspector can display inspection messages in-line with the source for better context.
The following is an example of a Java Project Source Files selection dialog:
Inspector is able to match source files to their associated class files properly. If you select source files that do not correspond to selected class files, corresponding entries will be listed in the “Source Directories that lack class files” pane. Inspector cannot analyze source files without corresponding class files. Similarly, if you select class files without selecting their associated source files, corresponding entries will be listed in the "Class directories that lack sources" pane. In this example, the appropriate class files haven’t been selected yet, which is why there are mismatched sources/classes.
Click on the Show Project Issues button to display a text list of file-selection issues (such as duplicate .java files).
Click the Done button to return to the Project Description dialog.
From the Project Description dialog, click the Class Files Select… button to select one or more class files to be inspected. You will be able to browse a source tree and select class files and archives (including .zip, .jar, .ear and .war files). You must select at least one class file for an inspection to succeed.
The following is an example of a Java Project Class Files selection dialog. In this example, corresponding source files have already been selected.
In the source tree, if a class file lacks debug information, that file and its parent directory are highlighted in yellow. If an archive contains a nested archive, that archive and its parent directory are highlighted in red. Inspector does not analyze nested archives; if any are found, they should be extracted to the file system before running Inspector.
As mentioned above, if you select source files that do not correspond to selected class files, corresponding entries will be listed in the “Source Directories that lack class files” pane. Similarly, if you select class files without selecting their associated source files, corresponding entries will be listed in the "Class directories that lack sources" pane.
Click on the Show Project Issues button to display a text list of file-selection issues (such as duplicate .java files).
Click the Done button to return to the Project Description dialog.
The Project Description dialog will indicate that source and class files have been selected, by changing the status message from “Not Selected” to “Selected,” as shown below.
Click on the Options button to modify the project’s run time parameters. The following dialog will appear:
Find out more about Inspector run time parameters in the “Command Line Options” section of the SofCheck Inspector User Guide. Brief explanations are given below.
· cutoff inspection id: type the inspection id of a previous inspection to use as a cutoff. The selected inspection will be used as the base inspection for this run.
· global (do not partition): By default, the Inspector automatically partitions the system into groups of files (if necessary), to perform the analysis without exceeding the limits of main memory; it then integrates the output from all partitions. Check the “global” checkbox to cause the Inspector to analyze the entire system in the same single partition. This may allow more error-checking to be performed and more errors to be detected, but may also cause the limits of main memory to be exceeded and the analysis of some of the larger files in the system to be skipped.
· allow-duplicates: check this to allow Inspector to continue running if it finds more than one source file that could be associated with a single class file. When duplicate source files are found, one will be arbitrarily chosen.
· additional command options: you may type in a free-form, space-delimited list any additional command line options which should be passed to Inspector. See the SofCheck Inspector User Guide for a complete list.
· identify race conditions: By default, the Inspector identifies potential race conditions in your system; uncheck this box to bypass race-condition analysis.
· singleton task entry points: type in space-delimited patterns in the form “<class>:<method>” that match entry points for singleton, or daemon, threads. Inspector recognizes some common defaults, so this edit box may be left blank.
· reentrant entry points: type in space-delimited patterns in the form “<class>:<method>” that match reentrant entry points. Inspector recognizes some common defaults, so this edit box may be left blank.
In the Project Options dialog, click on the Cancel button to return to the Project Description dialog without preserving any changes. Click on the OK button to preserve changes and return to the Project Description dialog
Saving a Project.
In the Project Description dialog, click the Save button to preserve all changes made in the dialog.
For an Ada Project, if the Validate Mode check box is checked, the Console will invoke the
SofCheck Ada Front End to generate class files for
the
If there are any errors during this build process, the messages are logged in the error.txt file. You can view the errors by selecting Show Project Issues… from the Run menu or by pressing Ctrl +I.
For a Java Project, if the Validate Mode check box is checked, the Console will examine and validate the class file and source file selections when the project is saved. It will check that class files are compiled with debug information, that class files have corresponding source files, that source files have corresponding class files, and that nested archives (e.g. jars within jars) are not present. Check the validity of the file selections at least once after they are changed, before inspection.
You may be warned that the validation process will take a long time with the following dialog box.
If you see the above dialog, click Yes to proceed with validation and save the selected classes and source files; you will return to the Console main window. Click No to save the class and source selections but return to the Console main window without validating them. Click Cancel to return to the Project Description dialog and continue to make changes. If you click Yes, the Console log will show the summary of the validation, and the details are saved in error.txt. If you have not already specified a name for the Console project file (with a .prj suffix by default), the Console will prompt you to enter one (See Project > Save As...), below.
In the above example, some problems were found with the class file selections and an error.txt file was generated.
Existing Projects |
Select Project > Open... (or press Ctrl+O) to open a project file that has been previously saved. You will be prompted to browse for a file on the file system. By default, Inspector project files end in the suffix .prj. When a project file is opened, the Project Description dialog will appear.
Select Project > Edit... (or press Ctrl+E) to edit the current project file. The Project Description dialog will appear.
Select Project > Save As… (or press Ctrl+A) to save the project you are currently editing. You will be prompted to type a save filename.
When you are satisfied with the location and name of the project file, click the Save button to save it.
Select Project > Quit (or press Alt+F4) to exit the Inspector Console. If you quit the Console while an inspection is running, the inspection will be terminated.
Console Run Menu |
Select Run > Inspect Project … to start the inspection as defined in the currently open project. First, the Estimated Run Time dialog will show an estimated count of lines and classes and give a rough estimate of the expected run time for the inspection. The actual run time may vary by an order of magnitude from the estimate due to variations in code complexity and server hardware, but changes in the estimate from inspection to inspection on the same hardware should give a more reliable indication of relative time. Note that if the class files have not been compiled with debug information, the Console will not be able to estimate a run time. When you run an inspection for the first time, the Output Directory and the Database Directory are created.
Select Run > Regenerate Reports … to regenerate text and html reports for an existing Inspector analysis. This is useful if you have modified the Message Pattern file, or if you specify a new “cutoff inspection id” against which to compare the current inspection results. It does NOT perform a new analysis of the code.
In the Estimated Run Time dialog, click the Run Now button to begin the inspection or the Cancel button to return to the Console run menu.
When you click on the Run Now button to start the inspection, progress messages will be shown on the Console text area, as shown below.
Select Run > Clear Console (or press Ctrl+C) to clear any text in the Console text area.
Select Run > Browse Output (or press Ctrl+B) to launch a dialog that will open the “./html/index.html” file in this project's output directory, which enables you to easily browse all output from the run of this project. This option will only work if output has already been generated to the output directory specified in the project information settings. If an inspection is still running, you will see a warning dialog box.
Click OK to dismiss the dialog; any running inspection will continue. If an inspection is complete, you will be allowed to select the output index.html file as shown below.
In the Browse Output Folder dialog, click on the OK button to browse the specified index.html file in your system's default browser. Optionally, click the Browse button to select another HTML file. Click the Cancel button to dismiss the dialog without launching the browser.
Select Run > Show Project Issues... (or press Ctrl+I) to open the error.txt file in your default text editor. The error.txt file captures the results of validating a project file after class and source selection, and in particular points out any duplicate or missing files. For an Ada Project, it includes error messages for the Ada Front End.
Console Help Menu |
Select Help and then one of the following Help Menu items for more information.
· SofCheck Inspector Console Help (F1): view this help document.
· SofCheck Inspector User Guide (Alt+U): view the SofCheck Inspector User Guide.
· About SofCheck Inspector Console (Alt+A): view an About dialog box with version information about SofCheck Inspector and the Console.
Appendix |
Troubleshooting |
Q. Will the Console run if I didn't install my LicenseKey.txt file?
A. When the Console runs, it will warn if a valid SofCheck Inspector license key is not installed on this machine.
Press the OK button, and you will be allowed to continue running the Console. Be aware that the features of SofCheck Inspector may be curtailed. Follow the instructions in the dialog box or contact your software reseller to obtain a current license key.
Q. Where can I find an audit log of my Console session?
A. When you create a project, the Console creates the file error.txt in the project directory. The Console writes information to error.txt that might be helpful to SofCheck support. In the Console main window, select Run > Show Project Issues ..., or press Ctrl+I, to open and view the error.txt file.
Q. Why are some of the items highlighted in yellow, in the File Selection window?
A. If a class file lacks debug information, that file and its parent directory are highlighted in yellow. A .jar file containing a class lacking debug information will also be highlighted in yellow. SofCheck Inspector makes extensive use of the debug information in Java .class files, to produce the most readable inspection messages. To generate debugging information, pass the "-g" option to javac.
Q. What does it mean when items are highlighted in red, in the File Selection window?
A. If an archive contains a nested archive, that archive and its parent directory are highlighted in red. SofCheck Inspector does not analyze nested archives; if any are found, they should be extracted to the file system before running Inspector.
Q. Why are there files in the "Class Directories that lack sources" pane of the File Selection window? Do I really need source files?
A. Although SofCheck Inspector can work with .class files alone, it generates more meaningful data when it can cross-reference the .java source files. Use the Console to select both class files and their corresponding source files. The File Selection window will identify folders containing mismatched sources and .class files. Individual mismatched files will be listed in the error.txt file.
|
$Revision: 1.30 $ |