Chapter 4. Executing from the Command-line

SonargraphBuild can be executed as a standalone Java application which enables the integration in any kind of continuous integration environment. The necessary configuration is straight-forward and an example shell script is provided in the directory <inst-dir>/example/bin. The batch script starts SonargraphBuild and specifies an XML file for the detailed configuration.

NOTE

SonargraphBuild returns an exit code indicating the execution status:

  • 0 : Successful execution

  • 1 : Execution failed because of failset properties

  • 2 : Execution failed because of handled exception, e.g. configuration error, license error, etc.

  • 3 : Execution failed because of unexpected exception. Please check the log file for details.

NOTE

The attribute "logLevel" affects the logging after the SonargraphBuild engine has been started. Setting it to "debug" and below will generate additional debug information into the report.

WARNING

Setting the attribute "reportType" to "standard" only generates metric values for "system" and "module" levels. "full" generates values for all element levels, but results in a significant larger report!

The splitting of the HTML report into different files is controlled by the attribute "elementCountToSplit​HtmlReport". The resulting detail pages contain tables of issues / resolutions of a specific issue type. The maximum number of items shown is limited by the parameter "maxElementCountFor​HtmlDetailsPage".

WARNING

The attribute "qualityModelFile" can be used to apply a fixed set of scripts, architecture files and analyzer configurations across several systems.

The reported issues are most likely very different from the results of analyzing the system with the Sonargraph application. If you specify a "qualityModelFile", it is advisable to specify the "Parser" virtual model, since resolutions e.g. for architecture violations probably will not match.

4.1. Report Creation

The following table lists all parameters that are available to create a report for an existing Sonargraph system:

Attribute Mandatory Description Default
installationDirectory Yes Installation directory of SonargraphBuild No default
activationCode No Sonargraph license activation code. If this parameter is not specified, you must specify a license file parameter (see below). No default
licenseServerPort No Port of license server to be used. This parameter is ignored if licenseServerHost is not set. 8080
licenseServerHost No Host name or IP address of license server. If this parameter is not specified, the web-based hello2morrow license server will be used for activation code based licenses. No default
licenseFile No Sonargraph license file location. If this parameter is not specified, you must specify the activation code parameter (see above). No default
languages No The languages that should be initialized, separated by ",". The fewer languages are specified the faster the startup of SonargraphBuild. If no value is specified, all languages will be initialized. Java, CSharp, CPlusPlus
logFile No Path of the log file to be used for SonargraphBuild. ${currentDir}/sonargraph_build.log
logLevel No Level of logging detail. One of: off, error, warn, info, debug, trace, all info
compilerDefinitionPath No

The path to the active compiler definition file to be used for parsing a C/C++ system. If a built-in or automatically generated definition should be used, prefix the definition with "CPlusPlus:", e.g. CPlusPlus:GnuCpp.cdef.

NOTE: If the standalone Sonargraph application is used on the same machine with the same user and this parameter is empty, the active definition specified with the standalone application will be used.

If empty, the default compiler definition for the build server's operating system is used: GnuCpp.cdef (Linux), CLang.cdef (Mac), VisualCpp*.cdef (Windows, generated definition for the latest Visual Studio installation)
systemDirectory Yes Directory of the Sonargraph System (xyz.sonargraph) No default
virtualModel No The virtual model to be used when checking for issues. This parameter overrides the default virtual model that is set when the system is opened. The default virtual model is "Modifiable.vm", if virtual models are licensed, "Parser" if not licensed. Parameter can only be used with Sonargraph Architect license. No default
workspaceProfile No The profile file name (e.g. "BuildProfile.xml") for transforming the workspace paths to match the build environment. No default
qualityModelFile No The path to the quality model file (xyz.sgqm) that should be applied for the report creation. Built-in quality models are the language-independent "Sonargraph:Default.sgqm" and language-specific "Sonargraph:Java.sgqm", "Sonargraph:CSharp.sgqm" and "Sonargraph:CPlusPlus.sgqm". NOTE: All scripts, analyzer configurations and architecture files present in the system are ignored! No default
snapshotDirectory No Target directory for the created snapshot. Only if either this parameter or snapshotFileName is provided, a snapshot will be generated. Parameter can only be used with Sonargraph Architect license. Current directory
snapshotFileName No The target file name (without extension). Only if either this parameter or snapshotDirectory is provided, a snapshot will be generated. Parameter can only be used with Sonargraph Architect license. <system-name>_<timestamp>
reportDirectory No Target directory for the created report Current directory
reportFileName No The target file name (without extension) <system-name>_<timestamp>
reportType No "standard" only creates metric information of system and module level. "full" creates metric information of all levels. standard
reportFormat No "xml", "html" or "xml, html" html

