Chapter 63. The SonarQube Runner Plugin

Table of Contents

63.1. SonarQube Runner version and compatibility
63.2. Getting started
63.3. Configuring the SonarQube Runner
63.4. Specifying the SonarQube Runner version
63.5. Analyzing Multi-Project Builds
63.6. Analyzing Custom Source Sets
63.7. Analyzing languages other than Java
63.8. More on configuring SonarQube properties
63.9. Setting SonarQube Properties from the Command Line
63.10. Controlling the SonarQube Runner process
63.11. Tasks

This plugin has been deprecated and superseded by the official plugin from SonarQube. This plugin will be removed in Gradle 3.0.

The SonarQube Runner plugin provides integration with SonarQube, a web-based platform for monitoring code quality. It is based on the SonarQube Runner API, a SonarQube library that starts source code analysis, and optionally publish all collected information to the SonarQube server. Compared to using the standalone SonarQube Runner CLI, the Gradle SonarQube Runner plugin offers the following benefits:

Automatic provisioning of SonarQube Runner

The ability to execute the SonarQube Runner via a regular Gradle task makes it available anywhere Gradle is available (developer build, CI server, etc.), without the need to manually download, setup, and maintain a SonarQube Runner installation.

Dynamic configuration from Gradle build scripts

All of Gradle's scripting features can be leveraged to configure SonarQube Runner as needed.

Extensive configuration defaults

Gradle already has much of the information needed for SonarQube to successfully analyze a project. By preconfiguring the SonarQube Runner properties based on that information, the need for manual configuration is reduced significantly.

63.1. SonarQube Runner version and compatibility

The default version of the SonarQube Runner used by the plugin is 2.3, which makes it compatible with SonarQube 3.0 and higher. For compatibility with SonarQube versions earlier than 3.0, you can configure the use of an earlier SonarQube Runner version (see Section 63.4, “Specifying the SonarQube Runner version”).

63.2. Getting started

To get started, apply the SonarQube Runner plugin to the project to be analyzed.

Example 63.1. Applying the SonarQube Runner plugin

build.gradle

apply plugin: "sonar-runner"

Assuming a local SonarQube server with out-of-the-box settings is up and running, no further mandatory configuration is required. Execute gradle sonarRunner and wait until the build has completed, then open the web page indicated at the bottom of the SonarQube Runner output. You should now be able to browse the analysis results.

Before executing the sonarRunner task, all tasks producing output to be analysed by SonarQube need to be executed. Typically, these are compile tasks, test tasks, and code coverage tasks. To meet these needs, the plugins adds a task dependency from sonarRunner on test if the java plugin is applied. Further task dependencies can be added as needed.

63.3. Configuring the SonarQube Runner

The SonarQube Runner plugin adds a SonarRunnerRootExtension extension to the project and a SonarRunnerExtension extension to its subprojects, which allows you to configure the SonarQube Runner via key/value pairs known as SonarQube properties. A typical base line configuration includes connection settings for the SonarQube server and database.

Example 63.2. Configuring SonarQube connection settings

build.gradle

sonarRunner {
    sonarProperties {
        property "sonar.host.url", "http://my.server.com"
        property "sonar.jdbc.url", "jdbc:mysql://my.server.com/sonar"
        property "sonar.jdbc.driverClassName", "com.mysql.jdbc.Driver"
        property "sonar.jdbc.username", "Fred Flintstone"
        property "sonar.jdbc.password", "very clever"
    }
}

Alternatively, SonarQube properties can be set from the command line. See Section 62.6, “Configuring Sonar Settings from the Command Line” for more information.

For a complete list of standard SonarQube properties, consult the SonarQube documentation. If you happen to use additional SonarQube plugins, consult their documentation.

In addition to set SonarQube properties, the SonarRunnerRootExtension extension allows the configuration of the SonarQube Runner version and the JavaForkOptions of the forked SonarQube Runner process.

The SonarQube Runner plugin leverages information contained in Gradle's object model to provide smart defaults for many of the standard SonarQube properties. The defaults are summarized in the tables below. Notice that additional defaults are provided for projects that have the java-base or java plugin applied. For some properties (notably server and database connection settings), determining a suitable default is left to the SonarQube Runner.

Table 63.1. Gradle defaults for standard SonarQube properties

Property Gradle default
sonar.projectKey “$project.group:$project.name” (for root project of analysed hierarchy; left to SonarQube Runner otherwise)
sonar.projectName project.name
sonar.projectDescription project.description
sonar.projectVersion project.version
sonar.projectBaseDir project.projectDir
sonar.working.directory “$project.buildDir/sonar”
sonar.dynamicAnalysis “reuseReports”

Table 63.2. Additional defaults when java-base plugin is applied

Property Gradle default
sonar.java.source project.sourceCompatibility
sonar.java.target project.targetCompatibility

Table 63.3. Additional defaults when java plugin is applied

Property Gradle default
sonar.sources sourceSets.main.allSource.srcDirs (filtered to only include existing directories)
sonar.tests sourceSets.test.allSource.srcDirs (filtered to only include existing directories)
sonar.binaries sourceSets.main.runtimeClasspath (filtered to only include directories)
sonar.libraries sourceSets.main.runtimeClasspath (filtering to only include files; rt.jar added if necessary)
sonar.surefire.reportsPath test.testResultsDir (if the directory exists)
sonar.junit.reportsPath test.testResultsDir (if the directory exists)

Table 63.4. Additional defaults when jacoco plugin is applied

Property Gradle default
sonar.jacoco.reportPath jacoco.destinationFile

63.4. Specifying the SonarQube Runner version

