Imagix 4D User Guide


Analyzer Syntax and Options

The Imagix 4D Java analyzer is a stand-alone executable, independent from the Imagix 4D database and user interface. It is located in the ../imagix/bin directory, and uses the following syntax:

imagix-java [option...] file...

where option can be one or more imagix-java options (described below) and file is the full path name for one or more source files. Typically these are just the .java source files of interest. While the file list of analysis targets can also directly include class and jar files, these are normally analyzed as the result of an import classname directive in the source code and/or a -cp classpath option in imagix-java invocation.

The Imagix 4D analyzer supports the following options.

-cmmd Filename   Append the commands from Filename.

The imagix-csrc source analyzer is a command line executable. The -cmmd option adds an indirect way of specifying command line options. Any options specified in Filename are appended to the options specified on the command line itself. If Filename consists of multiple lines, imagix-java behaves as if it were invoked multiple times, each time with the options, if any, from the next individual line in Filename.

-cp Dirname   Add Dirname to the list of class paths to search for class files.
-cp Filename   Add Filename to the list of jar files to search for class files.

When the analyzer encounters an import classname directive in a source file, it searches for the class file classname.class in all directories and jar files specified with the -cp option.

When -cp is followed by a Dirname, that directory serves as the base directory in a class file search. Any package names in the classname are treated as subdirectories of the classpath Dirname. For example, if the classpath Dirname is /some/dir and the import classname is pkgA.pkgB.classC, the analyzer looks for file classC.class in the directory /some/dir/pkgA/pkgB.

When -cp is followed by a Filename, class files in the jar file Filename are analyzed. By default, data about the contents of all class files in the jar file is generated. Through the -impmin option, data is only generated about the class files for which there is an import directive in the source code.

The directory and jar file containers are searched in the order that they appear in the command line through the -cp option.

-genflowDirname   Write control and data flow data to files in directory Dirname.

The analyzer can collect data to generate displays and reports about the control and data flow in the source code analyzed. This flow data is kept in a set of files separate from where the entity / relationship / attribute data is stored. The location of these flow data files is controlled by the -genflow option. In order for Imagix 4D to find this data, the location specified needs to be in a directory named cfd, with the same directory path as the -genvdb data (i.e., parallel to the -genvdb data). If the -genflow option isn't used, no flow data is generated, and flow charts, calculation trees, control flow graphs, and certain reports can not be created.

Option is set automatically when adding data source.

-genqcfDirname   Write quality control data to files in directory Dirname.

The analyzer can run source code checks and collect metrics about symbols in the source files analyzed. This quality control data is kept in a set of files separate from where the entity / relationship / attribute data is stored. The location of these quality control data files is controlled by the -genqcf option. In order for Imagix 4D to find this data, the location specified needs to be in a directory named qcm, with the same directory path as the -genvdb data (i.e., parallel to the -genvdb data). If the -genqcf option isn't used, no quality control data is generated, and certain metrics and reports can not be created.

Option is set automatically when adding data source.

-genvdbDirname   Write analysis results to data files in directory Dirname.

The analyzer generates entity / relationship / attribute data for each of the source files explicitly analyzed, and each of the header files directly or indirectly included by those source files. The possible exception is header files in system include directories (see the -S and -nosys options).

When the -genvdb option is used, the data for each source or header file is stored in a separate file within the directory Dirname. This makes incremental analysis possible, and is the recommended approach. The alternative is to use the -o option.

Option is set automatically when adding data source.

-impcj   Search for imported classes first in class files, then in java files.

When an import class directive occurs in the source code, the analyzer searches for definitions of that class. If the -impcj option is used, the analyzer first looks in class files located through the -cp options. If unable to locate the class definition in a class file, the analyzer then considers any class definitions which occur in the java source files being analyzed.

The -impcj, -impco and -impjc options are mutually exclusive. Option is selected in Import mode combobox on Class Paths tab of Data Source dialog.

-impco   Search for imported classes only in class files.

When an import class directive occurs in the source code, the analyzer searches for definitions of that class. If the -impco option is used, the analyzer looks only in class files. It ignores any definitions of the class which occur in the java source files being analyzed.

The -impcj, -impco and -impjc options are mutually exclusive. Option is selected in Import mode combobox on Class Paths tab of Data Source dialog.

-impjc   Search for imported classes first in java files, then in class files.

