Imagix 4D User Guide


Step 3 - Adjust the Project Settings (C/C++)

As the source code analysis starts, an Analysis Results window appears in Imagix 4D's main panel. As the source code analysis occurs, you can use this window to monitor the process and get a sense of how cleanly the source code is being analyzed. If you see that a lot of errors and warnings are being generated, it's probably best to use the Halt button to stop the analysis so that you don't waste time before beginning this refinement your project settings.

When the analysis completes, either naturally or through the Halt button, you can use the window to review and resolve any analysis issues that have been identified.

3a. Resolve any missing header files

The Analysis Results window offers a number of different displays, through the Display menu and its equivalent icon bar buttons. One of these (Display > Show Unlocated Files) focuses on analyzer messages about missing header files.

These messages take the form `cannot open file', and indicate the file where the #include preprocessor directive exists and its format. Resolving any missing header files is normally the appropriate starting point for adjusting your project settings, because the failure to find the headers and analyze any symbol declarations / definitions they contain can cause significant impacts in analyzing any downstream source code that relies on those declarations.

Detailed instructions for resolving these missing files are included in this User Guide.

3b. Resolve macro definitions

If the analyzer is finding the include files, but a lot of error messages such as `unknown type foo near symbol bar' are appearing in the display (Display > Show Significant Warnings), the problem is likely to be incompletely or inaccurately specified macro definitions.

The most typical errors occur because required types are unknown, as their typedefs occurred in sections of header files that were passed over because of how macro definitions control conditional compilation. This is a result of how the -D and -U flags were specified for the project, or what #defines are specified in the compiler configuration file.

Detailed instructions for resolving these macro definitions are included in this User Guide.

3c. Investigate and resolve errors in order

The Imagix 4D analyzer will produce error messages that you might not get with lexical parsers. This is because the Imagix 4D analyzer does full semantic parsing, like a compiler, in order to extract more complete and accurate data from your source files. However, unlike a compiler, the Imagix 4D analyzer has built-in error correction. After encountering a parsing problem, Imagix 4D resynchronizes to your source code, and reports which lines had to be skipped while it was resynchronizing. So as you review analysis results to determine whether the parsing issues were significant, take into consideration how many lines were ignored.

Also take into account the order that the error messages occur. Upstream errors can cause symbols, especially types, to be undefined and result in downstream errors. Resolving the upstream errors, which are listed earlier in the display, can result in many downstream errors being eliminated.

A useful approach for this is to select one of the initial errors related to a specific file by clicking on it, and then examining details about the error in the (Display > Investigate Errors) display. The display collates information about multiple aspects of the source code line where the error occurs. This includes a section labeled Adjacent Symbols which lists all of the locations known to the database where definitions exist for the symbol tokens appearing near where the error occurs. If the appropriate definitions for a given symbol are not listed, it is likely that some upstream issue is causing the current error.

For the first several errors for a given file, a section labeled Error Detail is generated, containing source analyzer-generated information to provide insight into the error. The Previous Tokens entry lists the symbols seen by the analyzer after resolving all macros and omitting all disabled lines. Of particular interest are any "IDENTIFIER" tokens appearing in a place where a type name or class name should be. This indicates that the type or class definition was not found. Typically, this results from missing header files.

The Parser Stack provides detail about the context of the analysis. If the Parser Stack shows a sequence of definitions (e.g. "external_definition_list") but the error line is actually a statement, then the overall nesting is not longer accurate. This typically happens because of upstream errors causing closing curly braces to be skipped.

The Identifiers entry list provides more detail of what the analysis found out about the last 5 identifiers, type names, or class names. If "undef" appears where a defined name should be, then either header files are missing, or those definitions have been skipped due to incorrect macro definitions or upstream errors.

3d. Correct any problem with filename specification

If you used the adding a makefile target approach, the Analyzer Results window starts off echoing the commands generated by make. If the window doesn't include any `Analyzing foo.c' style comments, then a problem occurred. The most common problem is that no source files were specified. Check your definition of IMAGIX_SOURCES in the makefile (using your own editor).

3e. Specify the entire set of source files

If you are purposely only analyzing a subset of your files while you adjust the preprocessor flags, and if you have adjusted the -I, -D and -U flags so that you're getting just a few error messages, change the file definitions to reflect all the files you want to analyze. For the makefile approach, redefine IMAGIX_SOURCES in the makefile itself. For the dialog-based approach, bring up the original Data Sources dialog (Project > Data Sources) and specify the change in the Files field on the Source Files tab.

3f. Repeat this process as appropriate

Until you're satisfied with the analysis results, continue to modify the compiler configuration file, the makefile, and/or the Data Sources dialog as appropriate, then reanalyze the code. For compiler configuration file or makefile changes, use Project > Regenerate Project Data. Then return to step 3a, and repeat this process.