Sonargraph-Build 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 Sonargraph-Build and specifies an XML file for the detailed configuration as first program argument.
NOTE
Sonargraph-Build 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.
TIP
All parameters can also be set as program arguments and will override the values set in the XML configuration file. Example (for details of classpath configuration, see example batch files in the installation):
java -cp <classpath> com.hello2morrow.sonargraph.build.client.SonargraphBuildRunner ./startup.xml snapshotDirectory=../System.sonargraph
NOTE
The attribute "logLevel" affects the logging after the Sonargraph-Build 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 "elementCountToSplitHtmlReport". 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 "maxElementCountForHtmlDetailsPage".
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.
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 Sonargraph-Build | 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 |
|
waitForLicense |
No | If license is ticket based, this parameter specifies the number of minutes that will be waited for a license to become available if all license tickets are currently in use. Waiting period between tries is 60 seconds. Possible values are: -1 (infinitely), 0 (do not wait), positive number > 0 | -1 |
| licenseServerUrl | No | URL of license server to be used. Must start with 'http:' or 'https:'. | |
| 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 Sonargraph-Build. If no value is specified, all languages will be initialized. | Java, CSharp, CPlusPlus |
| logFile | No | Path of the log file to be used for Sonargraph-Build. | ${currentDir}/sonargraph_build.log |
| logLevel | No | Level of logging detail. One of: off, error, warn, info, debug, trace, all | info |
| progressInfo | No | Level of progress info, either "none", "basic" or "detailed". "detailed" expects that the output console supports backspace characters. | none |
| analyzerExecutionLevel | No | Controls which analyzers will run after the parser has finished. Consider lower levels if your build takes too much time. Allowed values are FULL, ADVANCED, BASIC and MINIMAL. | FULL |
| 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) |
| numberOfDaemons | No |
The number of C/C++ parser daemon processes - minimum is 1, maximum is 16. |
8 |
| daemonStackSize | No |
Stack size for C/C++ parser daemons in MB. |
1 |
| requiredInstallationProfiles | No | Comma separated list of C# installation profiles (e.g. 'net-5.0') that will be created by Sonargraph before the actual build. The names are the id's of the profiles as shown in the c# preferences dialog. | |
| 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 |
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 |
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 |
| contextInfo | No | Allows specifying some additional info that helps to identify later the context of the report creation. | Current timestamp |
| baselineReportPath | No | Path of the baseline XML report that the current report is compared against. If specified, the system diff report is generated into the reportDirectory and has the filename <reportFileName>_diff. If no reportFileName is specified, the diff report's filename is <system-name>_diff_<timestamp>. | No default |
| 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 |
| pythonInterpreterPath | No |
The path to a valid Python 3 interpreter to be used for the build. NOTE: If the standalone Sonargraph application is used on the same machine with the same user and this parameter is empty, the Python interpreter specified with the standalone application will be used. |
PATH is searched for a valid Python 3 interpreter. If none can be found in this parameter is not set the build will fail. |
| uploadHostUrl | No | The host and port of the Sonargraph-Enterprise server (upcoming product). If this parameter is defined Sonargraph-Build will upload the report to this server. If the upload fails for some reason the report will be copied to a configurable directory (see parameter 'failedUploadDirectory') that collects all failed uploads. This directory is used by another task named 'resendFailedUploads' that should be invoked on a regular base. It is assumed that the server is internal, so as of now proxy settings are ignored. Must start with "http://". | No default |
| createAndUploadSnapshot | No | If the parameter 'uploadHostUrl' is set, Sonargraph will also create a snapshot of your system and upload it to Sonargraph-Enterprise. Set this parameter to 'false' if you don't want to create and upload snapshots. | true |
| clientKey | Only if 'uploadHostUrl' is set | The client key for the Sonargraph-Enterprise server. Uploading reports only works with the right client key, which can be found on the settings page of Sonargaph-Enterprise. The settings page is only visible in administrator mode. | No default |
| failedUploadDirectory | No | If the upload to the server configured in the parameter 'uploadHostUrl' fails for some reason the report that failed to upload is copied to this directory for later pickup by the task 'resendFailedUploads'. If you have a distributed build that directory should ideally point to a shared network storage drive. | System specific in user home directory |
| branch | No | If reports are uploaded to the Sonargraph-Enterprise server (upcoming product, see parameter 'uploadHostUrl') it is useful to associate the report with the version control system branch name to avoid mixing data of different branches. If the branch name is not given we assume 'default'. If you are only uploading data of the same branch you do not need to pass the branch name, otherwise it is highly recommended. | default |
| version | No | This parameter is only used in conjunction with 'uploadHostUrl' and should be used if the uploaded report should be associated with a specific software version. If you are using git flow, you would want to use this parameter for every commit of the master branch, since each commit is associated with a software release. | No default |
| commitId | No | This parameter is only used in conjunction with 'uploadHostUrl' and should be used if the uploaded report should be associated with a specific version control commit id. | No default |
| timestamp | No | This parameter allows to specify the timestamp in ISO-8601 extended offset date-time format, e.g. '2011-12-03T10:15:30+01:00'. | Current timestamp |
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>
Sonargraph-Build can mark the build as failed based on detected issues.
Sonargraph-Build 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
Support for quality gates has been introduced with Sonargraph version 10.3, making it easier to define conditions for breaking the build: Simply define the quality gates in Sonargraph, activate them and define a failSet for the issue type "QualityGateIssue". For more details on quality gates, check the user manual of Sonargraph Architect.
Please note, that a commercial license is required for the quality gate feature.
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 known issues in Sonargraph and only filter for resolution value "none".
TIP
The include/exclude definitions are applied in the following sequence, regardless of their definition order:
-
First all include definitions are matched against the set of existing issues.
-
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 |
| failSet | failOnIssues | No | Marks the build as failed if issues exist. 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 |
Example
This is an example failSet definition:
<sonargraphBuild
...
<failSet failOnEmptyWorkspace="false">
<include issueType="QualityGateIssue" />
<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.
If the upload of reports to Sonargraph-Enterprise failed, they are stored in the directory specified by the parameter "failedUploadDirectory". The upload can be retried calling the same executable as for creating the report and specifying additionally the argument "resendFailedUploads":
java -cp <classpath> com.hello2morrow.sonargraph.build.client.SonargraphBuildRunner
./startup.xml resendFailedUploads
The following table lists all parameters that are available to reattempt the upload of previously failed reports:
| Attribute | Mandatory | Description | Default |
|---|---|---|---|
| installationDirectory | Yes | Installation directory of Sonargraph-Build | 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 |
|
waitForLicense |
No | If license is ticket based, this parameter specifies the number of minutes that will be waited for a license to become available if all license tickets are currently in use. Waiting period between tries is 60 seconds. Possible values are: -1 (infinitely), 0 (do not wait), positive number > 0 | -1 |
| licenseServerUrl | No | URL of license server to be used. Must start with 'http:' or 'https:'. | |
| licenseFile | No | Sonargraph license file location. If this parameter is not specified, you must specify the activation code parameter (see above). | No default |
| logFile | No | Path of the log file to be used for Sonargraph-Build. | ${currentDir}/sonargraph_build.log |
| logLevel | No | Level of logging detail. One of: off, error, warn, info, debug, trace, all | info |
| progressInfo | No | Level of progress info, either "none", "basic" or "detailed". "detailed" expects that the output console supports backspace characters. | none |
| 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 |
| uploadHostUrl | No | The host and port of the Sonargraph-Enterprise server (upcoming product). If this parameter is defined Sonargraph-Build will upload the report to this server. If the upload fails for some reason the report will be copied to a configurable directory (see parameter 'failedUploadDirectory') that collects all failed uploads. This directory is used by another task named 'resendFailedUploads' that should be invoked on a regular base. It is assumed that the server is internal, so as of now proxy settings are ignored. Must start with "http://". | No default |
| clientKey | Only if 'uploadHostUrl' is set | The client key for the Sonargraph-Enterprise server. Uploading reports only works with the right client key, which can be found on the settings page of Sonargaph-Enterprise. The settings page is only visible in administrator mode. | No default |
| failedUploadDirectory | No | If the upload to the server configured in the parameter 'uploadHostUrl' fails for some reason the report that failed to upload is copied to this directory for later pickup by the task 'resendFailedUploads'. If you have a distributed build that directory should ideally point to a shared network storage drive. | System specific in user home directory |