elementCountToSplit
HtmlReport

No Issue and resolution tables might contain too many items making it impossible to open the HTML report in a browser. This parameter controls the lower limit of items that will cause separate files being generated per issue type. Possible values are: -1 (never split), 0 (use default value), 1 (always split), positive number > 1 (threshold for split) 1000

maxElementCountFor
HtmlDetailsPage

No If HTML report is split because of too many issues and/or resolutions, detail tables might contain too many items making it impossible to open the page in a browser. This parameter controls the upper limit of elements shown in the table. Possible values are: -1 (no limit), 0 (use default limit), positive number > 1 (maximum number of elements contained in page) 2000
splitByModule No If set to 'true', individual HTML reports are created per module. false
baselineReportPath No Path of the baseline XML report that the current report is compared against No default
deltaReportPath No Path of the output file that the delta info is written to. This log file is only generated if a baselineReportPath has been specified. <reportDirectory>/<reportFileName>​_delta.log
proxyHost No Proxy host No default
proxyPort No Proxy port No default
proxyUsername No Proxy user name No default
proxyPassword No Proxy password No default
Table 4.1. Configuration for Element "sonargraphBuild"


Example

This is an example configuration for creating an XML and HTML report:

<sonargraphBuild 
    activationCode="_your activation code_"
    languages="Java" 
    installationDirectory="../.."
    systemDirectory="../javaProject/AlarmClock.sonargraph" 
    reportDirectory="./_temp/report"
    reportFileName=""
    reportType="full"
    reportFormat="xml,html"
    snapshotFileName="./_temp/AlarmClock.snapshot" 
    proxyHost="" 
    proxyPort="" 
    proxyUsername=""
    proxyPassword="" 
    logLevel="warn">
</sonargraphBuild>

4.2. Specify Conditions for Build Failure

SonargraphBuild can check for the existence of specific issues and mark the build as failed. The nested "failSet" element of the "sonargraphBuild" element can include any number of "include" and "exclude" definitions based on the issues that are either built-in (like duplicate warnings, cycle group warnings, etc.) or custom issues created via Groovy scripts.

TIP

The issue type that must be specified for include/exclude definitions can be determined via the Properties View of Sonargraph .

TIP

If you want the build to fail only for newly introduced issues, apply resolutions like "Ignore" or "Fix" to the already know issues in Sonargraph and only filter for resolution value "none".

TIP

If you want the build to fail because of certain metric values (e.g. Lines of Code per Source File), define a threshold for that metric in Sonargraph to create issues if files grow too large.

TIP

The include/exclude definitions are applied in the following sequence, regardless of their definition order:

  1. First all include definitions are matched against the set of existing issues.

  2. Then the exclude definitions are applied and the set of previously matched issues is reduced accordingly.

Element Parameter Mandatory Description Default
failSet failOnEmptyWorkspace No Marks the build as failed if modules and root directories are detected but no components are found. Possible values are "true" or "false". true
include/exclude issueType Yes Name of the issue type or "any" for wildcard matching. No default
include/exclude severity No Severity of the issue. Possible values are: error, warning, info, none, any any
include/exclude resolution No The issue's resolution type. Possible values are: task, ignore, any, none none
Table 4.2. Configuration Parameters for Build Failure


Example

This is an example failSet definition:

<sonargraphBuild
...            
  <failSet failOnEmptyWorkspace="false">
    <include issueType="any" severity="error" resolution="none"/> 
    <exclude issueType="ScriptCompilationError"/>
    <include issueType="Supertype uses subtype"/>
    <include issueType="any" severity="warning"/>
    <exclude issueType="ThresholdViolation"/>
  </failSet>
</sonargraphBuild>

The console output provides some basic information about the number of issues matched by either "include" and "exclude":

Failed:
Sonargraph: Start creating report...
Sonargraph: Opening system...
Sonargraph: Refreshing system...
Sonargraph: Creating report...
Sonargraph: Check if build should be marked as failed...
Include filter [issueType=any, severity=error, resolution=none] matches 0 issue(s).
Include filter [issueType=Supertype uses subtype, severity=any, resolution=none] matches 0 issue(s).
Include filter [issueType=any, severity=warning, resolution=none] matches 2 issue(s).
Exclude filter [issueType=ScriptCompilationError, severity=any, resolution=none] removes 0 previously matched issue(s).
Exclude filter [issueType=ThresholdViolation, severity=any, resolution=none] removes 0 previously matched issue(s).
Summary: Build failed as 2 issue(s) match the specified failset on virtual model 'Modifiable.vm'.
Sonargraph: Finished.