Gradle Sonar Runner plug-in

Sonar Runner plug-in

The Sonar runner plug-in is still hatching. I t is important to note that DSL and other configurations may change in future Gradle releases.

The Sonar Runner plug-in provides integration into Sonar, a web-based code quality monitoring platform. I t is based on Sonar Runner, an Sonar client component that analyzes source code and build output and stores all the information collected in the Sonar database. The Sonar Runner plug-in provides the following conveniences compared to using Sonar Runner alone:

Sonar Runner is automatically configured

Sonar Runner can be performed with a formal Gradle task, which makes it available where it is available (developer build, CI server, etc.) without having to download, install, and maintain the installation of Sonar Runner.

Build a script dynamic configuration with Gradle

You can configure Sonar Runner with all the features of the Gradle script as needed.

A wide range of default configurations are available

Gradle already has a lot of information that Sonar Runner needs to successfully analyze a project. Sonar Runner is preconfigured based on this information, reducing the need for many manual configurations.

Plug-in status and compatibility

The Sonar Runner plug-in is the successor to the Sonar plug-in. I t is still in the hatching state. T he plug-in is based on Sonar Runner 2.0, which makes it compatible with Sonar 2.11 or higher. Unlike the Sonar plug-in, the Sonar Runner plug-in also works fine when used with Sonar 3.4 or higher.

Entry

To get started, use the Sonar Runner plug-in for the project configuration you want to analyze.

The configuration uses the Sonar Runner plug-in

build.gradle

apply plugin: "sonar-runner"  

Assuming that a local Sonar service is up and running with out-of-the-box settings, no further mandatory configuration is required. E xecute the gradle sonarRunner and wait for the build to complete, then open the page indicated at the bottom of the Sonar Runner output. You should now be able to see the results of the analysis.

Before the SonarRunner task is performed, all needs that generate output for Sonar analysis need to be executed. T ypically, they are compile tasks, test tasks, and code override tasks. T o meet these needs, if the java plug-in is applied, the Sonar Runner plug-in adds a task dependency to the test from sonarRunner. You can add more task dependencies as needed.

Configure Sonar Runner

The Sonar Runner plug-in adds an SonarRunner extension to the project that allows Sonar Runner to be configured through a key/value pair called the Sonar property. A typical baseline configuration includes connection settings for the Sonar server and database.

Configure the Sonar 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"
    }
}  

For a complete list of standard Sonar properties, see the Sonar documentation. If you happen to be using additional Sonar plug-ins, refer to their documentation.

Alternatively, you can set the Sonar property from the command line. For more information, see Section 35.6, Configure Sonar Settings from the Command Line.

The Sonar Runner plug-in leverages the information contained in Gradle's object model to provide intelligent default values for many standard Sonar properties. T he following table summarizes these default values. N ote that there are additional default values for configurations that use java-base or java plug-ins. For some properties, especially the connection configuration of the server and database, determine the appropriate default value for Sonar Runner.

Table 36.1. The Gradle default value for the standard Sonar property

Property	Gradle default
sonar.projectKey	"$project.group: $project.name" (the root project of the hierarchy analyzed, otherwise left to Sonar Runner)
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 36.2. Configure additional default values added when using the java-base plug-in

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

Table 36.2. Configure additional default values added when using java plug-ins

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

Analyze multi-project builds

The Sonar Runner plug-in analyzes the hierarchy of the entire project at once. I t generates a hierarchical graph on Sonar's web interface that contains comprehensive metrics and drills down into sub-projects. Analyzing the hierarchical results of an item can also take more time than analyzing each project individually.

To analyze the hierarchy of a project, you need to apply the Sonar Runner plug-in to the top-level project of the hierarchy. T ypically, but not necessarily, this Gradle-built root project. T he information related to the analysis, as a whole, such as the connection settings for the server and database, must be configured in the sonarRunner block of this project. Any Sonar properties set on the command line are also applied to this project.

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"
    }
}  

In the subprojects block, you can configure the configuration between shared subprojects.

Shared configuration settings

build.gradle

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

The information for a particular project is configured in the sonarRunner block of the corresponding project.

Individual configuration settings

build.gradle

project
    sonarRunner {
        sonarProperties {
            property "sonar.language", "grvy"
        }
    }
}  

For a particular subproject, to skip Sonar analysis, you can set up sonarRunner.skipProject.

Skip project analysis

build.gradle

project
    sonarRunner {
        skipProject = true
    }
}  

Analyze custom Source Sets

By default, the main source set that the Sonar Runner plug-in passes to the project will be the production source file, and the test source set passed to the project will be the test source file. T his process is independent of the source directory layout of the project. You can add additional source sets as needed.

Analyze custom Source Sets

build.gradle

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

Analyze non-Java languages

To analyze code written in a non-Java language, install the appropriate Sonar plug-in and set sonar.project.language accordingly:

Analyze non-Java languages

build.gradle

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

As of Sonar 3.4, only one language can be analyzed per project. However, in a multi-project build, you can analyze a different language for each project.

More about configuring the properties of Sonar

Let's take a closer look at the sonarRunner.sonarProperties block. A s we've seen in the example, the property() method allows you to set new properties or override existing properties. In addition, all properties that have been configured to this point, including all properties preconfigured through Gradle, can also be used through the properties accessor.

Entries on the properties map can be read and written using the common Groovy syntax. F or their convenience, these values still use their usual types (File, List, etc.). After the SonarProperties block is evaluated, these values are converted to strings, as follows: the values of the collection (recursive) are converted to a comma-separated string, and all other values are converted by calling its tostring() method.

Because the evaluation of sonarProperties blocks is lazy, the properties of Gradle's object model can be safely referenced in blocks without fear that they have not been assigned.

Set the Sonar property from the command line

The Sonar property can also be set from the command line, and by setting a system property, the name is like the Sonar property under consideration. This is useful when working with sensitive information, such as documents, environmental information, or point-to-point configurations.

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

While sometimes of course it's useful, we recommend that in a (version-controlled) build script, it's easy for everyone to keep most of the configuration.

The Sonar property value set by a system property overrides any value set in the build script (the same property name). When you analyze the hierarchy of an item, the values set by the system properties are applied to the root project of the hierarchy being analyzed.

Sonar Runner is executed in a separate process

Depending on the size of the project, Sonar Runner may require a large amount of memory. F or this and other (primarily isolated) reasons, it is best to execute Sonar Runner in a separate process. T his feature will be available once Sonar Runner 2.1 is released and adopted by the Sonar Runner plug-in. At that point, Sonar Runner executes in the Gradle main process.

Task

The Sonar Runner plug-in adds the following tasks to the project.

Table 36.4. S onnar Runner Plug-in - Task

The name of the task	Depends on	Type	Describe
sonarRunner {	-	sonarRunner {	Analyze the project hierarchy and store the results in the Sonar database.