By default, version 2.3 of the SonarQube Runner is used. To specify an alternative version, set the SonarRunnerRootExtension.getToolVersion() property of the sonarRunner extension of the project the plugin was applied to to the desired version. This will result in the SonarQube Runner dependency org.codehaus.sonar.runner:sonar-runner-dist:«toolVersion» being used as the SonarQube Runner.

Example 63.3. Configuring SonarQube runner version

build.gradle

sonarRunner {
    toolVersion = '2.3' // default
}

63.5. Analyzing Multi-Project Builds

The SonarQube Runner is capable of analyzing whole project hierarchies at once. This yields a hierarchical view in the SonarQube web interface, with aggregated metrics and the ability to drill down into subprojects. Analyzing a project hierarchy also takes less time than analyzing each project separately.

To analyze a project hierarchy, apply the SonarQube Runner plugin to the root project of the hierarchy. Typically (but not necessarily) this will be the root project of the Gradle build. Information pertaining to the analysis as a whole, like server and database connections settings, have to be configured in the sonarRunner block of this project. Any SonarQube properties set on the command line also apply to this project.

Example 63.4. Global configuration settings

build.gradle

sonarRunner {
    sonarProperties {
        property "sonar.host.url", "http://my.server.com"
        property "sonar.jdbc.url", "jdbc:mysql://my.server.com/sonar"
        property "sonar.jdbc.driverClassName", "com.mysql.jdbc.Driver"
        property "sonar.jdbc.username", "Fred Flintstone"
        property "sonar.jdbc.password", "very clever"
    }
}

Configuration shared between subprojects can be configured in a subprojects block.

Example 63.5. Shared configuration settings

build.gradle

subprojects {
    sonarRunner {
        sonarProperties {
            property "sonar.sourceEncoding", "UTF-8"
        }
    }
}

Project-specific information is configured in the sonarRunner block of the corresponding project.

Example 63.6. Individual configuration settings

build.gradle

project(":project1") {
    sonarRunner {
        sonarProperties {
            property "sonar.language", "grvy"
        }
    }
}

To skip SonarQube analysis for a particular subproject, set sonarRunner.skipProject to true.

Example 63.7. Skipping analysis of a project

build.gradle

project(":project2") {
    sonarRunner {
        skipProject = true
    }
}

63.6. Analyzing Custom Source Sets

By default, the SonarQube Runner plugin passes on the project's main source set as production sources, and the project's test source set as test sources. This works regardless of the project's source directory layout. Additional source sets can be added as needed.

Example 63.8. Analyzing custom source sets

build.gradle

sonarRunner {
    sonarProperties {
        properties["sonar.sources"] += sourceSets.custom.allSource.srcDirs
        properties["sonar.tests"] += sourceSets.integTest.allSource.srcDirs
    }
}

63.7. Analyzing languages other than Java

As of SonarQube 4.2, multi-language projects are supported and each file language will be detected according to its filename suffix. However, note that your SonarQube server has to have the SonarQube plugin that handles that programming language. If you want to enforce a single language for your project, you'll need to set sonar.project.language accordingly.

Example 63.9. Analyzing languages other than Java

build.gradle

sonarRunner {
    sonarProperties {
        property "sonar.language", "grvy" // set language to Groovy
    }
}

63.8. More on configuring SonarQube properties

Let's take a closer look at the sonarRunner.sonarProperties {} block. As we have already seen in the examples, the property() method allows you to set new properties or override existing ones. Furthermore, all properties that have been configured up to this point, including all properties preconfigured by Gradle, are available via the properties accessor.

Entries in the properties map can be read and written with the usual Groovy syntax. To facilitate their manipulation, values still have their “idiomatic” type (File, List, etc.). After the sonarProperties block has been evaluated, values are converted to Strings as follows: Collection values are (recursively) converted to comma-separated Strings, and all other values are converted by calling their toString() method.

Because the sonarProperties block is evaluated lazily, properties of Gradle's object model can be safely referenced from within the block, without having to fear that they have not yet been set.

63.9. Setting SonarQube Properties from the Command Line

SonarQube Properties can also be set from the command line, by setting a system property named exactly like the Sonar property in question. This can be useful when dealing with sensitive information (e.g. credentials), environment information, or for ad-hoc configuration.

gradle sonarRunner -Dsonar.host.url=http://sonar.mycompany.com -Dsonar.jdbc.password=myPassword -Dsonar.verbose=true

While certainly useful at times, we do recommend to keep the bulk of the configuration in a (versioned) build script, readily available to everyone.

A SonarQube property value set via a system property overrides any value set in a build script (for the same property). When analyzing a project hierarchy, values set via system properties apply to the root project of the analyzed hierarchy. Each system property starting with ""sonar." will taken into account for the sonar runner setup.

63.10. Controlling the SonarQube Runner process

The SonarQube Runner is executed in a forked process. This allows fine grained control over memory settings, system properties etc. just for the SonarQube Runner process. The forkOptions property of the sonarRunner extension of the project that applies the sonar-runner plugin (Usually the rootProject but not necessarily) allows the process configuration to be specified. This property is not available in the SonarRunnerExtension extension applied to the subprojects.

Example 63.10. setting custom SonarQube Runner fork options

build.gradle

sonarRunner {
    forkOptions {
        maxHeapSize = '512m'
    }
}

For a complete reference about the available options, see JavaForkOptions.

63.11. Tasks

The SonarQube Runner plugin adds the following tasks to the project.

Table 63.5. SonarQube Runner plugin - tasks

Task name Depends on Type Description
sonarRunner - SonarRunner Analyzes a project hierarchy with SonarQube.