Using Structure101 Build with SonarQube

When using Structure101 Build with SonarQube the detection of new structural issues can be delegated to SonarQube. This simplifies the configuration of Structure101 Build but requires an appropriate SonarQube Quality Gate to be defined. [Build 14507 and later of the Structure101 SonarQube plugin]

Overview

Installing and Configuring the SonarQube Plugin

The Structure101 SonarQube plugin jar file should be copied into the extensions/plugins folder of the SonarQube installation. Any previous version of the Structure101 plugin should be removed and the SonarQube instance restarted.

Create a new Quality Profile with language Java

Change the parent to your existing Java quality profile

Click Activate More to add the Structure101 rules

Filter the rules using Java language and Structure101 repository

Activate each of the rules setting the desired severity

Configuring the Quality Gate

On the SonarQube Quality Gates tab click Create and enter a suitable name in the dialog

Click Add Condition and select On Overall Code then select the relevant metric from the drop down list.

Set the value and click the Add Condition button.

Configuring the Build

It is assumed that SonarQube is already setup for your project

Structure101 Build must run the report-key-measures operation before the SonarQube scanner executes

The SonarQube scanner must have the system property structure101.reportdir set so that the Structure101 SonarQube plugin can find the output file of the report-key-measures operation

NOTES

Your Studio project file containing Structure Spec, Architecture Diagrams and Action Lists should be committed to source control so that it is available to your CI process

When multiple branches are published with the same Structure101 Repository Project name then the report-key-measures operation must be configured to use the local Structure Spec and Architecture Diagrams. (ie those contained in the .hsp file)
This ensures the checks are against the correct spec and diagrams for the branch being built. (The latest repository snapshot cannot be used because it may be for a different branch)

Set these properties – useProjectFileSpec=true and useProjectFileDiagrams=true

(Using the local project diagrams is good practice anyway as it removes the need to manually publish updated diagrams or Action Lists. The hsp file can be updated in Structure101 Studio and committed to source control. The next CI build will then publish the updates to the Repository)

Maven Example

This is an example pom.xml configuration to execute the report-key-measures goal

<plugin>
  <groupId>com.structure101.java</groupId>
  <artifactId>maven-structure101-plugin</artifactId>
  <version>14507</version>
  <configuration>
    <project>maven</project>
    <localProject>structure101-settings.java.hsp</localProject>
    <repository>http://ubuntu-server:8989/s101j/data</repository>
  </configuration>
  <executions>
    <execution>
      <id>s101checkKeyMeasures</id>
      <phase>compile</phase>
      <goals>
        <goal>report-key-measures</goal>
      </goals>
      <configuration>
        <report-key-measures-output-file>target/s101-results/key-measures.xml</report-key-measures-output-file>
        <use-project-file-spec>true</use-project-file-spec>
        <use-project-file-diagrams>true</use-project-file-diagrams>
      </configuration>
    </execution>

The report-key-measures-output-file path must be passed to the SonarQube scanner in the system property structure101.reportdir

For example, mvn sonar:sonar -Dstructure101.reportdir=target/structure101-reports/key-measures.xml

Or  in the Jenkins build step as shown below

If you are using a pipeline script or similar mechanism to call the sonarscanner shell script then the structure101.reportdir property must be passed in using the SONAR_SCANNER_OPTS property. The example below can be used in a Jenkins pipeline script.

env.SONAR_SCANNER_OPTS=”-Dstructure101.reportdir=${WORKSPACE}/target/structure101-reports/key-measures.xml”

Structure101 Build Configuration Example

The build configuration file shown below runs the report-key-measures and publish operations. Note the label argument contains the value “LABEL_TOKEN”. This will need to be replaced with an appropriate value when Structure101 Build is run.

This can be achieved with an execute shell command step

The label is passed to the Structure101 Build command using -Ds101.label. (In this example, a concatenation of the system variables GIT_BRANCH and BUILD_ID separated by an underscore)

java -Ds101.label="${GIT_BRANSH}_$BUILD_ID" -jar /opt/structure101-build-java-all-5.0.14435/structure101-java-build.jar structure101-build-config.xml -licenseDir=/opt/structure101-build-license

(NOTE that any of the arguments can be provided at runtime with -Ds101.<argument name>)

Example build configuration file

<?xml version="1.0" encoding="UTF-8"?>
<headless>
    <operations>

        <!-- report key measures -->
        <operation type="report-key-measures">
            <argument name="output-file" value="const(THIS_FILE)/target/structure101-reports/key-measures.xml"/>
            <argument name="useProjectFileSpec" value="true"/>
            <argument name="useProjectFileDiagrams" value="true"/>            
        </operation>

        <!-- publish snapshot and diagrams -->
        <operation type="publish">
            <argument name="label" value="LABEL_TOKEN"/>
            <argument name="diagrams" value="true"/>
            <argument name="spec" value="true"/>
            <argument name="actions" value="true"/>
        </operation>

    <arguments>
        <argument name="local-project" value="const(THIS_FILE)/structure101-settings.java.hsp">
        </argument>
        <argument name="repository" value="http://ubuntu-server:8989/s101j/data"/>
        <argument name="project" value="Maven"/>
    </arguments>
</headless>