Skip to content

Commit 38c0fc0

Browse files
ganncampganncamp
authored
DOC init docs file
2 parents 378a826 + 3c183c1 commit 38c0fc0

File tree

1 file changed

+208
-0
lines changed

1 file changed

+208
-0
lines changed

‎sonar-docs/analysis/scan/sonarscanner-for-gradle.md

+208
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
---
2+
title: SonarScanner for Gradle
3+
url: /analysis/scan/sonarscanner-for-gradle/
4+
---
5+
6+
[[info]]
7+
| By [SonarSource](https://www.sonarsource.com/) – GNU LGPL 3 – [Issue Tracker](https://jira.sonarsource.com/browse/SONARGRADL) – [Source](https://github.com/SonarSource/sonar-scanner-gradle)
8+
| Current version: **SonarQube Scanner for Gradle 2.7.1**
9+
10+
11+
12+
The SonarScanner for Gradle provides an easy way to start SonarQube analysis of a Gradle project.
13+
14+
The ability to execute the SonarQube analysis 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. The Gradle build already has much of the information needed for SonarQube to successfully analyze a project. By preconfiguring the analysis based on that information, the need for manual configuration is reduced significantly.
15+
16+
## Prerequisites
17+
* Gradle versions 2.14+
18+
* At least the minimal version of Java supported by your SonarQube server is in use
19+
20+
Bytecode created by javac compilation is required for Java analysis, including Android projects.
21+
22+
## Configure the Scanner
23+
Installation is automatic, but certain global properties should still be configured. A good place to configure global properties is `~/.gradle/gradle.properties`. Be aware that the scanner uses system properties so all properties should be prefixed by `systemProp`.
24+
25+
```
26+
# gradle.properties
27+
systemProp.sonar.host.url=http://localhost:9000
28+
29+
#----- Token generated from an account with 'publish analysis' permission
30+
systemProp.sonar.login=<token>
31+
```
32+
33+
## Analyzing
34+
First, activate the scanner in your build. For Gradle 2.1+, in `build.gradle`:
35+
```
36+
plugins {
37+
id "org.sonarqube" version "2.7"
38+
}
39+
```
40+
More details on https://plugins.gradle.org/plugin/org.sonarqube
41+
42+
Assuming a local SonarQube server with out-of-the-box settings is up and running, no further configuration is required.
43+
44+
Execute `gradle sonarqube` and wait until the build has completed, then open the web page indicated at the bottom of the console output. You should now be able to browse the analysis results.
45+
46+
## Analyzing Multi-Project Builds
47+
To analyze a project hierarchy, apply the SonarQube 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 has to be configured in the sonarqube block of this project. Any properties set on the command line also apply to this project.
48+
49+
```
50+
// build.gradle
51+
sonarqube {
52+
properties {
53+
property "sonar.sourceEncoding", "UTF-8"
54+
}
55+
}
56+
```
57+
58+
Configuration shared between subprojects can be configured in a subprojects block.
59+
```
60+
// build.gradle
61+
subprojects {
62+
sonarqube {
63+
properties {
64+
property "sonar.sources", "src"
65+
}
66+
}
67+
}
68+
```
69+
70+
Project-specific information is configured in the `sonarqube` block of the corresponding project.
71+
```
72+
// build.gradle
73+
project(":project1") {
74+
sonarqube {
75+
properties {
76+
property "sonar.branch", "Foo"
77+
}
78+
}}
79+
```
80+
81+
To skip SonarQube analysis for a particular subproject, set sonarqube.skipProject to true.
82+
```
83+
// build.gradle
84+
project(":project2") {
85+
sonarqube {
86+
skipProject = true
87+
}
88+
}
89+
```
90+
91+
## Task dependencies
92+
All tasks that produce output that should be included in the SonarQube analysis need to be executed before the `sonarqube` task runs. Typically, these are compile tasks, test tasks, and code coverage tasks. To meet these needs, the plugins adds a task dependency from `sonarqube` on `test` if the Java plugin is applied. Further task dependencies can be added as needed. For example:
93+
```
94+
// build.gradle
95+
project.tasks["sonarqube"].dependsOn "anotherTask"
96+
```
97+
98+
## Sample project
99+
100+
A simple working example is available at this URL so you can check everything is correctly configured in your env:
101+
https://github.com/SonarSource/sonar-scanning-examples/tree/master/sonarqube-scanner-gradle
102+
103+
104+
## Analysis property defaults
105+
The SonarScanner for Gradle uses information contained in Gradle's object model to provide smart defaults for most of the standard [analysis parameters](/analysis/analysis-parameters/), as listed below.
106+
107+
Gradle defaults for standard SonarQube properties:
108+
109+
Property|Gradle default
110+
---|---
111+
`sonar.projectKey`|`[${project.group}:]${project.name}` for root module; `<root module key>:<module path>` for submodules
112+
`sonar.projectName`|`${project.name}`
113+
`sonar.projectDescription`|`${project.description}`
114+
`sonar.projectVersion`|`${project.version}`
115+
`sonar.projectBaseDir`|`${project.projectDir}`
116+
`sonar.working.directory`|`${project.buildDir}/sonar`
117+
118+
Notice that additional defaults are provided for projects that have the java-base or java plugin applied:
119+
120+
Property|Gradle default
121+
---|---
122+
`sonar.sourceEncoding`|`${project.compileJava.options.encoding}`
123+
`sonar.java.source`|`${project.sourceCompatibility}`
124+
`sonar.java.target`|`${project.targetCompatibility}`
125+
`sonar.sources`|`${sourceSets.main.allSource.srcDirs}` (filtered to only include existing directories)
126+
`sonar.tests`|`${sourceSets.test.allSource.srcDirs}` (filtered to only include existing directories)
127+
`sonar.java.binaries`|`${sourceSets.main.output.classesDir}`
128+
`sonar.java.libraries`|`${sourceSets.main.compileClasspath}` (filtering to only include files; rt.jar and jfxrt.jar added if necessary)
129+
`sonar.java.test.binaries`|`${sourceSets.test.output.classeDir}`
130+
`sonar.java.test.libraries`|`${sourceSets.test.compileClasspath}` (filtering to only include files; rt.jar and jfxrt.jar added if necessary)
131+
`sonar.junit.reportPaths`|`${test.testResultsDir}` (if the directory exists)
132+
133+
Groovy projects get all the Java defaults, plus:
134+
135+
Property|Gradle default
136+
---|---
137+
`sonar.groovy.binaries`|`${sourceSets.main.output.classesDir}`
138+
139+
140+
Additional defaults when JaCoCo plugin is applied
141+
142+
Property|Gradle default
143+
---|---
144+
`sonar.jacoco.reportPaths`|`${jacoco.destinationFile}`
145+
`sonar.groovy.jacoco.reportPath`|`${jacoco.destinationFile}`
146+
147+
Additional defaults for Android projects (`com.android.application`, `com.android.library`, or `com.android.test`)
148+
By default the first variant of type "debug" will be used to configure the analysis. You can override the name of the variant to be used using the parameter 'androidVariant':
149+
150+
```
151+
build.gradle
152+
sonarqube {
153+
androidVariant 'fullDebug'
154+
}
155+
```
156+
157+
Property| Gradle default
158+
---|---
159+
`sonar.sources` (for non test variants)|`${variant.sourcesets.map}` (ManifestFile/CDirectories/AidlDirectories/AssetsDirectories/CppDirectories/JavaDirectories/RenderscriptDirectories/ResDirectories/ResourcesDirectories)
160+
`sonar.tests` (for test variants)|`${variant.sourcesets.map}` (ManifestFile/CDirectories/AidlDirectories/AssetsDirectories/CppDirectories/JavaDirectories/RenderscriptDirectories/ResDirectories/ResourcesDirectories)
161+
`sonar.java[.test].binaries`|`${variant.destinationDir}`
162+
`sonar.java[.test].libraries`|`${variant.javaCompile.classpath} + ${bootclasspath}`
163+
`sonar.java.source`|`${variant.javaCompile.sourceCompatibility}`
164+
`sonar.java.target`|`${variant.javaCompile.targetCompatibility}`
165+
166+
167+
## Passing manual properties / overriding defaults
168+
The SonarScanner for Gradle adds a SonarQubeExtension extension to project and its subprojects, which allows you to configure/override the analysis properties.
169+
```
170+
// in build.gradle
171+
sonarqube {
172+
properties {
173+
property "sonar.exclusions", "**/*Generated.java"
174+
}
175+
}
176+
```
177+
SonarQube properties can also be set from the command line, or by setting a system property named exactly like the SonarQube property in question. This can be useful when dealing with sensitive information (e.g. credentials), environment information, or for ad-hoc configuration.
178+
179+
```
180+
gradle sonarqube -Dsonar.host.url=http://sonar.mycompany.com -Dsonar.verbose=true
181+
```
182+
183+
While certainly useful at times, we recommend keeping the bulk of the configuration in a (versioned) build script, readily available to everyone.
184+
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 be taken into account.
185+
186+
187+
188+
### Analyzing Custom Source Sets
189+
By default, the SonarScanner for Gradle 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.
190+
191+
```
192+
// build.gradle
193+
sonarqube {
194+
properties {
195+
properties["sonar.sources"] += sourceSets.custom.allSource.srcDirs
196+
properties["sonar.tests"] += sourceSets.integTest.allSource.srcDirs
197+
}
198+
}
199+
```
200+
201+
## Advanced topics
202+
### More on configuring SonarQube properties
203+
Let's take a closer look at the `sonarqube.properties` `{}` 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.
204+
205+
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()` methods.
206+
207+
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.
208+

0 commit comments

Comments
 (0)