When an import class directive occurs in the source code, the analyzer searches for definitions of that class. If the -impjc option is used, the analyzer first considers the java source files being analyzed. If unable to locate the class definition in a .java file, the analyzer then searches for class definitions in class files located through the -cp option.

The -impcj, -impco and -impjc options are mutually exclusive. Option is selected in Import mode combobox on Class Paths tab of Data Source dialog.

-impmin   Do not generate data for non-imported classes in jar file.

Jar files are identified to the analyzer through the -cp option. Normally, data about all of the class files in the jar file is collected by the analyzer. When the -impmin option is used, data is only generated about those class files for which there is an import class directive in a file being analyzed.

-impwopkg   Do not require package name for import directives.

When processing an import directive, the source analyzer tries to find a java or class file with the full import name, including the package portion. When the -impwopkg option is used and the initial search has failed, the source analyzer then ignores the package portion in the java or class file search.

-incFilename   Include Filename at start of analyzing each file.

Using the -inc option is equivalent to adding the directive import Filename at the beginning of each source file you are analyzing. It therefore enables you to change how files are analyzed without modifying the files themselves.

The major use of this option is for including the language configuration files. These configuration files typically contain class path commands for jar files in your environment, enabling the Imagix 4D analyzer to emulate the your Java language environment while analyzing your code.

Filename is selected from files in ../imagix/user/java_cfg by selection in Language combobox on Source Files tab of Data Source dialog.

-java4   Analyze source code using Java 1.4 syntax.

The default behavior of the Imagix 4D Java analyzer is to analyze the source code according to the syntax of the 1.8 version of Java. When this option is applied, the source code analysis is based on the older syntax.

Option can be added in Options field on Source Files tab of Data Source dialog, or specified in a language configuration file.

-locals   Collect data about local variables.

Normally, the Imagix 4D analyzer collects data just about global and static variables, as local variables are set or read only by the function where they're defined, and thus provide little aid in understanding your software. Occasionally you may be interested in collecting data about local variables, for example when you're interested in certain quality metrics such as Class Coupling. Using the -locals option causes data about local variable definitions and usage to be added to the data files.

Option is specified as one of analysis options in Data Collection Options dialog.

-mark   Precede all analyzer messages with "imagix: "

Analyzer error messages normally start with the name of the file where they occur. Using the -mark option causes all error messages to be preceded with the string "imagix: ". This is useful where the analyzer error messages are intermixed with other messages to stderr, such as when running the analyzer in a makefile.

Option can be added in Options field on Source Files tab of Data Source dialog, or specified in a language configuration file.

-sfx   Append a suffix to the files names associated with -genflow and -genqcf data.

Normally, data generated with the -genflow and -genqcf switches is stored in files whose names end with the same suffixes as the corresponding original source and header files. This can cause difficulties in certain configuration management systems. -sfx causes an additional _sfx to be appended to the file name, so that data generated from a .java source file is stored in a file having a .java_sfx suffix.

Option can be added in Options field on Source Files tab of Data Source dialog, or specified in a language configuration file.

-vuid   Generate VUIDs for each symbol being analyzed.

When you generate documentation about your project, you normally build the full document in a single pass. In this case, the symbol identifiers used for the hypertext links are assigned when the database is loaded. Because the document is built in a single session, the identifiers are consistent between the HTML pages.

The -vuid option causes visualizer unique identifiers to be generated at the time the source code is analyzed, rather than when the project is loaded. The resulting consistency of identifiers across project sessions enables partial and incremental generation of the HTML documentation. See the file ../imagix/user/doc_gen/sample.dg_ for more information about partial and incremental documentation generation.

Option can be added in Options field on Source Files tab of Data Source dialog, or specified in a language configuration file.

-warn   Return all analyzer warnings.

When analyzing source code, the Imagix 4D analyzer may encounter syntax or semantic errors, caused by either the source code itself, or by the macro definitions and include paths used to analyze the code.

By default, the analyzer returns error messages for just significant problems, where include files can't be found, or where lines of code need to be skipped to resynchronize the analyzer. Using the -warn option causes the analyzer to return messages for all problems it encounters.

Sometimes it is useful to use the -warn option to isolate initial problems that cause more significant errors later in the analysis.

Option is always enabled through the user interface. Resulting warning messages are either displayed or filtered out of the Analysis Results window according to the display settings (Display > Show Xxxx).