Appendix B. Analysis
In this appendix, we’ll show you how to run a SonarQube analysis via three different methods: SonarQube Runner, Maven, and Ant. Each of the first three sections stands alone, so feel free to skip to the one that interests you the most. For SonarQube Runner analysis, continue to section B.1. For Maven, skip to B.2, and for Ant you want B.3. If you’re not sure which one to use, then you probably want SonarQube Runner.
Note
In each analysis section, we’ll show you configurations that use localhost in URLs that refer to the SonarQube server or database. If you’re not running your analyses on the SonarQube server itself, you’ll need to replace every instance of localhost with your SonarQube server’s hostname.
When you’re done with the analysis section of interest, be sure to check section B.4 for a full listing of properties you can use to modify the execution of any type of analysis.
B.1. Analyzing with SonarQube Runner
SonarQube Runner is a Java application you fire from the command line. You feed it your project and a simple set of properties, and with those two things it can run the analysis for any language SonarQube handles (Java, C, C++, C#, ABAP, COBOL and so on).
Before you can analyze with the SonarQube Runner, you need to download it: http://docs.codehaus.org/x/N4KxDQ. The best place to go for the download is the SonarQube wiki, which lists all the available versions, newest first. Pretty much without exception, the newest will be the one you want.
You also need to make sure you have Java installed—because the SonarQube Runner was written in Java, you need to have Java on your machine to run it.
With Java on board, you’re ready to install SonarQube Runner. Continue to section B.1.1 if you’re on Windows, and skip to section B.1.2 if you’re using Ubuntu.
B.1.1. Install: Windows 7
Once you’ve downloaded the SonarQube Runner zip file, expand it into the location of your choice. When you do so, by default the name of the directory that’s created contains the version number. Leaving the version number in that directory name is a good idea because it will make things clearer at upgrade time.
Now create an environment variable called SONAR_RUNNER_HOME that points to your sonar-runner-<version> directory. You also need to make sure you have a JAVA_HOME environment variable that points to your Java directory. If Java was preinstalled for you, you may have a Java directory under Program Files. This isn’t the directory you want to point your JAVA_HOME variable at. Open C:Program FilesJava, and find the subdirectory named something like jre6. The full path to that subdirectory is what should be in JAVA_HOME.
After you set up SONAR_RUNNER_HOME and JAVA_HOME, add the following to the end of your PATH environment variable, and restart:
;%SONAR_RUNNER_HOME%in;%JAVA_HOME%in
When your machine is back up, head to section B.1.3 for instructions on verifying and configuring your installation.
B.1.2. Install: Ubuntu
Installing SonarQube Runner is short and sweet for Linux. Run the following commands to expand the zip file and sym-link it into the default path:
Once you’re done, continue to the next section to verify and configure your installation.
B.1.3. Verify and configure : Ubuntu and Windows 7
Now that SonarQube Runner is installed—whatever your platform—the instructions for using it are the same for everyone. First you need to verify your installation, so head to a command line and type:
sonar-runner -h
If you get a usage message in response, then you’re good to go.
You could choose to use SonarQube Runner as is, but you’ll save yourself some effort down the road if you configure a few of the more common properties globally rather than on a project-by-project basis. Every analysis, no matter how it’s performed, needs to know where its target database is and what the credentials are to access that database. So you should configure those properties centrally.
To set these central properties, go to the SonarQube Runner home directory, and open conf/sonar-runner.properties in your favorite text editor. Uncomment (remove the leading # character) from the sonar.host.url line as well as the lines with the correct database driver and URL for your SonarQube install, and the database username and password. Be sure to correct the hostname in all the uncommented .url properties if you’re not setting up SonarQube Runner on the machine that hosts SonarQube. Also correct the database password—assuming you didn’t use the default. (You didn’t, did you?)
B.1.4. Analyze
With SonarQube Runner installed and configured, you’re ready to run your first analysis. In the target project’s root directory, create a file named sonar.properties and open it in your favorite text editor. The following listing shows a sample properties file. Adjust it to match your project. Note that the libraries property is a comma-delimited list of explicit library files or the wildcard paths to them, as shown in the listing.
Listing B.1. SonarQube Runner project properties file
Once your properties file is configured, you can use it as is, like this:
cd <project root directory> sonar-runner -Dproject.settings=sonar.properties
In response, you’ll get about 80 lines (or more) of output. Here’s a condensed version:
Runner configuration file: /usr/share/sonarRunner/conf/sonar-
runner.properties
Project configuration file: <path to project root>/sonar.properties
Runner version: 1.2
Java version: 1.6.0_31, vendor: Sun Microsystems Inc.
OS name: "Linux", version: "3.0.0-19-generic", arch: "i386"
Server: http://<your server>:9000
Work directory: <path to project root>/.sonar
18:32:31.238 INFO o.s.c.p.Database - Create JDBC datasource
18:32:31.869 INFO actDatabaseConnector - Initializing Hibernate
18:32:33.740 INFO .s.b.b.ProjectModule - ------------- Analyzing <Project
Name>
...
18:32:41.453 INFO p.PhasesTimeProfiler - Sensor CoberturaSensor done: 0 ms
18:32:42.207 INFO p.PhasesTimeProfiler - Execute decorators...
18:32:43.793 INFO .b.p.UpdateStatusJob - ANALYSIS SUCCESSFUL,
you can browse http://localhost:9000
18:32:43.794 INFO b.p.PostJobsExecutor - Executing post-job class
org.sonar.plugins.core.batch.IndexProjectPostJob
18:32:43.901 INFO b.p.PostJobsExecutor - Executing post-job class
org.sonar.plugins.dbcleaner.ProjectPurgePostJob
...
Total time: 14.082s
Final Memory: 8M/112M
When you see the ANALYSIS SUCCESSFUL line, the runner isn’t quite finished—there are still database cleanup routines to go through—but your metrics will be ready, and you can head over to your SonarQube host to see them.
B.1.5. Multi-module projects
If you’re dealing with a multi-module project, you need to set up the properties for each module. Fortunately, module properties follow an inheritance model, so you can set the common ones (or the most common ones) at the parent level and override what you need to at the module level.
You have two choices of how to set up your module properties. You can put everything in a parent-level sonar-project.properties file, or you can combine a parent-level properties file (it’s needed either way) with a properties file per module.
Again, a parent-level sonar-project.properties file is needed either way. At a minimum, it will contain the following:
- sonar.projectKey=com.myCompany:multiModuleProject
- sonar.projectName=Multi Module Project
- sonar.projectVersion=1.0
- sonar.modules=moduleA,moduleB
The sonar.modules property holds a comma-delimited list of module names or aliases. If your module’s name doesn’t match its directory, you also need to specify its directory, like so: moduleB.sonar.projectBaseDir=path/to/moduleB.
Notice how the base directory property is prefixed with moduleB. All module-specific properties specified in the parent properties file should begin with the project name/alias you specified in the modules list. Module properties specified in a separate, child-level file don’t need the prefix. Make sure you set a property for the projectName of each module; after that, it’s just a matter of adding any module-specific properties you need to override from the parent level.
Figure B.1. Editing settings.xml with NetBeans and Eclipse IDE
B.2. Analyzing with Maven
If your favorite build tool is Maven, you’re in luck, because SonarQube has supported Maven analysis from the start. In fact, for quite a while you could only perform a SonarQube analysis with Maven, and even today the Maven analysis functionality is richer than that offered by the other methods.
To perform your own Maven-based analysis, we’ll start by assuming that you already have Maven installed and configured and that Maven’s bin directory is in your system path variable. You can verify that it is by typing mvn at a command prompt. You should see something like this in response:
[INFO] Scanning for projects... [INFO] ------------------------------------------------------------------ [ERROR] BUILD FAILURE [INFO] ------------------------------------------------------------------
The beauty of Maven is that you don’t need to explicitly download any additional libraries. Setting up Maven was the biggest step in the process. Let’s look at how to configure an analysis.
B.2.1. Setup
First you need to set up a SonarQube profile specifying how to connect to SonarQube’s database. To do that, edit Maven’s global configuration file, settings.xml, which is located in $MAVEN_HOME/conf or in your home folder under a .m2 subdirectory. You can open it in your favorite text editor; or sometimes your IDE will show it with your project files, as shown in figure B.1, and you can edit it from there.
The next listing shows a sample SonarQube profile using MySQL. (For details on installing and configuring SonarQube to use MySQL, see appendix A.)
Listing B.2. Maven settings.xml configuration
Now that you’ve configured the SonarQube profile, you need to add a sonar-mavenplugin dependency to your project’s pom.xml file. You can skip this step if you want, but it’s a good idea to add this dependency because SonarQube provides two Maven plugins: one for Maven 2 and another for Maven 3. Adding the sonar-maven-plugin section to pom.xml ensures that the correct one is always used. If you don’t know which version of Maven you’re using, type this at a command line: mvn -v or mvn -version. You’ll get something like this:
The good folks at SonarSource make setting up the plugin dependency as easy as possible by providing the exact XML to use, and we’ve replicated it here for your convenience in listings B.3 through B.5. If you’re on Maven 2, then add the code in listing B.3 to your pom.xml. If you’re on Maven 3, then use what’s in listing B.4.
Listing B.3. Maven 2 plug-in specification for project pom.xml
<build>
<pluginManagement>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>sonar-maven-plugin</artifactId>
<version>1.0</version>
</plugin>
</pluginManagement>
</build>
Listing B.4. Maven 3 plug-in specification for project pom.xml
<build>
<pluginManagement>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>sonar-maven-plugin</artifactId>
<version>2.0</version>
</plugin>
</pluginManagement>
</build>
If you need to be able to build your project with either Maven version, then you must create two profiles in pom.xml and let Maven decide which one to use. Listing B.5 shows you how. The tricky part is in the activation tag, which relies on the existence (or not) of the ${basedir} expression. Maven 3 recognizes ${basedir} but Maven 2 doesn’t, and you set the sonarVersion attribute accordingly.
Listing B.5. Analyzing a project with either Maven version
<build>
<pluginManagement>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>sonar-maven-plugin</artifactId>
<version>${sonarVersion}</version>
</plugin>
</pluginManagement>
</build>
<profile>
<id>m2-profile</id>
<activation>
<file>
<missing>${basedir}</missing>
</file>
</activation>
<properties>
<sonarVersion>1.0</sonarVersion>
</properties>
</profile>
<profile>
<id>m3-profile</id>
<activation>
<file>
<exists>${basedir}</exists>
</file>
</activation>
<properties>
<sonarVersion>2.0</sonarVersion>
</properties>
</profile>
B.2.2. First analysis
You’re ready to run your first SonarQube analysis using Maven. At a command prompt, cd to the directory holding your pom.xml file. You could skip straight to the analysis, but it’s recommended that you run the Maven install goal first, like so:
mvn clean install
Once that’s complete, run the analysis:
mvn sonar:sonar
Alternately, you can run both goals in a single command:
mvn clean install sonar:sonar -Dmaven.test.failure.ignore=true
We need to mention a couple of points here:
- The parameter -Dmaven.test.failure.ignore should always be used to instruct SonarQube to continue with analysis even if one or more tests fail.
- By default, your unit tests are executed twice: once for the install goal and once for the sonar goal. It’s possible to skip the second run and reuse the test results from the first run. For details, see sonar.dynamicAnalysis and its companion properties in section B.4.
- Avoid using the Maven parameters -Dtest=false and -DskipTests=true. They’ll prevent SonarQube from running your unit tests, and you won’t get any test metrics.
B.2.3. Multi-module
If you have a multi-module project, you can easily analyze it using the steps just outlined. Each child module automatically inherits its parent properties. If there are properties you want overridden at the child level, such as sonar.language, define them in the child module’s pom.
B.3. Analyzing with Ant
If you’re in an Ant-build shop, you’ll be happy to know that the good folks at SonarSource have ported analysis functionality into an Ant task. Before you can use it, you’ll need to download the Ant task jar from http://docs.codehaus.org/x/QYKxDQ. The best place to go for the download is the SonarQube wiki, where the latest links and documentation are maintained.
Put the Ant task jar somewhere central. You can make it readily available to everyone by dropping it into the lib directory in the Ant installation (${ant.library .dir}), or put it in your user home in a directory named .ant/lib.
Once that’s done, you’re ready to go, and listing B.6 gives you a sample target. Notice that it refers to the Ant task jar as sonar-ant-task.jar, rather than sonar-ant-task-<version>.jar. That’s because we typically cheat by either renaming the jar to remove the version number or adding a version-less symlink to the directory. If it’s not your practice to do either, then you need to correct the name of the jar.
Listing B.6. Ant script
There are a couple of things to note about this listing. The first is that it’s not a full project file. We’re assuming you’ve already got one into which you need to incorporate analysis. Second, we’ve made the sonar target dependent on an (unprovided) compile target.
Of course, you’re free to remove that dependency (also remove the sonar.binaries property); but you’ll probably want to leave it in because the more you give SonarQube, the fuller the analysis it returns, and the compiled binaries can be an important part of a full analysis.
And of course, the elephant in the room for true Ant-heads is that the whole thing isn’t very Ant-y. At all. That’s probably because SonarSource is a Maven shop, and Ant-based analysis isn’t its primary focus.
That’s why you must give the properties the names shown in the example if you want the analysis to run correctly. That’s also why this example turns what you might expect to see as a path reference into a comma-delimited string that lists paths to jars.
Telling SonarQube where your dependencies are can enhance the quality of the analysis you get, but unfortunately you can’t just pass the SonarQube Ant task a resource collection, or even a stereotypical **/*.jar path. Instead it needs a comma-delimited list of jars. Assembling that list is what this chunk of code early in the target does:
<path id="tmpPath">
<fileset dir="lib" includes="**/*.jar"/>
<fileset dir="${ant.library.dir}" includes="*.jar"/>
</path>
<pathconvert dirsep="/" pathsep="," property="sonar.libraries"
refid="tmpPath"/>
Like binaries, libraries are optional, so feel free to leave this part out.
If you’re doing a multi-module build and want to make it a multi-module analysis as well, you need a few more (specifically named) properties. The first is
<property name="sonar.modules" value="moduleA,moduleB"/>
The sonar.modules property holds a comma-delimited list of module names or aliases. If your module’s name doesn’t match its directory, you also need to specify its directory, like so:
<property name="moduleB.sonar.projectBaseDir" value="path/to/moduleB"/>
Notice how the base directory property is prefixed with moduleB. All module-specific properties should begin with the project name/alias you specified in the modules list. Make sure you set a property for the projectName of each module, and after that, it’s just a matter of adding any module-specific properties you need to vary from what you’ve already set for the analysis as a whole.
B.4. Analysis properties
SonarQube provides a variety of advanced properties to customize analysis. Some of them can be set permanently on a project through the SonarQube interface, but others are available only as analysis parameters. They allow you to adjust individual analysis runs to meet the needs of the moment. The tables in this section list the available properties and discuss how they affect an analysis.
Table B.1 lists required analysis properties. Some must be explicitly stated for all analysis types; others, marked “Required for non-Maven analysis,” are inherited from elsewhere in the project settings for Maven analyses but must be explicitly stated for other analysis types.
Table B.1. Required analysis properties
| Property | Example | Details |
| sonar.projectKey | com.myDomain:projectId Format should be a:b | What’s shown here is a stereotypical Maven project ID. There’s no requirement that your project use Maven to be analyzable, but you still need to give it an ID in the Maven format of something :somethingElse. Don’t worry that it’s ugly. It’s not shown in many places. For an Ant analysis, this requirement is fulfilled by the key argument to the analysis task. |
| sonar.projectName | My Project | This value is what’s usually shown to users. It may contain spaces. |
| sonar.projectVersion | 1.0 | As this value changes, SonarQube records events, which are used to flag project snapshots, for long-term retention and comparison. |
| sonar.sources | srcDir1,srcDir2 | Required for non-Maven projects. This is a comma-delimited list of paths from project root to the directories holding source files. Directories are scanned recursively, so there’s no need to list subdirectories. If the source files are in the project root, set this value to a single period (.) |
| sonar.jdbc. driverClassName | One of the following: com.mysql.jdbc.Driveroracle. jdbc.OracleDriver, org.postgresql.Driver, net.sourceforge.jtds.jdbc.Driver | During an analysis, SonarQube must know how to reach its database. This property tells it which database driver class to use to make a connection. |
| sonar.jdbc.url | jdbc:mysql://localhost:3306/ sonar?useUnicode=true &characterEncoding=utf8& rewriteBatchedStatements=true | This property tells the local SonarQube analysis engine where its database is. It’s used in conjunction with the sonar.jdbc.driverClassName property and the two credentials properties. |
| sonar.jdbc.username | sonar | This is the name of the SonarQube database user you created during setup and installation in appendix A. |
| sonar.jdbc.password | <password you picked> | This is the password you assigned to the SonarQube database user you created during setup and installation in appendix A. |
| sonar.login sonar.password | Credentials of a user with permissions to SonarQube and/or User role on the project | These properties are required only if one of the following two conditions is true: -- Your SonarQube instance is secured and requires a user to log in for basic access. -- The Anyone group doesn’t have the User role on the project under analysis. |
None of the properties in table B.2 are required, but their use will help you get the most out of a SonarQube analysis, because the more data you give SonarQube, the richer the analysis you’ll get back. As with some of the properties in table B.1, some of these properties are available implicitly for a Maven analysis.
Table B.2. Analysis enrichment properties
|
Property |
Example |
Details |
|---|---|---|
| sonar.tests | testDir1,testDir2 | This is a comma-delimited list of paths from project root to the directories holding test files. Implicit for Maven analysis. |
| sonar.binaries | binDir | This is a comma-delimited list of paths from project root to the compiled byte code. Implicit for Maven analysis. |
| sonar.libraries | lib/lib1.jar,lib/*.jar | This is a comma-delimited list of paths to individual library files or directories. For a SonarQube Runner analysis, you can make this a comma-delimited list of paths to lib directories and end each entry with *.jar or whatever the appropriate extension is for your language. For an Ant analysis, this needs to be a comma-delimited list of paths to exact libraries. Listing B.6 in the Ant analysis section of this appendix gives you a way to do that. Implicit for Maven analysis. |
| sonar.dynamicAnalysis | One of true, false, reuseReports | Unit tests are executed by default, but you can choose to turn that off or to reuse previously generated reports. If you choose reuseReports, you need to use one of the companion properties to specify the report type and location. |
| sonar.jacoco.reportPath sonar.surefire.reportsPath sonar.coberatura.reportPath sonar.clover.reportPath | path/to/reports | This is the absolute or relative path to the chosen reports. |
Table B.3 lists properties you can use to tune various aspects of your analysis, such as which language is being analyzed and whether byte-code analysis is performed. It also lists a number of properties you can use to override values set at the server, such as which rule profile to use.
Table B.3. Analysis tuning and overrides
|
Property |
Example |
Details |
|---|---|---|
| sonar.language | One of abap, c, cobol, delph, cs (C#), flex, grvy, java, js, natur, php, plsql, py, vb, web, xml | This specifies the single non-Java language under analysis. Many properties may be set to comma-delimited lists, but this property may not be. It only accepts a single value. |
| sonar.importSources | true / false | This defaults to true, which means by default, SonarQube imports your source files into its database for display in the interface as a reference and for clearer illustration of the issues it finds. There are some controls you can place around who can view project sources in SonarQube, but if it’s ultra-sensitive, set this property to false to prevent the source files from being imported. |
| sonar.projectDate | yyyy-MM-dd | This defaults to now. If you’d like SonarQube to catch up the history on a project, use this property to tell SonarQube what date you checked out from your SCM. |
| sonar.branch | [your SCM branch name] | If you have multiple SCM branches of a project under analysis, use this property to differentiate them from Head and each other. |
| sonar.sourceEncoding | UTF-8 | This is the character set your source files are saved in. UTF-8 is the default and is typically correct for most projects. |
| sonar.exclusions | com/myCo/genned/*.java, com/**/*Dummy.java | This is a comma-delimited list of paths to files or directories that should be ignored during analysis. No metrics—including
the basics like size—will be calculated on anything listed here.
Wildcards in file or path names will be expanded. The examples at left will exclude the following:
|
| sonar.skippedModules | names,ofModules,toSkip | If your Maven project is composed of multiple modules and you want some of them skipped during analysis, list their IDs here in comma-delimited format. Does not apply to non-Maven projects. |
| sonar.includedModules | names,ofModules,toInclude | If your Maven project is composed of multiple modules and you want only some of them analyzed, list their IDs here in comma-delimited format. Does not apply to non-Maven projects. |
| sonar.profile | Sonar way with Findbugs | Set this property to the name of the profile you want your project analyzed with. This property overrides the profile that’s set at the server. For long-term use, it is preferable to assign a project to the chosen profile via SonarQube’s configuration interface. Note that using this property may cause confusion—because the dashboard description widget displays the name of the profile the project is assigned to (via the configuration interface) rather than the one it was last analyzed with (via this analysis property). |
| sonar.skipDesign | true / false | SonarQube implements byte-code analysis to determine dependencies and other design metrics. Set this property to true if for some reason you need to skip that analysis. |
| sonar.phase | [Maven phase name] | Use this property to have a Maven goal or phase executed before analysis starts. When SonarQube needs a phase or Maven goal to be executed prior to analysis, this parameter can be used. For example, sonar.phase=generate-sources. |
| sonar.java.source sonar.java.target | One of 1.5, 1.6, 1.7 | These properties align the source and target parameters to the Java compiler. If you’re using those parameters, set these properties correspondingly. |
| sonar.findbugs .excludesFilters | relative/path/to/file | SonarQube lets you exclude certain classes or packages from analysis, but FindBugs, one of the tools SonarQube can use for Java analysis, provides a much more fine-grained ability to set up exclusions for specific bugs or bug types against classes or packages. See: http://findbugs.sourceforge.net/manual/filter.html. Those FindBugs filters are defined in an XML file. If this property is defined, SonarQube passes in its value when the FindBugs portion of an analysis is invoked—assuming the rule profile in force includes FindBugs rules. |
The properties in table B.4 shouldn’t usually be needed, but they’re useful if you’re trying to debug an analysis problem.
Table B.4. Troubleshooting and debugging
|
Property |
Example |
Details |
|---|---|---|
| sonar.host.connectTimeoutMs sonar.host.readTimeoutMs | 100000 | Measured in milliseconds, these timeouts apply to Maven-based analyses, which make some HTTP requests to the server. Because two timeouts will make the call fail, you may want to increase these values if your server is slow and you’re having trouble. Defaults: connectTimeoutMs = 30000 readTimeoutMs = 60000 |
| sonar.verbose | true / false | Defaults to false. Set this to true to see a lot more detail in your analysis logs. |
| sonar.showSql | true / false | Defaults to true. Set this to true to see all SQL queries executed by SonarQube during batch analysis. Useful for debugging purposes and when you’re developing custom plug-ins. |
| sonar.showSqlResults | true / false | Defaults to true. Set this to true to see the results of SQL queries executed by SonarQube during batch analysis. Useful for debugging purposes and when you’re developing custom plug-ins. |